Struct ToolBuilder 

pub struct ToolBuilder { /* private fields */ }

A builder for creating tools with a simplified API.

Example

use helios_engine::ToolBuilder;
use serde_json::Value;

async fn my_calculator(args: Value) -> helios_engine::Result<helios_engine::ToolResult> {
    let a = args.get("a").and_then(|v| v.as_f64()).unwrap_or(0.0);
    let b = args.get("b").and_then(|v| v.as_f64()).unwrap_or(0.0);
    Ok(helios_engine::ToolResult::success((a + b).to_string()))
}

let tool = ToolBuilder::new("add_numbers")
    .description("Add two numbers together")
    .parameter("a", "number", "First number", true)
    .parameter("b", "number", "Second number", true)
    .function(my_calculator)
    .build();

Implementations

impl ToolBuilder

pub fn new(name: impl Into<String>) -> Self

Creates a new ToolBuilder with the given name.

Arguments

• name - The name of the tool (e.g., “calculator”, “weather_api”)

Examples found in repository

examples/tool_builder_demo.rs (line 60)

async fn main() -> helios_engine::Result<()> {
    let config = Config::from_file("config.toml")?;

    println!("=== Tool Builder Demo ===\n");
    println!("Creating tools with the ultra-simple ftool API!");
    println!("The system automatically infers types from your function signature!\n");

    // Example 1: Integer parameters (i32, i32) - types inferred automatically!
    let add_tool = ToolBuilder::new("add")
        .description("Add two integers")
        .parameters("x:i32:First number, y:i32:Second number")
        .ftool(adder) // Automatically knows these are i32!
        .build();

    // Example 2: Integer multiplication (i32, i32)
    let multiply_tool = ToolBuilder::new("multiply")
        .description("Multiply two integers")
        .parameters("a:i32:First number, b:i32:Second number")
        .ftool(multiplier)
        .build();

    // Example 3: Float parameters (f64, f64) - automatically inferred!
    let area_tool = ToolBuilder::new("calculate_area")
        .description("Calculate the area of a rectangle")
        .parameters("length:f64:Length in meters, width:f64:Width in meters")
        .ftool(calculate_area) // Same ftool method, but knows these are f64!
        .build();

    // Example 4: Three float parameters (f64, f64, f64)
    let volume_tool = ToolBuilder::new("calculate_volume")
        .description("Calculate the volume of a box")
        .parameters(
            "width:f64:Width in meters, height:f64:Height in meters, depth:f64:Depth in meters",
        )
        .ftool3(calculate_volume)
        .build();

    // Example 5: BMI calculator with floats
    let bmi_tool = ToolBuilder::new("calculate_bmi")
        .description("Calculate Body Mass Index")
        .parameters("weight_kg:f64:Weight in kilograms, height_m:f64:Height in meters")
        .ftool(calculate_bmi)
        .build();

    // Example 6: Mixed types - String and bool!
    let greet_tool = ToolBuilder::new("greet")
        .description("Greet someone by name")
        .parameters("name:string:Person's name, formal:bool:Use formal greeting")
        .ftool(greet) // Automatically knows: String, bool!
        .build();

    // Example 7: Mixed numeric types - f64 and i32
    let discount_tool = ToolBuilder::new("calculate_discount")
        .description("Calculate discount on a price")
        .parameters("price:f64:Original price, percent:i32:Discount percentage")
        .ftool(calculate_discount) // Automatically knows: f64, i32!
        .build();

    // Create an agent with all the tools
    let mut agent = Agent::builder("ToolDemo")
        .config(config)
        .system_prompt(
            "You are a helpful assistant with access to various calculation and utility tools. \
             Use them to help answer questions accurately.",
        )
        .tool(add_tool)
        .tool(multiply_tool)
        .tool(area_tool)
        .tool(volume_tool)
        .tool(bmi_tool)
        .tool(greet_tool)
        .tool(discount_tool)
        .build()
        .await?;

    println!("Created 7 tools with minimal code!\n");
    println!("All types automatically inferred from function signatures!\n");
    println!("===========================================\n");

    // Test the tools
    println!("Test 1: Integer addition");
    let response = agent.chat("What is 42 plus 17?").await?;
    println!("Agent: {}\n", response);

    println!("Test 2: Integer multiplication");
    let response = agent.chat("What is 12 times 8?").await?;
    println!("Agent: {}\n", response);

    println!("Test 3: Calculate area");
    let response = agent
        .chat("What is the area of a rectangle that is 5 meters long and 3 meters wide?")
        .await?;
    println!("Agent: {}\n", response);

    println!("Test 4: Calculate volume");
    let response = agent
        .chat("What's the volume of a box that is 2m wide, 3m high, and 1.5m deep?")
        .await?;
    println!("Agent: {}\n", response);

    println!("Test 5: Calculate BMI");
    let response = agent
        .chat("Calculate BMI for someone weighing 70 kg and 1.75 meters tall")
        .await?;
    println!("Agent: {}\n", response);

    println!("Test 6: Greeting with String and bool");
    let response = agent.chat("Greet Bob in a casual way").await?;
    println!("Agent: {}\n", response);

    println!("Test 7: Discount calculation with mixed types");
    let response = agent
        .chat("What's the discount on a $100 item with 20% off?")
        .await?;
    println!("Agent: {}\n", response);

    println!("\n===========================================");
    println!("✨ That's how easy it is to create tools!");
    println!("   Just define your function and the system automatically:");
    println!("   • Infers all parameter types from your function signature");
    println!("   • Extracts values from JSON in the right order");
    println!("   • Handles i32, i64, u32, u64, f32, f64, bool, String");
    println!(
        "   • Works with .ftool() for 2 params, .ftool3() for 3 params, .ftool4() for 4 params"
    );

    Ok(())
}

pub fn from_fn<F>( func_name: impl Into<String>, description: impl Into<String>, params: impl Into<String>, func: F, ) -> Self

where F: Fn(Value) -> Result<ToolResult> + Send + Sync + 'static,

Creates a ToolBuilder from an existing function, automatically deriving the tool name.

This method extracts the function name and uses it as the tool name, making it extremely simple to convert existing functions into tools without redefining anything.

Arguments

• func_name - The name to use for the tool (typically the function name)
• description - A description of what the tool does
• params - Parameter definitions in the format “name:type:description, …”
• func - The function to execute

Example

use helios_engine::{ToolBuilder, ToolResult};

fn calculate_area(length: f64, width: f64) -> f64 {
    length * width
}

let tool = ToolBuilder::from_fn(
    "calculate_area",
    "Calculate the area of a rectangle",
    "length:f64:The length of the rectangle, width:f64:The width of the rectangle",
    |args| {
        let length = args.get("length").and_then(|v| v.as_f64()).unwrap_or(0.0);
        let width = args.get("width").and_then(|v| v.as_f64()).unwrap_or(0.0);
        let area = calculate_area(length, width);
        Ok(ToolResult::success(format!("The area is {} square units", area)))
    }
).build();

pub fn simple( name: impl Into<String>, description: impl Into<String>, params: impl Into<String>, ) -> Self

Creates a tool from a simple function with automatic parameter extraction.

This is the SIMPLEST API - just provide name, description, parameters, and the function. The function will be automatically wrapped and its parameters extracted from JSON.

Example with inline function

use helios_engine::ToolBuilder;

fn adder(x: i32, y: i32) -> i32 {
    x + y
}

let tool = ToolBuilder::simple(
    "add_numbers",
    "Add two integers together",
    "x:i32:First number, y:i32:Second number"
).build();

pub fn from_async_fn<F, Fut>( func_name: impl Into<String>, description: impl Into<String>, params: impl Into<String>, func: F, ) -> Self

where F: Fn(Value) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<ToolResult>> + Send + 'static,

Creates a ToolBuilder from an existing async function, automatically deriving the tool name.

This is the async version of from_fn, for functions that need to perform async operations.

Arguments

• func_name - The name to use for the tool (typically the function name)
• description - A description of what the tool does
• params - Parameter definitions in the format “name:type:description, …”
• func - The async function to execute

Example

use helios_engine::{ToolBuilder, ToolResult};

async fn fetch_temperature(city: &str) -> Result<f64, String> {
    // Simulate API call
    Ok(20.5)
}

let tool = ToolBuilder::from_async_fn(
    "fetch_temperature",
    "Get the temperature for a city",
    "city:string:The name of the city",
    |args| async move {
        let city = args.get("city").and_then(|v| v.as_str()).unwrap_or("");
        let temp = fetch_temperature(city).await.unwrap_or(0.0);
        Ok(ToolResult::success(format!("Temperature: {}°C", temp)))
    }
).build();

pub fn description(self, description: impl Into<String>) -> Self

Sets the description of the tool.

Arguments

• description - A clear description of what the tool does

Examples found in repository

examples/tool_builder_demo.rs (line 61)

async fn main() -> helios_engine::Result<()> {
    let config = Config::from_file("config.toml")?;

    println!("=== Tool Builder Demo ===\n");
    println!("Creating tools with the ultra-simple ftool API!");
    println!("The system automatically infers types from your function signature!\n");

    // Example 1: Integer parameters (i32, i32) - types inferred automatically!
    let add_tool = ToolBuilder::new("add")
        .description("Add two integers")
        .parameters("x:i32:First number, y:i32:Second number")
        .ftool(adder) // Automatically knows these are i32!
        .build();

    // Example 2: Integer multiplication (i32, i32)
    let multiply_tool = ToolBuilder::new("multiply")
        .description("Multiply two integers")
        .parameters("a:i32:First number, b:i32:Second number")
        .ftool(multiplier)
        .build();

    // Example 3: Float parameters (f64, f64) - automatically inferred!
    let area_tool = ToolBuilder::new("calculate_area")
        .description("Calculate the area of a rectangle")
        .parameters("length:f64:Length in meters, width:f64:Width in meters")
        .ftool(calculate_area) // Same ftool method, but knows these are f64!
        .build();

    // Example 4: Three float parameters (f64, f64, f64)
    let volume_tool = ToolBuilder::new("calculate_volume")
        .description("Calculate the volume of a box")
        .parameters(
            "width:f64:Width in meters, height:f64:Height in meters, depth:f64:Depth in meters",
        )
        .ftool3(calculate_volume)
        .build();

    // Example 5: BMI calculator with floats
    let bmi_tool = ToolBuilder::new("calculate_bmi")
        .description("Calculate Body Mass Index")
        .parameters("weight_kg:f64:Weight in kilograms, height_m:f64:Height in meters")
        .ftool(calculate_bmi)
        .build();

    // Example 6: Mixed types - String and bool!
    let greet_tool = ToolBuilder::new("greet")
        .description("Greet someone by name")
        .parameters("name:string:Person's name, formal:bool:Use formal greeting")
        .ftool(greet) // Automatically knows: String, bool!
        .build();

    // Example 7: Mixed numeric types - f64 and i32
    let discount_tool = ToolBuilder::new("calculate_discount")
        .description("Calculate discount on a price")
        .parameters("price:f64:Original price, percent:i32:Discount percentage")
        .ftool(calculate_discount) // Automatically knows: f64, i32!
        .build();

    // Create an agent with all the tools
    let mut agent = Agent::builder("ToolDemo")
        .config(config)
        .system_prompt(
            "You are a helpful assistant with access to various calculation and utility tools. \
             Use them to help answer questions accurately.",
        )
        .tool(add_tool)
        .tool(multiply_tool)
        .tool(area_tool)
        .tool(volume_tool)
        .tool(bmi_tool)
        .tool(greet_tool)
        .tool(discount_tool)
        .build()
        .await?;

    println!("Created 7 tools with minimal code!\n");
    println!("All types automatically inferred from function signatures!\n");
    println!("===========================================\n");

    // Test the tools
    println!("Test 1: Integer addition");
    let response = agent.chat("What is 42 plus 17?").await?;
    println!("Agent: {}\n", response);

    println!("Test 2: Integer multiplication");
    let response = agent.chat("What is 12 times 8?").await?;
    println!("Agent: {}\n", response);

    println!("Test 3: Calculate area");
    let response = agent
        .chat("What is the area of a rectangle that is 5 meters long and 3 meters wide?")
        .await?;
    println!("Agent: {}\n", response);

    println!("Test 4: Calculate volume");
    let response = agent
        .chat("What's the volume of a box that is 2m wide, 3m high, and 1.5m deep?")
        .await?;
    println!("Agent: {}\n", response);

    println!("Test 5: Calculate BMI");
    let response = agent
        .chat("Calculate BMI for someone weighing 70 kg and 1.75 meters tall")
        .await?;
    println!("Agent: {}\n", response);

    println!("Test 6: Greeting with String and bool");
    let response = agent.chat("Greet Bob in a casual way").await?;
    println!("Agent: {}\n", response);

    println!("Test 7: Discount calculation with mixed types");
    let response = agent
        .chat("What's the discount on a $100 item with 20% off?")
        .await?;
    println!("Agent: {}\n", response);

    println!("\n===========================================");
    println!("✨ That's how easy it is to create tools!");
    println!("   Just define your function and the system automatically:");
    println!("   • Infers all parameter types from your function signature");
    println!("   • Extracts values from JSON in the right order");
    println!("   • Handles i32, i64, u32, u64, f32, f64, bool, String");
    println!(
        "   • Works with .ftool() for 2 params, .ftool3() for 3 params, .ftool4() for 4 params"
    );

    Ok(())
}

pub fn parameter( self, name: impl Into<String>, param_type: impl Into<String>, description: impl Into<String>, required: bool, ) -> Self

Adds a parameter to the tool.

Arguments

• name - The parameter name
• param_type - The parameter type (e.g., “string”, “number”, “boolean”, “object”, “array”)
• description - A description of the parameter
• required - Whether the parameter is required

pub fn optional_parameter( self, name: impl Into<String>, param_type: impl Into<String>, description: impl Into<String>, ) -> Self

Adds an optional parameter to the tool (convenience method).

Arguments

• name - The parameter name
• param_type - The parameter type
• description - A description of the parameter

pub fn required_parameter( self, name: impl Into<String>, param_type: impl Into<String>, description: impl Into<String>, ) -> Self

Adds a required parameter to the tool (convenience method).

Arguments

• name - The parameter name
• param_type - The parameter type
• description - A description of the parameter

pub fn parameters(self, params: impl Into<String>) -> Self

Adds multiple parameters at once using a compact format.

This method allows you to define all parameters in a single string, making it much easier and more concise than calling required_parameter multiple times.

Format

The format is: "param_name:type:description, param_name2:type2:description2, ..."

Supported types:

• i32, i64, u32, u64, isize, usize -> mapped to “integer”
• f32, f64, number -> mapped to “number”
• str, String, string -> mapped to “string”
• bool, boolean -> mapped to “boolean”
• object -> mapped to “object”
• array -> mapped to “array”

Arguments

• params - A comma-separated string of parameters in the format “name:type:description”

Example

use helios_engine::ToolBuilder;

let tool = ToolBuilder::new("calculate_volume")
    .description("Calculate the volume of a box")
    .parameters("width:i32:The width of the box, height:i32:The height of the box, depth:f64:The depth of the box")
    .sync_function(|args| {
        // function implementation
    })
    .build();

Examples found in repository

examples/tool_builder_demo.rs (line 62)

async fn main() -> helios_engine::Result<()> {
    let config = Config::from_file("config.toml")?;

    println!("=== Tool Builder Demo ===\n");
    println!("Creating tools with the ultra-simple ftool API!");
    println!("The system automatically infers types from your function signature!\n");

    // Example 1: Integer parameters (i32, i32) - types inferred automatically!
    let add_tool = ToolBuilder::new("add")
        .description("Add two integers")
        .parameters("x:i32:First number, y:i32:Second number")
        .ftool(adder) // Automatically knows these are i32!
        .build();

    // Example 2: Integer multiplication (i32, i32)
    let multiply_tool = ToolBuilder::new("multiply")
        .description("Multiply two integers")
        .parameters("a:i32:First number, b:i32:Second number")
        .ftool(multiplier)
        .build();

    // Example 3: Float parameters (f64, f64) - automatically inferred!
    let area_tool = ToolBuilder::new("calculate_area")
        .description("Calculate the area of a rectangle")
        .parameters("length:f64:Length in meters, width:f64:Width in meters")
        .ftool(calculate_area) // Same ftool method, but knows these are f64!
        .build();

    // Example 4: Three float parameters (f64, f64, f64)
    let volume_tool = ToolBuilder::new("calculate_volume")
        .description("Calculate the volume of a box")
        .parameters(
            "width:f64:Width in meters, height:f64:Height in meters, depth:f64:Depth in meters",
        )
        .ftool3(calculate_volume)
        .build();

    // Example 5: BMI calculator with floats
    let bmi_tool = ToolBuilder::new("calculate_bmi")
        .description("Calculate Body Mass Index")
        .parameters("weight_kg:f64:Weight in kilograms, height_m:f64:Height in meters")
        .ftool(calculate_bmi)
        .build();

    // Example 6: Mixed types - String and bool!
    let greet_tool = ToolBuilder::new("greet")
        .description("Greet someone by name")
        .parameters("name:string:Person's name, formal:bool:Use formal greeting")
        .ftool(greet) // Automatically knows: String, bool!
        .build();

    // Example 7: Mixed numeric types - f64 and i32
    let discount_tool = ToolBuilder::new("calculate_discount")
        .description("Calculate discount on a price")
        .parameters("price:f64:Original price, percent:i32:Discount percentage")
        .ftool(calculate_discount) // Automatically knows: f64, i32!
        .build();

    // Create an agent with all the tools
    let mut agent = Agent::builder("ToolDemo")
        .config(config)
        .system_prompt(
            "You are a helpful assistant with access to various calculation and utility tools. \
             Use them to help answer questions accurately.",
        )
        .tool(add_tool)
        .tool(multiply_tool)
        .tool(area_tool)
        .tool(volume_tool)
        .tool(bmi_tool)
        .tool(greet_tool)
        .tool(discount_tool)
        .build()
        .await?;

    println!("Created 7 tools with minimal code!\n");
    println!("All types automatically inferred from function signatures!\n");
    println!("===========================================\n");

    // Test the tools
    println!("Test 1: Integer addition");
    let response = agent.chat("What is 42 plus 17?").await?;
    println!("Agent: {}\n", response);

    println!("Test 2: Integer multiplication");
    let response = agent.chat("What is 12 times 8?").await?;
    println!("Agent: {}\n", response);

    println!("Test 3: Calculate area");
    let response = agent
        .chat("What is the area of a rectangle that is 5 meters long and 3 meters wide?")
        .await?;
    println!("Agent: {}\n", response);

    println!("Test 4: Calculate volume");
    let response = agent
        .chat("What's the volume of a box that is 2m wide, 3m high, and 1.5m deep?")
        .await?;
    println!("Agent: {}\n", response);

    println!("Test 5: Calculate BMI");
    let response = agent
        .chat("Calculate BMI for someone weighing 70 kg and 1.75 meters tall")
        .await?;
    println!("Agent: {}\n", response);

    println!("Test 6: Greeting with String and bool");
    let response = agent.chat("Greet Bob in a casual way").await?;
    println!("Agent: {}\n", response);

    println!("Test 7: Discount calculation with mixed types");
    let response = agent
        .chat("What's the discount on a $100 item with 20% off?")
        .await?;
    println!("Agent: {}\n", response);

    println!("\n===========================================");
    println!("✨ That's how easy it is to create tools!");
    println!("   Just define your function and the system automatically:");
    println!("   • Infers all parameter types from your function signature");
    println!("   • Extracts values from JSON in the right order");
    println!("   • Handles i32, i64, u32, u64, f32, f64, bool, String");
    println!(
        "   • Works with .ftool() for 2 params, .ftool3() for 3 params, .ftool4() for 4 params"
    );

    Ok(())
}

pub fn function<F, Fut>(self, f: F) -> Self

where F: Fn(Value) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<ToolResult>> + Send + 'static,

Sets the function to execute when the tool is called.

The function should be an async function that takes Value (JSON arguments) and returns Result<ToolResult>.

Arguments

• f - An async function that implements the tool’s logic

pub fn sync_function<F>(self, f: F) -> Self

where F: Fn(Value) -> Result<ToolResult> + Send + Sync + 'static,

Sets the function using a synchronous closure.

This is a convenience method for simple synchronous operations.

Arguments

• f - A synchronous function that implements the tool’s logic

pub fn ftool<F, T1, T2, R>(self, f: F) -> Self

where F: Fn(T1, T2) -> R + Send + Sync + 'static, T1: FromValue + Send + 'static, T2: FromValue + Send + 'static, R: ToString + Send + 'static,

Ultra-simple API: Pass a function directly with automatic type inference.

This method automatically infers parameter types from your function signature and extracts them from JSON. Works with any types that implement FromValue.

Supported types: i32, i64, u32, u64, f32, f64, bool, String

Example

use helios_engine::ToolBuilder;

fn adder(x: i32, y: i32) -> i32 { x + y }
fn greeter(name: String, formal: bool) -> String {
    if formal {
        format!("Good day, {}", name)
    } else {
        format!("Hey {}!", name)
    }
}

let add_tool = ToolBuilder::new("add")
    .description("Add two numbers")
    .parameters("x:i32:First, y:i32:Second")
    .ftool(adder)
    .build();

let greet_tool = ToolBuilder::new("greet")
    .description("Greet someone")
    .parameters("name:string:Name, formal:bool:Formal")
    .ftool(greeter)
    .build();

Examples found in repository

examples/tool_builder_demo.rs (line 63)

async fn main() -> helios_engine::Result<()> {
    let config = Config::from_file("config.toml")?;

    println!("=== Tool Builder Demo ===\n");
    println!("Creating tools with the ultra-simple ftool API!");
    println!("The system automatically infers types from your function signature!\n");

    // Example 1: Integer parameters (i32, i32) - types inferred automatically!
    let add_tool = ToolBuilder::new("add")
        .description("Add two integers")
        .parameters("x:i32:First number, y:i32:Second number")
        .ftool(adder) // Automatically knows these are i32!
        .build();

    // Example 2: Integer multiplication (i32, i32)
    let multiply_tool = ToolBuilder::new("multiply")
        .description("Multiply two integers")
        .parameters("a:i32:First number, b:i32:Second number")
        .ftool(multiplier)
        .build();

    // Example 3: Float parameters (f64, f64) - automatically inferred!
    let area_tool = ToolBuilder::new("calculate_area")
        .description("Calculate the area of a rectangle")
        .parameters("length:f64:Length in meters, width:f64:Width in meters")
        .ftool(calculate_area) // Same ftool method, but knows these are f64!
        .build();

    // Example 4: Three float parameters (f64, f64, f64)
    let volume_tool = ToolBuilder::new("calculate_volume")
        .description("Calculate the volume of a box")
        .parameters(
            "width:f64:Width in meters, height:f64:Height in meters, depth:f64:Depth in meters",
        )
        .ftool3(calculate_volume)
        .build();

    // Example 5: BMI calculator with floats
    let bmi_tool = ToolBuilder::new("calculate_bmi")
        .description("Calculate Body Mass Index")
        .parameters("weight_kg:f64:Weight in kilograms, height_m:f64:Height in meters")
        .ftool(calculate_bmi)
        .build();

    // Example 6: Mixed types - String and bool!
    let greet_tool = ToolBuilder::new("greet")
        .description("Greet someone by name")
        .parameters("name:string:Person's name, formal:bool:Use formal greeting")
        .ftool(greet) // Automatically knows: String, bool!
        .build();

    // Example 7: Mixed numeric types - f64 and i32
    let discount_tool = ToolBuilder::new("calculate_discount")
        .description("Calculate discount on a price")
        .parameters("price:f64:Original price, percent:i32:Discount percentage")
        .ftool(calculate_discount) // Automatically knows: f64, i32!
        .build();

    // Create an agent with all the tools
    let mut agent = Agent::builder("ToolDemo")
        .config(config)
        .system_prompt(
            "You are a helpful assistant with access to various calculation and utility tools. \
             Use them to help answer questions accurately.",
        )
        .tool(add_tool)
        .tool(multiply_tool)
        .tool(area_tool)
        .tool(volume_tool)
        .tool(bmi_tool)
        .tool(greet_tool)
        .tool(discount_tool)
        .build()
        .await?;

    println!("Created 7 tools with minimal code!\n");
    println!("All types automatically inferred from function signatures!\n");
    println!("===========================================\n");

    // Test the tools
    println!("Test 1: Integer addition");
    let response = agent.chat("What is 42 plus 17?").await?;
    println!("Agent: {}\n", response);

    println!("Test 2: Integer multiplication");
    let response = agent.chat("What is 12 times 8?").await?;
    println!("Agent: {}\n", response);

    println!("Test 3: Calculate area");
    let response = agent
        .chat("What is the area of a rectangle that is 5 meters long and 3 meters wide?")
        .await?;
    println!("Agent: {}\n", response);

    println!("Test 4: Calculate volume");
    let response = agent
        .chat("What's the volume of a box that is 2m wide, 3m high, and 1.5m deep?")
        .await?;
    println!("Agent: {}\n", response);

    println!("Test 5: Calculate BMI");
    let response = agent
        .chat("Calculate BMI for someone weighing 70 kg and 1.75 meters tall")
        .await?;
    println!("Agent: {}\n", response);

    println!("Test 6: Greeting with String and bool");
    let response = agent.chat("Greet Bob in a casual way").await?;
    println!("Agent: {}\n", response);

    println!("Test 7: Discount calculation with mixed types");
    let response = agent
        .chat("What's the discount on a $100 item with 20% off?")
        .await?;
    println!("Agent: {}\n", response);

    println!("\n===========================================");
    println!("✨ That's how easy it is to create tools!");
    println!("   Just define your function and the system automatically:");
    println!("   • Infers all parameter types from your function signature");
    println!("   • Extracts values from JSON in the right order");
    println!("   • Handles i32, i64, u32, u64, f32, f64, bool, String");
    println!(
        "   • Works with .ftool() for 2 params, .ftool3() for 3 params, .ftool4() for 4 params"
    );

    Ok(())
}

pub fn ftool3<F, T1, T2, T3, R>(self, f: F) -> Self

where F: Fn(T1, T2, T3) -> R + Send + Sync + 'static, T1: FromValue + Send + 'static, T2: FromValue + Send + 'static, T3: FromValue + Send + 'static, R: ToString + Send + 'static,

Ultra-simple API: Pass a 3-parameter function directly with automatic type inference.

Example

use helios_engine::ToolBuilder;

fn volume(width: f64, height: f64, depth: f64) -> f64 {
    width * height * depth
}

let tool = ToolBuilder::new("calculate_volume")
    .description("Calculate volume")
    .parameters("width:f64:Width, height:f64:Height, depth:f64:Depth")
    .ftool3(volume)
    .build();

Examples found in repository

examples/tool_builder_demo.rs (line 86)

async fn main() -> helios_engine::Result<()> {
    let config = Config::from_file("config.toml")?;

    println!("=== Tool Builder Demo ===\n");
    println!("Creating tools with the ultra-simple ftool API!");
    println!("The system automatically infers types from your function signature!\n");

    // Example 1: Integer parameters (i32, i32) - types inferred automatically!
    let add_tool = ToolBuilder::new("add")
        .description("Add two integers")
        .parameters("x:i32:First number, y:i32:Second number")
        .ftool(adder) // Automatically knows these are i32!
        .build();

    // Example 2: Integer multiplication (i32, i32)
    let multiply_tool = ToolBuilder::new("multiply")
        .description("Multiply two integers")
        .parameters("a:i32:First number, b:i32:Second number")
        .ftool(multiplier)
        .build();

    // Example 3: Float parameters (f64, f64) - automatically inferred!
    let area_tool = ToolBuilder::new("calculate_area")
        .description("Calculate the area of a rectangle")
        .parameters("length:f64:Length in meters, width:f64:Width in meters")
        .ftool(calculate_area) // Same ftool method, but knows these are f64!
        .build();

    // Example 4: Three float parameters (f64, f64, f64)
    let volume_tool = ToolBuilder::new("calculate_volume")
        .description("Calculate the volume of a box")
        .parameters(
            "width:f64:Width in meters, height:f64:Height in meters, depth:f64:Depth in meters",
        )
        .ftool3(calculate_volume)
        .build();

    // Example 5: BMI calculator with floats
    let bmi_tool = ToolBuilder::new("calculate_bmi")
        .description("Calculate Body Mass Index")
        .parameters("weight_kg:f64:Weight in kilograms, height_m:f64:Height in meters")
        .ftool(calculate_bmi)
        .build();

    // Example 6: Mixed types - String and bool!
    let greet_tool = ToolBuilder::new("greet")
        .description("Greet someone by name")
        .parameters("name:string:Person's name, formal:bool:Use formal greeting")
        .ftool(greet) // Automatically knows: String, bool!
        .build();

    // Example 7: Mixed numeric types - f64 and i32
    let discount_tool = ToolBuilder::new("calculate_discount")
        .description("Calculate discount on a price")
        .parameters("price:f64:Original price, percent:i32:Discount percentage")
        .ftool(calculate_discount) // Automatically knows: f64, i32!
        .build();

    // Create an agent with all the tools
    let mut agent = Agent::builder("ToolDemo")
        .config(config)
        .system_prompt(
            "You are a helpful assistant with access to various calculation and utility tools. \
             Use them to help answer questions accurately.",
        )
        .tool(add_tool)
        .tool(multiply_tool)
        .tool(area_tool)
        .tool(volume_tool)
        .tool(bmi_tool)
        .tool(greet_tool)
        .tool(discount_tool)
        .build()
        .await?;

    println!("Created 7 tools with minimal code!\n");
    println!("All types automatically inferred from function signatures!\n");
    println!("===========================================\n");

    // Test the tools
    println!("Test 1: Integer addition");
    let response = agent.chat("What is 42 plus 17?").await?;
    println!("Agent: {}\n", response);

    println!("Test 2: Integer multiplication");
    let response = agent.chat("What is 12 times 8?").await?;
    println!("Agent: {}\n", response);

    println!("Test 3: Calculate area");
    let response = agent
        .chat("What is the area of a rectangle that is 5 meters long and 3 meters wide?")
        .await?;
    println!("Agent: {}\n", response);

    println!("Test 4: Calculate volume");
    let response = agent
        .chat("What's the volume of a box that is 2m wide, 3m high, and 1.5m deep?")
        .await?;
    println!("Agent: {}\n", response);

    println!("Test 5: Calculate BMI");
    let response = agent
        .chat("Calculate BMI for someone weighing 70 kg and 1.75 meters tall")
        .await?;
    println!("Agent: {}\n", response);

    println!("Test 6: Greeting with String and bool");
    let response = agent.chat("Greet Bob in a casual way").await?;
    println!("Agent: {}\n", response);

    println!("Test 7: Discount calculation with mixed types");
    let response = agent
        .chat("What's the discount on a $100 item with 20% off?")
        .await?;
    println!("Agent: {}\n", response);

    println!("\n===========================================");
    println!("✨ That's how easy it is to create tools!");
    println!("   Just define your function and the system automatically:");
    println!("   • Infers all parameter types from your function signature");
    println!("   • Extracts values from JSON in the right order");
    println!("   • Handles i32, i64, u32, u64, f32, f64, bool, String");
    println!(
        "   • Works with .ftool() for 2 params, .ftool3() for 3 params, .ftool4() for 4 params"
    );

    Ok(())
}

pub fn ftool4<F, T1, T2, T3, T4, R>(self, f: F) -> Self

where F: Fn(T1, T2, T3, T4) -> R + Send + Sync + 'static, T1: FromValue + Send + 'static, T2: FromValue + Send + 'static, T3: FromValue + Send + 'static, T4: FromValue + Send + 'static, R: ToString + Send + 'static,

Ultra-simple API: Pass a 4-parameter function directly with automatic type inference.

pub fn build(self) -> Box<dyn Tool>

Builds the tool, consuming the builder and returning a boxed Tool.

Panics

Panics if the function has not been set.

Examples found in repository

examples/tool_builder_demo.rs (line 64)

async fn main() -> helios_engine::Result<()> {
    let config = Config::from_file("config.toml")?;

    println!("=== Tool Builder Demo ===\n");
    println!("Creating tools with the ultra-simple ftool API!");
    println!("The system automatically infers types from your function signature!\n");

    // Example 1: Integer parameters (i32, i32) - types inferred automatically!
    let add_tool = ToolBuilder::new("add")
        .description("Add two integers")
        .parameters("x:i32:First number, y:i32:Second number")
        .ftool(adder) // Automatically knows these are i32!
        .build();

    // Example 2: Integer multiplication (i32, i32)
    let multiply_tool = ToolBuilder::new("multiply")
        .description("Multiply two integers")
        .parameters("a:i32:First number, b:i32:Second number")
        .ftool(multiplier)
        .build();

    // Example 3: Float parameters (f64, f64) - automatically inferred!
    let area_tool = ToolBuilder::new("calculate_area")
        .description("Calculate the area of a rectangle")
        .parameters("length:f64:Length in meters, width:f64:Width in meters")
        .ftool(calculate_area) // Same ftool method, but knows these are f64!
        .build();

    // Example 4: Three float parameters (f64, f64, f64)
    let volume_tool = ToolBuilder::new("calculate_volume")
        .description("Calculate the volume of a box")
        .parameters(
            "width:f64:Width in meters, height:f64:Height in meters, depth:f64:Depth in meters",
        )
        .ftool3(calculate_volume)
        .build();

    // Example 5: BMI calculator with floats
    let bmi_tool = ToolBuilder::new("calculate_bmi")
        .description("Calculate Body Mass Index")
        .parameters("weight_kg:f64:Weight in kilograms, height_m:f64:Height in meters")
        .ftool(calculate_bmi)
        .build();

    // Example 6: Mixed types - String and bool!
    let greet_tool = ToolBuilder::new("greet")
        .description("Greet someone by name")
        .parameters("name:string:Person's name, formal:bool:Use formal greeting")
        .ftool(greet) // Automatically knows: String, bool!
        .build();

    // Example 7: Mixed numeric types - f64 and i32
    let discount_tool = ToolBuilder::new("calculate_discount")
        .description("Calculate discount on a price")
        .parameters("price:f64:Original price, percent:i32:Discount percentage")
        .ftool(calculate_discount) // Automatically knows: f64, i32!
        .build();

    // Create an agent with all the tools
    let mut agent = Agent::builder("ToolDemo")
        .config(config)
        .system_prompt(
            "You are a helpful assistant with access to various calculation and utility tools. \
             Use them to help answer questions accurately.",
        )
        .tool(add_tool)
        .tool(multiply_tool)
        .tool(area_tool)
        .tool(volume_tool)
        .tool(bmi_tool)
        .tool(greet_tool)
        .tool(discount_tool)
        .build()
        .await?;

    println!("Created 7 tools with minimal code!\n");
    println!("All types automatically inferred from function signatures!\n");
    println!("===========================================\n");

    // Test the tools
    println!("Test 1: Integer addition");
    let response = agent.chat("What is 42 plus 17?").await?;
    println!("Agent: {}\n", response);

    println!("Test 2: Integer multiplication");
    let response = agent.chat("What is 12 times 8?").await?;
    println!("Agent: {}\n", response);

    println!("Test 3: Calculate area");
    let response = agent
        .chat("What is the area of a rectangle that is 5 meters long and 3 meters wide?")
        .await?;
    println!("Agent: {}\n", response);

    println!("Test 4: Calculate volume");
    let response = agent
        .chat("What's the volume of a box that is 2m wide, 3m high, and 1.5m deep?")
        .await?;
    println!("Agent: {}\n", response);

    println!("Test 5: Calculate BMI");
    let response = agent
        .chat("Calculate BMI for someone weighing 70 kg and 1.75 meters tall")
        .await?;
    println!("Agent: {}\n", response);

    println!("Test 6: Greeting with String and bool");
    let response = agent.chat("Greet Bob in a casual way").await?;
    println!("Agent: {}\n", response);

    println!("Test 7: Discount calculation with mixed types");
    let response = agent
        .chat("What's the discount on a $100 item with 20% off?")
        .await?;
    println!("Agent: {}\n", response);

    println!("\n===========================================");
    println!("✨ That's how easy it is to create tools!");
    println!("   Just define your function and the system automatically:");
    println!("   • Infers all parameter types from your function signature");
    println!("   • Extracts values from JSON in the right order");
    println!("   • Handles i32, i64, u32, u64, f32, f64, bool, String");
    println!(
        "   • Works with .ftool() for 2 params, .ftool3() for 3 params, .ftool4() for 4 params"
    );

    Ok(())
}

pub fn try_build(self) -> Result<Box<dyn Tool>>

Builds the tool, returning a Result instead of panicking.

Returns an error if the function has not been set.