haive.games.single_player.base ============================== .. py:module:: haive.games.single_player.base .. autoapi-nested-parse:: Single-player game framework for LLM-powered games. This module provides a core framework for building single-player games where an LLM can act as the player, the assistant, or the game engine. The framework is designed to be flexible, extensible, and independent of any multiplayer game concepts. .. rubric:: Example >>> from haive.agents.single_player import SinglePlayerGameAgent >>> class WordleAgent(SinglePlayerGameAgent): ... def __init__(self, config): ... super().__init__(config) ... self.state_manager = WordleStateManager Typical usage: - Inherit from SinglePlayerGameState for game-specific state - Inherit from SinglePlayerStateManager for game logic - Inherit from SinglePlayerGameConfig for configuration - Inherit from SinglePlayerGameAgent for the agent implementation Classes ------- .. autoapisummary:: haive.games.single_player.base.GameDifficulty haive.games.single_player.base.GameMode haive.games.single_player.base.GameSourceType haive.games.single_player.base.PlayerType haive.games.single_player.base.SinglePlayerGameAgent haive.games.single_player.base.SinglePlayerGameConfig haive.games.single_player.base.SinglePlayerGameState haive.games.single_player.base.SinglePlayerStateManager Module Contents --------------- .. py:class:: GameDifficulty Bases: :py:obj:`str`, :py:obj:`enum.Enum` Difficulty level for a game. Initialize self. See help(type(self)) for accurate signature. .. py:class:: GameMode Bases: :py:obj:`str`, :py:obj:`enum.Enum` Mode of operation for the game. Initialize self. See help(type(self)) for accurate signature. .. py:class:: GameSourceType Bases: :py:obj:`str`, :py:obj:`enum.Enum` Source of the game content. Initialize self. See help(type(self)) for accurate signature. .. py:class:: PlayerType Bases: :py:obj:`str`, :py:obj:`enum.Enum` Type of player in a single-player game. Initialize self. See help(type(self)) for accurate signature. .. py:class:: SinglePlayerGameAgent(config) Base agent for single-player games. This class provides the core functionality for single-player game agents, including state initialization, move handling, analysis, and visualization. .. attribute:: config Configuration for the game agent .. attribute:: state_manager Manager for game state transitions .. attribute:: engines Dictionary of LLM engines for move generation and analysis .. attribute:: graph State graph for game flow .. attribute:: app Compiled graph application Initialize the game agent. :param config: Configuration for the game agent .. py:method:: analyze_position(state) Analyze the current game state. :param state: Current game state :returns: Command with the updated game state including analysis .. py:method:: extract_move(response) :abstractmethod: Extract move from engine response. :param response: Response from the engine :returns: Extracted move .. py:method:: get_hint(state) Get a hint for the current game state. :param state: Current game state :returns: Command with the updated game state including a hint .. py:method:: initialize_game(state) Initialize a new game. :param state: Initial state (usually empty) :returns: Command with the initialized game state .. py:method:: interactive_command(state, command) Process an interactive command. :param state: Current game state :param command: Command string :returns: Command with the updated game state .. py:method:: make_player_move(state) Make a move for the player. In auto mode, this uses the LLM to generate a move. In interactive mode, this just returns the state unchanged. :param state: Current game state :returns: Command with the updated game state .. py:method:: prepare_analysis_context(state) :abstractmethod: Prepare context for analysis. :param state: Current game state :returns: Context dictionary for the analysis engine .. py:method:: prepare_move_context(state) :abstractmethod: Prepare context for move generation. :param state: Current game state :returns: Context dictionary for the move engine .. py:method:: save_state_history() Save the current agent state to a JSON file. .. py:method:: setup_workflow() Setup the workflow for the game. The workflow depends on the game mode: - Auto: Initialize -> Analyze -> Move -> Check -> Repeat - Interactive: Initialize -> Listen for commands - Assist: Initialize -> Analyze -> Listen for commands .. py:method:: should_continue_game(state) Check if the game should continue. :param state: Current game state :returns: True if the game should continue, False otherwise .. py:method:: visualize_state(state) :abstractmethod: Visualize the current game state. :param state: Current game state .. py:class:: SinglePlayerGameConfig(/, **data) Bases: :py:obj:`pydantic.BaseModel` Configuration for single-player games. This class defines the core configuration parameters that all single-player games need, including player type, game mode, and difficulty. .. attribute:: state_schema The state schema class for the game .. attribute:: player_type Type of player (human, LLM, hybrid) .. attribute:: game_mode Mode of operation (interactive, auto, assist) .. attribute:: difficulty Difficulty level of the game .. attribute:: max_hints Maximum number of hints allowed .. attribute:: auto_analyze Whether to automatically analyze after each move .. attribute:: engines Configurations for game LLMs Create a new model by parsing and validating input data from keyword arguments. Raises [`ValidationError`][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model. `self` is explicitly positional-only to allow `self` as a field name. .. py:class:: SinglePlayerGameState(/, **data) Bases: :py:obj:`pydantic.BaseModel` Base state for single-player games. This class defines the core state attributes that all single-player games need to track, including game status, move history, and analysis. .. attribute:: player_type Type of player (human, LLM, hybrid) :type: PlayerType .. attribute:: move_count Number of moves made :type: int .. attribute:: hint_count Number of hints used :type: int .. attribute:: difficulty Difficulty level of the game :type: GameDifficulty .. attribute:: game_status Status of the game (ongoing, victory, defeat) :type: str .. attribute:: move_history History of moves made :type: List[Dict] .. attribute:: analysis_history History of analyses made :type: List[Dict] .. attribute:: error_message Error message if any :type: Optional[str] Create a new model by parsing and validating input data from keyword arguments. Raises [`ValidationError`][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model. `self` is explicitly positional-only to allow `self` as a field name. .. py:method:: increment_move_count() Increment the move count. .. py:method:: is_defeat() Check if the game was lost. .. py:method:: is_game_over() Check if the game is over. .. py:method:: is_victory() Check if the game was won. .. py:method:: use_hint() Use a hint. .. py:class:: SinglePlayerStateManager Bases: :py:obj:`Generic`\ [\ :py:obj:`T`\ ] Base state manager for single-player games. This class provides the interface for managing game state transitions and operations. Each game should extend this with game-specific logic by implementing the required methods. Type Parameters: T: The type of the game state, must be a Pydantic BaseModel. .. method:: initialize Initialize a new game state .. method:: apply_move Apply a move to the game state .. method:: generate_hint Generate a hint for the current game state .. method:: check_game_status Check and update the game status .. method:: interactive_input Process interactive input from the player .. py:method:: apply_move(state, move) :classmethod: :abstractmethod: Apply a move to the game state. :param state: Current game state :param move: Move to apply :returns: Updated game state .. py:method:: check_game_status(state) :classmethod: :abstractmethod: Check and update the game status. :param state: Current game state :returns: Updated game state with status checked .. py:method:: generate_hint(state) :classmethod: Generate a hint for the current game state. :param state: Current game state :returns: Tuple of (updated state, hint text) .. py:method:: get_legal_moves(state) :classmethod: :abstractmethod: Get all legal moves for the current state. :param state: Current game state :returns: List of legal moves .. py:method:: initialize(difficulty = GameDifficulty.MEDIUM, player_type = PlayerType.LLM, **kwargs) :classmethod: :abstractmethod: Initialize a new game state. :param difficulty: Difficulty level of the game :param player_type: Type of player :param \*\*kwargs: Additional game-specific initialization parameters :returns: A new game state .. py:method:: interactive_input(state, user_input) :classmethod: Process interactive input from the player. This method handles general commands like 'hint', 'quit', etc. Game-specific commands should be handled by overriding this method. :param state: Current game state :param user_input: User input string :returns: Updated game state