games.base.state_manager¶

Base state manager module for game agents.

This module provides the foundational state manager class that handles game state transitions and operations. It defines the interface that all game-specific state managers should implement.

Example

>>> class ChessStateManager(GameStateManager[ChessMove]):
...     @classmethod
...     def initialize(cls) -> ChessState:
...         return ChessState.new_game()
...
...     @classmethod
...     def apply_move(cls, state: ChessState, move: ChessMove) -> ChessState:
...         return state.apply_move(move)

Typical usage:

Inherit from GameStateManager to create game-specific state managers
Implement the required methods for state initialization and transitions
Use in conjunction with game agents to manage game flow

Classes¶

GameStateManager

Base state manager that implements common game state operations.

Module Contents¶

class games.base.state_manager.GameStateManager¶

Bases: Generic[T]

Base state manager that implements common game state operations.

This class provides the interface for managing game state transitions and operations. Each game should extend this with game-specific logic by implementing the required methods.

Type Parameters:: T: The type of the game state, must be a Pydantic BaseModel.

Example

>>> class ChessStateManager(GameStateManager[ChessState]):
...     @classmethod
...     def initialize(cls) -> ChessState:
...         return ChessState.new_game()
...
...     @classmethod
...     def apply_move(cls, state: ChessState, move: ChessMove) -> ChessState:
...         return state.apply_move(move)

classmethod apply_move(state, move)¶

Abstractmethod:

Parameters:

state (T)
move (Any)

Return type:

Apply a move to the game state.

This method should create and return a new game state that reflects the application of the given move to the current state.

Parameters:

state (T) – The current game state.
move (Any) – The move to apply.

Returns:

A new game state after applying the move.

Return type:

Raises:

NotImplementedError – This method must be implemented by subclasses.

Example

>>> @classmethod
... def apply_move(cls, state: ChessState, move: ChessMove) -> ChessState:
...     new_board = state.board.make_move(move)
...     return ChessState(
...         board=new_board,
...         turn="black" if state.turn == "white" else "white",
...         move_history=state.move_history + [move]
...     )

classmethod check_game_status(state)¶

Abstractmethod:
Parameters:: state (T)
Return type:: T

Check and update the game status.

This method should examine the current game state and determine if the game status needs to be updated (e.g., if someone has won or if the game is a draw).

Parameters:: state (T) – The current game state.
Returns:: The game state with updated status.
Return type:: T
Raises:: NotImplementedError – This method must be implemented by subclasses.

Example

>>> @classmethod
... def check_game_status(cls, state: ChessState) -> ChessState:
...     if state.board.is_checkmate():
...         state.game_status = "checkmate"
...     elif state.board.is_stalemate():
...         state.game_status = "stalemate"
...     return state

classmethod get_legal_moves(state)¶

Abstractmethod:
Parameters:: state (T)
Return type:: list[Any]

Get all legal moves for the current state.

This method should return a list of all valid moves that can be made from the current game state.

Parameters:: state (T) – The current game state.
Returns:: A list of legal moves.
Return type:: List[Any]
Raises:: NotImplementedError – This method must be implemented by subclasses.

Example

>>> @classmethod
... def get_legal_moves(cls, state: ChessState) -> List[ChessMove]:
...     return state.board.get_legal_moves(state.turn)

classmethod initialize(**kwargs)¶

Abstractmethod:
Return type:: T

Initialize a new game state.

This method should create and return a new instance of the game state with initial values set appropriately for the start of a game.

Parameters:: **kwargs – Additional keyword arguments for game-specific initialization.
Returns:: A new instance of the game state.
Return type:: T
Raises:: NotImplementedError – This method must be implemented by subclasses.

Example

>>> @classmethod
... def initialize(cls) -> ChessState:
...     return ChessState(
...         board=Board.initial_setup(),
...         turn="white",
...         game_status="ongoing"
...     )