haive.games.chess.models

Chess game models module.

This module provides data models for the chess game, including:

  • Move representation

  • Player decisions

  • Position analysis

  • Structured output models for LLMs

Classes

ChessAnalysis

Model for chess position analysis.

ChessMoveModel

Model for chess moves with validation.

ChessMoveValidation

Model for chess move validation results.

ChessPlayerDecision

Model for chess player decisions.

SegmentedAnalysis

Structured analysis of a chess position in segments.

Module Contents

class haive.games.chess.models.ChessAnalysis(/, **data)

Bases: pydantic.BaseModel

Model for chess position analysis.

This class represents a detailed analysis of a chess position:

  • Material evaluation

  • Positional assessment

  • Tactical opportunities

  • Strategic plans

Parameters:

data (Any)

material_eval

Material evaluation in pawns

Type:

float

position_eval

Qualitative position assessment

Type:

str

tactics

List of tactical opportunities

Type:

List[str]

strategy

Long-term strategic plan

Type:

str

best_moves

Suggested best moves

Type:

List[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.

class haive.games.chess.models.ChessMoveModel(/, **data)

Bases: pydantic.BaseModel

Model for chess moves with validation.

This class represents a chess move with:

  • UCI notation (e.g., “e2e4”)

  • Optional explanation

  • Move validation

Parameters:

data (Any)

move

Move in UCI notation

Type:

str

explanation

Explanation of the move’s purpose

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 from_move(move, explanation=None)

Create from a chess.Move object.

Parameters:

  • move (chess.Move)

  • explanation (str | None)

Return type:

ChessMoveModel

to_move()

Convert to a chess.Move object.

Return type:

chess.Move

classmethod validate_move(v)

Validate the move format.

Parameters:

v (str) – The move string to validate

Returns:

The validated move string

Raises:

ValueError – If move is not a string or too short

Return type:

str

class haive.games.chess.models.ChessMoveValidation(/, **data)

Bases: pydantic.BaseModel

Model for chess move validation results.

This class represents the validation of a chess move:

  • Move legality

  • Error messages

  • Resulting position

Parameters:

data (Any)

is_valid

Whether the move is legal

Type:

bool

error_message

Error message if move is invalid

Type:

Optional[str]

resulting_fen

FEN of position after move

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.

class haive.games.chess.models.ChessPlayerDecision(/, **data)

Bases: pydantic.BaseModel

Model for chess player decisions.

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

  • Move selection

  • Position evaluation

  • Alternative moves considered

  • Reasoning process

Parameters:

data (Any)

selected_move

Chosen move with explanation

Type:

ChessMoveModel

position_eval

Player’s assessment of the position

Type:

str

alternatives

Alternative moves considered

Type:

List[ChessMoveModel]

reasoning

Detailed reasoning for the move choice

Type:

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.

class haive.games.chess.models.SegmentedAnalysis(/, **data)

Bases: pydantic.BaseModel

Structured analysis of a chess position in segments.

This class breaks down position analysis into distinct categories:

  • Numerical position score

  • Attacking chances

  • Defensive needs

  • Strategic plans

Parameters:

data (Any)

position_score

The score evaluation of the position

Type:

float

attacking_chances

Likelihood of a successful attack

Type:

str

suggested_plans

Recommended next plans

Type:

List[str]

defensive_needs

Defensive needs and counterplay ideas

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.