games.chess.state

Chess game state models.

This module defines the state schema for chess games, including:

  • Board state representation using FEN notation

  • Move history tracking

  • Game status management

  • Position analysis storage

  • Player turn tracking

The state schema provides a complete representation of a chess game state that can be used by the agent and state manager.

Classes

ChessState

State schema for the chess game.

Module Contents

class games.chess.state.ChessState(/, **data)

Bases: haive.core.schema.state_schema.StateSchema

State schema for the chess game.

This class extends StateSchema to provide a comprehensive representation of a chess game, including board state, move history, game status, and analysis information.

Parameters:

data (Any)

board_fens

List of FEN board states, with the most recent at the end.

Type:

List[str]

move_history

List of (player_color, UCI move) tuples.

Type:

List[tuple[str, str]]

current_player

Color of the player making the current move.

Type:

Literal[“white”, “black”]

turn

Current turn color.

Type:

Literal[“white”, “black”]

game_status

Current status of the game.

Type:

Literal[“ongoing”, “check”, “checkmate”, “stalemate”, “draw”]

game_result

Final game result (white_win, black_win, draw) if game is over.

Type:

Optional[str]

white_analysis

Position analysis from white’s perspective.

Type:

List[Dict[str, Any]]

black_analysis

Position analysis from black’s perspective.

Type:

List[Dict[str, Any]]

captured_pieces

Pieces captured by each player.

Type:

Dict[str, List[str]]

error_message

Error message if any error occurred.

Type:

Optional[str]

legal_moves

String representation of legal moves in current position.

Type:

Optional[str]

recent_moves

Recent moves formatted for LLM context.

Type:

Optional[str]

Examples

>>> from haive.games.chess import ChessState
>>> state = ChessState()
>>> state.board_fen
'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1'
>>> board = state.get_board()
>>> board.is_check()
False

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_board()

Get a chess.Board object for the current position.

Creates a Python-chess Board object initialized with the current FEN position.

Returns:

Board object representing the current position.

Return type:

chess.Board

Raises:

ValueError – If the FEN string is invalid or cannot be parsed.

Example

>>> state = ChessState()
>>> board = state.get_board()
>>> board.is_game_over()
False
property board_fen: str

Get the current board state as FEN notation.

Returns:

The FEN representation of the current board position.

Return type:

str

property current_board_fen: str

Alias for board_fen for backwards compatibility.

Returns:

The FEN representation of the current board position.

Return type:

str