haive.agents.dynamic_supervisor.models
======================================

.. py:module:: haive.agents.dynamic_supervisor.models

.. autoapi-nested-parse::

   Data models for dynamic supervisor agent.

   This module contains Pydantic models used by the dynamic supervisor for
   agent metadata, routing information, and configuration.

   Classes:
       AgentInfo: Metadata container for agents (v1 with exclusion)
       AgentInfoV2: Experimental version with full serialization
       AgentRequest: Model for agent addition requests
       RoutingDecision: Model for routing decisions

   .. rubric:: Example

   Creating agent metadata::

       info = AgentInfo(
           agent=search_agent,
           name="search",
           description="Web search specialist",
           active=True
       )



Classes
-------

.. autoapisummary::

   haive.agents.dynamic_supervisor.models.AgentInfo
   haive.agents.dynamic_supervisor.models.AgentInfoV2
   haive.agents.dynamic_supervisor.models.AgentRequest
   haive.agents.dynamic_supervisor.models.RoutingDecision


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

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

   Bases: :py:obj:`pydantic.BaseModel`


   Information about an agent including instance and metadata.

   This model stores agent metadata and the agent instance itself. The agent
   field is excluded from serialization to avoid msgpack serialization issues
   with complex objects.

   .. attribute:: agent

      The actual agent instance (excluded from serialization)

   .. attribute:: name

      Unique identifier for the agent

   .. attribute:: description

      Human-readable description of capabilities

   .. attribute:: active

      Whether the agent is currently active

   .. attribute:: capabilities

      List of capability keywords for discovery

   .. attribute:: metadata

      Additional metadata (versions, config, etc.)

   .. rubric:: Example

   Creating agent info::

       info = AgentInfo(
           agent=math_agent,
           name="math",
           description="Mathematics and calculation expert",
           capabilities=["math", "calculation", "statistics"]
       )

   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()

      Activate the agent.



   .. py:method:: deactivate()

      Deactivate the agent.



   .. py:method:: extract_agent_info()

      Extract name and description from agent if not provided.

      :returns: Self with extracted information



   .. py:method:: get_agent()

      Get the agent instance.

      :returns: The agent instance



   .. py:method:: is_active()

      Check if agent is active.

      :returns: True if active, False otherwise



   .. py:method:: matches_capability(required)

      Check if agent has a required capability.

      :param required: Capability keyword to check

      :returns: True if agent has the capability



   .. py:attribute:: model_config

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


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

   Bases: :py:obj:`pydantic.BaseModel`


   Experimental version with full agent serialization.

   This version attempts to serialize the agent object. Requires custom
   serialization logic or agents that support model_dump().

   .. warning:: Experimental - may not work with all agent types.

   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:: serialize_agent(agent)

      Attempt to serialize agent to dict.

      :param agent: Agent instance

      :returns: Serialized representation



   .. py:attribute:: model_config

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


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

   Bases: :py:obj:`pydantic.BaseModel`


   Model for requesting a new agent be added.

   Used when the supervisor identifies a missing capability and needs
   to request a new agent from an agent builder or registry.

   .. attribute:: capability

      The required capability (e.g., "translation", "code_analysis")

   .. attribute:: task_context

      Context about what task needs this capability

   .. attribute:: suggested_name

      Suggested name for the new agent

   .. attribute:: requirements

      Specific requirements or constraints

   .. rubric:: Example

   Requesting a new agent::

       request = AgentRequest(
           capability="translation",
           task_context="Need to translate search results to French",
           suggested_name="translator",
           requirements=["Support French", "Maintain formatting"]
       )

   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:class:: RoutingDecision(/, **data)

   Bases: :py:obj:`pydantic.BaseModel`


   Model for supervisor routing decisions.

   Represents a decision made by the supervisor about which agent
   to route to or what action to take.

   .. attribute:: agent_name

      Name of agent to route to (or "END")

   .. attribute:: task

      Task to give to the agent

   .. attribute:: reasoning

      Explanation of the routing decision

   .. attribute:: confidence

      Confidence level in the decision (0-1)

   .. attribute:: alternatives

      Other agents that could handle this

   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.