GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

openai/chatkit-python

Public

mirrored from https://github.com/openai/chatkit-pythonAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
adf5a3acbb98602ad839feb58dcee889ef56c3bc

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

chatkit-python/chatkit

chatkit/types.py

879lines · modeblame

RawDownload
Merge pull request #64 from openai/client-side-effect7124c4c
f688d870victor-openai9 months ago1from __future__ import annotations
2
3from datetime import datetime
4from typing import Any, Generic, Literal
5
6from pydantic import AnyUrl, BaseModel, Field
7from typing_extensions import Annotated, TypeIs, TypeVar
8
9from chatkit.errors import ErrorCode
10
11from .actions import Action
9443833fJiwon Kim8 months ago12from .icons import IconName
f688d870victor-openai9 months ago13from .widgets import WidgetComponent, WidgetRoot
14
15T = TypeVar("T")
16
17
18class Page(BaseModel, Generic[T]):
6988ea0avictor-openai9 months ago19"""Paginated collection of records returned from the API."""
20
f688d870victor-openai9 months ago21data: list[T] = []
22has_more: bool = False
23after: str | None = None
24
25
26### REQUEST TYPES
27
28
29class BaseReq(BaseModel):
6988ea0avictor-openai9 months ago30"""Base class for all request payloads."""
31
f688d870victor-openai9 months ago32metadata: dict[str, Any] = Field(default_factory=dict)
33"""Arbitrary integration-specific metadata."""
34
35
36class ThreadsGetByIdReq(BaseReq):
6988ea0avictor-openai9 months ago37"""Request to fetch a single thread by its identifier."""
38
f688d870victor-openai9 months ago39type: Literal["threads.get_by_id"] = "threads.get_by_id"
40params: ThreadGetByIdParams
41
42
43class ThreadGetByIdParams(BaseModel):
6988ea0avictor-openai9 months ago44"""Parameters for retrieving a thread by id."""
45
f688d870victor-openai9 months ago46thread_id: str
47
48
49class ThreadsCreateReq(BaseReq):
6988ea0avictor-openai9 months ago50"""Request to create a new thread from a user message."""
51
f688d870victor-openai9 months ago52type: Literal["threads.create"] = "threads.create"
53params: ThreadCreateParams
54
55
56class ThreadCreateParams(BaseModel):
6988ea0avictor-openai9 months ago57"""User input required to create a thread."""
58
f688d870victor-openai9 months ago59input: UserMessageInput
60
61
62class ThreadListParams(BaseModel):
6988ea0avictor-openai9 months ago63"""Pagination parameters for listing threads."""
64
f688d870victor-openai9 months ago65limit: int | None = None
66order: Literal["asc", "desc"] = "desc"
67after: str | None = None
68
69
70class ThreadsListReq(BaseReq):
6988ea0avictor-openai9 months ago71"""Request to list threads."""
72
f688d870victor-openai9 months ago73type: Literal["threads.list"] = "threads.list"
74params: ThreadListParams
75
76
77class ThreadsAddUserMessageReq(BaseReq):
6988ea0avictor-openai9 months ago78"""Request to append a user message to a thread."""
79
f688d870victor-openai9 months ago80type: Literal["threads.add_user_message"] = "threads.add_user_message"
81params: ThreadAddUserMessageParams
82
83
84class ThreadAddUserMessageParams(BaseModel):
6988ea0avictor-openai9 months ago85"""Parameters for adding a user message to a thread."""
86
f688d870victor-openai9 months ago87input: UserMessageInput
88thread_id: str
89
90
91class ThreadsAddClientToolOutputReq(BaseReq):
6988ea0avictor-openai9 months ago92"""Request to add a client tool's output to a thread."""
93
f688d870victor-openai9 months ago94type: Literal["threads.add_client_tool_output"] = "threads.add_client_tool_output"
95params: ThreadAddClientToolOutputParams
96
97
98class ThreadAddClientToolOutputParams(BaseModel):
6988ea0avictor-openai9 months ago99"""Parameters for recording tool output in a thread."""
100
f688d870victor-openai9 months ago101thread_id: str
102result: Any
103
104
105class ThreadsCustomActionReq(BaseReq):
6988ea0avictor-openai9 months ago106"""Request to execute a custom action within a thread."""
107
f688d870victor-openai9 months ago108type: Literal["threads.custom_action"] = "threads.custom_action"
109params: ThreadCustomActionParams
110
111
112class ThreadCustomActionParams(BaseModel):
6988ea0avictor-openai9 months ago113"""Parameters describing the custom action to execute."""
114
f688d870victor-openai9 months ago115thread_id: str
116item_id: str | None = None
117action: Action[str, Any]
118
119
120class ThreadsRetryAfterItemReq(BaseReq):
6988ea0avictor-openai9 months ago121"""Request to retry processing after a specific thread item."""
122
f688d870victor-openai9 months ago123type: Literal["threads.retry_after_item"] = "threads.retry_after_item"
124params: ThreadRetryAfterItemParams
125
126
127class ThreadRetryAfterItemParams(BaseModel):
6988ea0avictor-openai9 months ago128"""Parameters specifying which item to retry."""
129
f688d870victor-openai9 months ago130thread_id: str
131item_id: str
132
133
134class ItemsFeedbackReq(BaseReq):
6988ea0avictor-openai9 months ago135"""Request to submit feedback on specific items."""
136
f688d870victor-openai9 months ago137type: Literal["items.feedback"] = "items.feedback"
138params: ItemFeedbackParams
139
140
141class ItemFeedbackParams(BaseModel):
6988ea0avictor-openai9 months ago142"""Parameters describing feedback targets and sentiment."""
143
f688d870victor-openai9 months ago144thread_id: str
145item_ids: list[str]
146kind: FeedbackKind
147
148
149class AttachmentsDeleteReq(BaseReq):
6988ea0avictor-openai9 months ago150"""Request to remove an attachment."""
151
f688d870victor-openai9 months ago152type: Literal["attachments.delete"] = "attachments.delete"
153params: AttachmentDeleteParams
154
155
156class AttachmentDeleteParams(BaseModel):
6988ea0avictor-openai9 months ago157"""Parameters identifying an attachment to delete."""
158
f688d870victor-openai9 months ago159attachment_id: str
160
161
162class AttachmentsCreateReq(BaseReq):
6988ea0avictor-openai9 months ago163"""Request to register a new attachment."""
164
f688d870victor-openai9 months ago165type: Literal["attachments.create"] = "attachments.create"
166params: AttachmentCreateParams
167
168
169class AttachmentCreateParams(BaseModel):
6988ea0avictor-openai9 months ago170"""Metadata needed to initialize an attachment."""
171
f688d870victor-openai9 months ago172name: str
173size: int
174mime_type: str
175
176
177class ItemsListReq(BaseReq):
6988ea0avictor-openai9 months ago178"""Request to list items inside a thread."""
179
f688d870victor-openai9 months ago180type: Literal["items.list"] = "items.list"
181params: ItemsListParams
182
183
184class ItemsListParams(BaseModel):
6988ea0avictor-openai9 months ago185"""Pagination parameters for listing thread items."""
186
f688d870victor-openai9 months ago187thread_id: str
188limit: int | None = None
189order: Literal["asc", "desc"] = "desc"
190after: str | None = None
191
192
193class ThreadsUpdateReq(BaseReq):
6988ea0avictor-openai9 months ago194"""Request to update thread metadata."""
195
f688d870victor-openai9 months ago196type: Literal["threads.update"] = "threads.update"
197params: ThreadUpdateParams
198
199
200class ThreadUpdateParams(BaseModel):
6988ea0avictor-openai9 months ago201"""Parameters for updating a thread's properties."""
202
f688d870victor-openai9 months ago203thread_id: str
204title: str
205
206
207class ThreadsDeleteReq(BaseReq):
6988ea0avictor-openai9 months ago208"""Request to delete a thread."""
209
f688d870victor-openai9 months ago210type: Literal["threads.delete"] = "threads.delete"
211params: ThreadDeleteParams
212
213
214class ThreadDeleteParams(BaseModel):
6988ea0avictor-openai9 months ago215"""Parameters identifying a thread to delete."""
216
f688d870victor-openai9 months ago217thread_id: str
218
219
220StreamingReq = (
221ThreadsCreateReq
222| ThreadsAddUserMessageReq
223| ThreadsAddClientToolOutputReq
224| ThreadsRetryAfterItemReq
225| ThreadsCustomActionReq
226)
6988ea0avictor-openai9 months ago227"""Union of request types that produce streaming responses."""
228
f688d870victor-openai9 months ago229
230NonStreamingReq = (
231ThreadsGetByIdReq
232| ThreadsListReq
233| ItemsListReq
234| ItemsFeedbackReq
235| AttachmentsCreateReq
236| AttachmentsDeleteReq
237| ThreadsUpdateReq
238| ThreadsDeleteReq
239)
6988ea0avictor-openai9 months ago240"""Union of request types that yield immediate responses."""
241
f688d870victor-openai9 months ago242
243ChatKitReq = Annotated[
244StreamingReq | NonStreamingReq,
245Field(discriminator="type"),
246]
247
248
249def is_streaming_req(request: ChatKitReq) -> TypeIs[StreamingReq]:
6988ea0avictor-openai9 months ago250"""Return True if the given request should be processed as streaming."""
f688d870victor-openai9 months ago251return isinstance(
252request,
253(
254ThreadsCreateReq,
255ThreadsAddUserMessageReq,
256ThreadsRetryAfterItemReq,
257ThreadsAddClientToolOutputReq,
258ThreadsCustomActionReq,
259),
260)
261
262
263### THREAD STREAM EVENT TYPES
264
265
266class ThreadCreatedEvent(BaseModel):
6988ea0avictor-openai9 months ago267"""Event emitted when a thread is created."""
aa7ec072victor-openai9 months ago268
f688d870victor-openai9 months ago269type: Literal["thread.created"] = "thread.created"
270thread: Thread
271
272
273class ThreadUpdatedEvent(BaseModel):
6988ea0avictor-openai9 months ago274"""Event emitted when a thread is updated."""
aa7ec072victor-openai9 months ago275
f688d870victor-openai9 months ago276type: Literal["thread.updated"] = "thread.updated"
277thread: Thread
278
279
280class ThreadItemAddedEvent(BaseModel):
6988ea0avictor-openai9 months ago281"""Event emitted when a new item is added to a thread."""
aa7ec072victor-openai9 months ago282
f688d870victor-openai9 months ago283type: Literal["thread.item.added"] = "thread.item.added"
284item: ThreadItem
285
286
7861b9a0Jiwon Kim7 months ago287class ThreadItemUpdatedEvent(BaseModel):
6988ea0avictor-openai9 months ago288"""Event describing an update to an existing thread item."""
aa7ec072victor-openai9 months ago289
f688d870victor-openai9 months ago290type: Literal["thread.item.updated"] = "thread.item.updated"
291item_id: str
292update: ThreadItemUpdate
293
294
7861b9a0Jiwon Kim7 months ago295# Type alias for backwards compatibility
296ThreadItemUpdated = ThreadItemUpdatedEvent
297
298
f688d870victor-openai9 months ago299class ThreadItemDoneEvent(BaseModel):
6988ea0avictor-openai9 months ago300"""Event emitted when a thread item is marked complete."""
aa7ec072victor-openai9 months ago301
f688d870victor-openai9 months ago302type: Literal["thread.item.done"] = "thread.item.done"
303item: ThreadItem
304
305
306class ThreadItemRemovedEvent(BaseModel):
6988ea0avictor-openai9 months ago307"""Event emitted when a thread item is removed."""
aa7ec072victor-openai9 months ago308
f688d870victor-openai9 months ago309type: Literal["thread.item.removed"] = "thread.item.removed"
310item_id: str
311
312
313class ThreadItemReplacedEvent(BaseModel):
6988ea0avictor-openai9 months ago314"""Event emitted when a thread item is replaced."""
aa7ec072victor-openai9 months ago315
f688d870victor-openai9 months ago316type: Literal["thread.item.replaced"] = "thread.item.replaced"
317item: ThreadItem
318
319
5a7244baJiwon Kim7 months ago320class StreamOptions(BaseModel):
321"""Settings that control runtime stream behavior."""
322
323allow_cancel: bool
324"""Allow the client to request cancellation mid-stream."""
325
326
327class StreamOptionsEvent(BaseModel):
328"""Event emitted to set stream options at runtime."""
329
330type: Literal["stream_options"] = "stream_options"
331stream_options: StreamOptions
332
333
f688d870victor-openai9 months ago334class ProgressUpdateEvent(BaseModel):
6988ea0avictor-openai9 months ago335"""Event providing incremental progress from the assistant."""
aa7ec072victor-openai9 months ago336
f688d870victor-openai9 months ago337type: Literal["progress_update"] = "progress_update"
338icon: IconName | None = None
339text: str
340
341
a3c67d60Jiwon Kim7 months ago342class ClientEffectEvent(BaseModel):
343"""Event emitted to trigger a client side-effect."""
12dd5dd5Jiwon Kim7 months ago344
a3c67d60Jiwon Kim7 months ago345type: Literal["client_effect"] = "client_effect"
12dd5dd5Jiwon Kim7 months ago346name: str
347data: dict[str, Any] = Field(default_factory=dict)
348
349
f688d870victor-openai9 months ago350class ErrorEvent(BaseModel):
6988ea0avictor-openai9 months ago351"""Event indicating an error occurred while processing a thread."""
aa7ec072victor-openai9 months ago352
f688d870victor-openai9 months ago353type: Literal["error"] = "error"
354code: ErrorCode | Literal["custom"] = Field(default="custom")
355message: str | None = None
356allow_retry: bool = Field(default=False)
357
358
359class NoticeEvent(BaseModel):
6988ea0avictor-openai9 months ago360"""Event conveying a user-facing notice."""
aa7ec072victor-openai9 months ago361
f688d870victor-openai9 months ago362type: Literal["notice"] = "notice"
363level: Literal["info", "warning", "danger"]
364message: str
365"""
366Supports markdown e.g. "You've reached your limit of 100 messages. [Upgrade](https://...) to a paid plan."
367"""
368title: str | None = None
369
370
371ThreadStreamEvent = Annotated[
372ThreadCreatedEvent
373| ThreadUpdatedEvent
374| ThreadItemDoneEvent
375| ThreadItemAddedEvent
376| ThreadItemUpdated
377| ThreadItemRemovedEvent
378| ThreadItemReplacedEvent
5a7244baJiwon Kim7 months ago379| StreamOptionsEvent
f688d870victor-openai9 months ago380| ProgressUpdateEvent
a3c67d60Jiwon Kim7 months ago381| ClientEffectEvent
f688d870victor-openai9 months ago382| ErrorEvent
383| NoticeEvent,
384Field(discriminator="type"),
385]
6988ea0avictor-openai9 months ago386"""Union of all streaming events emitted to clients."""
f688d870victor-openai9 months ago387
388### THREAD ITEM UPDATE TYPES
389
390
391class AssistantMessageContentPartAdded(BaseModel):
6988ea0avictor-openai9 months ago392"""Event emitted when new assistant content is appended."""
aa7ec072victor-openai9 months ago393
f688d870victor-openai9 months ago394type: Literal["assistant_message.content_part.added"] = (
395"assistant_message.content_part.added"
396)
397content_index: int
398content: AssistantMessageContent
399
400
401class AssistantMessageContentPartTextDelta(BaseModel):
6988ea0avictor-openai9 months ago402"""Event carrying incremental assistant text output."""
aa7ec072victor-openai9 months ago403
f688d870victor-openai9 months ago404type: Literal["assistant_message.content_part.text_delta"] = (
405"assistant_message.content_part.text_delta"
406)
407content_index: int
408delta: str
409
410
411class AssistantMessageContentPartAnnotationAdded(BaseModel):
6988ea0avictor-openai9 months ago412"""Event announcing a new annotation on assistant content."""
aa7ec072victor-openai9 months ago413
f688d870victor-openai9 months ago414type: Literal["assistant_message.content_part.annotation_added"] = (
415"assistant_message.content_part.annotation_added"
416)
417content_index: int
418annotation_index: int
419annotation: Annotation
420
421
422class AssistantMessageContentPartDone(BaseModel):
6988ea0avictor-openai9 months ago423"""Event indicating an assistant content part is finalized."""
aa7ec072victor-openai9 months ago424
f688d870victor-openai9 months ago425type: Literal["assistant_message.content_part.done"] = (
426"assistant_message.content_part.done"
427)
428content_index: int
429content: AssistantMessageContent
430
431
432class WidgetStreamingTextValueDelta(BaseModel):
6988ea0avictor-openai9 months ago433"""Event streaming widget text deltas."""
aa7ec072victor-openai9 months ago434
f688d870victor-openai9 months ago435type: Literal["widget.streaming_text.value_delta"] = (
436"widget.streaming_text.value_delta"
437)
438component_id: str
439delta: str
440done: bool
441
442
443class WidgetRootUpdated(BaseModel):
6988ea0avictor-openai9 months ago444"""Event published when the widget root changes."""
aa7ec072victor-openai9 months ago445
f688d870victor-openai9 months ago446type: Literal["widget.root.updated"] = "widget.root.updated"
447widget: WidgetRoot
448
449
450class WidgetComponentUpdated(BaseModel):
6988ea0avictor-openai9 months ago451"""Event emitted when a widget component updates."""
aa7ec072victor-openai9 months ago452
f688d870victor-openai9 months ago453type: Literal["widget.component.updated"] = "widget.component.updated"
454component_id: str
455component: WidgetComponent
456
457
458class WorkflowTaskAdded(BaseModel):
6988ea0avictor-openai9 months ago459"""Event emitted when a workflow task is added."""
aa7ec072victor-openai9 months ago460
f688d870victor-openai9 months ago461type: Literal["workflow.task.added"] = "workflow.task.added"
462task_index: int
463task: Task
464
465
466class WorkflowTaskUpdated(BaseModel):
6988ea0avictor-openai9 months ago467"""Event emitted when a workflow task is updated."""
aa7ec072victor-openai9 months ago468
f688d870victor-openai9 months ago469type: Literal["workflow.task.updated"] = "workflow.task.updated"
470task_index: int
471task: Task
472
473
474ThreadItemUpdate = (
475AssistantMessageContentPartAdded
476| AssistantMessageContentPartTextDelta
477| AssistantMessageContentPartAnnotationAdded
478| AssistantMessageContentPartDone
479| WidgetStreamingTextValueDelta
480| WidgetComponentUpdated
481| WidgetRootUpdated
482| WorkflowTaskAdded
483| WorkflowTaskUpdated
484)
6988ea0avictor-openai9 months ago485"""Union of possible updates applied to thread items."""
f688d870victor-openai9 months ago486
487
488### THREAD TYPES
489
490
491class ThreadMetadata(BaseModel):
6988ea0avictor-openai9 months ago492"""Metadata describing a thread without its items."""
aa7ec072victor-openai9 months ago493
f688d870victor-openai9 months ago494title: str | None = None
495id: str
496created_at: datetime
497status: ThreadStatus = Field(default_factory=lambda: ActiveStatus())
498# TODO - make not client rendered
499metadata: dict[str, Any] = Field(default_factory=dict)
500
501
502class ActiveStatus(BaseModel):
6988ea0avictor-openai9 months ago503"""Status indicating the thread is active."""
aa7ec072victor-openai9 months ago504
f688d870victor-openai9 months ago505type: Literal["active"] = Field(default="active", frozen=True)
506
507
508class LockedStatus(BaseModel):
6988ea0avictor-openai9 months ago509"""Status indicating the thread is locked."""
aa7ec072victor-openai9 months ago510
f688d870victor-openai9 months ago511type: Literal["locked"] = Field(default="locked", frozen=True)
512reason: str | None = None
513
514
515class ClosedStatus(BaseModel):
6988ea0avictor-openai9 months ago516"""Status indicating the thread is closed."""
aa7ec072victor-openai9 months ago517
f688d870victor-openai9 months ago518type: Literal["closed"] = Field(default="closed", frozen=True)
519reason: str | None = None
520
521
522ThreadStatus = Annotated[
523ActiveStatus | LockedStatus | ClosedStatus,
524Field(discriminator="type"),
525]
6988ea0avictor-openai9 months ago526"""Union of lifecycle states for a thread."""
f688d870victor-openai9 months ago527
528
529class Thread(ThreadMetadata):
6988ea0avictor-openai9 months ago530"""Thread with its paginated items."""
aa7ec072victor-openai9 months ago531
f688d870victor-openai9 months ago532items: Page[ThreadItem]
533
534
535### THREAD ITEM TYPES
536
537
538class ThreadItemBase(BaseModel):
6988ea0avictor-openai9 months ago539"""Base fields shared by all thread items."""
aa7ec072victor-openai9 months ago540
f688d870victor-openai9 months ago541id: str
542thread_id: str
543created_at: datetime
544
545
546class UserMessageItem(ThreadItemBase):
6988ea0avictor-openai9 months ago547"""Thread item representing a user message."""
aa7ec072victor-openai9 months ago548
f688d870victor-openai9 months ago549type: Literal["user_message"] = "user_message"
550content: list[UserMessageContent]
551attachments: list[Attachment] = Field(default_factory=list)
552quoted_text: str | None = None
553inference_options: InferenceOptions
554
555
556class AssistantMessageItem(ThreadItemBase):
6988ea0avictor-openai9 months ago557"""Thread item representing an assistant message."""
aa7ec072victor-openai9 months ago558
f688d870victor-openai9 months ago559type: Literal["assistant_message"] = "assistant_message"
560content: list[AssistantMessageContent]
561
562
563class ClientToolCallItem(ThreadItemBase):
6988ea0avictor-openai9 months ago564"""Thread item capturing a client tool call."""
aa7ec072victor-openai9 months ago565
f688d870victor-openai9 months ago566type: Literal["client_tool_call"] = "client_tool_call"
567status: Literal["pending", "completed"] = "pending"
568call_id: str
569name: str
570arguments: dict[str, Any]
571output: Any | None = None
572
573
574class WidgetItem(ThreadItemBase):
6988ea0avictor-openai9 months ago575"""Thread item containing widget content."""
aa7ec072victor-openai9 months ago576
f688d870victor-openai9 months ago577type: Literal["widget"] = "widget"
578widget: WidgetRoot
579copy_text: str | None = None
580
581
582class TaskItem(ThreadItemBase):
6988ea0avictor-openai9 months ago583"""Thread item containing a task."""
aa7ec072victor-openai9 months ago584
f688d870victor-openai9 months ago585type: Literal["task"] = "task"
586task: Task
587
588
589class WorkflowItem(ThreadItemBase):
6988ea0avictor-openai9 months ago590"""Thread item representing a workflow."""
aa7ec072victor-openai9 months ago591
f688d870victor-openai9 months ago592type: Literal["workflow"] = "workflow"
593workflow: Workflow
594
595
596class EndOfTurnItem(ThreadItemBase):
6988ea0avictor-openai9 months ago597"""Marker item indicating the assistant ends its turn."""
aa7ec072victor-openai9 months ago598
f688d870victor-openai9 months ago599type: Literal["end_of_turn"] = "end_of_turn"
600
601
602class HiddenContextItem(ThreadItemBase):
5a7244baJiwon Kim7 months ago603"""
604HiddenContext is never sent to the client. It's not officially part of ChatKit.js.
605It is only used internally to store additional context in a specific place in the thread.
606"""
f688d870victor-openai9 months ago607
608type: Literal["hidden_context_item"] = "hidden_context_item"
609content: Any
610
611
5a7244baJiwon Kim7 months ago612class SDKHiddenContextItem(ThreadItemBase):
613"""
614Hidden context that is used by the ChatKit Python SDK for storing additional context
615for internal operations.
616"""
617
618type: Literal["sdk_hidden_context"] = "sdk_hidden_context"
619content: str
620
621
f688d870victor-openai9 months ago622ThreadItem = Annotated[
623UserMessageItem
624| AssistantMessageItem
625| ClientToolCallItem
626| WidgetItem
627| WorkflowItem
628| TaskItem
629| HiddenContextItem
5a7244baJiwon Kim7 months ago630| SDKHiddenContextItem
f688d870victor-openai9 months ago631| EndOfTurnItem,
632Field(discriminator="type"),
633]
6988ea0avictor-openai9 months ago634"""Union of all thread item variants."""
f688d870victor-openai9 months ago635
636
637### ASSISTANT MESSAGE TYPES
638
639
640class AssistantMessageContent(BaseModel):
6988ea0avictor-openai9 months ago641"""Assistant message content consisting of text and annotations."""
aa7ec072victor-openai9 months ago642
f688d870victor-openai9 months ago643annotations: list[Annotation] = Field(default_factory=list)
644text: str
645type: Literal["output_text"] = "output_text"
646
647
648class Annotation(BaseModel):
6988ea0avictor-openai9 months ago649"""Reference to supporting context attached to assistant output."""
aa7ec072victor-openai9 months ago650
f688d870victor-openai9 months ago651type: Literal["annotation"] = "annotation"
652source: URLSource | FileSource | EntitySource
653index: int | None = None
654
655
656### USER MESSAGE TYPES
657
658
659class UserMessageInput(BaseModel):
6988ea0avictor-openai9 months ago660"""Payload describing a user message submission."""
aa7ec072victor-openai9 months ago661
f688d870victor-openai9 months ago662content: list[UserMessageContent]
663attachments: list[str]
664quoted_text: str | None = None
665inference_options: InferenceOptions
666
667
668class UserMessageTextContent(BaseModel):
6988ea0avictor-openai9 months ago669"""User message content containing plaintext."""
aa7ec072victor-openai9 months ago670
f688d870victor-openai9 months ago671type: Literal["input_text"] = "input_text"
672text: str
673
674
675class UserMessageTagContent(BaseModel):
6988ea0avictor-openai9 months ago676"""User message content representing an interactive tag."""
aa7ec072victor-openai9 months ago677
f688d870victor-openai9 months ago678type: Literal["input_tag"] = "input_tag"
679id: str
680text: str
681data: dict[str, Any]
ec580cbaJiwon Kim7 months ago682group: str | None = None
f688d870victor-openai9 months ago683interactive: bool = False
684
685
686UserMessageContent = Annotated[
687UserMessageTextContent | UserMessageTagContent, Field(discriminator="type")
688]
6988ea0avictor-openai9 months ago689"""Union of allowed user message content payloads."""
f688d870victor-openai9 months ago690
691
692class InferenceOptions(BaseModel):
6988ea0avictor-openai9 months ago693"""Model and tool configuration for message processing."""
aa7ec072victor-openai9 months ago694
f688d870victor-openai9 months ago695tool_choice: ToolChoice | None = None
696model: str | None = None
697
698
699class ToolChoice(BaseModel):
6988ea0avictor-openai9 months ago700"""Explicit tool selection for the assistant to invoke."""
aa7ec072victor-openai9 months ago701
f688d870victor-openai9 months ago702id: str
703
704
705class AttachmentBase(BaseModel):
6988ea0avictor-openai9 months ago706"""Base metadata shared by all attachments."""
aa7ec072victor-openai9 months ago707
f688d870victor-openai9 months ago708id: str
709name: str
710mime_type: str
711upload_url: AnyUrl | None = None
712"""
713The URL to upload the file, used for two-phase upload.
714Should be set to None after upload is complete or when using direct upload where uploading happens when creating the attachment object.
715"""
716
717
718class FileAttachment(AttachmentBase):
6988ea0avictor-openai9 months ago719"""Attachment representing a generic file."""
aa7ec072victor-openai9 months ago720
f688d870victor-openai9 months ago721type: Literal["file"] = "file"
722
723
724class ImageAttachment(AttachmentBase):
6988ea0avictor-openai9 months ago725"""Attachment representing an image resource."""
aa7ec072victor-openai9 months ago726
f688d870victor-openai9 months ago727type: Literal["image"] = "image"
728preview_url: AnyUrl
729
730
731Attachment = Annotated[
732FileAttachment | ImageAttachment,
733Field(discriminator="type"),
734]
6988ea0avictor-openai9 months ago735"""Union of supported attachment types."""
f688d870victor-openai9 months ago736
737
738### WORKFLOW TYPES
739
740
741class Workflow(BaseModel):
6988ea0avictor-openai9 months ago742"""Workflow attached to a thread with optional summary."""
aa7ec072victor-openai9 months ago743
f688d870victor-openai9 months ago744type: Literal["custom", "reasoning"]
745tasks: list[Task]
746summary: WorkflowSummary | None = None
747expanded: bool = False
748
749
750class CustomSummary(BaseModel):
6988ea0avictor-openai9 months ago751"""Custom summary for a workflow."""
aa7ec072victor-openai9 months ago752
f688d870victor-openai9 months ago753title: str
c9f5f09dJiwon Kim9 months ago754icon: IconName | None = None
f688d870victor-openai9 months ago755
756
757class DurationSummary(BaseModel):
6988ea0avictor-openai9 months ago758"""Summary providing total workflow duration."""
aa7ec072victor-openai9 months ago759
f688d870victor-openai9 months ago760duration: int
761"""The duration of the workflow in seconds"""
762
763
764WorkflowSummary = CustomSummary | DurationSummary
6988ea0avictor-openai9 months ago765"""Summary variants available for workflows."""
f688d870victor-openai9 months ago766
767### TASK TYPES
768
769
770class BaseTask(BaseModel):
6988ea0avictor-openai9 months ago771"""Base fields common to all workflow tasks."""
aa7ec072victor-openai9 months ago772
f688d870victor-openai9 months ago773status_indicator: Literal["none", "loading", "complete"] = "none"
774"""Only used when rendering the task as part of a workflow. Indicates the status of the task."""
775
776
777class CustomTask(BaseTask):
6988ea0avictor-openai9 months ago778"""Workflow task displaying custom content."""
aa7ec072victor-openai9 months ago779
f688d870victor-openai9 months ago780type: Literal["custom"] = "custom"
781title: str | None = None
c9f5f09dJiwon Kim9 months ago782icon: IconName | None = None
f688d870victor-openai9 months ago783content: str | None = None
784
785
786class SearchTask(BaseTask):
6988ea0avictor-openai9 months ago787"""Workflow task representing a web search."""
aa7ec072victor-openai9 months ago788
f688d870victor-openai9 months ago789type: Literal["web_search"] = "web_search"
790title: str | None = None
791title_query: str | None = None
792queries: list[str] = Field(default_factory=list)
793sources: list[URLSource] = Field(default_factory=list)
794
795
796class ThoughtTask(BaseTask):
6988ea0avictor-openai9 months ago797"""Workflow task capturing assistant reasoning."""
aa7ec072victor-openai9 months ago798
f688d870victor-openai9 months ago799type: Literal["thought"] = "thought"
800title: str | None = None
801content: str
802
803
804class FileTask(BaseTask):
6988ea0avictor-openai9 months ago805"""Workflow task referencing file sources."""
aa7ec072victor-openai9 months ago806
f688d870victor-openai9 months ago807type: Literal["file"] = "file"
808title: str | None = None
809sources: list[FileSource] = Field(default_factory=list)
810
811
812class ImageTask(BaseTask):
6988ea0avictor-openai9 months ago813"""Workflow task rendering image content."""
aa7ec072victor-openai9 months ago814
f688d870victor-openai9 months ago815type: Literal["image"] = "image"
816title: str | None = None
817
818
819Task = Annotated[
820CustomTask | SearchTask | ThoughtTask | FileTask | ImageTask,
821Field(discriminator="type"),
822]
6988ea0avictor-openai9 months ago823"""Union of workflow task variants."""
f688d870victor-openai9 months ago824
825
826### SOURCE TYPES
827
828
829class SourceBase(BaseModel):
6988ea0avictor-openai9 months ago830"""Base class for sources displayed to users."""
aa7ec072victor-openai9 months ago831
f688d870victor-openai9 months ago832title: str
833description: str | None = None
834timestamp: str | None = None
835group: str | None = None
836
837
838class FileSource(SourceBase):
6988ea0avictor-openai9 months ago839"""Source metadata for file-based references."""
aa7ec072victor-openai9 months ago840
f688d870victor-openai9 months ago841type: Literal["file"] = "file"
842filename: str
843
844
845class URLSource(SourceBase):
6988ea0avictor-openai9 months ago846"""Source metadata for external URLs."""
aa7ec072victor-openai9 months ago847
f688d870victor-openai9 months ago848type: Literal["url"] = "url"
849url: str
850attribution: str | None = None
851
852
853class EntitySource(SourceBase):
6988ea0avictor-openai9 months ago854"""Source metadata for entity references."""
aa7ec072victor-openai9 months ago855
f688d870victor-openai9 months ago856type: Literal["entity"] = "entity"
857id: str
c9f5f09dJiwon Kim9 months ago858icon: IconName | None = None
c47e7701jiwon-oai9 months ago859data: dict[str, Any] = Field(default_factory=dict)
f688d870victor-openai9 months ago860
ec580cbaJiwon Kim7 months ago861preview: Literal["lazy"] | None = Field(
862default=None,
863deprecated=True,
864description="This field is ignored. Please use the entities.onRequestPreview ChatKit.js option instead.",
865)
866
f688d870victor-openai9 months ago867
6988ea0avictor-openai9 months ago868Source = Annotated[
869URLSource | FileSource | EntitySource,
870Field(discriminator="type"),
871]
872"""Union of supported source types."""
f688d870victor-openai9 months ago873
874
875### MISC TYPES
876
877
878FeedbackKind = Literal["positive", "negative"]
6988ea0avictor-openai9 months ago879"""Literal type for feedback sentiment."""