Skip to content

events

Stream events and updates delivered to ChatKit clients.

ThreadStreamEvent module-attribute

Union of all streaming events emitted to clients.

ThreadCreatedEvent

Bases: BaseModel

Event emitted when a thread is created.

Source code in chatkit/events.py
10
11
12
13
14
class ThreadCreatedEvent(BaseModel):
    """Event emitted when a thread is created."""

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

ThreadUpdatedEvent

Bases: BaseModel

Event emitted when a thread is updated.

Source code in chatkit/events.py
17
18
19
20
21
class ThreadUpdatedEvent(BaseModel):
    """Event emitted when a thread is updated."""

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

ThreadItemAddedEvent

Bases: BaseModel

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

Source code in chatkit/events.py
24
25
26
27
28
class ThreadItemAddedEvent(BaseModel):
    """Event emitted when a new item is added to a thread."""

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

ThreadItemUpdatedEvent

Bases: BaseModel

Event describing an update to an existing thread item.

Source code in chatkit/events.py
31
32
33
34
35
36
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/events.py
39
40
41
42
43
class ThreadItemDoneEvent(BaseModel):
    """Event emitted when a thread item is marked complete."""

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

ThreadItemRemovedEvent

Bases: BaseModel

Event emitted when a thread item is removed.

Source code in chatkit/events.py
46
47
48
49
50
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/events.py
53
54
55
56
57
class ThreadItemReplacedEvent(BaseModel):
    """Event emitted when a thread item is replaced."""

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

StreamOptions

Bases: BaseModel

Settings that control runtime stream behavior.

Source code in chatkit/events.py
60
61
62
63
64
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/events.py
67
68
69
70
71
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/events.py
74
75
76
77
78
79
class ProgressUpdateEvent(BaseModel):
    """Event providing incremental progress from the assistant."""

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

ClientEffectEvent

Bases: BaseModel

Event emitted to trigger a client side-effect.

Source code in chatkit/events.py
82
83
84
85
86
87
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/events.py
90
91
92
93
94
95
96
class ErrorEvent(BaseModel):
    """Event indicating an error occurred while processing a thread."""

    type: Literal["error"] = "error"
    code: errors.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/events.py
 99
100
101
102
103
104
105
106
107
108
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/events.py
131
132
133
134
135
136
137
138
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: models.AssistantMessageContent

AssistantMessageContentPartTextDelta

Bases: BaseModel

Event carrying incremental assistant text output.

Source code in chatkit/events.py
141
142
143
144
145
146
147
148
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/events.py
151
152
153
154
155
156
157
158
159
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: models.Annotation

AssistantMessageContentPartDone

Bases: BaseModel

Event indicating an assistant content part is finalized.

Source code in chatkit/events.py
162
163
164
165
166
167
168
169
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: models.AssistantMessageContent

WidgetStreamingTextValueDelta

Bases: BaseModel

Event streaming widget text deltas.

Source code in chatkit/events.py
172
173
174
175
176
177
178
179
180
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/events.py
183
184
185
186
187
class WidgetRootUpdated(BaseModel):
    """Event published when the widget root changes."""

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

WidgetComponentUpdated

Bases: BaseModel

Event emitted when a widget component updates.

Source code in chatkit/events.py
190
191
192
193
194
195
class WidgetComponentUpdated(BaseModel):
    """Event emitted when a widget component updates."""

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

WorkflowTaskAdded

Bases: BaseModel

Event emitted when a workflow task is added.

Source code in chatkit/events.py
198
199
200
201
202
203
class WorkflowTaskAdded(BaseModel):
    """Event emitted when a workflow task is added."""

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

WorkflowTaskUpdated

Bases: BaseModel

Event emitted when a workflow task is updated.

Source code in chatkit/events.py
206
207
208
209
210
211
class WorkflowTaskUpdated(BaseModel):
    """Event emitted when a workflow task is updated."""

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

GeneratedImageUpdated

Bases: BaseModel

Event emitted when a generated image is updated.

Source code in chatkit/events.py
214
215
216
217
218
219
class GeneratedImageUpdated(BaseModel):
    """Event emitted when a generated image is updated."""

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

SyncCustomActionResponse

Bases: BaseModel

Single thread item update returned by a sync custom action.

Source code in chatkit/events.py
237
238
239
240
class SyncCustomActionResponse(BaseModel):
    """Single thread item update returned by a sync custom action."""

    updated_item: models.ThreadItem | None = None