tool-detector 0.1.0

A lightweight tool detection system for parsing user intents into structured tool calls

Tool Detector

A lightweight Python library for detecting tools and extracting parameters from user text. This library provides a simple way to parse natural language input into structured tool calls with confidence scoring and validation.

Features

• 🎯 Intent Detection: Parse natural language into structured tool calls
• 🔧 Decorator-based Registration: Use @tool_call decorator to register functions as tools
• 📊 Confidence Scoring: Get confidence scores for tool detection
• ✅ Parameter Validation: Automatic parameter extraction and validation with Pydantic
• 🎨 Flexible Matching: Support for multiple trigger phrases and examples
• 📋 Schema Generation: Generate JSON Schema for your tools
• 🚀 Lightweight: Minimal dependencies, fast performance

Installation

pip install tool-detector

Quick Start

Basic Usage

from tool_detector import detect_tool_and_params

# Detect calculator usage
result = detect_tool_and_params("Calculate 5 * 13")
print(result)
# {'tool': 'calculator', 'params': {'expression': '5 * 13'}}

# Detect weather lookup
result = detect_tool_and_params("Weather in London")
print(result)
# {'tool': 'get_weather', 'params': {'city': 'London'}}

Decorator-based Approach

from tool_detector import tool_call, get_tools_from_functions, detect_tool_and_params
from pydantic import BaseModel

class WeatherParams(BaseModel):
    city: str
    country: str = "US"

@tool_call(
    name="get_weather",
    description="Get current weather information for a city",
    trigger_phrases=["weather in", "weather for", "temperature in"],
    examples=[
        "weather in New York",
        "what's the temperature in London?",
        "weather for Tokyo"
    ]
)
def get_weather(city: str, country: str = "US") -> str:
    """Get weather information for a city."""
    return f"Weather in {city}, {country}: Sunny, 25°C"

# Register your functions
tools = get_tools_from_functions([get_weather])

# Detect tools in user input
result = detect_tool_and_params("What's the weather like in Paris?", tools)
print(result)
# DetectionResult(tool='get_weather', params={'city': 'Paris', 'country': 'US'}, confidence=0.85)

Advanced Features

Parameter Validation with Pydantic

from pydantic import BaseModel, Field

class CalculatorParams(BaseModel):
    expression: str = Field(..., description="Mathematical expression to evaluate")
    precision: int = Field(default=2, ge=0, le=10, description="Decimal precision")

@tool_call(
    name="calculator",
    description="Evaluate mathematical expressions",
    trigger_phrases=["calculate", "compute", "what is"],
    examples=["calculate 2 + 2", "what is 10 * 5", "compute 100 / 4"]
)
def calculator(expression: str, precision: int = 2) -> float:
    """Evaluate a mathematical expression."""
    return round(eval(expression), precision)

Schema Generation

from tool_detector import get_openapi_schema_for_tools

# Generate JSON Schema for your tools
schema = get_openapi_schema_for_tools(tools)
print(schema)

API Reference

Core Functions

• detect_tool_and_params(text: str, tools: List[Tool] = None) -> DetectionResult
• get_tools_from_functions(functions: List[Callable]) -> List[Tool]
• get_openapi_schema_for_tools(tools: List[Tool]) -> Dict

Decorators

• @tool_call(name: str, description: str, trigger_phrases: List[str], examples: List[str])

Data Models

• Tool: Represents a tool with metadata and parameters
• ToolParameter: Represents a tool parameter with type and validation
• DetectionResult: Result of tool detection with confidence score
• ParameterType: Enum of supported parameter types

Examples

Check out the examples directory for more comprehensive usage examples:

• Basic Usage
• Decorator Examples
• Advanced Features

Development

Setup

1. Clone the repository:

   git clone https://github.com/ameenalam/tool-detector.git
   cd tool-detector
   

2. Install development dependencies:

   pip install -e ".[dev]"
   

3. Install pre-commit hooks:

   pre-commit install
   

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=tool_detector --cov-report=html

# Run specific test file
pytest tests/test_detector.py

Code Quality

# Format code
black tool_detector tests examples

# Sort imports
isort tool_detector tests examples

# Type checking
mypy tool_detector

# Linting
flake8 tool_detector tests examples

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Documentation

For detailed documentation, visit tool-detector.readthedocs.io.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for a list of changes and version history.