haive.games.mancala.agent
=========================

.. py:module:: haive.games.mancala.agent

.. autoapi-nested-parse::

   Mancala game agent.

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



Classes
-------

.. autoapisummary::

   haive.games.mancala.agent.MancalaAgent


Functions
---------

.. autoapisummary::

   haive.games.mancala.agent.ensure_game_state
   haive.games.mancala.agent.extract_data_from_response


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

.. py:class:: MancalaAgent(config)

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


   Agent for playing Mancala using language models.

   This agent uses LLMs to generate moves and analyze positions
   in the Mancala game. It builds a dynamic graph for game flow
   and uses structured outputs for reliable move generation.

   .. attribute:: config

      Configuration for the Mancala game.

   .. attribute:: graph_builder

      Dynamic graph builder for game flow.

   .. attribute:: state_manager

      Manager for game state transitions.

   Initialize the Mancala agent.

   :param config: Configuration for the Mancala game.


   .. py:method:: check_game_over(state)

      Check if the game is over and update state accordingly.

      :param state: Current game state.

      :returns: Updated game state as dictionary.



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

      Make a move for the specified player.

      This method handles move generation, validation, and state updates.
      It includes retry logic for invalid moves and fallback to random
      valid moves if the LLM fails.

      :param state: Current game state.
      :param player: Player making the move ('player1' or 'player2').

      :returns: Updated game state after the move.



   .. py:method:: player1_turn(state)

      Execute player 1's turn.

      :param state: Current game state.

      :returns: Updated game state after player 1's move as dictionary.



   .. py:method:: player2_turn(state)

      Execute player 2's turn.

      :param state: Current game state.

      :returns: Updated game state after player 2's move as dictionary.



   .. py:method:: run(input_data = None)

      Run the Mancala game.

      :param input_data: Optional input data for the game.

      :returns: The final game state as a dictionary.



   .. py:method:: simple_play(state)

      Simple play logic for fallback mode.

      :param state: Current game state.

      :returns: Updated game state as dictionary.



.. py:function:: ensure_game_state(state_input)

   Ensure input is converted to MancalaState.

   :param state_input: Input that could be a dict, MancalaState, or Command.

   :returns: Properly typed game state.
   :rtype: MancalaState


.. py:function:: extract_data_from_response(response, data_type = 'move')

   Extract move or analysis data from an LLM response.

   :param response: The response from the LLM.
   :param data_type: Type of data to extract ('move' or 'analysis').

   :returns: Extracted data dictionary or None.