haive.games.fox_and_geese.state¶

Comprehensive state management system for Fox and Geese gameplay and strategic. analysis.

This module provides sophisticated state models for the classic Fox and Geese game with complete support for position tracking, strategic analysis, and game flow management. The state system maintains both traditional game mechanics and advanced strategic context for AI decision-making.

The Fox and Geese game is an asymmetric strategy game where: - One player controls the fox (trying to escape to the other side) - The other player controls multiple geese (trying to trap the fox) - The fox can capture geese by jumping over them - The geese win by blocking all fox movement - The fox wins by reaching the opposite side or reducing geese numbers

The state system supports: - Complete position tracking for fox and geese - Strategic analysis history for both players - Move validation and game completion detection - Performance metrics and statistical analysis - Board visualization and position evaluation

Examples

Creating a new game state:

state = FoxAndGeeseState.initialize()
assert state.turn == "fox"
assert state.game_status == "ongoing"
assert len(state.geese_positions) > 0

Accessing position information:

# Check current positions
fox_pos = state.fox_position
geese_count = state.num_geese
board_display = state.board_string

# Strategic analysis
fox_mobility = state.fox_mobility_score
geese_formation = state.geese_formation_strength

Tracking game progression:

# Check game completion
if state.is_game_over():
    winner = state.winner
    final_analysis = state.position_evaluation

# Move history analysis
recent_moves = state.get_recent_moves(3)
capture_count = state.total_captures

Note

All state models use Pydantic v2 for validation and support both JSON serialization and integration with LangGraph for distributed gameplay.

Classes¶

FoxAndGeeseState

Comprehensive state management for Fox and Geese gameplay with strategic.

Module Contents¶

class haive.games.fox_and_geese.state.FoxAndGeeseState(/, **data)[source]¶

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

Comprehensive state management for Fox and Geese gameplay with strategic. analysis.

This class provides complete state management for the classic Fox and Geese game, supporting both traditional game mechanics and strategic analysis. The state system maintains position tracking, strategic context, and performance metrics for advanced AI decision-making and game analysis.

The Fox and Geese game features asymmetric gameplay: - Fox: Single piece trying to escape to the opposite side or eliminate geese - Geese: Multiple pieces trying to trap the fox and prevent escape - Fox can capture geese by jumping over them (similar to checkers) - Geese cannot capture but can block fox movement - Victory conditions differ for each player

The state system supports: - Complete position tracking with validation for both fox and geese - Strategic analysis history for both players with pattern recognition - Move validation and legal move generation - Game completion detection with multiple victory conditions - Performance metrics and statistical analysis for gameplay optimization - Board visualization and position evaluation for strategic assessment

Parameters:: data (Any)

players¶

Fixed list of players [“fox”, “geese”]. Maintains consistent player identification.

Type:: List[str]

fox_position¶

Current position of the fox piece. Tracked with full coordinate validation.

Type:: FoxAndGeesePosition

geese_positions¶

Current positions of all geese. Maintained as a set for efficient position queries.

Type:: Set[FoxAndGeesePosition]

turn¶

Current player’s turn. Alternates between fox and geese players.

Type:: Literal[“fox”, “geese”]

game_status¶

Current game state with completion detection. Tracks ongoing play and victory conditions.

Type:: Literal

move_history¶

Complete chronological move history. Includes all moves made during the game.

Type:: List[FoxAndGeeseMove]

winner¶

Winner identifier if game completed. Set when victory conditions are met.

Type:: Optional[str]

num_geese¶

Current number of geese remaining on the board. Updated when geese are captured by the fox.

Type:: int

fox_analysis¶

Strategic analysis history for fox player. Tracks reasoning and decision-making patterns.

Type:: List[str]

geese_analysis¶

Strategic analysis history for geese player. Tracks reasoning and decision-making patterns.

Type:: List[str]

Examples

Creating a new game state:

state = FoxAndGeeseState.initialize()
assert state.turn == "fox"
assert state.game_status == "ongoing"
assert state.fox_position.row == 3  # Center position
assert len(state.geese_positions) > 0

Accessing position information:

# Check current positions
fox_pos = state.fox_position
geese_count = state.num_geese
board_display = state.board_string

# Strategic metrics
fox_mobility = state.fox_mobility_score
geese_formation = state.geese_formation_strength
escape_distance = state.fox_escape_distance

Managing strategic analysis:

# Add analysis for fox player
state.fox_analysis.append("Fox should move toward weak geese formation")

# Add analysis for geese player
state.geese_analysis.append("Geese should form blocking line")

# Access latest strategic insights
latest_fox_analysis = state.get_latest_fox_analysis()
latest_geese_analysis = state.get_latest_geese_analysis()

Game state queries:

# Check game completion
if state.is_game_over():
    winner = state.winner
    final_analysis = state.position_evaluation

# Strategic position analysis
mobility_analysis = state.mobility_analysis
capture_threats = state.capture_threat_analysis
formation_strength = state.formation_analysis

Advanced game analysis:

# Performance metrics
stats = state.game_statistics
print(f"Total moves: {stats['total_moves']}")
print(f"Capture rate: {stats['capture_rate']:.1f}%")

# Strategic evaluation
position_eval = state.position_evaluation
print(f"Fox advantage: {position_eval['fox_advantage']:.2f}")
print(f"Geese control: {position_eval['geese_control']:.2f}")

Note

The state uses Pydantic v2 for validation and supports both JSON serialization and integration with LangGraph for distributed game systems. All position operations maintain game rule consistency and strategic context.

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.

get_latest_fox_analysis()[source]¶

Get the latest strategic analysis for fox player.

Returns:: Latest fox analysis or None if no analysis exists.
Return type:: Optional[str]

get_latest_geese_analysis()[source]¶

Get the latest strategic analysis for geese player.

Returns:: Latest geese analysis or None if no analysis exists.
Return type:: Optional[str]

get_recent_moves(count)[source]¶

Get the most recent moves from the game history.

Parameters:: count (int) – Number of recent moves to return.
Returns:: List of recent moves (up to count).
Return type:: List[FoxAndGeeseMove]

classmethod initialize()[source]¶

Initialize a new Fox and Geese game.

Return type:: FoxAndGeeseState

is_game_over()[source]¶

Check if the game is over.

Returns:: True if game is over, False otherwise.
Return type:: bool

model_dump(**kwargs)[source]¶

Override model_dump to ensure proper serialization.

Return type:: dict[str, Any]

classmethod model_validate(obj, **kwargs)[source]¶

Override model_validate to handle various input formats.

Parameters:: obj (Any)
Return type:: FoxAndGeeseState

serialize_fox_position(fox_position)[source]¶

Serialize fox position as a dictionary.

Parameters:: fox_position (haive.games.fox_and_geese.models.FoxAndGeesePosition)
Return type:: dict[str, Any]

serialize_geese_positions(geese_positions)[source]¶

Serialize geese positions as a list of dictionaries.

Parameters:: geese_positions (set[haive.games.fox_and_geese.models.FoxAndGeesePosition])
Return type:: list[dict[str, Any]]

serialize_move_history(move_history)[source]¶

Serialize move history as a list of dictionaries.

Parameters:: move_history (list[haive.games.fox_and_geese.models.FoxAndGeeseMove])
Return type:: list[dict[str, Any]]

classmethod validate_fox_position(v)[source]¶

Validate and convert fox position.

Parameters:: v (Any)
Return type:: haive.games.fox_and_geese.models.FoxAndGeesePosition

classmethod validate_geese_positions(v)[source]¶

Validate and convert geese positions to a set.

Parameters:: v (Any)
Return type:: set[haive.games.fox_and_geese.models.FoxAndGeesePosition]

classmethod validate_move_history(v)[source]¶

Validate and convert move history.

Parameters:: v (Any)
Return type:: list[haive.games.fox_and_geese.models.FoxAndGeeseMove]

property board_string: str¶

Get a string representation of the board.

Return type:: str

property fox_escape_distance: int¶

Calculate minimum distance for fox to reach escape edge.

Returns:: Minimum number of moves to reach the opposite edge.
Return type:: int

property fox_mobility_score: float¶

Calculate fox mobility score based on available moves.

Returns:: Mobility score from 0.0 (trapped) to 1.0 (maximum mobility).
Return type:: float

property game_statistics: dict[str, int | float | str]¶

Generate comprehensive game statistics.

Returns:: Game statistics and metrics.
Return type:: Dict[str, Union[int, float, str]]

property geese_formation_strength: float¶

Calculate geese formation strength for blocking fox.

Returns:: Formation strength from 0.0 (weak) to 1.0 (strong).
Return type:: float

model_config¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property position_evaluation: dict[str, str | float]¶

Generate strategic position evaluation.

Returns:: Position evaluation metrics.
Return type:: Dict[str, Union[str, float]]

property total_captures: int¶

Count total number of geese captured by fox.

Returns:: Number of geese captured during the game.
Return type:: int