haive.games.common.voting_system
================================

.. py:module:: haive.games.common.voting_system

.. autoapi-nested-parse::

   Generalized AI Voting System for Game Winner Determination.

   This module provides a reusable voting system that can evaluate game performance across
   different game types using AI judges with specialized perspectives.



Classes
-------

.. autoapisummary::

   haive.games.common.voting_system.AIGameJudge
   haive.games.common.voting_system.ChessEvaluator
   haive.games.common.voting_system.DebateEvaluator
   haive.games.common.voting_system.GameEvaluator
   haive.games.common.voting_system.GameVotingSystem
   haive.games.common.voting_system.JudgePersonality
   haive.games.common.voting_system.VoteChoice
   haive.games.common.voting_system.VotingResult


Functions
---------

.. autoapisummary::

   haive.games.common.voting_system.create_voting_system


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

.. py:class:: AIGameJudge(name, personality = JudgePersonality.BALANCED, expertise_area = None, focus_weight = 0.5)

   AI judge that can evaluate any game type.


   .. py:method:: evaluate(topic, options, game_data, criteria)
      :async:


      Evaluate the game and return a vote choice.



.. py:class:: ChessEvaluator

   Evaluator for chess games.


.. py:class:: DebateEvaluator

   Evaluator for debate games.


.. py:class:: GameEvaluator

   Bases: :py:obj:`Protocol`


   Protocol for game-specific evaluation logic.


   .. py:method:: format_game_data(game_data)

      Format game data for judge evaluation.



   .. py:method:: get_evaluation_context()

      Get context-specific information for judges.



   .. py:method:: get_evaluation_criteria()

      Get the criteria this game should be judged on.



.. py:class:: GameVotingSystem(judges)

   Generalized voting system for any game type.


   .. py:method:: create_game_specific_judges(game_type, num_judges = 3)
      :classmethod:


      Create judges specialized for a specific game type.

      :param game_type: Type of game to create judges for
      :param num_judges: Number of judges to create (default: 3)



   .. py:method:: create_standard_judges(num_judges = 3)
      :classmethod:


      Create standard judge panel with configurable size and randomized.
      personalities.

      :param num_judges: Number of judges to create (default: 3 to avoid ties)
                         Odd numbers recommended to prevent tie votes.



   .. py:method:: vote(topic, options, game_data, criteria, evaluator = None)
      :async:


      Conduct voting with all judges.



.. py:class:: JudgePersonality

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Different AI judge personalities for game evaluation.

   Initialize self.  See help(type(self)) for accurate signature.


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

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


   A judge's vote choice with reasoning.

   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:: VotingResult(/, **data)

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


   Complete voting results from multiple judges.

   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:function:: create_voting_system(game_type = 'general', num_judges = 3)

   Create appropriate voting system for game type.

   :param game_type: Type of game ("general", "chess", "debate", "poker", "go")
   :param num_judges: Number of judges (default: 3 to avoid ties)