# sakanaai/ai-scientist-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/sakanaai/ai-scientist-v2
- Repository: https://github.com/sakanaai/ai-scientist-v2
- Video tour (about a minute): https://gitdiagram.com/sakanaai/ai-scientist-v2/video

## Overview

##### Main components
- Core Research Pipeline – This is the overall “brain” of the system that generates hypotheses, runs experiments, reviews results, and produces manuscripts.
- Tree Search Module – Represented by the “treesearch” directory, this includes sub-components such as:
- Agent Manager (agent_manager.py)
- Backend connectors for interfacing with LLM APIs (backend/backend_openai.py, backend/backend_anthropic.py)
- Utilities for configuration, serialization, and visualization (in treesearch/utils and viz_templates)
- Supporting scripts for journals, interpreters, and debugging (journal.py, interpreter.py, log_summarization.py)
- LLM and VLM Interaction – Files like llm.py and vlm.py indicate modules managing language models and vision-language models, plus associated processing scripts (e.g., perform_llm_review.py, perform_vlm_review.py, perform_writeup.py).
- Idea and Experiment Management – The “ideas” directory holds JSON and Python files for research ideas. Additionally, “fewshot_examples” exemplify input/output formats for experiments.
- Template/Manuscript Output – The “blank_icbinb_latex” and “blank_icml_latex” directories provide LaTeX templates for generated papers.
- External API Tools – The “tools” directory, including modules such as semantic_scholar.py, deals with external services for citation and literature search.

##### Out the relationships and interactions
- The launch entry point (launch_scientist_bfts.py) ties all operations together.
- The agentic tree search (the treesearch module) orchestrates the decision process: using a multi-worker (agent_manager.py and parallel_agent.py) search that explores hypothesis nodes based on configuration in bfts_config.yaml.
- There is a clear use of backend modules to abstract calls to external LLM APIs (OpenAI and Anthropic via AWS Bedrock), with environment variables (e.g., OPENAI_API_KEY, AWS keys) configuring these interactions.
- The experimental phase interacts with the idea files from the “ideas” directory as input and produces visualization outputs and logs (e.g., unified_tree_viz.html within experiment logs).
- Tools such as the Semantic Scholar connector often provide feedback to check novelty and retrieve citations, linking the research process with relevant external literature.
- Utility scripts (e.g., perform_plotting.py, perform_writeup.py) are involved for different stages of processing (analysis, writing, plotting).

##### Important design principles
- Modularity – Each functionality (tree search, LLM interactions, template management) is separated into its own module.
- Agentic Orchestration – The tree search with multiple agents denotes an asynchronous, parallel decision-making architecture.
- Extensibility – Presence of directories like “ideas” and “fewshot_examples”, and clear configuration in YAML, suggests that research topics and experiment parameters are easily modifiable.
- Safety and Flexibility – Given warnings in the README, the system is designed to execute code generated by LLMs, so risk boundaries and environment isolation are critical, though these may be managed externally (e.g., via containerization or secure execution contexts).

##### Relevant technologies and frameworks
- Python (version 3.11 as recommended) with supporting libraries like PyTorch for GPU usage.
- CUDA for GPU processing on NVIDIA GPUs.
- LaTeX templates for manuscript generation.
- External API integrations (OpenAI, Amazon Bedrock for Claude, and Semantic Scholar).
- Configuration via YAML (bfts_config.yaml), which controls the tree search parameters.

## Diagram (Mermaid)

```mermaid
graph TD
    CorePipeline["Core Research Pipeline"]:::core
    Orchestrator["Research Orchestrator / Entry Point"]:::orchestrator
    Config["bfts_config.yaml"]:::config
    External["Semantic Scholar"]:::external

    %% Main connections
    CorePipeline -->|"integrates"| Orchestrator
    Orchestrator -->|"launches"| AM
    Config ---|"configures"| AM
    External -->|"verifies_citations"| LLM

    %% Idea & Experiment Manager Subgraph
    subgraph "Idea & Experiment Manager"
        IR["Ideas Repository"]:::experiment
        FE["Fewshot Examples"]:::experiment
        IS["Ideation Script"]:::experiment
        ITF["Ideation Temp Free"]:::experiment
    end

    %% Template Manager Subgraph
    subgraph "Template Manager"
        ICL["ICBINB LaTeX"]:::template
        ICM["ICML LaTeX"]:::template
    end

    %% LLM/VLM Module Subgraph
    subgraph "LLM/VLM Module"
        LLM["LLM"]:::llmv
        PLLM["Perform LLM Review"]:::llmv
        VLM["VLM"]:::llmv
        PVLM["Perform VLM Review"]:::llmv
        PW["Perform Writeup"]:::llmv
        IW["ICBINB Writeup"]:::llmv
    end

    %% Tree Search Engine Subgraph
    subgraph "Tree Search Engine"
        AM["Agent Manager"]:::treesearch
        PA["Parallel Agent"]:::treesearch
        Intr["Interpreter"]:::treesearch
        Jour["Journal"]:::treesearch
        JR["Journal2Report"]:::treesearch
        LS["Log Summarization"]:::treesearch
        EE["Experiment Execution"]:::treesearch
        BO["Backend OpenAI"]:::treesearch
        BA["Backend Anthropic"]:::treesearch
        Util["Utilities"]:::treesearch
        VT["Viz Templates"]:::treesearch
    end

    %% Internal connections within Tree Search Engine
    AM -->|"manages"| PA
    AM -->|"delegates_to"| Intr
    AM -->|"logs_to"| Jour
    Jour -->|"reports_to"| JR
    AM -->|"summarizes"| LS
    AM -->|"runs"| EE
    AM -->|"calls"| BO
    AM -->|"calls"| BA
    AM -->|"utilizes"| Util
    Util -->|"contains"| VT

    %% Internal connections within LLM/VLM Module
    LLM -->|"triggers_review"| PLLM
    VLM -->|"triggers_review"| PVLM
    LLM -->|"initiates_writeup"| PW
    PW -->|"prepares"| IW
    IW -->|"formats_using"| ICL
    IW -->|"alternatively_formats_using"| ICM

    %% Connections between modules
    IR -->|"supplies_ideas"| AM
    IS -->|"generates_ideas"| IR
    ITF -->|"alternative_ideation"| IR
    AM -->|"calls_LLM/VLM"| LLM

    %% Class Definitions for styling
    classDef orchestrator fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef treesearch fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef llmv fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef experiment fill:#FFFFE0,stroke:#000,stroke-width:2px;
    classDef template fill:#FFDAB9,stroke:#000,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef config fill:#E6E6FA,stroke:#000,stroke-width:2px;
    classDef core fill:#F0E68C,stroke:#000,stroke-width:2px;

    %% Click Events
    click Orchestrator "https://github.com/sakanaai/ai-scientist-v2/blob/main/launch_scientist_bfts.py"
    click CorePipeline "https://github.com/sakanaai/ai-scientist-v2/tree/main/ai_scientist/"
    click AM "https://github.com/sakanaai/ai-scientist-v2/blob/main/ai_scientist/treesearch/agent_manager.py"
    click PA "https://github.com/sakanaai/ai-scientist-v2/blob/main/ai_scientist/treesearch/parallel_agent.py"
    click Intr "https://github.com/sakanaai/ai-scientist-v2/blob/main/ai_scientist/treesearch/interpreter.py"
    click Jour "https://github.com/sakanaai/ai-scientist-v2/blob/main/ai_scientist/treesearch/journal.py"
    click JR "https://github.com/sakanaai/ai-scientist-v2/blob/main/ai_scientist/treesearch/journal2report.py"
    click LS "https://github.com/sakanaai/ai-scientist-v2/blob/main/ai_scientist/treesearch/log_summarization.py"
    click EE "https://github.com/sakanaai/ai-scientist-v2/blob/main/ai_scientist/treesearch/perform_experiments_bfts_with_agentmanager.py"
    click BO "https://github.com/sakanaai/ai-scientist-v2/blob/main/ai_scientist/treesearch/backend/backend_openai.py"
    click BA "https://github.com/sakanaai/ai-scientist-v2/blob/main/ai_scientist/treesearch/backend/backend_anthropic.py"
    click Util "https://github.com/sakanaai/ai-scientist-v2/tree/main/ai_scientist/treesearch/utils"
    click VT "https://github.com/sakanaai/ai-scientist-v2/tree/main/ai_scientist/treesearch/utils/viz_templates"
    click LLM "https://github.com/sakanaai/ai-scientist-v2/blob/main/ai_scientist/llm.py"
    click PLLM "https://github.com/sakanaai/ai-scientist-v2/blob/main/ai_scientist/perform_llm_review.py"
    click VLM "https://github.com/sakanaai/ai-scientist-v2/blob/main/ai_scientist/vlm.py"
    click PVLM "https://github.com/sakanaai/ai-scientist-v2/blob/main/ai_scientist/perform_vlm_review.py"
    click PW "https://github.com/sakanaai/ai-scientist-v2/blob/main/ai_scientist/perform_writeup.py"
    click IW "https://github.com/sakanaai/ai-scientist-v2/blob/main/ai_scientist/perform_icbinb_writeup.py"
    click IR "https://github.com/sakanaai/ai-scientist-v2/tree/main/ai_scientist/ideas"
    click FE "https://github.com/sakanaai/ai-scientist-v2/tree/main/ai_scientist/fewshot_examples"
    click IS "https://github.com/sakanaai/ai-scientist-v2/blob/main/ai_scientist/perform_ideation.py"
    click ITF "https://github.com/sakanaai/ai-scientist-v2/blob/main/ai_scientist/perform_ideation_temp_free.py"
    click ICL "https://github.com/sakanaai/ai-scientist-v2/tree/main/ai_scientist/blank_icbinb_latex"
    click ICM "https://github.com/sakanaai/ai-scientist-v2/tree/main/ai_scientist/blank_icml_latex"
    click Config "https://github.com/sakanaai/ai-scientist-v2/blob/main/bfts_config.yaml"
    click External "https://github.com/sakanaai/ai-scientist-v2/blob/main/ai_scientist/tools/semantic_scholar.py"
```
