haive.games.nim.agent
=====================

.. py:module:: haive.games.nim.agent

.. autoapi-nested-parse::

   Agent for playing Nim.

   This module defines the Nim agent, which uses language models to generate moves and
   analyze positions in the game.



Classes
-------

.. autoapisummary::

   haive.games.nim.agent.NimAgent


Functions
---------

.. autoapisummary::

   haive.games.nim.agent.ensure_game_state


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

.. py:class:: NimAgent(config = NimConfig())

   Bases: :py:obj:`haive.games.framework.base.agent.GameAgent`\ [\ :py:obj:`haive.games.nim.config.NimConfig`\ ]


   Agent for playing Nim.

   Initialize the Nim agent.

   :param config: The configuration for the game.
   :type config: NimConfig


   .. py:method:: analyze_player1(state)

      Analyze position for player1.

      :param state: The current game state.
      :type state: NimState

      :returns: The command to analyze the position.
      :rtype: Command



   .. py:method:: analyze_player2(state)

      Analyze position for player2.

      :param state: The current game state.
      :type state: NimState

      :returns: The command to analyze the position.
      :rtype: Command



   .. py:method:: analyze_position(state, player)

      Analyze the current position for the specified player.

      :param state: The current game state.
      :param player: The player to analyze the position for.

      :returns: The command to analyze the position.
      :rtype: Command



   .. py:method:: extract_move(response)

      Extract move from engine response.

      :param response: The response from the engine.
      :type response: Any

      :returns: The move from the engine.
      :rtype: Any



   .. py:method:: initialize_game(state)

      Initialize a new Nim game with configured pile sizes.

      :param state: The initial state of the game.

      :returns: The command to initialize the game.
      :rtype: Command



   .. py:method:: make_move(state, player)

      Make a move for the specified player.

      :param state: The current game state.
      :param player: The player to make the move for.

      :returns: The command to make the move.
      :rtype: Command



   .. py:method:: make_player1_move(state)

      Make a move for player1.

      :param state: The current game state.
      :type state: NimState

      :returns: The command to make the move.
      :rtype: Command



   .. py:method:: make_player2_move(state)

      Make a move for player2.

      :param state: The current game state.
      :type state: NimState

      :returns: The command to make the move.
      :rtype: Command



   .. py:method:: prepare_analysis_context(state, player)

      Prepare context for position analysis.

      :param state: The current game state.
      :type state: NimState
      :param player: The player to prepare the context for.
      :type player: str

      :returns: The context for the position analysis.
      :rtype: Dict[str, Any]



   .. py:method:: prepare_move_context(state, player)

      Prepare context for move generation.

      :param state: The current game state.
      :type state: NimState
      :param player: The player to prepare the context for.
      :type player: str

      :returns: The context for the move generation.
      :rtype: Dict[str, Any]



   .. py:method:: run_game(visualize = True)

      Run a complete Nim game with optional visualization.

      :param visualize: Whether to visualize each game state.
      :type visualize: bool

      :returns: The final game state.
      :rtype: Dict[str, Any]



   .. py:method:: run_game_with_ui(show_analysis = True)

      Run a complete Nim game with Rich UI.

      This method runs a Nim game with Rich UI visualization, showing
      the game state after each move. It optionally includes analysis.

      :param show_analysis: Whether to include analysis in the game.

      :returns: The final game state.
      :rtype: Dict[str, Any]



   .. py:method:: setup_workflow()

      Set up the game workflow.

      :returns: None



   .. py:method:: visualize_state(state)

      Visualize the current game state.

      :param state: The current game state.
      :type state: Dict[str, Any]



.. py:function:: ensure_game_state(state_input)

   Ensure input is converted to NimState.

   This helper function ensures that the input state is properly converted to a NimState
   object, handling various input types (dict, NimState, Command).

   :param state_input: The state to convert, which can be a dictionary, NimState, or Command.

   :returns: The converted state.
   :rtype: NimState