Struct ToolOrchestrator

Source

pub struct ToolOrchestrator { /* private fields */ }

Expand description

Tool orchestrator - executes Rhai scripts with registered tool access.

The ToolOrchestrator is the main entry point for programmatic tool calling. It manages tool registration and script execution within a sandboxed Rhai environment.

§Features

Tool Registration: Register Rust functions as callable tools
Script Execution: Run Rhai scripts that can invoke registered tools
Resource Limits: Configurable limits prevent runaway execution
Audit Trail: All tool calls are logged with timing information

§Thread Safety

With the native feature, the orchestrator is thread-safe
With the wasm feature, it’s single-threaded for WASM compatibility

§Example

use tool_orchestrator::{ToolOrchestrator, ExecutionLimits};

let mut orchestrator = ToolOrchestrator::new();

// Register tools
orchestrator.register_executor("add", |input| {
    let arr = input.as_array().unwrap();
    let sum: i64 = arr.iter().filter_map(|v| v.as_i64()).sum();
    Ok(sum.to_string())
});

// Execute script
let result = orchestrator.execute(
    r#"
    let a = add([1, 2, 3]);
    let b = add([4, 5, 6]);
    `Sum: ${a} + ${b}`
    "#,
    ExecutionLimits::default()
)?;

println!("{}", result.output);  // "Sum: 6 + 15"
println!("Tool calls: {}", result.tool_calls.len());  // 2

Implementations§

Source §

impl ToolOrchestrator

Source

pub fn new() -> Self

Create a new tool orchestrator with default settings.

Initializes a fresh Rhai engine with expression depth limits and an empty tool registry.

Source

pub fn register_executor<F>(&mut self, name: impl Into<String>, executor: F)
where F: Fn(Value) -> Result<String, String> + Send + Sync + 'static,

Register a tool executor function (native version - thread-safe).

The executor function receives JSON input from the Rhai script and returns either a success string or an error string.

§Arguments

name - The name the tool will be callable as in Rhai scripts
executor - Function that processes tool calls

§Example

orchestrator.register_executor("fetch_user", |input| {
    let user_id = input.as_i64().ok_or("Expected user ID")?;
    // Fetch user from database...
    Ok(format!(r#"{{"id": {}, "name": "Alice"}}"#, user_id))
});

Source

pub fn execute( &self, script: &str, limits: ExecutionLimits, ) -> Result<OrchestratorResult, OrchestratorError>

Execute a Rhai script with access to registered tools.

Compiles and runs the provided Rhai script, making all registered tools available as callable functions. Execution is bounded by the provided ExecutionLimits.

§Arguments

script - Rhai source code to execute
limits - Resource limits for this execution

§Returns

On success, returns OrchestratorResult containing:

The script’s output (final expression value)
A log of all tool calls made
Execution timing information

§Errors

Returns OrchestratorError if:

Script fails to compile (CompilationError)
Script throws a runtime error (ExecutionError)
Operation limit exceeded (MaxOperationsExceeded)
Time limit exceeded (Timeout)

Source

pub fn registered_tools(&self) -> Vec<&str>

Get list of registered tool names.

Returns the names of all tools that have been registered with register_executor. These names are callable as functions in Rhai scripts.

§Example

orchestrator.register_executor("tool_a", |_| Ok("a".into()));
orchestrator.register_executor("tool_b", |_| Ok("b".into()));

let tools = orchestrator.registered_tools();
assert!(tools.contains(&"tool_a"));
assert!(tools.contains(&"tool_b"));