Attribute Macro clust_macros::clust_tool
source · #[clust_tool]
Expand description
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 arguments
- None
- e.g.
fn function() -> T
- e.g.
- A type or types that implement(s)
std::str::FromStr
.- e.g.
fn function(arg1: u32) -> T
fn function(arg1: DefinedStruct) -> T
whereDefinedStruct
implementsstd::str::FromStr
.
- e.g.
§Supported return values
- A type that implements
std::fmt::Display
.- e.g.
fn function() -> u32
fn function() -> DefinedStruct
whereDefinedStruct
implementsstd::fmt::Display
.
- e.g.
- Result<T, E> where T and E implement
std::fmt::Display
.- e.g.
fn function() -> Result<u32, Error>
fn function() -> Result<DefinedStruct, Error>
whereDefinedStruct
andError
implementstd::fmt::Display
.
- e.g.
§Supported executions
- Synchronous -> implement
clust::messages::Tool
- e.g.
fn function() -> T
- e.g.
- Asynchronous -> implement
clust::messages::AsyncTool
- e.g.
async fn function() -> T
- e.g.
§Supported documentation formats
- Description block for the function at the top of document.
- 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
.
- Other blocks are ignored.
/// 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 std::collections::BTreeMap;
use std::iter::FromIterator;
use clust::messages::{FunctionCalls, Invoke, Tool};
/// Increments the argument by 1.
///
/// ## Arguments
/// - `value` - Target value.
#[clust_tool]
fn incrementer(value: i32) -> i32 {
value + 1
}
let tool = ClustTool_incrementer {};
let description = tool.description();
let function_calls = FunctionCalls {
invoke: Invoke {
tool_name: String::from("incrementer"),
parameters: BTreeMap::from_iter(vec![(
"value".to_string(),
"42".to_string(),
)]),
},
};
let result = tool.call(function_calls).unwrap();
Generated XML tool description from above implementation is as follows:
<tool_description>
<tool_name>incrementer</tool_name>
<description>Increments the argument by 1.</description>
<parameters>
<parameter>
<name>value</name>
<type>i32</type>
<description>Target value.</description>
</parameter>
</parameters>
</tool_description>
This tool can be called with a function calls as following XML format:
<function_calls>
<invoke>
<tool_name>incrementer</tool_name>
<parameters>
<value>42</value>
</parameters>
</invoke>
</function_calls>
Calling result is as following XML format:
<function_results>
<result>
<tool_name>incrementer</tool_name>
<stdout>43</stdout>
</result>
</function_results>