haive.games.checkers.agent¶

Checkers agent implementation module.

This module provides the main checkers agent implementation using LangGraph, including:

Dynamic graph-based workflow for turn management
LLM-powered player engines for move generation
Position analysis and evaluation
Error handling and retry logic
Rich UI visualization
Game flow orchestration

The agent uses a state-based approach with LangGraph for managing the game workflow and supports both automated play and human interaction through a beautiful UI.

Classes¶

CheckersAgent

Agent for playing checkers with LLM-based players and rich UI.

Module Contents¶

class haive.games.checkers.agent.CheckersAgent(config)[source]¶

Bases: haive.games.framework.base.GameAgent[haive.games.checkers.config.CheckersAgentConfig]

Agent for playing checkers with LLM-based players and rich UI.

This agent implements a complete checkers 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 checkers players with structured outputs
Position analysis for better decision making
Beautiful rich-text UI visualization
Move validation and retry logic
Game status tracking and termination
Error handling and fallback moves

config¶

Configuration for the checkers agent

Type:: CheckersAgentConfig

state_manager¶

Manager for game state operations

Type:: CheckersStateManager

ui¶

Rich UI for game visualization

Type:: CheckersUI

engines¶

LLM engines for players and analyzers

Type:: dict

graph¶

LangGraph workflow for the checkers game

Type:: DynamicGraph

Examples

>>> # Create and run a checkers game
>>> agent = CheckersAgent(CheckersAgentConfig())
>>> final_state = agent.run_game(visualize=True)
>>>
>>> # Check the final game state
>>> print(f"Game winner: {final_state.get('winner')}")

Initialize the checkers agent.

Sets up the state manager, UI, and other components needed for the checkers game.

Parameters:: config (CheckersAgentConfig) – Configuration for the checkers agent

analyze_player1(state)[source]¶

Analyze the position for player 1 (red).

Handles position analysis for the red player.

Parameters:: state (dict[str, Any]) – Current game state
Returns:: LangGraph command with updated state and next node
Return type:: Command

analyze_player2(state)[source]¶

Analyze the position for player 2 (black).

Handles position analysis for the black player.

Parameters:: state (dict[str, Any]) – Current game state
Returns:: LangGraph command with updated state and next node
Return type:: Command

analyze_position(state, player)[source]¶

Analyze the position for a player.

Gets a detailed position analysis from the appropriate analyzer engine and updates the game state with the analysis.

Parameters:

state (CheckersState) – Current game state
player (str) – Player to analyze for (“red” or “black”)

Returns:

LangGraph command with updated state and next node

Return type:

Command

extract_move(response)[source]¶

Extract a move from a player decision.

Gets the selected move from a player’s decision object.

Parameters:: response (CheckersPlayerDecision) – Player’s move decision
Returns:: The selected move
Return type:: CheckersMove

initialize_game(state)[source]¶

Initialize a new checkers game.

Creates a fresh checkers game state and routes to the first player’s move.

Parameters:: state (dict[str, Any]) – Initial state data (usually empty)
Returns:: LangGraph command with initialized game state
Return type:: Command

make_move(state, player)[source]¶

Make a move with error handling and retry logic.

Core method for generating and applying moves, with robust error handling and visualization.

The method: 1. Shows a thinking animation 2. Gets legal moves 3. Prepares context for the LLM 4. Gets a move decision from the appropriate engine 5. Validates and applies the move 6. Updates the game state

Includes retry logic for invalid moves and fallback to the first legal move if all attempts fail.

Parameters:

state (CheckersState) – Current game state
player (str) – Player to make the move (“red” or “black”)

Returns:

LangGraph command with updated state and next node

Return type:

Command

make_player1_move(state)[source]¶

Make a move for player 1 (red).

Handles the red player’s turn, routing appropriately based on the current game state.

Parameters:: state (dict[str, Any]) – Current game state
Returns:: LangGraph command with updated state and next node
Return type:: Command

make_player2_move(state)[source]¶

Make a move for player 2 (black).

Handles the black player’s turn, routing appropriately based on the current game state.

Parameters:: state (dict[str, Any]) – Current game state
Returns:: LangGraph command with updated state and next node
Return type:: Command

prepare_analysis_context(state, player)[source]¶

Prepare context for position analysis.

Creates a context dictionary with all necessary information for the analyzer engines to evaluate a position.

Parameters:

state (CheckersState) – Current game state
player (str) – Player to analyze for (“red” or “black”)

Returns:

Context dictionary for analysis

Return type:

dict[str, Any]

prepare_move_context(state, player)[source]¶

Prepare context for move generation.

Creates a context dictionary with all necessary information for the player engines to make a move decision.

Parameters:

state (CheckersState) – Current game state
player (str) – Player to make the move (“red” or “black”)

Returns:

Context dictionary for move generation

Return type:

dict[str, Any]

run_game(visualize=True)[source]¶

Run the checkers game.

Runs a complete checkers game with optional visualization.

Parameters:: visualize (bool, optional) – Whether to show the UI. Defaults to True.
Returns:: Final game state
Return type:: dict[str, Any]

Examples

>>> agent = CheckersAgent(CheckersAgentConfig())
>>> # Run with visualization
>>> final_state = agent.run_game(visualize=True)
>>> # Run without visualization
>>> final_state = agent.run_game(visualize=False)

run_game_with_ui()[source]¶

Run game with beautiful UI visualization.

Runs a complete checkers game with rich UI visualization, streaming the state updates and displaying them in real-time.

Returns:: Final game state
Return type:: dict[str, Any]

Examples

>>> agent = CheckersAgent(CheckersAgentConfig())
>>> final_state = agent.run_game_with_ui()
>>> print(f"Winner: {final_state.get('winner')}")

setup_workflow()[source]¶

Set up the workflow graph for the checkers game.

Creates a LangGraph workflow with nodes for initialization, moves, and analysis, with appropriate edges between them.

The graph flow follows this pattern: initialize → player1_move → analyze_player2 → player2_move → analyze_player1 → loop

Return type:: None

visualize_state(state)[source]¶

Use the rich UI to visualize the current game state.

Displays the current board, game info, move history, and other visual elements using the rich UI.

Parameters:: state (dict[str, Any]) – Current game state
Return type:: None