haive.agents.dynamic_supervisor.state
=====================================

.. py:module:: haive.agents.dynamic_supervisor.state

.. autoapi-nested-parse::

   State schemas for dynamic supervisor agent.

   from typing import Any
   This module defines the state management for the dynamic supervisor, including
   agent registry, routing control, and tool generation. Two versions are provided:
   - SupervisorState: Uses exclude=True for agent serialization (v1)
   - SupervisorStateV2: Attempts full agent serialization (experimental)

   Classes:
       SupervisorState: Base supervisor state with agent registry
       SupervisorStateWithTools: Extends base with dynamic tool generation
       SupervisorStateV2: Experimental version with full serialization

   .. rubric:: Examples

   Creating and managing supervisor state::

       state = SupervisorState()
       state.add_agent("search", search_agent, "Search specialist")
       state.activate_agent("search")

       # List active agents
       active = state.list_active_agents()



Classes
-------

.. autoapisummary::

   haive.agents.dynamic_supervisor.state.SupervisorState
   haive.agents.dynamic_supervisor.state.SupervisorStateV2
   haive.agents.dynamic_supervisor.state.SupervisorStateWithTools


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

.. py:class:: SupervisorState(/, **data)

   Bases: :py:obj:`haive.core.schema.prebuilt.messages.messages_with_token_usage.MessagesStateWithTokenUsage`


   Base state for dynamic supervisor with agent registry.

   Inherits from MessagesState for message handling and adds agent management
   capabilities. Agents are stored in a registry with metadata for routing.

   .. attribute:: agents

      Registry of available agents by name

   .. attribute:: active_agents

      List of currently active agent names (unique)

   .. attribute:: next_agent

      Name of agent to execute next (routing control)

   .. attribute:: agent_task

      Task to pass to the selected agent

   .. attribute:: agent_response

      Response from the last executed agent

   .. rubric:: Examples

   Basic agent management::

       state = SupervisorState()
       state.add_agent("math", math_agent, "Math specialist")
       state.set_routing("math", "Calculate 2+2")

   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.


   .. py:method:: activate_agent(name)

      Activate an inactive agent.

      :param name: Agent name to activate

      :returns: True if agent was activated, False if not found



   .. py:method:: add_agent(name, agent, description, active = True)

      Add an agent to the registry.

      :param name: Unique identifier for the agent
      :param agent: The agent instance
      :param description: Human-readable description of agent capabilities
      :param active: Whether agent should be immediately active

      .. rubric:: Examples

      state.add_agent("search", search_agent, "Web search expert", active=True)



   .. py:method:: clear_execution_state()

      Clear execution state after completion.



   .. py:method:: deactivate_agent(name)

      Deactivate an active agent.

      :param name: Agent name to deactivate

      :returns: True if agent was deactivated, False if not found



   .. py:method:: ensure_unique_agents(v)
      :classmethod:


      Ensure active agents list contains unique values.

      :param v: List of agent names

      :returns: List with duplicates removed



   .. py:method:: get_agent(name)

      Get agent instance by name.

      :param name: Agent name

      :returns: Agent instance or None if not found



   .. py:method:: list_active_agents()

      List all active agents with descriptions.

      :returns: Dict mapping agent names to descriptions



   .. py:method:: list_all_agents()

      List all agents (active and inactive) with descriptions.

      :returns: Dict mapping agent names to descriptions



   .. py:method:: remove_agent(name)

      Remove an agent from the registry completely.

      :param name: Agent name to remove

      :returns: True if agent was removed, False if not found



   .. py:attribute:: model_config

      Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].


.. py:class:: SupervisorStateV2(/, **data)

   Bases: :py:obj:`haive.core.schema.prebuilt.messages.messages_with_token_usage.MessagesStateWithTokenUsage`


   Experimental supervisor state with full agent serialization.

   This version attempts to serialize agents fully rather than excluding them.
   May require custom serialization logic or agent reconstruction.

   .. warning::

      This is experimental and may not work with all agent types or
      checkpointing systems. Use SupervisorState for production.

   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.


   .. py:attribute:: model_config

      Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].


.. py:class:: SupervisorStateWithTools(/, **data)

   Bases: :py:obj:`SupervisorState`


   Supervisor state with dynamic tool generation.

   Extends SupervisorState with automatic tool generation from registered agents.
   Creates handoff tools for each agent and manages a dynamic choice model.

   .. attribute:: agent_choice_model

      Dynamic model for validated agent selection

   .. attribute:: generated_tools

      List of tool names generated from agents

   .. rubric:: Examples

   Using dynamic tools::

       state = SupervisorStateWithTools()
       state.add_agent("search", agent, "Search expert")
       state.sync_agents()  # Generates handoff_to_search tool

       tools = state.get_all_tools()  # Get tool instances

   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.


   .. py:method:: activate_agent(name)

      Override to trigger tool regeneration.



   .. py:method:: add_agent(name, agent, description, active = True)

      Override to trigger tool regeneration.



   .. py:method:: deactivate_agent(name)

      Override to trigger tool regeneration.



   .. py:method:: get_all_tools()

      Get all generated tools as callable instances.

      :returns: List of tool instances ready for use



   .. py:method:: remove_agent(name)

      Override to trigger tool regeneration.



   .. py:method:: sync_agents()

      Public method to sync agents with tools and choice model.

      Call this after adding/removing agents to regenerate tools.



   .. py:method:: sync_on_init()

      Sync tools and choice model after initialization.