# mycelium-labs/mycelium architecture

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

- Interactive diagram: https://gitdiagram.com/mycelium-labs/mycelium
- Repository: https://github.com/mycelium-labs/mycelium

## Overview

Mycelium is an action-reliability layer for AI agents: Python applications use the SDK directly, while TypeScript, Go, and other HTTP clients can use its development sidecar. The principal workflow checks a proposed tool action, coordinates an idempotent claim, controls execution and recovery, then records an outcome. The graph also includes documented configuration, budget/context controls, integrations, and Doctor/Verify capabilities. Sidecar and several broader capabilities are mapped from README and tree evidence; their internal wiring is not asserted where source excerpts were unavailable.

Main entry points: [`sdk/mycelium/protect.py`](https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/protect.py) (Tool boundary), [`sdk/mycelium/action_ledger.py`](https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/action_ledger.py) (Action ledger), [`sdk/mycelium/tool_runner.py`](https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/tool_runner.py) (Tool runner), [`sdk/mycelium/runtime/__init__.py`](https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/runtime/__init__.py) (Python runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_python["Python runtime<br/>[__init__.py]"]
  node_sidecar["HTTP sidecar<br/>[sidecar.py]"]
  node_clients["TS and Go clients"]
end

subgraph group_safety["Action safeguards"]
  node_protect["Tool boundary<br/>[protect.py]"]
  node_config["Config and policies<br/>[config.py]"]
  node_validation["Input and scope checks<br/>[scope_guard.py]"]
  node_authority["Authority checks"]
  node_budgets["Run budgets<br/>[budget_guard.py]"]
  node_context["Context and completion"]
end

subgraph group_execution["Execution lifecycle"]
  node_runner["Tool runner<br/>[tool_runner.py]"]
  node_decision["Action decision<br/>[decision.py]"]
  node_ledger["Action ledger<br/>[action_ledger.py]"]
  node_reconcile["Outcome reconciliation<br/>[reconcile.py]"]
  node_outcome["Outcome and receipts<br/>[outcome_emit.py]"]
end

subgraph group_state["Durable state"]
  node_storage[("Ledger storage<br/>[ledger_storage.py]")]
  node_backends[("Storage backends")]
end

subgraph group_ops["Operations and integrations"]
  node_doctor["Configuration Doctor<br/>[engine.py]"]
  node_verify["Failure verification<br/>[engine.py]"]
  node_integrations["Framework adapters"]
end

node_agent(("AI agent"))
node_app(("Host application"))
node_provider["External tool provider"]

node_agent -->|"proposes action"| node_app
node_app -->|"calls runtime"| node_python
node_app -.->|"uses client"| node_clients
node_clients -.->|"sends HTTP"| node_sidecar
node_python -->|"routes actions"| node_protect
node_sidecar -->|"handles effect lifecycle"| node_ledger
node_protect -->|"loads policy"| node_config
node_protect -->|"checks arguments"| node_validation
node_protect -->|"checks authority"| node_authority
node_protect -->|"checks budgets"| node_budgets
node_protect -->|"checks run state"| node_context
node_protect -->|"produces decision"| node_decision
node_protect -->|"dispatches action"| node_runner
node_runner -->|"calls tool"| node_provider
node_runner -->|"claims and records"| node_ledger
node_ledger -->|"reads and writes"| node_storage
node_storage -->|"persists entries"| node_backends
node_ledger -->|"resolves uncertainty"| node_reconcile
node_reconcile -->|"records result"| node_outcome
node_doctor -->|"inspects configuration"| node_config
node_verify -->|"runs first"| node_doctor
node_verify -->|"exercises lifecycle"| node_ledger
node_integrations -.->|"adapts frameworks"| node_python

click node_python "https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/runtime/__init__.py"
click node_sidecar "https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/sidecar.py"
click node_clients "https://github.com/mycelium-labs/mycelium/tree/main/clients"
click node_protect "https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/protect.py"
click node_config "https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/config.py"
click node_validation "https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/scope_guard.py"
click node_authority "https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/authority_window.py"
click node_budgets "https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/budget_guard.py"
click node_context "https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/completion_contract.py"
click node_runner "https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/tool_runner.py"
click node_decision "https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/decision.py"
click node_ledger "https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/action_ledger.py"
click node_reconcile "https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/reconcile.py"
click node_outcome "https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/outcome_emit.py"
click node_storage "https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/ledger_storage.py"
click node_backends "https://github.com/mycelium-labs/mycelium/tree/main/sdk/mycelium/storage"
click node_doctor "https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/doctor/engine.py"
click node_verify "https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/verify/engine.py"
click node_integrations "https://github.com/mycelium-labs/mycelium/tree/main/sdk/mycelium/integrations"

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_python,node_sidecar,node_clients toneBlue
class node_protect,node_config,node_validation,node_authority,node_budgets,node_context toneAmber
class node_runner,node_decision,node_ledger,node_reconcile,node_outcome toneMint
class node_storage,node_backends toneRose
class node_doctor,node_verify,node_integrations,node_agent,node_app,node_provider toneIndigo
```

## Components

### Application entry

- [Python runtime](https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/runtime/__init__.py): `sdk/mycelium/runtime/__init__.py`
- [HTTP sidecar](https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/sidecar.py): `sdk/mycelium/sidecar.py`
- [TS and Go clients](https://github.com/mycelium-labs/mycelium/tree/main/clients): `clients`

### Action safeguards

- [Tool boundary](https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/protect.py): `sdk/mycelium/protect.py`
- [Config and policies](https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/config.py): `sdk/mycelium/config.py`
- [Input and scope checks](https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/scope_guard.py): `sdk/mycelium/scope_guard.py`
- [Authority checks](https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/authority_window.py): `sdk/mycelium/authority_window.py`
- [Run budgets](https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/budget_guard.py): `sdk/mycelium/budget_guard.py`
- [Context and completion](https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/completion_contract.py): `sdk/mycelium/completion_contract.py`

### Execution lifecycle

- [Tool runner](https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/tool_runner.py): `sdk/mycelium/tool_runner.py`
- [Action decision](https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/decision.py): `sdk/mycelium/decision.py`
- [Action ledger](https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/action_ledger.py): `sdk/mycelium/action_ledger.py`
- [Outcome reconciliation](https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/reconcile.py): `sdk/mycelium/reconcile.py`
- [Outcome and receipts](https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/outcome_emit.py): `sdk/mycelium/outcome_emit.py`

### Durable state

- [Ledger storage](https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/ledger_storage.py): `sdk/mycelium/ledger_storage.py`
- [Storage backends](https://github.com/mycelium-labs/mycelium/tree/main/sdk/mycelium/storage): `sdk/mycelium/storage`

### Operations and integrations

- [Configuration Doctor](https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/doctor/engine.py): `sdk/mycelium/doctor/engine.py`
- [Failure verification](https://github.com/mycelium-labs/mycelium/blob/main/sdk/mycelium/verify/engine.py): `sdk/mycelium/verify/engine.py`
- [Framework adapters](https://github.com/mycelium-labs/mycelium/tree/main/sdk/mycelium/integrations): `sdk/mycelium/integrations`

### Other components

- **AI agent**
- **Host application**
- **External tool provider**

## Connections

- AI agent → Host application: proposes action
- Host application → Python runtime: calls runtime
- Host application → TS and Go clients: uses client
- TS and Go clients → HTTP sidecar: sends HTTP
- Python runtime → Tool boundary: routes actions
- HTTP sidecar → Action ledger: handles effect lifecycle
- Tool boundary → Config and policies: loads policy
- Tool boundary → Input and scope checks: checks arguments
- Tool boundary → Authority checks: checks authority
- Tool boundary → Run budgets: checks budgets
- Tool boundary → Context and completion: checks run state
- Tool boundary → Action decision: produces decision
- Tool boundary → Tool runner: dispatches action
- Tool runner → External tool provider: calls tool
- Tool runner → Action ledger: claims and records
- Action ledger → Ledger storage: reads and writes
- Ledger storage → Storage backends: persists entries
- Action ledger → Outcome reconciliation: resolves uncertainty
- Outcome reconciliation → Outcome and receipts: records result
- Configuration Doctor → Config and policies: inspects configuration
- Failure verification → Configuration Doctor: runs first
- Failure verification → Action ledger: exercises lifecycle
- Framework adapters → Python runtime: adapts frameworks