haive.games.core.agent.player_agent
===================================

.. py:module:: haive.games.core.agent.player_agent

.. autoapi-nested-parse::

   Configurable player agent system for games.

   This module provides a flexible player agent abstraction that allows games to use
   different LLM configurations for players without hardcoding them in engines.

   The system supports:
   - Dynamic LLM configuration per player
   - Role-based agent configuration (player, analyzer, etc.)
   - Easy swapping of LLMs and models
   - Integration with the new LLM factory system



Classes
-------

.. autoapisummary::

   haive.games.core.agent.player_agent.ConfigurableGameAgent
   haive.games.core.agent.player_agent.GamePlayerRole
   haive.games.core.agent.player_agent.PlayerAgentConfig
   haive.games.core.agent.player_agent.PlayerAgentFactory
   haive.games.core.agent.player_agent.PlayerRole


Functions
---------

.. autoapisummary::

   haive.games.core.agent.player_agent.create_llm_config
   haive.games.core.agent.player_agent.create_player_config
   haive.games.core.agent.player_agent.create_simple_player_configs


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

.. py:class:: ConfigurableGameAgent

   Bases: :py:obj:`abc.ABC`


   Abstract base for game agents with configurable players.

   This class provides the interface for game agents that support configurable player
   agents instead of hardcoded engines.



   .. py:method:: create_engines_from_player_configs(player_configs)
      :abstractmethod:


      Create engines from player configurations.

      :param player_configs: Dictionary of role name to player agent config

      :returns: Dictionary of engines
      :rtype: Dict[str, AugLLMConfig]



   .. py:method:: get_role_definitions()
      :abstractmethod:


      Get the role definitions for this game.

      :returns: Dictionary of role name to role definition
      :rtype: Dict[str, GamePlayerRole]



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

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


   Standard implementation of a player role in a game.

   This class defines a specific role that a player can take in a game, such as
   'white_player', 'black_analyzer', etc.


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

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


   Configuration for a player agent.

   This allows specifying which LLM configuration to use for a player without
   hardcoding it in the engine definitions.


   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:: create_llm_config()

      Create an LLMConfig instance from the configuration.

      :returns: Configured LLM instance
      :rtype: LLMConfig



.. py:class:: PlayerAgentFactory

   Factory for creating configurable player agents.

   This factory creates AugLLMConfig instances for game roles using configurable player
   agents instead of hardcoded LLM configurations.



   .. py:method:: create_engines_from_player_configs(roles, player_configs)
      :staticmethod:


      Create a complete set of engines from role definitions and player configs.

      :param roles: Dictionary of role name to role definition
      :param player_configs: Dictionary of role name to player agent config

      :returns: Dictionary of engines
      :rtype: Dict[str, AugLLMConfig]

      .. rubric:: Examples

      >>> roles = {
      ...     "white_player": GamePlayerRole(
      ...         role_name="white_player",
      ...         prompt_template=white_move_prompt,
      ...         structured_output_model=ChessPlayerDecision
      ...     )
      ... }
      >>> configs = {
      ...     "white_player": PlayerAgentConfig(llm_config="gpt-4")
      ... }
      >>> engines = PlayerAgentFactory.create_engines_from_player_configs(roles, configs)



   .. py:method:: create_player_engine(role, agent_config, **kwargs)
      :staticmethod:


      Create an AugLLMConfig for a player role.

      :param role: The game role definition
      :param agent_config: The player agent configuration
      :param \*\*kwargs: Additional parameters for AugLLMConfig

      :returns: Configured engine for the role
      :rtype: AugLLMConfig



.. py:class:: PlayerRole

   Bases: :py:obj:`Protocol`


   Protocol defining the interface for player roles.


   .. py:method:: get_prompt_template()

      Get the prompt template for this role.



   .. py:method:: get_role_name()

      Get the name of this role.



   .. py:method:: get_structured_output_model()

      Get the structured output model for this role.



.. py:function:: create_llm_config(model, **kwargs)

   Create an LLM config based on model string.

   This is a simple helper to create configs until a proper factory is available.



.. py:function:: create_player_config(model, temperature = None, player_name = None, **kwargs)

   Create a player agent configuration.

   :param model: Model string, LLMConfig instance, or config dict
   :param temperature: Temperature setting
   :param player_name: Human-readable name for the player
   :param \*\*kwargs: Additional configuration parameters

   :returns: Configured player agent
   :rtype: PlayerAgentConfig

   .. rubric:: Examples

   >>> config = create_player_config("gpt-4", temperature=0.7)
   >>> config = create_player_config("anthropic:claude-3-opus")
   >>> config = create_player_config({"model": "gpt-4", "provider": "openai"})


.. py:function:: create_simple_player_configs(white_model = 'gpt-4', black_model = 'claude-3-opus', temperature = None, **kwargs)

   Create simple player configurations for two-player games.

   :param white_model: Model for white/first player
   :param black_model: Model for black/second player
   :param temperature: Temperature for both players
   :param \*\*kwargs: Additional configuration parameters

   :returns: Player configurations
   :rtype: Dict[str, PlayerAgentConfig]

   .. rubric:: Examples

   >>> configs = create_simple_player_configs("gpt-4", "claude-3-opus", temperature=0.7)
   >>> # Creates configs for white_player, black_player, white_analyzer, black_analyzer