games.chess.agent¶

Chess agent implementation using LangGraph.

This module provides a chess agent implementation using LangGraph, featuring:

LLM-powered chess players
Position analysis
Game state management
Workflow graph for turn-based gameplay
Error handling and retry logic

The agent orchestrates the game flow between two LLM players and handles all game mechanics including move validation, position analysis, and game status tracking.

Classes¶

ChessAgent

Chess agent implementation using LangGraph.

Module Contents¶

class games.chess.agent.ChessAgent(config)¶

Bases: haive.core.engine.agent.agent.Agent[haive.games.chess.config.ChessConfig]

Chess agent implementation using LangGraph.

This agent implements a complete chess game using language models for move generation and position analysis. It uses LangGraph to create a workflow graph that manages the game flow between players.

Features:

LLM-powered chess players with structured outputs
Optional position analysis for enhanced play
Move validation and retry logic
Game status tracking and termination
Error handling and fallback moves

config¶

Configuration for the chess agent

Type:: ChessConfig

engines¶

LLM engines for players and analyzers

Type:: Dict[str, Any]

graph¶

LangGraph workflow for the chess game

Type:: StateGraph

Initialize the chess agent.

Parameters:: config (ChessConfig) – Configuration for the chess agent, including LLM engine settings, analysis options, and game parameters.

analyze_black_position(state)¶

Analyze the board position for the black player.

Parameters:: state (ChessState) – Current game state
Returns:: LangGraph command with black analysis updates
Return type:: Command

analyze_position(state, color)¶

Analyze the board position for the specified player.

This method uses the configured analyzer engine to generate a detailed position analysis from the perspective of the given player color.

Parameters:

state (ChessState) – Current game state
color (str) – Player color (“white” or “black”)

Returns:

LangGraph command with analysis updates

Return type:

Command

Note

Analysis results are stored in the state’s white_analysis or black_analysis fields, depending on the color.

analyze_white_position(state)¶

Analyze the board position for the white player.

Parameters:: state (ChessState) – Current game state
Returns:: LangGraph command with white analysis updates
Return type:: Command

check_game_status(state)¶

Check and update the game status.

This method evaluates the current board position to determine if the game has ended (checkmate, stalemate, draw) or if it should continue.

Game-ending conditions include: - Checkmate - Stalemate - Insufficient material - Maximum move limit reached

Parameters:: state (ChessState) – Current game state
Returns:: LangGraph command with game status updates
Return type:: Command

make_black_move(state)¶

Make a move for the black player.

Parameters:: state (ChessState) – Current game state
Returns:: LangGraph command with state updates
Return type:: Command

make_move(state, color)¶

Make a move for the specified player with retry logic.

This method handles the complete move generation process:

Gets legal moves from the current position
Sends context to the appropriate LLM engine
Validates the returned move
Updates the game state with the new move

Includes retry logic for invalid moves, with fallback to a safe move if all attempts fail.

Parameters:

state (ChessState) – Current game state
color (str) – Player color (“white” or “black”)

Returns:

LangGraph command with state updates

Return type:

Command

Examples

>>> command = agent.make_move(state, "white")
>>> command.update  # Contains the updated game state
{'board_fens': [...], 'move_history': [...], ...}

make_white_move(state)¶

Make a move for the white player.

Parameters:: state (ChessState) – Current game state
Returns:: LangGraph command with state updates
Return type:: Command

route_next_step(state)¶

Determine the next step in the workflow.

This conditional router decides where to direct the flow next based on the current game state: - If the game is over, route to the end - Otherwise, route to the next player’s turn

Parameters:: state (ChessState) – Current game state
Returns:: The next step key for the workflow graph
Return type:: str

Note

Return values correspond to the keys in the conditional edges of the graph: “game_over”, “continue_white”, or “continue_black”.

setup_workflow()¶

Set up the workflow graph for the chess game.

Creates a LangGraph StateGraph with nodes for:

White player’s moves
Black player’s moves
Game status checking
Optional position analysis

The graph flow depends on the current player and game status, with conditional edges for routing between nodes.

Return type:: None