tool_orchestrator/lib.rs
1//! Tool Orchestrator - Rhai-based tool orchestration for AI agents
2//!
3//! Implements Anthropic's "Programmatic Tool Calling" pattern for token-efficient
4//! tool orchestration. Instead of sequential tool calls, AI writes Rhai scripts
5//! that orchestrate multiple tools, returning only the final result.
6//!
7//! ## Features
8//!
9//! This crate supports multiple build targets via feature flags:
10//!
11//! - **`native`** (default) - Thread-safe Rust library with `Arc`/`Mutex`
12//! - **`wasm`** - WebAssembly bindings for browser/Node.js via `wasm-bindgen`
13//!
14//! ## Benefits
15//!
16//! - **37% token reduction** - intermediate results don't pollute context
17//! - **Parallel execution** - multiple tools in one pass
18//! - **Complex orchestration** - loops, conditionals, data processing
19//!
20//! ## Example (Native)
21//!
22//! ```ignore
23//! use tool_orchestrator::{ToolOrchestrator, ExecutionLimits};
24//!
25//! let mut orchestrator = ToolOrchestrator::new();
26//! orchestrator.register_executor("greet", |input| {
27//! Ok(format!("Hello, {}!", input.as_str().unwrap_or("world")))
28//! });
29//!
30//! let result = orchestrator.execute(
31//! r#"greet("Claude")"#,
32//! ExecutionLimits::default()
33//! )?;
34//!
35//! assert_eq!(result.output, "Hello, Claude!");
36//! ```
37//!
38//! ## Example (WASM)
39//!
40//! ```javascript
41//! import { WasmOrchestrator, ExecutionLimits } from 'tool-orchestrator';
42//!
43//! const orchestrator = new WasmOrchestrator();
44//! orchestrator.register_tool('greet', (input) => {
45//! const name = JSON.parse(input);
46//! return `Hello, ${name}!`;
47//! });
48//!
49//! const result = orchestrator.execute(
50//! 'greet("Claude")',
51//! ExecutionLimits.quick()
52//! );
53//!
54//! console.log(result.output); // "Hello, Claude!"
55//! ```
56
57// Require either native or wasm feature (but not both)
58#[cfg(not(any(feature = "native", feature = "wasm")))]
59compile_error!(
60 "Either the `native` or `wasm` feature must be enabled. \
61 Add `features = [\"native\"]` to your Cargo.toml dependency or use `--features native`."
62);
63
64#[cfg(all(feature = "native", feature = "wasm"))]
65compile_error!(
66 "The `native` and `wasm` features are mutually exclusive. \
67 Use `--features native` for Rust library or `--no-default-features --features wasm` for WASM."
68);
69
70// Core modules (always available)
71pub mod engine;
72pub mod sandbox;
73pub mod types;
74
75// Re-export core types
76pub use engine::{dynamic_to_json, ToolExecutor, ToolOrchestrator};
77pub use sandbox::{
78 ExecutionLimits,
79 // Default limit constants
80 DEFAULT_MAX_ARRAY_SIZE, DEFAULT_MAX_MAP_SIZE, DEFAULT_MAX_OPERATIONS, DEFAULT_MAX_STRING_SIZE,
81 DEFAULT_MAX_TOOL_CALLS, DEFAULT_TIMEOUT_MS,
82 // Profile constants
83 EXTENDED_MAX_OPERATIONS, EXTENDED_MAX_TOOL_CALLS, EXTENDED_TIMEOUT_MS, QUICK_MAX_OPERATIONS,
84 QUICK_MAX_TOOL_CALLS, QUICK_TIMEOUT_MS,
85};
86pub use types::{OrchestratorError, OrchestratorResult, ToolCall};
87
88// WASM module (only when wasm feature is enabled)
89#[cfg(feature = "wasm")]
90pub mod wasm;
91
92#[cfg(feature = "wasm")]
93pub use wasm::{ExecutionLimits as WasmExecutionLimits, WasmOrchestrator};