docs/adr/0011-declarative-validatable-config.md

ADR-0011: Declarative, Validatable Configuration

Status

Accepted

Context

"Super modular" and "easily configurable" require that the configurable surface — which agents exist, who participates, their model tier and memory, the scenario goal, tool grants, budgets — be data, not code. It must be editable by hand, by a future UI form, or by an LLM, and the engine must be able to verify a proposed configuration before running it. Hardcoded Python casts cannot satisfy any of that.

Decision

Express every knob as a declarative document with a Pydantic schema:

• AgentManifest (the agent contract) — persona, role, subscriptions, may_emit, schedule, model_profile, memory, tools, optional handler.
• ScenarioConfig — name, goal, default_seed, example_seeds, cast (agent names), genesis_text, optional governor.
• ModelsConfig / GovernorConfig — model profiles and budgets.
• WorldConfig — a whole world inline (agents + scenarios + models + budgets), cross-validated so every scenario's cast references a defined agent.

These live as YAML under config/ and are loaded by Registry (src/core/registry.py), which resolves a scenario's cast into live agents. validate_world / validate_agent / validate_scenario turn an arbitrary dict into a typed, cross-checked object or a precise error — so "configure from a prompt" reduces to emit JSON → validate → run.

Behaviour stays in Python only where needed: an agent names a handler and the registry instantiates the registered subclass; most agents need none.

Consequences

• Adding an agent or scenario, picking the cast, or wiring a tool is editing a YAML file — proven by tests/test_modularity.py (a brand-new agent + scenario runs with zero engine edits).
• The same schemas validate UI-form output and LLM-proposed configs, making a no-code or agent-built configuration path safe.
• A small pyyaml dependency is added.
• The shipped scenarios are now config (config/scenarios/*.yaml); their Python modules are thin build_scenario() shims that delegate to the registry.