# holobiomicslab/mimosa-ai architecture

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

- Interactive diagram: https://gitdiagram.com/holobiomicslab/mimosa-ai
- Repository: https://github.com/holobiomicslab/mimosa-ai

## Overview

Mimosa-AI turns a scientific objective into an executable, task-specific multi-agent workflow, runs it with discovered MCP tools, evaluates the result, and can refine the workflow from execution feedback. The main routes are task execution through the Darwinian workflow loop and optional goal decomposition through the planner; CSV evaluation provides a benchmark-oriented route. The README also documents reproducibility and audit trails. Edges reflect sampled imports/calls or explicit README claims; some internal evaluation and workspace details are unsampled, so those connections are omitted where evidence is insufficient.

Main entry points: [`sources/core/dgm.py`](https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/core/dgm.py) (Darwin workflow loop), [`main.py`](https://github.com/holobiomicslab/mimosa-ai/blob/main/main.py) (CLI entry), [`sources/cli/onboard_cli.py`](https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/cli/onboard_cli.py) (Onboarding), [`sources/core/workflow_factory.py`](https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/core/workflow_factory.py) (Workflow factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_main["CLI entry<br/>[main.py]"]
  node_onboarding["Onboarding<br/>[onboard_cli.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_planning["Planning and discovery"]
  node_planner["Goal planner<br/>[planner.py]"]
  node_toolmanager["MCP discovery<br/>[tools_manager.py]"]
  node_llm["LLM provider<br/>[llm_provider.py]"]
end

subgraph group_execution["Workflow execution"]
  node_darwin["Darwin workflow loop<br/>[dgm.py]"]
  node_orchestrator["Workflow orchestrator<br/>[orchestrator.py]"]
  node_factory["Workflow factory"]
  node_runner["Sandbox runner<br/>[workflow_runner.py]"]
  node_state["Agent state<br/>[state_schema.py]"]
  node_workflowinfo["Workflow records<br/>[workflow_info.py]"]
end

subgraph group_learning["Evaluation and learning"]
  node_evaluator["Workflow judge<br/>[evaluator.py]"]
  node_scenarios["Scenario loader<br/>[scenario_loader.py]"]
  node_csvmode["Benchmark mode<br/>[csv_mode.py]"]
end

node_researcher(("Researcher"))
node_toolomics{{"Toolomics MCP"}}
node_bench["ScienceAgentBench"]

node_researcher -->|"starts"| node_main
node_main -->|"launches"| node_onboarding
node_main -->|"routes goals"| node_planner
node_main -->|"routes tasks"| node_darwin
node_main -->|"starts evaluation"| node_csvmode
node_onboarding -->|"discovers tools"| node_toolmanager
node_onboarding -->|"launches goal"| node_planner
node_onboarding -->|"launches task"| node_darwin
node_config -->|"configures discovery"| node_toolmanager
node_toolmanager -->|"discovers MCPs"| node_toolomics
node_planner -->|"executes steps"| node_darwin
node_planner -->|"requests planning"| node_llm
node_darwin -->|"runs workflow"| node_orchestrator
node_darwin -->|"scores execution"| node_evaluator
node_darwin -->|"tracks runs"| node_workflowinfo
node_orchestrator -->|"crafts workflow"| node_factory
node_orchestrator -->|"runs sandbox"| node_runner
node_factory -->|"uses MCP tools"| node_toolmanager
node_factory -->|"generates workflow"| node_llm
node_factory -->|"uses agent state"| node_state
node_evaluator -->|"loads scenarios"| node_scenarios
node_csvmode -->|"runs tasks"| node_darwin
node_csvmode -->|"loads benchmark"| node_bench
node_csvmode -.->|"evaluates results"| node_evaluator

click node_main "https://github.com/holobiomicslab/mimosa-ai/blob/main/main.py"
click node_onboarding "https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/cli/onboard_cli.py"
click node_config "https://github.com/holobiomicslab/mimosa-ai/blob/main/config.py"
click node_planner "https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/core/planner.py"
click node_toolmanager "https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/core/tools_manager.py"
click node_llm "https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/core/llm_provider.py"
click node_darwin "https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/core/dgm.py"
click node_orchestrator "https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/core/orchestrator.py"
click node_factory "https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/core/workflow_factory.py"
click node_runner "https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/core/workflow_runner.py"
click node_state "https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/modules/state_schema.py"
click node_workflowinfo "https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/core/workflow_info.py"
click node_evaluator "https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/evaluation/evaluator.py"
click node_scenarios "https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/evaluation/scenario_loader.py"
click node_csvmode "https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/evaluation/csv_mode.py"

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_main,node_onboarding,node_config toneBlue
class node_planner,node_toolmanager,node_llm toneAmber
class node_darwin,node_orchestrator,node_factory,node_runner,node_state,node_workflowinfo toneMint
class node_evaluator,node_scenarios,node_csvmode toneRose
class node_researcher,node_toolomics,node_bench toneIndigo
```

## Components

### User entry

- [CLI entry](https://github.com/holobiomicslab/mimosa-ai/blob/main/main.py): `main.py`
- [Onboarding](https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/cli/onboard_cli.py): `sources/cli/onboard_cli.py`
- [Configuration](https://github.com/holobiomicslab/mimosa-ai/blob/main/config.py): `config.py`

### Planning and discovery

- [Goal planner](https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/core/planner.py): `sources/core/planner.py`
- [MCP discovery](https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/core/tools_manager.py): `sources/core/tools_manager.py`
- [LLM provider](https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/core/llm_provider.py): `sources/core/llm_provider.py`

### Workflow execution

- [Darwin workflow loop](https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/core/dgm.py): `sources/core/dgm.py`
- [Workflow orchestrator](https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/core/orchestrator.py): `sources/core/orchestrator.py`
- [Workflow factory](https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/core/workflow_factory.py): `sources/core/workflow_factory.py`
- [Sandbox runner](https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/core/workflow_runner.py): `sources/core/workflow_runner.py`
- [Agent state](https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/modules/state_schema.py): `sources/modules/state_schema.py`
- [Workflow records](https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/core/workflow_info.py): `sources/core/workflow_info.py`

### Evaluation and learning

- [Workflow judge](https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/evaluation/evaluator.py): `sources/evaluation/evaluator.py`
- [Scenario loader](https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/evaluation/scenario_loader.py): `sources/evaluation/scenario_loader.py`
- [Benchmark mode](https://github.com/holobiomicslab/mimosa-ai/blob/main/sources/evaluation/csv_mode.py): `sources/evaluation/csv_mode.py`

### Other components

- **Researcher**
- **Toolomics MCP**
- **ScienceAgentBench**

## Connections

- Researcher → CLI entry: starts (evidence: `README.md`)
- CLI entry → Onboarding: launches (evidence: `main.py`)
- CLI entry → Goal planner: routes goals (evidence: `main.py`)
- CLI entry → Darwin workflow loop: routes tasks (evidence: `main.py`)
- CLI entry → Benchmark mode: starts evaluation (evidence: `main.py`)
- Onboarding → MCP discovery: discovers tools (evidence: `sources/cli/onboard_cli.py`)
- Onboarding → Goal planner: launches goal (evidence: `sources/cli/onboard_cli.py`)
- Onboarding → Darwin workflow loop: launches task (evidence: `sources/cli/onboard_cli.py`)
- Configuration → MCP discovery: configures discovery (evidence: `sources/core/tools_manager.py`)
- MCP discovery → Toolomics MCP: discovers MCPs (evidence: `README.md`)
- Goal planner → Darwin workflow loop: executes steps (evidence: `sources/core/planner.py`)
- Goal planner → LLM provider: requests planning (evidence: `sources/core/planner.py`)
- Darwin workflow loop → Workflow orchestrator: runs workflow (evidence: `sources/core/dgm.py`)
- Darwin workflow loop → Workflow judge: scores execution (evidence: `sources/core/dgm.py`)
- Darwin workflow loop → Workflow records: tracks runs (evidence: `sources/core/dgm.py`)
- Workflow orchestrator → Workflow factory: crafts workflow (evidence: `sources/core/orchestrator.py`)
- Workflow orchestrator → Sandbox runner: runs sandbox (evidence: `sources/core/orchestrator.py`)
- Workflow factory → MCP discovery: uses MCP tools (evidence: `sources/core/workflow_factory.py`)
- Workflow factory → LLM provider: generates workflow (evidence: `sources/core/workflow_factory.py`)
- Workflow factory → Agent state: uses agent state (evidence: `sources/core/workflow_factory.py`)
- Workflow judge → Scenario loader: loads scenarios (evidence: `sources/evaluation/evaluator.py`)
- Benchmark mode → Darwin workflow loop: runs tasks (evidence: `sources/evaluation/csv_mode.py`)
- Benchmark mode → ScienceAgentBench: loads benchmark (evidence: `sources/evaluation/csv_mode.py`)
- Benchmark mode → Workflow judge: evaluates results