haive.games.tic_tac_toe.agent¶

Comprehensive agent implementation for strategic Tic Tac Toe gameplay.

This module provides the core agent class for managing Tic Tac Toe games with LLM-driven decision-making, strategic analysis, and flexible gameplay modes. The agent coordinates all aspects of the game including initialization, move generation, position analysis, and game flow management.

The agent supports: - LLM-based move generation with perfect play capability - Strategic position analysis for educational insights - Flexible game flow with conditional analysis - Board visualization for interactive gameplay - Error handling and state validation - Integration with LangGraph for distributed execution - Multiple AI personalities through engine configuration

Examples

Basic game execution:

config = TicTacToeConfig.default_config()
agent = TicTacToeAgent(config)
final_state = agent.run_game()

Tournament play without visualization:

config = TicTacToeConfig.competitive_config()
agent = TicTacToeAgent(config)
result = agent.run_game(visualize=False)

Educational game with analysis:

config = TicTacToeConfig.educational_config()
agent = TicTacToeAgent(config)
agent.run_game(visualize=True, debug=True)

Custom engine configuration:

config = TicTacToeConfig(
    engines=custom_engines,
    enable_analysis=True
)
agent = TicTacToeAgent(config)

Note

The agent uses LangGraph for workflow management and supports concurrent execution with proper state reducers.

Classes¶

TicTacToeAgent

Strategic agent for Tic Tac Toe gameplay with LLM-driven decision- making.

Module Contents¶

class haive.games.tic_tac_toe.agent.TicTacToeAgent(config=TicTacToeConfig())[source]¶

Bases: haive.games.framework.base.agent.GameAgent[haive.games.tic_tac_toe.config.TicTacToeConfig]

Strategic agent for Tic Tac Toe gameplay with LLM-driven decision- making.

This agent manages the complete Tic Tac Toe game lifecycle, from initialization through gameplay to completion. It coordinates LLM engines for move generation and position analysis, maintains game state consistency, and provides flexible gameplay modes for different use cases.

The agent supports: - Automated game initialization with configurable parameters - LLM-based move generation for both X and O players - Optional strategic position analysis after each move - Board visualization for interactive experiences - Error handling and recovery mechanisms - Integration with state management system - Flexible workflow configuration

config¶

Game configuration parameters.

Type:: TicTacToeConfig

state_manager¶

State management system.

Type:: TicTacToeStateManager

engines¶

LLM engines for players and analysis.

Type:: Dict[str, Engine]

graph¶

LangGraph workflow for game execution.

Type:: StateGraph

Examples

Standard gameplay:

agent = TicTacToeAgent()
result = agent.run_game()
print(f"Winner: {result.winner}")

Custom configuration:

config = TicTacToeConfig(
    enable_analysis=False,
    first_player="O"
)
agent = TicTacToeAgent(config)

Tournament mode:

config = TicTacToeConfig.competitive_config()
agent = TicTacToeAgent(config)
# Fast gameplay without visualization

Initialize the Tic Tac Toe agent with configuration.

Sets up the agent with the provided configuration, initializes the state manager, and prepares the workflow graph for game execution.

Parameters:: config (TicTacToeConfig) – Game configuration with engine settings, analysis options, and gameplay parameters.

Examples

Default initialization:

agent = TicTacToeAgent()
# Uses default configuration

Custom configuration:

config = TicTacToeConfig(
    enable_analysis=True,
    visualize=True
)
agent = TicTacToeAgent(config)

analyze_position(state)[source]¶

Analyze the board position for strategic insights.

Performs strategic analysis of the current board position for the player who just moved, providing insights about threats, opportunities, and optimal play. Analysis is only performed if enabled in configuration.

Parameters:: state – Current game state (dict or TicTacToeState).
Returns:: LangGraph command with analysis results and next node.
Return type:: Command

Examples

Post-move analysis:

# After X makes a move
command = agent.analyze_position(state)
# Analyzes position from X's perspective

Analysis disabled:

agent.config.enable_analysis = False
command = agent.analyze_position(state)
# Skips analysis, returns to make_move

Game over analysis:

state.game_status = "X_win"
command = agent.analyze_position(state)
# Returns Command with goto=END

initialize_game(state)[source]¶

Initialize a new Tic Tac Toe game with starting configuration.

Creates the initial game state with an empty board, assigns players to symbols based on configuration, and sets up the first turn.

Parameters:: state (dict[str, Any]) – Initial state dictionary (typically empty).
Returns:: LangGraph command with initialized state and next node.
Return type:: Command

Examples

Standard initialization:

command = agent.initialize_game({})
# Returns Command with empty board, X to play

Custom first player:

agent.config.first_player = "O"
command = agent.initialize_game({})
# Returns Command with O to play first

make_move(state)[source]¶

Generate and execute a move for the current player.

Uses the appropriate LLM engine to generate a move for the current player, validates the move, updates the game state, and determines the next step in the workflow based on game status and configuration.

Parameters:: state – Current game state (dict or TicTacToeState).
Returns:: LangGraph command with state updates and next node.
Return type:: Command
Raises:: Exception – If move generation or application fails.

Examples

X player move:

command = agent.make_move(state)
# X engine generates move, state updated

Game ending move:

command = agent.make_move(near_end_state)
# Returns Command with goto=END if game over

With analysis enabled:

agent.config.enable_analysis = True
command = agent.make_move(state)
# Returns Command with goto="analyze"

prepare_analysis_context(state, symbol)[source]¶

Prepare structured context for strategic position analysis.

Creates a context dictionary for the analysis engine containing the current board state and player information for strategic evaluation.

Parameters:

state (TicTacToeState) – Current game state to analyze.
symbol (str) – Symbol (‘X’ or ‘O’) of the player to analyze for.

Returns:

Analysis context with board state and player symbols.

Return type:

dict[str, Any]

Examples

Analysis for X player:

context = agent.prepare_analysis_context(state, "X")
# Returns: {
#     'board_string': '...',
#     'player_symbol': 'X',
#     'opponent_symbol': 'O'
# }

prepare_move_context(state)[source]¶

Prepare structured context for LLM move generation.

Creates a comprehensive context dictionary containing the current board state, legal moves, and previous analysis to enable informed decision-making by the LLM engine.

Parameters:

state (TicTacToeState) – Current game state with board and history.

Returns:

Context dictionary with board representation,: legal moves, current player, and analysis history.

Return type:

dict[str, Any]

Examples

Context for opening move:

context = agent.prepare_move_context(initial_state)
# Returns: {
#     'board_string': '   0 1 2\n  -------\n0 | | | |...',
#     'current_player': 'X',
#     'legal_moves': '(0, 0), (0, 1), (0, 2), ...',
#     'player_analysis': 'No previous analysis available.'
# }

Mid-game context:

context = agent.prepare_move_context(mid_game_state)
# Includes previous analysis if available

run_game(visualize=True, debug=False)[source]¶

Execute a complete Tic Tac Toe game from start to finish.

Runs the game workflow, optionally displaying board states and debug information. Returns the final game state with winner information.

Parameters:

visualize (bool) – Whether to display board after each move. Overrides config.visualize if provided.
debug (bool) – Whether to enable debug logging for troubleshooting.

Returns:

Final game state with winner and complete history.

Return type:

TicTacToeState

Examples

Standard game:

final_state = agent.run_game()
print(f"Winner: {final_state.winner}")

Fast execution without visualization:

result = agent.run_game(visualize=False)
# Runs at maximum speed

Debug mode:

result = agent.run_game(debug=True)
# Shows detailed execution logs

Tournament execution:

config = TicTacToeConfig.competitive_config()
agent = TicTacToeAgent(config)
result = agent.run_game(visualize=False, debug=False)
# Optimized for performance

setup_workflow()[source]¶

Configure the LangGraph workflow for game execution.

Creates the state graph with nodes for initialization, move generation, and position analysis. Sets up edges to define game flow based on configuration settings.

Workflow structure: - initialize -> make_move: Start game and make first move - make_move -> analyze: Analyze if enabled - make_move -> make_move: Continue play without analysis - analyze -> make_move: Return to play after analysis - Any -> END: When game is complete

Examples

Standard workflow:

agent.setup_workflow()
# Creates graph with all nodes

Analysis disabled:

agent.config.enable_analysis = False
agent.setup_workflow()
# Skips analyze node in practice

visualize_state(state)[source]¶

Visualize the current game state for interactive gameplay.

Displays a formatted representation of the board, game status, current turn, and recent moves. Only shows visualization if enabled in config.

Parameters:: state (TicTacToeState) – Game state to visualize.
Return type:: None

Examples

Standard visualization:

agent.visualize_state(state)
# Prints:
# ==================================================
# 🎮 Game Status: ongoing
# Current Turn: X (player1)
# ==================================================
#    0 1 2
#   -------
# 0 |X| | |
#   -------
# 1 | |O| |
#   -------
# 2 | | | |
#   -------
#
# 📝 Last Move: X places at (0, 0) - top-left corner

Game over visualization:

agent.visualize_state(final_state)
# Shows final board with winner