haive.agents.supervisor.models
==============================

.. py:module:: haive.agents.supervisor.models

.. autoapi-nested-parse::

   Data models for Dynamic Supervisor V2.

   This module contains all the Pydantic models and enums used by the dynamic supervisor
   for agent specifications, capabilities, and configuration.



Classes
-------

.. autoapisummary::

   haive.agents.supervisor.models.AgentCapability
   haive.agents.supervisor.models.AgentDiscoveryMode
   haive.agents.supervisor.models.AgentSpec
   haive.agents.supervisor.models.DiscoveryConfig


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

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

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


   Rich metadata describing an agent's capabilities.

   This model captures comprehensive information about what an agent can do,
   enabling intelligent task-to-agent matching.

   .. attribute:: name

      Unique identifier for the agent

   .. attribute:: agent_type

      Type of agent (e.g., SimpleAgent, ReactAgent)

   .. attribute:: description

      Human-readable description of agent's purpose

   .. attribute:: specialties

      List of task domains the agent excels at

   .. attribute:: tools

      Names of tools available to this agent

   .. attribute:: active

      Whether the agent is currently active

   .. attribute:: performance_score

      Historical performance metric (0-1)

   .. attribute:: usage_count

      Number of times this agent has been used

   .. attribute:: last_used

      Timestamp of last usage (ISO format)

   .. attribute:: metadata

      Additional custom metadata

   .. rubric:: Examples

   >>> capability = AgentCapability(
   ...     name="research_expert",
   ...     agent_type="ReactAgent",
   ...     description="Expert at research and information gathering",
   ...     specialties=["research", "analysis", "web search"],
   ...     tools=["web_search", "document_reader"]
   ... )

   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:: matches_task(task, threshold = 0.3)

      Calculate match score between this agent's capabilities and a task.

      :param task: The task description to match against
      :param threshold: Minimum score to consider a match (0-1)

      :returns: Match score between 0 and 1



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


      Ensure specialties are lowercase for consistent matching.



.. py:class:: AgentDiscoveryMode

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Agent discovery modes for the dynamic supervisor.

   .. attribute:: MANUAL

      Use manually provided agent specifications

   .. attribute:: COMPONENT_DISCOVERY

      Discover agents from installed components

   .. attribute:: RAG_DISCOVERY

      Use RAG to find relevant agent implementations

   .. attribute:: MCP_DISCOVERY

      Discover agents via Model Context Protocol

   .. attribute:: HYBRID

      Combine multiple discovery methods

   Initialize self.  See help(type(self)) for accurate signature.


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

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


   Specification for creating an agent dynamically.

   This model defines everything needed to instantiate a new agent at runtime,
   including its type, configuration, and capabilities.

   .. attribute:: name

      Unique identifier for the agent

   .. attribute:: agent_type

      Type of agent to create (e.g., "SimpleAgent", "ReactAgent")

   .. attribute:: description

      Human-readable description

   .. attribute:: specialties

      Task domains this agent should handle

   .. attribute:: tools

      Tool names or instances to provide to the agent

   .. attribute:: config

      Configuration dictionary for agent initialization

   .. attribute:: priority

      Priority level for agent selection (higher = preferred)

   .. attribute:: enabled

      Whether this spec can be used to create agents

   .. rubric:: Examples

   >>> spec = AgentSpec(
   ...     name="code_reviewer",
   ...     agent_type="ReactAgent",
   ...     description="Expert code reviewer and analyzer",
   ...     specialties=["code review", "analysis", "best practices"],
   ...     tools=["file_reader", "code_analyzer"],
   ...     config={
   ...         "temperature": 0.2,
   ...         "system_message": "You are an expert code reviewer."
   ...     }
   ... )

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

      Convert this spec to an AgentCapability.



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


      Ensure specialties are lowercase for consistent matching.



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

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


   Configuration for agent discovery mechanisms.

   .. attribute:: mode

      Discovery mode to use

   .. attribute:: component_paths

      Paths to search for component discovery

   .. attribute:: rag_collection

      Collection name for RAG discovery

   .. attribute:: mcp_endpoints

      MCP server endpoints for discovery

   .. attribute:: cache_discoveries

      Whether to cache discovered agents

   .. attribute:: discovery_timeout

      Timeout for discovery operations (seconds)

   .. attribute:: max_discoveries_per_request

      Maximum agents to discover per request

   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.