# kchimbodza/agentic-researcher architecture

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

- Interactive diagram: https://gitdiagram.com/kchimbodza/agentic-researcher
- Repository: https://github.com/kchimbodza/agentic-researcher

## Overview

Agentic Researcher is a desktop-style PDF research app: a user asks a multi-step question, agents retrieve and verify evidence, and a reviewer can approve a partial answer and sign off. Its main runtime path is exposed through the web server and LangGraph agent; retrieval is served through MCP, with a direct-call fallback. The README also documents evaluation and a fine-tuned claim checker. Some source is unsampled, so the graph omits unverified connections rather than inferring them.

Main entry points: [`app/agent.py`](https://github.com/kchimbodza/agentic-researcher/blob/main/app/agent.py) (Critic), [`app/server.py`](https://github.com/kchimbodza/agentic-researcher/blob/main/app/server.py) (Web server), [`app/tools.py`](https://github.com/kchimbodza/agentic-researcher/blob/main/app/tools.py) (Search tools), [`evals/evaluate.py`](https://github.com/kchimbodza/agentic-researcher/blob/main/evals/evaluate.py) (Evaluation runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Research workflow"]
  node_agent["Agent graph<br/>[agent.py]"]
  node_planner["Planner<br/>[agent.py]"]
  node_researcher["Researcher<br/>[agent.py]"]
  node_critic["Critic<br/>[agent.py]"]
  node_writer["Writer<br/>[agent.py]"]
  node_llm["Model router<br/>[llm.py]"]
end

subgraph group_retrieval["Documents and retrieval"]
  node_toolbox["Tool client<br/>[mcp_client.py]"]
  node_mcpserver["MCP tool server<br/>[mcp_server.py]"]
  node_tools["Search tools<br/>[tools.py]"]
  node_index[("Vector index<br/>[index.py]")]
  node_docs["PDF library<br/>[docs.py]"]
end

subgraph group_app["App and review"]
  node_browser["Browser UI<br/>[app.js]"]
  node_server["Web server<br/>[server.py]"]
  node_store[("Audit and threads<br/>[store.py]")]
end

subgraph group_quality["Evaluation and checking"]
  node_claimcheck["Claim checker<br/>[claimcheck.py]"]
  node_guardrails["Evidence guardrails<br/>[guardrails.py]"]
  node_evaluation["Evaluation runner<br/>[evaluate.py]"]
  node_baseline["RAG baseline<br/>[baseline.py]"]
  node_scoring["Answer scoring<br/>[scoring.py]"]
  node_training["Checker training<br/>[train.py]"]
end

node_user(("Questioner"))
node_models["Model providers"]
node_reviewer(("Reviewer"))

node_user -->|"asks via"| node_browser
node_browser -.->|"submits question"| node_server
node_server -->|"runs"| node_agent
node_agent -->|"plans lookups"| node_planner
node_planner -->|"dispatches lookups"| node_researcher
node_researcher -->|"searches via"| node_toolbox
node_toolbox -->|"calls tools"| node_mcpserver
node_toolbox -->|"falls back to"| node_tools
node_mcpserver -->|"serves tools"| node_tools
node_tools -->|"vector searches"| node_index
node_tools -->|"keyword searches"| node_docs
node_index -->|"indexes pages from"| node_docs
node_researcher -->|"extracts claims with"| node_llm
node_critic -->|"checks page quotes"| node_tools
node_critic -->|"reads page text"| node_docs
node_critic -->|"checks claims with"| node_guardrails
node_critic -->|"checks support with"| node_claimcheck
node_critic -->|"retries lookup"| node_researcher
node_critic -->|"passes verified evidence"| node_writer
node_writer -->|"writes with"| node_llm
node_llm -->|"routes requests"| node_models
node_server -->|"records run and audit"| node_store
node_server -->|"loads thread history"| node_store
node_reviewer -->|"approves or reviews"| node_server
node_server -.->|"streams events"| node_browser
node_evaluation -->|"evaluates"| node_agent
node_evaluation -->|"runs baseline"| node_baseline
node_evaluation -->|"scores answers"| node_scoring
node_training -.->|"produces checker model"| node_claimcheck

click node_browser "https://github.com/kchimbodza/agentic-researcher/blob/main/app/static/app.js"
click node_server "https://github.com/kchimbodza/agentic-researcher/blob/main/app/server.py"
click node_agent "https://github.com/kchimbodza/agentic-researcher/blob/main/app/agent.py"
click node_planner "https://github.com/kchimbodza/agentic-researcher/blob/main/app/agent.py"
click node_researcher "https://github.com/kchimbodza/agentic-researcher/blob/main/app/agent.py"
click node_critic "https://github.com/kchimbodza/agentic-researcher/blob/main/app/agent.py"
click node_writer "https://github.com/kchimbodza/agentic-researcher/blob/main/app/agent.py"
click node_claimcheck "https://github.com/kchimbodza/agentic-researcher/blob/main/app/claimcheck.py"
click node_guardrails "https://github.com/kchimbodza/agentic-researcher/blob/main/app/guardrails.py"
click node_toolbox "https://github.com/kchimbodza/agentic-researcher/blob/main/app/mcp_client.py"
click node_mcpserver "https://github.com/kchimbodza/agentic-researcher/blob/main/app/mcp_server.py"
click node_tools "https://github.com/kchimbodza/agentic-researcher/blob/main/app/tools.py"
click node_index "https://github.com/kchimbodza/agentic-researcher/blob/main/app/index.py"
click node_docs "https://github.com/kchimbodza/agentic-researcher/blob/main/app/docs.py"
click node_llm "https://github.com/kchimbodza/agentic-researcher/blob/main/app/llm.py"
click node_store "https://github.com/kchimbodza/agentic-researcher/blob/main/app/store.py"
click node_evaluation "https://github.com/kchimbodza/agentic-researcher/blob/main/evals/evaluate.py"
click node_baseline "https://github.com/kchimbodza/agentic-researcher/blob/main/evals/baseline.py"
click node_scoring "https://github.com/kchimbodza/agentic-researcher/blob/main/evals/scoring.py"
click node_training "https://github.com/kchimbodza/agentic-researcher/blob/main/finetune/train.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_planner,node_researcher,node_critic,node_writer,node_llm,node_reviewer toneBlue
class node_toolbox,node_mcpserver,node_tools,node_index,node_docs toneAmber
class node_browser,node_server,node_store toneMint
class node_claimcheck,node_guardrails,node_evaluation,node_baseline,node_scoring,node_training toneRose
class node_user,node_models toneIndigo
```

## Components

### Research workflow

- [Agent graph](https://github.com/kchimbodza/agentic-researcher/blob/main/app/agent.py): `app/agent.py`
- [Planner](https://github.com/kchimbodza/agentic-researcher/blob/main/app/agent.py): `app/agent.py`
- [Researcher](https://github.com/kchimbodza/agentic-researcher/blob/main/app/agent.py): `app/agent.py`
- [Critic](https://github.com/kchimbodza/agentic-researcher/blob/main/app/agent.py): `app/agent.py`
- [Writer](https://github.com/kchimbodza/agentic-researcher/blob/main/app/agent.py): `app/agent.py`
- [Model router](https://github.com/kchimbodza/agentic-researcher/blob/main/app/llm.py): `app/llm.py`

### Documents and retrieval

- [Tool client](https://github.com/kchimbodza/agentic-researcher/blob/main/app/mcp_client.py): `app/mcp_client.py`
- [MCP tool server](https://github.com/kchimbodza/agentic-researcher/blob/main/app/mcp_server.py): `app/mcp_server.py`
- [Search tools](https://github.com/kchimbodza/agentic-researcher/blob/main/app/tools.py): `app/tools.py`
- [Vector index](https://github.com/kchimbodza/agentic-researcher/blob/main/app/index.py): `app/index.py`
- [PDF library](https://github.com/kchimbodza/agentic-researcher/blob/main/app/docs.py): `app/docs.py`

### App and review

- [Browser UI](https://github.com/kchimbodza/agentic-researcher/blob/main/app/static/app.js): `app/static/app.js`
- [Web server](https://github.com/kchimbodza/agentic-researcher/blob/main/app/server.py): `app/server.py`
- [Audit and threads](https://github.com/kchimbodza/agentic-researcher/blob/main/app/store.py): `app/store.py`

### Evaluation and checking

- [Claim checker](https://github.com/kchimbodza/agentic-researcher/blob/main/app/claimcheck.py): `app/claimcheck.py`
- [Evidence guardrails](https://github.com/kchimbodza/agentic-researcher/blob/main/app/guardrails.py): `app/guardrails.py`
- [Evaluation runner](https://github.com/kchimbodza/agentic-researcher/blob/main/evals/evaluate.py): `evals/evaluate.py`
- [RAG baseline](https://github.com/kchimbodza/agentic-researcher/blob/main/evals/baseline.py): `evals/baseline.py`
- [Answer scoring](https://github.com/kchimbodza/agentic-researcher/blob/main/evals/scoring.py): `evals/scoring.py`
- [Checker training](https://github.com/kchimbodza/agentic-researcher/blob/main/finetune/train.py): `finetune/train.py`

### Other components

- **Questioner**
- **Model providers**
- **Reviewer**

## Connections

- Questioner → Browser UI: asks via (evidence: `README.md`)
- Browser UI → Web server: submits question
- Web server → Agent graph: runs (evidence: `app/server.py`)
- Agent graph → Planner: plans lookups (evidence: `README.md`)
- Planner → Researcher: dispatches lookups (evidence: `README.md`)
- Researcher → Tool client: searches via (evidence: `README.md`)
- Tool client → MCP tool server: calls tools (evidence: `app/mcp_client.py`)
- Tool client → Search tools: falls back to (evidence: `app/mcp_client.py`)
- MCP tool server → Search tools: serves tools (evidence: `app/mcp_server.py`)
- Search tools → Vector index: vector searches (evidence: `app/tools.py`)
- Search tools → PDF library: keyword searches (evidence: `app/tools.py`)
- Vector index → PDF library: indexes pages from (evidence: `app/index.py`)
- Researcher → Model router: extracts claims with (evidence: `README.md`)
- Critic → Search tools: checks page quotes (evidence: `app/agent.py`)
- Critic → PDF library: reads page text (evidence: `app/agent.py`)
- Critic → Evidence guardrails: checks claims with (evidence: `app/agent.py`)
- Critic → Claim checker: checks support with (evidence: `app/agent.py`)
- Critic → Researcher: retries lookup (evidence: `README.md`)
- Critic → Writer: passes verified evidence (evidence: `README.md`)
- Writer → Model router: writes with (evidence: `README.md`)
- Model router → Model providers: routes requests (evidence: `app/llm.py`)
- Web server → Audit and threads: records run and audit (evidence: `app/server.py`)
- Web server → Audit and threads: loads thread history (evidence: `app/server.py`)
- Reviewer → Web server: approves or reviews (evidence: `app/server.py`)
- Web server → Browser UI: streams events
- Evaluation runner → Agent graph: evaluates (evidence: `evals/evaluate.py`)
- Evaluation runner → RAG baseline: runs baseline (evidence: `evals/evaluate.py`)
- Evaluation runner → Answer scoring: scores answers (evidence: `evals/evaluate.py`)
- Checker training → Claim checker: produces checker model
