Configuration and CLI¶

Marimo notebooks expose selected dictionary keys as CLI options. Use --kebab-case=value; keys map case-insensitively to the notebook’s snake-case configuration.

Experiment Keys¶

Key	Meaning	Typical default
`timesteps`	Target environment steps per algorithm run.	750k–3M by environment
`num_runs`	Independent algorithm seeds.	3
`rollouts`	Steps collected per policy update.	2048
`learning_epochs`	Optimizer passes over a rollout.	4
`mini_batches`	Rollout partitions per epoch.	4
`learning_rate`	Learner step size.	2e-4–3e-4
`max_risk`	Initial eventual-unsafe reachability budget.	0.2; Pursuit 0.25
`use_wandb`	Enable Weights & Biases run logging.	Usually false
`n_agents`	Environment team size where supported.	Environment-specific
`experiment_tag`	Isolate histories and diagnostics below `experiments/runs/<tag>/`.	Empty (canonical run)
`seed_offset`	Non-negative first trainer seed for a disjoint run block.	0

timesteps is rounded up to at least one complete rollout/update. For a small smoke run, reduce rollouts as well as timesteps.

Stage Switches¶

run_ippo
run_ippo_lag
run_icpo
run_ippo_shielded
run_ippo_true_shielded
run_exact_anytime_diagnostic
just_vis

All run_* values default to false. The exact-anytime switch runs an offline certificate diagnostic rather than an algorithm. Select only the stages a scripted run should execute. Cluster algorithm launchers own their training switches and reject caller overrides.

Shield Keys¶

Key	Values and meaning
`shield_action_mode`	`pure`, `egalitarian_mixed`, `learned_budget_pure`, or `learned_budget_mixed`. Non-pure modes select parameterized PPO automatically.
`shield_opponent_mode`	`monotone_floor` (default), `credible_floor`, `all_levels`, or `bayesian_mixture`.
`shield_reward_mode`	`bayesian` (default) or `robust`; this ranks actions only after the safety test.
`shield_patience`	Consecutive supported posterior updates needed for one floor raise; `0` is eager.
`shield_credible_delta`	Posterior-tail allowance for `credible_floor`; default `0.05`.
`shield_credible_schedule`	`summable` (default) or pointwise `fixed`.
`shield_debug_mode`	`off`, `minimal`, or `verbose` runtime fields.
`shield_trace_limit`	Maximum in-memory verbose decision records.
`shield_missing_coverage_log_limit`	Cap on repeated missing-coverage log messages.
`true_policy_refresh_interval_updates`	Policy-update interval for rebuilding the exact-policy shield.

run_exact_anytime_diagnostic=true uses max_risk as both p_total and p_shield because the serialized exact-graph route reports delta_cov=0 relative to its matching environment contract and declared reset support. Its artifacts are written below true_shield/exact_anytime/; the switch does not consume timesteps, num_runs, or PPO configuration.

The pure/monotone-floor/Bayesian-reward/v0 condition retains the canonical ippo_shielded_* artifact names. Other action, opponent, reward, or explicit shield-version conditions receive deterministic suffixes.

Diagnostics Keys¶

Key	Meaning	Default
`verbose_data`	Add bounded raw traces and sampled policy/IOP comparisons; aggregate diagnostics remain always on.	false
`diagnostic_interval_updates`	Update interval for sampled live-policy/IOP diagnostics.	1
`diagnostic_state_sample`	Maximum sampled rollout states per diagnostic comparison.	8192
`data_trace_stride`	Keep one raw shield decision per this many decisions.	100
`max_trace_rows`	Hard cap on exported trace rows.	100,000

These controls reuse collected rollouts; enabling verbose data does not add environment steps.

World- and Opponent-Model Keys¶

WM notebooks accept n_steps for replay collection and configurable environments also accept n_agents. OM notebooks accept n_agents where needed; their detailed neural/imagination defaults live in notebook-local configuration objects.

Do not confuse WM n_steps with experiment timesteps. The dependency-aware cluster launcher routes them to different notebooks.

Value Coercion and Validation¶

CLI values representing integers, floats, booleans, or None are converted to their Python values. Both --n-agents=3 and n_agents=3 work in the relevant runner context. Unknown keys and duplicate normalized keys fail early, which protects long cluster jobs from silently ignoring a typo.

Example baseline smoke run:

uv run python notebooks/matrix/chicken/experiments_mo.py \
  --run-ippo=true \
  --num-runs=1 --timesteps=64 --rollouts=64 --use-wandb=false