Architecture Guide

Three-Layer Architecture

Singing Bird separates concerns into three strict layers:

+--------------------------------------------------+\n|  Content Pack (YAML)                             |\n|  Locations, entities, synths, processes,          |\n|  latent facts, initial conditions                 |\n+--------------------------------------------------+\n                      |\n                      v\n+--------------------------------------------------+\n|  Ruleset (physical_social_v1)                    |\n|  Component schemas, affordance definitions,       |\n|  validation rules                                 |\n+--------------------------------------------------+\n                      |\n                      v\n+--------------------------------------------------+\n|  Kernel                                          |\n|  Scheduling, transactions, event propagation,     |\n|  perception delivery, snapshots, replay           |\n+--------------------------------------------------+\n

The kernel does not know what any scenario entity means. It knows locations, adjacency, entities with typed components, sensory channels, and world processes. The ruleset defines what component types are valid. The content pack defines the specific world.

A content pack references a ruleset_ref. The loader validates all components against the ruleset schemas at load time. Unknown component types generate warnings; missing required properties generate errors.

The Director Cycle

Each cycle follows the normative execution sequence from the spec:

1. Deep-copy canonical state into working copies\n2. Advance simulation clock on working copy\n3. Evaluate due world processes (statechart transitions)\n4. Begin fixed-point microcycle loop:\n   a. Compose sensory bundles (channel-filtered + action surface)\n   b. Run synth cognitive cycles concurrently (LLM calls)\n   c. Collect intents from synths\n   d. Resolve communication intents -> CommunicationEvents\n   e. Resolve other intents sequentially (priority order)\n   f. Check for new events (communication, world changes)\n   g. If new events: re-compose affected bundles, continue loop\n   h. If quiescent or budget exhausted: exit loop\n5. Validate invariants against working state\n6. On success: promote working copies to canonical, commit snapshot\n7. On failure: discard working copies (canonical state unchanged)\n

Transactional rollback is real: the runtime deep-copies world, director, synths, clock, and pending outcomes before any mutation. If invariant validation fails, the working copies are discarded. The canonical state on self.world, self.director, self.synths, self.clock, and self._pending_outcomes is never touched until commit.

Fixed-point microcycles allow intra-cycle propagation. If Thomas speaks to Margaret in microcycle 1, she hears it and can respond in microcycle 2 of the same director cycle. The loop continues until no new events are generated (quiescent) or the event budget is exhausted.

Perception Pipeline

Perception enforces epistemic separation (SYS-03): a synth never reads canonical state directly.

Stage 1: Structured Observations

The perception engine scans the synth's canonical location and adjacent locations, filtered by the synth's sensory capabilities:

Visual: entities, light sources, ambient light, celestial state (only if synth has visual channel)
Auditory: sound sources, speech events, weather sounds (only if synth has auditory channel)
Tactile: temperature, environmental touch (only if synth has tactile channel)
Proprioceptive: self-location awareness (always available)

A blind synth (no visual channel) receives zero visual observations. This is enforced at the perception layer, not by prompt tricks.

Stage 2: Action Surface

The director builds a grounded action menu for each synth each cycle:

Available actions:\n  - move_to_<uuid>: Move to Ground Floor\n  - inspect_<uuid>: Examine Beacon Lamp closely\n  - repair_<uuid>: Attempt to repair Beacon Lamp (jammed)\n  - switch_<uuid>: Switch Flashlight on\n  - take_<uuid>: Pick up Wrench\n  - open_<uuid>: Open Tool Chest\n  - wait: Do nothing this turn\n  - communicate: Speak (Margaret, James can hear you)\n

Every action has a stable symbolic action_id. Every entity ref is a UUID. The synth LLM selects from this menu by ID. The resolver looks up refs directly -- no substring matching, no English parsing.

Stage 3: Perception Policy (Optional)

A PerceptionPolicy hook can modify observations before delivery. The default is a no-op pass-through. An example LowLightAmbiguityPolicy reduces visual salience in dim conditions.

Intent Resolution

The resolver is component-based. It dispatches on action_id prefix:

repair_<ref> -> check Repairable component, enforce tool requirements, apply cascade to linked LightSource/Switchable
switch_<ref> -> toggle Switchable component, cascade to linked LightSource
take_<ref> -> check Portable, check not already carried, set canonical carrying relationship
consume_<ref> -> decrement Consumable uses, apply effect
open_<ref> -> set container open=True (canonical state change), reveal contents
move_to_<ref> -> check adjacency, check constraints, move entity + carried items

Tool-gated repair: if a Repairable component specifies repair_requirements.tools, the resolver checks whether the synth's body entity carries entities with matching Tool components. Missing tools result in blocked outcome.

Conflict resolution: intents are resolved sequentially in priority order. If two synths try to take the same item, the first succeeds and the second gets blocked (item already carried).

LLM Integration

Single-Call Architecture

Each synth gets one LLM call per microcycle. The system prompt IS the synth's current mind:

System prompt = identity + body + inner state + beliefs + projects + mental models + memories + instructions\nUser message  = structured observations + action surface + previous outcomes\nResponse      = InnerMonologue + belief updates + mood + intents + memories + theory of mind\n

No conversation history is maintained. State is carried in the system prompt via beliefs, memories, and theory of mind. This keeps token costs bounded.

Structured Output

The LLM returns a SynthCognitiveResponse via OpenAI's .parse() with a pydantic response model. All fields are typed and validated. The InnerMonologue (react -> interpret -> deliberate -> resolve) forces genuine cognitive processing before action selection.

Live vs Replay Modes

Live mode: calls OpenAI, logs every prompt + response to audit/llm_calls.jsonl
Replay mode: reads logged responses, no API calls, deterministic

In live mode, the world's random_seed is passed to OpenAI calls for approximate reproducibility. True determinism requires replay mode.

Containment Model

Containment is first-class in the canonical world model:

Location contains entity: LocationNode.contained_entity_ids
Entity contains entity: EntityNode.contained_entity_ids
Synth carries entity: EntityNode.carried_by_synth_id + carrier's contained_entity_ids
Carried items move with carrier: move resolution updates carried entity locations automatically

Opening a container sets open=True on the container component (canonical state change). The action surface respects this: an already-open container does not re-offer the \"open\" affordance.

Theory of Mind

Each synth carries thin mental models of other known synths:

MentalModel:\n  name, believed_location, believed_mood, believed_goals,\n  believed_knowledge, believed_beliefs_about_me, confidence\n

The recursive layer is believed_beliefs_about_me -- what I think they think about me. This is populated from the LLM's TheoryOfMindEntry response and fed back into the next cycle's system prompt. Depth is capped at 1.

Snapshot and Persistence

Snapshots: full system state (World + Director + Synths) serialized as JSON, atomic write via temp-file-then-rename
Audit log: JSONL append-only event trail (cycle events, synth responses, intent resolutions, communications)
LLM call log: JSONL with full prompt, model, seed, temperature, response for every LLM call
Schema migration: migration registry chains versioned transforms (0.1.0 -> 0.2.0 -> 0.3.0); snapshot loader auto-migrates

Module Map

Models (`src/singing_bird/models/`)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

File	What it defines
`enums.py`	All enumerations used across the system
`components.py`	Component/affordance ontology and query utilities
`world.py`	World, LocationNode, EntityNode, WorldProcess, LatentFact, Environment
`synth.py`	Synth, Identity, Belief, MentalModel, Phenomenology, Affect, Project, Memory
`director.py`	Director configuration and runtime state
`payloads.py`	SensoryBundle, ActionSurface, ActuationIntent, ActionOutcome, CommunicationEvent
`ruleset.py`	Ruleset with ComponentSchema registry; PHYSICAL_SOCIAL_V1 definition

Engine (`src/singing_bird/engine/`)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

File	What it does
`director_runtime.py`	The cycle orchestrator: rollback, microcycles, commit
`clock.py`	Simulation clock with configurable chronon and turn advance
`perception.py`	Channel-filtered observation assembly + action surface generation
`perception_policy.py`	PerceptionPolicy hook + LowLightAmbiguityPolicy example
`communication.py`	Speech resolution: communicate intent -> CommunicationEvent
`resolver.py`	Symbolic intent resolution against canonical state
`processes.py`	Statechart-driven world process evaluation
`statechart.py`	Generic hierarchical state machine interpreter
`invariants.py`	Scenario-agnostic invariant checks + containment consistency

LLM (`src/singing_bird/llm/`)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

File	What it does
`client.py`	Async OpenAI client with live/replay modes and call logging
`schemas.py`	Pydantic response models for structured LLM output
`prompts.py`	System prompt builder and templates

Synth (`src/singing_bird/synth/`)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

File	What it does
`agent.py`	Cognitive cycle: build prompt, call LLM, apply state updates, convert intents
`theory_of_mind.py`	Mental model management from LLM responses

Content (`src/singing_bird/content/`)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n

File	What it does
`loader.py`	YAML scenario loader with stable ID compilation and ruleset validation

Persistence (`src/singing_bird/persistence/`)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

File	What it does
`snapshot.py`	Save/load/restore full system state as JSON
`audit.py`	JSONL event log + token/cost summary
`migration.py`	Schema migration registry and chain

API Control Plane (`src/singing_bird/api/`)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

File	What it does
`app.py`	FastAPI application with all routes under `/v1/`
`session_manager.py`	Session lifecycle: create, list, close, snapshot restore
`refs.py`	Stable ref resolution (name → UUID lookup)
`auth.py`	Bearer token auth with read/operate/admin scopes
`diff.py`	Change computation: what changed since a cursor or snapshot
`streaming.py`	SSE event stream generator
`services/observation.py`	Overview, object detail, events, cycle reports
`services/intervention.py`	Typed admin patches with dry_run/commit/commit_and_step

API Control Plane

The API layer sits above the kernel and exposes it as an HTTP/JSON service. It does not reimplement simulation logic.

Three Execution Lanes

Query Lane (GET)          Turn Lane (POST /turns)       Admin Patch Lane (POST /patches)\n  |                         |                              |\n  | read-only               | director-mediated            | working copy\n  | no mutation              | payload → stimulus           | invariant validation\n  | no cycle                 | triggers cycle               | commit or discard\n  |                         | full rollback semantics       | optional step-after\n  v                         v                              v\n  JSON response             CycleResult                    PatchResult\n

Query: overview, resolve, object detail, events, changes, reports, SSE stream
Turn: external input converted to mediated stimulus, delivered through perception
Admin patch: typed operations (move_entity, create_entity, set_component_property, add_belief, etc.) applied to working copy, validated, committed as snapshot

Session Model

One session = one simulation lineage. Each session owns a scenario, a DirectorRuntime, a snapshot chain, and an audit trail. Sessions start paused. Snapshot restore provides undo.

Stimulus Queue

External stimuli are queued on the session and delivered through compose_sensory_bundle on the next step or turn. They enter through the same mediated perception path as all other observations — the API never writes directly into synth state.

Auth and Scopes

read — query lane only
operate — query + control (step, pause, turns)
admin — full access including patches, stimuli, inner monologue

Enabled via SINGING_BIRD_API_TOKEN environment variable. Open access when auth is disabled.

Singing Bird

A declarative, scenario-driven, LLM-mediated embodied simulation kernel.

Singing Bird simulates canonical worlds containing synthetic agents (synths) whose subjective experience may differ from reality. A director maintains authoritative world truth. Synths receive filtered sensory input, deliberate via real LLM calls, and emit grounded action intents. The engine resolves those intents against canonical physics, propagates consequences, and commits transactional snapshots.

Scenarios are declarative YAML content packs. The engine does not know what a lighthouse is, or a clinic, or a dock. It knows locations, adjacency, entities with typed components, sensory channels, and world processes. All scenario-specific content lives in the packs, not in engine code.

Key Concepts

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Concept	What it is
Director	The sole authority over canonical world truth. Runs the cycle, delivers perceptions, resolves actions, commits snapshots.
World	The canonical simulation state: topology, entities, environment, processes. Ground truth.
Synth	A subjective agent with identity, beliefs, mood, projects, memories, and theory of mind. Receives sensory bundles, emits intents. Never directly reads canonical state.
Content Pack	A YAML file defining a complete scenario: locations, entities, synths, processes, latent facts. Loaded and validated against a ruleset.
Ruleset	The ontology layer: defines what component types exist, validates content at load time. Currently ships `physical_social_v1`.
Action Surface	A grounded menu of available actions presented to each synth each cycle. Synths select by symbolic ID, not free text.

Quick Start

# By default, singing_bird calls the Centroid LLM router (llm.benac.dev).\n# The router picks whichever backend is currently scaled up (local GGUF or\n# OpenAI pipe). Models are addressed by capability alias — "@chat" in the\n# shipped scenarios — so consumers don't need to be reconfigured when the\n# backend changes.\n#\n# Override with: export OPENAI_BASE_URL=https://api.openai.com/v1  (direct)\n#                export OPENAI_API_KEY=sk-...                     (needed for direct)\n\n# Run the lighthouse scenario (3 cycles)\nPYTHONPATH=src python -m singing_bird.cli run --scenario scenarios/lighthouse.yaml --cycles 3\n\n# Run the workshop blackout (different world, same kernel)\nPYTHONPATH=src python -m singing_bird.cli run --scenario scenarios/workshop_blackout.yaml --cycles 3\n\n# Start the API control plane (observe, step, intervene via HTTP)\nPYTHONPATH=src uvicorn singing_bird.api.app:app --host 0.0.0.0 --port 8420\n\n# Run unit tests (no API key needed)\nPYTHONPATH=src pytest tests/ -m "not llm" -v\n\n# Run full test suite including LLM integration (needs API key)\nPYTHONPATH=src pytest tests/ --run-llm -v\n

Architecture

Content Pack (YAML) --> Loader/Compiler --> Initial Snapshot\n                                                  |\n                                           DirectorRuntime\n                                        (pure transition kernel)\n                                                  |\n                   +------------------------------+------------------------------+\n                   |                              |                              |\n              Perception                     SynthAgent                     Resolver\n          (channel-filtered,              (LLM cognition,             (component-based,\n           action surface)                structured I/O)              symbolic refs)\n                   |                              |                              |\n              SensoryBundle              CognitiveResponse               ActionOutcome\n          (observations +                (intents, beliefs,            (success/failure +\n           grounded menu)                speech, memories)             canonical effects)\n

Three layers, strictly separated:

Kernel: scheduling, transactions, event propagation, perception delivery, snapshots, replay
Ruleset: component schemas, affordance definitions, validation rules
Content Pack: locations, entities, synths, processes, initial conditions

See Architecture Guide for details.

API Control Plane

An HTTP/JSON service lets external agents observe, control, and intervene in running simulations:

# Start the server\nPYTHONPATH=src uvicorn singing_bird.api.app:app --host 0.0.0.0 --port 8420\n\n# Create a session, step it, see what happened\ncurl -X POST localhost:8420/v1/sessions -d '{"scenario_path":"scenarios/lighthouse.yaml"}'\ncurl -X POST localhost:8420/v1/sessions/{id}/step -d '{"n":1}'\ncurl localhost:8420/v1/sessions/{id}/reports/last-cycle\n

Three execution lanes:\n- Query: read-only inspection (overview, resolve, object detail, events, changes, reports)\n- Turn: external input routed through the director as mediated stimuli\n- Admin patch: typed interventions (move/create entities, change weather, inject beliefs) with dry_run/commit/commit_and_step modes

Plus SSE live event streaming, queued stimuli, auth scopes, idempotency, and a 20-tool manifest for LLM agent consumption. See the Observer Guide for full details.

Scenario Packs

Six scenarios ship with the project, all running on the same kernel with zero engine code changes:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Scenario	Setting	Synths	Focus
`lighthouse`	Island lighthouse, 1847	Thomas (keeper), Margaret (blind wife), James (castaway)	Blind embodiment, repair, weather, epistemic asymmetry
`park_bench`	Lakeside boardwalk	Alice (artist), Bob (retiree)	Social deliberation, low-stakes conversation
`workshop_blackout`	Auto repair shop	Mara (owner), Eli (apprentice), June (courier)	Local repair, switchable light, weather pressure
`storm_cellar`	Farmhouse in a storm	Ruth, Ben, Alma	Shelter, consumption, testimony, worsening weather
`night_clinic`	Late-night clinic	Ana (nurse), Victor (patient), Hale (orderly)	Care, waiting, low-light, small-object handling
`dockside_outpost`	Harbor dock at dawn	Inez, Pavel, Sora	Fog, signal maintenance, mixed interior/exterior

See the Scenario Authoring Contract for how to write new packs.

Test Suite

107 tests total (96 unit + 11 LLM integration):

# Unit tests only (fast, no API key)\nPYTHONPATH=src pytest tests/ -m "not llm" -v\n\n# Full suite (slower, needs OPENAI_API_KEY)\nPYTHONPATH=src pytest tests/ --run-llm -v\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Test file	What it proves
`test_models`	Serialization, components, belief provenance, theory of mind
`test_statechart`	Generic HSM: events, timers, guards, history states
`test_perception`	Channel filtering, communication delivery, action surface grounding
`test_content_loader`	YAML loading, referential integrity, ruleset validation
`test_invariants`	Engine invariants, rollback isolation
`test_kernel`	Component validation, anonymized scenario, symbolic grounding, replay log
`test_hardening`	Snapshot roundtrip, forced rollback, container reveal, tool-gated repair, containment invariants
`test_preplay`	Schema migration, conflict arbitration, cascade regression
`test_scenario_matrix`	All 6 packs load and run on same kernel; stable IDs across loads
`test_engine`	Full LLM integration: single cycle, blind synth, intent production, multi-scenario
`test_api`	API control plane: sessions, observation, intervention, stimuli, idempotency, auth

Project Status

Version: 0.3.0 (experimental)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Category	Met	Partial	Total
System requirements	18	2	20
Non-functional	7	1	8
Director	15	1	16
Synth	14	2	16
Hierarchical state	7	1	8
Invariants	8	0	8
Total	69	7	76

See the full Compliance Matrix.

What works: Content decoupling, symbolic grounding, transactional rollback, replay infrastructure, six-scenario matrix, containment model, tool-gated repair, schema migration.

What is partial: Percept distortion (hook exists, rich system not built), recursive cascade (communication + world events, not all types), synth internal statechart (field exists, not engine-evaluated), sensory range/occlusion (channel + location heuristics, not true physics).

Documentation

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Document	Audience	What it covers
Architecture Guide	Developers	How the system works, module map, design decisions
Development Guide	Developers	Setup, testing, extending, debugging, cost management
Scenario Authoring Contract	Scenario authors	Pack format, component types, what works and what doesn't
Requirements Spec	Architects	Full system/director/synth requirements
Compliance Matrix	QA/reviewers	Requirement-by-requirement implementation status
Observer Guide	Operators/agents	API control plane: observe, step, intervene, stream
Contributing	Contributors	How to work with the codebase, areas for expansion

Dependencies

Python 3.10+
openai >= 1.50
pydantic >= 1.10, < 2
pyyaml >= 6.0
fastapi >= 0.99, < 0.100 (API control plane)
uvicorn >= 0.20 (API server)
OPENAI_API_KEY or Centroid LLM router (for LLM-powered simulation)

Architecture Guide

Three-Layer Architecture

The Director Cycle

Perception Pipeline

Stage 1: Structured Observations

Stage 2: Action Surface

Stage 3: Perception Policy (Optional)

Intent Resolution

LLM Integration

Single-Call Architecture

Structured Output

Live vs Replay Modes

Containment Model

Theory of Mind

Snapshot and Persistence

Module Map

Models (src/singing_bird/models/)

Engine (src/singing_bird/engine/)

LLM (src/singing_bird/llm/)

Synth (src/singing_bird/synth/)

Content (src/singing_bird/content/)

Persistence (src/singing_bird/persistence/)

API Control Plane (src/singing_bird/api/)

API Control Plane

Three Execution Lanes

Session Model

Stimulus Queue

Auth and Scopes

Singing Bird

Key Concepts

Quick Start

Architecture

API Control Plane

Scenario Packs

Test Suite

Project Status

Documentation

Dependencies

Singing Bird

What this is

KernelCanonical world with transactional cycles

SynthsLLM-powered agents with theory of mind

AuditAppend-only replayable event trail

SurfacesHTTP/JSON + MCP + SSE, one OpenAPI schema

Who it's for

ObserverFor watchers

OperatorFor drivers

BuilderFor integrators

AdminFor debuggers & ops

Quick starts

Discover scenarios

Create and step a session

MCP tool discovery

Debug a request by ID

Every surface, one schema

Dashboard

OpenAPI schema

Swagger UI

ReDoc

Tool manifest

MCP endpoint

Everything, one click

Models (`src/singing_bird/models/`)

Engine (`src/singing_bird/engine/`)

LLM (`src/singing_bird/llm/`)

Synth (`src/singing_bird/synth/`)

Content (`src/singing_bird/content/`)

Persistence (`src/singing_bird/persistence/`)

API Control Plane (`src/singing_bird/api/`)