Skip to content

Contributing

RAGhelm is release-control infrastructure for private RAG and agent systems. Contributions should make behavior more measurable, reliable, debuggable, private-by-default, and aligned with the ADRs.

Development setup

uv sync --extra dev
pnpm install

Checks

uv run ruff check .
uv run pytest tests/ -q
uv run mkdocs build --strict
pnpm run format:check

Architecture expectations

Before changing architecture-impacting behavior, read:

  1. ADR-001 Product Architecture Spine
  2. ADR-002 Scorecard and RAGRunManifest
  3. ADR-003 Security and Compliance Boundary
  4. ADR-004 Embedding Model Strategy
  5. ADR-005 Pinecone Reference Backend Namespace Strategy

Add or update ADRs for hard-to-reverse decisions, production behavior changes, security boundaries, product boundaries, provider abstractions, release-gate semantics, and public-proof rules.

Golden dataset changes

  1. Add examples to raghelm/eval/golden_dataset.json.
  2. Use stable unique IDs.
  3. Use valid categories: factual_lookup, comparison, synthesis, temporal, contradictory.
  4. Include expected answers, source docs, relevant chunks, difficulty, and category.
  5. Run validation and tests.

Public claims

Do not update public quality claims or badges from local/demo output. Public claims require production scorecard and manifest evidence per ADR-010.