volition_core/models/
tools.rs

1// volition-agent-core/src/models/tools.rs
2
3//! Structures related to AI tool definition, calling, and input/output.
4
5use serde::{Deserialize, Serialize};
6use serde_json::Value as JsonValue;
7use std::collections::HashMap;
8
9/// Represents a tool call requested by the AI model within a [`ChatMessage`](super::chat::ChatMessage).
10#[derive(Serialize, Deserialize, Debug, Clone)]
11pub struct ToolCall {
12    /// A unique identifier generated by the AI for this specific tool call request.
13    /// This ID must be included in the corresponding `tool` role [`ChatMessage`](super::chat::ChatMessage)
14    /// containing the execution result.
15    pub id: String,
16    /// The type of the tool call, typically "function".
17    #[serde(rename = "type")]
18    pub call_type: String,
19    /// Details of the function to be called.
20    pub function: ToolFunction,
21}
22
23/// Represents the function call details within a [`ToolCall`].
24#[derive(Serialize, Deserialize, Debug, Clone)]
25pub struct ToolFunction {
26    /// The name of the tool function to be executed (e.g., "read_file").
27    /// This must match the name provided in a [`ToolDefinition`].
28    pub name: String,
29    /// A JSON-formatted string containing the arguments for the function call.
30    /// The [`Agent`](crate::Agent) parses this string into a [`ToolInput`].
31    pub arguments: String,
32}
33
34/// Defines the schema for a tool that can be presented to the AI.
35///
36/// [`ToolProvider`](crate::ToolProvider) implementations return a `Vec<ToolDefinition>`
37/// from their `get_tool_definitions` method.
38#[derive(Serialize, Deserialize, Debug, Clone)]
39pub struct ToolDefinition {
40    /// The name of the tool function.
41    pub name: String,
42    /// A description of what the tool does, used by the AI model to determine when to call it.
43    pub description: String,
44    /// The parameters the tool function accepts, defined as a JSON Schema object.
45    pub parameters: ToolParametersDefinition,
46}
47
48/// Defines the parameters structure for a tool, following JSON Schema object type.
49#[derive(Serialize, Deserialize, Debug, Clone)]
50pub struct ToolParametersDefinition {
51    /// The type of the parameters object, typically "object".
52    #[serde(rename = "type")]
53    pub param_type: String,
54    /// A map defining the individual parameters, keyed by parameter name.
55    pub properties: HashMap<String, ToolParameter>,
56    /// A list of parameter names that are required by the tool function.
57    #[serde(default, skip_serializing_if = "Vec::is_empty")]
58    pub required: Vec<String>,
59}
60
61/// Defines a single parameter within a tool's schema.
62#[derive(Serialize, Deserialize, Debug, Clone)]
63pub struct ToolParameter {
64    /// The data type of the parameter.
65    #[serde(rename = "type")]
66    pub param_type: ToolParameterType,
67    /// A description of the parameter's purpose.
68    pub description: String,
69    /// Optional list of allowed string values for an enum-like parameter.
70    #[serde(rename = "enum", skip_serializing_if = "Option::is_none")]
71    pub enum_values: Option<Vec<String>>,
72    /// Optional definition for the items if `param_type` is `Array`.
73    #[serde(skip_serializing_if = "Option::is_none")]
74    pub items: Option<Box<ToolParameter>>,
75}
76
77/// Represents the allowed data types for a tool parameter.
78#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
79#[serde(rename_all = "lowercase")]
80pub enum ToolParameterType {
81    String,
82    Integer,
83    Number,
84    Boolean,
85    Array,
86    Object,
87}
88
89/// Represents the input arguments provided for a tool execution at runtime.
90///
91/// The [`Agent`](crate::Agent) parses the JSON argument string from [`ToolFunction::arguments`]
92/// into this structure before passing it to [`ToolProvider::execute_tool`](crate::ToolProvider::execute_tool).
93#[derive(Serialize, Deserialize, Debug, Clone, Default)]
94pub struct ToolInput {
95    /// A map holding the argument names and their corresponding JSON values.
96    pub arguments: HashMap<String, JsonValue>,
97}
volition_core/models/tools.rs

volition_core/models/
tools.rs
