# sachhh05/adaptive_rag architecture

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

- Interactive diagram: https://gitdiagram.com/sachhh05/adaptive_rag
- Repository: https://github.com/sachhh05/adaptive_rag

## Overview

This is an experimental adaptive RAG system: queries are routed to direct answering, retrieval, or decomposition, then answers and evidence are scored and results recorded. The README describes LinUCB routing, while the sampled evaluation excerpt also imports a rule-based router and LinUCB components; the omitted evaluation code prevents confirming the exact policy dispatch and update sequence. Edges reflect documented behavior or visible source references, with uncertain wiring left out.

Main entry points: [`eval/checkpoint5_full_eval.py`](https://github.com/sachhh05/adaptive_rag/blob/master/eval/checkpoint5_full_eval.py) (CP5 Evaluator), [`pipeline/reward/reward_function.py`](https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/reward/reward_function.py) (Reward Composer), [`pipeline/actions/retrieve.py`](https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/actions/retrieve.py) (Retrieve Action), [`pipeline/actions/decompose.py`](https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/actions/decompose.py) (Query Decomposition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routing["Query Routing"]
  node_features["Query Features"]
  node_rule_router["Rule Router<br/>[adaptive_router.py]"]
  node_context["Context Builder<br/>[context.py]"]
  node_linucb["LinUCB Policy<br/>[linucb.py]"]
end

subgraph group_actions["Answer Actions"]
  node_direct["Direct Answer<br/>[answer_directly.py]"]
  node_retrieval_action["Retrieve Action<br/>[retrieve.py]"]
  node_decompose["Query Decomposition<br/>[decompose.py]"]
  node_rerank["Reranking<br/>[rerank.py]"]
  node_action_common["Action Utilities<br/>[common.py]"]
end

subgraph group_evaluation["Scoring and Evaluation"]
  node_evaluation_runner["CP5 Evaluator"]
  node_reward["Reward Composer<br/>[reward_function.py]"]
  node_quality["Answer Quality<br/>[answer_quality.py]"]
  node_faithfulness["Faithfulness Scorer<br/>[faithfulness.py]"]
  node_precision["Retrieval Precision"]
  node_latency["Latency Scorer<br/>[latency.py]"]
  node_results["Evaluation Results"]
end

subgraph group_knowledge["Knowledge and Baselines"]
  node_chroma[("ChromaDB Collection")]
  node_groq{{"Groq LLM API"}}
  node_naive_rag["Naive RAG Baseline<br/>[naive_rag.py]"]
end

node_user(("Questioner"))

node_user -->|"submits query"| node_evaluation_runner
node_evaluation_runner -->|"extracts features"| node_features
node_rule_router -->|"extracts features"| node_features
node_evaluation_runner -->|"builds context"| node_context
node_evaluation_runner -->|"uses policy"| node_linucb
node_features -.->|"normalizes features"| node_context
node_context -.->|"supplies context"| node_linucb
node_evaluation_runner -.->|"executes action"| node_direct
node_evaluation_runner -.->|"executes action"| node_retrieval_action
node_evaluation_runner -.->|"executes action"| node_decompose
node_decompose -->|"retrieves subquestions"| node_retrieval_action
node_retrieval_action -->|"uses utilities"| node_action_common
node_direct -->|"uses utilities"| node_action_common
node_retrieval_action -->|"queries chunks"| node_chroma
node_retrieval_action -->|"generates answer"| node_groq
node_decompose -->|"generates subquestions"| node_groq
node_decompose -->|"synthesizes answer"| node_groq
node_naive_rag -->|"retrieves chunks"| node_chroma
node_naive_rag -->|"generates answer"| node_groq
node_evaluation_runner -->|"computes reward"| node_reward
node_reward -->|"scores answer"| node_quality
node_reward -->|"scores support"| node_faithfulness
node_reward -->|"scores evidence"| node_precision
node_reward -->|"scores latency"| node_latency
node_evaluation_runner -->|"writes results"| node_results

click node_evaluation_runner "https://github.com/sachhh05/adaptive_rag/blob/master/eval/checkpoint5_full_eval.py"
click node_features "https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/feature_extractor.py"
click node_rule_router "https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/adaptive_router.py"
click node_context "https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/bandit/context.py"
click node_linucb "https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/bandit/linucb.py"
click node_direct "https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/actions/answer_directly.py"
click node_retrieval_action "https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/actions/retrieve.py"
click node_decompose "https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/actions/decompose.py"
click node_rerank "https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/actions/rerank.py"
click node_action_common "https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/actions/common.py"
click node_naive_rag "https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/naive_rag.py"
click node_reward "https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/reward/reward_function.py"
click node_quality "https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/reward/answer_quality.py"
click node_faithfulness "https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/reward/faithfulness.py"
click node_precision "https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/reward/retrieval_precision.py"
click node_latency "https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/reward/latency.py"
click node_results "https://github.com/sachhh05/adaptive_rag/blob/master/results/checkpoint5/checkpoint5_results.csv"

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_features,node_rule_router,node_context,node_linucb toneBlue
class node_direct,node_retrieval_action,node_decompose,node_rerank,node_action_common toneAmber
class node_evaluation_runner,node_reward,node_quality,node_faithfulness,node_precision,node_latency,node_results toneMint
class node_chroma,node_groq,node_naive_rag toneRose
class node_user toneIndigo
```

## Components

### Query Routing

- [Query Features](https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/feature_extractor.py): `pipeline/feature_extractor.py`
- [Rule Router](https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/adaptive_router.py): `pipeline/adaptive_router.py`
- [Context Builder](https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/bandit/context.py): `pipeline/bandit/context.py`
- [LinUCB Policy](https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/bandit/linucb.py): `pipeline/bandit/linucb.py`

### Answer Actions

- [Direct Answer](https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/actions/answer_directly.py): `pipeline/actions/answer_directly.py`
- [Retrieve Action](https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/actions/retrieve.py): `pipeline/actions/retrieve.py`
- [Query Decomposition](https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/actions/decompose.py): `pipeline/actions/decompose.py`
- [Reranking](https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/actions/rerank.py): `pipeline/actions/rerank.py`
- [Action Utilities](https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/actions/common.py): `pipeline/actions/common.py`

### Scoring and Evaluation

- [CP5 Evaluator](https://github.com/sachhh05/adaptive_rag/blob/master/eval/checkpoint5_full_eval.py): `eval/checkpoint5_full_eval.py`
- [Reward Composer](https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/reward/reward_function.py): `pipeline/reward/reward_function.py`
- [Answer Quality](https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/reward/answer_quality.py): `pipeline/reward/answer_quality.py`
- [Faithfulness Scorer](https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/reward/faithfulness.py): `pipeline/reward/faithfulness.py`
- [Retrieval Precision](https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/reward/retrieval_precision.py): `pipeline/reward/retrieval_precision.py`
- [Latency Scorer](https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/reward/latency.py): `pipeline/reward/latency.py`
- [Evaluation Results](https://github.com/sachhh05/adaptive_rag/blob/master/results/checkpoint5/checkpoint5_results.csv): `results/checkpoint5/checkpoint5_results.csv`

### Knowledge and Baselines

- **ChromaDB Collection**
- **Groq LLM API**
- [Naive RAG Baseline](https://github.com/sachhh05/adaptive_rag/blob/master/pipeline/naive_rag.py): `pipeline/naive_rag.py`

### Other components

- **Questioner**

## Connections

- Questioner → CP5 Evaluator: submits query (evidence: `README.md`)
- CP5 Evaluator → Query Features: extracts features (evidence: `eval/checkpoint5_full_eval.py`)
- Rule Router → Query Features: extracts features (evidence: `pipeline/adaptive_router.py`)
- CP5 Evaluator → Context Builder: builds context (evidence: `eval/checkpoint5_full_eval.py`)
- CP5 Evaluator → LinUCB Policy: uses policy (evidence: `eval/checkpoint5_full_eval.py`)
- Query Features → Context Builder: normalizes features (evidence: `README.md`)
- Context Builder → LinUCB Policy: supplies context (evidence: `README.md`)
- CP5 Evaluator → Direct Answer: executes action (evidence: `README.md`)
- CP5 Evaluator → Retrieve Action: executes action (evidence: `README.md`)
- CP5 Evaluator → Query Decomposition: executes action (evidence: `README.md`)
- Query Decomposition → Retrieve Action: retrieves subquestions (evidence: `pipeline/actions/decompose.py`)
- Retrieve Action → Action Utilities: uses utilities (evidence: `pipeline/actions/retrieve.py`)
- Direct Answer → Action Utilities: uses utilities (evidence: `pipeline/actions/answer_directly.py`)
- Retrieve Action → ChromaDB Collection: queries chunks (evidence: `pipeline/actions/retrieve.py`)
- Retrieve Action → Groq LLM API: generates answer
- Query Decomposition → Groq LLM API: generates subquestions (evidence: `pipeline/actions/decompose.py`)
- Query Decomposition → Groq LLM API: synthesizes answer (evidence: `pipeline/actions/decompose.py`)
- Naive RAG Baseline → ChromaDB Collection: retrieves chunks (evidence: `pipeline/naive_rag.py`)
- Naive RAG Baseline → Groq LLM API: generates answer (evidence: `pipeline/naive_rag.py`)
- CP5 Evaluator → Reward Composer: computes reward (evidence: `eval/checkpoint5_full_eval.py`)
- Reward Composer → Answer Quality: scores answer (evidence: `pipeline/reward/reward_function.py`)
- Reward Composer → Faithfulness Scorer: scores support (evidence: `pipeline/reward/reward_function.py`)
- Reward Composer → Retrieval Precision: scores evidence (evidence: `pipeline/reward/reward_function.py`)
- Reward Composer → Latency Scorer: scores latency (evidence: `pipeline/reward/reward_function.py`)
- CP5 Evaluator → Evaluation Results: writes results (evidence: `eval/checkpoint5_full_eval.py`)