llm-tool 0.3.1

Framework-agnostic Rust tool definitions for LLM agents
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

//! Quick performance benchmark for template descriptions.
//!
//! Run with: `cargo test --features prompt-templates --release -- perf --nocapture`

#![cfg(feature = "prompt-templates")]

use std::time::{Duration, Instant};

use llm_tool::{RustTool, ToolRegistry, llm_tool};

// ── Static template description ──

#[llm_tool(prompt_file = "tools/static_desc.tmpl.md")]
fn static_tool(
    /// A value.
    x: i64,
) -> String {
    format!("{x}")
}

// ── Dynamic template description ──

fn bench_context(_tool: &DynamicTool) -> prompt_templates::Context {
    prompt_templates::Context::from_serialize(&serde_json::json!({
        "context": {
            "api_version": "v3.1",
            "env_name": "production"
        }
    }))
    .unwrap()
}

#[llm_tool(prompt_file = "tools/dynamic_desc.tmpl.md", context = bench_context)]
fn dynamic_tool(
    /// A value.
    x: i64,
) -> String {
    format!("{x}")
}

// ── Doc comment description (baseline) ──

/// Fetch the current weather for any city worldwide. Returns a JSON object
/// containing temperature, humidity, wind speed, and a human-readable
/// conditions summary.
#[llm_tool]
fn doc_comment_tool(
    /// A value.
    x: i64,
) -> String {
    format!("{x}")
}

const ITERATIONS: u32 = 100_000;

/// Convert a duration to nanoseconds-per-call without `as f64` precision loss.
fn ns_per_call(elapsed: Duration, iterations: u32) -> f64 {
    elapsed.as_secs_f64() * 1e9 / f64::from(iterations)
}

#[test]
fn perf_description_methods() {
    let static_tool = StaticTool;
    let dynamic_tool = DynamicTool;
    let doc_tool = DocCommentTool;

    // Warm up LazyLock
    std::hint::black_box(dynamic_tool.description());

    // Benchmark doc comment description (baseline)
    let start = Instant::now();
    for _ in 0..ITERATIONS {
        std::hint::black_box(doc_tool.description());
    }
    let doc_elapsed = start.elapsed();

    // Benchmark static template description
    let start = Instant::now();
    for _ in 0..ITERATIONS {
        std::hint::black_box(static_tool.description());
    }
    let static_elapsed = start.elapsed();

    // Benchmark dynamic template description
    let start = Instant::now();
    for _ in 0..ITERATIONS {
        std::hint::black_box(dynamic_tool.description());
    }
    let dynamic_elapsed = start.elapsed();

    println!("\n=== description() performance ({ITERATIONS} iterations) ===");
    println!(
        "  Doc comment (baseline): {:>8.2?}  ({:.0} ns/call)",
        doc_elapsed,
        ns_per_call(doc_elapsed, ITERATIONS)
    );
    println!(
        "  Static template:        {:>8.2?}  ({:.0} ns/call)",
        static_elapsed,
        ns_per_call(static_elapsed, ITERATIONS)
    );
    println!(
        "  Dynamic template:       {:>8.2?}  ({:.0} ns/call)",
        dynamic_elapsed,
        ns_per_call(dynamic_elapsed, ITERATIONS)
    );

    // Also benchmark registry definition generation
    let registry = ToolRegistry::new()
        .with_tool(StaticTool)
        .with_tool(DynamicTool)
        .with_tool(DocCommentTool);

    let start = Instant::now();
    for _ in 0..1000 {
        std::hint::black_box(registry.definitions());
    }
    let defn_elapsed = start.elapsed();
    println!(
        "  definitions() x1000:    {:>8.2?}  ({:.0} µs/call)",
        defn_elapsed,
        defn_elapsed.as_secs_f64() * 1e6 / 1000.0
    );
    println!();
}