Contributing¶

Contributions to Seamless-RAG are welcome. This guide covers the development setup and workflow.

Development Setup¶

git clone https://github.com/SunflowersLwtech/seamless-rag.git
cd seamless-rag

conda create -n seamless-rag python=3.12 -y
conda activate seamless-rag
pip install -e ".[dev,mariadb,embeddings]"

Running Tests¶

# Quick check (stops on first failure)
make test-quick

# All unit tests
make test-unit

# TOON spec conformance (166 official fixtures)
make test-spec

# Hypothesis property-based tests
make test-props

# Everything except integration
make test-all

# Full suite including integration (requires Docker)
docker compose -f docker-compose.test.yml up -d
make test-full

Code Style¶

The project uses ruff for linting and formatting:

make lint          # check
ruff format .      # auto-format

Pull Request Guidelines¶

Create a feature branch from main
Write tests for new functionality
Run make test-all and ensure it passes
Keep commits focused -- one logical change per commit
Use conventional commit messages: feat:, fix:, test:, docs:, refactor:

Project Structure¶

src/seamless_rag/       # Main package
tests/
  unit/                 # Unit tests
  integration/          # Integration tests (need Docker)
  fixtures/toon_spec/   # Official TOON v3 test fixtures (read-only)
eval/                   # Evaluation harness (read-only)
docs/                   # Documentation (MkDocs Material)

Adding a Provider¶

To add a new embedding or LLM provider:

Create a new module in src/seamless_rag/providers/ or src/seamless_rag/llm/
Implement the EmbeddingProvider or LLMProvider protocol
Register it in the corresponding factory module
Add tests in tests/unit/
Document it in docs/providers.md