# scybl/agentic-rag architecture

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

- Interactive diagram: https://gitdiagram.com/scybl/agentic-rag
- Repository: https://github.com/scybl/agentic-rag

## Overview

Agentic RAG is a local, single-user command-line research application that combines a private knowledge index, a private news API, and public web search. A question is planned across sources, retrieved and screened, then supported by reusable reading results and evaluated evidence; the system generates, checks, and delivers an answer, with bounded follow-up search and resumable research. News planning and API retrieval are distinct stages. The graph follows README-described workflow and indexed references; unsampled implementation details are not assumed.

Main entry points: [`src/agentic_rag/graph/build.py`](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/graph/build.py) (Workflow graph), [`src/agentic_rag/rag/retrieval.py`](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/rag/retrieval.py) (Source retrieval), [`src/agentic_rag/llm/chains.py`](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/llm/chains.py) (LLM chains), [`src/agentic_rag/cli.py`](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/cli.py) (CLI interaction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and orchestration"]
  node_cli["CLI interaction<br/>[cli.py]"]
  node_graph["Workflow graph<br/>[build.py]"]
  node_state["Run state<br/>[state.py]"]
  node_delivery["Terminal results<br/>[console.py]"]
end

subgraph group_research["Research workflow"]
  node_planning["Source planning<br/>[planning.py]"]
  node_evidence["Evidence assessment<br/>[evidence.py]"]
  node_reading["Document reading<br/>[reading.py]"]
  node_specialists["Topic specialists<br/>[specialists.py]"]
  node_generation["Answer generation<br/>[generation.py]"]
  node_reflection["Answer review<br/>[reflection.py]"]
end

subgraph group_sources["Sources and retrieval"]
  node_retrieval["Source retrieval<br/>[retrieval.py]"]
  node_knowledge[("Knowledge index<br/>[knowledge.py]")]
  node_newsplan["News query plan<br/>[plan.py]"]
  node_newsretrieval["News retrieval<br/>[retrieval.py]"]
  node_newsapi["News API client<br/>[client.py]"]
  node_web["Public web search<br/>[web_search.py]"]
  node_ingestion["Knowledge ingestion<br/>[ingestion.py]"]
end

subgraph group_memory["Memory and persistence"]
  node_store[("Research store<br/>[store.py]")]
  node_conversation[("Conversation memory<br/>[conversation.py]")]
  node_researchcontext["Research lifecycle<br/>[context.py]"]
end

subgraph group_runtime["Model and operations"]
  node_config["Runtime settings<br/>[config.py]"]
  node_llm["LLM chains<br/>[chains.py]"]
  node_budget["Research budget<br/>[budget.py]"]
  node_capacity["Execution capacity<br/>[capacity.py]"]
  node_telemetry["Usage telemetry<br/>[usage.py]"]
  node_exporters["Trace export<br/>[exporters.py]"]
  node_toolcontracts["Tool contracts<br/>[contracts.py]"]
  node_toolexecution["Tool execution<br/>[execution.py]"]
  node_guardrails["Tool guardrails<br/>[guardrails.py]"]
end

node_user(("Researcher"))
node_privateapi["Private news API"]
node_ollama["Ollama model"]

node_user -->|"asks"| node_cli
node_cli -.->|"starts research"| node_graph
node_graph -->|"plans sources"| node_planning
node_graph -->|"retrieves evidence"| node_retrieval
node_retrieval -->|"queries news"| node_newsretrieval
node_retrieval -->|"searches index"| node_knowledge
node_retrieval -->|"searches web"| node_web
node_newsretrieval -->|"uses query plan"| node_newsplan
node_newsretrieval -->|"fetches candidates"| node_newsapi
node_newsapi -->|"requests news"| node_privateapi
node_retrieval -->|"screens results"| node_evidence
node_evidence -->|"selects for reading"| node_reading
node_reading -->|"supports analysis"| node_specialists
node_graph -->|"generates answer"| node_generation
node_graph -->|"checks answer"| node_reflection
node_graph -.->|"tracks run"| node_state
node_graph -->|"saves research"| node_store
node_cli -->|"continues turns"| node_conversation
node_ingestion -->|"updates index"| node_knowledge
node_graph -.->|"initializes run"| node_researchcontext
node_researchcontext -->|"opens store"| node_store
node_llm -->|"calls model"| node_ollama
node_llm -->|"reserves calls"| node_budget
node_newsapi -->|"checks task limits"| node_capacity
node_graph -.->|"records usage"| node_telemetry
node_telemetry -->|"exports traces"| node_exporters
node_llm -->|"uses tool context"| node_toolcontracts
node_llm -->|"executes tools"| node_toolexecution
node_toolexecution -.->|"applies rules"| node_guardrails
node_graph -->|"delivers results"| node_delivery
node_delivery -->|"presents answer"| node_user

click node_cli "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/cli.py"
click node_graph "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/graph/build.py"
click node_state "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/graph/state.py"
click node_planning "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/agents/planning.py"
click node_retrieval "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/rag/retrieval.py"
click node_knowledge "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/rag/knowledge.py"
click node_newsplan "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/sources/news/plan.py"
click node_newsretrieval "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/sources/news/retrieval.py"
click node_newsapi "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/sources/news/client.py"
click node_web "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/tools/web_search.py"
click node_evidence "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/agents/evidence.py"
click node_reading "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/agents/reading.py"
click node_specialists "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/agents/specialists.py"
click node_generation "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/rag/generation.py"
click node_reflection "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/agents/reflection.py"
click node_store "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/memory/store.py"
click node_conversation "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/memory/conversation.py"
click node_ingestion "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/ingestion.py"
click node_config "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/config.py"
click node_llm "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/llm/chains.py"
click node_budget "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/runtime/budget.py"
click node_capacity "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/runtime/capacity.py"
click node_researchcontext "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/research/context.py"
click node_telemetry "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/telemetry/usage.py"
click node_exporters "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/telemetry/exporters.py"
click node_toolcontracts "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/tools/contracts.py"
click node_toolexecution "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/tools/execution.py"
click node_guardrails "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/tools/guardrails.py"
click node_delivery "https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/presentation/console.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_cli,node_graph,node_state,node_delivery toneBlue
class node_planning,node_evidence,node_reading,node_specialists,node_generation,node_reflection toneAmber
class node_retrieval,node_knowledge,node_newsplan,node_newsretrieval,node_newsapi,node_web,node_ingestion,node_privateapi toneMint
class node_store,node_conversation,node_researchcontext toneRose
class node_config,node_llm,node_budget,node_capacity,node_telemetry,node_exporters,node_toolcontracts,node_toolexecution,node_guardrails,node_user,node_ollama toneIndigo
```

## Components

### CLI and orchestration

- [CLI interaction](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/cli.py): `src/agentic_rag/cli.py`
- [Workflow graph](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/graph/build.py): `src/agentic_rag/graph/build.py`
- [Run state](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/graph/state.py): `src/agentic_rag/graph/state.py`
- [Terminal results](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/presentation/console.py): `src/agentic_rag/presentation/console.py`

### Research workflow

- [Source planning](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/agents/planning.py): `src/agentic_rag/agents/planning.py`
- [Evidence assessment](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/agents/evidence.py): `src/agentic_rag/agents/evidence.py`
- [Document reading](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/agents/reading.py): `src/agentic_rag/agents/reading.py`
- [Topic specialists](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/agents/specialists.py): `src/agentic_rag/agents/specialists.py`
- [Answer generation](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/rag/generation.py): `src/agentic_rag/rag/generation.py`
- [Answer review](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/agents/reflection.py): `src/agentic_rag/agents/reflection.py`

### Sources and retrieval

- [Source retrieval](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/rag/retrieval.py): `src/agentic_rag/rag/retrieval.py`
- [Knowledge index](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/rag/knowledge.py): `src/agentic_rag/rag/knowledge.py`
- [News query plan](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/sources/news/plan.py): `src/agentic_rag/sources/news/plan.py`
- [News retrieval](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/sources/news/retrieval.py): `src/agentic_rag/sources/news/retrieval.py`
- [News API client](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/sources/news/client.py): `src/agentic_rag/sources/news/client.py`
- [Public web search](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/tools/web_search.py): `src/agentic_rag/tools/web_search.py`
- [Knowledge ingestion](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/ingestion.py): `src/agentic_rag/ingestion.py`

### Memory and persistence

- [Research store](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/memory/store.py): `src/agentic_rag/memory/store.py`
- [Conversation memory](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/memory/conversation.py): `src/agentic_rag/memory/conversation.py`
- [Research lifecycle](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/research/context.py): `src/agentic_rag/research/context.py`

### Model and operations

- [Runtime settings](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/config.py): `src/agentic_rag/config.py`
- [LLM chains](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/llm/chains.py): `src/agentic_rag/llm/chains.py`
- [Research budget](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/runtime/budget.py): `src/agentic_rag/runtime/budget.py`
- [Execution capacity](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/runtime/capacity.py): `src/agentic_rag/runtime/capacity.py`
- [Usage telemetry](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/telemetry/usage.py): `src/agentic_rag/telemetry/usage.py`
- [Trace export](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/telemetry/exporters.py): `src/agentic_rag/telemetry/exporters.py`
- [Tool contracts](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/tools/contracts.py): `src/agentic_rag/tools/contracts.py`
- [Tool execution](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/tools/execution.py): `src/agentic_rag/tools/execution.py`
- [Tool guardrails](https://github.com/scybl/agentic-rag/blob/master/src/agentic_rag/tools/guardrails.py): `src/agentic_rag/tools/guardrails.py`

### Other components

- **Researcher**
- **Private news API**
- **Ollama model**

## Connections

- Researcher → CLI interaction: asks (evidence: `README.md`)
- CLI interaction → Workflow graph: starts research
- Workflow graph → Source planning: plans sources (evidence: `README.md`)
- Workflow graph → Source retrieval: retrieves evidence (evidence: `README.md`)
- Source retrieval → News retrieval: queries news (evidence: `src/agentic_rag/rag/retrieval.py`)
- Source retrieval → Knowledge index: searches index (evidence: `README.md`)
- Source retrieval → Public web search: searches web (evidence: `src/agentic_rag/rag/retrieval.py`)
- News retrieval → News query plan: uses query plan (evidence: `src/agentic_rag/sources/news/retrieval.py`)
- News retrieval → News API client: fetches candidates (evidence: `src/agentic_rag/sources/news/retrieval.py`)
- News API client → Private news API: requests news (evidence: `src/agentic_rag/sources/news/client.py`)
- Source retrieval → Evidence assessment: screens results (evidence: `README.md`)
- Evidence assessment → Document reading: selects for reading (evidence: `README.md`)
- Document reading → Topic specialists: supports analysis (evidence: `README.md`)
- Workflow graph → Answer generation: generates answer (evidence: `README.md`)
- Workflow graph → Answer review: checks answer (evidence: `README.md`)
- Workflow graph → Run state: tracks run
- Workflow graph → Research store: saves research (evidence: `README.md`)
- CLI interaction → Conversation memory: continues turns (evidence: `README.md`)
- Knowledge ingestion → Knowledge index: updates index (evidence: `src/agentic_rag/ingestion.py`)
- Workflow graph → Research lifecycle: initializes run
- Research lifecycle → Research store: opens store (evidence: `src/agentic_rag/research/context.py`)
- LLM chains → Ollama model: calls model (evidence: `src/agentic_rag/llm/chains.py`)
- LLM chains → Research budget: reserves calls (evidence: `src/agentic_rag/llm/chains.py`)
- News API client → Execution capacity: checks task limits (evidence: `src/agentic_rag/sources/news/client.py`)
- Workflow graph → Usage telemetry: records usage
- Usage telemetry → Trace export: exports traces (evidence: `src/agentic_rag/telemetry/exporters.py`)
- LLM chains → Tool contracts: uses tool context (evidence: `src/agentic_rag/llm/chains.py`)
- LLM chains → Tool execution: executes tools (evidence: `src/agentic_rag/llm/chains.py`)
- Tool execution → Tool guardrails: applies rules
- Workflow graph → Terminal results: delivers results (evidence: `README.md`)
- Terminal results → Researcher: presents answer (evidence: `README.md`)