async_openai/types/chatkit/
thread.rs

1use serde::{Deserialize, Serialize};
2
3/// Represents a ChatKit thread and its current status.
4#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
5pub struct ThreadResource {
6    /// Identifier of the thread.
7    pub id: String,
8    /// Type discriminator that is always `chatkit.thread`.
9    #[serde(default = "default_thread_object")]
10    pub object: String,
11    /// Unix timestamp (in seconds) for when the thread was created.
12    pub created_at: i64,
13    /// Optional human-readable title for the thread. Defaults to null when no title has been generated.
14    pub title: Option<String>,
15    /// Current status for the thread. Defaults to `active` for newly created threads.
16    #[serde(flatten)]
17    pub status: ThreadStatus,
18    /// Free-form string that identifies your end user who owns the thread.
19    pub user: String,
20    /// Thread items (only present when retrieving a thread)
21    #[serde(skip_serializing_if = "Option::is_none")]
22    pub items: Option<ThreadItemListResource>,
23}
24
25fn default_thread_object() -> String {
26    "chatkit.thread".to_string()
27}
28
29/// Current status for the thread.
30#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
31#[serde(tag = "type", rename_all = "snake_case")]
32pub enum ThreadStatus {
33    /// Indicates that a thread is active.
34    Active,
35    /// Indicates that a thread is locked and cannot accept new input.
36    Locked { reason: Option<String> },
37    /// Indicates that a thread has been closed.
38    Closed { reason: Option<String> },
39}
40
41/// A paginated list of ChatKit threads.
42#[derive(Clone, Serialize, Debug, Deserialize, PartialEq, Default)]
43pub struct ThreadListResource {
44    /// The type of object returned, must be `list`.
45    #[serde(default = "default_list_object")]
46    pub object: String,
47    /// A list of items
48    pub data: Vec<ThreadResource>,
49    /// The ID of the first item in the list.
50    pub first_id: Option<String>,
51    /// The ID of the last item in the list.
52    pub last_id: Option<String>,
53    /// Whether there are more items available.
54    pub has_more: bool,
55}
56
57fn default_list_object() -> String {
58    "list".to_string()
59}
60
61/// Confirmation payload returned after deleting a thread.
62#[derive(Clone, Serialize, Debug, Deserialize, PartialEq, Default)]
63pub struct DeletedThreadResource {
64    /// Identifier of the deleted thread.
65    pub id: String,
66    /// Type discriminator that is always `chatkit.thread.deleted`.
67    #[serde(default = "default_deleted_object")]
68    pub object: String,
69    /// Indicates that the thread has been deleted.
70    pub deleted: bool,
71}
72
73fn default_deleted_object() -> String {
74    "chatkit.thread.deleted".to_string()
75}
76
77/// A paginated list of thread items rendered for the ChatKit API.
78#[derive(Clone, Serialize, Debug, Deserialize, PartialEq, Default)]
79pub struct ThreadItemListResource {
80    /// The type of object returned, must be `list`.
81    #[serde(default = "default_list_object")]
82    pub object: String,
83    /// A list of items
84    pub data: Vec<ThreadItem>,
85    /// The ID of the first item in the list.
86    pub first_id: Option<String>,
87    /// The ID of the last item in the list.
88    pub last_id: Option<String>,
89    /// Whether there are more items available.
90    pub has_more: bool,
91}
92
93/// The thread item - discriminated union based on type field.
94#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
95#[serde(tag = "type", rename_all = "snake_case")]
96pub enum ThreadItem {
97    /// User-authored messages within a thread.
98    #[serde(rename = "chatkit.user_message")]
99    UserMessage(UserMessageItem),
100    /// Assistant-authored message within a thread.
101    #[serde(rename = "chatkit.assistant_message")]
102    AssistantMessage(AssistantMessageItem),
103    /// Thread item that renders a widget payload.
104    #[serde(rename = "chatkit.widget")]
105    Widget(WidgetMessageItem),
106    /// Record of a client side tool invocation initiated by the assistant.
107    #[serde(rename = "chatkit.client_tool_call")]
108    ClientToolCall(ClientToolCallItem),
109    /// Task emitted by the workflow to show progress and status updates.
110    #[serde(rename = "chatkit.task")]
111    Task(TaskItem),
112    /// Collection of workflow tasks grouped together in the thread.
113    #[serde(rename = "chatkit.task_group")]
114    TaskGroup(TaskGroupItem),
115}
116
117/// User-authored messages within a thread.
118#[derive(Clone, Serialize, Debug, Deserialize, PartialEq, Default)]
119pub struct UserMessageItem {
120    /// Identifier of the thread item.
121    pub id: String,
122    /// Type discriminator that is always `chatkit.thread_item`.
123    #[serde(default = "default_thread_item_object")]
124    pub object: String,
125    /// Unix timestamp (in seconds) for when the item was created.
126    pub created_at: i64,
127    /// Identifier of the parent thread.
128    pub thread_id: String,
129    /// Ordered content elements supplied by the user.
130    pub content: Vec<UserMessageContent>,
131    /// Attachments associated with the user message. Defaults to an empty list.
132    #[serde(default)]
133    pub attachments: Vec<Attachment>,
134    /// Inference overrides applied to the message. Defaults to null when unset.
135    #[serde(skip_serializing_if = "Option::is_none")]
136    pub inference_options: Option<InferenceOptions>,
137}
138
139fn default_thread_item_object() -> String {
140    "chatkit.thread_item".to_string()
141}
142
143/// Content blocks that comprise a user message.
144#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
145#[serde(tag = "type", rename_all = "snake_case")]
146pub enum UserMessageContent {
147    /// Text block that a user contributed to the thread.
148    #[serde(rename = "input_text")]
149    InputText { text: String },
150    /// Quoted snippet that the user referenced in their message.
151    #[serde(rename = "quoted_text")]
152    QuotedText { text: String },
153}
154
155/// Attachment metadata included on thread items.
156#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
157pub struct Attachment {
158    /// Attachment discriminator.
159    #[serde(rename = "type")]
160    pub attachment_type: AttachmentType,
161    /// Identifier for the attachment.
162    pub id: String,
163    /// Original display name for the attachment.
164    pub name: String,
165    /// MIME type of the attachment.
166    pub mime_type: String,
167    /// Preview URL for rendering the attachment inline.
168    pub preview_url: Option<String>,
169}
170
171/// Attachment discriminator.
172#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
173#[serde(rename_all = "snake_case")]
174pub enum AttachmentType {
175    Image,
176    File,
177}
178
179/// Model and tool overrides applied when generating the assistant response.
180#[derive(Clone, Serialize, Debug, Deserialize, PartialEq, Default)]
181pub struct InferenceOptions {
182    /// Preferred tool to invoke. Defaults to null when ChatKit should auto-select.
183    #[serde(skip_serializing_if = "Option::is_none")]
184    pub tool_choice: Option<ToolChoice>,
185    /// Model name that generated the response. Defaults to null when using the session default.
186    #[serde(skip_serializing_if = "Option::is_none")]
187    pub model: Option<String>,
188}
189
190/// Tool selection that the assistant should honor when executing the item.
191#[derive(Clone, Serialize, Debug, Deserialize, PartialEq, Default)]
192pub struct ToolChoice {
193    /// Identifier of the requested tool.
194    pub id: String,
195}
196
197/// Assistant-authored message within a thread.
198#[derive(Clone, Serialize, Debug, Deserialize, PartialEq, Default)]
199pub struct AssistantMessageItem {
200    /// Identifier of the thread item.
201    pub id: String,
202    /// Type discriminator that is always `chatkit.thread_item`.
203    #[serde(default = "default_thread_item_object")]
204    pub object: String,
205    /// Unix timestamp (in seconds) for when the item was created.
206    pub created_at: i64,
207    /// Identifier of the parent thread.
208    pub thread_id: String,
209    /// Ordered assistant response segments.
210    pub content: Vec<ResponseOutputText>,
211}
212
213/// Assistant response text accompanied by optional annotations.
214#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
215pub struct ResponseOutputText {
216    /// Type discriminator that is always `output_text`.
217    #[serde(default = "default_output_text_type")]
218    pub r#type: String,
219    /// Assistant generated text.
220    pub text: String,
221    /// Ordered list of annotations attached to the response text.
222    #[serde(default)]
223    pub annotations: Vec<Annotation>,
224}
225
226fn default_output_text_type() -> String {
227    "output_text".to_string()
228}
229
230/// Annotation object describing a cited source.
231#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
232#[serde(tag = "type", rename_all = "snake_case")]
233pub enum Annotation {
234    /// Annotation that references an uploaded file.
235    #[serde(rename = "file")]
236    File(FileAnnotation),
237    /// Annotation that references a URL.
238    #[serde(rename = "url")]
239    Url(UrlAnnotation),
240}
241
242/// Annotation that references an uploaded file.
243#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
244pub struct FileAnnotation {
245    /// Type discriminator that is always `file` for this annotation.
246    #[serde(default = "default_file_annotation_type")]
247    pub r#type: String,
248    /// File attachment referenced by the annotation.
249    pub source: FileAnnotationSource,
250}
251
252fn default_file_annotation_type() -> String {
253    "file".to_string()
254}
255
256/// Attachment source referenced by an annotation.
257#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
258pub struct FileAnnotationSource {
259    /// Type discriminator that is always `file`.
260    #[serde(default = "default_file_source_type")]
261    pub r#type: String,
262    /// Filename referenced by the annotation.
263    pub filename: String,
264}
265
266fn default_file_source_type() -> String {
267    "file".to_string()
268}
269
270/// Annotation that references a URL.
271#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
272pub struct UrlAnnotation {
273    /// Type discriminator that is always `url` for this annotation.
274    #[serde(default = "default_url_annotation_type")]
275    pub r#type: String,
276    /// URL referenced by the annotation.
277    pub source: UrlAnnotationSource,
278}
279
280fn default_url_annotation_type() -> String {
281    "url".to_string()
282}
283
284/// URL backing an annotation entry.
285#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
286pub struct UrlAnnotationSource {
287    /// Type discriminator that is always `url`.
288    #[serde(default = "default_url_source_type")]
289    pub r#type: String,
290    /// URL referenced by the annotation.
291    pub url: String,
292}
293
294fn default_url_source_type() -> String {
295    "url".to_string()
296}
297
298/// Thread item that renders a widget payload.
299#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
300pub struct WidgetMessageItem {
301    /// Identifier of the thread item.
302    pub id: String,
303    /// Type discriminator that is always `chatkit.thread_item`.
304    #[serde(default = "default_thread_item_object")]
305    pub object: String,
306    /// Unix timestamp (in seconds) for when the item was created.
307    pub created_at: i64,
308    /// Identifier of the parent thread.
309    pub thread_id: String,
310    /// Serialized widget payload rendered in the UI.
311    pub widget: String,
312}
313
314/// Record of a client side tool invocation initiated by the assistant.
315#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
316pub struct ClientToolCallItem {
317    /// Identifier of the thread item.
318    pub id: String,
319    /// Type discriminator that is always `chatkit.thread_item`.
320    #[serde(default = "default_thread_item_object")]
321    pub object: String,
322    /// Unix timestamp (in seconds) for when the item was created.
323    pub created_at: i64,
324    /// Identifier of the parent thread.
325    pub thread_id: String,
326    /// Execution status for the tool call.
327    pub status: ClientToolCallStatus,
328    /// Identifier for the client tool call.
329    pub call_id: String,
330    /// Tool name that was invoked.
331    pub name: String,
332    /// JSON-encoded arguments that were sent to the tool.
333    pub arguments: String,
334    /// JSON-encoded output captured from the tool. Defaults to null while execution is in progress.
335    pub output: Option<String>,
336}
337
338/// Execution status for the tool call.
339#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
340#[serde(rename_all = "snake_case")]
341pub enum ClientToolCallStatus {
342    InProgress,
343    Completed,
344}
345
346/// Task emitted by the workflow to show progress and status updates.
347#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
348pub struct TaskItem {
349    /// Identifier of the thread item.
350    pub id: String,
351    /// Type discriminator that is always `chatkit.thread_item`.
352    #[serde(default = "default_thread_item_object")]
353    pub object: String,
354    /// Unix timestamp (in seconds) for when the item was created.
355    pub created_at: i64,
356    /// Identifier of the parent thread.
357    pub thread_id: String,
358    /// Subtype for the task.
359    pub task_type: TaskType,
360    /// Optional heading for the task. Defaults to null when not provided.
361    pub heading: Option<String>,
362    /// Optional summary that describes the task. Defaults to null when omitted.
363    pub summary: Option<String>,
364}
365
366/// Subtype for the task.
367#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
368#[serde(rename_all = "snake_case")]
369pub enum TaskType {
370    Custom,
371    Thought,
372}
373
374/// Collection of workflow tasks grouped together in the thread.
375#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
376pub struct TaskGroupItem {
377    /// Identifier of the thread item.
378    pub id: String,
379    /// Type discriminator that is always `chatkit.thread_item`.
380    #[serde(default = "default_thread_item_object")]
381    pub object: String,
382    /// Unix timestamp (in seconds) for when the item was created.
383    pub created_at: i64,
384    /// Identifier of the parent thread.
385    pub thread_id: String,
386    /// Tasks included in the group.
387    pub tasks: Vec<TaskGroupTask>,
388}
389
390/// Task entry that appears within a TaskGroup.
391#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
392pub struct TaskGroupTask {
393    /// Subtype for the grouped task.
394    pub task_type: TaskType,
395    /// Optional heading for the grouped task. Defaults to null when not provided.
396    pub heading: Option<String>,
397    /// Optional summary that describes the grouped task. Defaults to null when omitted.
398    pub summary: Option<String>,
399}
async_openai/types/chatkit/thread.rs

async_openai/types/chatkit/
thread.rs
