Skip to content

Diagram Notebook Expansion

The diagram notebook surface now has one shared foundation under notebooks/diagrams/common/ and three diagram roots under exports/diagrams/:

  • exports/diagrams/om/ for the existing IOP notebooks
  • exports/diagrams/wm/ for legal and learned environment-transition graph views
  • exports/diagrams/shielding/ for shield inspection views

Shared common layer

The shared package carries the cross-cutting notebook helpers that used to live inside the IOP-only code:

  • registry-backed artifact resolution via resolve_diagram_artifacts(...)
  • shared state display and summary helpers
  • shared Graphviz card/export helpers
  • shared graph neighborhood slicing

notebooks.diagrams.iop keeps its public imports stable by re-exporting and wrapping these shared helpers rather than changing notebook entrypoints.

WM graph slicing defaults

The WM notebook intentionally avoids whole-graph rendering by default because gridworld transition graphs become unreadable very quickly once maps or agent counts grow.

Default slice settings:

  • direction: both
  • hop depth: 1
  • per-node expansion cap: 8
  • hard preview cap: 64 nodes / 128 edges

The neighborhood expansion sorts candidate edges by probability when a learned graph exposes env_prob (falling back to prob, then to a stable graph order). That keeps the slice focused on the most informative local transitions when a state has many outgoing candidates.

Whole-graph preview/export is only enabled when the loaded graph is at most:

  • 150 nodes
  • 400 edges

That guard is deliberate. The point of the notebook is to preserve legibility, not to dump an enormous DOT file into a browser panel.

Shielding diagrams

Shielding notebooks use the public inspection helpers in src/shield/inspection.py instead of reaching into TransitionShield private methods.

That gives one shared reasoning path for:

  • per-level inspection cards
  • runtime mix/floor decision cards
  • the actual TransitionShield runtime

If shield semantics change later, the notebook and runtime should stay aligned as long as the shared inspection module is updated.