# rauaan/rag-agent architecture

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

- Interactive diagram: https://gitdiagram.com/rauaan/rag-agent
- Repository: https://github.com/rauaan/rag-agent

## Overview

This repository implements a question-answering assistant for Kazakhstan’s Sovereign Wealth Fund law, with optional live web research. The workflow routes a user query, gathers local and/or web documents, splits and reranks them in a temporary vector store, then generates a source-grounded answer. A separate indexing entry point is present, but its implementation was not excerpted; its connections are therefore omitted. The graph follows the shown calls and documented prompt behavior.

Main entry points: [`agent.py`](https://github.com/rauaan/rag-agent/blob/main/agent.py) (Answer workflow), [`router.py`](https://github.com/rauaan/rag-agent/blob/main/router.py) (Tool router), [`tools/local_search.py`](https://github.com/rauaan/rag-agent/blob/main/tools/local_search.py) (Local search), [`tools/web_search.py`](https://github.com/rauaan/rag-agent/blob/main/tools/web_search.py) (Web search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Query orchestration"]
  node_agent["Answer workflow<br/>[agent.py]"]
  node_router["Tool router<br/>[router.py]"]
end

subgraph group_retrieval["Document retrieval"]
  node_local_tool["Local search<br/>[local_search.py]"]
  node_web_tool["Web search<br/>[web_search.py]"]
  node_web_search_service["Web search service"]
  node_page_converter["Page converter"]
  node_base_tool["Tool interface<br/>[base.py]"]
  node_persistent_store[("Persistent store<br/>[vectorstore.py]")]
  node_indexing_entry["Indexing entry point<br/>[index.py]"]
end

subgraph group_rag["RAG processing"]
  node_splitter["Document splitter<br/>[splitter.py]"]
  node_temporary_store[("Temporary store<br/>[vectorstore.py]")]
  node_context_builder["Context builder<br/>[utils.py]"]
end

subgraph group_models["Models and prompts"]
  node_embedding_model["Embedding model<br/>[embeddings.py]"]
  node_llm["Language model<br/>[llm.py]"]
  node_router_prompt["Routing prompt<br/>[router_prompt.py]"]
  node_answer_prompt["Answer prompt<br/>[system_prompt.py]"]
  node_config["Runtime settings<br/>[config.py]"]
end

node_user(("Question asker"))

node_user -->|"asks"| node_agent
node_agent -->|"routes query"| node_router
node_router -->|"formats query"| node_router_prompt
node_router -->|"classifies query"| node_llm
node_agent -->|"requests local search"| node_local_tool
node_agent -->|"requests web search"| node_web_tool
node_local_tool -->|"retrieves documents"| node_persistent_store
node_web_tool -->|"searches web"| node_web_search_service
node_web_tool -->|"converts pages"| node_page_converter
node_agent -->|"splits documents"| node_splitter
node_agent -->|"indexes chunks"| node_temporary_store
node_agent -->|"retrieves matches"| node_temporary_store
node_temporary_store -->|"embeds documents"| node_embedding_model
node_persistent_store -->|"embeds documents"| node_embedding_model
node_agent -->|"builds context"| node_context_builder
node_agent -->|"formats answer request"| node_answer_prompt
node_agent -->|"generates answer"| node_llm
node_llm -->|"reads model setting"| node_config
node_router -.-> node_base_tool
node_local_tool -.-> node_base_tool
node_agent -->|"returns answer"| node_user

click node_agent "https://github.com/rauaan/rag-agent/blob/main/agent.py"
click node_router "https://github.com/rauaan/rag-agent/blob/main/router.py"
click node_local_tool "https://github.com/rauaan/rag-agent/blob/main/tools/local_search.py"
click node_web_tool "https://github.com/rauaan/rag-agent/blob/main/tools/web_search.py"
click node_base_tool "https://github.com/rauaan/rag-agent/blob/main/tools/base.py"
click node_persistent_store "https://github.com/rauaan/rag-agent/blob/main/rag/vectorstore.py"
click node_indexing_entry "https://github.com/rauaan/rag-agent/blob/main/index.py"
click node_splitter "https://github.com/rauaan/rag-agent/blob/main/rag/splitter.py"
click node_temporary_store "https://github.com/rauaan/rag-agent/blob/main/rag/vectorstore.py"
click node_context_builder "https://github.com/rauaan/rag-agent/blob/main/utils.py"
click node_embedding_model "https://github.com/rauaan/rag-agent/blob/main/rag/embeddings.py"
click node_llm "https://github.com/rauaan/rag-agent/blob/main/llm.py"
click node_router_prompt "https://github.com/rauaan/rag-agent/blob/main/prompts/router_prompt.py"
click node_answer_prompt "https://github.com/rauaan/rag-agent/blob/main/prompts/system_prompt.py"
click node_config "https://github.com/rauaan/rag-agent/blob/main/config.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_agent,node_router toneBlue
class node_local_tool,node_web_tool,node_web_search_service,node_page_converter,node_base_tool,node_persistent_store,node_indexing_entry toneAmber
class node_splitter,node_temporary_store,node_context_builder toneMint
class node_embedding_model,node_llm,node_router_prompt,node_answer_prompt,node_config toneRose
class node_user toneIndigo
```

## Components

### Query orchestration

- [Answer workflow](https://github.com/rauaan/rag-agent/blob/main/agent.py): `agent.py`
- [Tool router](https://github.com/rauaan/rag-agent/blob/main/router.py): `router.py`

### Document retrieval

- [Local search](https://github.com/rauaan/rag-agent/blob/main/tools/local_search.py): `tools/local_search.py`
- [Web search](https://github.com/rauaan/rag-agent/blob/main/tools/web_search.py): `tools/web_search.py`
- **Web search service**
- **Page converter**
- [Tool interface](https://github.com/rauaan/rag-agent/blob/main/tools/base.py): `tools/base.py`
- [Persistent store](https://github.com/rauaan/rag-agent/blob/main/rag/vectorstore.py): `rag/vectorstore.py`
- [Indexing entry point](https://github.com/rauaan/rag-agent/blob/main/index.py): `index.py`

### RAG processing

- [Document splitter](https://github.com/rauaan/rag-agent/blob/main/rag/splitter.py): `rag/splitter.py`
- [Temporary store](https://github.com/rauaan/rag-agent/blob/main/rag/vectorstore.py): `rag/vectorstore.py`
- [Context builder](https://github.com/rauaan/rag-agent/blob/main/utils.py): `utils.py`

### Models and prompts

- [Embedding model](https://github.com/rauaan/rag-agent/blob/main/rag/embeddings.py): `rag/embeddings.py`
- [Language model](https://github.com/rauaan/rag-agent/blob/main/llm.py): `llm.py`
- [Routing prompt](https://github.com/rauaan/rag-agent/blob/main/prompts/router_prompt.py): `prompts/router_prompt.py`
- [Answer prompt](https://github.com/rauaan/rag-agent/blob/main/prompts/system_prompt.py): `prompts/system_prompt.py`
- [Runtime settings](https://github.com/rauaan/rag-agent/blob/main/config.py): `config.py`

### Other components

- **Question asker**

## Connections

- Question asker → Answer workflow: asks (evidence: `agent.py`)
- Answer workflow → Tool router: routes query (evidence: `agent.py`)
- Tool router → Routing prompt: formats query (evidence: `router.py`)
- Tool router → Language model: classifies query (evidence: `router.py`)
- Answer workflow → Local search: requests local search (evidence: `agent.py`)
- Answer workflow → Web search: requests web search (evidence: `agent.py`)
- Local search → Persistent store: retrieves documents (evidence: `tools/local_search.py`)
- Web search → Web search service: searches web (evidence: `tools/web_search.py`)
- Web search → Page converter: converts pages (evidence: `tools/web_search.py`)
- Answer workflow → Document splitter: splits documents (evidence: `agent.py`)
- Answer workflow → Temporary store: indexes chunks (evidence: `agent.py`)
- Answer workflow → Temporary store: retrieves matches (evidence: `agent.py`)
- Temporary store → Embedding model: embeds documents (evidence: `rag/vectorstore.py`)
- Persistent store → Embedding model: embeds documents (evidence: `rag/vectorstore.py`)
- Answer workflow → Context builder: builds context (evidence: `agent.py`)
- Answer workflow → Answer prompt: formats answer request (evidence: `agent.py`)
- Answer workflow → Language model: generates answer (evidence: `agent.py`)
- Language model → Runtime settings: reads model setting (evidence: `llm.py`)
- Tool router → Tool interface
- Local search → Tool interface (evidence: `tools/local_search.py`)
- Answer workflow → Question asker: returns answer (evidence: `agent.py`)
