games.connect4.models¶

Connect4 game models module.

This module provides data models for the Connect4 game implementation, including:

  • Move validation and representation

  • Player decisions and analysis

  • Game state components

  • Structured output models for LLMs

Example

>>> from haive.games.connect4.models import Connect4Move
>>>
>>> # Create and validate a move
>>> move = Connect4Move(
...     column=3,
...     explanation="Control the center column"
... )

Classes¶

Connect4Analysis

Model for Connect4 position analysis.

Connect4Move

Model for Connect4 moves with validation.

Connect4PlayerDecision

Model for Connect4 player decisions.

Module Contents¶

class games.connect4.models.Connect4Analysis(/, **data)¶

Bases: pydantic.BaseModel

Model for Connect4 position analysis.

This class represents a detailed analysis of a Connect4 position:

  • Position evaluation

  • Center control assessment

  • Threat detection

  • Strategic plans

Parameters:

data (Any)

position_score¶

Position evaluation (-1.0 to 1.0).

Type:

float

center_control¶

Center control rating (0-10).

Type:

int

threats¶

Detected threats and opportunities.

Type:

Dict[str, List[int]]

suggested_columns¶

Recommended columns to play.

Type:

List[int]

winning_chances¶

Estimated winning chances (0-100).

Type:

int

Example

>>> analysis = Connect4Analysis(
...     position_score=0.5,
...     center_control=8,
...     threats={
...         "winning_moves": [3],
...         "blocking_moves": [4]
...     },
...     suggested_columns=[3, 2, 4],
...     winning_chances=75
... )

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_center_control(v)¶

Validate the center control rating.

Parameters:

v (int) – Center control rating to validate.

Returns:

Validated center control rating.

Return type:

int

Raises:

ValueError – If the rating is not between 0 and 10.

classmethod validate_winning_chances(v)¶

Validate the winning chances percentage.

Parameters:

v (int) – Winning chances percentage to validate.

Returns:

Validated winning chances percentage.

Return type:

int

Raises:

ValueError – If the percentage is not between 0 and 100.

class games.connect4.models.Connect4Move(/, **data)¶

Bases: pydantic.BaseModel

Model for Connect4 moves with validation.

This class represents a Connect4 move with:

  • Column number (0-6)

  • Optional explanation

  • Move validation

Parameters:

data (Any)

column¶

Column number (0-6).

Type:

int

explanation¶

Explanation of the move’s purpose.

Type:

Optional[str]

Example

>>> move = Connect4Move(
...     column=3,
...     explanation="Control the center column"
... )

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_column(v)¶

Validate the column number.

Parameters:

v (int) – Column number to validate.

Returns:

Validated column number.

Return type:

int

Raises:

ValueError – If the column number is not between 0 and 6.

class games.connect4.models.Connect4PlayerDecision(/, **data)¶

Bases: pydantic.BaseModel

Model for Connect4 player decisions.

This class represents a player’s decision-making process:

  • Move selection

  • Position evaluation

  • Alternative moves considered

  • Reasoning process

Parameters:

data (Any)

move¶

Chosen move with explanation.

Type:

Connect4Move

position_eval¶

Player’s assessment of the position.

Type:

str

alternatives¶

Alternative moves considered.

Type:

List[Connect4Move]

reasoning¶

Detailed reasoning for the move choice.

Type:

str

Example

>>> decision = Connect4PlayerDecision(
...     move=Connect4Move(column=3, explanation="Control center"),
...     position_eval="Strong position with center control",
...     alternatives=[
...         Connect4Move(column=2, explanation="Alternative center approach")
...     ],
...     reasoning="Playing in column 3 maintains center control"
... )

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.