Percept Simulation

The Concept

An animal that closes its eyes can still think, plan, and respond to touch. Maxim's percept simulation works the same way — the full cognitive pipeline runs normally, but instead of camera frames and microphone audio, the system receives percepts from an interactive REPL or a scripted YAML file.

Everything after the Percept boundary is identical. The LLM reasons, FearAgent reviews, tools execute, memories form — all real. Only the source of sensory input changes.

Interactive Mode

Interactive mode is ON by default when running from a TTY. In generative and DM campaigns, a Rich split-panel display shows the narrative in the main panel and a scrollable log below. The human can type responses, make choices, and roleplay directly into the simulation.

The old standalone REPL is still available via maxim --sim with no arguments when no TTY is attached. With a TTY, running maxim --sim launches the interactive prompt:

Each turn builds on the conversation history. The LLM generates percepts from your natural-language descriptions, which flow through the full pipeline with bio-subsystem tracing.

Commands

Simulation Agent

The most powerful way to test Maxim. A second Maxim instance — the orchestrator — drives the agent-under-test through the full agentic pipeline, adapting in real time based on what it observes. Unlike the interactive REPL, the orchestrator plans multi-step campaigns, learns from results, and decides when to stop.

Architecture

Three threads, two agent loops, connected by a SimulationBridge:

The SimulationBridge wraps ConversationalSource + RecordingSink and adds atomic send_and_wait() with settle detection — it injects a percept, waits until the AUT stops producing actions, and returns the full response in one call.

Orchestrator Tools

Personas

Personas shape the orchestrator's testing strategy. Each is a Strategy object with a focus prompt and initiative level.

User Commands During Simulation

AUT Inspection

The orchestrator has an inspect_aut tool for read-only access to the AUT's cognitive state. Supports 8 queries: memory_recall, causal_links, predict_outcome, pain_history, energy_status, system_stats, concept_query, temporal_patterns. Used primarily by the refinement persona for systematic measurement.

Decomposition: Spawn & Extend

Two tools for multi-phase campaigns:

• spawn_sub_simulation — fresh AUT, clean state, isolated measurement. Sub-AUT stays alive for extend follow-ups.
• extend_simulation — same AUT, same context, go deeper on findings.

The orchestrator decides when to go wide (spawn across categories) vs. deep (extend within findings). Use --persona campaign for systematic spawning or --persona adversarial for depth-first chaining.

Continuous / Infinite Mode

Never auto-completes. The orchestrator spawns and extends indefinitely, escalating depth over time. Stop with /cancel or Ctrl+C.

Resuming a Previous Session

Restores the AUT's memory and causal links from the previous run. The orchestrator receives previous findings as context — what was tested, what issues were found, and what to focus on next. Supports fuzzy prefix matching (--resume-sim 20260403).

Response Policy (Auto-Approval)

In simulation mode, the AUT auto-approves confirmation prompts, plan approvals, and timeout retries by default. This prevents deadlocks from missing stdin. Four policies: auto_approve (default), auto_reject (test refusals), delayed (test timeouts), ask_orchestrator (full confirmation testing).

Session Reports

Every simulation run saves a complete report to ~/.maxim/sim_reports/{session_id}/:

• report.json — Metrics, tool usage, AUT cognitive state, cost, LLM analysis
• actions.jsonl — Every action record for post-hoc analysis
• aut_hippocampus.json — AUT's episodic memories
• aut_nac.json — AUT's causal links learned

An LLM-powered roundup runs at session end, adding a summary, issues found, and recommendations to the report.

Cost Ceiling

Cloud API costs are capped at $5.00 per session by default. Once hit, all further LLM requests are hard-rejected. Configure via max_session_cost in llm.json routing policy. Additional soft limits apply per-request ($0.50), hourly ($1.00), daily ($10.00), and monthly ($100.00) — these downgrade models rather than blocking.

Generative Campaigns

The default simulation mode. Pass a natural-language goal string to --sim and a narrator LLM generates a multi-phase narrative arc that drives the AUT through a structured story:

Narrative Arcs

Each campaign follows a NarrativeArc — a sequence of phases (setup, rising action, climax, resolution) with intensity curves. Built-in arcs cover common testing patterns; custom arcs can be loaded from YAML.

The narrator compresses the story history between phases using bridge_and_compress, keeping context manageable across long campaigns. An AdaptivePlanner integration translates plan goals into arc-compatible phases via translate_plan_to_arc.

How It Differs from the Simulation Agent

Generative campaigns export the generated scenario to YAML after completion, so successful runs can be re-run deterministically as direct injection campaigns.

DM Campaigns & Genre Gating

For deterministic, reproducible tests, write campaign YAML files with encounters, NPCs, choices, and branches. The DM runtime drives the AUT through the story and measures how the bio-stack responds. Interactive mode is ON by default for DM campaigns — the human picks choices from the encounter options and can type free-text roleplay that gets woven into the scene.

Available Campaigns

Genre Gating

Campaigns declare a genre field that filters the SEM Component Registry. When genre: fantasy is set, the EntityDesigner only suggests fantasy or genre-neutral base templates — no cyberpunk drones in a medieval tavern.

Genre-neutral components (like base_humanoid) are always available. Explicit registry refs bypass the gate for intentional cross-genre use. See the Component Library section for creating genre-tagged components.

Research Mode

Run a simulation with structured experiment tracking and automatic paper generation:

After the simulation completes, a Writer agent produces a structured research paper and a Reviewer agent evaluates it. Both use mesh primitives (AgentProfile, MeshMessage) for communication. The ExperimentLog tracks all runs with structured metadata for querying.

Fixture-Driven Mode (Substrate Testing)

Run YAML fixtures through the agent loop without a narrator LLM. Fastest and most deterministic mode — designed for substrate phase testing but usable for any repeatable scenario.

Features: no narrator LLM cost, bio-system state snapshots at end-of-run (Hippocampus, NAc, ATL, percept trace buffer, EC substrate nodes), substrate_metrics in session report, automatic expectation checking.

Deterministic Seeding

The --seed N flag sets all RNG sources (Python random, numpy, torch) from a single integer. Two runs with the same seed and fixture produce identical results. Per-agent RNG streams prevent cross-agent correlation in multi-agent sims.

Substrate Recognition Tests (P1)

The P1 recognition sweep runs all 155 paraphrase sentences through the substrate pipeline (LinguisticEncoder → EC pattern completion → ATL) and measures collapse rate, cross-cluster distinctness, and node stability. Results are recorded in the lab notebook at docs/experiments/.

Running YAML Scenarios

Single Scenario

All Scenarios in a Directory

Save Results to JSON

Available Scenarios

Generating from Natural Language

Instead of writing YAML by hand, describe what you want to test in plain English:

The local LLM (Mistral 7B recommended) converts your description into a structured YAML scenario with appropriate percepts, timing, and expectations. You can then review and edit the generated file before running it.

Writing Scenarios by Hand

A scenario is a YAML file with three sections: metadata, percepts, and expectations.

Percept Source Types

Timing Modes

Expectations & Validation

Expectations define what should happen during the scenario. After all percepts are processed, each expectation is checked against the recorded actions and memory state.

Metric Expectations

Bio-System Expectations

These validate cognitive architecture behavior — whether the bio-inspired subsystems are functioning correctly. Requires subsystem_snapshot and tool_stats data from SimulationResult.

Output Format

Bio-Subsystem Tracing

During simulation, a dedicated logger traces every bio-inspired subsystem in real time. Each line shows when a subsystem activates, what it processes, and what it decides.

Subsystem Labels

Safety & Sandboxing

Simulations run in a multi-layered sandbox. Even when testing malware scenarios, the system cannot escape these barriers:

Docker Sandbox — Container Isolation

Passing --sandbox docker launches the AUT inside a container with OS-enforced isolation layered on top of the bio-inspired pain signals. Resource limits scale to AutonomyLevel:

The AUT runs as an unprivileged maxim user. Root-owned honeypot files (/etc/shadow, /etc/sudoers) return permission-denied and fire pain — two layers of feedback. Files under the user's home directory are readable but still pain-triggering, so the AUT learns via NAc rather than being blocked.

The sandbox supports a catalog of base images covering realistic deployment targets:

• Python-focused: python:3.12-slim (default, ~45MB), python:3.12-bookworm
• Ubuntu: ubuntu:22.04, ubuntu:24.04 — common robotics platforms
• Debian: debian:12-slim
• Red Hat: rockylinux:9, almalinux:9, registry.access.redhat.com/ubi9/ubi-minimal
• Alpine: alpine:3.19 (~8MB, uses /bin/sh)

Container lifecycle is crash-safe: UUID-suffixed names, --rm auto-removal, and an atexit cleanup hook mean no orphan containers even if Maxim is killed with SIGKILL. Runaway commands are killed container-side via the timeout coreutil.

The ContainerRunner abstraction is a Protocol, so future cloud runners (AWS Fargate, Google Cloud Run, Azure Container Instances) can slot in without touching DockerSandbox.

Architecture

Key Components