Skip to main content

Documentation 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.

The fastest path to a working governance cycle is four steps: clone the repository, install the package in editable mode, run the speaker sanity check, and then wire up your own members and proposals using the public API. This guide walks through each step and ends with a complete, runnable Python example drawn directly from the reference implementation.
1

Install the package

The governance-layer package is installed from source in editable mode. Python 3.10 or later is required.
pip install -e .
If you prefer uv, the project is fully compatible:
uv pip install -e .
Optional extrasThe rl extra adds PyTorch and Stable-Baselines3 for the RL adversary experiment:
pip install -e ".[rl]"
The minigrid extra adds MiniGrid and pygame-ce for the visual grid-world scenarios:
pip install -e ".[minigrid]"
Core governance functionality — the Neural Parliament, Ulysses Contracts, and Identity Layer — requires neither rl nor minigrid. Install the base package unless you specifically need benchmark environments or the RL adversary.
2

Run the speaker demo

The bundled CLI provides a quick sanity check that exercises the Speaker state machine end-to-end with three members and three competing proposals:
python -m src.governance.runner speaker
You should see output similar to:
Decision: <GovernanceDecision CONSENSUS action=safe_middle_road>
  Action:  safe_middle_road
  Default: False
  Scores:  {'reward': 0.5, 'safety': 0.9, 'integrity': 0.9}
  Meta:    {'round': 1, 'decision_class': 'routine', ...}
If the safety member’s veto threshold blocks the high-reward proposal and the parliament reaches consensus on the safe action, the setup is working correctly.
3

Write your first governance cycle

Import the public API, construct your parliament, create proposals, and call run_governance_cycle(). The example below mirrors the speaker demo exactly as it appears in the reference implementation.
import time

from governance import (
    SpeakerStateMachine,
    ExampleRewardMember,
    ExampleSafetyMember,
    ExampleIntegrityMember,
    Proposal,
    PriorityTag,
)

# 1. Build the parliament — each member embodies a distinct governance concern
members = {
    "reward":    ExampleRewardMember(),    # veto_threshold=0.0, weight=1.0
    "safety":    ExampleSafetyMember(),    # veto_threshold=0.5, weight=2.0
    "integrity": ExampleIntegrityMember(), # veto_threshold=0.8, weight=3.0
}

# 2. Instantiate the Speaker state machine with a fallback default action
speaker = SpeakerStateMachine(
    members=members,
    default_action="emergency_shutdown",
)

# 3. Each member submits a Proposal — tagged by priority, carrying metadata
proposals = [
    Proposal(
        member_id="reward",
        action="high_reward_gamble",
        tag=PriorityTag.ROUTINE,
        timestamp=time.time(),
        metadata={"expected_reward": 0.9, "risk": 0.8, "identity_coherence": 0.2},
    ),
    Proposal(
        member_id="safety",
        action="safe_middle_road",
        tag=PriorityTag.CRITICAL_SAFETY,
        timestamp=time.time(),
        metadata={"expected_reward": 0.5, "risk": 0.1, "identity_coherence": 0.9},
    ),
    Proposal(
        member_id="integrity",
        action="principled_action",
        tag=PriorityTag.HIGH_IMPACT,
        timestamp=time.time(),
        metadata={"expected_reward": 0.4, "risk": 0.2, "identity_coherence": 1.0},
    ),
]

# 4. Run the full governance cycle — agenda, scoring, vetoes, vote, fallback
decision = speaker.run_governance_cycle(
    state="normal",
    raw_proposals=proposals,
    decision_class="routine",
)

# 5. Inspect the result
print(f"Decision: {decision}")
print(f"  Action:  {decision.action}")
print(f"  Default: {decision.is_default}")
print(f"  Scores:  {decision.scores}")
print(f"  Meta:    {decision.governance_meta}")
What just happened? The Speaker sorted the agenda by PriorityTag (0 = CRITICAL_SAFETY first), scored each proposal against all three members, checked for vetoes, and resolved a weighted vote. The safety proposal rises to the top of the agenda, passes veto checks, and wins the vote — beating the higher-reward gamble that the safety member would veto. If no proposal passes within max_rounds=3, the Speaker returns the default_action with is_default=True.
4

Explore the Streamlit dashboard

The governance package ships with a multi-page Streamlit application that visualises the formal model, lets you run the Neural Parliament interactively, and displays benchmark results.
streamlit run src/governance/dashboard/app.py
The dashboard opens in your browser and provides three tabs:
  • Formal Model — Browse the layered specification and testable predictions.
  • Parliament Live — Submit proposals and watch the Speaker deliberate in real time.
  • Benchmarks — Explore results across all four experimental scenarios and five strategies.
The dashboard uses MemoryBackend by default (ephemeral, no dependencies). To persist ontology entities and decision logs across sessions, add a .env file with NEO4J_URI, NEO4J_USER, and NEO4J_PASSWORD — the dashboard auto-detects credentials and upgrades to Neo4jBackend.

​
Next Steps

Architecture

Understand the four-layer stack before wiring custom members into your own agent loop.

Neural Parliament

Learn how to implement ParliamentMember, set veto thresholds, and configure proposal budgets.

Ulysses Contracts

Lock pre-committed constraints before high-stakes episodes to prevent self-amendment under pressure.

Identity Layer

Anchor a four-tier commitment ontology so the agent’s core values survive multi-round deliberation.

Build docs developers (and LLMs) love

Get started for freeTalk to us