# lucas1114/rag-contract architecture

> Architecture diagram of the GitHub repository lucas1114/rag-contract, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lucas1114/rag-contract
- Repository: https://github.com/lucas1114/rag-contract

## Overview

rag-contract is a fixed-corpus question-answering service whose contract emphasizes attributable answers, explicit refusal states, measured retrieval quality, versioned indexes, and enforced budgets. The request path runs through the HTTP surface and Service, which acquires one index, retrieves passages, drafts claims, and grounds them into an answer. Separate evaluation and gate paths check retrieval, answer behavior, index freshness, and thresholds. Edges reflect excerpts, SOURCE INDEX references, or README statements; unsampled details are omitted where wiring cannot be verified.

Main entry points: [`src/rag_contract/service.py`](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/service.py) (Request Service), [`src/rag_contract/index.py`](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/index.py) (Committed Index), [`src/rag_contract/cli.py`](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/cli.py) (Command Line), [`src/rag_contract/lifecycle.py`](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/lifecycle.py) (Index Lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_corpus_index["Corpus and Index"]
  node_corpus_files["RFC Corpus"]
  node_corpus_loader["Corpus Loader<br/>[corpus.py]"]
  node_sections["Section Parser<br/>[sections.py]"]
  node_chunking["Section Chunking<br/>[chunking.py]"]
  node_embedding["Embeddings<br/>[embedding.py]"]
  node_index[("Committed Index<br/>[index.py]")]
  node_lifecycle["Index Lifecycle<br/>[lifecycle.py]"]
  node_registry["Index Registry<br/>[registry.py]"]
end

subgraph group_answering["Answering"]
  node_http["HTTP Surface<br/>[app.py]"]
  node_service["Request Service<br/>[service.py]"]
  node_retrieval["Vector Retrieval<br/>[retrieval.py]"]
  node_drafts["Claim Drafter<br/>[drafter.py]"]
  node_grounding["Claim Grounding<br/>[grounding.py]"]
  node_answering_states["Answer States<br/>[answering.py]"]
end

subgraph group_evaluation["Evaluation and Gate"]
  node_evalset["Question Annotations<br/>[evalset.py]"]
  node_evaluate["Retrieval Evaluation<br/>[evaluate.py]"]
  node_answer_eval["Answer Evaluation<br/>[answer_eval.py]"]
  node_gate["Quality Gate<br/>[gate.py]"]
  node_cli["Command Line<br/>[cli.py]"]
end

subgraph group_runtime["Runtime Controls"]
  node_budget["Request Budgets<br/>[budget.py]"]
  node_ratelimit["Rate Limiter<br/>[ratelimit.py]"]
  node_spend["API Spend Cap<br/>[spend.py]"]
end

node_user(("Questioner"))
node_embedding_api(("Embedding API"))
node_model_api(("Drafting API"))

node_user -->|"asks"| node_http
node_http -->|"delegates"| node_service
node_service -->|"acquires index"| node_registry
node_service -->|"searches"| node_retrieval
node_service -->|"drafts claims"| node_drafts
node_service -->|"forms answer"| node_answering_states
node_answering_states -->|"checks claims"| node_grounding
node_retrieval -->|"ranks vectors"| node_index
node_drafts -.->|"optional request"| node_model_api
node_embedding -.->|"embeds text"| node_embedding_api
node_corpus_loader -->|"loads and verifies"| node_corpus_files
node_sections -->|"parses documents"| node_corpus_loader
node_chunking -->|"chunks sections"| node_sections
node_index -->|"fingerprints corpus"| node_corpus_loader
node_index -->|"stores chunks"| node_chunking
node_lifecycle -->|"checks corpus"| node_corpus_loader
node_lifecycle -->|"checks model"| node_embedding
node_lifecycle -->|"checks version"| node_index
node_registry -->|"loads index"| node_index
node_evalset -->|"validates states"| node_answering_states
node_evaluate -->|"scores questions"| node_evalset
node_evaluate -->|"measures ranking"| node_retrieval
node_answer_eval -->|"evaluates outcomes"| node_answering_states
node_answer_eval -->|"checks grounding"| node_grounding
node_gate -->|"checks ceilings"| node_budget
node_gate -->|"checks freshness"| node_lifecycle
node_cli -->|"runs evaluation"| node_evaluate
node_cli -->|"runs answer eval"| node_answer_eval
node_cli -->|"runs gate"| node_gate
node_cli -->|"builds index"| node_index
node_cli -->|"records drafts"| node_drafts
node_budget -->|"defines limit"| node_ratelimit
node_http -->|"limits requests"| node_ratelimit
node_service -->|"enforces deadline"| node_budget
node_embedding -->|"accounts usage"| node_spend
node_drafts -->|"accounts usage"| node_spend

click node_http "https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/app.py"
click node_service "https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/service.py"
click node_retrieval "https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/retrieval.py"
click node_drafts "https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/drafter.py"
click node_grounding "https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/grounding.py"
click node_answering_states "https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/answering.py"
click node_corpus_files "https://github.com/lucas1114/rag-contract/tree/main/corpus"
click node_corpus_loader "https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/corpus.py"
click node_sections "https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/sections.py"
click node_chunking "https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/chunking.py"
click node_embedding "https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/embedding.py"
click node_index "https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/index.py"
click node_lifecycle "https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/lifecycle.py"
click node_registry "https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/registry.py"
click node_evalset "https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/evalset.py"
click node_evaluate "https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/evaluate.py"
click node_answer_eval "https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/answer_eval.py"
click node_gate "https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/gate.py"
click node_cli "https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/cli.py"
click node_budget "https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/budget.py"
click node_ratelimit "https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/ratelimit.py"
click node_spend "https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/spend.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_corpus_files,node_corpus_loader,node_sections,node_chunking,node_embedding,node_index,node_lifecycle,node_registry toneBlue
class node_http,node_service,node_retrieval,node_drafts,node_grounding,node_answering_states toneAmber
class node_evalset,node_evaluate,node_answer_eval,node_gate,node_cli,node_embedding_api,node_model_api toneMint
class node_budget,node_ratelimit,node_spend toneRose
class node_user toneIndigo
```

## Components

### Corpus and Index

- [RFC Corpus](https://github.com/lucas1114/rag-contract/tree/main/corpus): `corpus`
- [Corpus Loader](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/corpus.py): `src/rag_contract/corpus.py`
- [Section Parser](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/sections.py): `src/rag_contract/sections.py`
- [Section Chunking](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/chunking.py): `src/rag_contract/chunking.py`
- [Embeddings](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/embedding.py): `src/rag_contract/embedding.py`
- [Committed Index](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/index.py): `src/rag_contract/index.py`
- [Index Lifecycle](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/lifecycle.py): `src/rag_contract/lifecycle.py`
- [Index Registry](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/registry.py): `src/rag_contract/registry.py`

### Answering

- [HTTP Surface](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/app.py): `src/rag_contract/app.py`
- [Request Service](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/service.py): `src/rag_contract/service.py`
- [Vector Retrieval](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/retrieval.py): `src/rag_contract/retrieval.py`
- [Claim Drafter](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/drafter.py): `src/rag_contract/drafter.py`
- [Claim Grounding](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/grounding.py): `src/rag_contract/grounding.py`
- [Answer States](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/answering.py): `src/rag_contract/answering.py`

### Evaluation and Gate

- [Question Annotations](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/evalset.py): `src/rag_contract/evalset.py`
- [Retrieval Evaluation](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/evaluate.py): `src/rag_contract/evaluate.py`
- [Answer Evaluation](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/answer_eval.py): `src/rag_contract/answer_eval.py`
- [Quality Gate](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/gate.py): `src/rag_contract/gate.py`
- [Command Line](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/cli.py): `src/rag_contract/cli.py`

### Runtime Controls

- [Request Budgets](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/budget.py): `src/rag_contract/budget.py`
- [Rate Limiter](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/ratelimit.py): `src/rag_contract/ratelimit.py`
- [API Spend Cap](https://github.com/lucas1114/rag-contract/blob/main/src/rag_contract/spend.py): `src/rag_contract/spend.py`

### Other components

- **Questioner**
- **Embedding API**
- **Drafting API**

## Connections

- Questioner → HTTP Surface: asks (evidence: `README.md`)
- HTTP Surface → Request Service: delegates (evidence: `src/rag_contract/app.py`)
- Request Service → Index Registry: acquires index (evidence: `src/rag_contract/service.py`)
- Request Service → Vector Retrieval: searches (evidence: `src/rag_contract/service.py`)
- Request Service → Claim Drafter: drafts claims (evidence: `src/rag_contract/service.py`)
- Request Service → Answer States: forms answer (evidence: `src/rag_contract/service.py`)
- Answer States → Claim Grounding: checks claims (evidence: `src/rag_contract/answering.py`)
- Vector Retrieval → Committed Index: ranks vectors (evidence: `src/rag_contract/retrieval.py`)
- Claim Drafter → Drafting API: optional request (evidence: `src/rag_contract/drafter.py`)
- Embeddings → Embedding API: embeds text (evidence: `src/rag_contract/embedding.py`)
- Corpus Loader → RFC Corpus: loads and verifies (evidence: `src/rag_contract/corpus.py`)
- Section Parser → Corpus Loader: parses documents (evidence: `src/rag_contract/sections.py`)
- Section Chunking → Section Parser: chunks sections (evidence: `src/rag_contract/chunking.py`)
- Committed Index → Corpus Loader: fingerprints corpus (evidence: `src/rag_contract/index.py`)
- Committed Index → Section Chunking: stores chunks (evidence: `src/rag_contract/index.py`)
- Index Lifecycle → Corpus Loader: checks corpus (evidence: `src/rag_contract/lifecycle.py`)
- Index Lifecycle → Embeddings: checks model (evidence: `src/rag_contract/lifecycle.py`)
- Index Lifecycle → Committed Index: checks version (evidence: `src/rag_contract/lifecycle.py`)
- Index Registry → Committed Index: loads index (evidence: `src/rag_contract/registry.py`)
- Question Annotations → Answer States: validates states (evidence: `src/rag_contract/evalset.py`)
- Retrieval Evaluation → Question Annotations: scores questions (evidence: `src/rag_contract/evaluate.py`)
- Retrieval Evaluation → Vector Retrieval: measures ranking (evidence: `src/rag_contract/evaluate.py`)
- Answer Evaluation → Answer States: evaluates outcomes (evidence: `src/rag_contract/answer_eval.py`)
- Answer Evaluation → Claim Grounding: checks grounding (evidence: `src/rag_contract/answer_eval.py`)
- Quality Gate → Request Budgets: checks ceilings (evidence: `src/rag_contract/gate.py`)
- Quality Gate → Index Lifecycle: checks freshness (evidence: `src/rag_contract/gate.py`)
- Command Line → Retrieval Evaluation: runs evaluation (evidence: `src/rag_contract/cli.py`)
- Command Line → Answer Evaluation: runs answer eval (evidence: `src/rag_contract/cli.py`)
- Command Line → Quality Gate: runs gate (evidence: `src/rag_contract/cli.py`)
- Command Line → Committed Index: builds index (evidence: `src/rag_contract/cli.py`)
- Command Line → Claim Drafter: records drafts (evidence: `src/rag_contract/cli.py`)
- Request Budgets → Rate Limiter: defines limit (evidence: `src/rag_contract/budget.py`)
- HTTP Surface → Rate Limiter: limits requests (evidence: `src/rag_contract/app.py`)
- Request Service → Request Budgets: enforces deadline (evidence: `src/rag_contract/service.py`)
- Embeddings → API Spend Cap: accounts usage (evidence: `src/rag_contract/embedding.py`)
- Claim Drafter → API Spend Cap: accounts usage (evidence: `src/rag_contract/drafter.py`)