Skip to content

Repository Map

This page maps the current repository layout to RAGhelm’s release-control architecture. Prefer this map over illustrative tree snippets.

Top-level paths

Path Purpose
raghelm/ Python package: ingestion, retrieval, generation, API, and evaluation modules.
raghelm/ingestion/ Pinecone reference backend ingestion and indexer code.
raghelm/retrieval/ Retrieval path for the reference runtime.
raghelm/generation/ Answer generation and cost estimation.
raghelm/api/ Python FastAPI query API, complexity classifier, model router, and cost tracker.
raghelm/eval/ Golden dataset, metrics, scorer, production adapter, regression checker, and eval runner.
packages/api/ Lightweight TypeScript Fastify package; target product/public gateway boundary.
packages/dashboard/ React/Vite local ReadinessScorecard/RAGRunManifest demo and future dashboard.
docs/ MkDocs user documentation.
docs/architecture/ System overview, technology choices, Pinecone reference backend docs, and ADRs.
docs/architecture/decisions/ Priority-ordered ADRs by product/architecture scope.
docs/eval/ Evaluation concepts, running instructions, metrics, dataset, and regression docs.
tests/ Python tests using fakes/mocks where external services are not required.
scripts/ Utility scripts, including badge generation and Pinecone smoke/integration helpers.
terraform/ Pinecone reference index infrastructure-as-code.
.github/workflows/ CI, Docker, eval, production eval, and docs deployment workflows.
data/eval_results/ Detailed eval run artifacts.
data/eval_summaries/ Summary artifacts used by badges/docs when valid.
badges/ and docs/badges/ Badge output locations; production publishing is disabled until scorecard/manifest-backed badges exist.
corpus/ Open-license example corpus files.

Important files

File Purpose
pyproject.toml Python package metadata, dependencies, Ruff config, Pytest config.
uv.lock Locked Python dependency graph.
package.json Root TypeScript formatting and hook scripts.
pnpm-workspace.yaml pnpm workspace configuration.
mkdocs.yml Docs site navigation, theme, and GitHub issue autolinking config.
.env.example Example local/production environment variables.
Dockerfile Container image that runs the eval CLI by default.
AGENTS.md Coding-agent guidance and repository architecture standards.

Source of truth notes

  • Start with Architecture, System Overview, and Technology Choices.
  • Product/evidence priority is defined by ADR-001 through ADR-003.
  • Embedding and Pinecone reference backend behavior is defined by ADR-004 and ADR-005.
  • External systems should be normalized through TargetAdapters per ADR-013.
  • Production quality claims require scorecard/manifest evidence per ADR-010.
  • CLI behavior is documented in CLI Commands and the live --help output.