haive.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 haive.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 haive.agents.discovery.semantic_discovery.DiscoveryMode¶

Bases: str, enum.Enum

Different modes for semantic discovery.

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

class haive.agents.discovery.semantic_discovery.QueryAnalysis¶: Analysis of user query for tool selection.

class haive.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 haive.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:

query (str)
max_tools (int)
strategy (ToolSelectionStrategy)
capability_filter (list[str] | None)

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 haive.agents.discovery.semantic_discovery.ToolSelectionStrategy¶

Bases: str, enum.Enum

Strategies for tool selection.

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

class haive.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:

query (str)
strategy (ToolSelectionStrategy)

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].

haive.agents.discovery.semantic_discovery.create_component_registry(**kwargs)¶: Create Component Registry.

haive.agents.discovery.semantic_discovery.create_semantic_discovery()¶

Create a semantic discovery engine with default configuration.

Return type:: SemanticDiscoveryEngine