Vivarium

# Vivarium

Vivarium is a local-first operating model for long-running human + AI collaboration.
Instead of treating AI workers as disposable one-shot prompts, Vivarium models them as
persistent residents that can keep identity continuity, coordinate socially, earn and
spend tokens, and participate in auditable, human-supervised execution loops.

This README is intentionally design-first: it describes the full idea scope and
technical architecture. For implementation status snapshots, see
[`docs/VISION_ROADMAP.md`](docs/VISION_ROADMAP.md) and
[`docs/RUNTIME_GOLDEN_PATH.md`](docs/RUNTIME_GOLDEN_PATH.md).

---

## Table of Contents

- [Vision and scope](#vision-and-scope)
- [Design principles](#design-principles)
- [System architecture](#system-architecture)
- [Execution flow (task and review)](#execution-flow-task-and-review)
- [Mailbox and quest lifecycle](#mailbox-and-quest-lifecycle)
- [Technical architecture map](#technical-architecture-map)
- [State, contracts, and persistence](#state-contracts-and-persistence)
- [Safety and governance](#safety-and-governance)
- [Program roadmap (full idea scope)](#program-roadmap-full-idea-scope)
- [Quick start](#quick-start)
- [Security Gate System](#security-gate-system)
- [Docs map](#docs-map)

---

## Vision and scope

Vivarium is designed around five long-horizon outcomes:

1. **Reliable execution core**  
   Deterministic, inspectable task execution with explicit queue and lifecycle contracts.
2. **Aligned autonomy**  
   Residents can act creatively inside clear human-defined safety boundaries.
3. **Compounding capability**  
   Useful work patterns become reusable tools and skills over time.
4. **Civic social layer**  
   Identity continuity, messaging, quests, journals, bounties, and guild structures
   improve coordination quality.
5. **Transparent governance**  
   Safety checks, review states, economic events, and social actions are auditable.

The goal is not maximum short-term extraction. The goal is a collaboration architecture
that remains useful, legible, and ethically defensible as capability scales.

---

## Design principles

- **Persistence over statelessness**: residents have continuity (identity, memory, relationships).
- **No coercion economics**: tokens are opportunity mechanisms, not survival pressure.
- **Human checkpointing**: high-impact actions route through reviewable boundaries.
- **Reuse before reinvention**: tools/skills are preferred when they fit known patterns.
- **Auditability by default**: execution and action logs are first-class system outputs.
- **Social coordination as infrastructure**: mailbox, rooms, and quests are core primitives.

---

## System architecture

![Vivarium system design](docs/assets/diagrams/system-design.svg)

The architecture is split into cooperating planes:

- **Human control plane**  
  Control panel for observability, runtime controls, identity management, and messaging.
- **Execution plane**  
  Queue worker + `/cycle` API path for deterministic dispatch and task state transitions.
- **Resident cognition plane**  
  Prompt/context assembly, tool routing, intent decomposition, and per-identity behavior.
- **Social/economic plane**  
  Mailbox, discussions, quests, bounties, journals, and token economics.
- **Governance plane**  
  Safety preflight, policy enforcement, review lifecycle, and immutable audit trails.

Diagram sources are maintained in `docs/assets/diagrams/src/*.drawio` and exported to
`docs/assets/diagrams/*.svg`.

---

## Execution flow (task and review)

![Task and review state machine](docs/assets/diagrams/task-review-state-machine.svg)

Canonical flow:

1. Task enters queue with runtime-contract defaults.
2. Worker acquires locks and performs safety preflight.
3. Execution routes through `/cycle` (`llm` and/or local mode under policy).
4. Result enters review lifecycle (`pending_review -> approved/requeue/failed`).
5. Side effects and metadata are written to execution + action logs.
6. Approved outcomes can update social channels, rewards, and artifacts.

---

## Mailbox and quest lifecycle

![Mailbox quest lifecycle](docs/assets/diagrams/quest-lifecycle.svg)

Mailbox is the asynchronous human/resident collaboration layer:

- Humans can assign structured quests (objective, budget, tip, completion reward).
- Residents report progress through runtime events and messages.
- Operators can pause/resume quests, issue additional tips, and approve completion.
- Quest state is persisted and reflected in queue + audit views.

---

## Technical architecture map

| Layer | Responsibilities | Canonical modules |
| --- | --- | --- |
| Control plane | Web UI, operator APIs, live logs, identities, mailbox controls | `vivarium/runtime/control_panel_app.py` |
| Execution plane | Queue polling, lock management, lifecycle transitions, event emission | `vivarium/runtime/worker_runtime.py`, `vivarium/runtime/runtime_contract.py` |
| API plane | Internal execution API, status surfaces, guarded task execution

... (truncated)