# alpha-innovator/internagent architecture

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

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

## Overview

##### Project type and purpose
- InternAgent (formerly “Dolphin”) is an open-source, closed-loop scientific research automation framework. It is a Python-based multi-agent orchestration system that spans idea generation → methodology construction → experimental execution.
- Key indicators:
- `launch_dolphin.py` / `launch_dolphin.sh` as CLI entry points
- `dolphin_utils/` library modules for agent orchestration (LLM utils, RAG tools, prompt templates, experiment utilities)
- `examples/` folder containing end-to-end experiment templates across 12 research tasks

##### File structure
- Top level:
- `dolphin_utils/`: core Python package with submodules
– `experiments_utils.py`: code to schedule, run, log experiments
– `generate_ideas.py`, `prompts.py`, `llm_utils.py`: idea generation pipeline
– `rag_tools/`: retrieval-augmented generation helpers (literature survey, review tools, utilities)
- `examples/`: per-task subfolders (e.g. AutoCls2D_Cifar100, AutoSeg_VOC12, AutoPCDet_Once…) each with Baseline vs custom variant, containing `experiment.py`, `launcher.sh`, config or prompt files, and result folders
- Configuration & deployment artifacts:
- launch scripts for system headless invocation
- shell wrappers customizing API keys, model choice, target tasks

##### README for additional insights
- The README outlines a 3-stage closed-loop: (1) Self-evolving idea generation, (2) Idea → methodology construction, (3) Evolutionary experimental planning & execution
- Mentions multi-agent orchestration coordinating Survey, Coding, Idea, Assessment, Execution Agents
- References to external LLM (via Ollama or API) and Google Drive datasets

a. Main components
1. CLI / Launcher Layer
- launch_dolphin.sh / launch_dolphin.py
- Parses user input: API key, model, task list, iteration rounds
2. Core Orchestrator
- Agent Manager (entry point in `launch_dolphin.py`)
- Scheduling & state machine tracking research rounds
3. Agent Modules (in `dolphin_utils/`)
- Survey Agent: uses `rag_tools` to fetch and summarize literature
- Idea Agent: `generate_ideas.py`, `prompts.py` to propose hypotheses
- Methodology Agent: assembles code templates, data pipelines, baseline code
- Assessment Agent: validates code snippets, metrics using `experiments_utils.py`
- Execution Agent: executes experiment scripts in `examples/…`, captures logs & metrics
4. Supporting Utilities
- LLM Interface (`llm_utils.py`): wraps remote/local model calls
- Prompt Library (`prompts.py` / `rag_tools/prompts.py`)
- RAG Engine (`rag_utils.py`, `rag_tools/utils.py`) & Document Store
- Experiment Utilities (`experiments_utils.py`): handles jobs, logging, result serialization
5. Experiment Repository
- `examples/…` templates for different tasks
- Config files, launcher scripts, result directories
6. External Services & Data
- LLM API or self-hosted model (via Ollama)
- External dataset sources (e.g., Google Drive links)
- Local compute environment (Python interpreter, CUDA if needed)

b. Relationships & Interactions
- CLI invokes Core Orchestrator
- Orchestrator spins up Agents in sequence or in parallel
- Each Agent calls LLM Interface and/or RAG Engine
- Agents produce artifacts (ideas, code snippets, experiment configs) stored in working directory
- Execution Agent launches experiment scripts from `examples/…` via shell or Python subprocess
- Results (metrics, logs) flow back into Orchestrator / Assessment Agent for evaluation and next iteration

c. Architectural patterns & design principles
- Modular multi-agent pipeline (each agent as a standalone module)
- Layered separation:
- Presentation (CLI)
- Orchestration (Agent Manager)
- Domain logic (Idea / Survey / Execution Agents)
- Infrastructure (LLM wrapper, RAG tools, experiment utils)
- Extensibility: new tasks added under `examples/`; new agents plugged into orchestration loop
- Configuration-driven: parameters passed via JSON/YAML configs and shell arguments

d. Key technologies & libraries
- Python 3.11 ecosystem
- LLM API clients (e.g., OpenAI, self-hosted via Ollama)
- Retrieval-augmented generation (RAG) utilities
- Subprocess / shell for experiment execution
- JSON/YAML for configuration, logging

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Launcher Layer
    subgraph "Launcher Layer"
        CLI_py["launch_dolphin.py"]:::orchestration
        CLI_sh["launch_dolphin.sh"]:::orchestration
    end

    %% Core Orchestrator
    Orchestrator["Agent Manager & Scheduler"]:::orchestration

    %% Agents
    subgraph "Agents"
        Survey["Survey Agent"]:::agent
        Idea["Idea Agent"]:::agent
        Methodology["Methodology Agent"]:::agent
        Assessment["Assessment Agent"]:::agent
        Execution["Execution Agent"]:::agent
    end

    %% Supporting Utilities
    LLM["LLM Interface"]:::util
    PromptLib["Prompt Library"]:::util
    RAG["RAG Engine & Document Store"]:::util
    ExpUtils["Experiment Utilities"]:::util

    %% Experiment Templates
    Examples["Experiment Template Registry (examples/)"]:::storage

    %% External Services
    LLMAPI["LLM API / Ollama"]:::external
    Datasets["External Datasets"]:::external
    Docs["Ollama Integration Docs"]:::external

    %% Connections
    CLI_py -->|invokes| Orchestrator
    CLI_sh -->|invokes| Orchestrator

    Orchestrator -->|orchestrates| Survey
    Orchestrator -->|orchestrates| Idea
    Orchestrator -->|orchestrates| Methodology
    Orchestrator -->|orchestrates| Assessment
    Orchestrator -->|orchestrates| Execution

    Survey -->|fetch/summarize| RAG
    Survey -->|calls| LLM

    Idea -->|generates| PromptLib
    Idea -->|calls| LLM

    Methodology -->|assembles| PromptLib
    Methodology -->|calls| LLM

    Assessment -->|validates| ExpUtils
    Assessment -->|reports| Orchestrator

    Execution -->|executes| Examples
    Execution -->|logs| ExpUtils
    Execution -->|uses| LLMAPI

    LLM -->|requests| LLMAPI
    RAG -->|retrieves| Datasets

    %% Click Events
    click CLI_py "https://github.com/alpha-innovator/internagent/blob/main/launch_dolphin.py"
    click CLI_sh "https://github.com/alpha-innovator/internagent/blob/main/launch_dolphin.sh"
    click Survey "https://github.com/alpha-innovator/internagent/blob/main/dolphin_utils/rag_tools/lit_review.py"
    click Survey "https://github.com/alpha-innovator/internagent/blob/main/dolphin_utils/rag_tools/lit_review_tools.py"
    click Idea "https://github.com/alpha-innovator/internagent/blob/main/dolphin_utils/generate_ideas.py"
    click Idea "https://github.com/alpha-innovator/internagent/blob/main/dolphin_utils/prompts.py"
    click Methodology "https://github.com/alpha-innovator/internagent/blob/main/dolphin_utils/prompts.py"
    click Assessment "https://github.com/alpha-innovator/internagent/blob/main/dolphin_utils/experiments_utils.py"
    click Execution "https://github.com/alpha-innovator/internagent/blob/main/dolphin_utils/experiments_utils.py"
    click LLM "https://github.com/alpha-innovator/internagent/blob/main/dolphin_utils/llm_utils.py"
    click PromptLib "https://github.com/alpha-innovator/internagent/blob/main/dolphin_utils/prompts.py"
    click PromptLib "https://github.com/alpha-innovator/internagent/blob/main/dolphin_utils/rag_tools/prompts.py"
    click RAG "https://github.com/alpha-innovator/internagent/blob/main/dolphin_utils/rag_utils.py"
    click RAG "https://github.com/alpha-innovator/internagent/blob/main/dolphin_utils/rag_tools/utils.py"
    click ExpUtils "https://github.com/alpha-innovator/internagent/blob/main/dolphin_utils/experiments_utils.py"
    click Examples "https://github.com/alpha-innovator/internagent/tree/main/examples/"
    click Docs "https://github.com/alpha-innovator/internagent/blob/main/docs/ollama_doc.md"

    %% Styles
    classDef orchestration fill:#cce5ff,stroke:#6699cc;
    classDef agent fill:#d4edda,stroke:#3c763d;
    classDef util fill:#fef9e7,stroke:#f0ad4e;
    classDef external fill:#fcf8e3,stroke:#faebcc;
    classDef storage fill:#ececec,stroke:#cccccc;
```
