haive.agents.supervisor.state
=============================

.. py:module:: haive.agents.supervisor.state

.. autoapi-nested-parse::

   State management for Dynamic Supervisor V2.

   This module defines the state structures used by the dynamic supervisor to track
   agents, tasks, metrics, and workflow execution.



Classes
-------

.. autoapisummary::

   haive.agents.supervisor.state.ActiveAgent
   haive.agents.supervisor.state.DynamicSupervisorState
   haive.agents.supervisor.state.SupervisorMetrics


Functions
---------

.. autoapisummary::

   haive.agents.supervisor.state.create_initial_state


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

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

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


   Represents an active agent instance in the supervisor.

   .. attribute:: name

      Unique identifier for the agent

   .. attribute:: instance

      The actual agent instance (excluded from serialization)

   .. attribute:: capability

      Full capability metadata for this agent

   .. attribute:: created_at

      When this agent was instantiated

   .. attribute:: last_task

      Description of the last task assigned

   .. attribute:: task_count

      Number of tasks completed

   .. attribute:: total_execution_time

      Cumulative execution time in seconds

   .. attribute:: error_count

      Number of errors encountered

   .. attribute:: state

      Current agent state (idle, busy, error)

   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:: update_metrics(execution_time, success = True)

      Update agent metrics after task execution.

      :param execution_time: Time taken for the task in seconds
      :param success: Whether the task completed successfully



   .. py:property:: average_execution_time
      :type: float


      Calculate average execution time per task.


   .. py:attribute:: model_config

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


   .. py:property:: success_rate
      :type: float


      Calculate task success rate.


.. py:class:: DynamicSupervisorState

   Bases: :py:obj:`TypedDict`


   State structure for dynamic supervisor execution.

   This TypedDict defines the state that flows through the supervisor's
   execution graph in LangGraph.

   .. attribute:: messages

      Conversation history (LangGraph standard)

   .. attribute:: active_agents

      Currently instantiated agents

   .. attribute:: agent_capabilities

      All known agent capabilities

   .. attribute:: discovered_agents

      Set of agent names that have been discovered

   .. attribute:: available_specs

      Agent specifications that can be instantiated

   .. attribute:: current_agent

      Name of agent handling current task

   .. attribute:: agent_task

      Task assigned to current agent

   .. attribute:: agent_response

      Response from current agent

   .. attribute:: next_agent

      Next agent to route to

   .. attribute:: supervisor_metrics

      Performance metrics

   .. attribute:: discovery_cache

      Cache of discovery results

   .. attribute:: workflow_state

      Current workflow state (routing, executing, etc.)

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


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

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


   Metrics tracking for the supervisor's performance.

   .. attribute:: total_tasks

      Total tasks processed

   .. attribute:: successful_tasks

      Tasks completed successfully

   .. attribute:: failed_tasks

      Tasks that failed

   .. attribute:: agent_creations

      Number of agents created

   .. attribute:: discovery_attempts

      Number of discovery attempts

   .. attribute:: successful_discoveries

      Successful discoveries

   .. attribute:: total_execution_time

      Total time spent on tasks

   .. attribute:: start_time

      When supervisor was created

   .. attribute:: last_task_time

      Timestamp of last task

   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:property:: discovery_success_rate
      :type: float


      Calculate discovery success rate.


   .. py:property:: success_rate
      :type: float


      Calculate overall success rate.


   .. py:property:: uptime_hours
      :type: float


      Calculate supervisor uptime in hours.


.. py:function:: create_initial_state(available_specs = None, discovery_cache = None)

   Create initial state for dynamic supervisor.

   :param available_specs: Initial agent specifications
   :param discovery_cache: Pre-populated discovery cache

   :returns: Initialized supervisor state