Metadata-Version: 2.4
Name: tool-router-ai
Version: 0.3.0
Summary: A tool routing AI package using embeddings and FAISS
Home-page: https://github.com/alturusatish/tool-router-ai
Author: Satish Alturu
Author-email: alturusatish@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: faiss-cpu
Requires-Dist: numpy
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

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

```bash
pip install tool-router-ai
```

> If you are using the local repository, build and install from source:
> ```bash
> python3 setup.py sdist bdist_wheel
> pip install dist/tool_router_ai-0.1.0-py3-none-any.whl
> ```

## Quick Start

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

