# sakanaai/ab-mcts-arc2 architecture

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

- Interactive diagram: https://gitdiagram.com/sakanaai/ab-mcts-arc2
- Repository: https://github.com/sakanaai/ab-mcts-arc2

## Overview

##### Project Type and Purpose
- This is an open‐source research tool (CLI application + library) that:
- Runs Adaptive Branching Monte Carlo Tree Search (AB-MCTS) using multiple LLMs
- Solves ARC-AGI-2 benchmark tasks in parallel
- Processes and visualizes results

##### File Structure
- Top-level folders:
- src/ab_mcts_arc2 – core library (algorithm, LLM interfaces, prompts, tasks, utilities)
- experiments/arc2 – experiment runner & prompt definitions
- scripts – shell wrappers for launching experiments and evaluation
- Key files/configs:
- experiments/arc2/configs/config.yaml – LLM settings
- pyproject.toml & uv.lock – dependency management
- .gitmodules – TreeQuest submodule
- graphviz & parallel – external binaries for visualization & parallelism

##### README for Additional Insights
- Core workflow:
1. run_experiments.sh → launches experiments in parallel via experiments/arc2/run.py
2. experiment code uses TreeQuest AB-MCTS classes in src/ab_mcts_arc2

##### Main Components and Their Relationships
1. CLI Entry Points (scripts/run_experiments.sh, scripts/run_eval.sh)
2. Experiment Manager (experiments/arc2/run.py & prompt.py)
3. AB-MCTS Core Library (src/ab_mcts_arc2/):
- Algorithm classes (model_base.py, ab_mcts…)
- Data types & utilities (data_types.py, utils.py)
- Tasks & prompt modules (tasks/arc, prompts/…)
- LLM‐related modules: llm_interface, llm_builder, openai_api, claude_api, gemini_api
4. TreeQuest Submodule (external engine imported via .gitmodules)
5. External Services: OpenAI, Anthropic Claude, Google Gemini APIs
6. Data Store / File System:
- inputs: ARC-AGI-2 problem specs (bundled or downloaded)
- outputs: logs, solution files, processed results, plots

1. User invokes run_experiments.sh → Experiment Manager
2. Experiment Manager loads config.yaml → spawns AB-MCTS instances via TreeQuest
3. AB-MCTS pulls Tasks → generates Prompts → calls LLM Interfaces → receives completions
4. Algorithm expands search tree → writes candidate solutions to outputs/
5. Upon completion, user invokes run_eval.sh → proc_results.py reads outputs → generates metrics

c. Architectural Patterns & Design Principles:
- Separation of concerns: CLI vs. orchestration vs. core algorithm vs. evaluation
- Strategy/Plugin pattern for LLM providers (llm_interface, llm_builder)
- Config‐driven behavior (config.yaml controls LLM list & temperatures)
- Parallel processing (GNU parallel) for experiment scaling
- Modular prompts and tasks for extensibility to new problem domains

d. Key Technologies & Frameworks:
- Python packages managed by uv (pyproject.toml)
- TreeQuest algorithm (submodule)
- Graphviz (visualization)
- Shell tooling (bash, parallel)

- Blue – CLI & orchestration
- Green – core library
- Orange – external services
- Gray – file system / data stores
- “calls”, “reads config”, “generates prompts”, “sends completion request”, “writes output”, “processes results”, etc.
- UML-style annotations for key classes or modules if desired

##### Putting It All Together
- Middle layer: src/ab_mcts_arc2/** modules → TreeQuest engine → LLM API connectors → external LLMs
- Bottom left: local filesystem (inputs, outputs, logs)
- Bottom right: evaluation scripts → plots
- Data flow path end‐to‐end for a single experiment

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI & Orchestration Layer
    subgraph "CLI & Orchestration"
        RES["scripts/run_experiments.sh"]:::cli
        REVAL["scripts/run_eval.sh"]:::cli
        EXP_RUN["experiments/arc2/run.py"]:::cli
        EXP_PROMPT["experiments/arc2/prompt.py"]:::cli
        EXP_UTILS["experiments/arc2/utils.py"]:::cli
        CONFIG["experiments/arc2/configs/config.yaml"]:::cli
    end

    %% Core Library
    subgraph "Core Library"
        MB["model_base.py"]:::core
        LLI["llm_interface.py"]:::core
        LB["llm/llm_builder.py"]:::core
        OA["llm/openai_api.py"]:::core
        CA["llm/claude_api.py"]:::core
        GA["llm/gemini_api.py"]:::core
        LGI["llm_generation_interface.py"]:::core
        DT["data_types.py"]:::core
        CU["utils.py"]:::core
        ER["eval_result.py"]:::core
        EC["evaluate_code.py"]:::core
    end

    %% Tasks & Prompt Modules
    subgraph "Tasks & Prompts"
        TB["tasks/base.py"]:::core
        TA["tasks/arc/task.py"]:::core
        PB["prompts/base.py"]:::core
        PC["prompts/prompt_configs.py"]:::core
        PG["prompts/arc/grid_repr.py"]:::core
    end

    %% TreeQuest Submodule
    TJ["TreeQuest Submodule"]:::core

    %% External Services
    subgraph "External LLM Services"
        OAS["OpenAI API"]:::external
        CLAUDE["Anthropic Claude API"]:::external
        GEM["Google Gemini API"]:::external
    end

    %% File System / Data Store
    subgraph "Data Store"
        IN["Inputs (ARC-AGI-2 specs)"]:::data
        OUT["Outputs (logs, solutions)"]:::data
        PLOTS["Plots"]:::data
    end

    %% Evaluation Layer
    subgraph "Evaluation & Visualization"
        PROC["eval/proc_results.py"]:::eval
        VIS["eval/visualize.py"]:::eval
    end

    %% Connections
    RES -->|"invokes"| EXP_RUN
    EXP_RUN -->|"reads config"| CONFIG
    EXP_RUN -->|"uses prompts"| EXP_PROMPT
    EXP_RUN -->|"uses utils"| EXP_UTILS
    EXP_RUN -->|"spawns AB-MCTS"| MB

    MB -->|"imports tasks"| TB
    MB -->|"uses ARC task"| TA
    MB -->|"imports prompts"| PB
    MB -->|"loads prompt configs"| PC
    MB -->|"uses grid repr"| PG
    MB -->|"invokes engine"| TJ

    MB -->|"uses interface"| LLI
    LLI -->|"builder pattern"| LB
    LB -->|"to OpenAI"| OA
    LB -->|"to Claude"| CA
    LB -->|"to Gemini"| GA

    OA -->|"completion"| MB
    CA -->|"completion"| MB
    GA -->|"completion"| MB

    MB -->|"reads tasks from"| IN
    MB -->|"writes solutions to"| OUT

    REVAL -->|"invokes"| PROC
    PROC -->|"reads outputs from"| OUT
    PROC -->|"processes results"| VIS
    VIS -->|"writes plots to"| PLOTS

    %% Click events
    click RES "https://github.com/sakanaai/ab-mcts-arc2/blob/main/scripts/run_experiments.sh"
    click REVAL "https://github.com/sakanaai/ab-mcts-arc2/blob/main/scripts/run_eval.sh"
    click EXP_RUN "https://github.com/sakanaai/ab-mcts-arc2/blob/main/experiments/arc2/run.py"
    click EXP_PROMPT "https://github.com/sakanaai/ab-mcts-arc2/blob/main/experiments/arc2/prompt.py"
    click EXP_UTILS "https://github.com/sakanaai/ab-mcts-arc2/blob/main/experiments/arc2/utils.py"
    click CONFIG "https://github.com/sakanaai/ab-mcts-arc2/blob/main/experiments/arc2/configs/config.yaml"
    click MB "https://github.com/sakanaai/ab-mcts-arc2/blob/main/src/ab_mcts_arc2/model_base.py"
    click LLI "https://github.com/sakanaai/ab-mcts-arc2/blob/main/src/ab_mcts_arc2/llm_interface.py"
    click LB "https://github.com/sakanaai/ab-mcts-arc2/blob/main/src/ab_mcts_arc2/llm/llm_builder.py"
    click OA "https://github.com/sakanaai/ab-mcts-arc2/blob/main/src/ab_mcts_arc2/llm/openai_api.py"
    click CA "https://github.com/sakanaai/ab-mcts-arc2/blob/main/src/ab_mcts_arc2/llm/claude_api.py"
    click GA "https://github.com/sakanaai/ab-mcts-arc2/blob/main/src/ab_mcts_arc2/llm/gemini_api.py"
    click LGI "https://github.com/sakanaai/ab-mcts-arc2/blob/main/src/ab_mcts_arc2/llm_generation_interface.py"
    click DT "https://github.com/sakanaai/ab-mcts-arc2/blob/main/src/ab_mcts_arc2/data_types.py"
    click CU "https://github.com/sakanaai/ab-mcts-arc2/blob/main/src/ab_mcts_arc2/utils.py"
    click ER "https://github.com/sakanaai/ab-mcts-arc2/blob/main/src/ab_mcts_arc2/eval_result.py"
    click EC "https://github.com/sakanaai/ab-mcts-arc2/blob/main/src/ab_mcts_arc2/evaluate_code.py"
    click TB "https://github.com/sakanaai/ab-mcts-arc2/blob/main/src/ab_mcts_arc2/tasks/base.py"
    click TA "https://github.com/sakanaai/ab-mcts-arc2/blob/main/src/ab_mcts_arc2/tasks/arc/task.py"
    click PB "https://github.com/sakanaai/ab-mcts-arc2/blob/main/src/ab_mcts_arc2/prompts/base.py"
    click PC "https://github.com/sakanaai/ab-mcts-arc2/blob/main/src/ab_mcts_arc2/prompts/prompt_configs.py"
    click PG "https://github.com/sakanaai/ab-mcts-arc2/blob/main/src/ab_mcts_arc2/prompts/arc/grid_repr.py"
    click TJ "https://github.com/sakanaai/ab-mcts-arc2/blob/main/.gitmodules"
    click PROC "https://github.com/sakanaai/ab-mcts-arc2/blob/main/eval/proc_results.py"
    click VIS "https://github.com/sakanaai/ab-mcts-arc2/blob/main/eval/visualize.py"

    %% Styles
    classDef cli fill:#E0F7FA,stroke:#006064,color:#006064
    classDef core fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef external fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef data fill:#ECEFF1,stroke:#37474F,color:#37474F
    classDef eval fill:#F3E5F5,stroke:#4A148C,color:#4A148C
```
