# starsuzi/adaptive-rag architecture

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

- Interactive diagram: https://gitdiagram.com/starsuzi/adaptive-rag
- Repository: https://github.com/starsuzi/adaptive-rag

## Overview

Adaptive-RAG answers questions by estimating their complexity and choosing among no-retrieval, single-step retrieval, and iterative multi-step QA. Its runtime combines configurable question decomposition, participant-based execution, retrieval, and LLM answer generation; the repository also includes classifier training-data preparation and evaluation utilities. The README documents the strategy selection and retriever/LLM services, while several runtime modules are represented only by the source index, so links without direct evidence are omitted or marked unverified.

Main entry points: [`commaqa/inference/configurable_inference.py`](https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/inference/configurable_inference.py) (Inference configuration), [`commaqa/execution/llm_qa_model.py`](https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/execution/llm_qa_model.py) (LLM QA model), [`classifier/run_classifier.py`](https://github.com/starsuzi/adaptive-rag/blob/main/classifier/run_classifier.py) (Complexity classifier), [`commaqa/inference/ircot.py`](https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/inference/ircot.py) (QA strategies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_adaptive["Complexity adaptation"]
  node_complexity_classifier["Complexity classifier<br/>[run_classifier.py]"]
  node_classifier_prep["Classifier preprocessing"]
  node_strategy["QA strategies<br/>[ircot.py]"]
end

subgraph group_inference["Question inference"]
  node_configurable_inference["Inference configuration"]
  node_search["Decomposition search<br/>[model_search.py]"]
  node_instances["Question state<br/>[data_instances.py]"]
  node_qa_participant["QA participant<br/>[participant_qa.py]"]
  node_execution_participant["Execution participant"]
  node_operation_executor["Operation executor"]
  node_qa_model["LLM QA model<br/>[llm_qa_model.py]"]
end

subgraph group_services["Retrieval and generation"]
  node_retriever_api["Retriever service<br/>[serve.py]"]
  node_retriever["Elasticsearch retrieval"]
  node_elasticsearch[("Elasticsearch index")]
  node_llm_server["LLM server<br/>[serve.py]"]
  node_llm_client["LLM client"]
  node_gpt_generator["GPT generator<br/>[gpt3generator.py]"]
end

subgraph group_data_eval["Data and evaluation"]
  node_dataset_build["Dataset builder<br/>[build_dataset.py]"]
  node_dataset_readers["Dataset readers<br/>[dataset_readers.py]"]
  node_evaluation["QA evaluation<br/>[evaluate.py]"]
end

node_user(("Question asker"))

node_user -->|"submits question"| node_complexity_classifier
node_classifier_prep -.->|"prepares labels"| node_complexity_classifier
node_complexity_classifier -->|"selects strategy"| node_strategy
node_strategy -.->|"runs QA"| node_configurable_inference
node_configurable_inference -->|"creates search"| node_search
node_search -->|"tracks state"| node_instances
node_execution_participant -->|"invokes operations"| node_operation_executor
node_qa_participant -.->|"requests answers"| node_qa_model
node_qa_model -->|"generates text"| node_gpt_generator
node_qa_model -->|"generates text"| node_llm_client
node_llm_client -->|"requests generation"| node_llm_server
node_retriever_api -.->|"dispatches retrieval"| node_retriever
node_retriever -->|"searches index"| node_elasticsearch
node_dataset_build -.->|"produces QA data"| node_dataset_readers
node_configurable_inference -->|"loads examples"| node_dataset_readers
node_configurable_inference -.->|"evaluates answers"| node_evaluation

click node_complexity_classifier "https://github.com/starsuzi/adaptive-rag/blob/main/classifier/run_classifier.py"
click node_classifier_prep "https://github.com/starsuzi/adaptive-rag/blob/main/classifier/preprocess/preprocess_utils.py"
click node_strategy "https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/inference/ircot.py"
click node_configurable_inference "https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/inference/configurable_inference.py"
click node_search "https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/inference/model_search.py"
click node_instances "https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/inference/data_instances.py"
click node_qa_participant "https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/inference/participant_qa.py"
click node_execution_participant "https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/inference/participant_execution.py"
click node_operation_executor "https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/execution/operation_executer.py"
click node_qa_model "https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/execution/llm_qa_model.py"
click node_retriever_api "https://github.com/starsuzi/adaptive-rag/blob/main/retriever_server/serve.py"
click node_retriever "https://github.com/starsuzi/adaptive-rag/blob/main/retriever_server/elasticsearch_retriever.py"
click node_llm_server "https://github.com/starsuzi/adaptive-rag/blob/main/llm_server/serve.py"
click node_llm_client "https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/models/llm_client_generator.py"
click node_gpt_generator "https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/models/gpt3generator.py"
click node_dataset_build "https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/dataset/build_dataset.py"
click node_dataset_readers "https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/inference/dataset_readers.py"
click node_evaluation "https://github.com/starsuzi/adaptive-rag/blob/main/evaluate.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_complexity_classifier,node_classifier_prep,node_strategy toneBlue
class node_configurable_inference,node_search,node_instances,node_qa_participant,node_execution_participant,node_operation_executor,node_qa_model toneAmber
class node_retriever_api,node_retriever,node_elasticsearch,node_llm_server,node_llm_client,node_gpt_generator toneMint
class node_dataset_build,node_dataset_readers,node_evaluation toneRose
class node_user toneIndigo
```

## Components

### Complexity adaptation

- [Complexity classifier](https://github.com/starsuzi/adaptive-rag/blob/main/classifier/run_classifier.py): `classifier/run_classifier.py`
- [Classifier preprocessing](https://github.com/starsuzi/adaptive-rag/blob/main/classifier/preprocess/preprocess_utils.py): `classifier/preprocess/preprocess_utils.py`
- [QA strategies](https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/inference/ircot.py): `commaqa/inference/ircot.py`

### Question inference

- [Inference configuration](https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/inference/configurable_inference.py): `commaqa/inference/configurable_inference.py`
- [Decomposition search](https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/inference/model_search.py): `commaqa/inference/model_search.py`
- [Question state](https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/inference/data_instances.py): `commaqa/inference/data_instances.py`
- [QA participant](https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/inference/participant_qa.py): `commaqa/inference/participant_qa.py`
- [Execution participant](https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/inference/participant_execution.py): `commaqa/inference/participant_execution.py`
- [Operation executor](https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/execution/operation_executer.py): `commaqa/execution/operation_executer.py`
- [LLM QA model](https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/execution/llm_qa_model.py): `commaqa/execution/llm_qa_model.py`

### Retrieval and generation

- [Retriever service](https://github.com/starsuzi/adaptive-rag/blob/main/retriever_server/serve.py): `retriever_server/serve.py`
- [Elasticsearch retrieval](https://github.com/starsuzi/adaptive-rag/blob/main/retriever_server/elasticsearch_retriever.py): `retriever_server/elasticsearch_retriever.py`
- **Elasticsearch index**
- [LLM server](https://github.com/starsuzi/adaptive-rag/blob/main/llm_server/serve.py): `llm_server/serve.py`
- [LLM client](https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/models/llm_client_generator.py): `commaqa/models/llm_client_generator.py`
- [GPT generator](https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/models/gpt3generator.py): `commaqa/models/gpt3generator.py`

### Data and evaluation

- [Dataset builder](https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/dataset/build_dataset.py): `commaqa/dataset/build_dataset.py`
- [Dataset readers](https://github.com/starsuzi/adaptive-rag/blob/main/commaqa/inference/dataset_readers.py): `commaqa/inference/dataset_readers.py`
- [QA evaluation](https://github.com/starsuzi/adaptive-rag/blob/main/evaluate.py): `evaluate.py`

### Other components

- **Question asker**

## Connections

- Question asker → Complexity classifier: submits question (evidence: `README.md`)
- Classifier preprocessing → Complexity classifier: prepares labels
- Complexity classifier → QA strategies: selects strategy (evidence: `README.md`)
- QA strategies → Inference configuration: runs QA
- Inference configuration → Decomposition search: creates search (evidence: `commaqa/inference/configurable_inference.py`)
- Decomposition search → Question state: tracks state (evidence: `commaqa/inference/model_search.py`)
- Execution participant → Operation executor: invokes operations (evidence: `commaqa/inference/participant_execution.py`)
- QA participant → LLM QA model: requests answers
- LLM QA model → GPT generator: generates text (evidence: `commaqa/execution/llm_qa_model.py`)
- LLM QA model → LLM client: generates text (evidence: `commaqa/execution/llm_qa_model.py`)
- LLM client → LLM server: requests generation (evidence: `commaqa/models/llm_client_generator.py`)
- Retriever service → Elasticsearch retrieval: dispatches retrieval
- Elasticsearch retrieval → Elasticsearch index: searches index (evidence: `retriever_server/elasticsearch_retriever.py`)
- Dataset builder → Dataset readers: produces QA data
- Inference configuration → Dataset readers: loads examples (evidence: `commaqa/inference/configurable_inference.py`)
- Inference configuration → QA evaluation: evaluates answers