Attribute Macro clust::attributes::clust_tool

#[clust_tool]

A procedural macro that generates a clust::messages::Tool or clust::messages::AsyncTool implementation for the annotated function with documentation.

See also the official guide.

Supported argument types

• None
  • e.g. fn function() -> T
• Types that can be represented as JSON object.
  • Boolean
    • bool
  • Integer
    • i8, i16, i32, i64, i128
    • u8, u16, u32, u64, u128
  • Number
    • f32
    • f64
  • String
    • String
    • &str
  • Array
    • Vec<T> where T is supported type.
    • &[T] where T is supported type.
    • &[T; N] where T is supported type and N is a constant.
  • Option
    • Option<T> where T is supported type.
  • e.g. fn function(arg1: i32, arg2: String, arg3: Vec<f64>) -> T

Supported return value types

• None
  • e.g. fn function()
• A type that can be formatted, i.e. implements std::fmt::Display.
  • e.g.
    • fn function() -> u32
    • fn function() -> DefinedStruct (where DefinedStruct implements std::fmt::Display).
• Result<T, E> where T and E can be formatted, i.e. implement std::fmt::Display.
  • e.g.
    • fn function() -> Result<u32, SomeError> (where SomeError implements std::fmt::Display).
    • fn function() -> Result<DefinedStruct, SomeError> (where DefinedStruct and SomeError implement std::fmt::Display).

Supported executions

• Synchronous -> implement clust::messages::Tool
  • e.g. fn function() -> T
• Asynchronous -> implement clust::messages::AsyncTool
  • e.g. async fn function() -> T

(Optional) Supported documentation formats

1. Description block for the function at the top of document.
2. Arguments block for the function with

• header: # Arguments, ## Arguments, # Parameters or ## Parameters.
• listed items: - arg1 - Description for the argument or * arg1 - Description for the argument.

3. Other blocks are ignored.

e.g.

/// Description for the function.
///
/// ## Arguments
/// - `arg1` - Description for the argument.
fn function(arg1: i32) -> i32 { arg1 }

Examples

Implement a tool by clust_tool for a function with documentation:

use clust_macros::clust_tool;
use clust::messages::{ToolUse, Tool};

/// Increments the argument by 1.
///
/// ## Arguments
/// - `value` - Target value.
#[clust_tool]
fn incrementer(value: i32) -> i32 {
   value + 1
}

let tool = ClustTool_incrementer {};

let tool_use = ToolUse::new(
    "toolu_XXXX",
    "incrementer",
    serde_json::json!({
        "value": 42
    }),
);

let result = tool.call(tool_use).unwrap();
assert_eq!(result.tool_use_id, "toolu_XXXX");
assert_eq!(result.is_error, None);
assert_eq!(result.content.unwrap().text, "43");