Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
221 lines (165 loc) · 4.83 KB

CONTRIBUTING.md

File metadata and controls

221 lines (165 loc) · 4.83 KB

Contributing to CocoIndex Claude Code

Thank you for your interest in contributing! This document provides guidelines for contributing to the project.

Code of Conduct

Be respectful and inclusive. We welcome contributors of all backgrounds and experience levels.

How to Contribute

Reporting Bugs

  1. Check existing issues - Your bug may already be reported
  2. Create a new issue with:
    • Clear title describing the problem
    • Steps to reproduce
    • Expected vs actual behavior
    • Environment details (OS, Python version, etc.)

Suggesting Features

  1. Open an issue with the enhancement label
  2. Describe:
    • The problem you're trying to solve
    • Your proposed solution
    • Alternative approaches you considered

Submitting Code

Setup Development Environment

# Clone the repository
git clone https://github.com/puneet8800/cocoindex-claude-code.git
cd cocoindex-claude-code

# Create virtual environment
python3.11 -m venv .venv
source .venv/bin/activate

# Install with dev dependencies
pip install -e ".[dev]"

# Start PostgreSQL
docker compose -f docker/compose.yaml up -d

# Setup CocoIndex
cocoindex setup main.py -f

Development Workflow

  1. Create a branch:

    git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

  2. Make your changes:

    • Write clear, documented code
    • Follow the existing code style
    • Add tests if applicable

  3. Test your changes:

    # Run type checking
mypy flows/

# Run linter
ruff check .

# Format code
ruff format .

# Test manually
cocoindex update main.py
python scripts/query.py "test query"

  4. Commit your changes:

    git add .
git commit -m "feat: add new feature"
# or
git commit -m "fix: resolve issue with X"

    Follow Conventional Commits:

    • feat: - New feature
    • fix: - Bug fix
    • docs: - Documentation only
    • refactor: - Code change that neither fixes a bug nor adds a feature
    • test: - Adding tests
    • chore: - Maintenance tasks

  5. Push and create PR:

    git push origin feature/your-feature-name

    Then open a Pull Request on GitHub.

Pull Request Guidelines

  • Title: Clear, descriptive title
  • Description: Explain what and why
  • Link issues: Reference related issues with Fixes #123
  • Small PRs: Keep changes focused and reviewable
  • Tests: Include tests for new functionality
  • Documentation: Update docs if needed

Code Style

Python

  • Python 3.11+ features are welcome
  • Use type hints
  • Follow PEP 8 (enforced by ruff)
  • Maximum line length: 100 characters
# Good
def search(query: str, limit: int = 5) -> QueryOutput:
    """Search indexed documents.

    Args:
        query: The search query
        limit: Maximum results to return

    Returns:
        QueryOutput with matching documents
    """
    ...

# Avoid
def search(q, l=5):
    ...

Documentation

  • Use Markdown for all docs
  • Include code examples
  • Add Mermaid diagrams where helpful
  • Keep language clear and accessible

Project Structure

cocoindex-claude-code/
├── flows/              # CocoIndex flow definitions
│   ├── text_embedding.py
│   └── llm_extraction.py
├── scripts/            # Utility scripts
├── docker/             # Docker configuration
├── docs/               # Documentation
├── main.py             # FastAPI server
├── mcp_server.py       # MCP server
└── pyproject.toml      # Dependencies

Key Files

File Purpose
mcp_server.py MCP protocol implementation
main.py FastAPI REST API
flows/text_embedding.py Vector search flow
flows/llm_extraction.py LLM extraction flow

Testing

Manual Testing

# Test indexing
cocoindex update main.py

# Test search
python scripts/query.py "test query"

# Test MCP server
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | python mcp_server.py

# Test FastAPI
python main.py &
curl http://localhost:8000/search?q=test

Adding Tests

Place tests in a tests/ directory:

# tests/test_search.py
import pytest
from flows.text_embedding import search

def test_search_returns_results():
    result = search("test query")
    assert len(result.results) >= 0

Areas for Contribution

We especially welcome contributions in:

  • Documentation improvements
  • New flow types (e.g., image indexing, code-specific flows)
  • Additional MCP tools
  • Performance optimizations
  • Test coverage
  • CI/CD setup

Questions?

  • Open a Discussion
  • Check existing issues and PRs
  • Review the documentation

Thank you for contributing!