semantic-tool-router 0.1.0__tar.gz

semantic_tool_router-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Semantic Tool Router Contributors
+
+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.
+

semantic_tool_router-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: semantic-tool-router
+Version: 0.1.0
+Summary: Runtime semantic discovery for agent tools.
+Author: Semantic Tool Router Contributors
+License: MIT
+Keywords: agents,tools,retrieval,mcp,semantic-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: sentence-transformers
+Requires-Dist: sentence-transformers>=2.2.0; extra == "sentence-transformers"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Dynamic: license-file
+
+# Semantic Tool Router
+
+[![PyPI Version](https://img.shields.io/badge/pypi-v0.1.0--alpha-blue)](https://pypi.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Python Support](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](pyproject.toml)
+[![CI Build](https://img.shields.io/badge/build-passing-brightgreen)](.github/workflows/ci.yml)
+
+> **Dynamic runtime tool discovery and retrieval-augmented routing for AI agents.**
+
+Semantic Tool Router is a dependency-light library designed to manage the "Many-Tool" problem in LLM and Agentic workflows. Instead of exposing every available tool or Model Context Protocol (MCP) server schema to a model context window (which increases costs and degrades accuracy), it embeds tools based on their descriptions and dynamically retrieves a focused candidate set ($top-k$) for the current task.
+
+---
+
+## How It Works
+
+```mermaid
+graph LR
+    Query[Task Query] --> Router(Tool Router)
+    Registry[Tool Registry] --> Router
+    Router --> Filters{Filters}
+    Filters --> LLM[LLM Context]
+```
+
+1. **Tool Indexing:** Tool descriptions, schemas, tags, examples, and permissions are compiled into search strings and vectorized.
+2. **Semantic Matching:** The user query is embedded and compared against the indexed tools using cosine similarity.
+3. **Metadata Filtering:** Results are filtered by permission layers (e.g. read-only vs destructive commands) or specific tags.
+4. **Context Injection:** Only the top $k$ relevant tool schemas are injected into the LLM system prompt, preserving context tokens.
+
+---
+
+## Features
+
+*   ⚡ **Zero-Dependency Hashing Baseline:** Comes with a local token-hashing vectorizer (`HashingEmbeddingProvider`) that runs instantly without external APIs or PyTorch downloads.
+*   🔌 **First-Class MCP Client:** Connects to live Stdio MCP servers, imports schemas automatically, and executes selected tools under expectation guards.
+*   🏷️ **Metadata-Aware Filtering:** Apply rigid tag filters or restrict tools based on security permissions (`read`, `write`, `execute`, `destructive`, `network`).
+*   📈 **Evaluation Suite:** Measure retrieval metrics (`hit_rate@k`, `top_1_accuracy`, `MRR`, `context_tokens_saved`) against reproducible benchmark files.
+*   🧠 **Swappable Embedders:** Easily swap the hashing provider for local Hugging Face `SentenceTransformers` or cloud APIs (`OpenAI`).
+
+---
+
+## Installation
+
+Install the core package (includes standard hashing retriever):
+
+```bash
+pip install -e .
+```
+
+For advanced semantic embeddings, install the optional package extras:
+
+```bash
+# To run local models via SentenceTransformers
+pip install -e .[sentence-transformers]
+
+# To use OpenAI's hosted embedding models
+pip install -e .[openai]
+```
+
+---
+
+## Quick Start
+
+### 1. Basic Tool Discovery
+Query a local JSON registry of tool specs:
+
+```bash
+python -m semantic_tool_router discover "read the project README file" --registry examples/tools.json
+```
+
+Or choose a specific embedding model:
+
+```bash
+python -m semantic_tool_router discover "generate a mock logo" \
+  --registry examples/tools.json \
+  --embedder sentence-transformers \
+  --embedding-model all-MiniLM-L6-v2
+```
+
+### 2. Live MCP Routing
+Connect to a live filesystem MCP server, dynamically retrieve the top-3 candidate tools matching your task, and execute the selected tool with safety parameters:
+
+```powershell
+python -m semantic_tool_router mcp-discover \
+  "read the first lines of the project README" \
+  --top-k 3 \
+  --allow-permission read \
+  --expect-tool read_text_file \
+  --call-argument "path=README.md" \
+  --call-argument "head=8" \
+  --server npx -y @modelcontextprotocol/server-filesystem .
+```
+
+---
+
+## Integrations
+
+Use the router as a preprocessing step inside standard orchestrator loops to save prompt tokens:
+
+*   **LangChain Agent Integration:** See the [langchain_integration.py](examples/langchain_integration.py) template.
+*   **LlamaIndex Agent Integration:** See the [llamaindex_integration.py](examples/llamaindex_integration.py) template.
+
+---
+
+## Benchmarking & Evaluation
+
+Evaluate your router configuration on fixture datasets:
+
+```bash
+python -m semantic_tool_router benchmark \
+  --registry examples/tools.json \
+  --tasks benchmarks/tasks.json \
+  --top-k 3
+```
+
+To run the reproducible baseline benchmark suite across four official live MCP reference servers (Filesystem, Memory, Sequential Thinking, and Everything):
+
+```bash
+python -m semantic_tool_router mcp-benchmark \
+  --suite benchmarks/live_mcp_suite.json \
+  --workspace . \
+  --markdown-output benchmarks/results/live_mcp_baseline.md
+```
+
+---
+
+## Testing
+
+Run unit tests locally across mock registry and MCP environments:
+
+```bash
+python -m unittest discover -s tests
+```
+
+---
+
+## Contributing & Development
+
+Contributions are welcome! Please run tests and benchmarking commands to verify that metrics remain high before submitting pull requests.
+
+1. Fork the repo and clone locally.
+2. Setup tests: `python -m pip install -e .[sentence-transformers,openai]`
+3. Ensure CI checks pass: `python -m unittest discover -s tests`
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

semantic_tool_router-0.1.0/README.md

@@ -0,0 +1,148 @@
+# Semantic Tool Router
+
+[![PyPI Version](https://img.shields.io/badge/pypi-v0.1.0--alpha-blue)](https://pypi.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Python Support](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](pyproject.toml)
+[![CI Build](https://img.shields.io/badge/build-passing-brightgreen)](.github/workflows/ci.yml)
+
+> **Dynamic runtime tool discovery and retrieval-augmented routing for AI agents.**
+
+Semantic Tool Router is a dependency-light library designed to manage the "Many-Tool" problem in LLM and Agentic workflows. Instead of exposing every available tool or Model Context Protocol (MCP) server schema to a model context window (which increases costs and degrades accuracy), it embeds tools based on their descriptions and dynamically retrieves a focused candidate set ($top-k$) for the current task.
+
+---
+
+## How It Works
+
+```mermaid
+graph LR
+    Query[Task Query] --> Router(Tool Router)
+    Registry[Tool Registry] --> Router
+    Router --> Filters{Filters}
+    Filters --> LLM[LLM Context]
+```
+
+1. **Tool Indexing:** Tool descriptions, schemas, tags, examples, and permissions are compiled into search strings and vectorized.
+2. **Semantic Matching:** The user query is embedded and compared against the indexed tools using cosine similarity.
+3. **Metadata Filtering:** Results are filtered by permission layers (e.g. read-only vs destructive commands) or specific tags.
+4. **Context Injection:** Only the top $k$ relevant tool schemas are injected into the LLM system prompt, preserving context tokens.
+
+---
+
+## Features
+
+*   ⚡ **Zero-Dependency Hashing Baseline:** Comes with a local token-hashing vectorizer (`HashingEmbeddingProvider`) that runs instantly without external APIs or PyTorch downloads.
+*   🔌 **First-Class MCP Client:** Connects to live Stdio MCP servers, imports schemas automatically, and executes selected tools under expectation guards.
+*   🏷️ **Metadata-Aware Filtering:** Apply rigid tag filters or restrict tools based on security permissions (`read`, `write`, `execute`, `destructive`, `network`).
+*   📈 **Evaluation Suite:** Measure retrieval metrics (`hit_rate@k`, `top_1_accuracy`, `MRR`, `context_tokens_saved`) against reproducible benchmark files.
+*   🧠 **Swappable Embedders:** Easily swap the hashing provider for local Hugging Face `SentenceTransformers` or cloud APIs (`OpenAI`).
+
+---
+
+## Installation
+
+Install the core package (includes standard hashing retriever):
+
+```bash
+pip install -e .
+```
+
+For advanced semantic embeddings, install the optional package extras:
+
+```bash
+# To run local models via SentenceTransformers
+pip install -e .[sentence-transformers]
+
+# To use OpenAI's hosted embedding models
+pip install -e .[openai]
+```
+
+---
+
+## Quick Start
+
+### 1. Basic Tool Discovery
+Query a local JSON registry of tool specs:
+
+```bash
+python -m semantic_tool_router discover "read the project README file" --registry examples/tools.json
+```
+
+Or choose a specific embedding model:
+
+```bash
+python -m semantic_tool_router discover "generate a mock logo" \
+  --registry examples/tools.json \
+  --embedder sentence-transformers \
+  --embedding-model all-MiniLM-L6-v2
+```
+
+### 2. Live MCP Routing
+Connect to a live filesystem MCP server, dynamically retrieve the top-3 candidate tools matching your task, and execute the selected tool with safety parameters:
+
+```powershell
+python -m semantic_tool_router mcp-discover \
+  "read the first lines of the project README" \
+  --top-k 3 \
+  --allow-permission read \
+  --expect-tool read_text_file \
+  --call-argument "path=README.md" \
+  --call-argument "head=8" \
+  --server npx -y @modelcontextprotocol/server-filesystem .
+```
+
+---
+
+## Integrations
+
+Use the router as a preprocessing step inside standard orchestrator loops to save prompt tokens:
+
+*   **LangChain Agent Integration:** See the [langchain_integration.py](examples/langchain_integration.py) template.
+*   **LlamaIndex Agent Integration:** See the [llamaindex_integration.py](examples/llamaindex_integration.py) template.
+
+---
+
+## Benchmarking & Evaluation
+
+Evaluate your router configuration on fixture datasets:
+
+```bash
+python -m semantic_tool_router benchmark \
+  --registry examples/tools.json \
+  --tasks benchmarks/tasks.json \
+  --top-k 3
+```
+
+To run the reproducible baseline benchmark suite across four official live MCP reference servers (Filesystem, Memory, Sequential Thinking, and Everything):
+
+```bash
+python -m semantic_tool_router mcp-benchmark \
+  --suite benchmarks/live_mcp_suite.json \
+  --workspace . \
+  --markdown-output benchmarks/results/live_mcp_baseline.md
+```
+
+---
+
+## Testing
+
+Run unit tests locally across mock registry and MCP environments:
+
+```bash
+python -m unittest discover -s tests
+```
+
+---
+
+## Contributing & Development
+
+Contributions are welcome! Please run tests and benchmarking commands to verify that metrics remain high before submitting pull requests.
+
+1. Fork the repo and clone locally.
+2. Setup tests: `python -m pip install -e .[sentence-transformers,openai]`
+3. Ensure CI checks pass: `python -m unittest discover -s tests`
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

semantic_tool_router-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "semantic-tool-router"
+version = "0.1.0"
+description = "Runtime semantic discovery for agent tools."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Semantic Tool Router Contributors" }]
+license = { text = "MIT" }
+keywords = ["agents", "tools", "retrieval", "mcp", "semantic-search"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+
+[project.optional-dependencies]
+sentence-transformers = ["sentence-transformers>=2.2.0"]
+openai = ["openai>=1.0.0"]
+
+[project.scripts]
+semantic-tool-router = "semantic_tool_router.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+

semantic_tool_router-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

semantic_tool_router-0.1.0/src/semantic_tool_router/__init__.py

@@ -0,0 +1,31 @@
+from semantic_tool_router.embeddings import (
+    HashingEmbeddingProvider,
+    OpenAIEmbeddingProvider,
+    SentenceTransformerEmbeddingProvider,
+)
+from semantic_tool_router.evaluation import (
+    BenchmarkReport,
+    BenchmarkTask,
+    TaskEvaluation,
+    evaluate,
+)
+from semantic_tool_router.models import DiscoveryResult, ToolSpec
+from semantic_tool_router.mcp import McpServerSnapshot, StdioMcpClient
+from semantic_tool_router.registry import ToolRegistry
+from semantic_tool_router.router import ToolRouter
+
+__all__ = [
+    "BenchmarkReport",
+    "BenchmarkTask",
+    "DiscoveryResult",
+    "HashingEmbeddingProvider",
+    "McpServerSnapshot",
+    "OpenAIEmbeddingProvider",
+    "SentenceTransformerEmbeddingProvider",
+    "StdioMcpClient",
+    "TaskEvaluation",
+    "ToolRegistry",
+    "ToolRouter",
+    "ToolSpec",
+    "evaluate",
+]

semantic_tool_router-0.1.0/src/semantic_tool_router/__main__.py

@@ -0,0 +1,5 @@
+from semantic_tool_router.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+