api_openai/components/
chat_shared.rs

1// src/components/chat_shared.rs
2//! This module defines shared data structures and components used across various `OpenAI` chat-related API endpoints.
3//! It includes definitions for chat completion requests, messages, content parts, and tool-related structures.
4//!
5//! For more details, refer to the [`OpenAI` Chat API documentation](https://platform.openai.com/docs/api-reference/chat).
6
7/// Define a private namespace for all its items.
8mod private
9{
10  // Serde imports
11  use serde::{ Serialize, Deserialize };
12  use serde_json::Value;
13  use former::Former;
14  use crate::components::tools::FunctionTool;
15
16  /// Represents a message in a chat completion request.
17  ///
18  /// # Used By
19  /// - `ChatCompletionRequest`
20  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Former ) ]
21  pub struct ChatCompletionRequestMessage
22  {
23    /// The role of the message's author.
24    pub role : String,
25    /// The content of the message.
26    #[ serde( skip_serializing_if = "Option::is_none" ) ]
27    pub content : Option< ChatCompletionRequestMessageContent >,
28    /// The name of the author of this message.
29    #[ serde( skip_serializing_if = "Option::is_none" ) ]
30    pub name : Option< String >,
31    /// The tool calls generated by the model, if applicable.
32    #[ serde( skip_serializing_if = "Option::is_none" ) ]
33    pub tool_calls : Option< Vec< ChatCompletionMessageToolCall > >,
34    /// Tool call ID that this message is responding to.
35    #[ serde( skip_serializing_if = "Option::is_none" ) ]
36    pub tool_call_id : Option< String >,
37  }
38
39  /// Represents the content of a message in a chat completion request.
40  /// Can be a simple string or a list of content parts (for multimodal input).
41  ///
42  /// # Used By
43  /// - `ChatCompletionRequestMessage`
44  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
45  #[ serde( untagged ) ]
46  pub enum ChatCompletionRequestMessageContent
47  {
48    /// A single string content.
49    Text( String ),
50    /// A list of content parts for multimodal input.
51    Parts( Vec< ChatCompletionRequestMessageContentPart > ),
52  }
53
54  /// Represents a part of the content in a chat completion request message.
55  /// Can be text or an image URL.
56  ///
57  /// # Used By
58  /// - `ChatCompletionRequestMessageContent`
59  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
60  #[ serde( tag = "type" ) ]
61  pub enum ChatCompletionRequestMessageContentPart
62  {
63    /// Text content.
64    #[ serde( rename = "text" ) ]
65    Text
66    {
67      /// The text content.
68      text : String
69    },
70    /// Image URL content.
71    #[ serde( rename = "image_url" ) ]
72    ImageUrl
73    {
74      /// The image URL content.
75      image_url : ChatCompletionRequestMessageContentImageUrl
76    },
77  }
78
79  /// Represents an image URL in a chat completion request message content part.
80  ///
81  /// # Used By
82  /// - `ChatCompletionRequestMessageContentPart::ImageUrl`
83  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Former ) ]
84  pub struct ChatCompletionRequestMessageContentImageUrl
85  {
86    /// The URL of the image.
87    pub url : String,
88    /// The detail level of the image. Can be `low`, `high`, or `auto`.
89    #[ serde( skip_serializing_if = "Option::is_none" ) ]
90    pub detail : Option< String >,
91  }
92
93  /// Represents a tool call generated by the model.
94  ///
95  /// # Used By
96  /// - `ChatCompletionRequestMessage`
97  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Former ) ]
98  pub struct ChatCompletionMessageToolCall
99  {
100    /// The ID of the tool call.
101    pub id : String,
102    /// The type of the tool. Currently, only `function` is supported.
103    pub r#type : String,
104    /// The function that the model called.
105    pub function : ChatCompletionMessageToolCallFunction,
106  }
107
108  /// Represents a function call within a tool call.
109  ///
110  /// # Used By
111  /// - `ChatCompletionMessageToolCall`
112  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Former ) ]
113  pub struct ChatCompletionMessageToolCallFunction
114  {
115    /// The name of the function to call.
116    pub name : String,
117    /// The arguments to call the function with, as a JSON string.
118    pub arguments : String,
119  }
120
121  /// Represents a tool that can be used by the model.
122  ///
123  /// # Used By
124  /// - `ChatCompletionRequest`
125  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Former ) ]
126  pub struct ChatCompletionTool
127  {
128    /// The type of the tool. Currently, only `function` is supported.
129    pub r#type : String,
130    /// The function definition.
131    #[ serde( skip_serializing_if = "Option::is_none" ) ]
132    pub function : Option< FunctionTool >,
133  }
134
135  /// Represents the choice of tool to use.
136  ///
137  /// # Used By
138  /// - `ChatCompletionRequest`
139  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
140  #[ serde( untagged ) ]
141  pub enum ToolChoiceOption
142  {
143    /// A string representing the tool choice (e.g., "none", "auto").
144    String( String ),
145    /// A specific tool to force the model to use.
146    Object( ToolChoiceObject ),
147  }
148
149  /// Represents a specific tool to force the model to use.
150  ///
151  /// # Used By
152  /// - `ToolChoiceOption::Object`
153  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Former ) ]
154  pub struct ToolChoiceObject
155  {
156    /// The type of the tool. Currently, only `function` is supported.
157    pub r#type : String,
158    /// The function to force the model to use.
159    pub function : ToolChoiceFunction,
160  }
161
162  /// Represents a function to force the model to use.
163  ///
164  /// # Used By
165  /// - `ToolChoiceObject`
166  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Former ) ]
167  pub struct ToolChoiceFunction
168  {
169    /// The name of the function to force the model to use.
170    pub name : String,
171  }
172
173  /// Represents a chat completion request.
174  ///
175  /// # Used By
176  /// - `api::responses::Responses::create`
177  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Former ) ]
178  pub struct ChatCompletionRequest
179  {
180    /// ID of the model to use.
181    pub model : String,
182    /// A list of messages comprising the conversation so far.
183    pub messages : Vec< ChatCompletionRequestMessage >,
184    /// What sampling temperature to use, between 0 and 2.
185    #[ serde( skip_serializing_if = "Option::is_none" ) ]
186    pub temperature : Option< f32 >,
187    /// An alternative to sampling with temperature, called nucleus sampling.
188    #[ serde( skip_serializing_if = "Option::is_none" ) ]
189    pub top_p : Option< f32 >,
190    /// The maximum number of tokens to generate in the chat completion.
191    #[ serde( skip_serializing_if = "Option::is_none" ) ]
192    pub max_tokens : Option< i32 >,
193    /// Number of chat completion choices to generate for each input message.
194    #[ serde( skip_serializing_if = "Option::is_none" ) ]
195    pub n : Option< i32 >,
196    /// Up to 4 sequences where the API will stop generating further tokens.
197    #[ serde( skip_serializing_if = "Option::is_none" ) ]
198    pub stop : Option< Vec< String > >,
199    /// Whether to stream back partial progress.
200    #[ serde( skip_serializing_if = "Option::is_none" ) ]
201    pub stream : Option< bool >,
202    /// The system prompt that helps guide the behavior of the model.
203    #[ serde( skip_serializing_if = "Option::is_none" ) ]
204    pub system_prompt : Option< String >,
205    /// A unique identifier representing your end-user.
206    #[ serde( skip_serializing_if = "Option::is_none" ) ]
207    pub user : Option< String >,
208    /// A list of tools the model may call.
209    #[ serde( skip_serializing_if = "Option::is_none" ) ]
210    pub tools : Option< Vec< ChatCompletionTool > >,
211    /// Controls which (if any) tool the model calls.
212    #[ serde( skip_serializing_if = "Option::is_none" ) ]
213    pub tool_choice : Option< ToolChoiceOption >,
214    /// An object specifying the format that the model must output.
215    #[ serde( skip_serializing_if = "Option::is_none" ) ]
216    pub response_format : Option< ChatCompletionResponseFormat >,
217    /// This feature is in Beta.
218    #[ serde( skip_serializing_if = "Option::is_none" ) ]
219    pub seed : Option< i64 >,
220    /// Adjusts the likelihood of specified tokens appearing in the completion.
221    #[ serde( skip_serializing_if = "Option::is_none" ) ]
222    pub logit_bias : Option< Value >,
223    /// Log probability of the most likely tokens.
224    #[ serde( skip_serializing_if = "Option::is_none" ) ]
225    pub logprobs : Option< bool >,
226    /// The number of most likely tokens to return at each token position.
227    #[ serde( skip_serializing_if = "Option::is_none" ) ]
228    pub top_logprobs : Option< i32 >,
229  }
230
231  /// Represents the format that the model must output.
232  ///
233  /// # Used By
234  /// - `ChatCompletionRequest`
235  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Former ) ]
236  pub struct ChatCompletionResponseFormat
237  {
238    /// The type of response format. Currently, only `json_object` is supported.
239    pub r#type : String,
240  }
241
242  /// Represents a chat completion response.
243  ///
244  /// # Used By
245  /// - `api::responses::Responses::create`
246  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
247  pub struct CreateChatCompletionResponse
248  {
249    /// A unique identifier for the chat completion.
250    pub id : String,
251    /// A list of chat completion choices.
252    pub choices : Vec< ChatCompletionChoice >,
253    /// The Unix timestamp (in seconds) of when the chat completion was created.
254    #[ serde( rename = "created" ) ]
255    pub created_at : i64,
256    /// The model used for the chat completion.
257    pub model : String,
258    /// The object type, which is always `chat.completion`.
259    pub object : String,
260    /// This fingerprint represents the contents of the `input` field.
261    #[ serde( skip_serializing_if = "Option::is_none" ) ]
262    pub system_fingerprint : Option< String >,
263    /// Usage statistics for the completion request.
264    #[ serde( skip_serializing_if = "Option::is_none" ) ]
265    pub usage : Option< ChatCompletionUsage >,
266  }
267
268  /// Represents a choice in a chat completion response.
269  ///
270  /// # Used By
271  /// - `CreateChatCompletionResponse`
272  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
273  pub struct ChatCompletionChoice
274  {
275    /// The reason the model finished generating tokens.
276    pub finish_reason : String,
277    /// The index of the choice in the list of choices.
278    pub index : i32,
279    /// A message describing the model's response.
280    pub message : ChatCompletionResponseMessage,
281    /// Log probability information for the choice.
282    #[ serde( skip_serializing_if = "Option::is_none" ) ]
283    pub logprobs : Option< ChatCompletionLogprobs >,
284  }
285
286  /// Represents a message in a chat completion response.
287  ///
288  /// # Used By
289  /// - `ChatCompletionChoice`
290  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
291  pub struct ChatCompletionResponseMessage
292  {
293    /// The contents of the message.
294    #[ serde( skip_serializing_if = "Option::is_none" ) ]
295    pub content : Option< String >,
296    /// The role of the author of this message.
297    pub role : String,
298    /// The tool calls generated by the model, if applicable.
299    #[ serde( skip_serializing_if = "Option::is_none" ) ]
300    pub tool_calls : Option< Vec< ChatCompletionMessageToolCall > >,
301  }
302
303  /// Represents usage statistics for a chat completion request.
304  ///
305  /// # Used By
306  /// - `CreateChatCompletionResponse`
307  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
308  pub struct ChatCompletionUsage
309  {
310    /// Number of tokens in the completion.
311    pub completion_tokens : i32,
312    /// Number of tokens in the prompt.
313    pub prompt_tokens : i32,
314    /// Total number of tokens used in the request (prompt + completion).
315    pub total_tokens : i32,
316  }
317
318  /// Represents log probability information for a chat completion choice.
319  ///
320  /// # Used By
321  /// - `ChatCompletionChoice`
322  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
323  pub struct ChatCompletionLogprobs
324  {
325    /// A list of log probability information for the tokens in the completion.
326    pub content : Vec< ChatCompletionLogprobsContent >,
327  }
328
329  /// Represents log probability information for a single token in the completion.
330  ///
331  /// # Used By
332  /// - `ChatCompletionLogprobs`
333  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
334  pub struct ChatCompletionLogprobsContent
335  {
336    /// The token.
337    pub token : String,
338    /// The log probability of the token.
339    pub logprob : f32,
340    /// A list of the most likely tokens and their log probabilities.
341    pub top_logprobs : Vec< ChatCompletionLogprobsTopLogprob >,
342  }
343
344  /// Represents a top log probability token.
345  ///
346  /// # Used By
347  /// - `ChatCompletionLogprobsContent`
348  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
349  pub struct ChatCompletionLogprobsTopLogprob
350  {
351    /// The token.
352    pub token : String,
353    /// The log probability of the token.
354    pub logprob : f32,
355  }
356
357  /// Represents a streaming chat completion response.
358  ///
359  /// # Used By
360  /// - `api::responses::Responses::create_stream`
361  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
362  pub struct ChatCompletionStreamResponse
363  {
364    /// A unique identifier for the chat completion.
365    pub id : String,
366    /// A list of chat completion choices.
367    pub choices : Vec< ChatCompletionStreamChoice >,
368    /// The Unix timestamp (in seconds) of when the chat completion was created.
369    #[ serde( rename = "created" ) ]
370    pub created_at : i64,
371    /// The model used for the chat completion.
372    pub model : String,
373    /// The object type, which is always `chat.completion.chunk`.
374    pub object : String,
375    /// This fingerprint represents the contents of the `input` field.
376    #[ serde( skip_serializing_if = "Option::is_none" ) ]
377    pub system_fingerprint : Option< String >,
378  }
379
380  /// Represents a choice in a streaming chat completion response.
381  ///
382  /// # Used By
383  /// - `ChatCompletionStreamResponse`
384  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
385  pub struct ChatCompletionStreamChoice
386  {
387    /// The reason the model finished generating tokens.
388    #[ serde( skip_serializing_if = "Option::is_none" ) ]
389    pub finish_reason : Option< String >,
390    /// The index of the choice in the list of choices.
391    pub index : i32,
392    /// A message describing the model's response.
393    pub delta : ChatCompletionStreamResponseMessage,
394    /// Log probability information for the choice.
395    #[ serde( skip_serializing_if = "Option::is_none" ) ]
396    pub logprobs : Option< ChatCompletionLogprobs >,
397  }
398
399  /// Represents a message in a streaming chat completion response.
400  ///
401  /// # Used By
402  /// - `ChatCompletionStreamChoice`
403  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
404  pub struct ChatCompletionStreamResponseMessage
405  {
406    /// The contents of the message.
407    #[ serde( skip_serializing_if = "Option::is_none" ) ]
408    pub content : Option< String >,
409    /// The role of the author of this message.
410    #[ serde( skip_serializing_if = "Option::is_none" ) ]
411    pub role : Option< String >,
412    /// The tool calls generated by the model, if applicable.
413    #[ serde( skip_serializing_if = "Option::is_none" ) ]
414    pub tool_calls : Option< Vec< ChatCompletionMessageToolCall > >,
415  }
416}
417
418crate ::mod_interface!
419{
420  exposed use
421  {
422    ChatCompletionRequestMessage,
423    ChatCompletionRequestMessageContent,
424    ChatCompletionRequestMessageContentPart,
425    ChatCompletionRequestMessageContentImageUrl,
426    ChatCompletionMessageToolCall,
427    ChatCompletionMessageToolCallFunction,
428    ChatCompletionTool,
429    ToolChoiceOption,
430    ToolChoiceObject,
431    ToolChoiceFunction,
432    ChatCompletionRequest,
433    ChatCompletionResponseFormat,
434    CreateChatCompletionResponse,
435    ChatCompletionChoice,
436    ChatCompletionResponseMessage,
437    ChatCompletionUsage,
438    ChatCompletionLogprobs,
439    ChatCompletionLogprobsContent,
440    ChatCompletionLogprobsTopLogprob,
441    ChatCompletionStreamResponse,
442    ChatCompletionStreamChoice,
443    ChatCompletionStreamResponseMessage,
444  };
445}
api_openai/components/chat_shared.rs

api_openai/components/
chat_shared.rs
