games.mafia.models¶

Models for the Mafia game implementation.

This module defines the core data models and enums used in the Mafia game, including:

Game phases (setup, night, day discussion, voting)
Player roles (villager, mafia, detective, doctor, narrator)
Action types (speak, vote, kill, investigate, save)
State tracking for players and game
Decision models for LLM output

Examples

>>> from mafia.models import PlayerRole, GamePhase, MafiaAction
>>>
>>> # Create a player action
>>> action = MafiaAction(
...     player_id="Player_1",
...     action_type="vote",
...     phase=GamePhase.DAY_VOTING,
...     round_number=1,
...     target_id="Player_2"
... )

Classes¶

`ActionType`	Action type enumeration for the Mafia game.
`GamePhase`	Game phase enumeration for the Mafia game.
`MafiaAction`	An action taken by a player in the Mafia game.
`MafiaPlayerDecision`	A decision made by a player in the Mafia game.
`MafiaPlayerDecisionSchema`	Schema for LLM to output structured player decisions.
`NarratorAction`	An action taken by the narrator in the Mafia game.
`NarratorDecision`	A decision made by the narrator in the Mafia game.
`NarratorDecisionSchema`	Schema for LLM to output structured narrator decisions.
`PlayerRole`	Player role enumeration for the Mafia game.
`PlayerState`	State information for a player in the Mafia game.

Module Contents¶

class games.mafia.models.ActionType¶

Bases: str, enum.Enum

Action type enumeration for the Mafia game.

This enum defines all possible actions that players can take during the game, including both general and role-specific actions.

SPEAK¶: Make a public statement during discussion

VOTE¶: Vote to eliminate a player during day voting

KILL¶: Mafia night action to eliminate a player

INVESTIGATE¶: Detective night action to learn a player’s role

SAVE¶: Doctor night action to protect a player

Initialize self. See help(type(self)) for accurate signature.

class games.mafia.models.GamePhase¶

Bases: str, enum.Enum

Game phase enumeration for the Mafia game.

This enum defines the possible phases of the game, which determine what actions players can take and how the game progresses.

SETUP¶: Initial game setup phase

NIGHT¶: Night phase where special roles act secretly

DAY_DISCUSSION¶: Day phase for open discussion

DAY_VOTING¶: Voting phase to eliminate a player

GAME_OVER¶: Game has ended

Initialize self. See help(type(self)) for accurate signature.

class games.mafia.models.MafiaAction(/, **data)¶

Bases: pydantic.BaseModel

An action taken by a player in the Mafia game.

This model represents any action a player can take, including speaking, voting, and role-specific night actions.

Parameters:: data (Any)

player_id¶

ID of the player taking the action

Type:: str

action_type¶

Type of action being taken

Type:: ActionType

phase¶

Game phase when the action occurs

Type:: GamePhase

round_number¶

Current round number

Type:: int

target_id¶

Target player for the action

Type:: Optional[str]

message¶

Content for speak actions

Type:: Optional[str]

Examples

>>> action = MafiaAction(
...     player_id="Player_1",
...     action_type=ActionType.VOTE,
...     phase=GamePhase.DAY_VOTING,
...     round_number=1,
...     target_id="Player_2"
... )

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

to_dict()¶

Convert the action to a dictionary format.

Returns:: Dictionary representation of the action
Return type:: Dict[str, Any]

class games.mafia.models.MafiaPlayerDecision(/, **data)¶

Bases: pydantic.BaseModel

A decision made by a player in the Mafia game.

This model represents the complete decision output from a player’s LLM, including both the action and reasoning.

Parameters:: data (Any)

action¶

The action the player will take

Type:: MafiaAction

reasoning¶

Explanation for the decision

Type:: Optional[str]

Examples

>>> decision = MafiaPlayerDecision(
...     action=MafiaAction(...),
...     reasoning="Player seems suspicious based on voting pattern"
... )

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

class games.mafia.models.MafiaPlayerDecisionSchema(/, **data)¶

Bases: pydantic.BaseModel

Schema for LLM to output structured player decisions.

This model provides a simplified schema for LLM output that can be converted into a full MafiaPlayerDecision.

Parameters:: data (Any)

action_type¶

Type of action to take

Type:: str

target_id¶

Target player for the action

Type:: Optional[str]

message¶

Content for speak actions

Type:: Optional[str]

reasoning¶

Explanation for the decision

Type:: Optional[str]

Examples

>>> schema = MafiaPlayerDecisionSchema(
...     action_type="vote",
...     target_id="Player_2",
...     reasoning="Suspicious behavior during discussion"
... )

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

class games.mafia.models.NarratorAction(/, **data)¶

Bases: pydantic.BaseModel

An action taken by the narrator in the Mafia game.

This model represents narrator actions that control game flow and provide information to players.

Parameters:: data (Any)

announcement¶

Public message to all players

Type:: Optional[str]

player_state_updates¶

State changes

Type:: Dict[str, Dict[str, Any]]

phase_transition¶

Whether to move to next phase

Type:: bool

next_phase¶

Phase to transition to

Type:: Optional[GamePhase]

round_number¶

Current round number

Type:: int

Examples

>>> action = NarratorAction(
...     announcement="Night falls on the village.",
...     phase_transition=True,
...     next_phase=GamePhase.NIGHT,
...     round_number=1
... )

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

serialize_next_phase(next_phase)¶

Serialize the next_phase enum to a string.

Parameters:: next_phase (Optional[GamePhase]) – Phase to serialize
Returns:: String value of the phase or None
Return type:: Optional[str]

class games.mafia.models.NarratorDecision(/, **data)¶

Bases: pydantic.BaseModel

A decision made by the narrator in the Mafia game.

This model represents the complete decision output from the narrator’s LLM, including both the action and reasoning.

Parameters:: data (Any)

action¶

The action the narrator will take

Type:: NarratorAction

reasoning¶

Explanation for the decision

Type:: Optional[str]

Examples

>>> decision = NarratorDecision(
...     action=NarratorAction(...),
...     reasoning="All players have completed their night actions"
... )

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

class games.mafia.models.NarratorDecisionSchema(/, **data)¶

Bases: pydantic.BaseModel

Schema for LLM to output structured narrator decisions.

This model provides a simplified schema for LLM output that can be converted into a full NarratorDecision.

Parameters:: data (Any)

announcement¶

Public message to all players

Type:: Optional[str]

phase_transition¶

Whether to move to next phase

Type:: bool

reasoning¶

Explanation for the decision

Type:: Optional[str]

Examples

>>> schema = NarratorDecisionSchema(
...     announcement="The village falls quiet as night approaches.",
...     phase_transition=True,
...     reasoning="All players have completed their day actions."
... )

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

class games.mafia.models.PlayerRole¶

Bases: str, enum.Enum

Player role enumeration for the Mafia game.

This enum defines the possible roles a player can have, each with unique abilities and win conditions.

VILLAGER¶: Basic role with no special abilities

MAFIA¶: Can kill one player each night

DETECTIVE¶: Can investigate one player’s role each night

DOCTOR¶: Can protect one player from death each night

NARRATOR¶: Game master role that manages game flow

Initialize self. See help(type(self)) for accurate signature.

class games.mafia.models.PlayerState(/, **data)¶

Bases: pydantic.BaseModel

State information for a player in the Mafia game.

This model tracks all information about a player’s current state, including their role, alive status, and what they know about others.

Parameters:: data (Any)

player_id¶

Unique identifier for the player

Type:: Optional[str]

role¶

The player’s assigned role

Type:: PlayerRole

is_alive¶

Whether the player is still alive

Type:: bool

known_roles¶

Roles known to this player

Type:: Dict[str, PlayerRole]

investigation_results¶

Detective’s investigation results

Type:: Dict[str, bool]

Examples

>>> state = PlayerState(
...     player_id="Player_1",
...     role=PlayerRole.DETECTIVE,
...     known_roles={"Player_1": PlayerRole.DETECTIVE}
... )

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.