Skip to content

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

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
class Page[T](BaseModel):
    """Paginated collection of records returned from the API."""

    data: list[T] = []
    has_more: bool = False
    after: str | None = None

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
class AudioInput(BaseModel):
    """Audio input data for transcription."""

    data: bytes
    """Audio data bytes."""

    mime_type: str
    """Raw MIME type for the audio payload, e.g. "audio/webm;codecs=opus"."""

    @property
    def media_type(self) -> str:
        """Media type for the audio payload, e.g. "audio/webm"."""
        return self.mime_type.split(";", 1)[0]

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
class TranscriptionResult(BaseModel):
    """Input speech transcription result."""

    text: str

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
class ThreadMetadata(BaseModel):
    """Metadata describing a thread without its items."""

    title: str | None = None
    id: str
    created_at: datetime
    status: ThreadStatus = Field(default_factory=lambda: ActiveStatus())
    allowed_image_domains: list[str] | None = None
    metadata: dict[str, Any] = Field(default_factory=dict)

ActiveStatus

Bases: BaseModel

Status indicating the thread is active.

Source code in chatkit/models.py
60
61
62
63
class ActiveStatus(BaseModel):
    """Status indicating the thread is active."""

    type: Literal["active"] = Field(default="active", frozen=True)

LockedStatus

Bases: BaseModel

Status indicating the thread is locked.

Source code in chatkit/models.py
66
67
68
69
70
class LockedStatus(BaseModel):
    """Status indicating the thread is locked."""

    type: Literal["locked"] = Field(default="locked", frozen=True)
    reason: str | None = None

ClosedStatus

Bases: BaseModel

Status indicating the thread is closed.

Source code in chatkit/models.py
73
74
75
76
77
class ClosedStatus(BaseModel):
    """Status indicating the thread is closed."""

    type: Literal["closed"] = Field(default="closed", frozen=True)
    reason: str | None = None

Thread

Bases: ThreadMetadata

Thread with its paginated items.

Source code in chatkit/models.py
87
88
89
90
class Thread(ThreadMetadata):
    """Thread with its paginated items."""

    items: Page[ThreadItem]

ThreadItemBase

Bases: BaseModel

Base fields shared by all thread items.

Source code in chatkit/models.py
 96
 97
 98
 99
100
101
class ThreadItemBase(BaseModel):
    """Base fields shared by all thread items."""

    id: str
    thread_id: str
    created_at: datetime

UserMessageItem

Bases: ThreadItemBase

Thread item representing a user message.

Source code in chatkit/models.py
104
105
106
107
108
109
110
111
class UserMessageItem(ThreadItemBase):
    """Thread item representing a user message."""

    type: Literal["user_message"] = "user_message"
    content: list[UserMessageContent]
    attachments: list[Attachment] = Field(default_factory=list)
    quoted_text: str | None = None
    inference_options: InferenceOptions

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
class AssistantMessageItem(ThreadItemBase):
    """Thread item representing an assistant message."""

    type: Literal["assistant_message"] = "assistant_message"
    content: list[AssistantMessageContent]
    phase: AssistantMessagePhase | None = None
    """Provider-supplied phase retained for model history and omitted from browser responses."""

    @model_serializer(mode="wrap")
    def _serialize(self, serializer, info: SerializationInfo):
        data = serializer(self)
        if (info.context or {}).get("browser_wire"):
            data.pop("phase", None)
        return data

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
class ClientToolCallItem(ThreadItemBase):
    """Browser-visible display and callback data for a client tool."""

    type: Literal["client_tool_call"] = "client_tool_call"
    status: Literal["pending", "completed"] = "pending"
    name: str
    arguments: dict[str, Any]
    output: Any | None = None

    @model_serializer(mode="wrap")
    def _serialize(self, serializer, info: SerializationInfo):
        data = serializer(self)
        if self.status == "pending" and (info.context or {}).get("browser_wire"):
            data["arguments"] = {"item_id": self.id, "input": data["arguments"]}
        return data

WidgetItem

Bases: ThreadItemBase

Thread item containing widget content.

Source code in chatkit/models.py
150
151
152
153
154
155
class WidgetItem(ThreadItemBase):
    """Thread item containing widget content."""

    type: Literal["widget"] = "widget"
    widget: widget_models.WidgetRoot
    copy_text: str | None = None

GeneratedImage

Bases: BaseModel

Generated image.

Source code in chatkit/models.py
158
159
160
161
162
class GeneratedImage(BaseModel):
    """Generated image."""

    id: str
    url: str

GeneratedImageItem

Bases: ThreadItemBase

Thread item containing a generated image.

Source code in chatkit/models.py
165
166
167
168
169
class GeneratedImageItem(ThreadItemBase):
    """Thread item containing a generated image."""

    type: Literal["generated_image"] = "generated_image"
    image: GeneratedImage | None = None

StructuredInputAnswer

Bases: BaseModel

Answer recorded for a structured input.

Source code in chatkit/models.py
172
173
174
175
176
177
178
class StructuredInputAnswer(BaseModel):
    """Answer recorded for a structured input."""

    values: list[str] = Field(default_factory=list)
    """Text answer values recorded for the structured input."""
    skipped: bool = False
    """Whether this structured input answer was skipped."""

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
class StructuredInputBase(BaseModel):
    """Base fields shared by structured inputs."""

    id: str
    """Stable id for this structured input."""
    question: str
    """Question shown to the user."""
    answer: StructuredInputAnswer | None = None
    """Answer recorded for this structured input, if available."""

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
class StructuredInputMultipleChoiceOption(BaseModel):
    """Option shown for a multiple-choice structured input."""

    value: str
    """Text value submitted when this option is selected."""

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
class StructuredInputMultipleChoice(StructuredInputBase):
    """Structured input answered by choosing one or more options."""

    type: Literal["multiple_choice"] = "multiple_choice"
    options: list[StructuredInputMultipleChoiceOption]
    """Suggested choices to display before the freeform custom answer affordance."""
    multiple: bool = False
    """Whether the user may submit more than one text value."""

options instance-attribute

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
class StructuredInputFreeform(StructuredInputBase):
    """Structured input answered with freeform text."""

    type: Literal["freeform"] = "freeform"
    description: str | None = None
    """Supporting text shown with this input."""

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
class StructuredInputItem(ThreadItemBase):
    """Thread item requesting structured input from the user."""

    type: Literal["structured_input"] = "structured_input"
    status: Literal["pending", "answered", "skipped"] = "pending"
    inputs: list[StructuredInput]

TaskItem

Bases: ThreadItemBase

Thread item containing a task.

Source code in chatkit/models.py
232
233
234
235
236
class TaskItem(ThreadItemBase):
    """Thread item containing a task."""

    type: Literal["task"] = "task"
    task: Task

WorkflowItem

Bases: ThreadItemBase

Thread item representing a workflow.

Source code in chatkit/models.py
239
240
241
242
243
class WorkflowItem(ThreadItemBase):
    """Thread item representing a workflow."""

    type: Literal["workflow"] = "workflow"
    workflow: Workflow

EndOfTurnItem

Bases: ThreadItemBase

Marker item indicating the assistant ends its turn.

Source code in chatkit/models.py
246
247
248
249
class EndOfTurnItem(ThreadItemBase):
    """Marker item indicating the assistant ends its turn."""

    type: Literal["end_of_turn"] = "end_of_turn"

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
class HiddenContextItem(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.
    """

    type: Literal["hidden_context_item"] = "hidden_context_item"
    content: Any

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
class SDKHiddenContextItem(ThreadItemBase):
    """
    Hidden context that is used by the ChatKit Python SDK for storing additional context
    for internal operations.
    """

    type: Literal["sdk_hidden_context"] = "sdk_hidden_context"
    content: str

AssistantMessageContent

Bases: BaseModel

Assistant message content consisting of text and annotations.

Source code in chatkit/models.py
292
293
294
295
296
297
class AssistantMessageContent(BaseModel):
    """Assistant message content consisting of text and annotations."""

    annotations: list[Annotation] = Field(default_factory=list)
    text: str
    type: Literal["output_text"] = "output_text"

Annotation

Bases: BaseModel

Reference to supporting context attached to assistant output.

Source code in chatkit/models.py
300
301
302
303
304
305
class Annotation(BaseModel):
    """Reference to supporting context attached to assistant output."""

    type: Literal["annotation"] = "annotation"
    source: URLSource | FileSource | EntitySource
    index: int | None = None

UserMessageInput

Bases: BaseModel

Payload describing a user message submission.

Source code in chatkit/models.py
311
312
313
314
315
316
317
class UserMessageInput(BaseModel):
    """Payload describing a user message submission."""

    content: list[UserMessageContent]
    attachments: list[str]
    quoted_text: str | None = None
    inference_options: InferenceOptions

UserMessageTextContent

Bases: BaseModel

User message content containing plaintext.

Source code in chatkit/models.py
320
321
322
323
324
class UserMessageTextContent(BaseModel):
    """User message content containing plaintext."""

    type: Literal["input_text"] = "input_text"
    text: str

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
class UserMessageTagContent(BaseModel):
    """User message content representing an interactive tag."""

    type: Literal["input_tag"] = "input_tag"
    id: str
    text: str
    data: dict[str, Any]
    group: str | None = None
    interactive: bool = False

InferenceOptions

Bases: BaseModel

Model and tool configuration for message processing.

Source code in chatkit/models.py
344
345
346
347
348
class InferenceOptions(BaseModel):
    """Model and tool configuration for message processing."""

    tool_choice: ToolChoice | None = None
    model: str | None = None

ToolChoice

Bases: BaseModel

Explicit tool selection for the assistant to invoke.

Source code in chatkit/models.py
351
352
353
354
class ToolChoice(BaseModel):
    """Explicit tool selection for the assistant to invoke."""

    id: str

AttachmentUploadDescriptor

Bases: BaseModel

Two-phase upload instructions.

Source code in chatkit/models.py
357
358
359
360
361
362
363
364
class AttachmentUploadDescriptor(BaseModel):
    """Two-phase upload instructions."""

    url: AnyUrl
    method: Literal["POST", "PUT"]
    """The HTTP method to use when uploading the file for two-phase upload."""
    headers: dict[str, str] = Field(default_factory=dict)
    """Optional headers to include in the upload request."""

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
class AttachmentBase(BaseModel):
    """Base metadata shared by all attachments."""

    id: str
    name: str
    mime_type: str
    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: 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: 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}.
    """

    @model_serializer(mode="wrap")
    def _serialize(self, serializer, info: SerializationInfo):
        data = serializer(self)
        if isinstance(data, dict) and (info.context or {}).get("exclude_metadata"):
            data.pop("metadata", None)
        return data

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
class FileAttachment(AttachmentBase):
    """Attachment representing a generic file."""

    type: Literal["file"] = "file"

ImageAttachment

Bases: AttachmentBase

Attachment representing an image resource.

Source code in chatkit/models.py
405
406
407
408
409
class ImageAttachment(AttachmentBase):
    """Attachment representing an image resource."""

    type: Literal["image"] = "image"
    preview_url: AnyUrl

Workflow

Bases: BaseModel

Workflow attached to a thread with optional summary.

Source code in chatkit/models.py
422
423
424
425
426
427
428
class Workflow(BaseModel):
    """Workflow attached to a thread with optional summary."""

    type: Literal["custom", "reasoning"]
    tasks: list[Task]
    summary: WorkflowSummary | None = None
    expanded: bool = False

CustomSummary

Bases: BaseModel

Custom summary for a workflow.

Source code in chatkit/models.py
431
432
433
434
435
class CustomSummary(BaseModel):
    """Custom summary for a workflow."""

    title: str
    icon: icons.IconName | None = None

DurationSummary

Bases: BaseModel

Summary providing total workflow duration.

Source code in chatkit/models.py
438
439
440
441
442
class DurationSummary(BaseModel):
    """Summary providing total workflow duration."""

    duration: int
    """The duration of the workflow in seconds"""

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
class BaseTask(BaseModel):
    """Base fields common to all workflow tasks."""

    status_indicator: Literal["none", "loading", "complete"] = "none"
    """Only used when rendering the task as part of a workflow. Indicates the status of the task."""

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
class CustomTask(BaseTask):
    """Workflow task displaying custom content."""

    type: Literal["custom"] = "custom"
    title: str | None = None
    icon: icons.IconName | None = None
    content: str | None = None

SearchTask

Bases: BaseTask

Workflow task representing a web search.

Source code in chatkit/models.py
467
468
469
470
471
472
473
474
class SearchTask(BaseTask):
    """Workflow task representing a web search."""

    type: Literal["web_search"] = "web_search"
    title: str | None = None
    title_query: str | None = None
    queries: list[str] = Field(default_factory=list)
    sources: list[URLSource] = Field(default_factory=list)

ThoughtTask

Bases: BaseTask

Workflow task capturing assistant reasoning.

Source code in chatkit/models.py
477
478
479
480
481
482
class ThoughtTask(BaseTask):
    """Workflow task capturing assistant reasoning."""

    type: Literal["thought"] = "thought"
    title: str | None = None
    content: str

FileTask

Bases: BaseTask

Workflow task referencing file sources.

Source code in chatkit/models.py
485
486
487
488
489
490
class FileTask(BaseTask):
    """Workflow task referencing file sources."""

    type: Literal["file"] = "file"
    title: str | None = None
    sources: list[FileSource] = Field(default_factory=list)

ImageTask

Bases: BaseTask

Workflow task rendering image content.

Source code in chatkit/models.py
493
494
495
496
497
class ImageTask(BaseTask):
    """Workflow task rendering image content."""

    type: Literal["image"] = "image"
    title: str | None = None

SourceBase

Bases: BaseModel

Base class for sources displayed to users.

Source code in chatkit/models.py
510
511
512
513
514
515
516
class SourceBase(BaseModel):
    """Base class for sources displayed to users."""

    title: str
    description: str | None = None
    timestamp: str | None = None
    group: str | None = None

FileSource

Bases: SourceBase

Source metadata for file-based references.

Source code in chatkit/models.py
519
520
521
522
523
class FileSource(SourceBase):
    """Source metadata for file-based references."""

    type: Literal["file"] = "file"
    filename: str

URLSource

Bases: SourceBase

Source metadata for external URLs.

Source code in chatkit/models.py
526
527
528
529
530
531
class URLSource(SourceBase):
    """Source metadata for external URLs."""

    type: Literal["url"] = "url"
    url: str
    attribution: str | None = None

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
class EntitySource(SourceBase):
    """Source metadata for entity references."""

    type: Literal["entity"] = "entity"
    id: str
    icon: icons.IconName | None = None
    label: str | None = None
    """Optional label shown with the icon in the default entity hover header
    when no preview callback is provided.
    """
    inline_label: str | None = None
    """Optional label for the inline annotation view. When not provided, the icon is used instead."""
    interactive: bool = False
    """Per-entity toggle to wire client callbacks and render this entity as interactive."""
    data: dict[str, Any] = Field(default_factory=dict)
    """Additional data for the entity source that is passed to client entity callbacks."""

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.