Technology Choices¶

This page maps RAGhelm's current implementation and accepted target architecture. It complements the ADRs by showing what exists today, what is intentionally deferred, and which decision governs each area.

Product posture¶

RAGhelm is private RAG and agent release-control infrastructure. The core release-control artifacts are ReadinessScorecards and RAGRunManifests. The built-in RAG runtime is a Pinecone-first reference target; external systems should be evaluated through TargetAdapters as that boundary is implemented. In shorthand: Pinecone-first reference runtime; backend-neutral release evidence layer.

Current stack and direction¶

Area	Current choice	Implementation status	Why this choice	Primary files	Related docs
Python runtime	Python 3.11+	Implemented	Mature AI/RAG ecosystem, good SDK coverage, simple local/CI execution through `uv`	`pyproject.toml`, `raghelm/`	Installation
Python package/dependency manager	`uv`	Implemented	Fast, reproducible project installs and simple `uv run` execution	`pyproject.toml`, `uv.lock`	Installation
Python lint/format	Ruff	Implemented	Fast linting/format checks with explicit project config	`pyproject.toml`	Contributing
Python tests	Pytest	Implemented	Standard Python test runner with async and coverage support	`tests/`, `pyproject.toml`	Contributing
Reference vector database	Pinecone serverless	Partial	Managed vector search, namespaces, metadata filtering, and production-friendly operations for the reference runtime	`raghelm/ingestion/indexer.py`, `terraform/`	ADR-005, Pinecone Reference Backend
Vector topology	Dimension-specific reference indexes: `raghelm-1536`, `raghelm-1024`	Partial	Preserves native embedding dimensions instead of projecting vectors	`terraform/indexes.tf`, `raghelm/ingestion/indexer.py`, `raghelm/eval/production_adapter.py`	ADR-004
Namespace strategy	Strategy namespaces within dimension-specific indexes	Partial	Isolates retrieval strategies while respecting embedding dimensions	`raghelm/ingestion/indexer.py`	ADR-005, ADR-011
ReadinessScorecard	JSON scorecard artifact	Partial local demo	Human release decision surface: `ship`, `needs_review`, or `block`	`packages/dashboard/public/demo/readiness-scorecard.json`	ADR-002, ADR-008
RAGRunManifest	JSON manifest artifact	Partial local demo	Machine/audit provenance artifact for release evidence	`packages/dashboard/public/demo/ragrun-manifest.json`	ADR-002, ADR-009
Release policy	Versioned YAML/JSON policy	Target architecture	Deterministic gate semantics for scorecard decisions	Not yet implemented	ADR-008
QueryPipeline	Shared Python reference-runtime orchestration	Target architecture	Ensures served reference behavior and production evals use one path	Not yet unified	ADR-007
TargetAdapter	External target evidence boundary	Target architecture	Lets RAGhelm evaluate external RAG/agent systems without replacing them	Not yet implemented	ADR-013
Model provider registry	Embeddings + generation + judges	Target architecture	Consistent model provenance, cost, latency, and failure handling	Existing provider calls are not yet unified	ADR-012
Hosted embedding provider	OpenAI embeddings	Partial	Production eval path uses OpenAI embeddings by default, with cost accounting and 1536-dimensional support	`raghelm/eval/production_adapter.py`, `raghelm/ingestion/__init__.py`	ADR-004
Local/open embedding model	`BAAI/bge-large-en-v1.5` via `sentence-transformers`	Implemented for retrieval path	Local 1024-dimensional retrieval path for development and open-model compatibility	`raghelm/retrieval/retriever.py`, `raghelm/api/server.py`	ADR-004
Reranking provider	Cohere SDK dependency	Dependency-ready, policy target	Reserved for precision-oriented reranking where measured lift justifies cost/latency	`pyproject.toml`, `.env.example`	ADR-011
Query API	Python FastAPI	Implemented	Canonical current AI runtime API for `/query`, `/health`, and cost/index metrics	`raghelm/api/server.py`, `tests/test_server.py`	ADR-006
Product gateway	TypeScript Fastify	Target architecture; current package is lightweight	Future product/public API boundary for dashboard/auth/external contracts	`packages/api/src/index.ts`, `packages/api/package.json`	ADR-006
Dashboard	React + Vite	Partial local demo	Local release-control demo surface and future scorecard dashboard	`packages/dashboard/src/App.tsx`, `packages/dashboard/package.json`	System Overview
Persistence	JSON artifacts now; SQLite local + Postgres production target	Partial JSON; DB target not started	Portable proof bundles now, queryable history later	`data/`, `packages/dashboard/public/demo/`	ADR-014, ADR-015
Security/compliance boundary	Private-by-default release-control evidence	Target architecture	Prevents private source content, credentials, and sensitive traces from leaking into public proof artifacts	Scorecards, manifests, target adapters, release policies	ADR-003
Docs site	MkDocs Material	Implemented	Searchable, navigable, GitHub Pages-friendly documentation	`mkdocs.yml`, `docs/`	Home
Deployment	Docker today; Compose target; BYOC future	Partial	Portable runtime packaging now, production-shaped deployment later	`Dockerfile`, `.github/workflows/docker-build.yml`	ADR-020

Architectural boundaries¶

External system under test
  -> TargetAdapter, target architecture
  -> normalized evidence
  -> RAGRunManifest + ReadinessScorecard

RAGhelm reference runtime
  -> Python QueryPipeline, target architecture
  -> retrieval/generation/eval
  -> RAGRunManifest + ReadinessScorecard

Product surfaces
  -> TypeScript gateway, target architecture
  -> dashboard / CI / proof artifacts

The TypeScript Fastify package is intentionally documented separately from the Python FastAPI query API because the current TypeScript package is lightweight, while Python owns implemented AI behavior today. ADR-006 defines the target split: Python owns AI runtime; TypeScript owns product/public gateway.

Environment variables¶

Variable	Required for	Notes
`PINECONE_API_KEY`	Hosted Pinecone ingestion, retrieval, production eval	Do not commit real keys.
`PINECONE_ENVIRONMENT`	Pinecone cloud metadata/configuration	Example uses `us-east-1`.
`RAGHELM_PINECONE_MODE`	Explicit Pinecone backend mode	Supported values are documented in Pinecone Reference Backend.
`PINECONE_LOCAL_URL`	Local Pinecone-compatible development/CI mode	Example: `http://localhost:5080`.
`RAGHELM_EVAL_INDEX`	Production eval index override	Defaults to `raghelm-1536` in `ProductionEvalAdapter`.
`OPENAI_API_KEY`	OpenAI embeddings/generation/judging	Needed for production eval and non-dry-run OpenAI embedding paths.
`ANTHROPIC_API_KEY`	Anthropic generation/judging	Optional unless selected by model routing or judge mode.
`COHERE_API_KEY`	Cohere reranking	Required only for reranking integrations that use Cohere.

Decision log¶

The full decision list, including implementation status and applies-to scope, is maintained in Architecture.

When to add another ADR¶

Add an ADR when a change constrains future work or changes production behavior. Examples:

changing the canonical API surface
changing model routing or retrieval policy
adding reranking as default behavior
changing scorecard/manifest source-of-truth rules
changing namespace naming or index topology
replacing Pinecone, FastAPI, Fastify, Vite, or MkDocs
changing privacy, public-proof, or BYOC security boundaries