# ltjed/freephdlabor architecture

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

- Interactive diagram: https://gitdiagram.com/ltjed/freephdlabor
- Repository: https://github.com/ltjed/freephdlabor

## Overview

freephdlabor is a multiagent research automation framework. A user submits a research task through the launcher; the ManagerAgent coordinates ideation, experiments, resource preparation, paper writing, review, and proofreading, iterating on feedback before delivering a manuscript. Supporting capabilities include workspace-based code execution, web and paper research, human interaction, and context management. The README documents the workflow; source-index references and excerpts support the main orchestration and agent/tool relationships. Several tool implementations and integrations were not sampled, so their internal links are omitted.

Main entry points: [`freephdlabor/agents/manager_agent.py`](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/agents/manager_agent.py) (Manager Agent), [`freephdlabor/agents/writeup_agent.py`](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/agents/writeup_agent.py) (Paper Writing), [`freephdlabor/agents/base_research_agent.py`](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/agents/base_research_agent.py) (Agent Foundation), [`freephdlabor/agents/reviewer_agent.py`](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/agents/reviewer_agent.py) (Paper Review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Orchestration"]
  node_launcher["Task Launcher"]
  node_manager["Manager Agent<br/>[manager_agent.py]"]
  node_base_agent["Agent Foundation"]
  node_prompts["Agent Instructions"]
  node_interaction["Human Interaction<br/>[callback_tools.py]"]
end

subgraph group_research["Research Stages"]
  node_ideation["Idea Generation<br/>[ideation_agent.py]"]
  node_idea_tools["Idea Tools"]
  node_experimentation["Experimentation"]
  node_experiment_tools["Experiment Tools"]
  node_scientist_search["Experiment Search"]
  node_resources["Resource Preparation"]
  node_research_tools["Research Tools<br/>[ods_tool.py]"]
end

subgraph group_writing["Paper Production"]
  node_writeup["Paper Writing<br/>[writeup_agent.py]"]
  node_latex_tools["LaTeX Generation"]
  node_writeup_analysis["Paper Analysis"]
  node_review["Paper Review<br/>[reviewer_agent.py]"]
  node_review_tools["Document Review"]
  node_proofread["Proofreading"]
end

subgraph group_runtime["Runtime Support"]
  node_executor["Workspace Executor"]
  node_file_tools["Workspace Files"]
  node_llm["LLM Access<br/>[llm.py]"]
  node_supervision["Agent Supervision"]
  node_context["Context Management"]
end

node_researcher(("Researcher"))

node_researcher -->|"submits task"| node_launcher
node_launcher -->|"starts workflow"| node_manager
node_manager -->|"delegates ideation"| node_ideation
node_manager -->|"delegates experiments"| node_experimentation
node_manager -->|"delegates preparation"| node_resources
node_manager -->|"delegates writing"| node_writeup
node_manager -->|"delegates review"| node_review
node_manager -->|"delegates proofreading"| node_proofread
node_manager -->|"uses workspace tools"| node_file_tools
node_manager -->|"supports feedback"| node_interaction
node_manager -->|"uses instructions"| node_prompts
node_ideation -.->|"uses idea tools"| node_idea_tools
node_ideation -.->|"researches literature"| node_research_tools
node_experimentation -.->|"uses experiment tools"| node_experiment_tools
node_experiment_tools -.->|"runs experiments"| node_scientist_search
node_experimentation -->|"executes code"| node_executor
node_resources -.->|"organizes workspace"| node_file_tools
node_writeup -->|"generates LaTeX"| node_latex_tools
node_writeup -->|"reflects on draft"| node_writeup_analysis
node_review -->|"analyzes paper"| node_review_tools
node_review -->|"accesses workspace"| node_file_tools
node_writeup -->|"submits for review"| node_review
node_manager -->|"requests revisions"| node_writeup
node_manager -->|"inherits agent support"| node_base_agent
node_base_agent -->|"creates executor"| node_executor
node_base_agent -->|"compacts context"| node_context
node_base_agent -->|"logs model calls"| node_llm
node_manager -.->|"supervises output"| node_supervision

click node_launcher "https://github.com/ltjed/freephdlabor/blob/main/launch_multiagent.py"
click node_manager "https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/agents/manager_agent.py"
click node_base_agent "https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/agents/base_research_agent.py"
click node_prompts "https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/prompts/system_prompt_template.py"
click node_interaction "https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/interaction/callback_tools.py"
click node_ideation "https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/agents/ideation_agent.py"
click node_idea_tools "https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/toolkits/idea_generation_toolkit.py"
click node_experimentation "https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/agents/experimentation_agent.py"
click node_experiment_tools "https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/toolkits/run_experiment_tool.py"
click node_scientist_search "https://github.com/ltjed/freephdlabor/blob/main/external_tools/run_experiment_tool/ai_scientist/treesearch/perform_experiments_bfts_with_agentmanager.py"
click node_resources "https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/agents/resource_preparation_agent.py"
click node_research_tools "https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/toolkits/general_tools/open_deep_search/ods_tool.py"
click node_writeup "https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/agents/writeup_agent.py"
click node_latex_tools "https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/toolkits/writeup/latex_generator_tool.py"
click node_writeup_analysis "https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/toolkits/writeup/latex_reflection_tool.py"
click node_review "https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/agents/reviewer_agent.py"
click node_review_tools "https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/toolkits/writeup/vlm_document_analysis_tool.py"
click node_proofread "https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/agents/proofreading_agent.py"
click node_executor "https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/interpreters/workspace_executor.py"
click node_file_tools "https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/toolkits/general_tools/file_editing/file_editing_tools.py"
click node_llm "https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/llm.py"
click node_supervision "https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/supervision/supervision_manager.py"
click node_context "https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/agents/context_compaction.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_launcher,node_manager,node_base_agent,node_prompts,node_interaction toneBlue
class node_ideation,node_idea_tools,node_experimentation,node_experiment_tools,node_scientist_search,node_resources,node_research_tools toneAmber
class node_writeup,node_latex_tools,node_writeup_analysis,node_review,node_review_tools,node_proofread toneMint
class node_executor,node_file_tools,node_llm,node_supervision,node_context toneRose
class node_researcher toneIndigo
```

## Components

### Orchestration

- [Task Launcher](https://github.com/ltjed/freephdlabor/blob/main/launch_multiagent.py): `launch_multiagent.py`
- [Manager Agent](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/agents/manager_agent.py): `freephdlabor/agents/manager_agent.py`
- [Agent Foundation](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/agents/base_research_agent.py): `freephdlabor/agents/base_research_agent.py`
- [Agent Instructions](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/prompts/system_prompt_template.py): `freephdlabor/prompts/system_prompt_template.py`
- [Human Interaction](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/interaction/callback_tools.py): `freephdlabor/interaction/callback_tools.py`

### Research Stages

- [Idea Generation](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/agents/ideation_agent.py): `freephdlabor/agents/ideation_agent.py`
- [Idea Tools](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/toolkits/idea_generation_toolkit.py): `freephdlabor/toolkits/idea_generation_toolkit.py`
- [Experimentation](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/agents/experimentation_agent.py): `freephdlabor/agents/experimentation_agent.py`
- [Experiment Tools](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/toolkits/run_experiment_tool.py): `freephdlabor/toolkits/run_experiment_tool.py`
- [Experiment Search](https://github.com/ltjed/freephdlabor/blob/main/external_tools/run_experiment_tool/ai_scientist/treesearch/perform_experiments_bfts_with_agentmanager.py): `external_tools/run_experiment_tool/ai_scientist/treesearch/perform_experiments_bfts_with_agentmanager.py`
- [Resource Preparation](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/agents/resource_preparation_agent.py): `freephdlabor/agents/resource_preparation_agent.py`
- [Research Tools](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/toolkits/general_tools/open_deep_search/ods_tool.py): `freephdlabor/toolkits/general_tools/open_deep_search/ods_tool.py`

### Paper Production

- [Paper Writing](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/agents/writeup_agent.py): `freephdlabor/agents/writeup_agent.py`
- [LaTeX Generation](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/toolkits/writeup/latex_generator_tool.py): `freephdlabor/toolkits/writeup/latex_generator_tool.py`
- [Paper Analysis](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/toolkits/writeup/latex_reflection_tool.py): `freephdlabor/toolkits/writeup/latex_reflection_tool.py`
- [Paper Review](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/agents/reviewer_agent.py): `freephdlabor/agents/reviewer_agent.py`
- [Document Review](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/toolkits/writeup/vlm_document_analysis_tool.py): `freephdlabor/toolkits/writeup/vlm_document_analysis_tool.py`
- [Proofreading](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/agents/proofreading_agent.py): `freephdlabor/agents/proofreading_agent.py`

### Runtime Support

- [Workspace Executor](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/interpreters/workspace_executor.py): `freephdlabor/interpreters/workspace_executor.py`
- [Workspace Files](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/toolkits/general_tools/file_editing/file_editing_tools.py): `freephdlabor/toolkits/general_tools/file_editing/file_editing_tools.py`
- [LLM Access](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/llm.py): `freephdlabor/llm.py`
- [Agent Supervision](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/supervision/supervision_manager.py): `freephdlabor/supervision/supervision_manager.py`
- [Context Management](https://github.com/ltjed/freephdlabor/blob/main/freephdlabor/agents/context_compaction.py): `freephdlabor/agents/context_compaction.py`

### Other components

- **Researcher**

## Connections

- Researcher → Task Launcher: submits task
- Task Launcher → Manager Agent: starts workflow
- Manager Agent → Idea Generation: delegates ideation (evidence: `freephdlabor/agents/manager_agent.py`)
- Manager Agent → Experimentation: delegates experiments (evidence: `freephdlabor/agents/manager_agent.py`)
- Manager Agent → Resource Preparation: delegates preparation (evidence: `freephdlabor/agents/manager_agent.py`)
- Manager Agent → Paper Writing: delegates writing (evidence: `freephdlabor/agents/manager_agent.py`)
- Manager Agent → Paper Review: delegates review (evidence: `freephdlabor/agents/manager_agent.py`)
- Manager Agent → Proofreading: delegates proofreading (evidence: `freephdlabor/utils.py`)
- Manager Agent → Workspace Files: uses workspace tools (evidence: `freephdlabor/agents/manager_agent.py`)
- Manager Agent → Human Interaction: supports feedback
- Manager Agent → Agent Instructions: uses instructions
- Idea Generation → Idea Tools: uses idea tools
- Idea Generation → Research Tools: researches literature
- Experimentation → Experiment Tools: uses experiment tools
- Experiment Tools → Experiment Search: runs experiments
- Experimentation → Workspace Executor: executes code
- Resource Preparation → Workspace Files: organizes workspace
- Paper Writing → LaTeX Generation: generates LaTeX (evidence: `freephdlabor/agents/writeup_agent.py`)
- Paper Writing → Paper Analysis: reflects on draft (evidence: `freephdlabor/agents/writeup_agent.py`)
- Paper Review → Document Review: analyzes paper (evidence: `freephdlabor/agents/reviewer_agent.py`)
- Paper Review → Workspace Files: accesses workspace (evidence: `freephdlabor/agents/reviewer_agent.py`)
- Paper Writing → Paper Review: submits for review
- Manager Agent → Paper Writing: requests revisions (evidence: `freephdlabor/agents/manager_agent.py`)
- Manager Agent → Agent Foundation: inherits agent support (evidence: `freephdlabor/agents/manager_agent.py`)
- Agent Foundation → Workspace Executor: creates executor (evidence: `freephdlabor/agents/base_research_agent.py`)
- Agent Foundation → Context Management: compacts context (evidence: `freephdlabor/agents/base_research_agent.py`)
- Agent Foundation → LLM Access: logs model calls (evidence: `freephdlabor/agents/base_research_agent.py`)
- Manager Agent → Agent Supervision: supervises output