tool-router-ai 0.3.0

A tool routing AI package using embeddings and FAISS

Capability Tool Router

An AI-driven tool routing library that uses semantic embeddings and FAISS to choose the best tool for a user query.

Features

• Semantic Tool Routing: Routes queries based on tool descriptions and semantic similarity
• Tool Registry: Register and manage tools in a central registry
• Async Embeddings: Pluggable async embedder for custom embedding providers
• FAISS Vector Search: Uses FAISS to build an index over tool descriptions
• Caching: Simple result caching with deterministic keys
• Feedback Tracking: Record success/failure rates for tools

Installation

Install the package in your environment:

pip install tool-router-ai

If you are using the local repository, build and install from source:

python3 setup.py sdist bdist_wheel
pip install dist/tool_router_ai-0.1.0-py3-none-any.whl

Quick Start

import asyncio
from tool_router_ai.models import Tool
from tool_router_ai.registry import ToolRegistry
from tool_router_ai.embedder import Embedder
from tool_router_ai.router import ToolRouter

# Example embedding function that produces dummy embeddings.
# Replace this with your own async embedder, e.g. OpenAI, cohere, etc.
async def dummy_embed(texts):
    return [[0.0] * 1536 for _ in texts]

async def main():
    registry = ToolRegistry()

    registry.register(Tool(
        name="weather",
        description="Get weather information for any city.",
        input_schema={"city": "string"},
        func=lambda city: f"Weather for {city}"
    ))

    registry.register(Tool(
        name="stocks",
        description="Get stock market prices for a symbol.",
        input_schema={"symbol": "string"},
        func=lambda symbol: f"Stock price for {symbol}"
    ))

    embedder = Embedder(dummy_embed)
    router = ToolRouter(registry, embedder)

    await router.build_index()

    selected_tools = await router.route("What is the weather in San Francisco?", top_k=1)
    print(selected_tools[0].name)

asyncio.run(main())

Package Overview

tool_router_ai.models.Tool

A simple dataclass for tool metadata:

• name
• description
• input_schema
• func
• endpoint

tool_router_ai.registry.ToolRegistry

Register and retrieve tools.

Methods:

• register(tool)
• register_many(tools)
• list_tools()
• get(name)

tool_router_ai.embedder.Embedder

Wraps an async embedding function.

Methods:

• embed_batch(texts)
• embed(text)

tool_router_ai.router.ToolRouter

Builds a FAISS index from tool descriptions and routes queries.

Methods:

• build_index()
• route(query, top_k=3)

tool_router_ai.cache.ToolCache

Caches results with deterministic keys based on tool name and params.

Methods:

• get(tool_name, params)
• set(tool_name, params, result)

tool_router_ai.feedback_store.FeedbackStore

Tracks tool successes and failures.

Methods:

• record_success(tool_name)
• record_failure(tool_name)
• score(tool_name)

Usage Notes

• The package does not include a specific OpenAI client implementation.
• Provide your own async embedder function when creating Embedder.
• Tool routing is based on FAISS nearest-neighbor search over the tool description embeddings.

Dependencies

• faiss-cpu
• numpy

Contributing

1. Fork the repository
2. Create a branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request