0.4.2

Overview

The new ToolBuilder feature in Helios Engine introduces a dramatically simplified way to create custom tools for LLM agents. With ToolBuilder, developers can wrap any function as a tool using a fluent builder pattern or the ultra-simple quick_tool! macro, eliminating the need for manual trait implementation and boilerplate code.

---

Key Highlights

• Zero Boilerplate: Create tools in a single expression with automatic parameter extraction and type inference.
• Builder Pattern: Use ToolBuilder to fluently define tool name, description, parameters, and execution logic.
• Macro Magic: The quick_tool! macro enables tool creation with just a function signature and body.
• Type Safety: Supports Rust primitives (i32, f64, bool, String, etc.) with automatic JSON extraction and conversion.
• Async & Sync Support: Easily define synchronous or asynchronous tool logic.
• Comprehensive Examples: See examples/tool_builder_demo.rs for real-world usage.

---

Usage Examples

1. ToolBuilder Pattern

use helios_engine::{ToolBuilder, ToolResult};
use serde_json::Value;

let tool = ToolBuilder::new("my_tool")
    .description("Does something useful")
    .required_parameter("input", "string", "The input value")
    .sync_function(|args: Value| {
        let input = args.get("input").and_then(|v| v.as_str())
            .ok_or_else(|| helios_engine::HeliosError::ToolError(
                "Missing input parameter".to_string()
            ))?;
        
        Ok(ToolResult::success(format!("Processed: {}", input)))
    })
    .build();

2. Macro-Based Tool Creation

use helios_engine::quick_tool;

let volume_tool = quick_tool! {
    name: calculate_volume,
    description: "Calculate the volume of a box",
    params: (width: f64, height: f64, depth: f64),
    execute: |width, height, depth| {
        format!("Volume: {:.2} cubic meters", width * height * depth)
    }
};

3. Real-World Demo

See the full demo in:

// Demonstrates creating tools for addition, multiplication, area, volume, BMI, greetings, and discounts
// using both ToolBuilder and quick_tool! macro

---

API Reference

• ToolBuilder::new(name)
• .description(desc)
• .required_parameter(name, type, desc)
• .optional_parameter(name, type, desc)
• .function(async_fn) / .sync_function(sync_fn)
• .build() / .try_build()

Parameter Types: "string", "number", "boolean", "object", "array"

---

Best Practices

• Write clear descriptions for tools and parameters.
• Always validate required parameters and handle errors gracefully.
• Use async functions for I/O-bound tools.
• See examples/tool_builder_demo.rs for patterns and advanced usage.

---

Documentation

• Main: docs/TOOLS.md
• Example: examples/tool_builder_demo.rs
• Macro: See "Quick Start: quick_tool! Macro" in docs/TOOLS.md

---

Testing & Verification

🧪 TESTING:

• Run the demo:

  cargo run --example tool_builder_demo
  

• All tools are covered in the example and validated for correct type inference and execution.

EXPECTED_OUTPUTS:

• Agent responds correctly to math, greeting, and discount queries using the generated tools.

---

⚠️ NOTES:

• No errors or warnings detected in the codebase.
• No GitHub releases or tags found; this report is based on the latest code and documentation.