agents.discovery.semantic_discovery

Semantic Discovery Engine with Vector-Based Tool Selection.

This module implements semantic discovery capabilities inspired by LangGraph’s many-tools pattern, using vector embeddings to match tools and components based on query content and semantic similarity.

Key Features: - Vector-based tool discovery and ranking - Semantic capability matching - Query analysis and tool recommendation - Dynamic tool binding and selection - Context-aware component matching

Classes

CapabilityMatcher

Matches tools based on required capabilities.

DiscoveryMode

Different modes for semantic discovery.

QueryAnalysis

Analysis of user query for tool selection.

QueryAnalyzer

Analyzes queries to extract relevant information for tool selection.

SemanticDiscoveryEngine

Main semantic discovery engine combining all capabilities.

ToolSelectionStrategy

Strategies for tool selection.

VectorBasedToolSelector

Selects tools using vector similarity search.

Functions

create_component_registry(**kwargs)

Create Component Registry.

create_semantic_discovery()

Create a semantic discovery engine with default configuration.

Module Contents

class agents.discovery.semantic_discovery.CapabilityMatcher(/, **data)

Bases: pydantic.BaseModel

Matches tools based on required capabilities.

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.

Parameters:

data (Any)

build_capability_matrix(tools)

Build capability matrix from tools.

Parameters:

tools (list[Any])

Return type:

None

match_tools(required_capabilities, optional_capabilities=None)

Match tools based on capabilities.

Parameters:

  • required_capabilities (list[str])

  • optional_capabilities (list[str] | None)

Return type:

list[tuple[str, float]]

class agents.discovery.semantic_discovery.DiscoveryMode

Bases: str, enum.Enum

Different modes for semantic discovery.

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

class agents.discovery.semantic_discovery.QueryAnalysis

Analysis of user query for tool selection.

class agents.discovery.semantic_discovery.QueryAnalyzer(/, **data)

Bases: pydantic.BaseModel

Analyzes queries to extract relevant information for tool selection.

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.

Parameters:

data (Any)

analyze_query(query)

Analyze query to extract useful information.

Parameters:

query (str)

Return type:

QueryAnalysis

class agents.discovery.semantic_discovery.SemanticDiscoveryEngine(/, **data)

Bases: pydantic.BaseModel

Main semantic discovery engine combining all capabilities.

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.

Parameters:

data (Any)

async discover_tools(tools=None, haive_root=None)

Discover available tools.

Parameters:

  • tools (list[Any] | None)

  • haive_root (str | None)

Return type:

list[haive.core.registry.ComponentMetadata]

async get_tools_for_capabilities(required_capabilities, optional_capabilities=None, max_tools=5)

Get tools that match specific capabilities.

Parameters:

  • required_capabilities (list[str])

  • optional_capabilities (list[str] | None)

  • max_tools (int)

Return type:

list[haive.core.registry.ComponentMetadata]

async semantic_tool_selection(query, max_tools=5, strategy=ToolSelectionStrategy.HYBRID, capability_filter=None)

Perform semantic tool selection for a query.

Parameters:
Return type:

tuple[list[haive.core.registry.ComponentMetadata], QueryAnalysis]

setup_registry()

Setup shared component registry.

Return type:

SemanticDiscoveryEngine

update_selection_strategy(strategy)

Update the selection strategy.

Parameters:

strategy (haive.agents.discovery.selection_strategies.BaseSelectionStrategy | str)

Return type:

None

class agents.discovery.semantic_discovery.ToolSelectionStrategy

Bases: str, enum.Enum

Strategies for tool selection.

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

class agents.discovery.semantic_discovery.VectorBasedToolSelector(/, **data)

Bases: pydantic.BaseModel

Selects tools using vector similarity search.

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.

Parameters:

data (Any)

index_tools(tools)

Index tools in vector store and component registry.

Parameters:

tools (list[Any])

Return type:

None

async select_tools(query, strategy=ToolSelectionStrategy.TOP_K)

Select tools based on query using specified strategy.

Parameters:
Return type:

list[haive.core.registry.ComponentMetadata]

setup_vector_store()

Setup vector store if not provided.

Return type:

VectorBasedToolSelector

model_config

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

agents.discovery.semantic_discovery.create_component_registry(**kwargs)

Create Component Registry.

agents.discovery.semantic_discovery.create_semantic_discovery()

Create a semantic discovery engine with default configuration.

Return type:

SemanticDiscoveryEngine