ceylon_next/tools/
mod.rs

1//! Tool system for extending agent capabilities.
2//!
3//! This module provides the trait and infrastructure for creating custom tools
4//! that agents can use to perform external actions.
5
6pub mod invoker;
7
8/// Trait for implementing custom tools that agents can use.
9///
10/// Tools extend agent capabilities by allowing them to interact with external systems,
11/// perform calculations, access databases, make API calls, and more.
12///
13/// # Examples
14///
15/// ```rust,no_run
16/// use ceylon_next::tools::ToolTrait;
17/// use serde_json::{json, Value};
18///
19/// struct CalculatorTool;
20///
21/// impl ToolTrait for CalculatorTool {
22///     fn name(&self) -> String {
23///         "calculator".to_string()
24///     }
25///
26///     fn description(&self) -> String {
27///         "Performs basic arithmetic operations (add, subtract, multiply, divide)".to_string()
28///     }
29///
30///     fn input_schema(&self) -> Value {
31///         json!({
32///             "type": "object",
33///             "properties": {
34///                 "operation": {
35///                     "type": "string",
36///                     "enum": ["add", "subtract", "multiply", "divide"]
37///                 },
38///                 "a": {"type": "number"},
39///                 "b": {"type": "number"}
40///             },
41///             "required": ["operation", "a", "b"]
42///         })
43///     }
44///
45///     fn execute(&self, input: Value) -> Value {
46///         let op = input["operation"].as_str().unwrap();
47///         let a = input["a"].as_f64().unwrap();
48///         let b = input["b"].as_f64().unwrap();
49///
50///         let result = match op {
51///             "add" => a + b,
52///             "subtract" => a - b,
53///             "multiply" => a * b,
54///             "divide" => a / b,
55///             _ => 0.0,
56///         };
57///
58///         json!({"result": result})
59///     }
60/// }
61///
62/// // Use the tool with an agent
63/// use ceylon_next::agent::Agent;
64///
65/// let mut agent = Agent::new("Calculator Agent", "openai::gpt-4");
66/// agent.add_tool(CalculatorTool);
67/// ```
68pub trait ToolTrait {
69    /// Returns the unique name of the tool.
70    ///
71    /// This name is used by the LLM to identify and invoke the tool.
72    fn name(&self) -> String;
73
74    /// Returns a human-readable description of what the tool does.
75    ///
76    /// This description helps the LLM understand when and how to use the tool.
77    fn description(&self) -> String;
78
79    /// Returns the JSON schema defining the tool's input parameters.
80    ///
81    /// The schema should follow the JSON Schema specification and define
82    /// all required and optional parameters for the tool.
83    fn input_schema(&self) -> serde_json::Value;
84
85    /// Executes the tool with the given input and returns the result.
86    ///
87    /// # Arguments
88    ///
89    /// * `input` - A JSON value containing the tool's input parameters
90    ///
91    /// # Returns
92    ///
93    /// A JSON value containing the tool's output
94    fn execute(&self, input: serde_json::Value) -> serde_json::Value;
95}
ceylon_next/tools/mod.rs

ceylon_next/tools/
mod.rs
