haive.games.base.models

Base models for game agents.

This module provides the foundational data models used across game agents. It includes models for game state, player state, moves, and other common game-related data structures.

Examples

>>> board = Board(size=(8, 8))
>>> player = Player(id="p1", name="Player 1")
>>> state = GameState(board=board, players=[player])

Typical usage:

• Use these models as base classes for game-specific models

• Inherit from these models to add game-specific functionality

Classes

Board	Represents a generic game board.
Cell	Represents a cell on the board.
GameState	Represents the state of a generic game.
MoveModel	Generic model for game moves.
Piece	Represents a piece on the board.
Player	Represents a player in the game.

Module Contents

class haive.games.base.models.Board(/, **data)

Bases: pydantic.BaseModel

Represents a generic game board.

This class provides a basic representation of a game board with dimensions and optional grid-based structure.

Parameters:

data (Any)

size

The dimensions of the board (width, height).

Type:

Tuple[int, int]

grid

Optional grid representation.

Type:

Optional[List[List[str]]]

Examples

>>> board = Board(size=(8, 8))
>>> chess_board = Board(size=(8, 8), grid=[["R", "N", "B", ...]])

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.base.models.Cell(/, **data)

Bases: pydantic.BaseModel

Represents a cell on the board.

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.

Parameters:

data (Any)

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

Bases: pydantic.BaseModel

Represents the state of a generic game.

Core game state model that can be extended for specific games.

Parameters:

data (Any)

board

The game board.

Type:

Board

players

List of players in the game.

Type:

List[Player]

current_player

The player whose turn it is.

Type:

Player

game_status

Current game status.

Type:

Literal[“ongoing”, “ended”]

game_result

Final result when game ends.

Type:

Optional[str]

Examples

>>> state = GameState(
...     board=Board(size=(8, 8)),
...     players=[Player(id="p1", name="Player 1")],
...     current_player=player,
...     game_status="ongoing"
... )

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.base.models.MoveModel(/, **data)

Bases: pydantic.BaseModel, Generic[TMove], abc.ABC

Generic model for game moves.

This class represents a move in the game, generic over the specific type of move (TMove) used in the game.

Parameters:

data (Any)

move

The actual move data.

Type:

TMove

player_id

ID of the player making the move.

Type:

str

timestamp

When the move was made.

Type:

float

Examples

>>> class ChessMove(BaseModel):
...     from_pos: str
...     to_pos: str
>>> move = MoveModel[ChessMove](
...     move=ChessMove(from_pos="e2", to_pos="e4"),
...     player_id="p1"
... )

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 validate_move(move, info)

Override in game-specific models to validate the move.

Return type:

Any

class haive.games.base.models.Piece(/, **data)

Bases: pydantic.BaseModel

Represents a piece on the board.

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.

Parameters:

data (Any)

class haive.games.base.models.Player(/, **data)

Bases: pydantic.BaseModel

Represents a player in the game.

Base player model with essential player information and state.

Parameters:

data (Any)

id

Unique identifier for the player.

Type:

str

name

Display name of the player.

Type:

str

score

Current score or points.

Type:

int

is_active

Whether the player is still active in the game.

Type:

bool

Examples

>>> player = Player(id="p1", name="Player 1", score=0)

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.