agents.discovery.component_discovery_agent

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

ComponentDiscoveryAgent

RAG-based agent for discovering components from documentation.

Module Contents

class agents.discovery.component_discovery_agent.ComponentDiscoveryAgent(/, **data)

Bases: 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

Parameters:

  • document_path – Path to documentation or component sources

  • discovery_agent – BaseRAGAgent for performing retrieval

  • meta_state – MetaStateSchema wrapper for the discovery agent

  • discovery_config – Configuration for discovery behavior

  • component_cache – Cache for discovered components

  • data (Any)

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.

clear_cache()

Clear the component cache.

Examples

Clear cache:

agent.clear_cache()
print("Cache cleared")
Return type:

None

async discover_components(query)

Discover components based on a query.

Parameters:

query (str) – Natural language query describing needed components

Returns:

List of component dictionaries with metadata

Return type:

list[dict[str, Any]]

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

Get statistics about the component cache.

Returns:

Dictionary with cache statistics

Return type:

dict[str, Any]

Examples

Check cache status:

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

Load actual component instance from component document.

Parameters:

component_doc (dict[str, Any]) – Component dictionary from discovery

Returns:

Loaded component instance or None if loading fails

Return type:

Any | None

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}")
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

Return type:

ComponentDiscoveryAgent

model_config

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