SAGE Tool Use
Tool retrieval and ranking algorithms for LLM agents
🎯 Overview
sage-agentic-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 Selector: Gorilla-style tool retrieval
📦 Installation
# Basic installation
pip install isage-agentic-tooluse
# Development installation
pip install isage-agentic-tooluse[dev]
🚀 Quick Start
Keyword-based Tool Selection
from sage_libs.sage_agentic_tooluse import KeywordSelector, ToolSelectionQuery
# Create selector
selector = KeywordSelector.from_config(config=keyword_config, resources=resources)
# Select tools for a query
selected = selector.select(
query=ToolSelectionQuery(
sample_id="q1",
instruction="Get current weather in New York",
candidate_tools=["weather_api", "search_api"],
),
top_k=5
)
for tool in selected:
print(f"Tool: {tool.tool_id}, Score: {tool.score}")
Embedding-based Tool Selection
from sage_libs.sage_agentic_tooluse import EmbeddingSelector, ToolSelectionQuery
# Create selector with embedding model
selector = EmbeddingSelector.from_config(config=embedding_config, resources=resources)
# Select tools based on semantic similarity
selected = selector.select(
query=ToolSelectionQuery(
sample_id="q2",
instruction="What's the weather like?",
candidate_tools=["weather_api", "search_api"],
),
top_k=5
)
Hybrid Tool Selection
from sage_libs.sage_agentic_tooluse import HybridSelector, ToolSelectionQuery
# Combine keyword and embedding approaches
selector = HybridSelector.from_config(config=hybrid_config, resources=resources)
selected = selector.select(
query=ToolSelectionQuery(
sample_id="q3",
instruction="Find tools for weather updates",
candidate_tools=["weather_api", "search_api", "calendar_api"],
),
top_k=5,
)
📚 Key Components
Selectors
- KeywordSelector: Fast keyword-based matching
- EmbeddingSelector: Semantic similarity using embeddings
- HybridSelector: Weighted combination of multiple selectors
- DFSDTSelector: Decision tree-based selection
- GorillaSelector: Gorilla-style API-centric retrieval
Base Classes
- BaseToolSelector: Abstract base for all selectors
- SelectorRegistry: Central registry for selector implementations
Schemas
- ToolSelectionQuery: Query payload for selector input
- ToolPrediction: Selection result with score and metadata
- SelectorConfig: Base selector configuration schema
🏗️ Architecture
sage_libs.sage_agentic_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
- Agent Tool Selection: Help agents choose the right tools
- API Discovery: Find relevant APIs for a task
- Function Calling: Select appropriate functions for LLMs
- Tool Recommendation: Recommend tools to users
- 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:
# Standalone usage
from sage_libs.sage_agentic_tooluse import HybridSelector
from sage_libs.sage_agentic_tooluse import create_selector
selector = create_selector({"name": "hybrid", "top_k": 5}, resources)
📖 Documentation
- Repository: https://github.com/intellistream/sage-agentic-tooluse
- SAGE Documentation: https://intellistream.github.io/SAGE-Pub/
- Issues: https://github.com/intellistream/sage-agentic-tooluse/issues
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
📄 License
MIT License - see LICENSE file for details.
🙏 Acknowledgments
Originally part of the 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
Metadata
Release files for isage-agentic-tooluse 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| isage_agentic_tooluse-0.2.0-py2.py3-none-any.whl | Python 2, Python 3 | none | any | Details for isage_agentic_tooluse-0.2.0-py2.py3-none-any.whl |
Release files / isage_agentic_tooluse-0.2.0-py2.py3-none-any.whl
| Download URL | isage_agentic_tooluse-0.2.0-py2.py3-none-any.whl |
|---|---|
| Size | 61.8 kB |
| Tags | Python 2 Python 3 |
|
SHA-256 checksum How to use checksums |
a65c69b0f7115977ed3c6b642a5224fe566932483c8da1c87d4917a82ae6189c
|
|
BLAKE2b-256 checksum How to use checksums |
f23b6b1acef71a87ad79358650a6722734c5d76e038ed920bc0b9148746810b5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.14
|
Security for isage-agentic-tooluse 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.