haive.games.chess.models
========================

.. py:module:: haive.games.chess.models

.. autoapi-nested-parse::

   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
-------

.. autoapisummary::

   haive.games.chess.models.ChessAnalysis
   haive.games.chess.models.ChessMoveModel
   haive.games.chess.models.ChessMoveValidation
   haive.games.chess.models.ChessPlayerDecision
   haive.games.chess.models.SegmentedAnalysis


Module Contents
---------------

.. py:class:: ChessAnalysis(/, **data)

   Bases: :py:obj:`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

   .. attribute:: material_eval

      Material evaluation in pawns

      :type: float

   .. attribute:: position_eval

      Qualitative position assessment

      :type: str

   .. attribute:: tactics

      List of tactical opportunities

      :type: List[str]

   .. attribute:: strategy

      Long-term strategic plan

      :type: str

   .. attribute:: 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.


.. py:class:: ChessMoveModel(/, **data)

   Bases: :py:obj:`pydantic.BaseModel`


   Model for chess moves with validation.

   This class represents a chess move with:
       - UCI notation (e.g., "e2e4")
       - Optional explanation
       - Move validation

   .. attribute:: move

      Move in UCI notation

      :type: str

   .. attribute:: 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.


   .. py:method:: from_move(move, explanation = None)
      :classmethod:


      Create from a chess.Move object.



   .. py:method:: to_move()

      Convert to a chess.Move object.



   .. py:method:: validate_move(v)
      :classmethod:


      Validate the move format.

      :param v: The move string to validate

      :returns: The validated move string

      :raises ValueError: If move is not a string or too short



.. py:class:: ChessMoveValidation(/, **data)

   Bases: :py:obj:`pydantic.BaseModel`


   Model for chess move validation results.

   This class represents the validation of a chess move:
       - Move legality
       - Error messages
       - Resulting position

   .. attribute:: is_valid

      Whether the move is legal

      :type: bool

   .. attribute:: error_message

      Error message if move is invalid

      :type: Optional[str]

   .. attribute:: 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.


.. py:class:: ChessPlayerDecision(/, **data)

   Bases: :py:obj:`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

   .. attribute:: selected_move

      Chosen move with explanation

      :type: ChessMoveModel

   .. attribute:: position_eval

      Player's assessment of the position

      :type: str

   .. attribute:: alternatives

      Alternative moves considered

      :type: List[ChessMoveModel]

   .. attribute:: 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.


.. py:class:: SegmentedAnalysis(/, **data)

   Bases: :py:obj:`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

   .. attribute:: position_score

      The score evaluation of the position

      :type: float

   .. attribute:: attacking_chances

      Likelihood of a successful attack

      :type: str

   .. attribute:: suggested_plans

      Recommended next plans

      :type: List[str]

   .. attribute:: 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.