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

Quick Start

# By default, singing_bird calls the Centroid LLM router (llm.benac.dev).
# The router picks whichever backend is currently scaled up (local GGUF or
# OpenAI pipe). Models are addressed by capability alias — "@chat" in the
# shipped scenarios — so consumers don't need to be reconfigured when the
# backend changes.
#
# Override with: export OPENAI_BASE_URL=https://api.openai.com/v1  (direct)
#                export OPENAI_API_KEY=sk-...                     (needed for direct)

# Run the lighthouse scenario (3 cycles)
PYTHONPATH=src python -m singing_bird.cli run --scenario scenarios/lighthouse.yaml --cycles 3

# Run the workshop blackout (different world, same kernel)
PYTHONPATH=src python -m singing_bird.cli run --scenario scenarios/workshop_blackout.yaml --cycles 3

# Start the API control plane (observe, step, intervene via HTTP)
PYTHONPATH=src uvicorn singing_bird.api.app:app --host 0.0.0.0 --port 8420

# Run unit tests (no API key needed)
PYTHONPATH=src pytest tests/ -m "not llm" -v

# Run full test suite including LLM integration (needs API key)
PYTHONPATH=src pytest tests/ --run-llm -v

Architecture

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

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
PYTHONPATH=src uvicorn singing_bird.api.app:app --host 0.0.0.0 --port 8420

# Create a session, step it, see what happened
curl -X POST localhost:8420/v1/sessions -d '{"scenario_path":"scenarios/lighthouse.yaml"}'
curl -X POST localhost:8420/v1/sessions/{id}/step -d '{"n":1}'
curl localhost:8420/v1/sessions/{id}/reports/last-cycle

Three execution lanes: - Query: read-only inspection (overview, resolve, object detail, events, changes, reports) - Turn: external input routed through the director as mediated stimuli - 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:

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)
PYTHONPATH=src pytest tests/ -m "not llm" -v

# Full suite (slower, needs OPENAI_API_KEY)
PYTHONPATH=src pytest tests/ --run-llm -v

Project Status

Version: 0.3.0 (experimental)

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

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)