# daimx1214/evidence-first-research-agent architecture

> Architecture diagram of the GitHub repository daimx1214/evidence-first-research-agent, 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/daimx1214/evidence-first-research-agent
- Repository: https://github.com/daimx1214/evidence-first-research-agent

## Overview

Evidence-First Research Agent turns a question into a cited research brief: it plans searches, gathers and ranks sources, optionally extracts fuller text, refines once when evidence is sparse, then synthesizes and verifies claims. Runs with insufficient evidence stop without synthesis. Results include confidence, citations, and a trace, with optional HTML/Markdown reports. The README documents the full workflow; the sampled agent excerpt confirms key service calls and verification behavior. Internal pipeline links rely on README documentation where their implementation was not excerpted.

Main entry points: [`src/agent.py`](https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py) (Research runner), [`src/report.py`](https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/report.py) (Report generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Research workflow"]
  node_agent["Research runner<br/>[agent.py]"]
  node_planner["Query planning<br/>[agent.py]"]
  node_refinement["Query refinement<br/>[agent.py]"]
  node_evidence_gate["Evidence threshold<br/>[agent.py]"]
  node_nebius{{"Nebius Token Factory"}}
end

subgraph group_evidence["Evidence gathering"]
  node_search["Web search<br/>[agent.py]"]
  node_tavily{{"Tavily"}}
  node_selection["Evidence selection<br/>[agent.py]"]
  node_credibility["Credibility scoring<br/>[agent.py]"]
  node_extraction["Page extraction<br/>[agent.py]"]
end

subgraph group_reasoning["Synthesis and verification"]
  node_synthesis["Cited synthesis<br/>[agent.py]"]
  node_verification["Claim verification<br/>[agent.py]"]
  node_citation_check["Citation check<br/>[agent.py]"]
  node_confidence["Confidence score<br/>[agent.py]"]
end

subgraph group_outputs["Results and reports"]
  node_answer["Answer and trace<br/>[agent.py]"]
  node_report["Report generator<br/>[report.py]"]
  node_report_files["HTML / Markdown"]
end

node_researcher(("Researcher"))

node_researcher -->|"asks question"| node_agent
node_agent -->|"plans queries"| node_planner
node_planner -->|"requests inference"| node_nebius
node_agent -->|"searches queries"| node_search
node_search -->|"requests results"| node_tavily
node_agent -->|"selects results"| node_selection
node_selection -->|"scores publishers"| node_credibility
node_agent -->|"extracts thin sources"| node_extraction
node_extraction -->|"requests page text"| node_tavily
node_agent -->|"checks source count"| node_evidence_gate
node_evidence_gate -->|"refines once"| node_refinement
node_refinement -->|"requests inference"| node_nebius
node_agent -->|"synthesizes evidence"| node_synthesis
node_synthesis -->|"requests inference"| node_nebius
node_agent -->|"checks claims"| node_verification
node_verification -->|"requests inference"| node_nebius
node_agent -->|"checks citations"| node_citation_check
node_agent -->|"scores confidence"| node_confidence
node_agent -->|"assembles result"| node_answer
node_agent -->|"renders report"| node_report
node_report -->|"produces reports"| node_report_files
node_agent -->|"refuses if insufficient"| node_answer

click node_agent "https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py"
click node_planner "https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py"
click node_refinement "https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py"
click node_evidence_gate "https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py"
click node_search "https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py"
click node_selection "https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py"
click node_credibility "https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py"
click node_extraction "https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py"
click node_synthesis "https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py"
click node_verification "https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py"
click node_citation_check "https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py"
click node_confidence "https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py"
click node_answer "https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py"
click node_report "https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/report.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_refinement,node_evidence_gate,node_nebius toneBlue
class node_search,node_tavily,node_selection,node_credibility,node_extraction toneAmber
class node_synthesis,node_verification,node_citation_check,node_confidence toneMint
class node_answer,node_report,node_report_files toneRose
class node_researcher toneIndigo
```

## Components

### Research workflow

- [Research runner](https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py): `src/agent.py`
- [Query planning](https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py): `src/agent.py`
- [Query refinement](https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py): `src/agent.py`
- [Evidence threshold](https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py): `src/agent.py`
- **Nebius Token Factory**

### Evidence gathering

- [Web search](https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py): `src/agent.py`
- **Tavily**
- [Evidence selection](https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py): `src/agent.py`
- [Credibility scoring](https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py): `src/agent.py`
- [Page extraction](https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py): `src/agent.py`

### Synthesis and verification

- [Cited synthesis](https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py): `src/agent.py`
- [Claim verification](https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py): `src/agent.py`
- [Citation check](https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py): `src/agent.py`
- [Confidence score](https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py): `src/agent.py`

### Results and reports

- [Answer and trace](https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/agent.py): `src/agent.py`
- [Report generator](https://github.com/daimx1214/evidence-first-research-agent/blob/main/src/report.py): `src/report.py`
- **HTML / Markdown**

### Other components

- **Researcher**

## Connections

- Researcher → Research runner: asks question (evidence: `README.md`)
- Research runner → Query planning: plans queries (evidence: `README.md`)
- Query planning → Nebius Token Factory: requests inference (evidence: `README.md`)
- Research runner → Web search: searches queries (evidence: `src/agent.py`)
- Web search → Tavily: requests results (evidence: `src/agent.py`)
- Research runner → Evidence selection: selects results (evidence: `README.md`)
- Evidence selection → Credibility scoring: scores publishers (evidence: `README.md`)
- Research runner → Page extraction: extracts thin sources (evidence: `README.md`)
- Page extraction → Tavily: requests page text (evidence: `README.md`)
- Research runner → Evidence threshold: checks source count (evidence: `README.md`)
- Evidence threshold → Query refinement: refines once (evidence: `README.md`)
- Query refinement → Nebius Token Factory: requests inference (evidence: `README.md`)
- Research runner → Cited synthesis: synthesizes evidence (evidence: `README.md`)
- Cited synthesis → Nebius Token Factory: requests inference (evidence: `README.md`)
- Research runner → Claim verification: checks claims (evidence: `src/agent.py`)
- Claim verification → Nebius Token Factory: requests inference (evidence: `README.md`)
- Research runner → Citation check: checks citations (evidence: `README.md`)
- Research runner → Confidence score: scores confidence (evidence: `README.md`)
- Research runner → Answer and trace: assembles result (evidence: `src/agent.py`)
- Research runner → Report generator: renders report (evidence: `src/agent.py`)
- Report generator → HTML / Markdown: produces reports (evidence: `README.md`)
- Research runner → Answer and trace: refuses if insufficient (evidence: `README.md`)
