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
v1.5.0

Branches

Tags

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

Clone

HTTPS

Download ZIP

chatkit-python/chatkit

chatkit/types.py

923lines · modeblame

RawDownload
Latest commit unavailable.
f688d870victor-openai8 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 Kim7 months ago12from .icons import IconName
f688d870victor-openai8 months ago13from .widgets import WidgetComponent, WidgetRoot
14
15T = TypeVar("T")
16
17
18class Page(BaseModel, Generic[T]):
6988ea0avictor-openai8 months ago19"""Paginated collection of records returned from the API."""
20
f688d870victor-openai8 months ago21data: list[T] = []
22has_more: bool = False
23after: str | None = None
24
25
26### REQUEST TYPES
27
28
29class BaseReq(BaseModel):
6988ea0avictor-openai8 months ago30"""Base class for all request payloads."""
31
f688d870victor-openai8 months ago32metadata: dict[str, Any] = Field(default_factory=dict)
33"""Arbitrary integration-specific metadata."""
34
35
36class ThreadsGetByIdReq(BaseReq):
6988ea0avictor-openai8 months ago37"""Request to fetch a single thread by its identifier."""
38
f688d870victor-openai8 months ago39type: Literal["threads.get_by_id"] = "threads.get_by_id"
40params: ThreadGetByIdParams
41
42
43class ThreadGetByIdParams(BaseModel):
6988ea0avictor-openai8 months ago44"""Parameters for retrieving a thread by id."""
45
f688d870victor-openai8 months ago46thread_id: str
47
48
49class ThreadsCreateReq(BaseReq):
6988ea0avictor-openai8 months ago50"""Request to create a new thread from a user message."""
51
f688d870victor-openai8 months ago52type: Literal["threads.create"] = "threads.create"
53params: ThreadCreateParams
54
55
56class ThreadCreateParams(BaseModel):
6988ea0avictor-openai8 months ago57"""User input required to create a thread."""
58
f688d870victor-openai8 months ago59input: UserMessageInput
60
61
62class ThreadListParams(BaseModel):
6988ea0avictor-openai8 months ago63"""Pagination parameters for listing threads."""
64
f688d870victor-openai8 months ago65limit: int | None = None
66order: Literal["asc", "desc"] = "desc"
67after: str | None = None
68
69
70class ThreadsListReq(BaseReq):
6988ea0avictor-openai8 months ago71"""Request to list threads."""
72
f688d870victor-openai8 months ago73type: Literal["threads.list"] = "threads.list"
74params: ThreadListParams
75
76
77class ThreadsAddUserMessageReq(BaseReq):
6988ea0avictor-openai8 months ago78"""Request to append a user message to a thread."""
79
f688d870victor-openai8 months ago80type: Literal["threads.add_user_message"] = "threads.add_user_message"
81params: ThreadAddUserMessageParams
82
83
84class ThreadAddUserMessageParams(BaseModel):
6988ea0avictor-openai8 months ago85"""Parameters for adding a user message to a thread."""
86
f688d870victor-openai8 months ago87input: UserMessageInput
88thread_id: str
89
90
91class ThreadsAddClientToolOutputReq(BaseReq):
6988ea0avictor-openai8 months ago92"""Request to add a client tool's output to a thread."""
93
f688d870victor-openai8 months ago94type: Literal["threads.add_client_tool_output"] = "threads.add_client_tool_output"
95params: ThreadAddClientToolOutputParams
96
97
98class ThreadAddClientToolOutputParams(BaseModel):
6988ea0avictor-openai8 months ago99"""Parameters for recording tool output in a thread."""
100
f688d870victor-openai8 months ago101thread_id: str
102result: Any
103
104
105class ThreadsCustomActionReq(BaseReq):
6988ea0avictor-openai8 months ago106"""Request to execute a custom action within a thread."""
107
f688d870victor-openai8 months ago108type: Literal["threads.custom_action"] = "threads.custom_action"
109params: ThreadCustomActionParams
110
111
112class ThreadCustomActionParams(BaseModel):
6988ea0avictor-openai8 months ago113"""Parameters describing the custom action to execute."""
114
f688d870victor-openai8 months ago115thread_id: str
116item_id: str | None = None
117action: Action[str, Any]
118
119
120class ThreadsRetryAfterItemReq(BaseReq):
6988ea0avictor-openai8 months ago121"""Request to retry processing after a specific thread item."""
122
f688d870victor-openai8 months ago123type: Literal["threads.retry_after_item"] = "threads.retry_after_item"
124params: ThreadRetryAfterItemParams
125
126
127class ThreadRetryAfterItemParams(BaseModel):
6988ea0avictor-openai8 months ago128"""Parameters specifying which item to retry."""
129
f688d870victor-openai8 months ago130thread_id: str
131item_id: str
132
133
134class ItemsFeedbackReq(BaseReq):
6988ea0avictor-openai8 months ago135"""Request to submit feedback on specific items."""
136
f688d870victor-openai8 months ago137type: Literal["items.feedback"] = "items.feedback"
138params: ItemFeedbackParams
139
140
141class ItemFeedbackParams(BaseModel):
6988ea0avictor-openai8 months ago142"""Parameters describing feedback targets and sentiment."""
143
f688d870victor-openai8 months ago144thread_id: str
145item_ids: list[str]
146kind: FeedbackKind
147
148
149class AttachmentsDeleteReq(BaseReq):
6988ea0avictor-openai8 months ago150"""Request to remove an attachment."""
151
f688d870victor-openai8 months ago152type: Literal["attachments.delete"] = "attachments.delete"
153params: AttachmentDeleteParams
154
155
156class AttachmentDeleteParams(BaseModel):
6988ea0avictor-openai8 months ago157"""Parameters identifying an attachment to delete."""
158
f688d870victor-openai8 months ago159attachment_id: str
160
161
162class AttachmentsCreateReq(BaseReq):
6988ea0avictor-openai8 months ago163"""Request to register a new attachment."""
164
f688d870victor-openai8 months ago165type: Literal["attachments.create"] = "attachments.create"
166params: AttachmentCreateParams
167
168
169class AttachmentCreateParams(BaseModel):
6988ea0avictor-openai8 months ago170"""Metadata needed to initialize an attachment."""
171
f688d870victor-openai8 months ago172name: str
173size: int
174mime_type: str
175
176
177class ItemsListReq(BaseReq):
6988ea0avictor-openai8 months ago178"""Request to list items inside a thread."""
179
f688d870victor-openai8 months ago180type: Literal["items.list"] = "items.list"
181params: ItemsListParams
182
183
184class ItemsListParams(BaseModel):
6988ea0avictor-openai8 months ago185"""Pagination parameters for listing thread items."""
186
f688d870victor-openai8 months ago187thread_id: str
188limit: int | None = None
189order: Literal["asc", "desc"] = "desc"
190after: str | None = None
191
192
193class ThreadsUpdateReq(BaseReq):
6988ea0avictor-openai8 months ago194"""Request to update thread metadata."""
195
f688d870victor-openai8 months ago196type: Literal["threads.update"] = "threads.update"
197params: ThreadUpdateParams
198
199
200class ThreadUpdateParams(BaseModel):
6988ea0avictor-openai8 months ago201"""Parameters for updating a thread's properties."""
202
f688d870victor-openai8 months ago203thread_id: str
204title: str
205
206
207class ThreadsDeleteReq(BaseReq):
6988ea0avictor-openai8 months ago208"""Request to delete a thread."""
209
f688d870victor-openai8 months ago210type: Literal["threads.delete"] = "threads.delete"
211params: ThreadDeleteParams
212
213
214class ThreadDeleteParams(BaseModel):
6988ea0avictor-openai8 months ago215"""Parameters identifying a thread to delete."""
216
f688d870victor-openai8 months ago217thread_id: str
218
219
220StreamingReq = (
221ThreadsCreateReq
222| ThreadsAddUserMessageReq
223| ThreadsAddClientToolOutputReq
224| ThreadsRetryAfterItemReq
225| ThreadsCustomActionReq
226)
6988ea0avictor-openai8 months ago227"""Union of request types that produce streaming responses."""
228
f688d870victor-openai8 months ago229
230NonStreamingReq = (
231ThreadsGetByIdReq
232| ThreadsListReq
233| ItemsListReq
234| ItemsFeedbackReq
235| AttachmentsCreateReq
236| AttachmentsDeleteReq
237| ThreadsUpdateReq
238| ThreadsDeleteReq
239)
6988ea0avictor-openai8 months ago240"""Union of request types that yield immediate responses."""
241
f688d870victor-openai8 months ago242
243ChatKitReq = Annotated[
244StreamingReq | NonStreamingReq,
245Field(discriminator="type"),
246]
247
248
249def is_streaming_req(request: ChatKitReq) -> TypeIs[StreamingReq]:
6988ea0avictor-openai8 months ago250"""Return True if the given request should be processed as streaming."""
f688d870victor-openai8 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-openai8 months ago267"""Event emitted when a thread is created."""
aa7ec072victor-openai8 months ago268
f688d870victor-openai8 months ago269type: Literal["thread.created"] = "thread.created"
270thread: Thread
271
272
273class ThreadUpdatedEvent(BaseModel):
6988ea0avictor-openai8 months ago274"""Event emitted when a thread is updated."""
aa7ec072victor-openai8 months ago275
f688d870victor-openai8 months ago276type: Literal["thread.updated"] = "thread.updated"
277thread: Thread
278
279
280class ThreadItemAddedEvent(BaseModel):
6988ea0avictor-openai8 months ago281"""Event emitted when a new item is added to a thread."""
aa7ec072victor-openai8 months ago282
f688d870victor-openai8 months ago283type: Literal["thread.item.added"] = "thread.item.added"
284item: ThreadItem
285
286
7861b9a0Jiwon Kim7 months ago287class ThreadItemUpdatedEvent(BaseModel):
6988ea0avictor-openai8 months ago288"""Event describing an update to an existing thread item."""
aa7ec072victor-openai8 months ago289
f688d870victor-openai8 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-openai8 months ago299class ThreadItemDoneEvent(BaseModel):
6988ea0avictor-openai8 months ago300"""Event emitted when a thread item is marked complete."""
aa7ec072victor-openai8 months ago301
f688d870victor-openai8 months ago302type: Literal["thread.item.done"] = "thread.item.done"
303item: ThreadItem
304
305
306class ThreadItemRemovedEvent(BaseModel):
6988ea0avictor-openai8 months ago307"""Event emitted when a thread item is removed."""
aa7ec072victor-openai8 months ago308
f688d870victor-openai8 months ago309type: Literal["thread.item.removed"] = "thread.item.removed"
310item_id: str
311
312
313class ThreadItemReplacedEvent(BaseModel):
6988ea0avictor-openai8 months ago314"""Event emitted when a thread item is replaced."""
aa7ec072victor-openai8 months ago315
f688d870victor-openai8 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-openai8 months ago334class ProgressUpdateEvent(BaseModel):
6988ea0avictor-openai8 months ago335"""Event providing incremental progress from the assistant."""
aa7ec072victor-openai8 months ago336
f688d870victor-openai8 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-openai8 months ago350class ErrorEvent(BaseModel):
6988ea0avictor-openai8 months ago351"""Event indicating an error occurred while processing a thread."""
aa7ec072victor-openai8 months ago352
f688d870victor-openai8 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-openai8 months ago360"""Event conveying a user-facing notice."""
aa7ec072victor-openai8 months ago361
f688d870victor-openai8 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-openai8 months ago380| ProgressUpdateEvent
a3c67d60Jiwon Kim7 months ago381| ClientEffectEvent
f688d870victor-openai8 months ago382| ErrorEvent
383| NoticeEvent,
384Field(discriminator="type"),
385]
6988ea0avictor-openai8 months ago386"""Union of all streaming events emitted to clients."""
f688d870victor-openai8 months ago387
388### THREAD ITEM UPDATE TYPES
389
390
391class AssistantMessageContentPartAdded(BaseModel):
6988ea0avictor-openai8 months ago392"""Event emitted when new assistant content is appended."""
aa7ec072victor-openai8 months ago393
f688d870victor-openai8 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-openai8 months ago402"""Event carrying incremental assistant text output."""
aa7ec072victor-openai8 months ago403
f688d870victor-openai8 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-openai8 months ago412"""Event announcing a new annotation on assistant content."""
aa7ec072victor-openai8 months ago413
f688d870victor-openai8 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-openai8 months ago423"""Event indicating an assistant content part is finalized."""
aa7ec072victor-openai8 months ago424
f688d870victor-openai8 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-openai8 months ago433"""Event streaming widget text deltas."""
aa7ec072victor-openai8 months ago434
f688d870victor-openai8 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-openai8 months ago444"""Event published when the widget root changes."""
aa7ec072victor-openai8 months ago445
f688d870victor-openai8 months ago446type: Literal["widget.root.updated"] = "widget.root.updated"
447widget: WidgetRoot
448
449
450class WidgetComponentUpdated(BaseModel):
6988ea0avictor-openai8 months ago451"""Event emitted when a widget component updates."""
aa7ec072victor-openai8 months ago452
f688d870victor-openai8 months ago453type: Literal["widget.component.updated"] = "widget.component.updated"
454component_id: str
455component: WidgetComponent
456
457
458class WorkflowTaskAdded(BaseModel):
6988ea0avictor-openai8 months ago459"""Event emitted when a workflow task is added."""
aa7ec072victor-openai8 months ago460
f688d870victor-openai8 months ago461type: Literal["workflow.task.added"] = "workflow.task.added"
462task_index: int
463task: Task
464
465
466class WorkflowTaskUpdated(BaseModel):
6988ea0avictor-openai8 months ago467"""Event emitted when a workflow task is updated."""
aa7ec072victor-openai8 months ago468
f688d870victor-openai8 months ago469type: Literal["workflow.task.updated"] = "workflow.task.updated"
470task_index: int
471task: Task
472
473
35ee77f0Jiwon Kim6 months ago474class GeneratedImageUpdated(BaseModel):
475"""Event emitted when a generated image is updated."""
476
477type: Literal["generated_image.updated"] = "generated_image.updated"
478image: GeneratedImage
479progress: float | None = None
480
481
f688d870victor-openai8 months ago482ThreadItemUpdate = (
483AssistantMessageContentPartAdded
484| AssistantMessageContentPartTextDelta
485| AssistantMessageContentPartAnnotationAdded
486| AssistantMessageContentPartDone
487| WidgetStreamingTextValueDelta
488| WidgetComponentUpdated
489| WidgetRootUpdated
490| WorkflowTaskAdded
491| WorkflowTaskUpdated
35ee77f0Jiwon Kim6 months ago492| GeneratedImageUpdated
f688d870victor-openai8 months ago493)
6988ea0avictor-openai8 months ago494"""Union of possible updates applied to thread items."""
f688d870victor-openai8 months ago495
496
497### THREAD TYPES
498
499
500class ThreadMetadata(BaseModel):
6988ea0avictor-openai8 months ago501"""Metadata describing a thread without its items."""
aa7ec072victor-openai8 months ago502
f688d870victor-openai8 months ago503title: str | None = None
504id: str
505created_at: datetime
506status: ThreadStatus = Field(default_factory=lambda: ActiveStatus())
507# TODO - make not client rendered
508metadata: dict[str, Any] = Field(default_factory=dict)
509
510
511class ActiveStatus(BaseModel):
6988ea0avictor-openai8 months ago512"""Status indicating the thread is active."""
aa7ec072victor-openai8 months ago513
f688d870victor-openai8 months ago514type: Literal["active"] = Field(default="active", frozen=True)
515
516
517class LockedStatus(BaseModel):
6988ea0avictor-openai8 months ago518"""Status indicating the thread is locked."""
aa7ec072victor-openai8 months ago519
f688d870victor-openai8 months ago520type: Literal["locked"] = Field(default="locked", frozen=True)
521reason: str | None = None
522
523
524class ClosedStatus(BaseModel):
6988ea0avictor-openai8 months ago525"""Status indicating the thread is closed."""
aa7ec072victor-openai8 months ago526
f688d870victor-openai8 months ago527type: Literal["closed"] = Field(default="closed", frozen=True)
528reason: str | None = None
529
530
531ThreadStatus = Annotated[
532ActiveStatus | LockedStatus | ClosedStatus,
533Field(discriminator="type"),
534]
6988ea0avictor-openai8 months ago535"""Union of lifecycle states for a thread."""
f688d870victor-openai8 months ago536
537
538class Thread(ThreadMetadata):
6988ea0avictor-openai8 months ago539"""Thread with its paginated items."""
aa7ec072victor-openai8 months ago540
f688d870victor-openai8 months ago541items: Page[ThreadItem]
542
543
544### THREAD ITEM TYPES
545
546
547class ThreadItemBase(BaseModel):
6988ea0avictor-openai8 months ago548"""Base fields shared by all thread items."""
aa7ec072victor-openai8 months ago549
f688d870victor-openai8 months ago550id: str
551thread_id: str
552created_at: datetime
553
554
555class UserMessageItem(ThreadItemBase):
6988ea0avictor-openai8 months ago556"""Thread item representing a user message."""
aa7ec072victor-openai8 months ago557
f688d870victor-openai8 months ago558type: Literal["user_message"] = "user_message"
559content: list[UserMessageContent]
560attachments: list[Attachment] = Field(default_factory=list)
561quoted_text: str | None = None
562inference_options: InferenceOptions
563
564
565class AssistantMessageItem(ThreadItemBase):
6988ea0avictor-openai8 months ago566"""Thread item representing an assistant message."""
aa7ec072victor-openai8 months ago567
f688d870victor-openai8 months ago568type: Literal["assistant_message"] = "assistant_message"
569content: list[AssistantMessageContent]
570
571
572class ClientToolCallItem(ThreadItemBase):
6988ea0avictor-openai8 months ago573"""Thread item capturing a client tool call."""
aa7ec072victor-openai8 months ago574
f688d870victor-openai8 months ago575type: Literal["client_tool_call"] = "client_tool_call"
576status: Literal["pending", "completed"] = "pending"
577call_id: str
578name: str
579arguments: dict[str, Any]
580output: Any | None = None
581
582
583class WidgetItem(ThreadItemBase):
6988ea0avictor-openai8 months ago584"""Thread item containing widget content."""
aa7ec072victor-openai8 months ago585
f688d870victor-openai8 months ago586type: Literal["widget"] = "widget"
587widget: WidgetRoot
588copy_text: str | None = None
589
590
35ee77f0Jiwon Kim6 months ago591class GeneratedImage(BaseModel):
592"""Generated image."""
593
594id: str
595url: str
596
597
598class GeneratedImageItem(ThreadItemBase):
599"""Thread item containing a generated image."""
600
601type: Literal["generated_image"] = "generated_image"
602image: GeneratedImage | None = None
603
604
f688d870victor-openai8 months ago605class TaskItem(ThreadItemBase):
6988ea0avictor-openai8 months ago606"""Thread item containing a task."""
aa7ec072victor-openai8 months ago607
f688d870victor-openai8 months ago608type: Literal["task"] = "task"
609task: Task
610
611
612class WorkflowItem(ThreadItemBase):
6988ea0avictor-openai8 months ago613"""Thread item representing a workflow."""
aa7ec072victor-openai8 months ago614
f688d870victor-openai8 months ago615type: Literal["workflow"] = "workflow"
616workflow: Workflow
617
618
619class EndOfTurnItem(ThreadItemBase):
6988ea0avictor-openai8 months ago620"""Marker item indicating the assistant ends its turn."""
aa7ec072victor-openai8 months ago621
f688d870victor-openai8 months ago622type: Literal["end_of_turn"] = "end_of_turn"
623
624
625class HiddenContextItem(ThreadItemBase):
5a7244baJiwon Kim7 months ago626"""
627HiddenContext is never sent to the client. It's not officially part of ChatKit.js.
628It is only used internally to store additional context in a specific place in the thread.
629"""
f688d870victor-openai8 months ago630
631type: Literal["hidden_context_item"] = "hidden_context_item"
632content: Any
633
634
5a7244baJiwon Kim7 months ago635class SDKHiddenContextItem(ThreadItemBase):
636"""
637Hidden context that is used by the ChatKit Python SDK for storing additional context
638for internal operations.
639"""
640
641type: Literal["sdk_hidden_context"] = "sdk_hidden_context"
642content: str
643
644
f688d870victor-openai8 months ago645ThreadItem = Annotated[
646UserMessageItem
647| AssistantMessageItem
648| ClientToolCallItem
649| WidgetItem
35ee77f0Jiwon Kim6 months ago650| GeneratedImageItem
f688d870victor-openai8 months ago651| WorkflowItem
652| TaskItem
653| HiddenContextItem
5a7244baJiwon Kim7 months ago654| SDKHiddenContextItem
f688d870victor-openai8 months ago655| EndOfTurnItem,
656Field(discriminator="type"),
657]
6988ea0avictor-openai8 months ago658"""Union of all thread item variants."""
f688d870victor-openai8 months ago659
660
661### ASSISTANT MESSAGE TYPES
662
663
664class AssistantMessageContent(BaseModel):
6988ea0avictor-openai8 months ago665"""Assistant message content consisting of text and annotations."""
aa7ec072victor-openai8 months ago666
f688d870victor-openai8 months ago667annotations: list[Annotation] = Field(default_factory=list)
668text: str
669type: Literal["output_text"] = "output_text"
670
671
672class Annotation(BaseModel):
6988ea0avictor-openai8 months ago673"""Reference to supporting context attached to assistant output."""
aa7ec072victor-openai8 months ago674
f688d870victor-openai8 months ago675type: Literal["annotation"] = "annotation"
676source: URLSource | FileSource | EntitySource
677index: int | None = None
678
679
680### USER MESSAGE TYPES
681
682
683class UserMessageInput(BaseModel):
6988ea0avictor-openai8 months ago684"""Payload describing a user message submission."""
aa7ec072victor-openai8 months ago685
f688d870victor-openai8 months ago686content: list[UserMessageContent]
687attachments: list[str]
688quoted_text: str | None = None
689inference_options: InferenceOptions
690
691
692class UserMessageTextContent(BaseModel):
6988ea0avictor-openai8 months ago693"""User message content containing plaintext."""
aa7ec072victor-openai8 months ago694
f688d870victor-openai8 months ago695type: Literal["input_text"] = "input_text"
696text: str
697
698
699class UserMessageTagContent(BaseModel):
6988ea0avictor-openai8 months ago700"""User message content representing an interactive tag."""
aa7ec072victor-openai8 months ago701
f688d870victor-openai8 months ago702type: Literal["input_tag"] = "input_tag"
703id: str
704text: str
705data: dict[str, Any]
ec580cbaJiwon Kim7 months ago706group: str | None = None
f688d870victor-openai8 months ago707interactive: bool = False
708
709
710UserMessageContent = Annotated[
711UserMessageTextContent | UserMessageTagContent, Field(discriminator="type")
712]
6988ea0avictor-openai8 months ago713"""Union of allowed user message content payloads."""
f688d870victor-openai8 months ago714
715
716class InferenceOptions(BaseModel):
6988ea0avictor-openai8 months ago717"""Model and tool configuration for message processing."""
aa7ec072victor-openai8 months ago718
f688d870victor-openai8 months ago719tool_choice: ToolChoice | None = None
720model: str | None = None
721
722
723class ToolChoice(BaseModel):
6988ea0avictor-openai8 months ago724"""Explicit tool selection for the assistant to invoke."""
aa7ec072victor-openai8 months ago725
f688d870victor-openai8 months ago726id: str
727
728
ad273215Jiwon Kim6 months ago729class AttachmentUploadDescriptor(BaseModel):
730"""Two-phase upload instructions."""
731
732url: AnyUrl
24b53f98Jiwon Kim5 months ago733method: Literal["POST", "PUT"]
ad273215Jiwon Kim6 months ago734"""The HTTP method to use when uploading the file for two-phase upload."""
735headers: dict[str, str] = Field(default_factory=dict)
736"""Optional headers to include in the upload request."""
737
738
f688d870victor-openai8 months ago739class AttachmentBase(BaseModel):
6988ea0avictor-openai8 months ago740"""Base metadata shared by all attachments."""
aa7ec072victor-openai8 months ago741
f688d870victor-openai8 months ago742id: str
743name: str
744mime_type: str
ad273215Jiwon Kim6 months ago745upload_descriptor: AttachmentUploadDescriptor | None = None
f688d870victor-openai8 months ago746"""
ad273215Jiwon Kim6 months ago747Two-phase upload instructions.
748Should be set to None after upload is complete or when using direct upload
749where uploading happens when creating the attachment object.
f688d870victor-openai8 months ago750"""
751
752
753class FileAttachment(AttachmentBase):
6988ea0avictor-openai8 months ago754"""Attachment representing a generic file."""
aa7ec072victor-openai8 months ago755
f688d870victor-openai8 months ago756type: Literal["file"] = "file"
757
758
759class ImageAttachment(AttachmentBase):
6988ea0avictor-openai8 months ago760"""Attachment representing an image resource."""
aa7ec072victor-openai8 months ago761
f688d870victor-openai8 months ago762type: Literal["image"] = "image"
763preview_url: AnyUrl
764
765
766Attachment = Annotated[
767FileAttachment | ImageAttachment,
768Field(discriminator="type"),
769]
6988ea0avictor-openai8 months ago770"""Union of supported attachment types."""
f688d870victor-openai8 months ago771
772
773### WORKFLOW TYPES
774
775
776class Workflow(BaseModel):
6988ea0avictor-openai8 months ago777"""Workflow attached to a thread with optional summary."""
aa7ec072victor-openai8 months ago778
f688d870victor-openai8 months ago779type: Literal["custom", "reasoning"]
780tasks: list[Task]
781summary: WorkflowSummary | None = None
782expanded: bool = False
783
784
785class CustomSummary(BaseModel):
6988ea0avictor-openai8 months ago786"""Custom summary for a workflow."""
aa7ec072victor-openai8 months ago787
f688d870victor-openai8 months ago788title: str
c9f5f09dJiwon Kim8 months ago789icon: IconName | None = None
f688d870victor-openai8 months ago790
791
792class DurationSummary(BaseModel):
6988ea0avictor-openai8 months ago793"""Summary providing total workflow duration."""
aa7ec072victor-openai8 months ago794
f688d870victor-openai8 months ago795duration: int
796"""The duration of the workflow in seconds"""
797
798
799WorkflowSummary = CustomSummary | DurationSummary
6988ea0avictor-openai8 months ago800"""Summary variants available for workflows."""
f688d870victor-openai8 months ago801
802### TASK TYPES
803
804
805class BaseTask(BaseModel):
6988ea0avictor-openai8 months ago806"""Base fields common to all workflow tasks."""
aa7ec072victor-openai8 months ago807
f688d870victor-openai8 months ago808status_indicator: Literal["none", "loading", "complete"] = "none"
809"""Only used when rendering the task as part of a workflow. Indicates the status of the task."""
810
811
812class CustomTask(BaseTask):
6988ea0avictor-openai8 months ago813"""Workflow task displaying custom content."""
aa7ec072victor-openai8 months ago814
f688d870victor-openai8 months ago815type: Literal["custom"] = "custom"
816title: str | None = None
c9f5f09dJiwon Kim8 months ago817icon: IconName | None = None
f688d870victor-openai8 months ago818content: str | None = None
819
820
821class SearchTask(BaseTask):
6988ea0avictor-openai8 months ago822"""Workflow task representing a web search."""
aa7ec072victor-openai8 months ago823
f688d870victor-openai8 months ago824type: Literal["web_search"] = "web_search"
825title: str | None = None
826title_query: str | None = None
827queries: list[str] = Field(default_factory=list)
828sources: list[URLSource] = Field(default_factory=list)
829
830
831class ThoughtTask(BaseTask):
6988ea0avictor-openai8 months ago832"""Workflow task capturing assistant reasoning."""
aa7ec072victor-openai8 months ago833
f688d870victor-openai8 months ago834type: Literal["thought"] = "thought"
835title: str | None = None
836content: str
837
838
839class FileTask(BaseTask):
6988ea0avictor-openai8 months ago840"""Workflow task referencing file sources."""
aa7ec072victor-openai8 months ago841
f688d870victor-openai8 months ago842type: Literal["file"] = "file"
843title: str | None = None
844sources: list[FileSource] = Field(default_factory=list)
845
846
847class ImageTask(BaseTask):
6988ea0avictor-openai8 months ago848"""Workflow task rendering image content."""
aa7ec072victor-openai8 months ago849
f688d870victor-openai8 months ago850type: Literal["image"] = "image"
851title: str | None = None
852
853
854Task = Annotated[
855CustomTask | SearchTask | ThoughtTask | FileTask | ImageTask,
856Field(discriminator="type"),
857]
6988ea0avictor-openai8 months ago858"""Union of workflow task variants."""
f688d870victor-openai8 months ago859
860
861### SOURCE TYPES
862
863
864class SourceBase(BaseModel):
6988ea0avictor-openai8 months ago865"""Base class for sources displayed to users."""
aa7ec072victor-openai8 months ago866
f688d870victor-openai8 months ago867title: str
868description: str | None = None
869timestamp: str | None = None
870group: str | None = None
871
872
873class FileSource(SourceBase):
6988ea0avictor-openai8 months ago874"""Source metadata for file-based references."""
aa7ec072victor-openai8 months ago875
f688d870victor-openai8 months ago876type: Literal["file"] = "file"
877filename: str
878
879
880class URLSource(SourceBase):
6988ea0avictor-openai8 months ago881"""Source metadata for external URLs."""
aa7ec072victor-openai8 months ago882
f688d870victor-openai8 months ago883type: Literal["url"] = "url"
884url: str
885attribution: str | None = None
886
887
888class EntitySource(SourceBase):
6988ea0avictor-openai8 months ago889"""Source metadata for entity references."""
aa7ec072victor-openai8 months ago890
f688d870victor-openai8 months ago891type: Literal["entity"] = "entity"
892id: str
c9f5f09dJiwon Kim8 months ago893icon: IconName | None = None
002dd9feJiwon Kim6 months ago894label: str | None = None
895"""Optional label shown with the icon in the default entity hover header
896when no preview callback is provided.
897"""
6161a280Jiwon Kim6 months ago898inline_label: str | None = None
899"""Optional label for the inline annotation view. When not provided, the icon is used instead."""
67064fb2Jiwon Kim6 months ago900interactive: bool = False
901"""Per-entity toggle to wire client callbacks and render this entity as interactive."""
c47e7701jiwon-oai8 months ago902data: dict[str, Any] = Field(default_factory=dict)
002dd9feJiwon Kim6 months ago903"""Additional data for the entity source that is passed to client entity callbacks."""
f688d870victor-openai8 months ago904
ec580cbaJiwon Kim7 months ago905preview: Literal["lazy"] | None = Field(
906default=None,
907deprecated=True,
908description="This field is ignored. Please use the entities.onRequestPreview ChatKit.js option instead.",
909)
910
f688d870victor-openai8 months ago911
6988ea0avictor-openai8 months ago912Source = Annotated[
913URLSource | FileSource | EntitySource,
914Field(discriminator="type"),
915]
916"""Union of supported source types."""
f688d870victor-openai8 months ago917
918
919### MISC TYPES
920
921
922FeedbackKind = Literal["positive", "negative"]
6988ea0avictor-openai8 months ago923"""Literal type for feedback sentiment."""