# alpha-innovator/dolphin architecture

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

- Interactive diagram: https://gitdiagram.com/alpha-innovator/dolphin
- Repository: https://github.com/alpha-innovator/dolphin

## Overview

##### Project Type and Purpose
- Dolphin is a Python-based closed-loop, LLM-driven auto-research framework.
- It orchestrates iterative rounds of idea generation, code implementation, experiment execution, and results analysis, feeding feedback into subsequent rounds.

a. Orchestrator
- launch_dolphin.py / launch_dolphin.sh
- Coordinates the closed-loop workflow and round management.
b. Idea Generation Module
- dolphin_utils/generate_ideas.py
- Uses prompts (dolphin_utils/prompts.py) and LLM utilities (dolphin_utils/llm_utils.py) to produce novel research ideas.
c. Retrieval & Context Module
- dolphin_utils/rag_tools/ (lit_review.py, lit_review_tools.py, utils.py, prompts.py)
- Retrieves and ranks relevant papers; provides contextual feedback to the LLM.
d. Code Template & Implementation Module
- dolphin_utils/experiments_utils.py, dolphin_utils/rag_utils.py
- Builds/refines code templates for running experiments; handles exception-traceback guided debugging.
e. Experiment Runner
- examples/… directories (image_classification_cifar100, point_classification_modelnet, sentiment_classification_sst2)
- Scripts (experiment.py, launcher.sh) that train/evaluate models and produce result artifacts (best.pth, final_info.json).
f. Results Analyzer
- Parses final_info.json and other metrics (e.g., metrics.py); summarizes performance improvements.
g. Data & Artifacts Store
- experiment directories under examples/, run_0/, seed_ideas.json
- Stores generated code, logs, model checkpoints, and analysis outputs.
h. External Services
- LLM API (OpenAI or self-hosted via Ollama per docs/ollama_doc.md)
- Datasets (downloaded by users, not bundled)

##### Relationships and Data Flow
- Orchestrator → Idea Generation: “start round, pass previous round feedback”
- Idea Generation → Retrieval Module: “fetch literature context”
- Idea Generation → Code Template Module: “produce initial code skeleton”
- Code Template Module → Experiment Runner: “execute experiment script”
- Experiment Runner → Data Store: “write checkpoints, final_info.json”
- Experiment Runner → Results Analyzer: “send raw metrics”
- Results Analyzer → Orchestrator: “send summary feedback for next idea generation”
- Orchestrator loops back to Idea Generation

##### Architectural Patterns and Principles
- Closed-loop feedback architecture: clearly illustrate the iterative cycle.
- Modular separation: LLM interaction, retrieval, code synthesis, execution, analysis are separate modules.
- Pluggable backends: experiments defined per task under examples/; supports adding new tasks.
- Declarative configuration: launch scripts and prompt JSONs define metadata.

##### Relevant Technologies & Frameworks
- Python 3.11, Conda environment
- Hugging Face/LLM APIs or Ollama self-hosted model
- PyTorch (implied by .pth model files)
- RAG tools for retrieval-augmented generation
- Shell scripts for orchestration (bash)

4. To the left of Retrieval, place Idea Generation (rectangle), connected from Orchestrator and Retrieval.
5. Below Idea Generation, place Code Template & Implementation (rectangle).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Main Components
    Orch["Orchestrator\n(launch_dolphin.py, launch_dolphin.sh)"]:::orchestrator
    LLM["LLM API\n(OpenAI / Ollama)"]:::cloud

    subgraph "LLM + Retrieval Subsystem"
        Idea["Idea Generation Module\n(dolphin_utils)"]:::module
        Retrieval["Retrieval & Context Module\n(dolphin_utils/rag_tools)"]:::module
    end

    CodeTemplate["Code Template & Implementation Module\n(dolphin_utils/experiments_utils.py, rag_utils.py)"]:::module
    ExperimentRunner["Experiment Runner\n(examples/... tasks)"]:::module
    DataStore["Data & Artifacts Store\n(examples/*/run_0, seed_ideas.json)"]:::storage
    Results["Results Analyzer\n(metrics parsing)"]:::analyzer

    %% Data Flows
    Orch -->|"start round\npass previous feedback"| Idea
    Idea -->|"prompt + context"| LLM
    LLM -->|"literature context"| Retrieval
    Retrieval -->|"context"| Idea
    Idea -->|"code template"| CodeTemplate
    CodeTemplate -->|"execute experiment"| ExperimentRunner
    ExperimentRunner -->|"model checkpoint,\nfinal_info.json"| DataStore
    ExperimentRunner -->|"raw metrics"| Results
    Results -->|"feedback summary"| Orch

    %% Click Events
    click Orch "https://github.com/alpha-innovator/dolphin/blob/main/launch_dolphin.py"
    click Orch "https://github.com/alpha-innovator/dolphin/blob/main/launch_dolphin.sh"
    click Idea "https://github.com/alpha-innovator/dolphin/blob/main/dolphin_utils/generate_ideas.py"
    click Idea "https://github.com/alpha-innovator/dolphin/blob/main/dolphin_utils/prompts.py"
    click Idea "https://github.com/alpha-innovator/dolphin/blob/main/dolphin_utils/llm_utils.py"
    click Retrieval "https://github.com/alpha-innovator/dolphin/blob/main/dolphin_utils/rag_tools/lit_review.py"
    click Retrieval "https://github.com/alpha-innovator/dolphin/blob/main/dolphin_utils/rag_tools/lit_review_tools.py"
    click Retrieval "https://github.com/alpha-innovator/dolphin/blob/main/dolphin_utils/rag_tools/prompts.py"
    click Retrieval "https://github.com/alpha-innovator/dolphin/blob/main/dolphin_utils/rag_tools/utils.py"
    click CodeTemplate "https://github.com/alpha-innovator/dolphin/blob/main/dolphin_utils/experiments_utils.py"
    click CodeTemplate "https://github.com/alpha-innovator/dolphin/blob/main/dolphin_utils/rag_utils.py"
    click ExperimentRunner "https://github.com/alpha-innovator/dolphin/blob/main/examples/image_classification_cifar100/experiment.py"
    click ExperimentRunner "https://github.com/alpha-innovator/dolphin/blob/main/examples/image_classification_cifar100/launch.sh"
    click ExperimentRunner "https://github.com/alpha-innovator/dolphin/blob/main/examples/image_classification_cifar100/run_0/experiment.py"
    click ExperimentRunner "https://github.com/alpha-innovator/dolphin/blob/main/examples/image_classification_cifar100/run_0/best.pth"
    click ExperimentRunner "https://github.com/alpha-innovator/dolphin/blob/main/examples/image_classification_cifar100/run_0/final_info.json"
    click ExperimentRunner "https://github.com/alpha-innovator/dolphin/blob/main/examples/image_classification_cifar100/seed_ideas.json"
    click ExperimentRunner "https://github.com/alpha-innovator/dolphin/blob/main/examples/point_classification_modelnet/experiment.py"
    click ExperimentRunner "https://github.com/alpha-innovator/dolphin/blob/main/examples/point_classification_modelnet/launcher.sh"
    click ExperimentRunner "https://github.com/alpha-innovator/dolphin/blob/main/examples/point_classification_modelnet/metrics.py"
    click ExperimentRunner "https://github.com/alpha-innovator/dolphin/blob/main/examples/point_classification_modelnet/run_0/experiment.py"
    click ExperimentRunner "https://github.com/alpha-innovator/dolphin/blob/main/examples/point_classification_modelnet/run_0/final_info.json"
    click ExperimentRunner "https://github.com/alpha-innovator/dolphin/blob/main/examples/point_classification_modelnet/seed_ideas.json"
    click ExperimentRunner "https://github.com/alpha-innovator/dolphin/blob/main/examples/sentiment_classification_sst2/experiment.py"
    click ExperimentRunner "https://github.com/alpha-innovator/dolphin/blob/main/examples/sentiment_classification_sst2/launch.sh"
    click ExperimentRunner "https://github.com/alpha-innovator/dolphin/blob/main/examples/sentiment_classification_sst2/run_0/experiment.py"
    click ExperimentRunner "https://github.com/alpha-innovator/dolphin/blob/main/examples/sentiment_classification_sst2/run_0/final_info.json"
    click ExperimentRunner "https://github.com/alpha-innovator/dolphin/blob/main/examples/sentiment_classification_sst2/seed_ideas.json"
    click Results "https://github.com/alpha-innovator/dolphin/blob/main/examples/point_classification_modelnet/metrics.py"
    click DataStore "https://github.com/alpha-innovator/dolphin/tree/main/examples/*/run_0/"
    click DataStore "https://github.com/alpha-innovator/dolphin/blob/main/examples/*/seed_ideas.json"

    %% Styles
    classDef orchestrator fill:#f9f,stroke:#333,stroke-width:1px;
    classDef module fill:#bbf,stroke:#333,stroke-width:1px;
    classDef storage fill:#afa,stroke:#333,stroke-width:1px;
    classDef cloud fill:#fed,stroke:#333,stroke-width:1px;
    classDef analyzer fill:#fdd,stroke:#333,stroke-width:1px;
```
