# puneet-swarup/mantrana architecture

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

- Interactive diagram: https://gitdiagram.com/puneet-swarup/mantrana
- Repository: https://github.com/puneet-swarup/mantrana

## Overview

Mantrana is a Python framework for iterative, moderator-routed AI deliberation. A user supplies a problem to the runnable entry point; the council loop loads configuration, seeds a shared log, asks the moderator to select roles, invokes those agents, and returns a final synthesis. Role mandates and the moderator protocol are prompt-driven. The README also describes tool-agent and browser/multi-model plans, but the inspected runtime implements only a text-only tool-agent placeholder and fake client; those planned integrations are not shown as working subsystems.

Main entry points: [`src/mantrana/orchestrator.py`](https://github.com/puneet-swarup/mantrana/blob/main/src/mantrana/orchestrator.py) (Council loop), [`src/mantrana/config.py`](https://github.com/puneet-swarup/mantrana/blob/main/src/mantrana/config.py) (Config loader), [`main.py`](https://github.com/puneet-swarup/mantrana/blob/main/main.py) (Runnable demo), [`src/mantrana/agents.py`](https://github.com/puneet-swarup/mantrana/blob/main/src/mantrana/agents.py) (Agent runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry point"]
  node_main["Runnable demo<br/>[main.py]"]
end

subgraph group_coordination["Council coordination"]
  node_council["Council loop<br/>[orchestrator.py]"]
  node_router["Moderator router<br/>[router.py]"]
  node_conversation[("Shared log<br/>[log.py]")]
end

subgraph group_roles["Roles and prompts"]
  node_agent_runtime["Agent runtime<br/>[agents.py]"]
  node_role_prompts["Role mandates"]
  node_moderator_prompt["Moderator protocol<br/>[moderator.md]"]
  node_role_catalog["Role catalog<br/>[role_catalog.md]"]
end

subgraph group_configuration["Configuration and clients"]
  node_config_loader["Config loader<br/>[config.py]"]
  node_council_settings["Council settings<br/>[council.yaml]"]
  node_model_settings["Model bindings<br/>[models.yaml]"]
  node_client_contract["Client contract<br/>[base.py]"]
  node_fake_client["Fake client<br/>[fake.py]"]
end

node_user(("Problem submitter"))
node_synthesis["Final synthesis"]

node_user -->|"submits problem"| node_main
node_main -->|"loads settings"| node_config_loader
node_main -->|"creates clients"| node_fake_client
node_main -->|"starts council"| node_council
node_council -->|"reads prompts"| node_config_loader
node_config_loader -->|"loads YAML"| node_council_settings
node_config_loader -->|"reads mandates"| node_role_prompts
node_config_loader -->|"reads protocol"| node_moderator_prompt
node_config_loader -->|"reads catalog"| node_role_catalog
node_council -->|"parses and enforces"| node_router
node_router -->|"reads invariants"| node_council_settings
node_council -->|"updates log"| node_conversation
node_council -->|"invokes roles"| node_agent_runtime
node_agent_runtime -->|"reads context"| node_conversation
node_agent_runtime -->|"queries through"| node_client_contract
node_council -->|"queries moderator"| node_client_contract
node_fake_client -->|"implements"| node_client_contract
node_model_settings -.->|"documents bindings"| node_config_loader
node_council -->|"returns final"| node_synthesis

click node_main "https://github.com/puneet-swarup/mantrana/blob/main/main.py"
click node_council "https://github.com/puneet-swarup/mantrana/blob/main/src/mantrana/orchestrator.py"
click node_router "https://github.com/puneet-swarup/mantrana/blob/main/src/mantrana/router.py"
click node_conversation "https://github.com/puneet-swarup/mantrana/blob/main/src/mantrana/log.py"
click node_agent_runtime "https://github.com/puneet-swarup/mantrana/blob/main/src/mantrana/agents.py"
click node_role_prompts "https://github.com/puneet-swarup/mantrana/tree/main/prompts/roles"
click node_moderator_prompt "https://github.com/puneet-swarup/mantrana/blob/main/prompts/moderator.md"
click node_role_catalog "https://github.com/puneet-swarup/mantrana/blob/main/prompts/role_catalog.md"
click node_config_loader "https://github.com/puneet-swarup/mantrana/blob/main/src/mantrana/config.py"
click node_council_settings "https://github.com/puneet-swarup/mantrana/blob/main/config/council.yaml"
click node_model_settings "https://github.com/puneet-swarup/mantrana/blob/main/config/models.yaml"
click node_client_contract "https://github.com/puneet-swarup/mantrana/blob/main/src/mantrana/clients/base.py"
click node_fake_client "https://github.com/puneet-swarup/mantrana/blob/main/src/mantrana/clients/fake.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 toneBlue
class node_council,node_router,node_conversation toneAmber
class node_agent_runtime,node_role_prompts,node_moderator_prompt,node_role_catalog toneMint
class node_config_loader,node_council_settings,node_model_settings,node_client_contract,node_fake_client toneRose
class node_user,node_synthesis toneIndigo
```

## Components

### Entry point

- [Runnable demo](https://github.com/puneet-swarup/mantrana/blob/main/main.py): `main.py`

### Council coordination

- [Council loop](https://github.com/puneet-swarup/mantrana/blob/main/src/mantrana/orchestrator.py): `src/mantrana/orchestrator.py`
- [Moderator router](https://github.com/puneet-swarup/mantrana/blob/main/src/mantrana/router.py): `src/mantrana/router.py`
- [Shared log](https://github.com/puneet-swarup/mantrana/blob/main/src/mantrana/log.py): `src/mantrana/log.py`

### Roles and prompts

- [Agent runtime](https://github.com/puneet-swarup/mantrana/blob/main/src/mantrana/agents.py): `src/mantrana/agents.py`
- [Role mandates](https://github.com/puneet-swarup/mantrana/tree/main/prompts/roles): `prompts/roles`
- [Moderator protocol](https://github.com/puneet-swarup/mantrana/blob/main/prompts/moderator.md): `prompts/moderator.md`
- [Role catalog](https://github.com/puneet-swarup/mantrana/blob/main/prompts/role_catalog.md): `prompts/role_catalog.md`

### Configuration and clients

- [Config loader](https://github.com/puneet-swarup/mantrana/blob/main/src/mantrana/config.py): `src/mantrana/config.py`
- [Council settings](https://github.com/puneet-swarup/mantrana/blob/main/config/council.yaml): `config/council.yaml`
- [Model bindings](https://github.com/puneet-swarup/mantrana/blob/main/config/models.yaml): `config/models.yaml`
- [Client contract](https://github.com/puneet-swarup/mantrana/blob/main/src/mantrana/clients/base.py): `src/mantrana/clients/base.py`
- [Fake client](https://github.com/puneet-swarup/mantrana/blob/main/src/mantrana/clients/fake.py): `src/mantrana/clients/fake.py`

### Other components

- **Problem submitter**
- **Final synthesis**

## Connections

- Problem submitter → Runnable demo: submits problem
- Runnable demo → Config loader: loads settings
- Runnable demo → Fake client: creates clients
- Runnable demo → Council loop: starts council
- Council loop → Config loader: reads prompts
- Config loader → Council settings: loads YAML
- Config loader → Role mandates: reads mandates
- Config loader → Moderator protocol: reads protocol
- Config loader → Role catalog: reads catalog
- Council loop → Moderator router: parses and enforces
- Moderator router → Council settings: reads invariants
- Council loop → Shared log: updates log
- Council loop → Agent runtime: invokes roles
- Agent runtime → Shared log: reads context
- Agent runtime → Client contract: queries through
- Council loop → Client contract: queries moderator
- Fake client → Client contract: implements
- Model bindings → Config loader: documents bindings
- Council loop → Final synthesis: returns final