haive.games.core.agent.player_agent¶

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¶

`ConfigurableGameAgent`	Abstract base for game agents with configurable players.
`GamePlayerRole`	Standard implementation of a player role in a game.
`PlayerAgentConfig`	Configuration for a player agent.
`PlayerAgentFactory`	Factory for creating configurable player agents.
`PlayerRole`	Protocol defining the interface for player roles.

Functions¶

`create_llm_config`(model, **kwargs)	Create an LLM config based on model string.
`create_player_config`(model[, temperature, player_name])	Create a player agent configuration.
`create_simple_player_configs`([white_model, ...])	Create simple player configurations for two-player games.

Module Contents¶

class haive.games.core.agent.player_agent.ConfigurableGameAgent[source]¶

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

abstractmethod create_engines_from_player_configs(player_configs)[source]¶

Create engines from player configurations.

Parameters:: player_configs (dict[str, PlayerAgentConfig]) – Dictionary of role name to player agent config
Returns:: Dictionary of engines
Return type:: Dict[str, AugLLMConfig]

abstractmethod get_role_definitions()[source]¶

Get the role definitions for this game.

Returns:: Dictionary of role name to role definition
Return type:: Dict[str, GamePlayerRole]

class haive.games.core.agent.player_agent.GamePlayerRole(/, **data)[source]¶

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

Parameters:: data (Any)

class haive.games.core.agent.player_agent.PlayerAgentConfig(/, **data)[source]¶

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

Parameters:: data (Any)

create_llm_config()[source]¶

Create an LLMConfig instance from the configuration.

Returns:: Configured LLM instance
Return type:: LLMConfig

class haive.games.core.agent.player_agent.PlayerAgentFactory[source]¶

Factory for creating configurable player agents.

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

static create_engines_from_player_configs(roles, player_configs)[source]¶

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

Parameters:

roles (dict[str, GamePlayerRole]) – Dictionary of role name to role definition
player_configs (dict[str, PlayerAgentConfig]) – Dictionary of role name to player agent config

Returns:

Dictionary of engines

Return type:

Dict[str, AugLLMConfig]

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)

static create_player_engine(role, agent_config, **kwargs)[source]¶

Create an AugLLMConfig for a player role.

Parameters:

role (GamePlayerRole) – The game role definition
agent_config (PlayerAgentConfig) – The player agent configuration
**kwargs – Additional parameters for AugLLMConfig

Returns:

Configured engine for the role

Return type:

AugLLMConfig

class haive.games.core.agent.player_agent.PlayerRole[source]¶

Bases: Protocol

Protocol defining the interface for player roles.

get_prompt_template()[source]¶

Get the prompt template for this role.

Return type:: Any

get_role_name()[source]¶

Get the name of this role.

Return type:: str

get_structured_output_model()[source]¶

Get the structured output model for this role.

Return type:: type | None

haive.games.core.agent.player_agent.create_llm_config(model, **kwargs)[source]¶

Create an LLM config based on model string.

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

Parameters:: model (str)
Return type:: haive.core.models.llm.LLMConfig

haive.games.core.agent.player_agent.create_player_config(model, temperature=None, player_name=None, **kwargs)[source]¶

Create a player agent configuration.

Parameters:

model (str | haive.core.models.llm.LLMConfig) – Model string, LLMConfig instance, or config dict
temperature (float | None) – Temperature setting
player_name (str | None) – Human-readable name for the player
**kwargs – Additional configuration parameters

Returns:

Configured player agent

Return type:

PlayerAgentConfig

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"})

haive.games.core.agent.player_agent.create_simple_player_configs(white_model='gpt-4', black_model='claude-3-opus', temperature=None, **kwargs)[source]¶

Create simple player configurations for two-player games.

Parameters:

white_model (str | haive.core.models.llm.LLMConfig) – Model for white/first player
black_model (str | haive.core.models.llm.LLMConfig) – Model for black/second player
temperature (float | None) – Temperature for both players
**kwargs – Additional configuration parameters

Returns:

Player configurations

Return type:

Dict[str, PlayerAgentConfig]

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