haive.games.chess.state_manager

Chess game state management module.

This module provides comprehensive state management functionality for chess games, including game initialization, move validation, position tracking, and game status management using the standard chess library.

Chess is a strategic board game played on an 8×8 checkered board between two players. Each player begins with 16 pieces: one king, one queen, two rooks, two bishops, two knights, and eight pawns. The objective is to checkmate the opponent’s king.

Classes:

ChessGameStateManager: Main state management class for chess game operations.

Example

Basic chess game setup and play:

>>> from haive.games.chess.state_manager import ChessGameStateManager
>>>
>>> # Initialize game in starting position
>>> state = ChessGameStateManager.initialize()
>>> print(f"Starting position: {state.board_fen}")
>>> print(f"Current turn: {state.turn}")  # "white"
>>>
>>> # Apply opening moves
>>> state = ChessGameStateManager.apply_move(state, "e2e4")  # King's pawn
>>> print(f"After e2e4, turn: {state.turn}")  # "black"
>>>
>>> state = ChessGameStateManager.apply_move(state, "e7e5")  # Mirror move
>>> print(f"Move history: {state.move_history}")

Note

  • Moves must be in UCI notation (e.g., “e2e4”, “Ng1f3”)

  • The chess library handles all rule validation and special moves

  • Game states include full FEN position, move history, and captured pieces

  • This module has known issues with the apply_move method accessing analysis fields

Warning

The apply_move method currently has a bug when trying to access state.analysis instead of the correct state.white_analysis/state.black_analysis fields.

Classes

ChessGameStateManager

Chess game state manager.

Module Contents

class haive.games.chess.state_manager.ChessGameStateManager

Chess game state manager.

This class provides static methods for managing chess game states:

  • Game initialization with default settings

  • Move application with validation

  • Game status updates

  • Captured pieces tracking

The manager implements a functional approach where methods take the current state and return a new state, rather than modifying the state in place.

Examples

>>> state = ChessGameStateManager.initialize()
>>> print(state.board_fen)
'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1'

>>> new_state = ChessGameStateManager.apply_move(state, "e2e4")
>>> print(new_state.board_fen)
'rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1'
static apply_move(state, move_uci)

Apply a move to the current game state.

Takes the current game state and a move in UCI format, validates it, applies it to the board, and returns a new state with updated properties.

Parameters:

  • state (ChessState) – Current game state.

  • move_uci (str) – Move in UCI notation (e.g., “e2e4”).

Returns:

New game state after applying the move.

Return type:

ChessState

Raises:

ValueError – If the move is not valid in the current position.

Note

This method handles: - Board position updates - Captured pieces tracking - Game status changes (check, checkmate, stalemate) - Player turn switching

Examples

>>> state = ChessGameStateManager.initialize()
>>> new_state = ChessGameStateManager.apply_move(state, "e2e4")
>>> assert new_state.turn == "black"
>>> assert "e2e4" in new_state.move_history

>>> # Detecting checkmate
>>> from chess import Board
>>> board = Board.from_epd("8/8/8/8/8/5K2/4Q3/7k w - - 0 1")
>>> state = ChessState(board_fen=board.fen())
>>> new_state = ChessGameStateManager.apply_move(state, "e2e1")
>>> assert new_state.game_status == "checkmate"
static initialize()

Initialize a new chess game state.

Creates a fresh chess game state with standard initial position and default settings for all game parameters.

Returns:

A fresh game state with standard starting position.

Return type:

ChessState

Examples

>>> state = ChessGameStateManager.initialize()
>>> assert state.turn == "white"
>>> assert state.game_status == "ongoing"
>>> assert state.board_fen.startswith("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR")