Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/xcoder-es/governance-layer/llms.txt

Use this file to discover all available pages before exploring further.

The Governance Layer ships a unified CLI runner (src.governance.runner) that executes all four experimental scenarios — GridWorld, TemptationBank, DriftLab, and DeadlockMaze — under any combination of strategies and seeds. A single command can produce a full benchmark matrix of 4 × 5 × 20 × 1,000 = 400 runs and automatically export the results to CSV, JSON, and publication-ready figures.

​
CLI Commands

The runner is invoked as a Python module. Every subcommand accepts --steps, --seeds, --strategies, and --csv. 
# Run all scenarios with the governance strategy only
python -m src.governance.runner all

# Run all scenarios with all five baseline strategies
python -m src.governance.runner all --baselines

# Full benchmark: 1,000 steps × 20 seeds across all strategies
python -m src.governance.runner all --baselines --steps 1000 --seeds 20

# Selective strategies only
python -m src.governance.runner all --baselines --strategies governance,random,veto_only

# Full benchmark with CSV export (timestamped file in results/)
python -m src.governance.runner all --baselines --steps 1000 --seeds 20 --csv

​
CLI Flags

FlagDefaultDescription
--steps N1000Steps executed per strategy–scenario run. Must be ≥ 1.
--seeds N1Independent random seeds per strategy–scenario pair. Must be ≥ 1.
--baselinesoffIncludes all five baseline strategies alongside governance.
--strategies a,b,…allComma-separated subset of strategies (overrides --baselines).
--csv [path]offExport step-level records to CSV. Defaults to results/run_<timestamp>.csv if no path is given.

​
The Five Baseline Strategies

When --baselines is passed, each scenario is run under all five strategies in parallel (one fresh instance per seed). Each baseline replaces the full Speaker state machine with a simpler decision rule so the governance layer’s marginal contribution can be measured directly.

governance

Full Neural Parliament SpeakerStateMachine. All proposals go through budget enforcement, priority ordering, weighted voting, safety vetoes, and identity checks.

monolithic_rl

Selects the proposal with the highest expected_reward metadata value. No safety filtering. Corresponds to a standard unconstrained RL policy.

random

Uniformly samples one proposal at random. Seeded with the per-run seed so results are reproducible.

static_masking

Blocks a predefined set of actions, then selects the highest-reward proposal from those remaining. Initialised with an empty block-set in benchmarks, making it equivalent to monolithic_rl.

veto_only

Accepts the first proposal whose risk metadata is below a fixed threshold (0.3). Provides lightweight safety without full deliberation.

​
Workflow

1

Choose your scenarios and strategies

Run a single scenario (gridworld, temptation, drift, deadlock) or all at once with all. Add --baselines to enable the full comparison matrix, or restrict to a subset with --strategies.
2

Set step count and seed count

The defaults (1,000 steps, 1 seed) are suitable for a quick sanity check. For statistically rigorous results, use --seeds 20, which runs each strategy–scenario pair from 20 independent initial conditions.
3

Execute the runner

The runner creates one fresh scenario instance per (strategy, seed) combination, runs it for the specified number of steps, and collects an ExperimentReport with reward, violations, deadlocks, vetoes, identity drift, and governance latency.
4

Review the console output

Results are printed per scenario block. Each line shows strategy, seed, total steps, total reward, deadlock count, and constraint violations.
5

Export and analyse

Pass --csv to write step-level records. When --baselines is active, the runner also calls run_analysis() to compute Cohen’s d effect sizes and detect reward-hacking episodes, and generate_all_figures() to write PNG figures into results/figures/.

​
Scenarios at a Glance

The four scenarios stress-test different governance properties. See the Scenarios page for full parameter tables and per-strategy results.
ScenarioWhat it testsCLI subcommand
GridWorldPoison-fruit reward hacking; Safety Committee vetogridworld
TemptationBankVoluntary self-binding via Ulysses Contractstemptation
DriftLabIdentity drift resistance under shifting reward signalsdrift
DeadlockMazeDeadlock breaker and cold-boot recoverydeadlock
The governance strategy is fully algorithmic — no neural networks, no sampling. A fixed seed therefore produces bit-identical results across platforms. This determinism is the foundation of the reproducibility guarantees documented in Appendix D of the book.

Build docs developers (and LLMs) love

Get started for freeTalk to us