haive.agents.discovery.component_discovery_agent
================================================

.. py:module:: haive.agents.discovery.component_discovery_agent

.. autoapi-nested-parse::

   Component Discovery Agent for Dynamic Activation.

   This module provides ComponentDiscoveryAgent, a RAG-based agent for discovering
   components from documentation. It uses MetaStateSchema for tracking and follows
   the Dynamic Activation Pattern.

   Based on: @project_docs/active/patterns/dynamic_activation_pattern.md



Classes
-------

.. autoapisummary::

   haive.agents.discovery.component_discovery_agent.ComponentDiscoveryAgent


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

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

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


   RAG-based agent for discovering components from documentation.

   This agent uses retrieval-augmented generation to find components that
   can satisfy specific requirements. It wraps a BaseRAGAgent in MetaStateSchema
   for tracking and recompilation support.

   Key Features:
       - RAG-based component discovery from documentation
       - MetaStateSchema integration for tracking
       - Automatic document loading from various sources
       - Component parsing and metadata extraction
       - Caching for performance
       - Error handling and logging

   :param document_path: Path to documentation or component sources
   :param discovery_agent: BaseRAGAgent for performing retrieval
   :param meta_state: MetaStateSchema wrapper for the discovery agent
   :param discovery_config: Configuration for discovery behavior
   :param component_cache: Cache for discovered components

   .. rubric:: Examples

   Basic usage::

       from haive.agents.discovery.component_discovery_agent import ComponentDiscoveryAgent

       # Create discovery agent
       agent = ComponentDiscoveryAgent(
           document_path="@haive-tools/docs"
       )

       # Discover components
       components = await agent.discover_components("math tools")

       for comp in components:
           print(f"Found: {comp['name']} - {comp['description']}")

   With custom configuration::

       agent = ComponentDiscoveryAgent(
           document_path="/path/to/docs",
           discovery_config={
               "max_results": 5,
               "similarity_threshold": 0.7,
               "use_cache": True
           }
       )

       # Discover specific capabilities
       components = await agent.discover_components(
           "tools for data visualization and charting"
       )

   From Haive components::

       # Use HaiveComponentDiscovery for automatic loading
       agent = ComponentDiscoveryAgent(
           document_path="@haive-tools"
       )

       # Find tools that can handle specific tasks
       tools = await agent.discover_components("file processing tools")

       # Parse and load actual tool instances
       for tool_doc in tools:
           tool_instance = await agent.load_component_from_doc(tool_doc)
           if tool_instance:
               print(f"Loaded tool: {tool_instance.name}")

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

      Clear the component cache.

      .. rubric:: Examples

      Clear cache::

          agent.clear_cache()
          print("Cache cleared")



   .. py:method:: discover_components(query)
      :async:


      Discover components based on a query.

      :param query: Natural language query describing needed components

      :returns: List of component dictionaries with metadata

      .. rubric:: Examples

      Discover math tools::

          components = await agent.discover_components("math and calculation tools")

      Discover with specific requirements::

          components = await agent.discover_components(
              "tools for file processing and data extraction"
          )



   .. py:method:: get_cache_stats()

      Get statistics about the component cache.

      :returns: Dictionary with cache statistics

      .. rubric:: Examples

      Check cache status::

          stats = agent.get_cache_stats()
          print(f"Cached queries: {stats['cached_queries']}")
          print(f"Total components: {stats['total_components']}")



   .. py:method:: load_component_from_doc(component_doc)
      :async:


      Load actual component instance from component document.

      :param component_doc: Component dictionary from discovery

      :returns: Loaded component instance or None if loading fails

      .. rubric:: Examples

      Load discovered component::

          components = await agent.discover_components("calculator")
          for comp_doc in components:
              instance = await agent.load_component_from_doc(comp_doc)
              if instance:
                  print(f"Loaded: {instance}")



   .. py:method:: setup_discovery_agent()

      Initialize the discovery agent after model creation.

      This validator:
      1. Loads documents from the specified path
      2. Creates BaseRAGAgent with documents
      3. Wraps agent in MetaStateSchema
      4. Sets up configuration defaults
      5. Initializes caching system



   .. py:attribute:: model_config

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