# brookww/qagent architecture

> Architecture diagram of the GitHub repository brookww/qagent, 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/brookww/qagent
- Repository: https://github.com/brookww/qagent

## Overview

QAgent is a local research assistant that turns paper inputs into reviewed, theorem-level mathematical questions and exports selected questions with supporting guidance. Its main workflow resolves and reads papers, assesses evidence, generates candidates through the Codex CLI, validates and reviews them for novelty and direct-corollary risk, then selects and exports results. The README documents the product stages; sampled source and the source index support several internal links. Some implementation details are unsampled, so uncertain connections are omitted.

Main entry points: [`app.py`](https://github.com/brookww/qagent/blob/main/app.py) (Streamlit UI), [`src/qagent/deep_paper_reader.py`](https://github.com/brookww/qagent/blob/main/src/qagent/deep_paper_reader.py) (Deep paper reader), [`src/qagent/hard_review.py`](https://github.com/brookww/qagent/blob/main/src/qagent/hard_review.py) (Hard review), [`src/qagent/paper_fetcher.py`](https://github.com/brookww/qagent/blob/main/src/qagent/paper_fetcher.py) (Paper fetcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Input and control"]
  node_streamlit["Streamlit UI<br/>[app.py]"]
  node_resolver["Input resolver<br/>[input_resolver.py]"]
end

subgraph group_reading["Paper understanding"]
  node_fetcher["Paper fetcher<br/>[paper_fetcher.py]"]
  node_text["Text extraction"]
  node_reader["Deep paper reader"]
  node_preflight["Evidence preflight"]
  node_theorems["Theorem extraction"]
  node_gaps["Gap extraction<br/>[gap_extractor.py]"]
  node_reading_quality["Reading quality<br/>[reading_quality.py]"]
  node_paper_survey["Paper literature survey"]
end

subgraph group_questions["Question generation"]
  node_runner["Candidate generation<br/>[runner.py]"]
end

subgraph group_review["Validation and review"]
  node_candidate_validator["Candidate validation"]
  node_validators["Question validators<br/>[validators.py]"]
  node_novelty["Novelty review<br/>[novelty_review.py]"]
  node_survey["Candidate survey<br/>[survey.py]"]
  node_hard_review["Hard review<br/>[hard_review.py]"]
  node_critic["Candidate critic<br/>[critic.py]"]
  node_quality_audit["Quality audit<br/>[quality_audit.py]"]
end

subgraph group_delivery["Export and diagnostics"]
  node_exporter["Question export<br/>[exporter.py]"]
  node_candidate_exporter["Candidate export"]
  node_backend_diagnostics["Backend diagnostics"]
  node_handoff["GPT Pro handoff<br/>[gpt_pro_handoff.py]"]
  node_outputs["Generated outputs"]
end

node_researcher(("Researcher"))
node_codex["Codex CLI"]

node_researcher -->|"submits papers"| node_streamlit
node_streamlit -->|"resolves inputs"| node_resolver
node_resolver -->|"fetches sources"| node_fetcher
node_fetcher -->|"extracts text"| node_text
node_streamlit -->|"checks evidence"| node_preflight
node_streamlit -->|"surveys papers"| node_paper_survey
node_streamlit -.->|"reads papers"| node_reader
node_reader -->|"fetches source"| node_fetcher
node_reader -.->|"extracts text"| node_text
node_reader -.->|"extracts theorems"| node_theorems
node_reader -->|"extracts gaps"| node_gaps
node_reader -.->|"assesses reading"| node_reading_quality
node_streamlit -->|"generates candidates"| node_runner
node_runner -->|"invokes backend"| node_codex
node_streamlit -->|"validates candidates"| node_candidate_validator
node_candidate_validator -->|"checks theorem form"| node_validators
node_streamlit -->|"reviews novelty"| node_novelty
node_streamlit -->|"runs hard review"| node_hard_review
node_hard_review -->|"reviews candidates"| node_critic
node_hard_review -->|"surveys candidates"| node_survey
node_streamlit -->|"audits quality"| node_quality_audit
node_streamlit -->|"exports selection"| node_exporter
node_streamlit -.->|"exports candidates"| node_candidate_exporter
node_streamlit -->|"checks backend"| node_backend_diagnostics
node_streamlit -->|"writes handoff"| node_handoff
node_exporter -->|"writes questions"| node_outputs
node_candidate_exporter -.->|"writes artifacts"| node_outputs

click node_streamlit "https://github.com/brookww/qagent/blob/main/app.py"
click node_resolver "https://github.com/brookww/qagent/blob/main/src/qagent/input_resolver.py"
click node_fetcher "https://github.com/brookww/qagent/blob/main/src/qagent/paper_fetcher.py"
click node_text "https://github.com/brookww/qagent/blob/main/src/qagent/paper_text_extractor.py"
click node_reader "https://github.com/brookww/qagent/blob/main/src/qagent/deep_paper_reader.py"
click node_preflight "https://github.com/brookww/qagent/blob/main/src/qagent/evidence_preflight.py"
click node_theorems "https://github.com/brookww/qagent/blob/main/src/qagent/theorem_extractor.py"
click node_gaps "https://github.com/brookww/qagent/blob/main/src/qagent/gap_extractor.py"
click node_reading_quality "https://github.com/brookww/qagent/blob/main/src/qagent/reading_quality.py"
click node_paper_survey "https://github.com/brookww/qagent/blob/main/src/qagent/paper_literature_survey.py"
click node_runner "https://github.com/brookww/qagent/blob/main/src/qagent/runner.py"
click node_candidate_validator "https://github.com/brookww/qagent/blob/main/src/qagent/candidate_validator.py"
click node_validators "https://github.com/brookww/qagent/blob/main/src/qagent/validators.py"
click node_novelty "https://github.com/brookww/qagent/blob/main/src/qagent/novelty_review.py"
click node_survey "https://github.com/brookww/qagent/blob/main/src/qagent/survey.py"
click node_hard_review "https://github.com/brookww/qagent/blob/main/src/qagent/hard_review.py"
click node_critic "https://github.com/brookww/qagent/blob/main/src/qagent/critic.py"
click node_quality_audit "https://github.com/brookww/qagent/blob/main/src/qagent/quality_audit.py"
click node_exporter "https://github.com/brookww/qagent/blob/main/src/qagent/exporter.py"
click node_candidate_exporter "https://github.com/brookww/qagent/blob/main/src/qagent/candidate_exporter.py"
click node_backend_diagnostics "https://github.com/brookww/qagent/blob/main/src/qagent/backend_diagnostics.py"
click node_handoff "https://github.com/brookww/qagent/blob/main/src/qagent/gpt_pro_handoff.py"
click node_outputs "https://github.com/brookww/qagent/tree/main/outputs"

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_streamlit,node_resolver toneBlue
class node_fetcher,node_text,node_reader,node_preflight,node_theorems,node_gaps,node_reading_quality,node_paper_survey toneAmber
class node_runner toneMint
class node_candidate_validator,node_validators,node_novelty,node_survey,node_hard_review,node_critic,node_quality_audit toneRose
class node_exporter,node_candidate_exporter,node_backend_diagnostics,node_handoff,node_outputs,node_researcher,node_codex toneIndigo
```

## Components

### Input and control

- [Streamlit UI](https://github.com/brookww/qagent/blob/main/app.py): `app.py`
- [Input resolver](https://github.com/brookww/qagent/blob/main/src/qagent/input_resolver.py): `src/qagent/input_resolver.py`

### Paper understanding

- [Paper fetcher](https://github.com/brookww/qagent/blob/main/src/qagent/paper_fetcher.py): `src/qagent/paper_fetcher.py`
- [Text extraction](https://github.com/brookww/qagent/blob/main/src/qagent/paper_text_extractor.py): `src/qagent/paper_text_extractor.py`
- [Deep paper reader](https://github.com/brookww/qagent/blob/main/src/qagent/deep_paper_reader.py): `src/qagent/deep_paper_reader.py`
- [Evidence preflight](https://github.com/brookww/qagent/blob/main/src/qagent/evidence_preflight.py): `src/qagent/evidence_preflight.py`
- [Theorem extraction](https://github.com/brookww/qagent/blob/main/src/qagent/theorem_extractor.py): `src/qagent/theorem_extractor.py`
- [Gap extraction](https://github.com/brookww/qagent/blob/main/src/qagent/gap_extractor.py): `src/qagent/gap_extractor.py`
- [Reading quality](https://github.com/brookww/qagent/blob/main/src/qagent/reading_quality.py): `src/qagent/reading_quality.py`
- [Paper literature survey](https://github.com/brookww/qagent/blob/main/src/qagent/paper_literature_survey.py): `src/qagent/paper_literature_survey.py`

### Question generation

- [Candidate generation](https://github.com/brookww/qagent/blob/main/src/qagent/runner.py): `src/qagent/runner.py`

### Validation and review

- [Candidate validation](https://github.com/brookww/qagent/blob/main/src/qagent/candidate_validator.py): `src/qagent/candidate_validator.py`
- [Question validators](https://github.com/brookww/qagent/blob/main/src/qagent/validators.py): `src/qagent/validators.py`
- [Novelty review](https://github.com/brookww/qagent/blob/main/src/qagent/novelty_review.py): `src/qagent/novelty_review.py`
- [Candidate survey](https://github.com/brookww/qagent/blob/main/src/qagent/survey.py): `src/qagent/survey.py`
- [Hard review](https://github.com/brookww/qagent/blob/main/src/qagent/hard_review.py): `src/qagent/hard_review.py`
- [Candidate critic](https://github.com/brookww/qagent/blob/main/src/qagent/critic.py): `src/qagent/critic.py`
- [Quality audit](https://github.com/brookww/qagent/blob/main/src/qagent/quality_audit.py): `src/qagent/quality_audit.py`

### Export and diagnostics

- [Question export](https://github.com/brookww/qagent/blob/main/src/qagent/exporter.py): `src/qagent/exporter.py`
- [Candidate export](https://github.com/brookww/qagent/blob/main/src/qagent/candidate_exporter.py): `src/qagent/candidate_exporter.py`
- [Backend diagnostics](https://github.com/brookww/qagent/blob/main/src/qagent/backend_diagnostics.py): `src/qagent/backend_diagnostics.py`
- [GPT Pro handoff](https://github.com/brookww/qagent/blob/main/src/qagent/gpt_pro_handoff.py): `src/qagent/gpt_pro_handoff.py`
- [Generated outputs](https://github.com/brookww/qagent/tree/main/outputs): `outputs`

### Other components

- **Researcher**
- **Codex CLI**

## Connections

- Researcher → Streamlit UI: submits papers (evidence: `README.md`)
- Streamlit UI → Input resolver: resolves inputs (evidence: `README.md`)
- Input resolver → Paper fetcher: fetches sources (evidence: `README.md`)
- Paper fetcher → Text extraction: extracts text (evidence: `README.md`)
- Streamlit UI → Evidence preflight: checks evidence (evidence: `README.md`)
- Streamlit UI → Paper literature survey: surveys papers (evidence: `README.md`)
- Streamlit UI → Deep paper reader: reads papers
- Deep paper reader → Paper fetcher: fetches source (evidence: `src/qagent/deep_paper_reader.py`)
- Deep paper reader → Text extraction: extracts text (evidence: `src/qagent/deep_paper_reader.py`)
- Deep paper reader → Theorem extraction: extracts theorems (evidence: `src/qagent/deep_paper_reader.py`)
- Deep paper reader → Gap extraction: extracts gaps (evidence: `src/qagent/deep_paper_reader.py`)
- Deep paper reader → Reading quality: assesses reading (evidence: `src/qagent/deep_paper_reader.py`)
- Streamlit UI → Candidate generation: generates candidates (evidence: `README.md`)
- Candidate generation → Codex CLI: invokes backend (evidence: `README.md`)
- Streamlit UI → Candidate validation: validates candidates (evidence: `README.md`)
- Candidate validation → Question validators: checks theorem form (evidence: `src/qagent/candidate_validator.py`)
- Streamlit UI → Novelty review: reviews novelty (evidence: `README.md`)
- Streamlit UI → Hard review: runs hard review (evidence: `README.md`)
- Hard review → Candidate critic: reviews candidates (evidence: `src/qagent/hard_review.py`)
- Hard review → Candidate survey: surveys candidates (evidence: `src/qagent/hard_review.py`)
- Streamlit UI → Quality audit: audits quality (evidence: `README.md`)
- Streamlit UI → Question export: exports selection (evidence: `README.md`)
- Streamlit UI → Candidate export: exports candidates (evidence: `app.py`)
- Streamlit UI → Backend diagnostics: checks backend (evidence: `app.py`)
- Streamlit UI → GPT Pro handoff: writes handoff (evidence: `README.md`)
- Question export → Generated outputs: writes questions (evidence: `README.md`)
- Candidate export → Generated outputs: writes artifacts
