volition-core 0.2.0

Core library for the Volition AI agent
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

// volition-agent-core/src/models/tools.rs

//! Structures related to AI tool definition, calling, and input/output.

use serde::{Deserialize, Serialize};
use serde_json::Value as JsonValue;
use std::collections::HashMap;

/// Represents a tool call requested by the AI model within a [`ChatMessage`](super::chat::ChatMessage).
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct ToolCall {
    /// A unique identifier generated by the AI for this specific tool call request.
    /// This ID must be included in the corresponding `tool` role [`ChatMessage`](super::chat::ChatMessage)
    /// containing the execution result.
    pub id: String,
    /// The type of the tool call, typically "function".
    #[serde(rename = "type")]
    pub call_type: String,
    /// Details of the function to be called.
    pub function: ToolFunction,
}

/// Represents the function call details within a [`ToolCall`].
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct ToolFunction {
    /// The name of the tool function to be executed (e.g., "read_file").
    /// This must match the name provided in a [`ToolDefinition`].
    pub name: String,
    /// A JSON-formatted string containing the arguments for the function call.
    /// The [`Agent`](crate::Agent) parses this string into a [`ToolInput`].
    pub arguments: String,
}

/// Defines the schema for a tool that can be presented to the AI.
///
/// [`ToolProvider`](crate::ToolProvider) implementations return a `Vec<ToolDefinition>`
/// from their `get_tool_definitions` method.
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct ToolDefinition {
    /// The name of the tool function.
    pub name: String,
    /// A description of what the tool does, used by the AI model to determine when to call it.
    pub description: String,
    /// The parameters the tool function accepts, defined as a JSON Schema object.
    pub parameters: ToolParametersDefinition,
}

/// Defines the parameters structure for a tool, following JSON Schema object type.
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct ToolParametersDefinition {
    /// The type of the parameters object, typically "object".
    #[serde(rename = "type")]
    pub param_type: String,
    /// A map defining the individual parameters, keyed by parameter name.
    pub properties: HashMap<String, ToolParameter>,
    /// A list of parameter names that are required by the tool function.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub required: Vec<String>,
}

/// Defines a single parameter within a tool's schema.
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct ToolParameter {
    /// The data type of the parameter.
    #[serde(rename = "type")]
    pub param_type: ToolParameterType,
    /// A description of the parameter's purpose.
    pub description: String,
    /// Optional list of allowed string values for an enum-like parameter.
    #[serde(rename = "enum", skip_serializing_if = "Option::is_none")]
    pub enum_values: Option<Vec<String>>,
    /// Optional definition for the items if `param_type` is `Array`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub items: Option<Box<ToolParameter>>,
}

/// Represents the allowed data types for a tool parameter.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(rename_all = "lowercase")]
pub enum ToolParameterType {
    String,
    Integer,
    Number,
    Boolean,
    Array,
    Object,
}

/// Represents the input arguments provided for a tool execution at runtime.
///
/// The [`Agent`](crate::Agent) parses the JSON argument string from [`ToolFunction::arguments`]
/// into this structure before passing it to [`ToolProvider::execute_tool`](crate::ToolProvider::execute_tool).
#[derive(Serialize, Deserialize, Debug, Clone, Default)]
pub struct ToolInput {
    /// A map holding the argument names and their corresponding JSON values.
    pub arguments: HashMap<String, JsonValue>,
}