haive.agents.discovery.semantic_discovery
=========================================

.. py:module:: haive.agents.discovery.semantic_discovery

.. autoapi-nested-parse::

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

.. autoapisummary::

   haive.agents.discovery.semantic_discovery.CapabilityMatcher
   haive.agents.discovery.semantic_discovery.DiscoveryMode
   haive.agents.discovery.semantic_discovery.QueryAnalysis
   haive.agents.discovery.semantic_discovery.QueryAnalyzer
   haive.agents.discovery.semantic_discovery.SemanticDiscoveryEngine
   haive.agents.discovery.semantic_discovery.ToolSelectionStrategy
   haive.agents.discovery.semantic_discovery.VectorBasedToolSelector


Functions
---------

.. autoapisummary::

   haive.agents.discovery.semantic_discovery.create_component_registry
   haive.agents.discovery.semantic_discovery.create_semantic_discovery


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

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

   Bases: :py:obj:`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.


   .. py:method:: build_capability_matrix(tools)

      Build capability matrix from tools.



   .. py:method:: match_tools(required_capabilities, optional_capabilities = None)

      Match tools based on capabilities.



.. py:class:: DiscoveryMode

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Different modes for semantic discovery.

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


.. py:class:: QueryAnalysis

   Analysis of user query for tool selection.


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

   Bases: :py:obj:`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.


   .. py:method:: analyze_query(query)

      Analyze query to extract useful information.



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

   Bases: :py:obj:`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.


   .. py:method:: discover_tools(tools = None, haive_root = None)
      :async:


      Discover available tools.



   .. py:method:: get_tools_for_capabilities(required_capabilities, optional_capabilities = None, max_tools = 5)
      :async:


      Get tools that match specific capabilities.



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


      Perform semantic tool selection for a query.



   .. py:method:: setup_registry()

      Setup shared component registry.



   .. py:method:: update_selection_strategy(strategy)

      Update the selection strategy.



.. py:class:: ToolSelectionStrategy

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Strategies for tool selection.

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


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

   Bases: :py:obj:`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.


   .. py:method:: index_tools(tools)

      Index tools in vector store and component registry.



   .. py:method:: select_tools(query, strategy = ToolSelectionStrategy.TOP_K)
      :async:


      Select tools based on query using specified strategy.



   .. py:method:: setup_vector_store()

      Setup vector store if not provided.



   .. py:attribute:: model_config

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


.. py:function:: create_component_registry(**kwargs)

   Create Component Registry.


.. py:function:: create_semantic_discovery()

   Create a semantic discovery engine with default configuration.