haive.games.framework.base.factory
==================================

.. py:module:: haive.games.framework.base.factory

.. autoapi-nested-parse::

   Factory module for creating game agents.

   This module provides a factory class for creating game agents with standardized
   workflows and configurations. It simplifies the process of creating new game
   agents by providing a flexible, composable pattern.

   .. rubric:: Examples

   >>> # Create a new chess agent
   >>> chess_agent = GameAgentFactory.create_game_agent(
   ...     name="ChessAgent",
   ...     state_schema=ChessState,
   ...     state_manager=ChessStateManager,
   ...     enable_analysis=True
   ... )
   >>>
   >>> # Create a standard workflow
   >>> graph = StateGraph()
   >>> graph = GameAgentFactory.create_standard_workflow(graph)

   Typical usage:
       - Use create_game_agent to generate new game agent classes
       - Use create_standard_workflow to set up game workflows
       - Customize agents with analysis, custom nodes, and edges



Classes
-------

.. autoapisummary::

   haive.games.framework.base.factory.GameAgentFactory


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

.. py:class:: GameAgentFactory

   Factory for creating game agents using a flexible, composable pattern.

   This factory class provides methods for creating game agents and their
   workflows. It simplifies the process of creating new game agents by:
   1. Generating workflow nodes from a standardized template
   2. Using DynamicGraph for simplified graph building
   3. Supporting consistent extension patterns for analysis and custom workflows

   The factory supports:
   - Creation of game agent classes with standard methods
   - Configuration of analysis steps and custom nodes
   - Flexible workflow definition with conditional edges
   - Registration of agents with their configs

   .. rubric:: Examples

   >>> # Create a new chess agent
   >>> chess_agent = GameAgentFactory.create_game_agent(
   ...     name="ChessAgent",
   ...     state_schema=ChessState,
   ...     state_manager=ChessStateManager
   ... )
   >>>
   >>> # Create an instance with custom config
   >>> agent = chess_agent(ChessConfig())


   .. py:method:: create_game_agent(name, state_schema, state_manager, player1_name = 'player1', player2_name = 'player2', enable_analysis = True, aug_llm_configs = None, custom_nodes = None, custom_edges = None, conditional_edges = None)
      :staticmethod:


      Create a new game agent class with a complete workflow.

      This method generates a new game agent class with all necessary methods
      and workflow configuration. It creates both the agent class and its
      corresponding config class.

      :param name: Name of the agent class.
      :type name: str
      :param state_schema: The game state schema class.
      :type state_schema: Type[GameState]
      :param state_manager: The game state manager class.
      :type state_manager: Type[GameStateManager]
      :param player1_name: Name for player 1. Defaults to "player1".
      :type player1_name: str, optional
      :param player2_name: Name for player 2. Defaults to "player2".
      :type player2_name: str, optional
      :param enable_analysis: Whether to enable analysis steps. Defaults to True.
      :type enable_analysis: bool, optional
      :param aug_llm_configs: LLM configurations. Defaults to None.
      :type aug_llm_configs: Optional[Dict[str, AugLLMConfig]], optional
      :param custom_nodes: Custom node functions. Defaults to None.
      :type custom_nodes: Optional[Dict[str, Callable]], optional
      :param custom_edges: Custom edges. Defaults to None.
      :type custom_edges: Optional[List[Dict[str, Any]]], optional
      :param conditional_edges: Conditional edges. Defaults to None.
      :type conditional_edges: Optional[Dict[str, Dict[str, Any]]], optional

      :returns: A new agent class with all methods and workflow configured.
      :rtype: Type[Agent]

      .. rubric:: Examples

      >>> # Create a chess agent with analysis
      >>> chess_agent = GameAgentFactory.create_game_agent(
      ...     name="ChessAgent",
      ...     state_schema=ChessState,
      ...     state_manager=ChessStateManager,
      ...     enable_analysis=True,
      ...     aug_llm_configs={
      ...         "player1": player1_config,
      ...         "player2": player2_config
      ...     }
      ... )



   .. py:method:: create_standard_workflow(graph, enable_analysis = True)
      :staticmethod:


      Add a standard game workflow to an existing graph.

      This method creates the typical workflow for a turn-based game with
      two players, optionally including analysis steps. It modifies the
      provided graph by adding nodes and edges for the standard game flow.

      :param graph: The state graph to modify.
      :type graph: StateGraph
      :param enable_analysis: Whether to include analysis steps.
                              Defaults to True.
      :type enable_analysis: bool, optional

      :returns: The modified graph with standard workflow added.
      :rtype: StateGraph

      .. rubric:: Examples

      >>> # Create a basic graph and add standard workflow
      >>> graph = StateGraph()
      >>> graph = GameAgentFactory.create_standard_workflow(
      ...     graph,
      ...     enable_analysis=True
      ... )