games.go.state¶

Go game state management.

This module provides state tracking and management for Go games, including:

  • Game state representation

  • Move validation and application

  • Board state tracking in SGF format

  • Capture counting

  • Game status management

Example

>>> from haive.games.go.state import GoGameState, GoGameStateManager
>>>
>>> # Initialize a new game
>>> state = GoGameStateManager.initialize(board_size=19)
>>>
>>> # Apply moves
>>> state = GoGameStateManager.apply_move(state, (3, 4))  # Black's move
>>> state = GoGameStateManager.apply_move(state, (15, 15))  # White's move
>>>
>>> # Check game status
>>> print(state.game_status)  # 'ongoing'
>>> print(state.captured_stones)  # {'black': 0, 'white': 0}

Classes¶

GoGameState

A model representing the complete state of a Go game.

Module Contents¶

class games.go.state.GoGameState(/, **data)¶

Bases: pydantic.BaseModel

A model representing the complete state of a Go game.

This class tracks all aspects of a Go game’s state, including:

  • Board configuration and size

  • Move history

  • Captured stones

  • Game status and result

  • Error conditions

Parameters:

data (Any)

board_size¶

Size of the Go board (default: 19x19).

Type:

int

board_sgf¶

Current board state in SGF format.

Type:

str

move_history¶

List of played moves as (color, row, col) tuples.

Type:

List[Tuple[str, int, int]]

captured_stones¶

Count of stones captured by each player.

Type:

Dict[str, int]

turn¶

Current player to move (“black” or “white”).

Type:

str

game_status¶

Current game status (ongoing/ended/resignation/timeout).

Type:

str

passes¶

Count of consecutive pass moves.

Type:

int

error_message¶

Error message if any.

Type:

Optional[str]

game_result¶

Final game result if game is ended.

Type:

Optional[str]

Example

>>> state = GoGameState(
...     board_sgf=sente.sgf.dumps(sente.Game(19)),
...     turn="black",
...     captured_stones={"black": 0, "white": 0}
... )
>>> state.validate_turn("black", {"board_sgf": state.board_sgf})
'black'

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_turn(v, info)¶

Validate that the turn matches the board state.

This validator ensures the turn field matches the actual board state by checking against the SGF representation.

Parameters:

  • v (str) – The turn value to validate.

  • info (ValidationInfo) – Validation context with other field values.

Returns:

The validated turn value.

Return type:

str

Raises:

ValueError – If turn doesn’t match the board state.