docs/schema/world-config.md

World Config Contract

WorldConfig (src/core/config.py) is a whole runnable world as one validatable artifact — agents, scenarios, model profiles, and budgets inline. It is the contract a UI form or an LLM emits when "configuring from a prompt," and validate_world() checks it (including cross-references) before anything runs.

Schema

WorldConfig:
    models:    ModelsConfig        # profile -> concrete model bindings
    governor:  GovernorConfig      # default budgets
    agents:    list[AgentManifest] # agent definitions
    scenarios: list[ScenarioConfig]# scenarios referencing those agents by name

Cross-validation

The key safety property: every scenario's cast must reference a defined agent. A dangling reference is rejected at validation time, not discovered at run time.

from src.core.config import validate_world

world = validate_world({
    "models":    {"offline": True},
    "governor":  {"max_turns": 500},
    "agents":    [{"name": "town-crier", "persona": "Announce the news.",
                   "may_emit": ["crier.announced"], "schedule": {"tick_every": 1}}],
    "scenarios": [{"name": "town-square", "default_seed": "Market day.",
                   "cast": ["town-crier"]}],
})
# -> WorldConfig

validate_world({
    "agents":    [{"name": "a", "persona": "p"}],
    "scenarios": [{"name": "s", "default_seed": "x", "cast": ["ghost"]}],
})
# -> ValidationError: scenario 's' references undefined agents: ['ghost']

Granular validators

For incremental UI/agent workflows, validate one piece at a time:

Function	Returns	Use
validate_agent(dict)	AgentManifest	a single proposed agent
validate_scenario(dict)	ScenarioConfig	a single proposed scenario
validate_world(dict)	WorldConfig	the whole world, cross-checked

Relationship to config/

The on-disk config/ tree (one file per agent/scenario + models.yaml) is the file-based projection of a WorldConfig. Registry.from_dir() loads that tree; validate_world() validates an equivalent inline document. Same schemas, two delivery surfaces — files for the repo, dicts for a UI or an LLM.

See also: scenario-config.md, agent-manifest.md.