Contributing to anchor¶

We welcome contributions to anchor! This guide explains how to set up your development environment, follow our code conventions, and submit changes.

Development Setup¶

Prerequisites¶

• Python 3.11 or later
• uv package manager

Getting Started¶

git clone https://github.com/artcgranja/anchor.git
cd anchor
uv sync

This installs all dependencies, including development tools.

Running Tests¶

uv run pytest

This runs the full test suite (1,988 tests with ~94% coverage). To run specific tests:

uv run pytest tests/test_retrieval/  # Run tests in a module
uv run pytest tests/test_retrieval/test_rerankers.py::test_name  # Run specific test

Code Quality¶

Check your code with Ruff:

uv run ruff check src/ tests/
uv run ruff format src/ tests/  # Auto-format code

Code Conventions¶

Language and Tools¶

• Python: 3.11+ with full type hints
• Models: Pydantic v2 (all models use frozen=True by default)
• Extension Points: PEP 544 Protocols for all interfaces
• Linting: Ruff with line-length of 100 characters
• Type Checking: mypy with strict mode enabled

Requirements for Every File¶

Add this import at the top of every Python file:

from __future__ import annotations

Always include complete type hints:

def process_query(query: str, limit: int = 10) -> list[ContextItem]:
    """Process a query and return ranked context items."""
    ...

Pydantic Models¶

from pydantic import BaseModel, Field

class MyModel(BaseModel, frozen=True):  # frozen=True is the default
    name: str = Field(..., description="The name")
    score: float = Field(default=0.0, ge=0.0, le=1.0)

Protocols for Extension Points¶

Define extension points using Protocol:

from typing import Protocol

class MyCustomInterface(Protocol):
    """Protocol for implementing custom behavior."""

    def process(self, data: str) -> str:
        """Process data and return a result."""
        ...

Testing¶

Coverage Requirements¶

• Minimum 80% code coverage (94% for new features)
• Every new class must have tests
• Never make real API calls in tests (mock external services)

Test File Organization¶

tests/
├── test_{module}/
│   ├── conftest.py          # Shared fixtures
│   ├── test_{file}.py       # Test one module
│   └── test_{file}_async.py # Async tests

Example Test¶

from unittest.mock import Mock, patch
import pytest

def test_retriever_returns_items():
    """Test that retriever returns expected items."""
    retriever = DenseRetriever(...)
    items = retriever.retrieve("query")
    assert len(items) > 0
    assert all(isinstance(item, ContextItem) for item in items)

Adding a New Module¶

Follow this checklist:

1. Define Protocol (if it's an extension point)
2. Create src/anchor/protocols/{name}.py

3. Define the protocol interface

4. Implement Core

5. Create implementation in appropriate subpackage
6. Use type hints everywhere

7. Add docstrings

8. Export Properly

9. Add to module __init__.py
10. Add to main src/anchor/__init__.py

11. Update __all__

12. Add Tests

13. Create tests/test_{module}/ directory

14. Achieve 94% coverage for new code

15. Document

16. Add guide: docs/docs/guides/{name}.md
17. Add API reference: docs/docs/api/{name}.md
18. Update main navigation in docs/mkdocs.yml

Pull Request Guidelines¶

Before Submitting¶

• Tests pass: uv run pytest
• Linting passes: uv run ruff check src/ tests/
• Type checking passes: uv run mypy src/
• Coverage is 94%+ for new code
• One feature per PR (keep PRs focused)
• Documentation updated for public APIs

PR Title and Description¶

• Title: Start with verb (Add, Fix, Update, Refactor)
• Description: Explain why the change is needed
• Link related issues: "Closes #123"

Example PR Template¶

## Summary
Brief description of what this PR does.

## Changes
- Item 1
- Item 2

## Testing
- [ ] Unit tests added
- [ ] Integration tests passing
- [ ] Manual testing done

Closes #123

Architecture Overview¶

anchor is organized into 14 core modules with 217+ exports:

• Protocols: Extension points for custom implementations
• Pipeline: Step-based execution framework
• Retrieval: Dense, sparse, and hybrid search
• Ingestion: Document parsing and chunking
• Memory: Conversation and context management
• Query: Transformation and classification
• Evaluation: RAG and retrieval metrics
• Observability: Tracing and cost tracking
• Multimodal: Image and table handling

See Architecture for details.

Getting Help¶

• Questions: Check Getting Started
• API Reference: See API Docs
• Guides: Browse Guides
• Issues: GitHub Issues

Code Review Expectations¶

We follow these principles:

• Simplicity First: Make changes as minimal as possible
• No Laziness: Find root causes, not quick fixes
• Minimal Impact: Only touch necessary code
• Senior Standards: Code should pass staff engineer review

Thank you for contributing to anchor!