haive.games.connect4.state

Connect4 game state module.

This module defines the core state representation for Connect4 games, including board representation, move tracking, and game status.

Example

>>> from haive.games.connect4.state import Connect4State
>>> from haive.games.connect4.models import Connect4Move
>>>
>>> # Initialize a new game
>>> state = Connect4State.initialize()
>>> state.board_string  # Get string representation
>>>
>>> # Check game properties
>>> state.is_column_full(3)  # Check if column is full
>>> state.get_next_row(3)    # Get next available row in column

Classes

Connect4State

State representation for a Connect4 game.

Module Contents

class haive.games.connect4.state.Connect4State(/, **data)

Bases: haive.games.framework.base.state.GameState

State representation for a Connect4 game.

This class represents the complete state of a Connect4 game, including:

• Board representation (6x7 grid)

• Current player’s turn

• Game status and winner

• Move history

• Position analysis for both players

The board is represented as a 6x7 grid of cells, where each cell can be:

• None: Empty cell

• “red”: Red player’s piece

• “yellow”: Yellow player’s piece

Parameters:

data (Any)

board

6x7 board representation (rows x columns)

Type:

list[list[str | None]]

turn

Current player’s turn

Type:

Literal[“red”, “yellow”]

game_status

Game status

Type:

Literal[“ongoing”, “red_win”, “yellow_win”, “draw”]

move_history

History of moves made in the game

Type:

list[Connect4Move]

red_analysis

Analysis history for the red player

Type:

list[dict]

yellow_analysis

Analysis history for the yellow player

Type:

list[dict]

winner

Winner of the game, if any

Type:

Optional[str]

error_message

Error message from the last operation

Type:

Optional[str]

Examples

>>> state = Connect4State.initialize()
>>> state.turn
'red'
>>> state.is_column_full(3)
False

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.

get_next_row(column)

Get the next available row in a column.

Returns the row index where a piece would land if dropped in the specified column, or None if the column is full.

Parameters:

column (int) – Column index (0-6)

Returns:

Row index for the next piece, or None if column is full

Return type:

Optional[int]

Example

>>> state = Connect4State.initialize()
>>> state.get_next_row(3)
5  # Bottom row (gravity effect)

classmethod initialize()

Initialize a new Connect4 game.

Creates a new Connect4 game state with an empty board, red player starting, and game status set to ongoing.

Returns:

A new game state

Return type:

Connect4State

Example

>>> state = Connect4State.initialize()
>>> state.turn
'red'
>>> state.game_status
'ongoing'

is_column_full(column)

Check if a column is full.

Parameters:

column (int) – Column index to check (0-6)

Returns:

True if the column is full, False otherwise

Return type:

bool

Example

>>> state = Connect4State.initialize()
>>> state.is_column_full(3)
False

classmethod validate_board_dimensions(board)

Validate board dimensions are 6x7.

Parameters:

board – Board to validate

Returns:

Validated board

Return type:

list[list[str | None]]

Raises:

ValueError – If board dimensions are invalid

property board_string: str

Get a string representation of the board.

Returns a formatted string representation of the current board state, with column and row indices, cell contents, and borders.

Returns:

String representation of the board

Return type:

str

Example

>>> state = Connect4State.initialize()
>>> # state.board_string displays:
  0 1 2 3 4 5 6
  -------------
0| | | | | | | |
1| | | | | | | |
2| | | | | | | |
3| | | | | | | |
4| | | | | | | |
5| | | | | | | |
  -------------
  0 1 2 3 4 5 6