games.core.agent.generic_player_agent¶

Generic player agent system using Python generics.

This module provides a fully generic player agent system that works across all two-player games using Python’s typing.Generic system. It abstracts the common pattern of player1/player2 + analyzer1/analyzer2 found across all games.

The generic system supports: - Type-safe player identifiers (e.g., “white”/”black”, “red”/”yellow”, “X”/”O”) - Generic role definitions that work for any game - Automatic engine generation from player configurations - Template-based prompt generation - Full integration with the LLM factory system

Classes¶

`AmongUsPlayerIdentifiers`	Among Us-specific player identifiers.
`BattleshipPlayerIdentifiers`	Battleship-specific player identifiers.
`CheckersPlayerIdentifiers`	Checkers-specific player identifiers.
`ChessPlayerIdentifiers`	Chess-specific player identifiers.
`CluePlayerIdentifiers`	Clue-specific player identifiers.
`Connect4PlayerIdentifiers`	Connect4-specific player identifiers.
`DebatePlayerIdentifiers`	Debate-specific player identifiers.
`DominoesPlayerIdentifiers`	Dominoes-specific player identifiers.
`FoxAndGeesePlayerIdentifiers`	Fox and Geese-specific player identifiers.
`GamePlayerIdentifiers`	Generic container for two-player game identifiers.
`GenericGameEngineFactory`	Generic factory for creating game engines using player type generics.
`GenericGameRole`	Generic game role definition using player type generics.
`GenericPromptGenerator`	Abstract base class for generating game-specific prompts using generics.
`GoPlayerIdentifiers`	Go-specific player identifiers.
`HoldEmPlayerIdentifiers`	Hold'em-specific player identifiers.
`MafiaPlayerIdentifiers`	Mafia-specific player identifiers.
`MancalaPlayerIdentifiers`	Mancala-specific player identifiers.
`MastermindPlayerIdentifiers`	Mastermind-specific player identifiers.
`MonopolyPlayerIdentifiers`	Monopoly-specific player identifiers.
`NimPlayerIdentifiers`	Nim-specific player identifiers.
`PokerPlayerIdentifiers`	Poker-specific player identifiers.
`ReversiPlayerIdentifiers`	Reversi-specific player identifiers.
`RiskPlayerIdentifiers`	Risk-specific player identifiers.
`TicTacToePlayerIdentifiers`	Tic Tac Toe-specific player identifiers.

Functions¶

`create_engines_from_simple_configs`(factory, ...[, ...])	Create engines from simple model configurations using a factory.
`create_generic_game_config`(game_name, players, ...[, ...])	Create a generic game configuration for any two-player game.
`example_chess_usage`()	Example of how to use the generic system for chess.
`example_custom_game_usage`()	Example of creating a new game using the generic system.

Module Contents¶

class games.core.agent.generic_player_agent.AmongUsPlayerIdentifiers¶

Bases: GamePlayerIdentifiers[str, str]

Among Us-specific player identifiers.

class games.core.agent.generic_player_agent.BattleshipPlayerIdentifiers¶

Bases: GamePlayerIdentifiers[str, str]

Battleship-specific player identifiers.

class games.core.agent.generic_player_agent.CheckersPlayerIdentifiers¶

Bases: GamePlayerIdentifiers[str, str]

Checkers-specific player identifiers.

class games.core.agent.generic_player_agent.ChessPlayerIdentifiers¶

Bases: GamePlayerIdentifiers[str, str]

Chess-specific player identifiers.

class games.core.agent.generic_player_agent.CluePlayerIdentifiers¶

Bases: GamePlayerIdentifiers[str, str]

Clue-specific player identifiers.

class games.core.agent.generic_player_agent.Connect4PlayerIdentifiers¶

Bases: GamePlayerIdentifiers[str, str]

Connect4-specific player identifiers.

class games.core.agent.generic_player_agent.DebatePlayerIdentifiers¶

Bases: GamePlayerIdentifiers[str, str]

Debate-specific player identifiers.

class games.core.agent.generic_player_agent.DominoesPlayerIdentifiers¶

Bases: GamePlayerIdentifiers[str, str]

Dominoes-specific player identifiers.

class games.core.agent.generic_player_agent.FoxAndGeesePlayerIdentifiers¶

Bases: GamePlayerIdentifiers[str, str]

Fox and Geese-specific player identifiers.

class games.core.agent.generic_player_agent.GamePlayerIdentifiers(/, **data)¶

Bases: pydantic.BaseModel, Generic[PlayerType, PlayerType2]

Generic container for two-player game identifiers.

This class defines the player identifiers for a two-player game using generics. It ensures type safety while allowing different naming conventions per game.

Examples

>>> chess_players = GamePlayerIdentifiers(player1="white", player2="black")
>>> checkers_players = GamePlayerIdentifiers(player1="red", player2="black")
>>> ttt_players = GamePlayerIdentifiers(player1="X", player2="O")
>>> connect4_players = GamePlayerIdentifiers(player1="red", player2="yellow")

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)

get_opponent(player)¶

Get the opponent of the given player.

Parameters:: player (PlayerType | PlayerType2)
Return type:: PlayerType | PlayerType2

get_players()¶

Get both player identifiers as a tuple.

Return type:: tuple[PlayerType, PlayerType2]

class games.core.agent.generic_player_agent.GenericGameEngineFactory(players, prompt_generator, default_temperature=0.7, analyzer_temperature=0.3)¶

Bases: Generic[PlayerType, PlayerType2]

Generic factory for creating game engines using player type generics.

This factory creates AugLLMConfig engines for any two-player game using the generic player agent system and type-safe player identifiers.

Init .

Parameters:

players (GamePlayerIdentifiers[PlayerType, PlayerType2]) – [TODO: Add description]
prompt_generator (GenericPromptGenerator[PlayerType, PlayerType2]) – [TODO: Add description]
default_temperature (float) – [TODO: Add description]
analyzer_temperature (float) – [TODO: Add description]

create_engines_from_player_configs(player_configs)¶

Create engines from player configurations using generics.

Parameters:: player_configs (dict[str, haive.games.core.agent.player_agent.PlayerAgentConfig]) – Dictionary of role name to player configuration
Returns:: Dictionary of configured engines
Return type:: Dict[str, AugLLMConfig]

Examples

>>> configs = {
...     "white_player": PlayerAgentConfig(llm_config="gpt-4"),
...     "black_player": PlayerAgentConfig(llm_config="claude-3-opus"),
...     "white_analyzer": PlayerAgentConfig(llm_config="gpt-4"),
...     "black_analyzer": PlayerAgentConfig(llm_config="claude-3-opus"),
... }
>>> engines = factory.create_engines_from_player_configs(configs)

create_engines_from_simple_configs(player1_model, player2_model, **kwargs)¶

Create engines from simple model configurations.

Parameters:

player1_model (str | haive.core.models.llm.LLMConfig) – Model for first player and analyzer
player2_model (str | haive.core.models.llm.LLMConfig) – Model for second player and analyzer
**kwargs – Additional configuration parameters

Returns:

Dictionary of engines

Return type:

Dict[str, AugLLMConfig]

create_role_definitions()¶

Create generic role definitions for the game.

Returns:: Dictionary of role definitions
Return type:: Dict[str, GenericGameRole]

class games.core.agent.generic_player_agent.GenericGameRole(/, **data)¶

Bases: pydantic.BaseModel, Generic[PlayerType]

Generic game role definition using player type generics.

This class defines a role in a game (like “white_player” or “red_analyzer”) using generic types for type safety and reusability across games.

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 games.core.agent.generic_player_agent.GenericPromptGenerator(players)¶

Bases: Generic[PlayerType, PlayerType2], abc.ABC

Abstract base class for generating game-specific prompts using generics.

This class provides the interface for generating move and analysis prompts for any two-player game using generic player types.

Init .

Parameters:: players (GamePlayerIdentifiers[PlayerType, PlayerType2]) – [TODO: Add description]

abstractmethod create_analysis_prompt(player)¶

Create a position analysis prompt for the specified player.

Parameters:: player (PlayerType | PlayerType2)
Return type:: langchain_core.prompts.ChatPromptTemplate

abstractmethod create_move_prompt(player)¶

Create a move generation prompt for the specified player.

Parameters:: player (PlayerType | PlayerType2)
Return type:: langchain_core.prompts.ChatPromptTemplate

abstractmethod get_analysis_output_model()¶

Get the structured output model for analysis.

Return type:: type

abstractmethod get_move_output_model()¶

Get the structured output model for moves.

Return type:: type

class games.core.agent.generic_player_agent.GoPlayerIdentifiers¶

Bases: GamePlayerIdentifiers[str, str]

Go-specific player identifiers.

class games.core.agent.generic_player_agent.HoldEmPlayerIdentifiers¶

Bases: GamePlayerIdentifiers[str, str]

Hold’em-specific player identifiers.

class games.core.agent.generic_player_agent.MafiaPlayerIdentifiers¶

Bases: GamePlayerIdentifiers[str, str]

Mafia-specific player identifiers.

class games.core.agent.generic_player_agent.MancalaPlayerIdentifiers¶

Bases: GamePlayerIdentifiers[str, str]

Mancala-specific player identifiers.

class games.core.agent.generic_player_agent.MastermindPlayerIdentifiers¶

Bases: GamePlayerIdentifiers[str, str]

Mastermind-specific player identifiers.

class games.core.agent.generic_player_agent.MonopolyPlayerIdentifiers¶

Bases: GamePlayerIdentifiers[str, str]

Monopoly-specific player identifiers.

class games.core.agent.generic_player_agent.NimPlayerIdentifiers¶

Bases: GamePlayerIdentifiers[str, str]

Nim-specific player identifiers.

class games.core.agent.generic_player_agent.PokerPlayerIdentifiers¶

Bases: GamePlayerIdentifiers[str, str]

Poker-specific player identifiers.

class games.core.agent.generic_player_agent.ReversiPlayerIdentifiers¶

Bases: GamePlayerIdentifiers[str, str]

Reversi-specific player identifiers.

class games.core.agent.generic_player_agent.RiskPlayerIdentifiers¶

Bases: GamePlayerIdentifiers[str, str]

Risk-specific player identifiers.

class games.core.agent.generic_player_agent.TicTacToePlayerIdentifiers¶

Bases: GamePlayerIdentifiers[str, str]

Tic Tac Toe-specific player identifiers.

games.core.agent.generic_player_agent.create_engines_from_simple_configs(factory, player1_model, player2_model, temperature=0.3)¶

Create engines from simple model configurations using a factory.

Parameters:

factory (GenericGameEngineFactory) – The game engine factory instance
player1_model (str | haive.core.models.llm.LLMConfig) – Model for first player and analyzer
player2_model (str | haive.core.models.llm.LLMConfig) – Model for second player and analyzer
temperature (float) – Generation temperature

Returns:

Dictionary of engines

Return type:

Dict[str, AugLLMConfig]

games.core.agent.generic_player_agent.create_generic_game_config(game_name, players, prompt_generator, player1_model='gpt-4o', player2_model='claude-3-5-sonnet-20240620', **kwargs)¶

Create a generic game configuration for any two-player game.

Parameters:

game_name (str) – Name of the game
players (GamePlayerIdentifiers) – Player identifiers for the game
prompt_generator (GenericPromptGenerator) – Prompt generator for the game
player1_model (str | haive.core.models.llm.LLMConfig) – Model for first player
player2_model (str | haive.core.models.llm.LLMConfig) – Model for second player
**kwargs – Additional configuration parameters

Returns:

Dictionary of engines

Return type:

Dict[str, AugLLMConfig]

Examples

>>> chess_players = ChessPlayerIdentifiers()
>>> chess_prompt_gen = ChessPromptGenerator(chess_players)
>>> engines = create_generic_game_config(
...     "chess", chess_players, chess_prompt_gen, "gpt-4", "claude-3-opus"
... )

games.core.agent.generic_player_agent.example_chess_usage()¶: Example of how to use the generic system for chess.

games.core.agent.generic_player_agent.example_custom_game_usage()¶: Example of creating a new game using the generic system.