# aammartufail/top_five_ai_agents_for_research architecture

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

- Interactive diagram: https://gitdiagram.com/aammartufail/top_five_ai_agents_for_research
- Repository: https://github.com/aammartufail/top_five_ai_agents_for_research

## Overview

This repository is a starter kit for five independent AI research agents, plus guides and learning materials. The main runtime workflow spans discovery, systematic review, experimentation, manuscript preparation and PhD mentoring; the agents are separate CLIs rather than a connected pipeline. The sampled entrypoints support the workflow and orchestration edges shown here; unsampled agent internals are represented only where the README or entrypoint establishes their role.

Main entry points: [`02_agents_code/agent_03_research_experiment/main.py`](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_03_research_experiment/main.py) (Experiment CLI), [`02_agents_code/agent_04_academic_writing/main.py`](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_04_academic_writing/main.py) (Writing CLI), [`02_agents_code/agent_04_academic_writing/llm.py`](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_04_academic_writing/llm.py) (LLM Client), [`02_agents_code/agent_01_research_discovery/main.py`](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_01_research_discovery/main.py) (Discovery CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Research Discovery"]
  node_discovery_cli["Discovery CLI<br/>[main.py]"]
  node_paper_search["Paper Search<br/>[tools.py]"]
  node_trend_gaps["Trends &amp; Gaps<br/>[agents.py]"]
  node_idea_proposal["Ideas &amp; Proposal<br/>[agents.py]"]
end

subgraph group_review["Literature Review"]
  node_review_cli["Review CLI<br/>[main.py]"]
  node_review_search["Review Search<br/>[tools.py]"]
  node_screen_extract_write["Screen &amp; Extract<br/>[agents.py]"]
  node_prisma_counts["PRISMA Counts<br/>[prisma.py]"]
end

subgraph group_experiment["Research Experiment"]
  node_experiment_cli["Experiment CLI<br/>[main.py]"]
  node_experiment_data["Data Input<br/>[data.py]"]
  node_experiment_analysis["Statistical &amp; ML<br/>[analysis.py]"]
  node_experiment_agents["Design &amp; Reporting<br/>[agents.py]"]
  node_notebook_output["Notebook Output<br/>[notebook.py]"]
end

subgraph group_publication["Writing &amp; Mentoring"]
  node_writing_cli["Writing CLI<br/>[main.py]"]
  node_manuscript["Manuscript Drafting<br/>[agents.py]"]
  node_journal_match["Journal Matching<br/>[agents.py]"]
  node_peer_review["Reviewer Simulation<br/>[agents.py]"]
  node_revision["Revision &amp; Rebuttal<br/>[agents.py]"]
  node_supervisor_cli["Supervisor CLI<br/>[main.py]"]
  node_mentor_agents["Mentoring Tasks<br/>[agents.py]"]
  node_student_memory[("Student Memory<br/>[memory.py]")]
end

subgraph group_shared["Shared Agent Layer"]
  node_llm_discovery["LLM Client<br/>[llm.py]"]
  node_llm_review["LLM Client<br/>[llm.py]"]
  node_llm_experiment["LLM Client<br/>[llm.py]"]
  node_llm_writing["LLM Client<br/>[llm.py]"]
  node_llm_supervisor["LLM Client<br/>[llm.py]"]
end

node_researcher(("Researcher"))
node_anthropic{{"Anthropic API"}}
node_research_sources{{"Research APIs"}}

node_researcher -->|"submits topic"| node_discovery_cli
node_discovery_cli -->|"searches papers"| node_paper_search
node_paper_search -->|"queries APIs"| node_research_sources
node_discovery_cli -->|"analyzes literature"| node_trend_gaps
node_discovery_cli -->|"generates outputs"| node_idea_proposal
node_trend_gaps -->|"requests analysis"| node_llm_discovery
node_idea_proposal -->|"generates text"| node_llm_discovery
node_llm_discovery -->|"calls model"| node_anthropic
node_researcher -->|"submits question"| node_review_cli
node_review_cli -->|"searches records"| node_review_search
node_review_search -->|"queries APIs"| node_research_sources
node_review_cli -->|"screens and writes"| node_screen_extract_write
node_review_cli -->|"builds counts"| node_prisma_counts
node_screen_extract_write -->|"requests analysis"| node_llm_review
node_llm_review -->|"calls model"| node_anthropic
node_researcher -->|"describes study"| node_experiment_cli
node_experiment_cli -->|"loads data"| node_experiment_data
node_experiment_cli -->|"runs analyses"| node_experiment_analysis
node_experiment_cli -->|"plans and reports"| node_experiment_agents
node_experiment_cli -->|"builds notebook"| node_notebook_output
node_experiment_agents -->|"requests analysis"| node_llm_experiment
node_llm_experiment -->|"calls model"| node_anthropic
node_researcher -->|"provides notes"| node_writing_cli
node_writing_cli -->|"drafts manuscript"| node_manuscript
node_writing_cli -->|"matches journals"| node_journal_match
node_writing_cli -->|"simulates review"| node_peer_review
node_writing_cli -->|"revises manuscript"| node_revision
node_manuscript -->|"requests drafting"| node_llm_writing
node_journal_match -->|"requests matching"| node_llm_writing
node_peer_review -->|"requests review"| node_llm_writing
node_revision -->|"requests revision"| node_llm_writing
node_llm_writing -->|"calls model"| node_anthropic
node_researcher -->|"submits updates"| node_supervisor_cli
node_supervisor_cli -->|"reads and writes"| node_student_memory
node_supervisor_cli -->|"runs mentoring tasks"| node_mentor_agents
node_mentor_agents -->|"requests guidance"| node_llm_supervisor
node_llm_supervisor -->|"calls model"| node_anthropic

click node_discovery_cli "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_01_research_discovery/main.py"
click node_paper_search "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_01_research_discovery/tools.py"
click node_trend_gaps "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_01_research_discovery/agents.py"
click node_idea_proposal "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_01_research_discovery/agents.py"
click node_review_cli "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_02_literature_review/main.py"
click node_review_search "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_02_literature_review/tools.py"
click node_screen_extract_write "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_02_literature_review/agents.py"
click node_prisma_counts "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_02_literature_review/prisma.py"
click node_experiment_cli "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_03_research_experiment/main.py"
click node_experiment_data "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_03_research_experiment/data.py"
click node_experiment_analysis "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_03_research_experiment/analysis.py"
click node_experiment_agents "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_03_research_experiment/agents.py"
click node_notebook_output "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_03_research_experiment/notebook.py"
click node_writing_cli "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_04_academic_writing/main.py"
click node_manuscript "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_04_academic_writing/agents.py"
click node_journal_match "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_04_academic_writing/agents.py"
click node_peer_review "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_04_academic_writing/agents.py"
click node_revision "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_04_academic_writing/agents.py"
click node_supervisor_cli "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_05_phd_supervisor/main.py"
click node_mentor_agents "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_05_phd_supervisor/agents.py"
click node_student_memory "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_05_phd_supervisor/memory.py"
click node_llm_discovery "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_01_research_discovery/llm.py"
click node_llm_review "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_02_literature_review/llm.py"
click node_llm_experiment "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_03_research_experiment/llm.py"
click node_llm_writing "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_04_academic_writing/llm.py"
click node_llm_supervisor "https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_05_phd_supervisor/llm.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_discovery_cli,node_paper_search,node_trend_gaps,node_idea_proposal toneBlue
class node_review_cli,node_review_search,node_screen_extract_write,node_prisma_counts toneAmber
class node_experiment_cli,node_experiment_data,node_experiment_analysis,node_experiment_agents,node_notebook_output,node_anthropic,node_research_sources toneMint
class node_writing_cli,node_manuscript,node_journal_match,node_peer_review,node_revision,node_supervisor_cli,node_mentor_agents,node_student_memory toneRose
class node_llm_discovery,node_llm_review,node_llm_experiment,node_llm_writing,node_llm_supervisor,node_researcher toneIndigo
```

## Components

### Research Discovery

- [Discovery CLI](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_01_research_discovery/main.py): `02_agents_code/agent_01_research_discovery/main.py`
- [Paper Search](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_01_research_discovery/tools.py): `02_agents_code/agent_01_research_discovery/tools.py`
- [Trends & Gaps](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_01_research_discovery/agents.py): `02_agents_code/agent_01_research_discovery/agents.py`
- [Ideas & Proposal](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_01_research_discovery/agents.py): `02_agents_code/agent_01_research_discovery/agents.py`

### Literature Review

- [Review CLI](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_02_literature_review/main.py): `02_agents_code/agent_02_literature_review/main.py`
- [Review Search](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_02_literature_review/tools.py): `02_agents_code/agent_02_literature_review/tools.py`
- [Screen & Extract](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_02_literature_review/agents.py): `02_agents_code/agent_02_literature_review/agents.py`
- [PRISMA Counts](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_02_literature_review/prisma.py): `02_agents_code/agent_02_literature_review/prisma.py`

### Research Experiment

- [Experiment CLI](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_03_research_experiment/main.py): `02_agents_code/agent_03_research_experiment/main.py`
- [Data Input](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_03_research_experiment/data.py): `02_agents_code/agent_03_research_experiment/data.py`
- [Statistical & ML](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_03_research_experiment/analysis.py): `02_agents_code/agent_03_research_experiment/analysis.py`
- [Design & Reporting](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_03_research_experiment/agents.py): `02_agents_code/agent_03_research_experiment/agents.py`
- [Notebook Output](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_03_research_experiment/notebook.py): `02_agents_code/agent_03_research_experiment/notebook.py`

### Writing & Mentoring

- [Writing CLI](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_04_academic_writing/main.py): `02_agents_code/agent_04_academic_writing/main.py`
- [Manuscript Drafting](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_04_academic_writing/agents.py): `02_agents_code/agent_04_academic_writing/agents.py`
- [Journal Matching](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_04_academic_writing/agents.py): `02_agents_code/agent_04_academic_writing/agents.py`
- [Reviewer Simulation](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_04_academic_writing/agents.py): `02_agents_code/agent_04_academic_writing/agents.py`
- [Revision & Rebuttal](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_04_academic_writing/agents.py): `02_agents_code/agent_04_academic_writing/agents.py`
- [Supervisor CLI](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_05_phd_supervisor/main.py): `02_agents_code/agent_05_phd_supervisor/main.py`
- [Mentoring Tasks](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_05_phd_supervisor/agents.py): `02_agents_code/agent_05_phd_supervisor/agents.py`
- [Student Memory](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_05_phd_supervisor/memory.py): `02_agents_code/agent_05_phd_supervisor/memory.py`

### Shared Agent Layer

- [LLM Client](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_01_research_discovery/llm.py): `02_agents_code/agent_01_research_discovery/llm.py`
- [LLM Client](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_02_literature_review/llm.py): `02_agents_code/agent_02_literature_review/llm.py`
- [LLM Client](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_03_research_experiment/llm.py): `02_agents_code/agent_03_research_experiment/llm.py`
- [LLM Client](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_04_academic_writing/llm.py): `02_agents_code/agent_04_academic_writing/llm.py`
- [LLM Client](https://github.com/aammartufail/top_five_ai_agents_for_research/blob/main/02_agents_code/agent_05_phd_supervisor/llm.py): `02_agents_code/agent_05_phd_supervisor/llm.py`

### Other components

- **Researcher**
- **Anthropic API**
- **Research APIs**

## Connections

- Researcher → Discovery CLI: submits topic
- Discovery CLI → Paper Search: searches papers
- Paper Search → Research APIs: queries APIs
- Discovery CLI → Trends & Gaps: analyzes literature
- Discovery CLI → Ideas & Proposal: generates outputs
- Trends & Gaps → LLM Client: requests analysis
- Ideas & Proposal → LLM Client: generates text
- LLM Client → Anthropic API: calls model
- Researcher → Review CLI: submits question
- Review CLI → Review Search: searches records
- Review Search → Research APIs: queries APIs
- Review CLI → Screen & Extract: screens and writes
- Review CLI → PRISMA Counts: builds counts
- Screen & Extract → LLM Client: requests analysis
- LLM Client → Anthropic API: calls model
- Researcher → Experiment CLI: describes study
- Experiment CLI → Data Input: loads data
- Experiment CLI → Statistical & ML: runs analyses
- Experiment CLI → Design & Reporting: plans and reports
- Experiment CLI → Notebook Output: builds notebook
- Design & Reporting → LLM Client: requests analysis
- LLM Client → Anthropic API: calls model
- Researcher → Writing CLI: provides notes
- Writing CLI → Manuscript Drafting: drafts manuscript
- Writing CLI → Journal Matching: matches journals
- Writing CLI → Reviewer Simulation: simulates review
- Writing CLI → Revision & Rebuttal: revises manuscript
- Manuscript Drafting → LLM Client: requests drafting
- Journal Matching → LLM Client: requests matching
- Reviewer Simulation → LLM Client: requests review
- Revision & Rebuttal → LLM Client: requests revision
- LLM Client → Anthropic API: calls model
- Researcher → Supervisor CLI: submits updates
- Supervisor CLI → Student Memory: reads and writes
- Supervisor CLI → Mentoring Tasks: runs mentoring tasks
- Mentoring Tasks → LLM Client: requests guidance
- LLM Client → Anthropic API: calls model