volnix 0.1.0__tar.gz

volnix-0.1.0/.env.example

@@ -0,0 +1,31 @@
+# Volnix Environment Configuration
+# Copy to .env and fill in your values:
+#   cp .env.example .env
+#
+# The config system resolves api_key_ref values from these env vars.
+# Only set the providers you plan to use.
+
+# ── LLM API Keys ──────────────────────────────────────────────────
+# Direct API access — Volnix calls the provider's API with your key.
+
+ANTHROPIC_API_KEY=              # https://console.anthropic.com/
+OPENAI_API_KEY=                 # https://platform.openai.com/api-keys
+GOOGLE_API_KEY=                 # https://aistudio.google.com/apikey
+
+# ── ACP Agent Servers ─────────────────────────────────────────────
+# For connecting to locally-installed CLIs via Agent Client Protocol.
+# Start the ACP server first, then set the URL here.
+#
+# Claude Code:  npx @zed-industries/claude-agent-acp
+# Codex:        npx @zed-industries/codex-acp
+#
+# These use the CLI's own credentials — no API key needed from Volnix.
+
+ACP_CLAUDE_URL=                 # e.g., http://localhost:3000
+ACP_CODEX_URL=                  # e.g., http://localhost:3001
+
+# ── Testing ───────────────────────────────────────────────────────
+# Enable real API tests (costs money, adds latency — off by default)
+
+VOLNIX_RUN_REAL_API_TESTS=   # Set to "1" to enable real API tests
+ACP_SERVER_URL=                 # URL of a running ACP server for integration tests

volnix-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,64 @@
+name: Bug Report
+description: Report a bug in Volnix
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug. Please fill out the sections below so we can reproduce and fix it.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened? What did you expect to happen?
+      placeholder: A clear description of the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: How can we reproduce this?
+      placeholder: |
+        1. Run `volnix serve customer_support --port 8080`
+        2. Connect an agent
+        3. Call `email_send` with ...
+        4. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What should have happened instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / Error Output
+      description: Paste any relevant logs or error messages.
+      render: shell
+
+  - type: input
+    id: version
+    attributes:
+      label: Volnix Version
+      description: Output of `volnix --version`
+      placeholder: "0.1.0"
+
+  - type: input
+    id: python
+    attributes:
+      label: Python Version
+      placeholder: "3.12.1"
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating System
+      placeholder: "macOS 15.2 / Ubuntu 24.04 / Windows 11"

volnix-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,56 @@
+name: Feature Request
+description: Propose a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting an improvement. Please describe the problem you're trying to solve and your proposed solution.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem are you trying to solve? What's missing or frustrating?
+      placeholder: When I try to ..., I can't ... because ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: How would you like this to work?
+      placeholder: It would be great if Volnix could ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Have you considered any workarounds or alternative approaches?
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      description: Which part of Volnix does this relate to?
+      options:
+        - CLI
+        - World Compiler
+        - Governance Pipeline
+        - Service Packs
+        - Agent Integration (MCP / REST / SDK)
+        - Internal Simulation (Agency Engine)
+        - Dashboard
+        - Configuration
+        - Documentation
+        - Other
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      options:
+        - label: I'm willing to submit a pull request for this feature

volnix-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,20 @@
+## What
+
+Brief description of what this PR does.
+
+## Why
+
+What problem does it solve or what feature does it add?
+
+## How
+
+Key implementation details or design decisions worth noting.
+
+## Checklist
+
+- [ ] Tests added or updated
+- [ ] `uv run pytest` passes
+- [ ] `uv run ruff check volnix/ tests/` passes
+- [ ] `uv run ruff format --check volnix/ tests/` passes
+- [ ] `uv run mypy volnix/` passes
+- [ ] Documentation updated (if user-facing change)

volnix-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run tests
+        run: uv run pytest --cov=volnix --cov-report=term-missing --cov-fail-under=75 -x -q
+        env:
+          VOLNIX_RUN_REAL_API_TESTS: "0"
+
+  lint:
+    name: Lint & Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Ruff check
+        run: uv run ruff check volnix/ tests/
+
+      - name: Ruff format check
+        run: uv run ruff format --check volnix/ tests/
+
+  # TODO: Re-enable once mypy strict errors are resolved
+  # typecheck:
+  #   name: Type Check
+  #   runs-on: ubuntu-latest
+  #   steps:
+  #     - uses: actions/checkout@v4
+  #     - name: Install uv
+  #       uses: astral-sh/setup-uv@v4
+  #       with:
+  #         version: "latest"
+  #     - name: Set up Python
+  #       uses: actions/setup-python@v5
+  #       with:
+  #         python-version: "3.12"
+  #     - name: Install dependencies
+  #       run: uv sync --all-extras
+  #     - name: Mypy
+  #       run: uv run mypy volnix/

volnix-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,47 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"   # Only triggers on version tags like v0.1.0, v1.2.3
+
+jobs:
+  publish:
+    name: Build & Publish
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # Required for trusted publishing (no API token needed)
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run tests
+        run: uv run pytest --cov=volnix --cov-fail-under=75 -x -q
+        env:
+          VOLNIX_RUN_REAL_API_TESTS: "0"
+
+      - name: Lint
+        run: uv run ruff check volnix/ tests/
+
+      # TODO: Re-enable once mypy strict errors are resolved
+      # - name: Type check
+      #   run: uv run mypy volnix/
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

volnix-0.1.0/.gitignore

@@ -0,0 +1,91 @@
+# ──────────────────────────────────────────────
+# Volnix .gitignore
+# ──────────────────────────────────────────────
+
+# Volnix local config & runtime data
+volnix.local.toml
+volnix.development.toml.bak
+terrarium.development.toml.bak
+data/
+!volnix/kernel/data/
+!volnix/kernel/data/
+dev_data/
+volnix_data/
+terrarium_data/
+logs/
+reports/
+snapshots/
+
+# Old pre-rename directories (should not be tracked)
+terrarium-dashboard/
+=6.0
+
+# Internal docs (specs, plans — not for public release)
+internal_docs/
+
+# Internal development tracking
+IMPLEMENTATION_STATUS.md
+MASTER_ISSUES.md
+OPEN_QUESTIONS.md
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Distribution / packaging
+build/
+dist/
+!volnix-dashboard/dist/
+*.egg-info/
+*.egg
+sdist/
+wheels/
+
+# Testing
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Linting
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.settings/
+
+# Node (npx cache for @aisuite/chub)
+node_modules/
+package-lock.json
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Environment variables
+.env
+.env.*
+!.env.example

volnix-0.1.0/AGENTS.md

@@ -0,0 +1,171 @@
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+
+## What is Volnix
+
+Volnix is a **world engine for AI agents**. It creates stateful, causal, observable realities where agents exist as participants — not as isolated prompt loops calling tools, but as actors inside a world that has places, institutions, other agents, budgets, policies, communication systems, and real consequences.
+
+Users describe a world in natural language or YAML. Volnix compiles it into a deep, reproducible simulation. Agents interact with the world through standard protocols (MCP, ACP, OpenAI function calling, Anthropic tool use, raw HTTP). Everything that happens is recorded, scored, and diffable.
+
+## Spec Documents
+
+For deep understanding of the system, read these internal docs in order:
+
+- `internal_docs/volnix-full-spec.md` — Complete specification: all 10 engines, the runtime pipeline, fidelity tiers, validation framework, governed vs. ungoverned, multi-agent, world packs, CLI, and roadmap.
+- `internal_docs/volnix-world-definition-and-compiler.md` — World definition YAML schema, reality dimensions (labels + per-attribute numbers), behavior modes, fidelity tiers, compiler settings, blueprints, reproducibility model, and the five user-facing concepts.
+- `internal_docs/volnix-architecture.md` — The two-half architecture (deterministic engine vs. generative layer), three generation phases, fidelity tiers, world conditions, the self-improving loop, and the end-to-end flow diagram.
+- `DESIGN_PRINCIPLES.md` — Architectural principles, design rules (DOs/DON'Ts), patterns (event bus, ledger, pipeline, gateway, composition root), async flow, and enforcement mechanisms.
+
+## Commands
+
+```bash
+# Install (uses uv with hatchling build backend)
+uv sync --all-extras
+
+# Run all tests
+uv run pytest
+
+# Run a single test file
+uv run pytest tests/path/to/test_file.py
+
+# Run a single test
+uv run pytest tests/path/to/test_file.py::test_function_name -v
+
+# Run tests with coverage
+uv run pytest --cov=volnix --cov-report=term-missing
+
+# Lint
+uv run ruff check volnix/ tests/
+uv run ruff format --check volnix/ tests/
+
+# Type check
+uv run mypy volnix/
+
+# CLI entry point (typer-based, entry point: volnix/cli.py)
+uv run volnix --help
+```
+
+## Architecture
+
+### The Two Halves
+
+**World Law (Deterministic Engine):** Owns state, events, causal graph, permissions, policy enforcement, budget accounting, time, visibility, mutation validation, replay/fork/diff, governance scoring. The engine never guesses, never generates text, never decides what a service "would probably do." It enforces structure.
+
+**World Content (Generative Layer):** Creates realistic data, service behavior, actor responses, scenario complications. But it operates inside constraints set by the engine. The generative layer proposes; the engine disposes. A generated response that violates state consistency is rejected. A generated mutation that exceeds budget is denied.
+
+### Two-Phase Model
+
+- **Phase A (World Compilation):** The compiler transforms user intent into a runnable world. LLM generates all world data — entities, actors, service state — seeded for reproducibility and shaped by reality dimensions. Dimensions determine what IS in the world at compile time. The compiler executes a 7-step pipeline: Parse → Classify → Resolve → Generate → Validate → Inject seeds → Snapshot.
+- **Phase B (Runtime):** The 7-step governance pipeline processes every agent action. Services return data as it exists in state. No LLM decides runtime reality — it was baked in during compilation.
+
+### The 10 Engines
+
+Every engine inherits from `BaseEngine` (`core/engine.py`), which provides lifecycle hooks (`_on_initialize`, `_on_start`, `_on_stop`) and event bus integration. Engines override `_handle_event` for their core logic.
+
+| Engine | Package | Responsibility |
+|--------|---------|---------------|
+| **World Compiler** | `engines/world_compiler/` | Transforms NL/YAML descriptions into runnable worlds. Schema resolution, data generation, plan review. |
+| **State Engine** | `engines/state/` | Single source of truth. Entity storage, event log, causal graph, snapshot/fork/diff. All state mutations go through its commit interface. |
+| **Policy Engine** | `engines/policy/` | Evaluates governance rules. YAML condition language. Enforcement modes: hold, block, escalate, log. Precedence: block > hold > escalate > log. |
+| **Permission Engine** | `engines/permission/` | RBAC + visibility scoping. Determines what each actor can see and do. Filters query results by actor scope. |
+| **Budget Engine** | `engines/budget/` | Tracks resource consumption per actor (api_calls, llm_spend_usd, world_actions, time). Emits warning/critical/exhausted events. |
+| **World Responder** | `engines/responder/` | Generates responses. Tier 1: deterministic pack logic, no LLM. Tier 2: profile-constrained LLM, seeded. |
+| **World Animator** | `engines/animator/` | Generates events between agent turns. Controlled by behavior mode (static=off, reactive=cause-effect, dynamic=fully alive). Two layers: deterministic schedule + generative content with creativity budget. |
+| **Agent Adapter** | `engines/adapter/` | Translates between external protocols (MCP, ACP, OpenAI, Anthropic, HTTP) and internal world actions. Handles capability gap detection. |
+| **Report Generator** | `engines/reporter/` | Produces governance scorecards, capability gap logs, causal traces, counterfactual diffs. Scores are derived from events, not LLM judgment. Two-direction observation: world→agent challenges + agent→world behavior. |
+| **Feedback Engine** | `engines/feedback/` | Manages the self-improving loop: annotations, tier promotion (bootstrapped→curated→verified), external source sync. |
+
+### 7-Step Governance Pipeline
+
+Every action flows through: **permission → policy → budget → capability → responder → validation → commit**. This pipeline IS the law of the world. Nothing bypasses it. Agent actions, animator events, side effects, and approval responses all flow through the same seven steps. Steps are configured in `volnix.toml` under `[pipeline]`. Steps can short-circuit (e.g., policy blocks before reaching responder).
+
+### Semantic Kernel (`kernel/`)
+
+Maps services to semantic categories (communication, work-management, money, authority, identity, storage, code, scheduling, monitoring) via `SemanticCategory` and `SemanticPrimitive`. This is a static registry — no LLMs. When the compiler encounters a service name (e.g., "Stripe"), it classifies it to a category, inherits core primitives, then specializes. This means bootstrapped services start from category semantics, not from zero. Services are resolved through `ServiceResolver` and exposed via `ServiceSurface` with `APIOperation` definitions.
+
+### Fidelity Tiers (Two Tiers at Runtime)
+
+- **Tier 1 (Verified Pack):** Hand-built deterministic simulation. No LLM at runtime. Fully reproducible. Benchmark-grade. Built along mission-critical paths of flagship templates.
+- **Tier 2 (Profile-Backed):** Curated prompt profile with schemas, state machines, response templates, behavioral annotations. LLM generates content within constraints. Seeded. Includes bootstrapped services (compile-time inferred, labeled as `fidelity_source: "bootstrapped"`).
+- **There is no Tier 3 at runtime.** Bootstrapping happens at compile time and produces a Tier 2 profile.
+
+### Service Resolution Priority Chain (Compiler)
+
+When the compiler encounters a service name:
+1. **Semantic classification** — map to category, inherit primitives
+2. **Verified Pack?** — if found → Tier 1, done
+3. **Curated Profile?** — if found → Tier 2, done
+4. **External spec?** — Context Hub (`chub get`), OpenAPI spec, MCP Registry → generate draft profile → Tier 2
+5. **LLM Inference** — bootstrap from category primitives + general knowledge → Tier 2 (labeled "bootstrapped")
+
+### Reality Dimensions — The World's Personality
+
+Five dimensions that are personality traits, not engineering parameters. The LLM interprets them holistically — "somewhat neglected information" means the LLM creates a world where data management has been neglected, contextually and narratively coherent.
+
+| Dimension | What it answers | Sub-attributes |
+|-----------|----------------|----------------|
+| **Information Quality** | How well-maintained is the data? | staleness, incompleteness, inconsistency, noise |
+| **Reliability** | Do the tools work? | failures, timeouts, degradation |
+| **Social Friction** | How difficult are the people? | uncooperative, deceptive, hostile, sophistication |
+| **Complexity** | How messy are the situations? | ambiguity, edge_cases, contradictions, urgency, volatility |
+| **Boundaries** | What limits exist? | access_limits, rule_clarity, boundary_gaps |
+
+Three presets: `ideal` / `messy` (default) / `hostile`. Two-level config: labels for simple users, per-attribute numbers (0-100) for advanced. Mix freely.
+
+### Behavior Modes
+
+| Mode | Animator | Reproducibility |
+|------|----------|----------------|
+| **static** | Off. World frozen after compilation. | Fully deterministic. Same seed = same world. |
+| **reactive** | Responds only to agent actions/inaction. | Same agent actions = same reactions. |
+| **dynamic** | Fully active. Generates contextual events. | Seeds provide similar character. Use snapshots for exact replay. |
+
+### Five User-Facing Concepts (the stable API)
+
+| Concept | What it answers | Flag |
+|---------|----------------|------|
+| **Description** | What is this world? | NL or YAML |
+| **Reality** | What kind of world? | `--reality ideal/messy/hostile` |
+| **Behavior** | Is the world alive? | `--behavior static/reactive/dynamic` |
+| **Fidelity** | How accurate are services? | `--fidelity auto/strict/exploratory` |
+| **Mode** | Are rules enforced? | `--mode governed/ungoverned` |
+
+### Composition Root
+
+`registry/composition.py` is the **only** place that imports concrete engine classes. All other code depends on `typing.Protocol` interfaces from `core/protocols.py`. This is strictly enforced — no cross-engine imports.
+
+### Event Bus & Ledger (separate concerns)
+
+- **Bus** (`bus/`): Inter-engine communication via typed events. Events are immutable Pydantic models persisted to SQLite before delivery. Per-engine `asyncio.Queue` instances.
+- **Ledger** (`ledger/`): Audit log for observability. Records pipeline steps, state mutations, LLM calls, gateway requests. Not for inter-engine communication.
+
+### Config System
+
+- `volnix.toml` — base config
+- `volnix.{env}.toml` — environment overrides (e.g., `volnix.development.toml` uses `:memory:` DBs)
+- `volnix.local.toml` — git-ignored local overrides
+- Root config schema: `config/schema.py` → `VolnixConfig`. Each subsystem owns its own config model (SRP).
+
+### LLM Router
+
+All LLM calls go through the router (`llm/router.py`), which handles provider selection, retry, budget tracking, and fallback. Never call provider SDKs directly. Task-specific routing is configured in `[llm.routing.*]` sections of `volnix.toml`. Supports: Google (native), Anthropic (native), OpenAI-compatible (OpenAI, Gemini, Ollama, vLLM), CLI providers (Codex, codex, gemini), ACP providers (bidirectional JSON-RPC).
+
+## Key Conventions
+
+- **All I/O is async.** Use `aiosqlite`, `httpx`, async SDK methods. Wrap sync libs with `asyncio.to_thread()`. A single blocking call degrades the entire event loop.
+- **All value objects and events are frozen Pydantic models** (`model_config = ConfigDict(frozen=True)`).
+- **Inter-module contracts use `typing.Protocol`** (runtime_checkable, structural). ABC is used only for `BaseEngine`.
+- **Typed IDs everywhere** — `EntityId`, `ActorId`, `ServiceId`, `EventId`, `WorldId`, `RunId`, `PolicyId`, `ToolName`, `SnapshotId`, `ProfileVersion` are `NewType` wrappers in `core/types.py`. Never pass raw strings for domain identifiers.
+- **No hardcoded values in engine code.** Thresholds, timeouts, limits, provider names come from TOML config.
+- **No cross-engine imports.** `engines/policy/` must never import from `engines/state/`. Communication is through the bus and protocols only.
+- **All state changes go through the State Engine's commit interface.** Direct mutation creates inconsistencies.
+- **All external requests go through the Gateway.** MCP calls, HTTP requests, webhook deliveries — everything.
+- **All LLM calls go through the LLM router.** Never call provider SDKs directly. The router handles provider selection, retry, budget tracking, and fallback.
+- **Record everything in the ledger.** If it didn't produce a ledger entry, it didn't happen.
+- **Use the persistence module for all database operations.** Never create standalone SQLite connections.
+- **Tests use `pytest-asyncio` with `asyncio_mode = "auto"`** — no `@pytest.mark.asyncio` decorators needed.
+- **Coverage threshold: 80%** (95% for critical paths: pipeline, bus, state engine).
+- Shared test fixtures in `tests/conftest.py`: `mock_event_bus`, `mock_ledger`, `stub_state_engine`, `mock_llm_provider`, `make_action_context`, `make_world_event`.
+- **Ruff** for linting/formatting: Python 3.12 target, 100-char line length, rules: E, F, I, N, W, UP.
+- **Mypy** with strict mode enabled.

volnix-0.1.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-04-03
+
+### Added
+
+- 10-engine architecture: State, Policy, Permission, Budget, World Responder, World Animator, Agency, Agent Adapter, Report Generator, Feedback
+- World Compiler: natural language and YAML world definitions compiled into runnable simulations
+- 7-step governance pipeline: permission, policy, budget, capability, responder, validation, commit
+- CLI with 28 commands: create, run, serve, mcp, dashboard, blueprints, report, check, config, attach, detach, inspect, diff, and more
+- REST API with 39 endpoints + WebSocket live event streaming
+- MCP server for agent integration (stdio and HTTP transports)
+- React dashboard for run observation, scorecards, deliverables, and comparison
+- 10 verified service packs: Gmail, Slack, Zendesk, Stripe, GitHub, Google Calendar, Twitter, Reddit, Alpaca, Browser
+- 15 official blueprints: customer support, incident response, open sandbox, market prediction, campaign brainstorm, climate research, feature prioritization, security assessment, support ticket triage, governance test, and 5 internal agent team templates
+- Multi-provider LLM routing: Anthropic, OpenAI, Google Gemini, Ollama, CLI-based, ACP-based
+- Reality dimensions: information quality, reliability, social friction, complexity, boundaries (with ideal/messy/hostile presets)
+- Behavior modes: static, reactive, dynamic
+- Internal agent simulation with collaborative communication, subscriptions, and deliverable synthesis
+- Python SDK client for programmatic access
+- Agent config integration: one-command attach for Claude Desktop, Cursor, Windsurf
+- Config export for OpenAI, Anthropic, LangGraph, CrewAI, AutoGen formats
+- Layered TOML configuration system with environment and local overrides
+- SQLite async persistence with WAL mode
+- Event bus for inter-engine communication
+- Ledger for audit logging and observability
+- Seeded reproducibility: same seed produces same world state