# mao-code/manta architecture

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

- Interactive diagram: https://gitdiagram.com/mao-code/manta
- Repository: https://github.com/mao-code/manta

## Overview

MANTA is an inference-time adaptive multi-agent system within an experiment and evaluation harness. The primary workflow configures a run, plans a task-specific topology, executes and audits collaboration turns, repairs the topology when needed, and records a final answer for benchmark evaluation. Across runs, process signals update a playbook; traces and evaluations feed descriptor analysis. The tree and excerpts do not expose benchmark-adapter source, so its internal wiring is left unspecified.

Main entry points: [`MAS/self_evolved/engine.py`](https://github.com/mao-code/manta/blob/main/MAS/self_evolved/engine.py) (Topology engine), [`cli/commands.py`](https://github.com/mao-code/manta/blob/main/cli/commands.py) (Run commands), [`MAS/runner.py`](https://github.com/mao-code/manta/blob/main/MAS/runner.py) (MAS runner), [`main.py`](https://github.com/mao-code/manta/blob/main/main.py) (Experiment CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Experiment entry"]
  node_cli["Experiment CLI<br/>[main.py]"]
  node_commands["Run commands<br/>[commands.py]"]
  node_experiment["Experiment config<br/>[experiment.py]"]
end

subgraph group_adaptive["Adaptive MAS"]
  node_engine["Topology engine<br/>[engine.py]"]
  node_planner["Topology planner<br/>[planner.py]"]
  node_auditor["Trace auditor<br/>[auditor.py]"]
  node_executor["Turn executor<br/>[executor.py]"]
  node_spec["Topology spec<br/>[spec.py]"]
  node_playbook["Experience playbook<br/>[playbook.py]"]
end

subgraph group_runtime["Collaboration runtime"]
  node_runner["MAS runner<br/>[runner.py]"]
  node_langgraph["Topology workflows"]
  node_llm["LLM client<br/>[llm.py]"]
end

subgraph group_evaluation["Evaluation and analysis"]
  node_benchmark["Benchmark adapters"]
  node_artifacts["Run artifacts<br/>[artifacts.py]"]
  node_descriptor["Descriptor analysis<br/>[experiment.py]"]
  node_analysis["Descriptor metrics<br/>[metrics.py]"]
  node_outputs["Experiment outputs<br/>[artifacts.py]"]
end

node_user(("Experiment operator"))
node_provider(("LLM provider"))

node_user -->|"starts run"| node_cli
node_cli -->|"dispatches"| node_commands
node_commands -->|"loads settings"| node_experiment
node_commands -->|"selects tasks"| node_benchmark
node_commands -->|"runs tasks"| node_runner
node_runner -->|"selects topology"| node_engine
node_engine -->|"loads experience"| node_playbook
node_engine -->|"requests plan"| node_planner
node_planner -->|"proposes topology"| node_spec
node_engine -->|"executes turn"| node_executor
node_executor -->|"runs collaboration"| node_langgraph
node_langgraph -->|"requests completions"| node_llm
node_llm -.->|"sends requests"| node_provider
node_engine -->|"audits trace"| node_auditor
node_auditor -->|"reports findings"| node_engine
node_engine -->|"repairs topology"| node_spec
node_engine -->|"records experience"| node_playbook
node_runner -->|"records trace"| node_artifacts
node_runner -->|"submits answer"| node_benchmark
node_benchmark -->|"returns evaluation"| node_runner
node_commands -->|"analyzes runs"| node_descriptor
node_descriptor -->|"computes metrics"| node_analysis
node_commands -->|"writes results"| node_outputs

click node_cli "https://github.com/mao-code/manta/blob/main/main.py"
click node_commands "https://github.com/mao-code/manta/blob/main/cli/commands.py"
click node_experiment "https://github.com/mao-code/manta/blob/main/MAS/experiment.py"
click node_runner "https://github.com/mao-code/manta/blob/main/MAS/runner.py"
click node_engine "https://github.com/mao-code/manta/blob/main/MAS/self_evolved/engine.py"
click node_planner "https://github.com/mao-code/manta/blob/main/MAS/self_evolved/planner.py"
click node_auditor "https://github.com/mao-code/manta/blob/main/MAS/self_evolved/auditor.py"
click node_executor "https://github.com/mao-code/manta/blob/main/MAS/self_evolved/executor.py"
click node_spec "https://github.com/mao-code/manta/blob/main/MAS/self_evolved/spec.py"
click node_playbook "https://github.com/mao-code/manta/blob/main/MAS/self_evolved/playbook.py"
click node_langgraph "https://github.com/mao-code/manta/blob/main/MAS/langgraph_engine.py"
click node_llm "https://github.com/mao-code/manta/blob/main/MAS/llm.py"
click node_artifacts "https://github.com/mao-code/manta/blob/main/MAS/artifacts.py"
click node_descriptor "https://github.com/mao-code/manta/blob/main/descriptor/experiment.py"
click node_analysis "https://github.com/mao-code/manta/blob/main/descriptor/metrics.py"
click node_outputs "https://github.com/mao-code/manta/blob/main/cli/artifacts.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_cli,node_commands,node_experiment toneBlue
class node_engine,node_planner,node_auditor,node_executor,node_spec,node_playbook toneAmber
class node_runner,node_langgraph,node_llm toneMint
class node_benchmark,node_artifacts,node_descriptor,node_analysis,node_outputs toneRose
class node_user,node_provider toneIndigo
```

## Components

### Experiment entry

- [Experiment CLI](https://github.com/mao-code/manta/blob/main/main.py): `main.py`
- [Run commands](https://github.com/mao-code/manta/blob/main/cli/commands.py): `cli/commands.py`
- [Experiment config](https://github.com/mao-code/manta/blob/main/MAS/experiment.py): `MAS/experiment.py`

### Adaptive MAS

- [Topology engine](https://github.com/mao-code/manta/blob/main/MAS/self_evolved/engine.py): `MAS/self_evolved/engine.py`
- [Topology planner](https://github.com/mao-code/manta/blob/main/MAS/self_evolved/planner.py): `MAS/self_evolved/planner.py`
- [Trace auditor](https://github.com/mao-code/manta/blob/main/MAS/self_evolved/auditor.py): `MAS/self_evolved/auditor.py`
- [Turn executor](https://github.com/mao-code/manta/blob/main/MAS/self_evolved/executor.py): `MAS/self_evolved/executor.py`
- [Topology spec](https://github.com/mao-code/manta/blob/main/MAS/self_evolved/spec.py): `MAS/self_evolved/spec.py`
- [Experience playbook](https://github.com/mao-code/manta/blob/main/MAS/self_evolved/playbook.py): `MAS/self_evolved/playbook.py`

### Collaboration runtime

- [MAS runner](https://github.com/mao-code/manta/blob/main/MAS/runner.py): `MAS/runner.py`
- [Topology workflows](https://github.com/mao-code/manta/blob/main/MAS/langgraph_engine.py): `MAS/langgraph_engine.py`
- [LLM client](https://github.com/mao-code/manta/blob/main/MAS/llm.py): `MAS/llm.py`

### Evaluation and analysis

- **Benchmark adapters**
- [Run artifacts](https://github.com/mao-code/manta/blob/main/MAS/artifacts.py): `MAS/artifacts.py`
- [Descriptor analysis](https://github.com/mao-code/manta/blob/main/descriptor/experiment.py): `descriptor/experiment.py`
- [Descriptor metrics](https://github.com/mao-code/manta/blob/main/descriptor/metrics.py): `descriptor/metrics.py`
- [Experiment outputs](https://github.com/mao-code/manta/blob/main/cli/artifacts.py): `cli/artifacts.py`

### Other components

- **Experiment operator**
- **LLM provider**

## Connections

- Experiment operator → Experiment CLI: starts run
- Experiment CLI → Run commands: dispatches
- Run commands → Experiment config: loads settings
- Run commands → Benchmark adapters: selects tasks
- Run commands → MAS runner: runs tasks
- MAS runner → Topology engine: selects topology
- Topology engine → Experience playbook: loads experience
- Topology engine → Topology planner: requests plan
- Topology planner → Topology spec: proposes topology
- Topology engine → Turn executor: executes turn
- Turn executor → Topology workflows: runs collaboration
- Topology workflows → LLM client: requests completions
- LLM client → LLM provider: sends requests
- Topology engine → Trace auditor: audits trace
- Trace auditor → Topology engine: reports findings
- Topology engine → Topology spec: repairs topology
- Topology engine → Experience playbook: records experience
- MAS runner → Run artifacts: records trace
- MAS runner → Benchmark adapters: submits answer
- Benchmark adapters → MAS runner: returns evaluation
- Run commands → Descriptor analysis: analyzes runs
- Descriptor analysis → Descriptor metrics: computes metrics
- Run commands → Experiment outputs: writes results