openfunctions_rs/models/mod.rs
1//! Data models for tools, agents, and execution results.
2//!
3//! This module defines the primary data structures used throughout the application.
4//! These models are designed to be serializable and deserializable, and they form
5//! the basis for configuration, tool definition, and communication between
6//! components.
7
8use schemars::JsonSchema;
9use serde::{Deserialize, Serialize};
10use std::collections::HashMap;
11
12/// The definition of a tool, parsed from comments in its source code.
13///
14/// This structure captures everything needed to understand and use a tool,
15/// including its purpose, parameters, and dependencies.
16#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
17pub struct ToolDefinition {
18 /// A description of the tool's purpose and functionality.
19 pub description: String,
20
21 /// The parameters that the tool accepts.
22 pub parameters: Vec<ParameterDefinition>,
23
24 /// Environment variables that are required for the tool's execution.
25 pub env_vars: Vec<EnvVarDefinition>,
26
27 /// A list of external command-line tools that this tool depends on.
28 pub required_tools: Vec<String>,
29
30 /// A map for any additional, unstructured metadata about the tool.
31 pub metadata: HashMap<String, serde_json::Value>,
32}
33
34impl ToolDefinition {
35 /// Converts a `ToolDefinition` into a `FunctionDeclaration` for use with an LLM.
36 ///
37 /// This is a crucial step for function calling, as it transforms the internal
38 /// tool representation into a format that the AI model can understand.
39 pub fn to_function_declaration(
40 &self,
41 name: &str,
42 ) -> crate::Result<crate::core::function::FunctionDeclaration> {
43 use crate::core::function::{FunctionDeclaration, Parameter};
44
45 let parameters = self
46 .parameters
47 .iter()
48 .map(|p| {
49 let param_type = match &p.param_type {
50 ParameterType::String => {
51 if let Some(ref enum_values) = p.enum_values {
52 crate::core::function::ParameterType::Enum(enum_values.clone())
53 } else {
54 crate::core::function::ParameterType::String
55 }
56 }
57 ParameterType::Integer => crate::core::function::ParameterType::Integer,
58 ParameterType::Number => crate::core::function::ParameterType::Number,
59 ParameterType::Boolean => crate::core::function::ParameterType::Boolean,
60 ParameterType::Array => crate::core::function::ParameterType::Array,
61 ParameterType::Object => crate::core::function::ParameterType::Object,
62 ParameterType::Enum(values) => {
63 crate::core::function::ParameterType::Enum(values.clone())
64 }
65 };
66
67 Parameter {
68 name: p.name.clone(),
69 param_type,
70 description: p.description.clone(),
71 required: p.required,
72 default: p.default.clone(),
73 }
74 })
75 .collect();
76
77 Ok(FunctionDeclaration {
78 name: name.to_string(),
79 description: self.description.clone(),
80 parameters,
81 })
82 }
83}
84
85/// The definition of a single parameter for a tool.
86#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
87pub struct ParameterDefinition {
88 /// The name of the parameter.
89 pub name: String,
90
91 /// The data type of the parameter.
92 pub param_type: ParameterType,
93
94 /// A description of the parameter's purpose.
95 pub description: String,
96
97 /// Whether the parameter is required for the tool to be called.
98 pub required: bool,
99
100 /// An optional default value for the parameter.
101 pub default: Option<serde_json::Value>,
102
103 /// For `String` or `Enum` types, a list of allowed values.
104 pub enum_values: Option<Vec<String>>,
105}
106
107/// An enumeration of data types for tool parameters.
108#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq)]
109#[serde(rename_all = "lowercase")]
110pub enum ParameterType {
111 /// UTF-8 string type
112 String,
113 /// 64-bit signed integer
114 Integer,
115 /// 64-bit floating point number
116 Number,
117 /// Boolean value (true/false)
118 Boolean,
119 /// Array of values
120 Array,
121 /// JSON object
122 Object,
123 /// String with predefined allowed values
124 #[serde(rename = "enum")]
125 Enum(Vec<String>),
126}
127
128/// The definition of an environment variable required by a tool.
129#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
130pub struct EnvVarDefinition {
131 /// The name of the environment variable (e.g., "API_KEY").
132 pub name: String,
133
134 /// A description of what the environment variable is used for.
135 pub description: String,
136
137 /// Whether the environment variable must be set for the tool to run.
138 pub required: bool,
139
140 /// An optional default value for the environment variable.
141 pub default: Option<String>,
142}
143
144/// The definition of an agent, loaded from its `index.yaml` file.
145#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
146pub struct AgentDefinition {
147 /// The unique name of the agent.
148 pub name: String,
149
150 /// A description of the agent's purpose and capabilities.
151 pub description: String,
152
153 /// The version of the agent.
154 pub version: String,
155
156 /// The system prompt or instructions that guide the agent's behavior.
157 pub instructions: String,
158
159 /// Variables that can be configured for the agent.
160 #[serde(default)]
161 pub variables: Vec<AgentVariable>,
162
163 /// A list of documents to be used for Retrieval-Augmented Generation (RAG).
164 #[serde(default)]
165 pub documents: Vec<String>,
166
167 /// A list of example prompts to start a conversation with the agent.
168 #[serde(default)]
169 pub conversation_starters: Vec<String>,
170
171 /// Additional, unstructured metadata for the agent.
172 #[serde(default)]
173 pub metadata: HashMap<String, serde_json::Value>,
174}
175
176/// The definition of a configurable variable for an agent.
177#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
178pub struct AgentVariable {
179 /// The name of the variable.
180 pub name: String,
181
182 /// A description of the variable's purpose.
183 pub description: String,
184
185 /// An optional default value for the variable.
186 pub default: Option<String>,
187}
188
189/// The result of an execution of a tool function.
190#[derive(Debug, Clone, Serialize, Deserialize)]
191pub struct ExecutionResult {
192 /// `true` if the execution was successful, `false` otherwise.
193 pub success: bool,
194
195 /// The standard output (stdout) from the execution.
196 pub output: String,
197
198 /// The standard error (stderr) from the execution, if any.
199 pub error: Option<String>,
200
201 /// The duration of the execution.
202 pub duration: std::time::Duration,
203
204 /// Additional, unstructured metadata about the execution.
205 pub metadata: HashMap<String, serde_json::Value>,
206}
207
208/// Represents a request to call a function, typically from an LLM.
209#[derive(Debug, Clone, Serialize, Deserialize)]
210pub struct FunctionCall {
211 /// The name of the function to call.
212 pub name: String,
213
214 /// The arguments for the function, as a JSON value.
215 pub arguments: serde_json::Value,
216
217 /// A unique ID for tracking the request.
218 pub request_id: String,
219
220 /// The timestamp of when the call was requested.
221 pub timestamp: chrono::DateTime<chrono::Utc>,
222}
223
224/// Represents the response from a function call.
225#[derive(Debug, Clone, Serialize, Deserialize)]
226pub struct FunctionResponse {
227 /// The ID of the request that this response corresponds to.
228 pub request_id: String,
229
230 /// The result of the function's execution.
231 pub result: ExecutionResult,
232
233 /// The timestamp of when the response was generated.
234 pub timestamp: chrono::DateTime<chrono::Utc>,
235}