Models

Immutable game models, actions, events and state transitions.

MAX_SPEECH_LENGTH module-attribute

MAX_SPEECH_LENGTH: Final = 500

Maximum number of characters kept from a speech.

Action dataclass

Base class for every move a player can make.

Attributes:

Name	Type	Description
description	str	Human-readable text shown to agents when the action is offered.

CallSpecialElectionAction dataclass

Bases: Action

The president picks the next president.

Attributes:

Name	Type	Description
target_uid	int	UID of the player who becomes the next president.

ChancellorEnactAction dataclass

Bases: Action

The chancellor enacts one of the two received policies.

Attributes:

Name	Type	Description
target_index	int	Index of the policy to enact in GameState.drawn_policies.

ChancellorVetoAction dataclass

Bases: Action

The chancellor proposes to veto both received policies.

ClaimChancellorEnactAction dataclass

Bases: Action

The chancellor claims which two policies they received.

Attributes:

Name	Type	Description
claim_policies	tuple[PolicyTile, ...] | None	The claimed policies, or None to decline.

ClaimInvestigationAction dataclass

Bases: Action

The president claims the investigated player's party.

Attributes:

Name	Type	Description
claim_party	Party | None	The claimed party, or None to decline.

ClaimPolicyPeekAction dataclass

Bases: Action

The president claims what the policy peek showed.

Attributes:

Name	Type	Description
claim_policies	tuple[PolicyTile, ...] | None	The claimed policies from the top down, or None to decline.

ClaimPresidentEnactAction dataclass

Bases: Action

The president claims which three policies they drew.

Attributes:

Name	Type	Description
claim_policies	tuple[PolicyTile, ...] | None	The claimed policies, or None to decline.

ExecutionAction dataclass

Bases: Action

The president executes a player.

Attributes:

Name	Type	Description
target_uid	int	UID of the player to execute.

InvestigateLoyaltyAction dataclass

Bases: Action

The president investigates another player's party.

Attributes:

Name	Type	Description
target_uid	int	UID of the player to investigate.

NominateAction dataclass

Bases: Action

The president nominates a chancellor.

Attributes:

Name	Type	Description
target_uid	int	UID of the nominated player.

PassAction dataclass

Bases: Action

A player stays silent during discussion.

PolicyPeekAction dataclass

Bases: Action

The president looks at the top three policies of the draw pile.

PresidentDiscardAction dataclass

Bases: Action

The president discards one of the three drawn policies.

Attributes:

Name	Type	Description
target_index	int	Index of the policy to discard in GameState.drawn_policies.

PresidentVetoResponseAction dataclass

Bases: Action

The president answers the chancellor's veto proposal.

Attributes:

Name	Type	Description
approve	bool	Whether the president agrees to the veto.

SpeakAction dataclass

Bases: Action

A player says something during discussion.

Attributes:

Name	Type	Description
message	str	What the player says, filled in by the agent.

VoteAction dataclass

Bases: Action

A player votes on the proposed government.

Attributes:

Name	Type	Description
vote	Vote	The vote cast.

Agent

Bases: Protocol

Protocol that every player implementation satisfies.

Attributes:

Name	Type	Description
uid	int	The player's unique ID.

choose_action async

choose_action(
    state: GameState, valid_actions: tuple[Action, ...]
) -> Action

Chooses one of the offered actions.

Parameters:

Name	Type	Description	Default
state	GameState	The game state, scrubbed for this agent.	required
valid_actions	tuple[Action, ...]	The actions this agent may take now.	required

Returns:

Type	Description
Action	One of valid_actions. The agent may fill in description and SpeakAction.message.

AgentFault dataclass

A failed attempt by an agent to choose an action.

Attributes:

Name	Type	Description
uid	int	UID of the agent that failed.
phase	GamePhase	Phase the game was in.
reason	str	The repr of the exception raised.
fell_back	bool	Whether this failure made the runner play a random legal action.

BallotBox dataclass

The votes cast in the current election.

Attributes:

Name	Type	Description
votes	frozendict[int, Vote | HIDDEN]	Each voter's UID mapped to their vote, or to HIDDEN in a scrubbed state.

vote_count property

vote_count: int

The number of votes cast so far.

result property

result: Vote

Vote.JA if a strict majority of the votes cast are ja, otherwise Vote.NEIN.

Board dataclass

The liberal and fascist policy tracks.

Attributes:

Name	Type	Description
player_count	int	Number of players, which selects the fascist track.
liberal_played	int	Number of liberal policies enacted.
fascist_played	int	Number of fascist policies enacted.

winner property

winner: Party | None

The party that has enacted enough policies to win, or None.

hitler_zone property

hitler_zone: bool

Whether electing Hitler as chancellor now wins the game for the fascists.

veto_power_unlocked property

veto_power_unlocked: bool

Whether the chancellor may propose a veto.

ChancellorEnactClaim dataclass

Bases: Claim

The chancellor's claim about the two policies they received.

Attributes:

Name	Type	Description
policies	tuple[PolicyTile, PolicyTile] | None	The claimed policies, or None if the chancellor declined.

Claim dataclass

Base class for what a player says they saw.

Attributes:

Name	Type	Description
uid	int	UID of the player making the claim.

InvestigationClaim dataclass

Bases: Claim

The president's claim about the investigated player's party.

Attributes:

Name	Type	Description
party	Party | None	The claimed party, or None if the president declined.

PeekClaim dataclass

Bases: Claim

The president's claim about the top three policies of the deck.

Attributes:

Name	Type	Description
policies	tuple[PolicyTile, PolicyTile, PolicyTile] | None	The claimed policies from the top down, or None if the president declined.

PresidentEnactClaim dataclass

Bases: Claim

The president's claim about the three policies they drew.

Attributes:

Name	Type	Description
policies	tuple[PolicyTile, PolicyTile, PolicyTile] | None	The claimed policies, or None if the president declined.

Deck dataclass

The policy draw and discard piles.

Attributes:

Name	Type	Description
draw_pile	tuple[PolicyTile | HIDDEN, ...]	Policies left to draw; the last element is the top of the deck.
discard_pile	tuple[PolicyTile | HIDDEN, ...]	Discarded policies.

peek property

peek: tuple[
    PolicyTile | HIDDEN,
    PolicyTile | HIDDEN,
    PolicyTile | HIDDEN,
]

The top three policies of the draw pile, from the top down.

Raises:

Type	Description
RuntimeError	If the draw pile holds fewer than three policies.

Discussion dataclass

A discussion in progress, where living players take turns to speak.

Attributes:

Name	Type	Description
context	DiscussionContext	What triggered the discussion.
resume_phase	GamePhase	Phase the game returns to when the discussion ends.
speaker_order	tuple[int, ...]	UIDs of the speakers, in turn order.
rounds	int	How many times the table goes around.
turn	int	Number of turns taken so far.

current_speaker property

current_speaker: int

UID of the player whose turn it is to speak.

current_round property

current_round: int

The current round, starting at 1.

is_complete property

is_complete: bool

Whether every speaker has taken all their turns.

ElectionTracker dataclass

Counts consecutive failed elections.

Attributes:

Name	Type	Description
failed_elections	int	Failed elections since the tracker last reset.

HIDDEN

Sentinel for a value the viewer is not allowed to see.

scrub_state puts the class itself, not an instance, in place of each hidden value.

DiscussionContext

Bases: StrEnum

The public event that triggered a discussion.

Attributes:

Name	Type	Description
AFTER_NOMINATION		The president nominated a chancellor.
AFTER_FAILED_ELECTION		An election failed.
AFTER_POLICY_CLAIMS		The government claimed its policies and no power needs a choice next.
BEFORE_INVESTIGATION		The government claimed its policies and the president will investigate next.
BEFORE_SPECIAL_ELECTION		The government claimed its policies and the president will call a special election next.
BEFORE_EXECUTION		The government claimed its policies and the president will execute a player next.
AFTER_INVESTIGATION_CLAIM		The president claimed an investigation result.
AFTER_PEEK_CLAIM		The president claimed what a policy peek showed.
AFTER_SPECIAL_ELECTION		The president called a special election.
AFTER_EXECUTION		The president executed a player.

GamePhase

Bases: StrEnum

The step of the game that decides who acts next.

Attributes:

Name	Type	Description
SETUP		Not used by the engine; games start in NOMINATION.
NOMINATION		The president nominates a chancellor.
DISCUSSION		Living players take turns to speak.
VOTING		Every living player votes on the proposed government.
PRESIDENT_DISCARD		The president discards one of three drawn policies.
CHANCELLOR_ENACT		The chancellor enacts one of two policies or proposes a veto.
CLAIM_POLICIES		The president and chancellor claim the policies they saw.
PRESIDENTIAL_POWER		The president uses the active power.
CLAIM_POLICY_PEEK		The president claims what the policy peek showed.
CLAIM_INVESTIGATION		The president claims the investigated player's party.
PRESIDENT_VETO_RESPONSE		The president answers the chancellor's veto proposal.
GAME_OVER		The game has ended.

Party

Bases: StrEnum

A player's team.

PolicyTile

Bases: StrEnum

A policy card.

PresidentialPower

Bases: StrEnum

A power that an enacted fascist policy grants the president.

Attributes:

Name	Type	Description
NONE		No power.
INVESTIGATE_LOYALTY		The president learns another player's party.
CALL_SPECIAL_ELECTION		The president picks the next president.
POLICY_PEEK		The president sees the top three policies of the deck.
EXECUTION		The president kills a player.

Role

Bases: StrEnum

A player's secret role; Hitler belongs to the fascist party.

Vote

Bases: StrEnum

A ballot in an election.

WinCondition

Bases: StrEnum

How a game was won.

Attributes:

Name	Type	Description
LIBERAL_POLICIES		Five liberal policies were enacted.
FASCIST_POLICIES		Six fascist policies were enacted.
HITLER_ELECTED		Hitler was elected chancellor after three fascist policies were enacted.
HITLER_EXECUTED		Hitler was executed.

ClaimEvent dataclass

Bases: Event

A player made a claim.

Attributes:

Name	Type	Description
claim	Claim	The claim made.
president_uid	int	UID of the president of the government or power the claim is about.
chancellor_uid	int | None	UID of the chancellor for a policy claim, otherwise None.
target_uid	int | None	UID of the investigated player for an investigation claim, otherwise None.

ElectionEvent dataclass

Bases: Event

An election resolved.

Attributes:

Name	Type	Description
president_uid	int	UID of the president.
chancellor_uid	int	UID of the nominated chancellor.
votes	frozendict[int, Vote]	Each voter's UID mapped to their vote.
result	Vote	Vote.JA if the government was elected, otherwise Vote.NEIN.

Event dataclass

Base class for the public events recorded in GameState.events.

ExecutionEvent dataclass

Bases: Event

The president executed a player.

Attributes:

Name	Type	Description
president_uid	int	UID of the president.
target_uid	int	UID of the executed player.

GameOverEvent dataclass

Bases: Event

The game ended.

Attributes:

Name	Type	Description
winner	Party	The winning party.
condition	WinCondition	How the game was won.

InvestigationEvent dataclass

Bases: Event

The president investigated a player.

Attributes:

Name	Type	Description
president_uid	int	UID of the president.
target_uid	int	UID of the investigated player.

NominationEvent dataclass

Bases: Event

The president nominated a chancellor.

Attributes:

Name	Type	Description
president_uid	int	UID of the president.
chancellor_uid	int	UID of the nominee.

PolicyEnactedEvent dataclass

Bases: Event

A policy was enacted.

Attributes:

Name	Type	Description
policy	PolicyTile	The enacted policy.
president_uid	int | None	UID of the president, or None for a top-deck.
chancellor_uid	int | None	UID of the chancellor, or None for a top-deck.

top_deck property

top_deck: bool

Whether the election tracker enacted the policy from the top of the deck.

SpecialElectionEvent dataclass

Bases: Event

The president called a special election.

Attributes:

Name	Type	Description
president_uid	int	UID of the president.
target_uid	int	UID of the player who becomes the next president.

SpeechEvent dataclass

Bases: Event

A player spoke or passed during discussion.

Attributes:

Name	Type	Description
uid	int	UID of the speaker.
text	str | None	What the player said, or None if they passed.
context	DiscussionContext	What triggered the discussion.

VetoEvent dataclass

Bases: Event

The president answered the chancellor's veto proposal.

Attributes:

Name	Type	Description
president_uid	int	UID of the president.
chancellor_uid	int	UID of the chancellor who proposed the veto.
approved	bool	Whether the president agreed to the veto.

GameState dataclass

The complete state of a game.

Attributes:

Name	Type	Description
players	tuple[Player, ...]	Every player, in seat order.
board	Board	The policy tracks.
deck	Deck	The draw and discard piles.
election_tracker	ElectionTracker	The count of consecutive failed elections.
phase	GamePhase	The current phase.
president_index	int	Seat index of the current president.
chancellor	int | None	UID of the nominated or elected chancellor, or None.
ballot_box	BallotBox	The votes cast in the current election.
drawn_policies	tuple[PolicyTile | HIDDEN, ...]	The policies in the president's or chancellor's hand, or shown by a policy peek.
previous_president	int | None	UID of the last elected president, or None.
previous_chancellor	int | None	UID of the last elected chancellor, or None.
winner	Party | None	The winning party, or None while the game is running.
special_election_president	int | None	UID of the player picked by a special election, or None.
rng_state	tuple[int, tuple[int, ...], float | None] | HIDDEN	State of the random generator that shuffles the deck, or HIDDEN in a scrubbed state.
veto_denied_this_term	bool	Whether the president has refused a veto in the current legislative session.
investigations	frozendict[int, int]	Each investigated player's UID mapped to the UID of the president who investigated them.
deck_shuffled_last_action	bool	Whether the last action shuffled the discard pile back into the draw pile.
active_power	PresidentialPower	The presidential power being used, or PresidentialPower.NONE.
current_investigation_result	Party | HIDDEN | None	The party found by the pending investigation, HIDDEN for other viewers, or None.
claims	tuple[Claim, ...]	Every claim made, in order.
pending_president_enact_claim	bool	Whether the president still has to claim the drawn policies.
pending_chancellor_enact_claim	bool	Whether the chancellor still has to claim the received policies.
pending_power	PresidentialPower	The power to grant once both policy claims are made.
special_election_caller_index	int | None	Seat index of the president who called the special election, or None.
discussion_enabled	bool	Whether discussions are held.
discussion_rounds	int	How many times the table goes around in each discussion.
discussion	Discussion | None	The discussion in progress, or None.
events	tuple[Event, ...]	Every public event, in order.
knowledge	tuple[Knowledge, ...]	What each player learned in secret, in order.

ChancellorReceiveKnowledge dataclass

Bases: Knowledge

A chancellor received two policies from the president.

Attributes:

Name	Type	Description
president_uid	int	UID of the president who passed the policies.
policies	tuple[PolicyTile, PolicyTile]	The received policies.

InvestigationKnowledge dataclass

Bases: Knowledge

A president learned an investigated player's party.

Attributes:

Name	Type	Description
target_uid	int	UID of the investigated player.
party	Party	The investigated player's party.

Knowledge dataclass

Base class for what a player learned in secret.

Attributes:

Name	Type	Description
uid	int	UID of the player who learned it.

PeekKnowledge dataclass

Bases: Knowledge

A president peeked at the top three policies of the deck.

Attributes:

Name	Type	Description
policies	tuple[PolicyTile, PolicyTile, PolicyTile]	The peeked policies, from the top down.

PresidentDrawKnowledge dataclass

Bases: Knowledge

A president drew three policies after a passed election.

Attributes:

Name	Type	Description
chancellor_uid	int	UID of the chancellor in that government.
policies	tuple[PolicyTile, PolicyTile, PolicyTile]	The drawn policies, from the top down.

Player dataclass

A player at the table.

Attributes:

Name	Type	Description
uid	int	The player's unique ID.
party	Party | HIDDEN	The player's party, or HIDDEN in a scrubbed state.
role	Role | HIDDEN	The player's role, or HIDDEN in a scrubbed state.
is_alive	bool	Whether the player has not been executed.

Replay dataclass

Every action applied in a game, enough to rebuild each state.

Attributes:

Name	Type	Description
initial_state	GameState	The unscrubbed state the game started from.
steps	tuple[ReplayStep, ...]	The applied actions, in order.

ReplayStep dataclass

One applied action.

Attributes:

Name	Type	Description
uid	int	UID of the player who acted.
action	Action	The action applied.
fallback	bool	Whether the runner played the action at random after the agent failed.

create_game

create_game(
    uids: tuple[int, ...],
    seed: int | None = 42,
    roles: Mapping[int, Role] | None = None,
    shuffle_players: bool = True,
    discussion_enabled: bool = False,
    discussion_rounds: int = 2,
) -> GameState

Creates a new game, ready for the first nomination.

Parameters:

Name	Type	Description	Default
uids	tuple[int, ...]	Unique IDs of the 5 to 10 players.	required
seed	int | None	Seed for dealing roles, seating players and shuffling the deck, or None for a random game.	42
roles	Mapping[int, Role] | None	Fixed role for each UID, or None to deal roles at random.	None
shuffle_players	bool	Whether to shuffle the seating order; otherwise players sit in uids order.	True
discussion_enabled	bool	Whether to hold discussions.	False
discussion_rounds	int	How many times the table goes around in each discussion.	2

Returns:

Type	Description
GameState	The initial game state.

Raises:

Type	Description
TyrantError	If the player count, the UIDs, roles or discussion_rounds are invalid.

scrub_state

scrub_state(state: GameState, viewer_uid: int) -> GameState

Hides everything the viewer is not allowed to see.

Other players' parties and roles are hidden unless the viewer's role or an investigation reveals them. The deck contents, other players' hands, votes still being cast, the shuffle state and other players' knowledge are hidden too. Public events pass through unchanged.

Parameters:

Name	Type	Description	Default
state	GameState	The full game state.	required
viewer_uid	int	UID of the player who will see the state.	required

Returns:

Type	Description
GameState	A new game state that is safe to show to the viewer.

Raises:

Type	Description
TyrantError	If the viewer is not in the game.