haive.games.clue.state¶

Comprehensive state management for the Clue (Cluedo) mystery game.

This module defines the state model for the Clue game, providing complete tracking of game progression, player cards, hypotheses, and game status. The state system supports both two-player and multi-player configurations with full game rule enforcement.

The state model handles: - Secret solution management (murderer, weapon, room) - Player card distribution and tracking - Guess and response history - AI hypothesis generation and tracking - Turn management and game flow - Win condition evaluation - Game status and completion handling

Key Features:

  • Immutable solution hidden from players

  • Dynamic card dealing and distribution

  • Comprehensive guess and response logging

  • AI hypothesis tracking for strategic play

  • Turn-based progression with validation

  • Multiple win conditions and game ending scenarios

Examples

Initializing a new game:

from haive.games.clue.state import ClueState

# Create a new game with random solution
state = ClueState.initialize()

# Create a game with specific solution
from haive.games.clue.models import ClueSolution, ValidSuspect, ValidWeapon, ValidRoom

solution = ClueSolution(
    suspect=ValidSuspect.COLONEL_MUSTARD,
    weapon=ValidWeapon.KNIFE,
    room=ValidRoom.KITCHEN
)
state = ClueState.initialize(solution=solution)

Checking game status:

if state.is_game_over:
    print(f"Game ended! Winner: {state.winner}")
else:
    print(f"Turn {state.current_turn_number}: {state.current_player}'s turn")

Accessing player information:

player1_cards = state.player1_cards
player2_cards = state.player2_cards
print(f"Player 1 has {len(player1_cards)} cards")
print(f"Player 2 has {len(player2_cards)} cards")

The state model integrates seamlessly with the game agent system and provides all necessary information for AI decision-making and strategic gameplay.

Classes¶

ClueState

Comprehensive state model for Clue game sessions.

Module Contents¶

class haive.games.clue.state.ClueState(/, **data)[source]¶

Bases: haive.games.framework.base.state.GameState

Comprehensive state model for Clue game sessions.

This class manages all aspects of a Clue game state, including the secret solution, player cards, game progression, and AI reasoning. It provides methods for game initialization, turn management, and win condition evaluation.

The state model supports strategic gameplay by tracking player hypotheses, guess history, and response patterns. This enables sophisticated AI decision-making and deduction logic.

Parameters:

data (Any)

solution¶

The secret solution that players are trying to discover. Contains the murderer (suspect), weapon, and room.

guesses¶

Complete history of all guesses made during the game. Each guess contains a suspect, weapon, and room combination.

responses¶

Responses to each guess, indicating whether cards were shown and which player responded.

player1_cards¶

List of cards held by player 1. Used for responding to guesses and making deductions.

player2_cards¶

List of cards held by player 2. Used for responding to guesses and making deductions.

current_player¶

The player whose turn it is to make a guess. Alternates between “player1” and “player2”.

max_turns¶

Maximum number of turns before the game ends in a draw. Prevents infinite games and ensures completion.

game_status¶

Current status of the game (ongoing, player1_win, player2_win). Used to determine if the game has ended and who won.

winner¶

The winning player, if any. Set when a player makes a correct accusation.

player1_hypotheses¶

List of AI-generated hypotheses for player 1. Tracks the AI’s reasoning and deduction process.

player2_hypotheses¶

List of AI-generated hypotheses for player 2. Tracks the AI’s reasoning and deduction process.

Examples

Creating a new game state:

state = ClueState.initialize()
print(f"Solution: {state.solution}")
print(f"Player 1 cards: {state.player1_cards}")
print(f"Player 2 cards: {state.player2_cards}")

Checking game progress:

if state.is_game_over:
    print(f"Game ended! Winner: {state.winner}")
else:
    print(f"Turn {state.current_turn_number}: {state.current_player}'s turn")

Accessing game history:

for i, (guess, response) in enumerate(zip(state.guesses, state.responses)):
    print(f"Turn {i+1}: {guess.suspect}, {guess.weapon}, {guess.room}")
    print(f"Response: {response.responding_player}")

Note

The solution is hidden from players during normal gameplay but is accessible to the game engine for validation and scoring purposes.

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.

classmethod initialize(**kwargs)[source]¶

Initialize a new Clue game state.

Creates a new game state with a random or specified solution, deals cards to players, and sets up the initial game conditions. The solution is kept secret and the remaining cards are distributed between players.

Parameters:

**kwargs –

Keyword arguments for customization: solution (ClueSolution, optional): Predefined solution. If not provided,

a random solution will be generated.

first_player (str, optional): Which player goes first (“player1” or “player2”).

Defaults to “player1”.

max_turns (int, optional): Maximum number of turns before game ends.

Defaults to 20.

Returns:

A new initialized game state ready for play.

Return type:

ClueState

Examples

Creating a random game:

state = ClueState.initialize()
print(f"Game initialized with random solution")
print(f"Player 1 has {len(state.player1_cards)} cards")
print(f"Player 2 has {len(state.player2_cards)} cards")

Creating a game with specific solution:

from haive.games.clue.models import ClueSolution, ValidSuspect, ValidWeapon, ValidRoom

solution = ClueSolution(
    suspect=ValidSuspect.COLONEL_MUSTARD,
    weapon=ValidWeapon.KNIFE,
    room=ValidRoom.KITCHEN
)
state = ClueState.initialize(
    solution=solution,
    first_player="player2",
    max_turns=15
)

Checking initialization results:

state = ClueState.initialize()

# Verify solution is set
assert state.solution.suspect in ValidSuspect
assert state.solution.weapon in ValidWeapon
assert state.solution.room in ValidRoom

# Verify cards are distributed
total_cards = len(state.player1_cards) + len(state.player2_cards)
assert total_cards == 18  # 21 total cards - 3 solution cards

# Verify initial state
assert state.current_player == "player1"  # Default first player
assert state.game_status == "ongoing"
assert len(state.guesses) == 0
assert len(state.responses) == 0

Note

The solution cards are automatically removed from the deck before dealing to players, ensuring they remain hidden. Card distribution is as even as possible, with any extra cards going to player1.

property board_string: str¶

Get a string representation of the game board.

Creates a formatted string showing the history of guesses and responses, useful for display purposes and debugging.

Returns:

Formatted string representation of the game history.

Return type:

str

Examples

Displaying game history:

state = ClueState.initialize()
# After some guesses...
print(state.board_string)
# Output:
# Turn 1: Colonel Mustard, Knife, Kitchen | Response: Alice
# Turn 2: Professor Plum, Candlestick, Library | Response: No card shown
property current_turn_number: int¶

Get the current turn number.

The turn number is calculated based on the number of guesses made so far, starting from 1 for the first turn.

Returns:

The current turn number (1-based).

Return type:

int

Examples

Checking turn number:

state = ClueState.initialize()
print(f"Turn {state.current_turn_number}")  # "Turn 1"

# After first guess
state.guesses.append(guess)
print(f"Turn {state.current_turn_number}")  # "Turn 2"
property is_game_over: bool¶

Check if the game is over.

The game is over when the status is no longer “ongoing”, which happens when a player wins or the maximum turns are reached.

Returns:

True if the game has ended, False otherwise.

Return type:

bool

Examples

Checking game status:

state = ClueState.initialize()
if state.is_game_over:
    print(f"Game ended! Winner: {state.winner}")
else:
    print("Game is still in progress")