types

StreamingReq module-attribute

StreamingReq = (
    ThreadsCreateReq
    | ThreadsAddUserMessageReq
    | ThreadsAddClientToolOutputReq
    | ThreadsRetryAfterItemReq
    | ThreadsCustomActionReq
)

Union of request types that produce streaming responses.

NonStreamingReq module-attribute

NonStreamingReq = (
    ThreadsGetByIdReq
    | ThreadsListReq
    | ItemsListReq
    | ItemsFeedbackReq
    | AttachmentsCreateReq
    | AttachmentsDeleteReq
    | ThreadsUpdateReq
    | ThreadsDeleteReq
    | InputTranscribeReq
)

Union of request types that yield immediate responses.

ThreadStreamEvent module-attribute

ThreadStreamEvent = Annotated[
    ThreadCreatedEvent
    | ThreadUpdatedEvent
    | ThreadItemDoneEvent
    | ThreadItemAddedEvent
    | ThreadItemUpdated
    | ThreadItemRemovedEvent
    | ThreadItemReplacedEvent
    | StreamOptionsEvent
    | ProgressUpdateEvent
    | ClientEffectEvent
    | ErrorEvent
    | NoticeEvent,
    Field(discriminator="type"),
]

Union of all streaming events emitted to clients.

ThreadItemUpdate module-attribute

ThreadItemUpdate = (
    AssistantMessageContentPartAdded
    | AssistantMessageContentPartTextDelta
    | AssistantMessageContentPartAnnotationAdded
    | AssistantMessageContentPartDone
    | WidgetStreamingTextValueDelta
    | WidgetComponentUpdated
    | WidgetRootUpdated
    | WorkflowTaskAdded
    | WorkflowTaskUpdated
    | GeneratedImageUpdated
)

Union of possible updates applied to thread items.

ThreadStatus module-attribute

ThreadStatus = Annotated[
    ActiveStatus | LockedStatus | ClosedStatus,
    Field(discriminator="type"),
]

Union of lifecycle states for a thread.

ThreadItem module-attribute

ThreadItem = Annotated[
    UserMessageItem
    | AssistantMessageItem
    | ClientToolCallItem
    | WidgetItem
    | GeneratedImageItem
    | 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, Generic[T]

Paginated collection of records returned from the API.

Source code in chatkit/types.py

class Page(BaseModel, Generic[T]):
    """Paginated collection of records returned from the API."""

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

BaseReq

Bases: BaseModel

Base class for all request payloads.

Source code in chatkit/types.py

class BaseReq(BaseModel):
    """Base class for all request payloads."""

    metadata: dict[str, Any] = Field(default_factory=dict)
    """Arbitrary integration-specific metadata."""

metadata class-attribute instance-attribute

metadata: dict[str, Any] = Field(default_factory=dict)

Arbitrary integration-specific metadata.

ThreadsGetByIdReq

Bases: BaseReq

Request to fetch a single thread by its identifier.

Source code in chatkit/types.py

class ThreadsGetByIdReq(BaseReq):
    """Request to fetch a single thread by its identifier."""

    type: Literal["threads.get_by_id"] = "threads.get_by_id"
    params: ThreadGetByIdParams

ThreadGetByIdParams

Bases: BaseModel

Parameters for retrieving a thread by id.

Source code in chatkit/types.py

class ThreadGetByIdParams(BaseModel):
    """Parameters for retrieving a thread by id."""

    thread_id: str

ThreadsCreateReq

Bases: BaseReq

Request to create a new thread from a user message.

Source code in chatkit/types.py

class ThreadsCreateReq(BaseReq):
    """Request to create a new thread from a user message."""

    type: Literal["threads.create"] = "threads.create"
    params: ThreadCreateParams

ThreadCreateParams

Bases: BaseModel

User input required to create a thread.

Source code in chatkit/types.py

class ThreadCreateParams(BaseModel):
    """User input required to create a thread."""

    input: UserMessageInput

ThreadListParams

Bases: BaseModel

Pagination parameters for listing threads.

Source code in chatkit/types.py

class ThreadListParams(BaseModel):
    """Pagination parameters for listing threads."""

    limit: int | None = None
    order: Literal["asc", "desc"] = "desc"
    after: str | None = None

ThreadsListReq

Bases: BaseReq

Request to list threads.

Source code in chatkit/types.py

class ThreadsListReq(BaseReq):
    """Request to list threads."""

    type: Literal["threads.list"] = "threads.list"
    params: ThreadListParams

ThreadsAddUserMessageReq

Bases: BaseReq

Request to append a user message to a thread.

Source code in chatkit/types.py

class ThreadsAddUserMessageReq(BaseReq):
    """Request to append a user message to a thread."""

    type: Literal["threads.add_user_message"] = "threads.add_user_message"
    params: ThreadAddUserMessageParams

ThreadAddUserMessageParams

Bases: BaseModel

Parameters for adding a user message to a thread.

Source code in chatkit/types.py

class ThreadAddUserMessageParams(BaseModel):
    """Parameters for adding a user message to a thread."""

    input: UserMessageInput
    thread_id: str

ThreadsAddClientToolOutputReq

Bases: BaseReq

Request to add a client tool's output to a thread.

Source code in chatkit/types.py

class ThreadsAddClientToolOutputReq(BaseReq):
    """Request to add a client tool's output to a thread."""

    type: Literal["threads.add_client_tool_output"] = "threads.add_client_tool_output"
    params: ThreadAddClientToolOutputParams

ThreadAddClientToolOutputParams

Bases: BaseModel

Parameters for recording tool output in a thread.

Source code in chatkit/types.py

class ThreadAddClientToolOutputParams(BaseModel):
    """Parameters for recording tool output in a thread."""

    thread_id: str
    result: Any

ThreadsCustomActionReq

Bases: BaseReq

Request to execute a custom action within a thread.

Source code in chatkit/types.py

class ThreadsCustomActionReq(BaseReq):
    """Request to execute a custom action within a thread."""

    type: Literal["threads.custom_action"] = "threads.custom_action"
    params: ThreadCustomActionParams

ThreadCustomActionParams

Bases: BaseModel

Parameters describing the custom action to execute.

Source code in chatkit/types.py

class ThreadCustomActionParams(BaseModel):
    """Parameters describing the custom action to execute."""

    thread_id: str
    item_id: str | None = None
    action: Action[str, Any]

ThreadsRetryAfterItemReq

Bases: BaseReq

Request to retry processing after a specific thread item.

Source code in chatkit/types.py

class ThreadsRetryAfterItemReq(BaseReq):
    """Request to retry processing after a specific thread item."""

    type: Literal["threads.retry_after_item"] = "threads.retry_after_item"
    params: ThreadRetryAfterItemParams

ThreadRetryAfterItemParams

Bases: BaseModel

Parameters specifying which item to retry.

Source code in chatkit/types.py

class ThreadRetryAfterItemParams(BaseModel):
    """Parameters specifying which item to retry."""

    thread_id: str
    item_id: str

ItemsFeedbackReq

Bases: BaseReq

Request to submit feedback on specific items.

Source code in chatkit/types.py

class ItemsFeedbackReq(BaseReq):
    """Request to submit feedback on specific items."""

    type: Literal["items.feedback"] = "items.feedback"
    params: ItemFeedbackParams

ItemFeedbackParams

Bases: BaseModel

Parameters describing feedback targets and sentiment.

Source code in chatkit/types.py

class ItemFeedbackParams(BaseModel):
    """Parameters describing feedback targets and sentiment."""

    thread_id: str
    item_ids: list[str]
    kind: FeedbackKind

AttachmentsDeleteReq

Bases: BaseReq

Request to remove an attachment.

Source code in chatkit/types.py

class AttachmentsDeleteReq(BaseReq):
    """Request to remove an attachment."""

    type: Literal["attachments.delete"] = "attachments.delete"
    params: AttachmentDeleteParams

AttachmentDeleteParams

Bases: BaseModel

Parameters identifying an attachment to delete.

Source code in chatkit/types.py

class AttachmentDeleteParams(BaseModel):
    """Parameters identifying an attachment to delete."""

    attachment_id: str

AttachmentsCreateReq

Bases: BaseReq

Request to register a new attachment.

Source code in chatkit/types.py

class AttachmentsCreateReq(BaseReq):
    """Request to register a new attachment."""

    type: Literal["attachments.create"] = "attachments.create"
    params: AttachmentCreateParams

AttachmentCreateParams

Bases: BaseModel

Metadata needed to initialize an attachment.

Source code in chatkit/types.py

class AttachmentCreateParams(BaseModel):
    """Metadata needed to initialize an attachment."""

    name: str
    size: int
    mime_type: str

InputTranscribeReq

Bases: BaseReq

Request to transcribe an audio payload into text.

Source code in chatkit/types.py

class InputTranscribeReq(BaseReq):
    """Request to transcribe an audio payload into text."""

    type: Literal["input.transcribe"] = "input.transcribe"
    params: InputTranscribeParams

InputTranscribeParams

Bases: BaseModel

Parameters for speech transcription.

Source code in chatkit/types.py

class InputTranscribeParams(BaseModel):
    """Parameters for speech transcription."""

    audio_base64: str
    """Base64-encoded audio bytes."""

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

audio_base64 instance-attribute

audio_base64: str

Base64-encoded audio bytes.

mime_type instance-attribute

mime_type: str

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

AudioInput

Bases: BaseModel

Audio input data for transcription.

Source code in chatkit/types.py

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/types.py

class TranscriptionResult(BaseModel):
    """Input speech transcription result."""

    text: str

ItemsListReq

Bases: BaseReq

Request to list items inside a thread.

Source code in chatkit/types.py

class ItemsListReq(BaseReq):
    """Request to list items inside a thread."""

    type: Literal["items.list"] = "items.list"
    params: ItemsListParams

ItemsListParams

Bases: BaseModel

Pagination parameters for listing thread items.

Source code in chatkit/types.py

class ItemsListParams(BaseModel):
    """Pagination parameters for listing thread items."""

    thread_id: str
    limit: int | None = None
    order: Literal["asc", "desc"] = "desc"
    after: str | None = None

ThreadsUpdateReq

Bases: BaseReq

Request to update thread metadata.

Source code in chatkit/types.py

class ThreadsUpdateReq(BaseReq):
    """Request to update thread metadata."""

    type: Literal["threads.update"] = "threads.update"
    params: ThreadUpdateParams

ThreadUpdateParams

Bases: BaseModel

Parameters for updating a thread's properties.

Source code in chatkit/types.py

class ThreadUpdateParams(BaseModel):
    """Parameters for updating a thread's properties."""

    thread_id: str
    title: str

ThreadsDeleteReq

Bases: BaseReq

Request to delete a thread.

Source code in chatkit/types.py

class ThreadsDeleteReq(BaseReq):
    """Request to delete a thread."""

    type: Literal["threads.delete"] = "threads.delete"
    params: ThreadDeleteParams

ThreadDeleteParams

Bases: BaseModel

Parameters identifying a thread to delete.

Source code in chatkit/types.py

class ThreadDeleteParams(BaseModel):
    """Parameters identifying a thread to delete."""

    thread_id: str

ThreadCreatedEvent

Bases: BaseModel

Event emitted when a thread is created.

Source code in chatkit/types.py

class ThreadCreatedEvent(BaseModel):
    """Event emitted when a thread is created."""

    type: Literal["thread.created"] = "thread.created"
    thread: Thread

ThreadUpdatedEvent

Bases: BaseModel

Event emitted when a thread is updated.

Source code in chatkit/types.py

class ThreadUpdatedEvent(BaseModel):
    """Event emitted when a thread is updated."""

    type: Literal["thread.updated"] = "thread.updated"
    thread: Thread

ThreadItemAddedEvent

Bases: BaseModel

Event emitted when a new item is added to a thread.

Source code in chatkit/types.py

class ThreadItemAddedEvent(BaseModel):
    """Event emitted when a new item is added to a thread."""

    type: Literal["thread.item.added"] = "thread.item.added"
    item: ThreadItem

ThreadItemUpdatedEvent

Bases: BaseModel

Event describing an update to an existing thread item.

Source code in chatkit/types.py

class ThreadItemUpdatedEvent(BaseModel):
    """Event describing an update to an existing thread item."""

    type: Literal["thread.item.updated"] = "thread.item.updated"
    item_id: str
    update: ThreadItemUpdate

ThreadItemDoneEvent

Bases: BaseModel

Event emitted when a thread item is marked complete.

Source code in chatkit/types.py

class ThreadItemDoneEvent(BaseModel):
    """Event emitted when a thread item is marked complete."""

    type: Literal["thread.item.done"] = "thread.item.done"
    item: ThreadItem

ThreadItemRemovedEvent

Bases: BaseModel

Event emitted when a thread item is removed.

Source code in chatkit/types.py

class ThreadItemRemovedEvent(BaseModel):
    """Event emitted when a thread item is removed."""

    type: Literal["thread.item.removed"] = "thread.item.removed"
    item_id: str

ThreadItemReplacedEvent

Bases: BaseModel

Event emitted when a thread item is replaced.

Source code in chatkit/types.py

class ThreadItemReplacedEvent(BaseModel):
    """Event emitted when a thread item is replaced."""

    type: Literal["thread.item.replaced"] = "thread.item.replaced"
    item: ThreadItem

StreamOptions

Bases: BaseModel

Settings that control runtime stream behavior.

Source code in chatkit/types.py

class StreamOptions(BaseModel):
    """Settings that control runtime stream behavior."""

    allow_cancel: bool
    """Allow the client to request cancellation mid-stream."""

allow_cancel instance-attribute

allow_cancel: bool

Allow the client to request cancellation mid-stream.

StreamOptionsEvent

Bases: BaseModel

Event emitted to set stream options at runtime.

Source code in chatkit/types.py

class StreamOptionsEvent(BaseModel):
    """Event emitted to set stream options at runtime."""

    type: Literal["stream_options"] = "stream_options"
    stream_options: StreamOptions

ProgressUpdateEvent

Bases: BaseModel

Event providing incremental progress from the assistant.

Source code in chatkit/types.py

class ProgressUpdateEvent(BaseModel):
    """Event providing incremental progress from the assistant."""

    type: Literal["progress_update"] = "progress_update"
    icon: IconName | None = None
    text: str

ClientEffectEvent

Bases: BaseModel

Event emitted to trigger a client side-effect.

Source code in chatkit/types.py

class ClientEffectEvent(BaseModel):
    """Event emitted to trigger a client side-effect."""

    type: Literal["client_effect"] = "client_effect"
    name: str
    data: dict[str, Any] = Field(default_factory=dict)

ErrorEvent

Bases: BaseModel

Event indicating an error occurred while processing a thread.

Source code in chatkit/types.py

class ErrorEvent(BaseModel):
    """Event indicating an error occurred while processing a thread."""

    type: Literal["error"] = "error"
    code: ErrorCode | Literal["custom"] = Field(default="custom")
    message: str | None = None
    allow_retry: bool = Field(default=False)

NoticeEvent

Bases: BaseModel

Event conveying a user-facing notice.

Source code in chatkit/types.py

class NoticeEvent(BaseModel):
    """Event conveying a user-facing notice."""

    type: Literal["notice"] = "notice"
    level: Literal["info", "warning", "danger"]
    message: str
    """
    Supports markdown e.g. "You've reached your limit of 100 messages. [Upgrade](https://...) to a paid plan."
    """
    title: str | None = None

message instance-attribute

message: str

Supports markdown e.g. "You've reached your limit of 100 messages. Upgrade to a paid plan."

AssistantMessageContentPartAdded

Bases: BaseModel

Event emitted when new assistant content is appended.

Source code in chatkit/types.py

class AssistantMessageContentPartAdded(BaseModel):
    """Event emitted when new assistant content is appended."""

    type: Literal["assistant_message.content_part.added"] = (
        "assistant_message.content_part.added"
    )
    content_index: int
    content: AssistantMessageContent

AssistantMessageContentPartTextDelta

Bases: BaseModel

Event carrying incremental assistant text output.

Source code in chatkit/types.py

class AssistantMessageContentPartTextDelta(BaseModel):
    """Event carrying incremental assistant text output."""

    type: Literal["assistant_message.content_part.text_delta"] = (
        "assistant_message.content_part.text_delta"
    )
    content_index: int
    delta: str

AssistantMessageContentPartAnnotationAdded

Bases: BaseModel

Event announcing a new annotation on assistant content.

Source code in chatkit/types.py

class AssistantMessageContentPartAnnotationAdded(BaseModel):
    """Event announcing a new annotation on assistant content."""

    type: Literal["assistant_message.content_part.annotation_added"] = (
        "assistant_message.content_part.annotation_added"
    )
    content_index: int
    annotation_index: int
    annotation: Annotation

AssistantMessageContentPartDone

Bases: BaseModel

Event indicating an assistant content part is finalized.

Source code in chatkit/types.py

class AssistantMessageContentPartDone(BaseModel):
    """Event indicating an assistant content part is finalized."""

    type: Literal["assistant_message.content_part.done"] = (
        "assistant_message.content_part.done"
    )
    content_index: int
    content: AssistantMessageContent

WidgetStreamingTextValueDelta

Bases: BaseModel

Event streaming widget text deltas.

Source code in chatkit/types.py

class WidgetStreamingTextValueDelta(BaseModel):
    """Event streaming widget text deltas."""

    type: Literal["widget.streaming_text.value_delta"] = (
        "widget.streaming_text.value_delta"
    )
    component_id: str
    delta: str
    done: bool

WidgetRootUpdated

Bases: BaseModel

Event published when the widget root changes.

Source code in chatkit/types.py

class WidgetRootUpdated(BaseModel):
    """Event published when the widget root changes."""

    type: Literal["widget.root.updated"] = "widget.root.updated"
    widget: WidgetRoot

WidgetComponentUpdated

Bases: BaseModel

Event emitted when a widget component updates.

Source code in chatkit/types.py

class WidgetComponentUpdated(BaseModel):
    """Event emitted when a widget component updates."""

    type: Literal["widget.component.updated"] = "widget.component.updated"
    component_id: str
    component: WidgetComponent

WorkflowTaskAdded

Bases: BaseModel

Event emitted when a workflow task is added.

Source code in chatkit/types.py

class WorkflowTaskAdded(BaseModel):
    """Event emitted when a workflow task is added."""

    type: Literal["workflow.task.added"] = "workflow.task.added"
    task_index: int
    task: Task

WorkflowTaskUpdated

Bases: BaseModel

Event emitted when a workflow task is updated.

Source code in chatkit/types.py

class WorkflowTaskUpdated(BaseModel):
    """Event emitted when a workflow task is updated."""

    type: Literal["workflow.task.updated"] = "workflow.task.updated"
    task_index: int
    task: Task

GeneratedImageUpdated

Bases: BaseModel

Event emitted when a generated image is updated.

Source code in chatkit/types.py

class GeneratedImageUpdated(BaseModel):
    """Event emitted when a generated image is updated."""

    type: Literal["generated_image.updated"] = "generated_image.updated"
    image: GeneratedImage
    progress: float | None = None

ThreadMetadata

Bases: BaseModel

Metadata describing a thread without its items.

Source code in chatkit/types.py

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())
    # TODO - make not client rendered
    metadata: dict[str, Any] = Field(default_factory=dict)

ActiveStatus

Bases: BaseModel

Status indicating the thread is active.

Source code in chatkit/types.py

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/types.py

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/types.py

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/types.py

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/types.py

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/types.py

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/types.py

class AssistantMessageItem(ThreadItemBase):
    """Thread item representing an assistant message."""

    type: Literal["assistant_message"] = "assistant_message"
    content: list[AssistantMessageContent]

ClientToolCallItem

Bases: ThreadItemBase

Thread item capturing a client tool call.

Source code in chatkit/types.py

class ClientToolCallItem(ThreadItemBase):
    """Thread item capturing a client tool call."""

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

WidgetItem

Bases: ThreadItemBase

Thread item containing widget content.

Source code in chatkit/types.py

class WidgetItem(ThreadItemBase):
    """Thread item containing widget content."""

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

GeneratedImage

Bases: BaseModel

Generated image.

Source code in chatkit/types.py

class GeneratedImage(BaseModel):
    """Generated image."""

    id: str
    url: str

GeneratedImageItem

Bases: ThreadItemBase

Thread item containing a generated image.

Source code in chatkit/types.py

class GeneratedImageItem(ThreadItemBase):
    """Thread item containing a generated image."""

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

TaskItem

Bases: ThreadItemBase

Thread item containing a task.

Source code in chatkit/types.py

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/types.py

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/types.py

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/types.py

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/types.py

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/types.py

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/types.py

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/types.py

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/types.py

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/types.py

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/types.py

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/types.py

class ToolChoice(BaseModel):
    """Explicit tool selection for the assistant to invoke."""

    id: str

AttachmentUploadDescriptor

Bases: BaseModel

Two-phase upload instructions.

Source code in chatkit/types.py

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/types.py

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/types.py

class FileAttachment(AttachmentBase):
    """Attachment representing a generic file."""

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

ImageAttachment

Bases: AttachmentBase

Attachment representing an image resource.

Source code in chatkit/types.py

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/types.py

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/types.py

class CustomSummary(BaseModel):
    """Custom summary for a workflow."""

    title: str
    icon: IconName | None = None

DurationSummary

Bases: BaseModel

Summary providing total workflow duration.

Source code in chatkit/types.py

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/types.py

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/types.py

class CustomTask(BaseTask):
    """Workflow task displaying custom content."""

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

SearchTask

Bases: BaseTask

Workflow task representing a web search.

Source code in chatkit/types.py

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/types.py

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/types.py

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/types.py

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/types.py

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/types.py

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/types.py

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/types.py

class EntitySource(SourceBase):
    """Source metadata for entity references."""

    type: Literal["entity"] = "entity"
    id: str
    icon: 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."""

    preview: Literal["lazy"] | None = Field(
        default=None,
        deprecated=True,
        description="This field is ignored. Please use the entities.onRequestPreview ChatKit.js option instead.",
    )

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.

is_streaming_req

is_streaming_req(
    request: ChatKitReq,
) -> TypeIs[StreamingReq]

Return True if the given request should be processed as streaming.

Source code in chatkit/types.py

def is_streaming_req(request: ChatKitReq) -> TypeIs[StreamingReq]:
    """Return True if the given request should be processed as streaming."""
    return isinstance(
        request,
        (
            ThreadsCreateReq,
            ThreadsAddUserMessageReq,
            ThreadsRetryAfterItemReq,
            ThreadsAddClientToolOutputReq,
            ThreadsCustomActionReq,
        ),
    )