haive.games.single_player.base¶

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.

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¶

`GameDifficulty`	Difficulty level for a game.
`GameMode`	Mode of operation for the game.
`GameSourceType`	Source of the game content.
`PlayerType`	Type of player in a single-player game.
`SinglePlayerGameAgent`	Base agent for single-player games.
`SinglePlayerGameConfig`	Configuration for single-player games.
`SinglePlayerGameState`	Base state for single-player games.
`SinglePlayerStateManager`	Base state manager for single-player games.

Module Contents¶

class haive.games.single_player.base.GameDifficulty[source]¶

Bases: str, enum.Enum

Difficulty level for a game.

Initialize self. See help(type(self)) for accurate signature.

class haive.games.single_player.base.GameMode[source]¶

Bases: str, enum.Enum

Mode of operation for the game.

Initialize self. See help(type(self)) for accurate signature.

class haive.games.single_player.base.GameSourceType[source]¶

Bases: str, enum.Enum

Source of the game content.

Initialize self. See help(type(self)) for accurate signature.

class haive.games.single_player.base.PlayerType[source]¶

Bases: str, enum.Enum

Type of player in a single-player game.

Initialize self. See help(type(self)) for accurate signature.

class haive.games.single_player.base.SinglePlayerGameAgent(config)[source]¶

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.

config¶: Configuration for the game agent

state_manager¶: Manager for game state transitions

engines¶: Dictionary of LLM engines for move generation and analysis

graph¶: State graph for game flow

app¶: Compiled graph application

Initialize the game agent.

Parameters:: config – Configuration for the game agent

analyze_position(state)[source]¶

Analyze the current game state.

Parameters:: state (T) – Current game state
Returns:: Command with the updated game state including analysis
Return type:: langgraph.types.Command

abstractmethod extract_move(response)[source]¶

Extract move from engine response.

Parameters:: response (Any) – Response from the engine
Returns:: Extracted move
Return type:: Any

get_hint(state)[source]¶

Get a hint for the current game state.

Parameters:: state (T) – Current game state
Returns:: Command with the updated game state including a hint
Return type:: langgraph.types.Command

initialize_game(state)[source]¶

Initialize a new game.

Parameters:: state (dict[str, Any]) – Initial state (usually empty)
Returns:: Command with the initialized game state
Return type:: langgraph.types.Command

interactive_command(state, command)[source]¶

Process an interactive command.

Parameters:

state (T) – Current game state
command (str) – Command string

Returns:

Command with the updated game state

Return type:

langgraph.types.Command

make_player_move(state)[source]¶

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.

Parameters:: state (T) – Current game state
Returns:: Command with the updated game state
Return type:: langgraph.types.Command

abstractmethod prepare_analysis_context(state)[source]¶

Prepare context for analysis.

Parameters:: state (T) – Current game state
Returns:: Context dictionary for the analysis engine
Return type:: dict[str, Any]

abstractmethod prepare_move_context(state)[source]¶

Prepare context for move generation.

Parameters:: state (T) – Current game state
Returns:: Context dictionary for the move engine
Return type:: dict[str, Any]

save_state_history()[source]¶

Save the current agent state to a JSON file.

Return type:: None

setup_workflow()[source]¶

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

should_continue_game(state)[source]¶

Check if the game should continue.

Parameters:: state (T) – Current game state
Returns:: True if the game should continue, False otherwise
Return type:: bool

abstractmethod visualize_state(state)[source]¶

Visualize the current game state.

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

class haive.games.single_player.base.SinglePlayerGameConfig(/, **data)[source]¶

Bases: 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.

Parameters:: data (Any)

state_schema¶: The state schema class for the game

player_type¶: Type of player (human, LLM, hybrid)

game_mode¶: Mode of operation (interactive, auto, assist)

difficulty¶: Difficulty level of the game

max_hints¶: Maximum number of hints allowed

auto_analyze¶: Whether to automatically analyze after each move

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.

class haive.games.single_player.base.SinglePlayerGameState(/, **data)[source]¶

Bases: 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.

Parameters:: data (Any)

player_type¶

Type of player (human, LLM, hybrid)

Type:: PlayerType

move_count¶

Number of moves made

Type:: int

hint_count¶

Number of hints used

Type:: int

difficulty¶

Difficulty level of the game

Type:: GameDifficulty

game_status¶

Status of the game (ongoing, victory, defeat)

Type:: str

move_history¶

History of moves made

Type:: List[Dict]

analysis_history¶

History of analyses made

Type:: List[Dict]

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.

increment_move_count()[source]¶

Increment the move count.

Return type:: None

is_defeat()[source]¶

Check if the game was lost.

Return type:: bool

is_game_over()[source]¶

Check if the game is over.

Return type:: bool

is_victory()[source]¶

Check if the game was won.

Return type:: bool

use_hint()[source]¶

Use a hint.

Return type:: None

class haive.games.single_player.base.SinglePlayerStateManager[source]¶

Bases: Generic[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.

initialize()[source]¶

Initialize a new game state

Parameters:

difficulty (GameDifficulty)
player_type (PlayerType)

Return type:

apply_move()[source]¶

Apply a move to the game state

Parameters:

state (T)
move (Any)

Return type:

generate_hint()[source]¶

Generate a hint for the current game state

Parameters:: state (T)
Return type:: tuple[T, str]

check_game_status()[source]¶

Check and update the game status

Parameters:: state (T)
Return type:: T

interactive_input()[source]¶

Process interactive input from the player

Parameters:

state (T)
user_input (str)

Return type:

classmethod apply_move(state, move)[source]¶

Abstractmethod:

Parameters:

state (T)
move (Any)

Return type:

Apply a move to the game state.

Parameters:

state (T) – Current game state
move (Any) – Move to apply

Returns:

Updated game state

Return type:

classmethod check_game_status(state)[source]¶

Abstractmethod:
Parameters:: state (T)
Return type:: T

Check and update the game status.

Parameters:: state (T) – Current game state
Returns:: Updated game state with status checked
Return type:: T

classmethod generate_hint(state)[source]¶

Generate a hint for the current game state.

Parameters:: state (T) – Current game state
Returns:: Tuple of (updated state, hint text)
Return type:: tuple[T, str]

classmethod get_legal_moves(state)[source]¶

Abstractmethod:
Parameters:: state (T)
Return type:: list[Any]

Get all legal moves for the current state.

Parameters:: state (T) – Current game state
Returns:: List of legal moves
Return type:: list[Any]

classmethod initialize(difficulty=GameDifficulty.MEDIUM, player_type=PlayerType.LLM, **kwargs)[source]¶

Abstractmethod:

Parameters:

difficulty (GameDifficulty)
player_type (PlayerType)

Return type:

Initialize a new game state.

Parameters:

difficulty (GameDifficulty) – Difficulty level of the game
player_type (PlayerType) – Type of player
**kwargs – Additional game-specific initialization parameters

Returns:

A new game state

Return type:

classmethod interactive_input(state, user_input)[source]¶

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.

Parameters:

state (T) – Current game state
user_input (str) – User input string

Returns:

Updated game state

Return type: