# hotba318/ai_agent_task architecture

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

- Interactive diagram: https://gitdiagram.com/hotba318/ai_agent_task
- Repository: https://github.com/hotba318/ai_agent_task

## Overview

Group 3 is a paper-research workflow comprising retrieval, common-reference analysis, and grounded report writing. Users can run retrieval independently, then analyze the stored papers’ shared citations and provide analysis/evidence inputs to the Writer. Retrieval searches, ranks, downloads, parses, and stores papers; the Writer produces Markdown with citation/numeric checks and optional model review. The README documents these capabilities; unsampled modules are included where their role is documented or named in the source index, but their internal call details are not inferred.

Main entry points: [`group3/services.py`](https://github.com/hotba318/ai_agent_task/blob/main/group3/services.py) (Analysis services), [`group3/agents/retrieval/agent.py`](https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/retrieval/agent.py) (Retrieval agent), [`group3/agents/writer/agent.py`](https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/writer/agent.py) (Writer agent), [`group3/agents/references/agent.py`](https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/references/agent.py) (Reference analyzer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_retrieval["Paper Retrieval"]
  node_retrieval_cli["Retrieval CLI<br/>[cli.py]"]
  node_retrieval_agent["Retrieval agent<br/>[agent.py]"]
  node_search["Search providers<br/>[search.py]"]
  node_arxiv["arXiv client<br/>[arxiv_client.py]"]
  node_datacite["DataCite client<br/>[datacite_client.py]"]
  node_retrieval_planner["Search planner<br/>[planner.py]"]
  node_ranker["Relevance ranker<br/>[ranker.py]"]
  node_fetcher["Document fetcher<br/>[fetcher.py]"]
  node_downloader["HTTP downloader<br/>[downloader.py]"]
  node_parser["Document parser<br/>[parser.py]"]
  node_paper_store[("Paper store<br/>[storage.py]")]
end

subgraph group_references["Common References"]
  node_analysis_cli["Analysis CLI<br/>[analysis_cli.py]"]
  node_services["Analysis services<br/>[services.py]"]
  node_references_agent["Reference analyzer<br/>[agent.py]"]
  node_matcher["Citation matcher<br/>[matcher.py]"]
end

subgraph group_writer["Grounded Writing"]
  node_writer_agent["Writer agent<br/>[agent.py]"]
  node_writer_planner["Draft planner<br/>[planner.py]"]
  node_draft["Grounded draft<br/>[draft.py]"]
  node_validator["Claim validator<br/>[validator.py]"]
  node_renderer["Markdown renderer<br/>[renderer.py]"]
  node_writer_state["Revision state<br/>[state.py]"]
end

subgraph group_shared["Shared Contracts"]
  node_llm["Structured LLM client<br/>[llm.py]"]
  node_contracts["Retrieval contracts<br/>[schemas.py]"]
  node_analysis_contracts["Analysis contracts"]
  node_settings["Configuration<br/>[config.py]"]
  node_interfaces["Agent interfaces<br/>[interfaces.py]"]
end

node_user(("Researcher"))
node_paper_sources{{"Paper sources"}}
node_grobid{{"GROBID service"}}
node_groq{{"Groq API"}}

node_user -->|"starts retrieval"| node_retrieval_cli
node_retrieval_cli -->|"runs"| node_retrieval_agent
node_retrieval_agent -->|"plans searches"| node_retrieval_planner
node_retrieval_agent -->|"fetches papers"| node_fetcher
node_retrieval_agent -->|"uses settings"| node_settings
node_retrieval_planner -->|"ranks candidates"| node_ranker
node_retrieval_planner -->|"requests decisions"| node_llm
node_search -.->|"queries"| node_arxiv
node_search -.->|"queries"| node_datacite
node_fetcher -->|"downloads"| node_downloader
node_fetcher -->|"parses documents"| node_parser
node_fetcher -->|"stores papers"| node_paper_store
node_downloader -.->|"requests documents"| node_paper_sources
node_parser -.->|"parses PDFs"| node_grobid
node_retrieval_agent -->|"uses contracts"| node_contracts
node_user -->|"starts analysis"| node_analysis_cli
node_analysis_cli -->|"dispatches"| node_services
node_services -->|"runs analysis"| node_references_agent
node_services -->|"selects stored papers"| node_paper_store
node_references_agent -->|"loads papers"| node_paper_store
node_references_agent -->|"matches citations"| node_matcher
node_references_agent -->|"returns results"| node_analysis_contracts
node_analysis_cli -->|"dispatches writing"| node_services
node_services -->|"runs or revises"| node_writer_agent
node_services -->|"selects planner"| node_writer_planner
node_services -->|"uses settings"| node_settings
node_writer_agent -->|"plans prose"| node_writer_planner
node_writer_agent -->|"validates claims"| node_validator
node_writer_agent -->|"renders report"| node_renderer
node_writer_agent -->|"tracks revisions"| node_writer_state
node_writer_planner -->|"builds draft"| node_draft
node_writer_planner -->|"checks draft"| node_validator
node_writer_planner -->|"requests generation"| node_llm
node_renderer -->|"renders draft"| node_draft
node_renderer -->|"checks output"| node_validator
node_validator -->|"recomputes citations"| node_references_agent
node_llm -->|"sends completions"| node_groq
node_writer_agent -->|"uses contracts"| node_analysis_contracts
node_retrieval_agent -->|"uses interfaces"| node_interfaces

click node_retrieval_cli "https://github.com/hotba318/ai_agent_task/blob/main/group3/cli.py"
click node_retrieval_agent "https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/retrieval/agent.py"
click node_search "https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/retrieval/search.py"
click node_arxiv "https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/retrieval/arxiv_client.py"
click node_datacite "https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/retrieval/datacite_client.py"
click node_retrieval_planner "https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/retrieval/planner.py"
click node_ranker "https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/retrieval/ranker.py"
click node_fetcher "https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/retrieval/fetcher.py"
click node_downloader "https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/retrieval/downloader.py"
click node_parser "https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/retrieval/parser.py"
click node_paper_store "https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/retrieval/storage.py"
click node_analysis_cli "https://github.com/hotba318/ai_agent_task/blob/main/group3/analysis_cli.py"
click node_services "https://github.com/hotba318/ai_agent_task/blob/main/group3/services.py"
click node_references_agent "https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/references/agent.py"
click node_matcher "https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/references/matcher.py"
click node_writer_agent "https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/writer/agent.py"
click node_writer_planner "https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/writer/planner.py"
click node_draft "https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/writer/draft.py"
click node_validator "https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/writer/validator.py"
click node_renderer "https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/writer/renderer.py"
click node_writer_state "https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/writer/state.py"
click node_llm "https://github.com/hotba318/ai_agent_task/blob/main/group3/common/llm.py"
click node_contracts "https://github.com/hotba318/ai_agent_task/blob/main/group3/common/schemas.py"
click node_analysis_contracts "https://github.com/hotba318/ai_agent_task/blob/main/group3/common/analysis_schemas.py"
click node_settings "https://github.com/hotba318/ai_agent_task/blob/main/group3/common/config.py"
click node_interfaces "https://github.com/hotba318/ai_agent_task/blob/main/group3/common/interfaces.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_retrieval_cli,node_retrieval_agent,node_search,node_arxiv,node_datacite,node_retrieval_planner,node_ranker,node_fetcher,node_downloader,node_parser,node_paper_store toneBlue
class node_analysis_cli,node_services,node_references_agent,node_matcher toneAmber
class node_writer_agent,node_writer_planner,node_draft,node_validator,node_renderer,node_writer_state,node_groq toneMint
class node_llm,node_contracts,node_analysis_contracts,node_settings,node_interfaces toneRose
class node_user,node_paper_sources,node_grobid toneIndigo
```

## Components

### Paper Retrieval

- [Retrieval CLI](https://github.com/hotba318/ai_agent_task/blob/main/group3/cli.py): `group3/cli.py`
- [Retrieval agent](https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/retrieval/agent.py): `group3/agents/retrieval/agent.py`
- [Search providers](https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/retrieval/search.py): `group3/agents/retrieval/search.py`
- [arXiv client](https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/retrieval/arxiv_client.py): `group3/agents/retrieval/arxiv_client.py`
- [DataCite client](https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/retrieval/datacite_client.py): `group3/agents/retrieval/datacite_client.py`
- [Search planner](https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/retrieval/planner.py): `group3/agents/retrieval/planner.py`
- [Relevance ranker](https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/retrieval/ranker.py): `group3/agents/retrieval/ranker.py`
- [Document fetcher](https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/retrieval/fetcher.py): `group3/agents/retrieval/fetcher.py`
- [HTTP downloader](https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/retrieval/downloader.py): `group3/agents/retrieval/downloader.py`
- [Document parser](https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/retrieval/parser.py): `group3/agents/retrieval/parser.py`
- [Paper store](https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/retrieval/storage.py): `group3/agents/retrieval/storage.py`

### Common References

- [Analysis CLI](https://github.com/hotba318/ai_agent_task/blob/main/group3/analysis_cli.py): `group3/analysis_cli.py`
- [Analysis services](https://github.com/hotba318/ai_agent_task/blob/main/group3/services.py): `group3/services.py`
- [Reference analyzer](https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/references/agent.py): `group3/agents/references/agent.py`
- [Citation matcher](https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/references/matcher.py): `group3/agents/references/matcher.py`

### Grounded Writing

- [Writer agent](https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/writer/agent.py): `group3/agents/writer/agent.py`
- [Draft planner](https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/writer/planner.py): `group3/agents/writer/planner.py`
- [Grounded draft](https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/writer/draft.py): `group3/agents/writer/draft.py`
- [Claim validator](https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/writer/validator.py): `group3/agents/writer/validator.py`
- [Markdown renderer](https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/writer/renderer.py): `group3/agents/writer/renderer.py`
- [Revision state](https://github.com/hotba318/ai_agent_task/blob/main/group3/agents/writer/state.py): `group3/agents/writer/state.py`

### Shared Contracts

- [Structured LLM client](https://github.com/hotba318/ai_agent_task/blob/main/group3/common/llm.py): `group3/common/llm.py`
- [Retrieval contracts](https://github.com/hotba318/ai_agent_task/blob/main/group3/common/schemas.py): `group3/common/schemas.py`
- [Analysis contracts](https://github.com/hotba318/ai_agent_task/blob/main/group3/common/analysis_schemas.py): `group3/common/analysis_schemas.py`
- [Configuration](https://github.com/hotba318/ai_agent_task/blob/main/group3/common/config.py): `group3/common/config.py`
- [Agent interfaces](https://github.com/hotba318/ai_agent_task/blob/main/group3/common/interfaces.py): `group3/common/interfaces.py`

### Other components

- **Researcher**
- **Paper sources**
- **GROBID service**
- **Groq API**

## Connections

- Researcher → Retrieval CLI: starts retrieval (evidence: `README.md`)
- Retrieval CLI → Retrieval agent: runs (evidence: `group3/cli.py`)
- Retrieval agent → Search planner: plans searches (evidence: `group3/agents/retrieval/agent.py`)
- Retrieval agent → Document fetcher: fetches papers (evidence: `group3/agents/retrieval/agent.py`)
- Retrieval agent → Configuration: uses settings (evidence: `group3/agents/retrieval/agent.py`)
- Search planner → Relevance ranker: ranks candidates (evidence: `group3/agents/retrieval/planner.py`)
- Search planner → Structured LLM client: requests decisions (evidence: `group3/agents/retrieval/planner.py`)
- Search providers → arXiv client: queries
- Search providers → DataCite client: queries
- Document fetcher → HTTP downloader: downloads (evidence: `group3/agents/retrieval/fetcher.py`)
- Document fetcher → Document parser: parses documents (evidence: `group3/agents/retrieval/fetcher.py`)
- Document fetcher → Paper store: stores papers (evidence: `group3/agents/retrieval/fetcher.py`)
- HTTP downloader → Paper sources: requests documents
- Document parser → GROBID service: parses PDFs
- Retrieval agent → Retrieval contracts: uses contracts (evidence: `group3/agents/retrieval/agent.py`)
- Researcher → Analysis CLI: starts analysis (evidence: `README.md`)
- Analysis CLI → Analysis services: dispatches (evidence: `group3/analysis_cli.py`)
- Analysis services → Reference analyzer: runs analysis (evidence: `group3/services.py`)
- Analysis services → Paper store: selects stored papers (evidence: `group3/services.py`)
- Reference analyzer → Paper store: loads papers (evidence: `group3/agents/references/agent.py`)
- Reference analyzer → Citation matcher: matches citations (evidence: `group3/agents/references/agent.py`)
- Reference analyzer → Analysis contracts: returns results (evidence: `group3/agents/references/agent.py`)
- Analysis CLI → Analysis services: dispatches writing (evidence: `README.md`)
- Analysis services → Writer agent: runs or revises (evidence: `group3/services.py`)
- Analysis services → Draft planner: selects planner (evidence: `group3/services.py`)
- Analysis services → Configuration: uses settings (evidence: `group3/services.py`)
- Writer agent → Draft planner: plans prose (evidence: `group3/agents/writer/agent.py`)
- Writer agent → Claim validator: validates claims (evidence: `group3/agents/writer/agent.py`)
- Writer agent → Markdown renderer: renders report (evidence: `group3/agents/writer/agent.py`)
- Writer agent → Revision state: tracks revisions (evidence: `group3/agents/writer/agent.py`)
- Draft planner → Grounded draft: builds draft (evidence: `group3/agents/writer/planner.py`)
- Draft planner → Claim validator: checks draft (evidence: `group3/agents/writer/planner.py`)
- Draft planner → Structured LLM client: requests generation (evidence: `group3/agents/writer/planner.py`)
- Markdown renderer → Grounded draft: renders draft (evidence: `group3/agents/writer/renderer.py`)
- Markdown renderer → Claim validator: checks output (evidence: `group3/agents/writer/renderer.py`)
- Claim validator → Reference analyzer: recomputes citations (evidence: `group3/agents/writer/validator.py`)
- Structured LLM client → Groq API: sends completions (evidence: `group3/common/llm.py`)
- Writer agent → Analysis contracts: uses contracts (evidence: `group3/agents/writer/agent.py`)
- Retrieval agent → Agent interfaces: uses interfaces (evidence: `group3/agents/retrieval/agent.py`)