Multiagent Probabilistic Shielding¶
OMSH studies safe decision-making when a focal reinforcement-learning agent shares an environment with other agents whose behavior must be estimated.
The repository combines three layers:
- World modelling starts from an exact legal joint-state graph and learns a masked categorical distribution over each transition's legal successors, with a reward per successor.
- Opponent modelling fits a neural level-0 policy from observed actions, then trains higher reasoning levels through imagined rollouts on the learned graph.
- Probabilistic shielding (OmSh) conservatively bounds eventual unsafe reachability against every opponent level it has not ruled out, and replaces a focal action when it cannot be certified within the current safety budget.
Experiments compare OmSh with IPPO, IPPO-Lagrangian, and CPO, and with IPPO-TrueShielded, an oracle reference that shields with exact dynamics and the opponents' live policies. Safety is defined explicitly per environment and is reported separately from reward.
What the Repository Covers¶
- Runtime shield variants. Pure or pairwise-mixed actions, egalitarian or learned successor budgets, several opponent-uncertainty modes, coordinated shielding of several roles at once, and certificates padded against model error.
- Guarantee tooling. An exact arbitrary-opponent certificate, count-centred ambiguity sets, robustness margins, opponent-gap measurement, and a step-by-step risk-dominance audit. Guarantees and Robustness explains what each one claims.
- Frozen-policy evaluation. Every trained policy can be frozen and evaluated on fresh seeds, with exact reachability for stationary baselines.
- Campaign reporting. Tagged campaigns isolate artifacts from canonical runs, and scripts turn them into cross-environment reports and paper tables.
Where to Begin¶
- Get Started installs the project, validates the checkout, and runs one small baseline notebook.
- Conceptual Overview explains how public state, joint graphs, opponent levels, and safety certificates fit together.
- The interactive field guide teaches winning regions, carried budgets, interval value iteration, learned allocations, and opponent floors with live calculations. It runs offline in the browser.
- Training Pipeline gives the local WM → OM → experiment workflow and artifact dependencies.
- Experiments lists every stage and the settings the published campaign uses.
- Cluster Execution documents the Slurm and PBS launchers.
- Supported Environments lists agent counts, action spaces, export roots, budgets, and safety objectives.
- API Reference documents the curated reusable Python interfaces.
Documentation Scope¶
The main pages are operational and user-facing. Durable contracts, design
rationale, cache semantics, campaign protocols, and resolved failure modes live
in the maintainer notes. Dated result and audit reports live in
reports/, outside this site. Both sets of pages are built by Zensical and
validated with strict link checking.