haive.games.connect4.models
===========================

.. py:module:: haive.games.connect4.models

.. autoapi-nested-parse::

   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

   .. rubric:: Example

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



Classes
-------

.. autoapisummary::

   haive.games.connect4.models.Connect4Analysis
   haive.games.connect4.models.Connect4Move
   haive.games.connect4.models.Connect4PlayerDecision


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

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

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

   .. attribute:: position_score

      Position evaluation (-1.0 to 1.0).

      :type: float

   .. attribute:: center_control

      Center control rating (0-10).

      :type: int

   .. attribute:: threats

      Detected threats and opportunities.

      :type: Dict[str, List[int]]

   .. attribute:: suggested_columns

      Recommended columns to play.

      :type: List[int]

   .. attribute:: winning_chances

      Estimated winning chances (0-100).

      :type: int

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


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


      Validate the center control rating.

      :param v: Center control rating to validate.
      :type v: int

      :returns: Validated center control rating.
      :rtype: int

      :raises ValueError: If the rating is not between 0 and 10.



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


      Validate the winning chances percentage.

      :param v: Winning chances percentage to validate.
      :type v: int

      :returns: Validated winning chances percentage.
      :rtype: int

      :raises ValueError: If the percentage is not between 0 and 100.



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

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


   Model for Connect4 moves with validation.

   This class represents a Connect4 move with:
       - Column number (0-6)
       - Optional explanation
       - Move validation

   .. attribute:: column

      Column number (0-6).

      :type: int

   .. attribute:: explanation

      Explanation of the move's purpose.

      :type: Optional[str]

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


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


      Validate the column number.

      :param v: Column number to validate.
      :type v: int

      :returns: Validated column number.
      :rtype: int

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



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

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

   .. attribute:: move

      Chosen move with explanation.

      :type: Connect4Move

   .. attribute:: position_eval

      Player's assessment of the position.

      :type: str

   .. attribute:: alternatives

      Alternative moves considered.

      :type: List[Connect4Move]

   .. attribute:: reasoning

      Detailed reasoning for the move choice.

      :type: str

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