haive.games.framework.base.state

Base state module for game agents.

This module provides the foundational state class for game agents, defining the core state attributes that all games need to track.

Examples

>>> # GameState is abstract - inherit from it:
>>> class ConcreteGameState(GameState):
...     @classmethod
...     def initialize(cls, **kwargs):
...         return cls(turn="player1", game_status="ongoing")

Typical usage:

• Inherit from GameState to create game-specific state classes

• Use as the state schema in game configurations

• Track game progress and history

Classes

GameState

Base game state that all game states should inherit from.

Module Contents

class haive.games.framework.base.state.GameState(/, **data)

Bases: pydantic.BaseModel, abc.ABC

Base game state that all game states should inherit from.

This class defines the core state attributes that all games need to track, including the current turn, game status, move history, and error handling.

Parameters:

data (Any)

players

List of players in the game.

Type:

List[str]

turn

Current player’s turn.

Type:

str

game_status

Status of the game (e.g., “ongoing”, “finished”).

Type:

str

move_history

History of moves made in the game.

Type:

List[Any]

error_message

Error message if any error occurred.

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.

classmethod initialize(**kwargs)

Abstractmethod:

Return type:

GameState

Abstract method that all subclasses must implement to initialize the game. state.

Returns:

A fully initialized game state object.

Return type:

GameState

Examples

>>> return Connect4State.initialize(first_player="red")