isage-tooluse 0.1.0.0__py3-none-any.whl

isage_tooluse-0.1.0.0.dist-info/METADATA

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: isage-tooluse
+Version: 0.1.0.0
+Summary: Tool retrieval and ranking algorithms for LLM agents
+Author-email: IntelliStream Team <shuhao_zhang@hust.edu.cn>
+Project-URL: Homepage, https://github.com/intellistream/sage-tooluse
+Project-URL: Documentation, https://intellistream.github.io/SAGE-Pub/
+Project-URL: Repository, https://github.com/intellistream/sage-tooluse
+Project-URL: Issues, https://github.com/intellistream/sage-tooluse/issues
+Keywords: sage,tool-selection,tool-use,tool-retrieval,tool-ranking,llm,agents,intellistream
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<2.3.0,>=1.26.0
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.8.4; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Provides-Extra: embedding
+Requires-Dist: sentence-transformers>=2.0.0; extra == "embedding"
+Requires-Dist: faiss-cpu>=1.7.0; extra == "embedding"
+Provides-Extra: all
+Requires-Dist: isage-tooluse[dev,embedding]; extra == "all"
+Dynamic: license-file
+
+# SAGE Tool Use
+
+**Tool retrieval and ranking algorithms for LLM agents**
+
+[![PyPI version](https://badge.fury.io/py/isage-tooluse.svg)](https://badge.fury.io/py/isage-tooluse)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 🎯 Overview
+
+`sage-tooluse` provides a comprehensive suite of tool selection and ranking algorithms for LLM agents:
+
+- **Keyword Selector**: Fast matching based on keyword overlap
+- **Embedding Selector**: Semantic similarity using embeddings
+- **Hybrid Selector**: Combines keyword and embedding approaches
+- **DFS-DT Selector**: Decision tree-based tool selection
+- **Gorilla Adapter**: Gorilla-style tool retrieval
+
+## 📦 Installation
+
+```bash
+# Basic installation
+pip install isage-tooluse
+
+# With embedding support
+pip install isage-tooluse[embedding]
+
+# Development installation
+pip install isage-tooluse[dev]
+```
+
+## 🚀 Quick Start
+
+### Keyword-based Tool Selection
+
+```python
+from sage_libs.sage_tooluse import KeywordToolSelector
+
+# Create selector
+selector = KeywordToolSelector(tools=available_tools)
+
+# Select tools for a query
+selected = selector.select(
+    query="Get current weather in New York",
+    top_k=5
+)
+
+for tool in selected:
+    print(f"Tool: {tool.name}, Score: {tool.score}")
+```
+
+### Embedding-based Tool Selection
+
+```python
+from sage_libs.sage_tooluse import EmbeddingToolSelector
+
+# Create selector with embedding model
+selector = EmbeddingToolSelector(
+    tools=available_tools,
+    model_name="sentence-transformers/all-MiniLM-L6-v2"
+)
+
+# Select tools based on semantic similarity
+selected = selector.select(
+    query="What's the weather like?",
+    top_k=5
+)
+```
+
+### Hybrid Tool Selection
+
+```python
+from sage_libs.sage_tooluse import HybridToolSelector
+
+# Combine keyword and embedding approaches
+selector = HybridToolSelector(
+    tools=available_tools,
+    keyword_weight=0.3,
+    embedding_weight=0.7
+)
+
+selected = selector.select(query="...", top_k=5)
+```
+
+## 📚 Key Components
+
+### Selectors
+
+- **KeywordToolSelector**: Fast keyword-based matching
+- **EmbeddingToolSelector**: Semantic similarity using embeddings
+- **HybridToolSelector**: Weighted combination of multiple selectors
+- **DFSDTToolSelector**: Decision tree-based selection
+- **GorillaAdapter**: Gorilla-style API-centric retrieval
+
+### Base Classes
+
+- **BaseToolSelector**: Abstract base for all selectors
+- **ToolRegistry**: Central registry for selector implementations
+
+### Schemas
+
+- **Tool**: Tool representation with metadata
+- **ToolSelection**: Selection result with scores
+- **SelectionContext**: Context for tool selection
+
+## 🏗️ Architecture
+
+```
+sage_libs.sage_tooluse/
+├── __init__.py              # Public API exports
+├── base.py                  # Base selector interface
+├── keyword_selector.py      # Keyword-based selection
+├── embedding_selector.py    # Embedding-based selection
+├── hybrid_selector.py       # Hybrid selection strategy
+├── dfsdt_selector.py        # Decision tree selector
+├── gorilla_selector.py      # Gorilla-style retrieval
+├── registry.py              # Selector registry
+├── schemas.py               # Data schemas
+└── retriever/               # Retrieval utilities
+```
+
+## 🎓 Use Cases
+
+1. **Agent Tool Selection**: Help agents choose the right tools
+2. **API Discovery**: Find relevant APIs for a task
+3. **Function Calling**: Select appropriate functions for LLMs
+4. **Tool Recommendation**: Recommend tools to users
+5. **Multi-step Planning**: Select tool sequences for complex tasks
+
+## 🔗 Integration with SAGE
+
+This package is part of the SAGE ecosystem and can be used with SAGE agents:
+
+```python
+# Standalone usage
+from sage_libs.sage_tooluse import HybridToolSelector
+
+# With SAGE (when available, through interface layer)
+from sage.libs.tooluse import create_selector
+
+selector = create_selector("hybrid", tools=available_tools)
+```
+
+## 📖 Documentation
+
+- **Repository**: https://github.com/intellistream/sage-tooluse
+- **SAGE Documentation**: https://intellistream.github.io/SAGE-Pub/
+- **Issues**: https://github.com/intellistream/sage-tooluse/issues
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+Originally part of the [sage-agentic](https://github.com/intellistream/sage-agentic) package, now maintained as an independent repository for focused development and research.
+
+## 📧 Contact
+
+- **Team**: IntelliStream Team
+- **Email**: shuhao_zhang@hust.edu.cn
+- **GitHub**: https://github.com/intellistream
+
+---
+
+**Part of the SAGE ecosystem** - Stream Analytics for Generative AI Engines

isage_tooluse-0.1.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+isage_tooluse-0.1.0.0.dist-info/licenses/LICENSE,sha256=FviS_SBgJ3MCvV517X_20AfytowsiItMOu_l3GJWFnI,1080
+sage_libs/sage_tooluse/__init__.py,sha256=bA6hLvDnMNvxwAoeLjMIXFPMizrYW6Vy1t1iBUFXC-4,2014
+sage_libs/sage_tooluse/base.py,sha256=5iLmJ5_oiqcEX7DqcHGgVhrNsQK5B_YRmVZU2eDLWl8,5953
+sage_libs/sage_tooluse/dfsdt_selector.py,sha256=NJ4JojxUGCqCzCSxcti6x3pv-iYNvHnohbvvb5lxcN8,13625
+sage_libs/sage_tooluse/embedding_selector.py,sha256=l8YduV_ikJbZkXHdOfVEHrfhED8eyM-zweJrX6o9Jws,9599
+sage_libs/sage_tooluse/gorilla_selector.py,sha256=CZsF4toPpD0eGijI_uW9RvX4H-M22x0TQKA9a7d_Iko,18466
+sage_libs/sage_tooluse/hybrid_selector.py,sha256=3Bsm4glYrHIBTCV3Yttl-dQIgLv7EEn50hbdOG5EwaY,7370
+sage_libs/sage_tooluse/keyword_selector.py,sha256=0sus1-pbX9NCaIvwIMOhrAE4n3rtUPnZVEFe5TvMAis,7801
+sage_libs/sage_tooluse/registry.py,sha256=xvq__KzoKcdJuys6WKaDgkuU9mI3sA4ne9lYF7VR51Y,5125
+sage_libs/sage_tooluse/schemas.py,sha256=bIvhnP5WqVuJUpYuwGhUR6p4hDWn5e-ZVJCOw-yW82U,7266
+isage_tooluse-0.1.0.0.dist-info/METADATA,sha256=ioD9ce2JRE8Qbjc-OsEqNGPWAvn-obvfcnzxP5SSnn8,6631
+isage_tooluse-0.1.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+isage_tooluse-0.1.0.0.dist-info/top_level.txt,sha256=_xtJhEYnKsvxmrqAlXqhVS4DzJcuU_VhAU_z6LOAGho,10
+isage_tooluse-0.1.0.0.dist-info/RECORD,,

isage_tooluse-0.1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

isage_tooluse-0.1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 IntelliStream Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

isage_tooluse-0.1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sage_libs

sage_libs/sage_tooluse/__init__.py

@@ -0,0 +1,75 @@
+"""
+Tool selection module.
+
+Provides tool selector strategies for choosing relevant tools based on queries.
+"""
+
+__version__ = "0.1.0.0"
+__author__ = "IntelliStream Team"
+__email__ = "shuhao_zhang@hust.edu.cn"
+
+from .base import BaseToolSelector, SelectorResources, ToolSelectorProtocol
+from .dfsdt_selector import DFSDTSelector
+from .embedding_selector import EmbeddingSelector
+from .gorilla_selector import GorillaSelector, GorillaSelectorConfig
+from .hybrid_selector import HybridSelector, HybridSelectorConfig
+from .keyword_selector import KeywordSelector
+from .registry import (
+    SelectorRegistry,
+    create_selector_from_config,
+    get_selector,
+    register_selector,
+)
+from .schemas import (
+    CONFIG_TYPES,
+    AdaptiveSelectorConfig,
+    DFSDTSelectorConfig,
+    EmbeddingSelectorConfig,
+    KeywordSelectorConfig,
+    SelectorConfig,
+    ToolPrediction,
+    ToolSelectionQuery,
+    TwoStageSelectorConfig,
+    create_selector_config,
+)
+from .schemas import (
+    GorillaSelectorConfig as GorillaSelectorConfigSchema,
+)
+
+# Auto-register built-in selectors
+register_selector("keyword", KeywordSelector)
+register_selector("embedding", EmbeddingSelector)
+register_selector("hybrid", HybridSelector)
+register_selector("gorilla", GorillaSelector)
+register_selector("dfsdt", DFSDTSelector)
+
+__all__ = [
+    # Base classes
+    "BaseToolSelector",
+    "SelectorResources",
+    "ToolSelectorProtocol",
+    # Selector implementations
+    "KeywordSelector",
+    "EmbeddingSelector",
+    "HybridSelector",
+    "HybridSelectorConfig",
+    "GorillaSelector",
+    "GorillaSelectorConfig",
+    "DFSDTSelector",
+    "DFSDTSelectorConfig",
+    # Registry
+    "SelectorRegistry",
+    "register_selector",
+    "get_selector",
+    "create_selector_from_config",
+    # Schemas
+    "SelectorConfig",
+    "KeywordSelectorConfig",
+    "EmbeddingSelectorConfig",
+    "TwoStageSelectorConfig",
+    "AdaptiveSelectorConfig",
+    "ToolSelectionQuery",
+    "ToolPrediction",
+    "CONFIG_TYPES",
+    "create_selector_config",
+]

sage_libs/sage_tooluse/base.py

@@ -0,0 +1,203 @@
+"""
+Base classes and protocols for tool selection.
+
+Defines the ToolSelector protocol and abstract base class.
+"""
+
+import logging
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, Optional, Protocol
+
+from .schemas import SelectorConfig, ToolPrediction, ToolSelectionQuery
+
+if TYPE_CHECKING:
+    from sage.common.components.sage_embedding.protocols import EmbeddingProtocol
+
+logger = logging.getLogger(__name__)
+
+
+class SelectorResources:
+    """
+    Container for shared resources needed by selectors.
+
+    Attributes:
+        tools_loader: DataLoader for tool metadata
+        embedding_client: Optional embedding service client (must conform to EmbeddingProtocol)
+        logger: Logger instance
+        cache: Optional cache instance
+    """
+
+    def __init__(
+        self,
+        tools_loader: Any,
+        embedding_client: Optional["EmbeddingProtocol"] = None,
+        logger: Optional[logging.Logger] = None,
+        cache: Optional[Any] = None,
+    ):
+        """
+        Initialize resources.
+
+        Args:
+            tools_loader: Tool metadata loader (from DataManager)
+            embedding_client: Optional embedding service (must have embed(texts, model) interface)
+            logger: Optional logger instance
+            cache: Optional cache instance
+        """
+        self.tools_loader = tools_loader
+        self.embedding_client = embedding_client
+        self.logger = logger or logging.getLogger(__name__)
+        self.cache = cache
+
+
+class ToolSelectorProtocol(Protocol):
+    """Protocol defining the tool selector interface."""
+
+    name: str
+
+    @classmethod
+    def from_config(
+        cls, config: SelectorConfig, resources: SelectorResources
+    ) -> "ToolSelectorProtocol":
+        """
+        Create selector instance from config and resources.
+
+        Args:
+            config: Selector configuration
+            resources: Shared resources
+
+        Returns:
+            Initialized selector instance
+        """
+        ...
+
+    def select(
+        self, query: ToolSelectionQuery, top_k: Optional[int] = None
+    ) -> list[ToolPrediction]:
+        """
+        Select top-k relevant tools for the given query.
+
+        Args:
+            query: Tool selection query
+            top_k: Number of tools to select (overrides config if provided)
+
+        Returns:
+            List of tool predictions, sorted by score (descending)
+        """
+        ...
+
+
+class BaseToolSelector(ABC):
+    """
+    Abstract base class for tool selectors.
+
+    Provides common functionality and enforces the protocol.
+    """
+
+    def __init__(self, config: SelectorConfig, resources: SelectorResources):
+        """
+        Initialize base selector.
+
+        Args:
+            config: Selector configuration
+            resources: Shared resources
+        """
+        self.config = config
+        self.resources = resources
+        self.logger = resources.logger
+        self.name = config.name
+
+        # Statistics
+        self._query_count = 0
+        self._cache_hits = 0
+
+    @classmethod
+    @abstractmethod
+    def from_config(
+        cls, config: SelectorConfig, resources: SelectorResources
+    ) -> "BaseToolSelector":
+        """
+        Create selector from config.
+
+        Args:
+            config: Selector configuration
+            resources: Shared resources
+
+        Returns:
+            Initialized selector instance
+        """
+        return cls(config, resources)
+
+    @abstractmethod
+    def _select_impl(self, query: ToolSelectionQuery, top_k: int) -> list[ToolPrediction]:
+        """
+        Implementation-specific selection logic.
+
+        Args:
+            query: Tool selection query
+            top_k: Number of tools to select
+
+        Returns:
+            List of tool predictions
+        """
+        pass
+
+    def select(
+        self, query: ToolSelectionQuery, top_k: Optional[int] = None
+    ) -> list[ToolPrediction]:
+        """
+        Select top-k relevant tools.
+
+        Args:
+            query: Tool selection query
+            top_k: Number of tools to select (overrides config)
+
+        Returns:
+            List of tool predictions, sorted by score (descending)
+        """
+        k = top_k if top_k is not None else self.config.top_k
+        self._query_count += 1
+
+        try:
+            # Check cache if enabled
+            if self.config.cache_enabled and self.resources.cache:
+                cache_key = self._get_cache_key(query, k)
+                cached = self.resources.cache.get(cache_key)
+                if cached is not None:
+                    self._cache_hits += 1
+                    self.logger.debug(f"Cache hit for query {query.sample_id}")
+                    return cached
+
+            # Perform selection
+            predictions = self._select_impl(query, k)
+
+            # Filter by minimum score
+            if self.config.min_score > 0:
+                predictions = [p for p in predictions if p.score >= self.config.min_score]
+
+            # Sort by score descending
+            predictions = sorted(predictions, key=lambda p: p.score, reverse=True)
+
+            # Limit to top-k
+            predictions = predictions[:k]
+
+            # Cache result if enabled
+            if self.config.cache_enabled and self.resources.cache:
+                self.resources.cache.set(cache_key, predictions)
+
+            return predictions
+
+        except Exception as e:
+            self.logger.error(f"Error in tool selection for {query.sample_id}: {e}")
+            raise
+
+    def _get_cache_key(self, query: ToolSelectionQuery, top_k: int) -> str:
+        """Generate cache key for query."""
+        return f"{self.name}:{query.sample_id}:{top_k}:{hash(query.instruction)}"
+
+    def get_stats(self) -> dict:
+        """Get selector statistics."""
+        return {
+            "query_count": self._query_count,
+            "cache_hits": self._cache_hits,
+            "cache_hit_rate": self._cache_hits / max(self._query_count, 1),
+        }