SpeakerStateMachine: Neural Parliament Governance Engine

SpeakerStateMachine is the core governance engine of the Neural Parliament architecture. It accepts a pool of Proposal objects, runs them through a fixed seven-phase immutable protocol — budget enforcement, priority sorting, scoring, tag-compliance checking, veto resolution, voting, and default fallback — and returns a single GovernanceDecision. The machine is fully algorithmic: it has no learnable parameters, performs no neural inference, and is deterministic given the same inputs. This determinism is deliberate; the discrete protocol operations act as a gradient barrier that prevents backpropagation from tunnelling through governance logic.

Constructor

from governance import SpeakerStateMachine, ExampleSafetyMember

speaker = SpeakerStateMachine(
    members={"safety": ExampleSafetyMember()},
    default_action="emergency_shutdown",
    majority_threshold=0.5,
    supermajority_threshold=0.66,
    max_rounds=3,
)

members

Dict[str, ParliamentMember]

required

A mapping of member_id string to a ParliamentMember instance. Every key must match the member_id attribute of the corresponding member object. Proposals whose member_id is not present in this dict are silently dropped during budget enforcement.

default_action

Any

required

The action returned inside a GovernanceDecision when no proposal achieves consensus after max_rounds rounds. Should be a safe, conservative fallback — for example "emergency_shutdown" or a known-safe Action instance.

majority_threshold

float

default:"0.5"

The minimum weighted-average score required for a proposal to pass under "routine" decision class. Scores are computed as the weighted mean of all members’ evaluate_proposal results, normalised by total weight.

supermajority_threshold

float

default:"0.66"

The minimum weighted-average score required for a proposal to pass under "high_impact" decision class. Requires broader agreement than majority_threshold.

max_rounds

int

default:"3"

The maximum number of rounds the speaker will attempt before giving up and returning the default action. In each round every surviving agenda item is re-evaluated and re-voted.

Class Constants

TAG_COMPLIANCE_THRESHOLD

float

default:"0.4"

The minimum integrity score a member must receive on its own proposal for that proposal to be considered tag-compliant. If a member’s "integrity" score (returned by the integrity member’s evaluate_proposal) falls below this value, a falsification strike is recorded against that member.

FALSIFICATION_BUDGET_CUTOFF

int

default:"3"

The number of tag-compliance violations a member may accumulate before its proposal budget is halved. Once _falsification_counts[member_id] >= FALSIFICATION_BUDGET_CUTOFF, the member’s budget is set to max(1, budget // 2), throttling its ability to flood the agenda.

Attributes

immutable_procedures

List[str]

An instance attribute holding the seven protocol phase names that are hardcoded into every governance cycle. Set in __init__ and never modified by the machine. These phases are executed in order and cannot be bypassed, reordered, or removed by any configuration option.

speaker.immutable_procedures
# [
#   "agenda_budget_enforcement",
#   "agenda_priority_sorting",
#   "scoring_phase",
#   "tag_compliance_check",
#   "veto_phase",
#   "voting_phase",
#   "default_fallback",
# ]

Methods

`set_agenda(proposals)`

Applies budget enforcement and priority sorting to a raw proposal list, returning the ordered agenda that the governance cycle will process. This method is called automatically inside run_governance_cycle but is exposed publicly so callers can inspect or pre-validate the agenda before committing to a full cycle.

proposals

List[Proposal]

required

The unsorted, unfiltered list of proposals to process. Proposals from members not registered in self.members are removed, and each member’s submissions are capped at their budget value. The remaining proposals are sorted by (tag, timestamp) in ascending order.

return

List[Proposal]

The budget-filtered, priority-sorted agenda. The list may be shorter than the input if any proposals were dropped due to unknown member IDs or exceeded budgets.

agenda = speaker.set_agenda(raw_proposals)
for p in agenda:
    print(p)
# <Proposal by safety tag=CRITICAL_SAFETY>
# <Proposal by reward tag=ROUTINE>

`run_governance_cycle(state, raw_proposals, decision_class)`

The primary entry point. Runs the full seven-phase governance protocol over the provided proposals and returns a GovernanceDecision. This method is deterministic: the same state, raw_proposals, and member configurations will always produce the same decision.

state

Any

required

Opaque state value passed verbatim to each member’s evaluate_proposal(state, proposal) call. Can be any Python object meaningful to your domain — a string label, an environment observation, or a structured state dataclass.

raw_proposals

List[Proposal]

required

The unfiltered list of proposals submitted for this cycle. Budget enforcement and sorting are applied internally via set_agenda before any evaluation begins.

decision_class

str

default:"\"routine\""

Controls the voting threshold applied during _resolve_vote. Accepted values:

Value	Threshold applied
`"routine"`	`majority_threshold` (default `0.5`)
`"high_impact"`	`supermajority_threshold` (default `0.66`)
`"identity"`	Unanimity — exactly `1.0`

return

GovernanceDecision

The result of the governance cycle. If at least one proposal cleared all veto checks and met the voting threshold, action is set to that proposal’s action and is_default is False. If no proposal passed after max_rounds rounds, action is set to default_action and is_default is True.

Internal Phase Methods

The following methods implement the individual phases of the immutable protocol. They are called automatically by run_governance_cycle and are documented here for transparency and auditability. Callers should not invoke them directly.

`_apply_budgets(proposals)` internal

Filters the proposal list so that no single member submits more proposals than its configured budget. Iterates proposals in input order, counting per-member submissions and dropping any that exceed the limit. Members not present in self.members are dropped entirely.

`_sort_agenda(proposals)` internal

Sorts a filtered proposal list by (tag, timestamp) ascending. Because PriorityTag.CRITICAL_SAFETY = 0 is the smallest value, critical proposals always appear first. Within the same tag, earlier timestamps are processed before later ones.

`_score_proposal(state, proposal)` internal

Calls evaluate_proposal(state, proposal) on every registered member and collects the results into a Dict[str, float] keyed by member_id. Returns a complete score map regardless of whether any individual member’s score is above or below a threshold.

`_check_tag_compliance(proposals, integrity_scores)` internal

Detects members that are inflating proposal priority by checking whether the integrity member’s score for each proposal exceeds TAG_COMPLIANCE_THRESHOLD. Members that fail this check receive a falsification strike; once they accumulate FALSIFICATION_BUDGET_CUTOFF strikes their proposal budget is permanently halved (floored at 1). Returns the current falsification_counts dict.

`_check_vetoes(scores)` internal

Examines the score map for a single proposal and returns the list of member IDs whose score falls below that member’s configured veto_threshold. A non-empty result causes the speaker to skip the proposal entirely and move on to the next agenda item.

`_resolve_vote(scores, decision_class)` internal

Computes the weighted average of all member scores for a proposal (using each member’s weight) and compares it against the threshold selected by decision_class. Returns True if the weighted average meets or exceeds the threshold; False otherwise.

Complete Example

The following example demonstrates a full governance cycle using all three built-in example members. The ExampleSafetyMember carries the highest weight (2.0) and a veto threshold of 0.5; the ExampleIntegrityMember carries the highest weight of all (3.0) and a veto threshold of 0.8. The high-risk "high_reward_gamble" proposal will be vetoed by both, leaving only "safe_middle_road" to contest the vote.

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

members = {
    "reward": ExampleRewardMember(),
    "safety": ExampleSafetyMember(),
    "integrity": ExampleIntegrityMember(),
}

speaker = SpeakerStateMachine(
    members=members,
    default_action="emergency_shutdown",
)

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},
    ),
]

decision = speaker.run_governance_cycle(
    state="normal",
    raw_proposals=proposals,
    decision_class="routine",
)

print(decision.action)           # "safe_middle_road"
print(decision.is_default)       # False — consensus was reached
print(decision.scores)           # {"reward": 0.5, "safety": 0.9, "integrity": 0.9}
print(decision.governance_meta)
# {
#   "round": 1,
#   "decision_class": "routine",
#   "winning_proposal": "<Proposal by safety tag=CRITICAL_SAFETY>",
#   "falsification_counts": {},
# }

Understanding the returned `GovernanceDecision`

Field	Consensus value	Default-fallback value
`action`	The `action` of the winning `Proposal`	`SpeakerStateMachine.default_action`
`scores`	Per-member scores for the winning proposal	`{}` (empty)
`vetoed_by`	`[]` (winning proposals are never vetoed)	`[]`
`is_default`	`False`	`True`
`governance_meta["round"]`	Round number (1-indexed)	(not present)
`governance_meta["decision_class"]`	The `decision_class` argument	The `decision_class` argument
`governance_meta["winning_proposal"]`	`str(proposal)` of the winner	(not present)
`governance_meta["is_default"]`	(not present)	`True`
`governance_meta["reason"]`	(not present)	`"No consensus after N rounds"`
`governance_meta["falsification_counts"]`	Per-member violation counts	Per-member violation counts

Decision class thresholds at a glance

`decision_class`	Threshold	Typical use
`"routine"`	`majority_threshold` (0.5)	Normal operational decisions
`"high_impact"`	`supermajority_threshold` (0.66)	Strategic changes, resource reallocation
`"identity"`	`1.0` (unanimity)	Modifications to core identity or ontology

Core Types

Parliament

Identity & Security

CLI Reference

SpeakerStateMachine: Neural Parliament Governance Engine

Constructor

Class Constants

Attributes

Methods

`set_agenda(proposals)`

`run_governance_cycle(state, raw_proposals, decision_class)`

Internal Phase Methods

`_apply_budgets(proposals)` internal

`_sort_agenda(proposals)` internal

`_score_proposal(state, proposal)` internal

`_check_tag_compliance(proposals, integrity_scores)` internal

`_check_vetoes(scores)` internal

`_resolve_vote(scores, decision_class)` internal

Complete Example

Understanding the returned `GovernanceDecision`

Decision class thresholds at a glance

Build docs developers (and LLMs) love

Core Types

Parliament

Identity & Security

CLI Reference

Documentation Index

​Constructor

​Class Constants

​Attributes

​Methods

​set_agenda(proposals)

​run_governance_cycle(state, raw_proposals, decision_class)

​Internal Phase Methods

​_apply_budgets(proposals) internal

​_sort_agenda(proposals) internal

​_score_proposal(state, proposal) internal

​_check_tag_compliance(proposals, integrity_scores) internal

​_check_vetoes(scores) internal

​_resolve_vote(scores, decision_class) internal

​Complete Example

​Understanding the returned GovernanceDecision

​Decision class thresholds at a glance

Build docs developers (and LLMs) love

Constructor

Class Constants

Attributes

Methods

`set_agenda(proposals)`

`run_governance_cycle(state, raw_proposals, decision_class)`

Internal Phase Methods

`_apply_budgets(proposals)` internal

`_sort_agenda(proposals)` internal

`_score_proposal(state, proposal)` internal

`_check_tag_compliance(proposals, integrity_scores)` internal

`_check_vetoes(scores)` internal

`_resolve_vote(scores, decision_class)` internal

Complete Example

Understanding the returned `GovernanceDecision`

Decision class thresholds at a glance