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 models module defines the shared vocabulary that every layer of the Governance Layer framework reads and writes. All parliament members produce Proposal objects, the SpeakerStateMachine emits GovernanceDecision objects, and the broader system is threaded together through GovernanceContext. Understanding these five types is a prerequisite for working with any other part of the framework.

​
PriorityTag

PriorityTag is a plain class that acts as an ordered enumeration of proposal priorities. Lower integer values carry higher urgency and are sorted to the front of the governance agenda. All five constants are class-level integers; there are no instances. 
from governance import PriorityTag

print(PriorityTag.CRITICAL_SAFETY)  # 0
print(PriorityTag.HIGH_IMPACT)      # 1
print(PriorityTag.ROUTINE)          # 2
print(PriorityTag.EXPLORATORY)      # 3
print(PriorityTag.INFORMATIONAL)    # 4

print(PriorityTag.name(0))  # "CRITICAL_SAFETY"
print(PriorityTag.name(99)) # "UNKNOWN"

​
Class constants

​
CRITICAL_SAFETY
int
default:"0"
Highest urgency. Reserved for proposals that address immediate safety concerns. The SpeakerStateMachine sorts these to the very front of every agenda.
​
HIGH_IMPACT
int
default:"1"
Proposals with significant but non-emergency consequences, such as those that alter long-term strategy or resource allocation.
​
ROUTINE
int
default:"2"
Standard governance proposals that cover normal operational decisions. This is the default tag on every new Proposal.
​
EXPLORATORY
int
default:"3"
Proposals for experimental or novel actions where the outcome is uncertain. Sorted after routine items.
​
INFORMATIONAL
int
default:"4"
Lowest urgency. Used for proposals that convey information or suggest bookkeeping changes with no immediate operational impact.

​
Methods

​
PriorityTag.name(tag)

Returns the human-readable name for a numeric tag constant. Returns "UNKNOWN" for any integer not in the registered set.
​
tag
int
required
The integer priority constant to look up. Must be one of 0–4 to receive a named result.
​
return
str
The string name of the tag, e.g. "CRITICAL_SAFETY", or "UNKNOWN" if the value is not registered.

​
Action

Action is a frozen dataclass that represents a discrete, immutable action a parliament member may propose or that the system may execute. Because it is frozen, Action instances are hashable and safe to use as dictionary keys or set members. 
from governance import Action

# Minimal construction — only index is required
a = Action(index=7)
print(a)               # <Action 7>
print(a.runtime_hash)  # None

# Full construction
b = Action(
    index=42,
    properties={"temperature": 0.8, "cost": 1.2},
    runtime_hash="sha256:abcdef01",
)
print(b.properties["temperature"])  # 0.8

​
Fields

​
index
int
required
A stable integer identifier for this action within the action space. Must be unique across all actions your system defines.
​
properties
Dict[str, float]
default:"{}"
An optional mapping of named scalar properties associated with this action — for example {"cost": 1.5, "duration": 0.3}. Defaults to an empty dict. Because Action is frozen, the dict reference itself is fixed at construction time.
​
runtime_hash
Optional[str]
default:"None"
An optional opaque string that can be used to tie this action to a specific runtime artifact, commit hash, or content-addressable record. When None, no hash verification is performed.

​
Proposal

Proposal is a mutable dataclass produced by a ParliamentMember and consumed by the SpeakerStateMachine. It carries the identity of the proposing member, the action being proposed, a priority tag, a submission timestamp, and an open-ended metadata dict that member-specific scoring logic reads at evaluation time. 
import time
from governance import Proposal, PriorityTag

# Minimal proposal
p = Proposal(member_id="safety", action="hold_position")
print(p)  # <Proposal by safety tag=ROUTINE>

# Full proposal with metadata that scoring members will read
p = 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,
    },
)

​
Fields

​
member_id
str
required
The string identifier of the ParliamentMember that is submitting this proposal. Must match a key in the SpeakerStateMachine.members dict for the proposal to pass budget enforcement.
​
action
Any
required
The action being proposed. Can be any Python object — a string label, an Action dataclass instance, or an arbitrary domain-specific type.
​
tag
int
default:"PriorityTag.ROUTINE"
The priority level of this proposal. Use one of the PriorityTag constants. Lower values are sorted earlier in the governance agenda. Misuse of high-priority tags is tracked by _check_tag_compliance and can reduce a member’s proposal budget.
​
timestamp
float
default:"0.0"
Unix timestamp (seconds since epoch) of when the proposal was created. Used as a tiebreaker when two proposals share the same tag — earlier timestamps are processed first.
​
metadata
Dict[str, Any]
default:"{}"
Arbitrary key-value pairs that member scoring functions read during evaluation. The keys are not enforced by the framework; each concrete ParliamentMember documents which keys it looks for. Common conventions include "risk", "expected_reward", and "identity_coherence".

​
GovernanceDecision

GovernanceDecision is the output of every run_governance_cycle call. It records the elected action, the per-member score breakdown, the list of any members who cast a veto, and a metadata dict containing cycle-level bookkeeping. The is_default property is the canonical way to determine whether the cycle reached consensus or fell back to the configured default action. 
from governance import GovernanceDecision

# Inspect a decision returned by the speaker
decision: GovernanceDecision = speaker.run_governance_cycle(
    state="normal",
    raw_proposals=proposals,
)

print(decision.action)      # the elected action value
print(decision.is_default)  # True only when no consensus was reached
print(decision.scores)      # {"reward": 0.9, "safety": 0.1, "integrity": 0.2}
print(decision.vetoed_by)   # [] or ["integrity"] etc.
print(decision.governance_meta)
# {
#   "round": 1,
#   "decision_class": "routine",
#   "winning_proposal": "<Proposal by safety tag=CRITICAL_SAFETY>",
#   "falsification_counts": {},
# }

# When no consensus is reached the meta looks like:
# {
#   "is_default": True,
#   "reason": "No consensus after 3 rounds",
#   "decision_class": "routine",
#   "falsification_counts": {},
# }

​
Fields

​
action
Any
required
The elected action. On a successful vote this is the action field of the winning Proposal; on a default fallback this is SpeakerStateMachine.default_action.
​
scores
Dict[str, float]
default:"{}"
A mapping of member_id to the score that member assigned to the winning proposal. Empty when the decision is a default fallback (no proposal survived the full protocol).
​
vetoed_by
List[str]
default:"[]"
A list of member_id values that cast a veto against the winning proposal candidate. In practice the speaker skips a proposal the moment any veto is detected, so a non-empty list here reflects intermediate veto data rather than a veto on the final elected action.
​
governance_meta
Dict[str, Any]
default:"{}"
Structured bookkeeping from the governance cycle. On a consensus decision the dict contains:
KeyTypeDescription
roundintThe cycle round (1-indexed) in which consensus was reached.
decision_classstrThe decision class used ("routine", "high_impact", or "identity").
winning_proposalstrString representation of the proposal that won.
falsification_countsDict[str, int]Per-member count of tag-compliance violations detected this cycle.
On a default fallback the dict instead contains:
KeyTypeDescription
is_defaultboolAlways True on fallback decisions.
reasonstrHuman-readable reason, e.g. "No consensus after 3 rounds".
decision_classstrThe decision class that was attempted.
falsification_countsDict[str, int]Per-member tag-compliance violation counts.

​
Properties

​
is_default
bool
Returns True when governance_meta["is_default"] is set, which only occurs on a default fallback. Returns False for all consensus decisions. This is the canonical way to distinguish a real consensus from an emergency fallback.

​
GovernanceContext

GovernanceContext is an optional carrier for system-wide state that can be passed into governance logic. It gathers the active contracts that constrain what actions are permissible, the recent decision history, per-member health statuses, and the system’s identity vector and ontology. None of its fields are required; the dataclass is designed to be incrementally populated. 
from governance.models import GovernanceContext

# Build a context before passing it to higher-level orchestration
ctx = GovernanceContext(
    active_contracts=[],          # UlyssesContract instances, etc.
    recent_history=[],            # past GovernanceDecision objects
    member_statuses={
        "safety": {"healthy": True, "last_veto": None},
    },
    identity_vector=[0.9, 0.1, 0.7],   # optional embedding
    ontology=None,
)

​
Fields

​
active_contracts
List[Any]
default:"[]"
A list of contract objects (typically UlyssesContract instances) that represent pre-committed constraints on system behaviour. The governance layer enforces these constraints before any vote is resolved.
​
recent_history
List[GovernanceDecision]
default:"[]"
A rolling log of past GovernanceDecision objects. Higher-level orchestration layers may inspect this history to detect repeated defaults or pattern anomalies.
​
member_statuses
Dict[str, Dict[str, Any]]
default:"{}"
A mapping of member_id to an arbitrary status dict describing that member’s current health, suspension state, or diagnostic metadata. The schema of the inner dict is not enforced by the framework.
​
identity_vector
Optional[List[float]]
default:"None"
An optional floating-point vector that represents the system’s current identity embedding. Used by identity-tier governance checks when decision_class="identity" is in effect.
​
ontology
Optional[Any]
default:"None"
An optional reference to the system’s ontology or concept graph. The framework does not prescribe a type; any object meaningful to your domain logic is accepted.

Build docs developers (and LLMs) love

Get started for freeTalk to us