games.base.agent¶

Base game agent module.

This module provides the foundational GameAgent class that implements common workflow patterns for game-specific agents. It handles game initialization, move generation, position analysis, and game flow control.

Example

>>> class ChessAgent(GameAgent[ChessConfig]):
...     def __init__(self, config: ChessConfig):
...         super().__init__(config)
...         self.state_manager = ChessStateManager

Typical usage:

Inherit from GameAgent to create game-specific agents
Override necessary methods like prepare_move_context and extract_move
Use the setup_workflow method to customize the game flow

Classes¶

GameAgent

Base game agent that implements common workflow patterns.

Functions¶

run_game(agent[, initial_state])

Run a complete game with the given agent.

Module Contents¶

class games.base.agent.GameAgent(config)¶

Bases: haive.core.engine.agent.agent.Agent[haive.games.framework.base.config.GameConfig], Generic[T]

Base game agent that implements common workflow patterns.

This class provides a foundation for building game-specific agents by implementing common patterns for game initialization, move generation, position analysis, and game flow control. Game-specific agents should inherit from this class and override the necessary methods.

config¶

Configuration for the game agent.

Type:: GameConfig

state_manager¶: Manager for handling game state transitions.

engines¶

Dictionary of LLM engines for different functions.

Type:: Dict[str, Any]

graph¶: The workflow graph for the game.

Example

>>> class ChessAgent(GameAgent[ChessConfig]):
...     def __init__(self, config: ChessConfig):
...         super().__init__(config)
...         self.state_manager = ChessStateManager
...
...     def prepare_move_context(self, state, player):
...         legal_moves = self.state_manager.get_legal_moves(state)
...         return {"legal_moves": legal_moves}

Initialize the game agent.

Parameters:: config (GameConfig, optional) – Configuration for the game agent. Defaults to GameConfig().

abstractmethod analyze_player1(state)¶

Analyze position for player 1.

This method should be implemented by subclasses to handle position analysis specifically for player 1.

Parameters:: state (T) – The current game state.
Returns:: A command containing the updated game state with analysis.
Return type:: Command
Raises:: NotImplementedError – This method must be implemented by subclasses.

Example

>>> def analyze_player1(self, state):
...     return self.analyze_position(state, "player1")

abstractmethod analyze_player2(state)¶

Analyze position for player 2.

This method should be implemented by subclasses to handle position analysis specifically for player 2.

Parameters:: state (T) – The current game state.
Returns:: A command containing the updated game state with analysis.
Return type:: Command
Raises:: NotImplementedError – This method must be implemented by subclasses.

Example

>>> def analyze_player2(self, state):
...     return self.analyze_position(state, "player2")

analyze_position(state, player)¶

Analyze the position for the specified player.

This method handles position analysis including: 1. Getting the appropriate analyzer engine 2. Preparing the analysis context 3. Generating and storing the analysis

Parameters:

state (T) – The current game state.
player (str) – The player for whom to analyze the position.

Returns:

A command containing the updated game state with analysis.

Return type:

Command

Example

>>> def analyze_position(self, state, player):
...     analyzer = self.engines.get(f"{player}_analyzer")
...     analysis = analyzer.invoke({"position": state.board})
...     return Command(update={f"{player}_analysis": analysis})

abstractmethod extract_move(response)¶

Extract move from engine response.

This method should be implemented by subclasses to parse the LLM’s response and extract a valid move.

Parameters:: response (Any) – The raw response from the LLM engine.
Returns:: A valid move object for the game.
Return type:: Any
Raises:: NotImplementedError – This method must be implemented by subclasses.

Example

>>> def extract_move(self, response):
...     move_text = response.get("move")
...     return ChessMove.from_uci(move_text)

initialize_game(state)¶

Initialize a new game.

Parameters:: state (Dict[str, Any]) – The initial state dictionary.
Returns:: A command containing the initialized game state.
Return type:: Command

Example

>>> def initialize_game(self, state):
...     game_state = self.state_manager.initialize()
...     return Command(update=game_state.dict())

make_move(state, player)¶

Make a move for the specified player.

This method handles the complete move generation process including: 1. Getting the appropriate engine for the player 2. Preparing the move context 3. Generating and validating the move 4. Applying the move to the game state

Parameters:

state (T) – The current game state.
player (str) – The player making the move.

Returns:

A command containing the updated game state after the move.

Return type:

Command

Example

>>> def make_move(self, state, player):
...     engine = self.engines.get(f"{player}_player")
...     move_context = self.prepare_move_context(state, player)
...     response = engine.invoke(move_context)
...     move = self.extract_move(response)
...     new_state = self.state_manager.apply_move(state, move)
...     return Command(update=new_state.dict())

abstractmethod make_player1_move(state)¶

Make a move for player 1.

This method should be implemented by subclasses to handle moves specifically for player 1.

Parameters:: state (T) – The current game state.
Returns:: A command containing the updated game state after the move.
Return type:: Command
Raises:: NotImplementedError – This method must be implemented by subclasses.

Example

>>> def make_player1_move(self, state):
...     return self.make_move(state, "player1")

abstractmethod make_player2_move(state)¶

Make a move for player 2.

This method should be implemented by subclasses to handle moves specifically for player 2.

Parameters:: state (T) – The current game state.
Returns:: A command containing the updated game state after the move.
Return type:: Command
Raises:: NotImplementedError – This method must be implemented by subclasses.

Example

>>> def make_player2_move(self, state):
...     return self.make_move(state, "player2")

abstractmethod prepare_analysis_context(state, player)¶

Prepare context for position analysis.

This method should be implemented by subclasses to provide the necessary context for the LLM to analyze a position.

Parameters:

state (T) – The current game state.
player (str) – The player for whom to prepare the analysis context.

Returns:

The context dictionary for position analysis.

Return type:

Dict[str, Any]

Raises:

NotImplementedError – This method must be implemented by subclasses.

Example

>>> def prepare_analysis_context(self, state, player):
...     return {
...         "board": state.board.to_fen(),
...         "material_count": state.get_material_count(player),
...         "previous_moves": state.move_history[-5:]
...     }

abstractmethod prepare_move_context(state, player)¶

Prepare context for move generation.

This method should be implemented by subclasses to provide the necessary context for the LLM to generate a move.

Parameters:

state (T) – The current game state.
player (str) – The player for whom to prepare the context.

Returns:

The context dictionary for move generation.

Return type:

Dict[str, Any]

Raises:

NotImplementedError – This method must be implemented by subclasses.

Example

>>> def prepare_move_context(self, state, player):
...     legal_moves = self.state_manager.get_legal_moves(state)
...     return {
...         "board": state.board.to_fen(),
...         "legal_moves": legal_moves,
...         "player": player
...     }

setup_workflow()¶

Setup the standard game workflow with configurable analysis.

This method sets up the default game workflow including initialization, player moves, and optional position analysis. Override this method to implement custom game flows.

The default workflow includes: 1. Game initialization 2. Alternating player moves 3. Optional position analysis before each move 4. Game continuation checks between moves

Example

>>> def setup_workflow(self):
...     # Add custom nodes
...     self.graph.add_node("custom_analysis", self.analyze_position)
...     # Modify the workflow
...     self.graph.add_edge("initialize_game", "custom_analysis")

Return type:: None

should_continue_game(state)¶

Determine if the game should continue.

Parameters:: state (T) – The current game state.
Returns:: True if the game should continue, False otherwise.
Return type:: bool

Example

>>> def should_continue_game(self, state):
...     return state.moves_remaining > 0 and not state.checkmate

games.base.agent.run_game(agent, initial_state=None)¶

Run a complete game with the given agent.

This function executes a game from start to finish using the provided agent. It handles game initialization, move execution, state visualization, and error reporting. The game can optionally start from a provided initial state.

Parameters:

agent (GameAgent) – The game agent to run the game with.
initial_state (Optional[Dict[str, Any]], optional) – Initial game state. If not provided, a new game will be initialized. Defaults to None.

Example

>>> agent = ChessAgent(ChessConfig())
>>> # Start a new game
>>> run_game(agent)
>>>
>>> # Continue from a saved state
>>> run_game(agent, saved_state)

Note

The function will print game progress to the console
Game visualization depends on the agent’s visualize_state method
Game history will be saved using the agent’s save_state_history method