# sakanaai/ai-scientist-v3 architecture

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

- Interactive diagram: https://gitdiagram.com/sakanaai/ai-scientist-v3
- Repository: https://github.com/sakanaai/ai-scientist-v3

## Overview

Agentic Scientist turns a task description into agent-driven experiments and a paper, with task drafting, iterative investigation, ablations, sealed final evaluation, and post-hoc analysis as distinct stages. The main entry point dispatches `agsci run`; the README documents the phase workflow and persistent run directory. The separate run inspector discovers saved runs and serves graph, detail, and performance views to a browser UI. Edges between pipeline stages follow the README; the excerpts do not expose their internal runtime wiring, so those links are documented rather than inferred from module names.

Main entry points: [`src/pipeline/cli.py`](https://github.com/sakanaai/ai-scientist-v3/blob/main/src/pipeline/cli.py) (Run pipeline), [`src/pipeline/portable_run_storage.py`](https://github.com/sakanaai/ai-scientist-v3/blob/main/src/pipeline/portable_run_storage.py) (Run directory), [`apps/run_inspector/backend/app.py`](https://github.com/sakanaai/ai-scientist-v3/blob/main/apps/run_inspector/backend/app.py) (Inspector API), [`src/investigation/cli.py`](https://github.com/sakanaai/ai-scientist-v3/blob/main/src/investigation/cli.py) (Idea investigation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Run orchestration"]
  node_cli["Command dispatcher<br/>[main.py]"]
  node_pipeline["Run pipeline<br/>[cli.py]"]
  node_runstore[("Run directory")]
end

subgraph group_research["Task and investigation"]
  node_draft["Task drafting<br/>[service.py]"]
  node_investigation["Idea investigation<br/>[cli.py]"]
  node_runtime["Agent runtime<br/>[runtime.py]"]
end

subgraph group_evaluation["Evaluation phases"]
  node_ablations["Ablations<br/>[pipeline.py]"]
  node_finaleval["Final evaluation<br/>[runner.py]"]
  node_posthoc["Post-hoc analysis<br/>[pipeline.py]"]
end

subgraph group_publication["Analysis and paper"]
  node_paper["Paper production<br/>[paper_step.py]"]
  node_review["Paper review<br/>[final_ai_review.py]"]
end

subgraph group_inspection["Run inspection"]
  node_inspectapi["Inspector API<br/>[app.py]"]
  node_discovery["Run discovery<br/>[discovery.py]"]
  node_graph["Run graph builder<br/>[graph_builder.py]"]
  node_performance["Performance builder"]
  node_views["Run detail views<br/>[views_builder.py]"]
  node_frontend["Inspector UI<br/>[App.tsx]"]
  node_api["API client<br/>[client.ts]"]
end

node_user(("Researcher"))
node_browser(("Browser user"))

node_user -->|"runs command"| node_cli
node_cli -->|"dispatches run"| node_pipeline
node_pipeline -->|"runs phase"| node_draft
node_pipeline -->|"runs phase"| node_investigation
node_pipeline -->|"runs phase"| node_ablations
node_pipeline -->|"runs phase"| node_finaleval
node_pipeline -->|"runs phase"| node_posthoc
node_pipeline -->|"runs phase"| node_paper
node_draft -->|"writes run outputs"| node_runstore
node_investigation -.->|"uses agent runtime"| node_runtime
node_investigation -->|"writes run outputs"| node_runstore
node_ablations -->|"writes run outputs"| node_runstore
node_finaleval -->|"writes run outputs"| node_runstore
node_posthoc -->|"writes run outputs"| node_runstore
node_paper -->|"writes manuscript"| node_runstore
node_paper -.->|"optional AI review"| node_review
node_browser -->|"browses runs"| node_frontend
node_frontend -->|"requests data"| node_api
node_api -->|"calls API"| node_inspectapi
node_inspectapi -->|"discovers runs"| node_discovery
node_inspectapi -->|"builds graph"| node_graph
node_inspectapi -->|"builds performance"| node_performance
node_inspectapi -->|"builds details"| node_views
node_discovery -.->|"scans run data"| node_runstore

click node_cli "https://github.com/sakanaai/ai-scientist-v3/blob/main/src/agsci/main.py"
click node_pipeline "https://github.com/sakanaai/ai-scientist-v3/blob/main/src/pipeline/cli.py"
click node_runstore "https://github.com/sakanaai/ai-scientist-v3/blob/main/src/pipeline/portable_run_storage.py"
click node_draft "https://github.com/sakanaai/ai-scientist-v3/blob/main/src/task_drafting/service.py"
click node_investigation "https://github.com/sakanaai/ai-scientist-v3/blob/main/src/investigation/cli.py"
click node_runtime "https://github.com/sakanaai/ai-scientist-v3/blob/main/src/investigation/runtime.py"
click node_ablations "https://github.com/sakanaai/ai-scientist-v3/blob/main/src/variants_pipeline/pipeline.py"
click node_finaleval "https://github.com/sakanaai/ai-scientist-v3/blob/main/src/final_evaluation/runner.py"
click node_posthoc "https://github.com/sakanaai/ai-scientist-v3/blob/main/src/posthoc_pipeline/pipeline.py"
click node_paper "https://github.com/sakanaai/ai-scientist-v3/blob/main/src/orchestrator/paper_step.py"
click node_review "https://github.com/sakanaai/ai-scientist-v3/blob/main/src/investigation/final_ai_review.py"
click node_inspectapi "https://github.com/sakanaai/ai-scientist-v3/blob/main/apps/run_inspector/backend/app.py"
click node_discovery "https://github.com/sakanaai/ai-scientist-v3/blob/main/apps/run_inspector/backend/discovery.py"
click node_graph "https://github.com/sakanaai/ai-scientist-v3/blob/main/apps/run_inspector/backend/graph_builder.py"
click node_performance "https://github.com/sakanaai/ai-scientist-v3/blob/main/apps/run_inspector/backend/performance_builder.py"
click node_views "https://github.com/sakanaai/ai-scientist-v3/blob/main/apps/run_inspector/backend/views_builder.py"
click node_frontend "https://github.com/sakanaai/ai-scientist-v3/blob/main/apps/run_inspector/frontend/src/App.tsx"
click node_api "https://github.com/sakanaai/ai-scientist-v3/blob/main/apps/run_inspector/frontend/src/api/client.ts"

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_cli,node_pipeline,node_runstore,node_browser toneBlue
class node_draft,node_investigation,node_runtime toneAmber
class node_ablations,node_finaleval,node_posthoc toneMint
class node_paper,node_review toneRose
class node_inspectapi,node_discovery,node_graph,node_performance,node_views,node_frontend,node_api,node_user toneIndigo
```

## Components

### Run orchestration

- [Command dispatcher](https://github.com/sakanaai/ai-scientist-v3/blob/main/src/agsci/main.py): `src/agsci/main.py`
- [Run pipeline](https://github.com/sakanaai/ai-scientist-v3/blob/main/src/pipeline/cli.py): `src/pipeline/cli.py`
- [Run directory](https://github.com/sakanaai/ai-scientist-v3/blob/main/src/pipeline/portable_run_storage.py): `src/pipeline/portable_run_storage.py`

### Task and investigation

- [Task drafting](https://github.com/sakanaai/ai-scientist-v3/blob/main/src/task_drafting/service.py): `src/task_drafting/service.py`
- [Idea investigation](https://github.com/sakanaai/ai-scientist-v3/blob/main/src/investigation/cli.py): `src/investigation/cli.py`
- [Agent runtime](https://github.com/sakanaai/ai-scientist-v3/blob/main/src/investigation/runtime.py): `src/investigation/runtime.py`

### Evaluation phases

- [Ablations](https://github.com/sakanaai/ai-scientist-v3/blob/main/src/variants_pipeline/pipeline.py): `src/variants_pipeline/pipeline.py`
- [Final evaluation](https://github.com/sakanaai/ai-scientist-v3/blob/main/src/final_evaluation/runner.py): `src/final_evaluation/runner.py`
- [Post-hoc analysis](https://github.com/sakanaai/ai-scientist-v3/blob/main/src/posthoc_pipeline/pipeline.py): `src/posthoc_pipeline/pipeline.py`

### Analysis and paper

- [Paper production](https://github.com/sakanaai/ai-scientist-v3/blob/main/src/orchestrator/paper_step.py): `src/orchestrator/paper_step.py`
- [Paper review](https://github.com/sakanaai/ai-scientist-v3/blob/main/src/investigation/final_ai_review.py): `src/investigation/final_ai_review.py`

### Run inspection

- [Inspector API](https://github.com/sakanaai/ai-scientist-v3/blob/main/apps/run_inspector/backend/app.py): `apps/run_inspector/backend/app.py`
- [Run discovery](https://github.com/sakanaai/ai-scientist-v3/blob/main/apps/run_inspector/backend/discovery.py): `apps/run_inspector/backend/discovery.py`
- [Run graph builder](https://github.com/sakanaai/ai-scientist-v3/blob/main/apps/run_inspector/backend/graph_builder.py): `apps/run_inspector/backend/graph_builder.py`
- [Performance builder](https://github.com/sakanaai/ai-scientist-v3/blob/main/apps/run_inspector/backend/performance_builder.py): `apps/run_inspector/backend/performance_builder.py`
- [Run detail views](https://github.com/sakanaai/ai-scientist-v3/blob/main/apps/run_inspector/backend/views_builder.py): `apps/run_inspector/backend/views_builder.py`
- [Inspector UI](https://github.com/sakanaai/ai-scientist-v3/blob/main/apps/run_inspector/frontend/src/App.tsx): `apps/run_inspector/frontend/src/App.tsx`
- [API client](https://github.com/sakanaai/ai-scientist-v3/blob/main/apps/run_inspector/frontend/src/api/client.ts): `apps/run_inspector/frontend/src/api/client.ts`

### Other components

- **Researcher**
- **Browser user**

## Connections

- Researcher → Command dispatcher: runs command (evidence: `src/agsci/main.py`)
- Command dispatcher → Run pipeline: dispatches run (evidence: `src/agsci/main.py`)
- Run pipeline → Task drafting: runs phase
- Run pipeline → Idea investigation: runs phase
- Run pipeline → Ablations: runs phase
- Run pipeline → Final evaluation: runs phase
- Run pipeline → Post-hoc analysis: runs phase
- Run pipeline → Paper production: runs phase
- Task drafting → Run directory: writes run outputs
- Idea investigation → Agent runtime: uses agent runtime
- Idea investigation → Run directory: writes run outputs
- Ablations → Run directory: writes run outputs
- Final evaluation → Run directory: writes run outputs
- Post-hoc analysis → Run directory: writes run outputs
- Paper production → Run directory: writes manuscript
- Paper production → Paper review: optional AI review
- Browser user → Inspector UI: browses runs
- Inspector UI → API client: requests data (evidence: `apps/run_inspector/frontend/src/App.tsx`)
- API client → Inspector API: calls API (evidence: `apps/run_inspector/frontend/src/api/client.ts`)
- Inspector API → Run discovery: discovers runs (evidence: `apps/run_inspector/backend/app.py`)
- Inspector API → Run graph builder: builds graph (evidence: `apps/run_inspector/backend/app.py`)
- Inspector API → Performance builder: builds performance (evidence: `apps/run_inspector/backend/app.py`)
- Inspector API → Run detail views: builds details (evidence: `apps/run_inspector/backend/app.py`)
- Run discovery → Run directory: scans run data
