Manthan — Architecture (v0)

Manthan — Architecture (v0)

Five thin services on a single docker-compose stack.

                                                         ┌────────────────┐
                                                         │   External     │
                                                         │  consumers     │
                                                         │ (Conduir, ...) │
                                                         └───────┬────────┘
                                                                 │ HTTP (read-only)
                                                                 ▼
┌───────────┐                                            ┌────────────────┐
│  Viewer   │ ◄───── HTTP / SSE ──────┐                  │   Read API     │
│ (Next.js) │                         │                  │   (FastAPI)    │
└───────────┘                         │                  └────────┬───────┘
                                      │                           │
                                      │                           │  SQL
                                      ▼                           ▼
                              ┌──────────────────────────────────────┐
                              │            Substrate                 │
                              │     (FastAPI + Postgres + pgvector)  │
                              │    artefacts · lineage · embeddings  │
                              └──────────────┬───────────────────────┘
                                             ▲
                                             │ writes
                                             │
                              ┌──────────────┴───────────────────────┐
                              │         Agent Runtime                │
                              │  long-lived persona host · scheduler │
                              │       inbox/outbox · dormancy        │
                              └──────────────┬───────────────────────┘
                                             │
                                             ▼
                                    ┌────────────────┐
                                    │  Bus (NATS)    │
                                    │   JetStream    │
                                    │   pub/sub      │
                                    └────────────────┘

Services

Postgres is exposed on host port 27432 (separate from any maestro-platform Postgres).

Data model (substrate, v0)

Artefacts are first-class entities, not statuses on one table. Lineage links are a separate graph table — many-to-many.

artefact
├── id (uuid, pk)
├── kind (enum: idea | prototype | opportunity | message | critique | synthesis)
├── author_agent_id (uuid, fk → agent)
├── content_text (text)
├── content_embedding (vector(1536))
├── tags (text[])
├── metadata (jsonb)
├── created_at
└── updated_at

artefact_lineage
├── parent_id (uuid, fk)
├── child_id (uuid, fk)
└── relation (enum: derives_from | contradicts | refines | combines | replaces)
PK (parent_id, child_id, relation)

agent
├── id (uuid, pk)
├── name (text, unique)
├── persona_doc (text)               -- the seed prompt
├── llm_provider (text)
├── llm_model (text)
├── status (enum: active | dormant | retired)
├── created_at
└── last_active_at

Indexes:

• HNSW index on artefact.content_embedding for cosine similarity.
• GIN trigram index on artefact.content_text for keyword search.
• Btree on artefact.kind, artefact.created_at.
• Btree on artefact_lineage.child_id (lineage walks usually go up).

Bus topology (NATS subjects)

manthan.bus.broadcast              # all agents see; "town square"
manthan.bus.persona.<name>.inbox   # private inbox per persona
manthan.bus.persona.<name>.outbox  # observable outbox per persona
manthan.bus.events.artefact.created
manthan.bus.events.artefact.linked
manthan.bus.presence               # heartbeat / status changes

Streams persist 24 h or 100k messages, whichever first. Older churn lives in the substrate; the bus is for now.

Agent runtime model

• One runtime container hosts N personas as async tasks (v0).
• Each persona has its own state (memory, inbox cursor, scheduler tick, last-active).
• Scheduler wakes a persona on: inbox arrival, scheduled tick, or human nudge.
• Persona enters dormancy after MANTHAN_DORMANCY_AFTER_EMPTY_INBOX_SECONDS of nothing — stops thinking, stays subscribed.
• Hard cap: MANTHAN_MAX_TOKENS_PER_AGENT_PER_HOUR. When hit, persona sleeps until next hour.
• Hard cap: MANTHAN_MAX_USD_PER_DAY_TOTAL across all personas. When hit, all personas sleep until midnight UTC.

Per-process-per-persona is a v1 concern (failure isolation, independent scaling).

Read API surface

GET  /healthz
GET  /ideas/search?q=&tag=&limit=&since=
GET  /ideas/{id}
GET  /ideas/{id}/lineage
GET  /prototypes/list?status=&since=
GET  /prototypes/{id}
GET  /opportunities/current
GET  /agents
GET  /agents/{id}/recent

No mutating endpoints. External callers cannot write. (Substrate has its own admin API, not exposed publicly.)

Cost & dormancy controls

Implemented in shared/manthan_common/budget.py:

• Token counter per agent, per hour bucket.
• USD running tally per UTC day.
• Dormancy timer per agent.
• Single kill switch: MANTHAN_PAUSE_ALL=1 env var freezes all scheduler ticks.

What's deliberately missing (v0)

• Promotion gates between idea → prototype → opportunity.
• Voting / scoring / consensus.
• Prototype sandbox (containers, scratch DB, tool access).
• Cross-persona memory sharing rituals.
• Identity-reset / generation rotation.
• Authentication on the public read API.
• Persistent vector index across restarts (HNSW reindexed on first warm-up).

Each is a known follow-up; tracked in MANTHAN_PLATFORM_TRACKER.md and (when MD-space tickets are drafted per the planning notes) under the MD project.