Skip to content

Shielding API

Shielding APIs cover the learned transition shield, conservative value iteration, runtime inspection, and exact true-shield baselines.

Learned Transition Shield

src.shield.transition_shield.TransitionShield

Bases: BaseParallelWrapper

Budget-augmented robust replacement shield over a monotone OM-level floor.

Runtime behavior
  • expose the focal observation as [flat_obs, current_safety_bound, level_floor]
  • keep the focal action space identical to the base environment
  • keep a monotone floor over opponent-model levels using argmax(iop.mix_alpha) with optional sample-based raise patience
  • replace only unsafe proposed actions with the robust safest pure action
  • update the remaining budget from the realized successor state's projected budget

src.shield.transition_shield.ShieldedEnv

Bases: TransitionShield

Compatibility alias for the canonical budgeted TransitionShield.

src.shield.transition_shield.TransitionShieldBundle dataclass

src.shield.transition_shield.ShieldLevelBuildResult dataclass

src.shield.transition_shield.SuccessorDistribution dataclass

src.shield.transition_shield.build_transition_shield_bundle(*, env, transition_graph_path, iop, agent_id='player_0', focal_idx=None, vi_tol=1e-08, vi_max_iter=1000000, vi_round_outward=1e-12)

Sound Value Iteration

src.shield.sound_value_iteration.SoundVIResult dataclass

src.shield.sound_value_iteration.sound_value_iteration_min_reach_upper(*, graph, unsafe, n_actions=None, tol=1e-08, max_iter=1000000, round_outward=1e-12)

Compute sound lower/upper bounds on the minimal probability of eventually reaching the unsafe set U.

Conservative modeling: any missing transition mass is sent to an absorbing unsafe sink (value 1), ensuring over-approximation for the upper bound.

The interval is initialized with
  • lower_q = 0 outside unsafe,
  • upper_q = 1 outside unsafe,
  • lower_q = upper_q = 1 on unsafe,
  • lower_q = upper_q = 0 on the almost-sure safe set.

Then both bounds are iterated monotonically until the sup-norm gap between them is within tol, or max_iter is reached.

src.shield.sound_value_iteration.unsafe_keys_from_env(*, graph, labelled_env)

Use the environment's labelling to decide which graph nodes are unsafe.

src.shield.sound_value_iteration.almost_sure_safe_keys_from_graph(*, graph, unsafe, n_actions=None, mass_tol=1e-12)

Largest safe set W such that every state in W has at least one action whose full support stays inside W and has no missing transition mass.

These are the states from which the controller can stay safe almost surely, so their minimal reachability to unsafe is exactly zero.

Runtime Inspection

src.shield.inspection.ShieldLevelInspection dataclass

src.shield.inspection.ShieldStateInspection dataclass

src.shield.inspection.ShieldDecisionInspection dataclass

src.shield.inspection.inspect_shield_level(bundle, *, key, level)

src.shield.inspection.inspect_shield_state(bundle, *, key, current_budget, mix_alpha, current_floor=0, manual_floor=None, warn_missing_coverage=None)

src.shield.inspection.inspect_shield_decision(bundle, *, key, proposed_action, current_budget, mix_alpha, current_floor=0, manual_floor=None, warn_missing_coverage=None)

True Shield

src.true_shield.wrapper.TruePolicyTransitionShield

Bases: TransitionShield

src.true_shield.bundle.build_true_policy_transition_shield_bundle(*, env, opponent_policies, transition_graph_path=None, transition_graph=None, agent_id='player_0', focal_idx=None, vi_tol=1e-08, vi_max_iter=1000000, vi_round_outward=1e-12)

src.true_shield.exact_graph.build_true_transition_graph(env, **kwargs)