# 0xankitsingh/corrective-rag architecture

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

- Interactive diagram: https://gitdiagram.com/0xankitsingh/corrective-rag
- Repository: https://github.com/0xankitsingh/corrective-rag

## Overview

1. **What this repo is**
   - This is a Python command-line RAG system, not a web service.
   - Its core purpose is to answer questions against a Bedrock Knowledge Base, using a “corrective” retrieval loop when the first retrieval is weak.

2. **Top-level architecture**
   - The repository splits into three main runtime paths:
     - **Knowledge base provisioning** for onboarding documents.
     - **Interactive/query-time agents** for answering questions.
     - **Support tooling** for retrieval scoring and web fallback.
   - The main boundary is between **offline setup** and **online inference**.

3. **CLI and application entry**
   - `src/rag/main.py` is the user-facing entry point for the agent CLI.
   - It supports interactive mode, one-shot queries, switching between a simple agent and a corrective agent, and selecting the LLM provider/model from the command line or environment.

4. **Configuration layer**
   - `src/rag/config.py` centralizes environment-driven settings using Pydantic-style config.
   - This layer is the control plane for the whole repo: Bedrock Knowledge Base ID, AWS region, Tavily key, model IDs, provider selection, and thresholds such as retrieval and relevance cutoffs.
   - `.env.example` and the README indicate the system is designed to be configured externally rather than hard-coded.

5. **AWS client boundary**
   - `src/rag/clients.py` is the integration point for model and AWS service clients.
   - The architecture depends on pluggable LLM backends, with Bedrock as the default and alternatives such as Anthropic, OpenAI-compatible endpoints, and Ollama.
   - This means the agent logic is separated from the specific model provider implementation.

6. **Agent subsystem**
   - `src/rag/agents/simple.py` appears to be the baseline RAG flow: retrieve context and answer.
   - `src/rag/agents/corrective.py` adds the corrective decision loop: retrieve, evaluate chunk relevance, and optionally fall back to web search.
   - `src/rag/agents/prompts.py` holds system prompts, keeping prompting concerns separate from orchestration code.

7. **Retrieval and correction flow**
   - The primary data flow is:
     1. User query enters the CLI.
     2. The agent queries the Bedrock Knowledge Base.
     3. Retrieved chunks are scored for relevance.
     4. If the score is acceptable, the answer is generated from KB context.
     5. If not, web search is used to supplement or replace weak retrieval.
   - This is the central architectural pattern of the repo.

8. **Relevance evaluation tool**
   - `src/rag/tools/relevance.py` implements chunk relevance checking using RAGAS, specifically a context-precision style metric without a reference answer.
   - This tool acts as the “corrective” gate in the system: it decides whether KB retrieval is good enough to trust.

9. **Web fallback tool**
   - `src/rag/tools/search.py` integrates Tavily for external web search.
   - This is the fallback knowledge source when internal retrieval is insufficient, creating a second information boundary outside AWS.
   - The README makes clear this is only used in the corrective path, not the baseline simple agent.

10. **Knowledge base provisioning path**
    - `src/rag/knowledge_base/provisioner.py` is an offline bootstrapper for the ingestion pipeline.
    - It creates the S3 bucket, uploads documents from `onboarding_files/`, builds the Bedrock Knowledge Base, and triggers ingestion.
    - It also writes the resulting `KNOWLEDGE_BASE_ID` back into `.env`, tying provisioning output directly into runtime configuration.

11. **Content and data sources**
    - `onboarding_files/` contains the sample source documents that become the knowledge base corpus.
    - The repo therefore has a clear document lifecycle: local files → S3 upload → Bedrock Knowledge Base indexing → retrieval at query time.

12. **External services and infrastructure**
    - The architecture depends materially on AWS Bedrock, S3, and OpenSearch Serverless for KB storage/indexing/retrieval.
    - It also requires an LLM provider for generation/evaluation and Tavily for fallback search.
    - The default runtime model is Claude via Bedrock, but the system is intentionally provider-agnostic.

13. **Build and execution tooling**
    - `pyproject.toml` and `uv.lock` show the project is managed with UV and follows modern PEP 621 packaging.
    - The README suggests two operational commands matter most: provisioning the KB and running the agent.
    - That separation reinforces the architecture: setup once, query many times.

14. **How to draw the diagram**
    - A good diagram should show:
      - **User/CLI** at the edge.
      - **Agent orchestration** in the middle.
      - **Bedrock KB retrieval** as the primary knowledge path.
      - **RAGAS relevance evaluation** as the decision gate.
      - **Tavily web search** as the fallback path.
      - **Provisioner + S3 + Bedrock KB ingestion** as the offline ingestion pipeline.
    - The key design idea is a retrieval-then-validate-then-fallback loop, with model/provider choice kept behind a client boundary.

Main entry points: [`src/rag/clients.py`](https://github.com/0xankitsingh/corrective-rag/blob/main/src/rag/clients.py) (Client layer), [`src/rag/knowledge_base/provisioner.py`](https://github.com/0xankitsingh/corrective-rag/blob/main/src/rag/knowledge_base/provisioner.py) (Provisioner), [`src/rag/agents/corrective.py`](https://github.com/0xankitsingh/corrective-rag/blob/main/src/rag/agents/corrective.py) (Corrective agent), [`src/rag/main.py`](https://github.com/0xankitsingh/corrective-rag/blob/main/src/rag/main.py) (CLI entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Online inference"]
  node_main["CLI entry<br/>entrypoint<br/>[main.py]"]
  node_config["Settings<br/>config<br/>[config.py]"]
  node_clients["Client layer<br/>integration<br/>[clients.py]"]
  node_simple_agent["Simple agent<br/>rag flow<br/>[simple.py]"]
  node_corrective_agent["Corrective agent<br/>rag loop<br/>[corrective.py]"]
  node_prompts["Prompts<br/>prompt pack<br/>[prompts.py]"]
  node_relevance{{"Relevance check<br/>evaluation<br/>[relevance.py]"}}
  node_search["Web search<br/>fallback tool<br/>[search.py]"]
end

subgraph group_ingest["Offline setup"]
  node_provisioner["Provisioner<br/>bootstrapper<br/>[provisioner.py]"]
  node_corpus["Onboarding docs<br/>document corpus"]
end

subgraph group_external["External systems"]
  node_bedrock_kb[("Bedrock KB<br/>aws knowledge base")]
  node_s3[("S3 bucket<br/>aws storage")]
  node_opensearch[("OpenSearch<br/>aws index")]
  node_llm_provider(("LLM provider<br/>model backend"))
  node_tavily(("Tavily API<br/>web search"))
  node_aws_bedrock{{"Bedrock service<br/>aws runtime"}}
end

node_main -->|"loads"| node_config
node_main -->|"builds"| node_clients
node_main -->|"selects"| node_simple_agent
node_main -->|"selects"| node_corrective_agent
node_simple_agent -->|"uses"| node_clients
node_corrective_agent -->|"uses"| node_clients
node_simple_agent -->|"prompts"| node_prompts
node_corrective_agent -->|"prompts"| node_prompts
node_corrective_agent -->|"checks"| node_relevance
node_corrective_agent -->|"falls back"| node_search
node_clients -->|"queries"| node_bedrock_kb
node_clients -->|"generates"| node_llm_provider
node_clients -->|"integrates"| node_aws_bedrock
node_provisioner -->|"uploads"| node_corpus
node_provisioner -->|"stages"| node_s3
node_provisioner -->|"creates"| node_bedrock_kb
node_provisioner -->|"indexes"| node_opensearch
node_provisioner -->|"writes"| node_config
node_bedrock_kb -.->|"backed by"| node_opensearch
node_search -->|"calls"| node_tavily
node_llm_provider -.->|"may use"| node_aws_bedrock

click node_main "https://github.com/0xankitsingh/corrective-rag/blob/main/src/rag/main.py"
click node_config "https://github.com/0xankitsingh/corrective-rag/blob/main/src/rag/config.py"
click node_clients "https://github.com/0xankitsingh/corrective-rag/blob/main/src/rag/clients.py"
click node_simple_agent "https://github.com/0xankitsingh/corrective-rag/blob/main/src/rag/agents/simple.py"
click node_corrective_agent "https://github.com/0xankitsingh/corrective-rag/blob/main/src/rag/agents/corrective.py"
click node_prompts "https://github.com/0xankitsingh/corrective-rag/blob/main/src/rag/agents/prompts.py"
click node_relevance "https://github.com/0xankitsingh/corrective-rag/blob/main/src/rag/tools/relevance.py"
click node_search "https://github.com/0xankitsingh/corrective-rag/blob/main/src/rag/tools/search.py"
click node_provisioner "https://github.com/0xankitsingh/corrective-rag/blob/main/src/rag/knowledge_base/provisioner.py"
click node_corpus "https://github.com/0xankitsingh/corrective-rag/tree/main/onboarding_files"

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_main,node_config,node_clients,node_simple_agent,node_corrective_agent,node_prompts,node_relevance,node_search toneBlue
class node_provisioner,node_corpus toneAmber
class node_bedrock_kb,node_s3,node_opensearch,node_llm_provider,node_tavily,node_aws_bedrock toneMint
```

## Components

### Online inference

Query-time CLI, agents, and supporting tools.

- [CLI entry](https://github.com/0xankitsingh/corrective-rag/blob/main/src/rag/main.py): entrypoint · User-facing command line entry for interactive and one-shot question answering. · `src/rag/main.py`
- [Settings](https://github.com/0xankitsingh/corrective-rag/blob/main/src/rag/config.py): config · Environment-driven configuration for models, AWS, thresholds, and fallback search. · `src/rag/config.py`
- [Client layer](https://github.com/0xankitsingh/corrective-rag/blob/main/src/rag/clients.py): integration · Factory and boundary for model and AWS service clients. · `src/rag/clients.py`
- [Simple agent](https://github.com/0xankitsingh/corrective-rag/blob/main/src/rag/agents/simple.py): rag flow · Baseline retrieve-and-answer path over the knowledge base. · `src/rag/agents/simple.py`
- [Corrective agent](https://github.com/0xankitsingh/corrective-rag/blob/main/src/rag/agents/corrective.py): rag loop · Retrieval flow that scores context and falls back when evidence is weak. · `src/rag/agents/corrective.py`
- [Prompts](https://github.com/0xankitsingh/corrective-rag/blob/main/src/rag/agents/prompts.py): prompt pack · System prompts and instruction templates for the agents. · `src/rag/agents/prompts.py`
- [Relevance check](https://github.com/0xankitsingh/corrective-rag/blob/main/src/rag/tools/relevance.py): evaluation · RAGAS-based chunk relevance scoring used as the corrective gate. · `src/rag/tools/relevance.py`
- [Web search](https://github.com/0xankitsingh/corrective-rag/blob/main/src/rag/tools/search.py): fallback tool · Tavily-backed external search used when retrieval quality is insufficient. · `src/rag/tools/search.py`

### Offline setup

Knowledge base provisioning and corpus bootstrapping.

- [Provisioner](https://github.com/0xankitsingh/corrective-rag/blob/main/src/rag/knowledge_base/provisioner.py): bootstrapper · Offline setup flow that creates and ingests the knowledge base. · `src/rag/knowledge_base/provisioner.py`
- [Onboarding docs](https://github.com/0xankitsingh/corrective-rag/tree/main/onboarding_files): document corpus · Source PDFs uploaded into the knowledge base during provisioning. · `onboarding_files`

### External systems

AWS services and third-party providers used by the repo.

- **Bedrock KB**: aws knowledge base · Primary retrieval store queried at runtime and created during provisioning.
- **S3 bucket**: aws storage · Staging storage for uploaded onboarding documents.
- **OpenSearch**: aws index · Backend index used by the knowledge base for retrieval.
- **LLM provider**: model backend · Pluggable generation backend such as Bedrock, Anthropic, OpenAI-compatible endpoints, or Ollama.
- **Tavily API**: web search · Third-party search service used only on the corrective fallback path.
- **Bedrock service**: aws runtime · AWS service boundary for knowledge base and model access.

## Connections

- CLI entry → Settings: loads · CLI reads runtime settings and thresholds from environment-backed config.
- CLI entry → Client layer: builds · Entry point initializes provider and AWS clients before dispatching agents.
- CLI entry → Simple agent: selects · CLI can run the baseline retrieval flow.
- CLI entry → Corrective agent: selects · CLI can run the corrective retrieval loop.
- Simple agent → Client layer: uses · Simple agent depends on retrieval and model clients.
- Corrective agent → Client layer: uses · Corrective agent depends on retrieval, evaluation, and model clients.
- Simple agent → Prompts: prompts · Baseline answer generation is guided by shared prompt templates.
- Corrective agent → Prompts: prompts · Corrective orchestration uses shared system instructions.
- Corrective agent → Relevance check: checks · Retrieved chunks are scored before answering.
- Corrective agent → Web search: falls back · Weak retrieval triggers external search supplementation.
- Client layer → Bedrock KB: queries · Retrieval client talks to the knowledge base.
- Client layer → LLM provider: generates · Model client is abstracted behind a provider boundary.
- Client layer → Bedrock service: integrates · Default path targets AWS Bedrock services.
- Provisioner → Onboarding docs: uploads · Offline bootstrap takes local documents as input.
- Provisioner → S3 bucket: stages · Documents are first placed in S3.
- Provisioner → Bedrock KB: creates · Provisioner creates the knowledge base and records its id.
- Provisioner → OpenSearch: indexes · Knowledge base setup includes the retrieval index backend.
- Provisioner → Settings: writes · Provisioning updates runtime configuration with the new KB id.
- Bedrock KB → OpenSearch: backed by · Knowledge base retrieval depends on the search index.
- Web search → Tavily API: calls · Fallback search queries the external Tavily API.
- LLM provider → Bedrock service: may use · One supported provider is Bedrock-hosted generation.
