# nirmalkumar31/agentic-research-engine architecture

> Architecture diagram of the GitHub repository nirmalkumar31/agentic-research-engine, 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/nirmalkumar31/agentic-research-engine
- Repository: https://github.com/nirmalkumar31/agentic-research-engine

## Overview

Agentic Research Engine turns a question into a bounded, evidence-backed report. Its principal workflow builds an answer contract, plans and searches across question dimensions, retrieves and extracts source quotes, assesses coverage with budgeted follow-ups, then verifies atomic claims for support and relevance before publication. The CLI and web interface expose runs and reports; the web app also supports deterministic recordings. Evaluation is a separate capability. Several implementation files were not sampled, so documented workflow links are cited to the README; uncertain internal calls are omitted.

Main entry points: [`src/agentic_research/graph/workflow.py`](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/graph/workflow.py) (Research graph), [`src/agentic_research/runner.py`](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/runner.py) (Run orchestration), [`src/agentic_research/graph/nodes/research.py`](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/graph/nodes/research.py) (Search and extraction), [`src/agentic_research/graph/nodes/reporting.py`](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/graph/nodes/reporting.py) (Synthesis and report)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI<br/>[main.py]"]
  node_web["Web API<br/>[api.py]"]
  node_frontend["Web interface<br/>[App.tsx]"]
  node_report["Published report<br/>[report.py]"]
end

subgraph group_flow["Research workflow"]
  node_runner["Run orchestration<br/>[runner.py]"]
  node_workflow["Research graph<br/>[workflow.py]"]
  node_state["Run state<br/>[state.py]"]
  node_contract["Answer contract<br/>[answer_contract.py]"]
  node_planning["Question planning<br/>[planning.py]"]
  node_research_nodes["Search and extraction<br/>[research.py]"]
  node_coverage["Coverage assessment<br/>[answer_coverage.py]"]
  node_reporting["Synthesis and report<br/>[reporting.py]"]
end

subgraph group_evidence["Evidence and verification"]
  node_fetch["Source retrieval<br/>[fetcher.py]"]
  node_store[("Evidence store<br/>[store.py]")]
  node_citation["Citation verification<br/>[verifier.py]"]
  node_relevance["Relevance checks<br/>[relevance.py]"]
end

subgraph group_runtime["Runtime services"]
  node_search["Search providers<br/>[service.py]"]
  node_models["Model routing<br/>[router.py]"]
  node_config["Configuration and budgets<br/>[config.py]"]
  node_search_service["Search service<br/>[service.py]"]
end

subgraph group_quality["Replay and evaluation"]
  node_recordings["Recorded runs<br/>[recordings.py]"]
  node_evaluation["Evaluation<br/>[ab.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs question"| node_cli
node_cli -->|"starts run"| node_runner
node_researcher -->|"asks question"| node_frontend
node_frontend -->|"streams run"| node_web
node_web -->|"starts live run"| node_runner
node_frontend -->|"requests recordings"| node_web
node_web -->|"loads replay"| node_recordings
node_runner -->|"executes graph"| node_workflow
node_workflow -->|"updates state"| node_state
node_workflow -->|"plans question"| node_planning
node_planning -->|"builds contract"| node_contract
node_workflow -->|"dispatches research"| node_research_nodes
node_research_nodes -->|"runs queries"| node_search
node_research_nodes -->|"fetches sources"| node_fetch
node_research_nodes -->|"registers evidence"| node_store
node_workflow -->|"assesses gaps"| node_coverage
node_coverage -->|"routes follow-ups"| node_workflow
node_workflow -->|"synthesizes claims"| node_reporting
node_reporting -->|"checks support"| node_citation
node_reporting -->|"checks relevance"| node_relevance
node_reporting -->|"judges answer fit"| node_contract
node_workflow -->|"requests model roles"| node_models
node_runner -->|"renders result"| node_report
node_runner -->|"uses run settings"| node_config
node_evaluation -->|"runs comparisons"| node_runner
node_evaluation -->|"configures search"| node_search
node_evaluation -->|"configures models"| node_models

click node_cli "https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/cli/main.py"
click node_web "https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/web/api.py"
click node_frontend "https://github.com/nirmalkumar31/agentic-research-engine/blob/main/web/src/App.tsx"
click node_runner "https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/runner.py"
click node_workflow "https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/graph/workflow.py"
click node_state "https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/graph/state.py"
click node_contract "https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/answer_contract.py"
click node_planning "https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/graph/nodes/planning.py"
click node_research_nodes "https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/graph/nodes/research.py"
click node_search "https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/search/service.py"
click node_fetch "https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/retrieval/fetcher.py"
click node_store "https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/evidence/store.py"
click node_coverage "https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/answer_coverage.py"
click node_reporting "https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/graph/nodes/reporting.py"
click node_citation "https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/citations/verifier.py"
click node_relevance "https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/citations/relevance.py"
click node_models "https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/llm/router.py"
click node_config "https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/config.py"
click node_recordings "https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/web/recordings.py"
click node_evaluation "https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/evaluation/ab.py"
click node_report "https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/report.py"
click node_search_service "https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/search/service.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_web,node_frontend,node_report toneBlue
class node_runner,node_workflow,node_state,node_contract,node_planning,node_research_nodes,node_coverage,node_reporting toneAmber
class node_fetch,node_store,node_citation,node_relevance toneMint
class node_search,node_models,node_config,node_search_service toneRose
class node_recordings,node_evaluation,node_researcher toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/cli/main.py): `src/agentic_research/cli/main.py`
- [Web API](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/web/api.py): `src/agentic_research/web/api.py`
- [Web interface](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Published report](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/report.py): `src/agentic_research/report.py`

### Research workflow

- [Run orchestration](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/runner.py): `src/agentic_research/runner.py`
- [Research graph](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/graph/workflow.py): `src/agentic_research/graph/workflow.py`
- [Run state](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/graph/state.py): `src/agentic_research/graph/state.py`
- [Answer contract](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/answer_contract.py): `src/agentic_research/answer_contract.py`
- [Question planning](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/graph/nodes/planning.py): `src/agentic_research/graph/nodes/planning.py`
- [Search and extraction](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/graph/nodes/research.py): `src/agentic_research/graph/nodes/research.py`
- [Coverage assessment](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/answer_coverage.py): `src/agentic_research/answer_coverage.py`
- [Synthesis and report](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/graph/nodes/reporting.py): `src/agentic_research/graph/nodes/reporting.py`

### Evidence and verification

- [Source retrieval](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/retrieval/fetcher.py): `src/agentic_research/retrieval/fetcher.py`
- [Evidence store](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/evidence/store.py): `src/agentic_research/evidence/store.py`
- [Citation verification](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/citations/verifier.py): `src/agentic_research/citations/verifier.py`
- [Relevance checks](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/citations/relevance.py): `src/agentic_research/citations/relevance.py`

### Runtime services

- [Search providers](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/search/service.py): `src/agentic_research/search/service.py`
- [Model routing](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/llm/router.py): `src/agentic_research/llm/router.py`
- [Configuration and budgets](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/config.py): `src/agentic_research/config.py`
- [Search service](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/search/service.py): `src/agentic_research/search/service.py`

### Replay and evaluation

- [Recorded runs](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/web/recordings.py): `src/agentic_research/web/recordings.py`
- [Evaluation](https://github.com/nirmalkumar31/agentic-research-engine/blob/main/src/agentic_research/evaluation/ab.py): `src/agentic_research/evaluation/ab.py`

### Other components

- **Researcher**

## Connections

- Researcher → CLI: runs question (evidence: `README.md`)
- CLI → Run orchestration: starts run (evidence: `src/agentic_research/cli/main.py`)
- Researcher → Web interface: asks question (evidence: `README.md`)
- Web interface → Web API: streams run (evidence: `web/src/App.tsx`)
- Web API → Run orchestration: starts live run (evidence: `src/agentic_research/web/api.py`)
- Web interface → Web API: requests recordings (evidence: `web/src/App.tsx`)
- Web API → Recorded runs: loads replay (evidence: `src/agentic_research/web/api.py`)
- Run orchestration → Research graph: executes graph (evidence: `src/agentic_research/runner.py`)
- Research graph → Run state: updates state
- Research graph → Question planning: plans question (evidence: `README.md`)
- Question planning → Answer contract: builds contract
- Research graph → Search and extraction: dispatches research (evidence: `README.md`)
- Search and extraction → Search providers: runs queries (evidence: `src/agentic_research/search/service.py`)
- Search and extraction → Source retrieval: fetches sources (evidence: `README.md`)
- Search and extraction → Evidence store: registers evidence (evidence: `src/agentic_research/graph/nodes/research.py`)
- Research graph → Coverage assessment: assesses gaps (evidence: `README.md`)
- Coverage assessment → Research graph: routes follow-ups (evidence: `README.md`)
- Research graph → Synthesis and report: synthesizes claims (evidence: `README.md`)
- Synthesis and report → Citation verification: checks support (evidence: `README.md`)
- Synthesis and report → Relevance checks: checks relevance (evidence: `README.md`)
- Synthesis and report → Answer contract: judges answer fit
- Research graph → Model routing: requests model roles (evidence: `src/agentic_research/llm/router.py`)
- Run orchestration → Published report: renders result (evidence: `src/agentic_research/runner.py`)
- Run orchestration → Configuration and budgets: uses run settings (evidence: `src/agentic_research/runner.py`)
- Evaluation → Run orchestration: runs comparisons (evidence: `src/agentic_research/evaluation/ab.py`)
- Evaluation → Search providers: configures search (evidence: `src/agentic_research/evaluation/ab.py`)
- Evaluation → Model routing: configures models (evidence: `src/agentic_research/evaluation/ab.py`)
