tool-useful

⚡ A blazing-fast, type-safe, secure function calling and tool orchestration framework for Rust AI applications.

Why tool-useful?

Built from the ground up to be faster, safer, and more powerful than Python alternatives.

🚀 Performance Features

• ⚡ True Parallel Execution - No GIL limitations, use all your CPU cores
• 🔄 Advanced Retry Policies - Exponential backoff with jitter, circuit breakers
• 📊 Built-in Metrics - Track success rates, latencies, throughput
• 🎯 Zero-Cost Abstractions - Compile-time optimizations, no runtime overhead
• 📦 Batch Processing - Execute multiple tools concurrently
• 🌊 Streaming Support - Handle large outputs efficiently

🔒 Security Features

• 🛡️ Permission System - Fine-grained network & filesystem access control
• 📏 Resource Limits - Memory, CPU time, and execution limits
• 🚦 Rate Limiting - Token bucket algorithm for API protection
• 🔐 Sandboxing Support - Isolate tool execution
• ⏱️ Timeout Management - Prevent runaway executions

🎯 Type Safety

• ✅ Compile-Time Verification - Catch errors before runtime
• 🏗️ Strong Types - Full type inference and checking
• 🔍 Automatic Schema Generation - From Rust types to LLM schemas

🌐 Multi-Provider Support

• OpenAI function calling format
• Anthropic tool format
• Google Gemini function format
• Generic JSON schema

Quick Start

[dependencies]
tool-useful = "0.1"
tokio = { version = "1", features = ["full"] }
async-trait = "0.1"
serde = { version = "1", features = ["derive"] }

Simple Example

use tool_useful::prelude::*;

#[derive(Debug, Clone, Serialize, Deserialize)]
struct Calculator { a: f64, b: f64 }

impl Tool for Calculator {
    fn metadata(&self) -> ToolMetadata {
        ToolMetadata::new("add", "Add two numbers")
    }

    fn schema(&self) -> ToolSchema {
        ToolSchema::new("add", "Add two numbers")
            .with_parameter(
                ParameterSchema::new("a", "number")
                    .with_description("First number")
                    .required()
            )
            .with_parameter(
                ParameterSchema::new("b", "number")
                    .with_description("Second number")
                    .required()
            )
    }

    fn name(&self) -> &str { "add" }
}

impl FromToolCall for Calculator {
    fn from_tool_call(call: &ToolCall) -> ToolResult<Self> {
        serde_json::from_value(call.arguments.clone())
            .map_err(|e| ToolError::invalid_arguments(e.to_string()))
    }
}

#[async_trait]
impl ToolExecutor for Calculator {
    type Output = f64;
    type Error = std::convert::Infallible;

    async fn execute(&self, _ctx: &ExecutionContext) -> Result<f64, Self::Error> {
        Ok(self.a + self.b)
    }
}

#[tokio::main]
async fn main() {
    let tool = Calculator { a: 5.0, b: 3.0 };
    let executor = Executor::new();
    let result = executor.execute(&tool).await.unwrap();
    println!("Result: {}", result); // 8.0
}

Advanced Features

1. Retry with Exponential Backoff

let executor = Executor::builder()
    .retry_policy(
        RetryPolicy::exponential(3)
            .with_backoff(Duration::from_millis(100))
            .with_max_delay(Duration::from_secs(5))
            .with_jitter(true)  // Add randomness to prevent thundering herd
    )
    .timeout(Duration::from_secs(30))
    .build();

2. Circuit Breaker

Prevent cascading failures:

let executor = Executor::builder()
    .circuit_breaker(5, Duration::from_secs(10))  // Open after 5 failures, retry after 10s
    .build();

3. Parallel Batch Execution

let tools = vec![tool1, tool2, tool3];
let results = executor.execute_batch(tools).await;
// Executes all tools concurrently with configurable limits

4. Metrics & Monitoring

let executor = Executor::new();
executor.execute(&tool).await?;

println!("Success rate: {:.2}%", executor.metrics().success_rate());
println!("Avg latency: {:.2}ms", executor.metrics().avg_duration_ms());

5. Security & Permissions

let permissions = Permissions::builder()
    .allow_network_hosts(vec!["api.openai.com".to_string()])
    .readonly_filesystem(vec!["/tmp".into()])
    .max_memory(100_000_000)  // 100MB
    .max_cpu_time(Duration::from_secs(30))
    .build();

// Check permissions
permissions.check_network_access("api.openai.com")?;
permissions.check_file_access(Path::new("/tmp/data.json"))?;

6. Rate Limiting

let limiter = RateLimiter::per_second(100);

limiter.acquire().await?;  // Blocks if rate limit exceeded
// Make API call

7. Resource Tracking

let tracker = ResourceTracker::new(permissions);

tracker.track_memory_allocation(1024)?;  // Fails if exceeds limit
println!("Memory used: {}", tracker.memory_usage());
println!("Elapsed: {:?}", tracker.elapsed_time());

8. Streaming Tools

For tools that produce large outputs:

#[async_trait]
impl StreamingToolExecutor for LogAnalyzer {
    type Item = LogEntry;
    type Error = std::io::Error;

    fn execute_stream(&self, ctx: &ExecutionContext) 
        -> Pin<Box<dyn Stream<Item = Result<Self::Item, Self::Error>> + Send + '_>> 
    {
        // Return a stream of results
    }
}

9. Tool Registry

let registry = ToolRegistry::new();
registry.register(WeatherTool { location: "".into() })?;
registry.register(TimeTool { timezone: "".into() })?;

// Discovery
let weather_tools = registry.find_by_tag("weather");
let data_tools = registry.find_by_category("data");

// Export schemas
let openai_schemas = registry.export_schemas(Provider::OpenAI);
let anthropic_schemas = registry.export_schemas(Provider::Anthropic);

Performance Benchmarks

Benchmarks run on AMD Ryzen 9 5900X, measuring tool execution overhead

Comparison with Python

Examples

Run the examples:

cargo run --example simple      # Basic calculator
cargo run --example registry    # Tool registry & discovery
cargo run --example advanced    # All advanced features

Architecture

• Single Crate - No complex workspace, just tool-useful
• Modular - Use only what you need
• Extensible - Easy to add custom tools
• Production Ready - Battle-tested patterns

Safety & Security

• ✅ Memory-safe by design (no segfaults, no UAF)
• ✅ Thread-safe with compile-time verification
• ✅ Resource limits enforced
• ✅ Permission system for access control
• ✅ No unsafe code in core paths
• ✅ Comprehensive error handling

Roadmap

• Derive macro for automatic Tool implementation
• WebAssembly support for sandboxing
• Distributed execution over gRPC
• MCP (Model Context Protocol) integration
• Persistent tool result caching
• OpenTelemetry integration

Contributing

Contributions welcome! This is a high-performance, security-focused project.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

Built with 🦀 Rust for maximum performance and safety.