The Governance Layer ships a Streamlit dashboard that provides a live, visual interface to the formal framework. It exposes four tabs — Formal Model, Parliament Live, Benchmarks, and RL Training — and connects to whichever ontology backend is configured in yourDocumentation 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.
.env. It is designed as a research and development companion, not a production service.
The dashboard is a development and research tool. It is not hardened for public deployment, does not implement authentication, and should be run locally or in a trusted environment only.
Launching the dashboard
From the project root, run:http://localhost:8501 by default. The sidebar displays the active ontology backend type — either Neo4j Aura (if .env credentials are valid) or Memory (local) (fallback).
Prerequisites
Bothstreamlit>=1.35 and altair>=5.4 are included in the base install — no extra extras flag is needed. A standard pip install -e . or uv sync is sufficient.
Tab overview
The dashboard is organised into four tabs, each covering a distinct aspect of the governance framework.📐 Formal Model
Source:src/governance/dashboard/model_tab.py
The Formal Model tab renders the Identity Layer tuple 𝒮 = ⟨𝒪, 𝒞_core, 𝒦, 𝒫⟩ with live values pulled from the active ontology backend. Four metric columns show the current state of each component:
| Column | Content |
|---|---|
| 𝒪 (Ontology) | Count of "action" entities in the backend, with an expandable entity list |
| 𝒞_core (Core Commitments) | Commitment count and types from IdentityCore |
| 𝒦 (Extended Knowledge) | Bootstrapped knowledge confirmation |
| 𝒫 (Parameters) | All values from DEFAULT_PARAMETER_ENVELOPE, including quorum_threshold |
- Identity Vector — a bar chart of the current identity vector dimensions (green above 0.5, red below)
- Formal Predictions — live status of all 12 predictions from Chapters 2–4, executed via
run_all()fromsrc/governance/prove/
🏛️ Parliament Live
Source:src/governance/dashboard/parliament_tab.py
The Parliament Live tab replays a parliament episode step by step. It reads JSONL log files from the results/ directory — any file matching live_*.jsonl. Each record in the log corresponds to one environment step.
Controls:
- ◀ Back / Forward ▶ — step through the episode manually
- Auto-play — advances one step every 0.5 seconds with automatic page refresh
- A rendered grid image showing the agent position (blue), apple tiles (green), and obstacle tiles (red), with step counter
- A bar chart of the seven parliament member scores, colour-coded by threshold (green > 0.5, red ≤ 0.5)
- A five-metric ribbon: current step index, per-step reward, cumulative reward, apples collected, and violation count
- A reward / violations timeline chart for all steps up to the current position
"decision" entity with associated "member_score" entities, so Neo4j users get a persistent record of the replay session.
No log file? The tab offers two fallback options: a built-in demo dataset (20 procedurally generated steps) or a quick local simulation using GovernanceGridWorld that you can run directly from the UI with a configurable step count.
📊 Benchmarks
Source:src/governance/dashboard/benchmarks_tab.py
The Benchmarks tab loads results/benchmark_results.json and presents a statistical comparison across all strategies and scenarios.
Sections:
- Per-Scenario Results — expandable sections per scenario showing mean reward, standard deviation, mean violations, deadlock counts, and seed count per strategy
- Aggregate Comparison — a pivot table of mean reward by strategy × scenario
- Effect Sizes (Cohen’s d) — if present in the results file, a table of pairwise effect sizes
results/prove_results.json (always available after a runner prove run) and any results_*.json training result files.
All loaded benchmark aggregates are logged to the ontology backend as "benchmark" entities.
🤖 RL Training
Source:src/governance/dashboard/rl_tab.py
The RL Training tab presents a statistical comparison between governed (Neural Parliament) and ungoverned (raw PPO) agents across three experiment types. Results are loaded from CSV files written by the training scripts in scripts/.
Top-level governed vs ungoverned comparison (from results/rl/comparison_summary.csv):
- A pivot table of mean reward, standard deviation, violation count, apple count, and veto count, averaged across seeds
- A per-seed bar chart comparing mean reward for governed and ungoverned agents side by side
- Training curves for cumulative reward and constraint violations from
governed_metrics.csvandungoverned_metrics.csv, overlaid on the same chart - A separate veto count curve for the governed agent (if
veto_countis present in the metrics)
results/rl/minigrid/comparison_summary.csv):
- Expandable sections per Minigrid environment showing governed vs ungoverned reward and veto counts, broken out by seed
- Per-environment training curves loaded from
governed_{env_name}_seed0.csv
results/rl/safety_grid/comparison_summary.csv):
- Summary table and bar chart of mean reward by condition and seed
- Training curve from
governed_seed0.csv, plotting cumulative reward or cost
results/rl/, each section shows an info message prompting you to run python scripts/train_governed_agent.py first. All loaded RL run aggregates are logged to the ontology backend as "rl_run" entities.
Neo4j integration
When a valid.env is present and the Neo4j connection succeeds, the dashboard caches the Neo4jBackend instance via @st.cache_resource for the lifetime of the Streamlit session. Decision logs, member scores, and benchmark entries written during the session are durably persisted to the graph database.
If the connection fails at startup — network error, wrong credentials, or missing .env — the dashboard emits a sidebar warning and continues with MemoryBackend. No restart is required.