models
Thread records and domain values stored or passed to application hooks.
ThreadStatus
module-attribute
ThreadStatus = Annotated[ActiveStatus | LockedStatus | ClosedStatus, Field(discriminator='type')]
Union of lifecycle states for a thread.
StructuredInput
module-attribute
StructuredInput = Annotated[StructuredInputMultipleChoice | StructuredInputFreeform, Field(discriminator='type')]
Structured input variants supported by a structured input item.
ThreadItem
module-attribute
ThreadItem = Annotated[UserMessageItem | AssistantMessageItem | ClientToolCallItem | WidgetItem | GeneratedImageItem | StructuredInputItem | WorkflowItem | TaskItem | HiddenContextItem | SDKHiddenContextItem | EndOfTurnItem, Field(discriminator='type')]
Union of all thread item variants.
UserMessageContent
module-attribute
UserMessageContent = Annotated[UserMessageTextContent | UserMessageTagContent, Field(discriminator='type')]
Union of allowed user message content payloads.
Attachment
module-attribute
Attachment = Annotated[FileAttachment | ImageAttachment, Field(discriminator='type')]
Union of supported attachment types.
WorkflowSummary
module-attribute
WorkflowSummary = CustomSummary | DurationSummary
Summary variants available for workflows.
Task
module-attribute
Task = Annotated[CustomTask | SearchTask | ThoughtTask | FileTask | ImageTask, Field(discriminator='type')]
Union of workflow task variants.
Source
module-attribute
Source = Annotated[URLSource | FileSource | EntitySource, Field(discriminator='type')]
Union of supported source types.
FeedbackKind
module-attribute
FeedbackKind = Literal['positive', 'negative']
Literal type for feedback sentiment.
Page
Bases: BaseModel
Paginated collection of records returned from the API.
Source code in chatkit/models.py
17 18 19 20 21 22 | |
AudioInput
Bases: BaseModel
Audio input data for transcription.
Source code in chatkit/models.py
25 26 27 28 29 30 31 32 33 34 35 36 37 | |
data
instance-attribute
data: bytes
Audio data bytes.
mime_type
instance-attribute
mime_type: str
Raw MIME type for the audio payload, e.g. "audio/webm;codecs=opus".
media_type
property
media_type: str
Media type for the audio payload, e.g. "audio/webm".
TranscriptionResult
Bases: BaseModel
Input speech transcription result.
Source code in chatkit/models.py
40 41 42 43 | |
ThreadMetadata
Bases: BaseModel
Metadata describing a thread without its items.
Source code in chatkit/models.py
49 50 51 52 53 54 55 56 57 | |
ActiveStatus
Bases: BaseModel
Status indicating the thread is active.
Source code in chatkit/models.py
60 61 62 63 | |
LockedStatus
Bases: BaseModel
Status indicating the thread is locked.
Source code in chatkit/models.py
66 67 68 69 70 | |
ClosedStatus
Bases: BaseModel
Status indicating the thread is closed.
Source code in chatkit/models.py
73 74 75 76 77 | |
Thread
Bases: ThreadMetadata
Thread with its paginated items.
Source code in chatkit/models.py
87 88 89 90 | |
ThreadItemBase
Bases: BaseModel
Base fields shared by all thread items.
Source code in chatkit/models.py
96 97 98 99 100 101 | |
UserMessageItem
Bases: ThreadItemBase
Thread item representing a user message.
Source code in chatkit/models.py
104 105 106 107 108 109 110 111 | |
AssistantMessageItem
Bases: ThreadItemBase
Thread item representing an assistant message.
Source code in chatkit/models.py
117 118 119 120 121 122 123 124 125 126 127 128 129 130 | |
phase
class-attribute
instance-attribute
phase: AssistantMessagePhase | None = None
Provider-supplied phase retained for model history and omitted from browser responses.
ClientToolCallItem
Bases: ThreadItemBase
Browser-visible display and callback data for a client tool.
Source code in chatkit/models.py
133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 | |
WidgetItem
Bases: ThreadItemBase
Thread item containing widget content.
Source code in chatkit/models.py
150 151 152 153 154 155 | |
GeneratedImage
Bases: BaseModel
Generated image.
Source code in chatkit/models.py
158 159 160 161 162 | |
GeneratedImageItem
Bases: ThreadItemBase
Thread item containing a generated image.
Source code in chatkit/models.py
165 166 167 168 169 | |
StructuredInputAnswer
Bases: BaseModel
Answer recorded for a structured input.
Source code in chatkit/models.py
172 173 174 175 176 177 178 | |
values
class-attribute
instance-attribute
values: list[str] = Field(default_factory=list)
Text answer values recorded for the structured input.
skipped
class-attribute
instance-attribute
skipped: bool = False
Whether this structured input answer was skipped.
StructuredInputBase
Bases: BaseModel
Base fields shared by structured inputs.
Source code in chatkit/models.py
181 182 183 184 185 186 187 188 189 | |
id
instance-attribute
id: str
Stable id for this structured input.
question
instance-attribute
question: str
Question shown to the user.
answer
class-attribute
instance-attribute
answer: StructuredInputAnswer | None = None
Answer recorded for this structured input, if available.
StructuredInputMultipleChoiceOption
Bases: BaseModel
Option shown for a multiple-choice structured input.
Source code in chatkit/models.py
192 193 194 195 196 | |
value
instance-attribute
value: str
Text value submitted when this option is selected.
StructuredInputMultipleChoice
Bases: StructuredInputBase
Structured input answered by choosing one or more options.
Source code in chatkit/models.py
199 200 201 202 203 204 205 206 | |
options
instance-attribute
options: list[StructuredInputMultipleChoiceOption]
Suggested choices to display before the freeform custom answer affordance.
multiple
class-attribute
instance-attribute
multiple: bool = False
Whether the user may submit more than one text value.
StructuredInputFreeform
Bases: StructuredInputBase
Structured input answered with freeform text.
Source code in chatkit/models.py
209 210 211 212 213 214 | |
description
class-attribute
instance-attribute
description: str | None = None
Supporting text shown with this input.
StructuredInputItem
Bases: ThreadItemBase
Thread item requesting structured input from the user.
Source code in chatkit/models.py
224 225 226 227 228 229 | |
TaskItem
Bases: ThreadItemBase
Thread item containing a task.
Source code in chatkit/models.py
232 233 234 235 236 | |
WorkflowItem
Bases: ThreadItemBase
Thread item representing a workflow.
Source code in chatkit/models.py
239 240 241 242 243 | |
EndOfTurnItem
Bases: ThreadItemBase
Marker item indicating the assistant ends its turn.
Source code in chatkit/models.py
246 247 248 249 | |
HiddenContextItem
Bases: ThreadItemBase
HiddenContext is never sent to the client. It's not officially part of ChatKit.js. It is only used internally to store additional context in a specific place in the thread.
Source code in chatkit/models.py
252 253 254 255 256 257 258 259 | |
SDKHiddenContextItem
Bases: ThreadItemBase
Hidden context that is used by the ChatKit Python SDK for storing additional context for internal operations.
Source code in chatkit/models.py
262 263 264 265 266 267 268 269 | |
AssistantMessageContent
Bases: BaseModel
Assistant message content consisting of text and annotations.
Source code in chatkit/models.py
292 293 294 295 296 297 | |
Annotation
Bases: BaseModel
Reference to supporting context attached to assistant output.
Source code in chatkit/models.py
300 301 302 303 304 305 | |
UserMessageInput
Bases: BaseModel
Payload describing a user message submission.
Source code in chatkit/models.py
311 312 313 314 315 316 317 | |
UserMessageTextContent
Bases: BaseModel
User message content containing plaintext.
Source code in chatkit/models.py
320 321 322 323 324 | |
UserMessageTagContent
Bases: BaseModel
User message content representing an interactive tag.
Source code in chatkit/models.py
327 328 329 330 331 332 333 334 335 | |
InferenceOptions
Bases: BaseModel
Model and tool configuration for message processing.
Source code in chatkit/models.py
344 345 346 347 348 | |
ToolChoice
Bases: BaseModel
Explicit tool selection for the assistant to invoke.
Source code in chatkit/models.py
351 352 353 354 | |
AttachmentUploadDescriptor
Bases: BaseModel
Two-phase upload instructions.
Source code in chatkit/models.py
357 358 359 360 361 362 363 364 | |
method
instance-attribute
method: Literal['POST', 'PUT']
The HTTP method to use when uploading the file for two-phase upload.
headers
class-attribute
instance-attribute
headers: dict[str, str] = Field(default_factory=dict)
Optional headers to include in the upload request.
AttachmentBase
Bases: BaseModel
Base metadata shared by all attachments.
Source code in chatkit/models.py
367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 | |
upload_descriptor
class-attribute
instance-attribute
upload_descriptor: AttachmentUploadDescriptor | None = None
Two-phase upload instructions. Should be set to None after upload is complete or when using direct upload where uploading happens when creating the attachment object.
thread_id
class-attribute
instance-attribute
thread_id: str | None = None
The thread the attachment belongs to, if any. Added when the user message that contains the attachment is saved to store.
metadata
class-attribute
instance-attribute
metadata: dict[str, Any] | None = None
Integration-only metadata stored with the attachment. Ignored by ChatKit and not returned in ChatKitServer responses. If you serialize attachments from a custom direct-upload endpoint and want to omit this field, pass context={"exclude_metadata": True}.
FileAttachment
Bases: AttachmentBase
Attachment representing a generic file.
Source code in chatkit/models.py
399 400 401 402 | |
ImageAttachment
Bases: AttachmentBase
Attachment representing an image resource.
Source code in chatkit/models.py
405 406 407 408 409 | |
Workflow
Bases: BaseModel
Workflow attached to a thread with optional summary.
Source code in chatkit/models.py
422 423 424 425 426 427 428 | |
CustomSummary
Bases: BaseModel
Custom summary for a workflow.
Source code in chatkit/models.py
431 432 433 434 435 | |
DurationSummary
Bases: BaseModel
Summary providing total workflow duration.
Source code in chatkit/models.py
438 439 440 441 442 | |
duration
instance-attribute
duration: int
The duration of the workflow in seconds
BaseTask
Bases: BaseModel
Base fields common to all workflow tasks.
Source code in chatkit/models.py
451 452 453 454 455 | |
status_indicator
class-attribute
instance-attribute
status_indicator: Literal['none', 'loading', 'complete'] = 'none'
Only used when rendering the task as part of a workflow. Indicates the status of the task.
CustomTask
Bases: BaseTask
Workflow task displaying custom content.
Source code in chatkit/models.py
458 459 460 461 462 463 464 | |
SearchTask
Bases: BaseTask
Workflow task representing a web search.
Source code in chatkit/models.py
467 468 469 470 471 472 473 474 | |
ThoughtTask
Bases: BaseTask
Workflow task capturing assistant reasoning.
Source code in chatkit/models.py
477 478 479 480 481 482 | |
FileTask
Bases: BaseTask
Workflow task referencing file sources.
Source code in chatkit/models.py
485 486 487 488 489 490 | |
ImageTask
Bases: BaseTask
Workflow task rendering image content.
Source code in chatkit/models.py
493 494 495 496 497 | |
SourceBase
Bases: BaseModel
Base class for sources displayed to users.
Source code in chatkit/models.py
510 511 512 513 514 515 516 | |
FileSource
Bases: SourceBase
Source metadata for file-based references.
Source code in chatkit/models.py
519 520 521 522 523 | |
URLSource
Bases: SourceBase
Source metadata for external URLs.
Source code in chatkit/models.py
526 527 528 529 530 531 | |
EntitySource
Bases: SourceBase
Source metadata for entity references.
Source code in chatkit/models.py
534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 | |
label
class-attribute
instance-attribute
label: str | None = None
Optional label shown with the icon in the default entity hover header when no preview callback is provided.
inline_label
class-attribute
instance-attribute
inline_label: str | None = None
Optional label for the inline annotation view. When not provided, the icon is used instead.
interactive
class-attribute
instance-attribute
interactive: bool = False
Per-entity toggle to wire client callbacks and render this entity as interactive.
data
class-attribute
instance-attribute
data: dict[str, Any] = Field(default_factory=dict)
Additional data for the entity source that is passed to client entity callbacks.