Simulation Context Protocol

A lightweight framework for building multi-stage simulation demos with LLM-driven agents.

What this project is for

This repo helps you build scenarios where:

• multiple sub-environments are composed into one MetaEnv
• an agent makes stage-wise decisions (for example social -> physical)
• behavior and outcomes are logged with readable, config-driven summaries

The current reference demo is demos/red_light_crossing.

Project organization

Simulation_Context_Protocol/
├── agent/                      # Generic LLM backend + action parsing
├── envs/                       # Reusable sub-environments (gym-style interface)
├── scp/                        # MetaEnv abstractions, adapters, topology helpers
├── runtime/                    # Runner + readable logging (driven by log schema)
├── demos/                      # Scenario demos (config + builder + meta env + run script)
│   └── red_light_crossing/
├── config/                     # Config loader + templates
├── skills/                     # Project skills for code agents
└── user_input_template.md      # User-facing form for new demo requirements

Core architecture

• agent/llm_agent.py
  • generic OpenAI-compatible client (openai / deepseek)
  • demo-specific logic stays outside this file
• envs/*.py
  • sub simulators with project-style gym-like API:
    • reset(...) -> (obs, info)
    • step(action) -> (obs, reward, done, info)
    • get_state() -> dict
• demos/<demo>/demo_meta_env.py
  • orchestrates stage order and data flow across envs
• demos/<demo>/demo_builder.py
  • builds env instances from demo_config.yaml
  • builds demo agent from agent config
• runtime/runner.py
  • runs episodes
  • prints readable logs based on meta_env.logging schema in config

How a demo is built

Each demo lives in its own folder (for example demos/red_light_crossing) and usually contains:

• demo_config.yaml (global source of truth)
• demo_builder.py
• demo_meta_env.py
• <demo>_llm_agent.py
• run_demo.py

Recommended build sequence:

1. define demo_config.yaml first
2. reuse existing envs from envs/ where possible
3. create missing envs in gym-style if needed
4. implement demo_meta_env.py orchestration
5. implement demo agent wrapper around generic LLMAgent
6. wire everything in demo_builder.py
7. run through run_demo.py

Demo config: the global contract

Use this structure in each demo config:

• meta_env
  • id/name/purpose
  • relation between envs (type, flow, description)
  • I/O spec
  • logging schema (step_fields, derived_fields, summaries)
• envs
  • each stage has class + settings
• agent
  • backend settings and llm_personality

Reference files:

• template: config/demo_config_template.yaml
• concrete example: demos/red_light_crossing/demo_config.yaml

Running the example demo

Install dependencies:

pip install -r requirements.txt

Run:

python demos/red_light_crossing/run_demo.py

You will see step-level logs and summary stats rendered from config-defined log schema.

Vibe Coding workflow (using Code Agents)

For fast scenario creation with Claude Code or similar code agents:

1. Fill the form in user_input_template.md
2. Ask the code agent to build a new demo using that filled input
3. Let the agent:
   • generate demo_config.yaml
   • reuse or create needed envs
   • build meta_env, demo agent, builder, and run_demo.py
4. run and iterate based on readable logs

The form already includes:

• empty template for new demos
• filled red-light-crossing example for reference

For detailed fields and examples, see user_input_template

In short, provide:

• demo basics and evaluation target
• multi-stage flow definition
• per-stage env I/O and key settings
• agent settings and llm_personality
• expected step outputs/logging and success criteria

The file includes both an empty template and a filled red-light-crossing example, so you can copy-and-fill directly for code agents.

Skill for automated demo creation

This repo includes a project skill:

• skills/demo-scene-builder/SKILL.md
• skills/demo-scene-builder/reference.md

What it provides:

• methodized workflow (config first -> env reuse/create -> compose meta env/agent -> run demo)
• env search-and-reuse strategy
• gym-style env creation guidance when missing
• validation checklist and minimal follow-up question policy

Use this skill when users provide user_input_template.md content and ask for a new demo scenario.

Dependencies

requirements.txt includes:

• numpy
• PyYAML
• openai
• httpx[socks] (for environments using SOCKS proxy)

Notes

• Keep scenario-specific behavior in demos/<demo>/, not in generic runtime or base agent.
• Keep logging semantics in config (meta_env.logging) to avoid hard-coded demo assumptions.