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¶
Agent for playing checkers with LLM-based players and rich UI. |
Module Contents¶
- class games.checkers.agent.CheckersAgent(config)¶
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:
- ui¶
Rich UI for game visualization
- Type:
- 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)¶
Analyze the position for player 1 (red).
Handles position analysis for the red player.
- analyze_player2(state)¶
Analyze the position for player 2 (black).
Handles position analysis for the black player.
- analyze_position(state, player)¶
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)¶
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)¶
Initialize a new checkers game.
Creates a fresh checkers game state and routes to the first player’s move.
- make_move(state, player)¶
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)¶
Make a move for player 1 (red).
Handles the red player’s turn, routing appropriately based on the current game state.
- make_player2_move(state)¶
Make a move for player 2 (black).
Handles the black player’s turn, routing appropriately based on the current game state.
- prepare_analysis_context(state, player)¶
Prepare context for position analysis.
Creates a context dictionary with all necessary information for the analyzer engines to evaluate a position.
- prepare_move_context(state, player)¶
Prepare context for move generation.
Creates a context dictionary with all necessary information for the player engines to make a move decision.
- run_game(visualize=True)¶
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:
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()¶
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.
Examples
>>> agent = CheckersAgent(CheckersAgentConfig()) >>> final_state = agent.run_game_with_ui() >>> print(f"Winner: {final_state.get('winner')}")
- setup_workflow()¶
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