ChatKit Python SDK

The ChatKit Python SDK provides tools for building chat-based applications. To begin using the SDK, you should follow the Quick start guide, understand the core concept of Threads, and refer to the API reference for detailed method signatures.

Key resources for developers:

• Quick start: For initial setup and first calls.
• Core concepts: To understand how Threads manage conversation state.
• Guides: For specific tasks like responding to user messages or preparing an application for production.
• API reference: For the complete technical specification of the chatkit package.

The Chatkit Python API is organized into several functional modules to help you build chat-based applications, manage state, and integrate with agents:

• chatkit.server: Use ChatKitServer and its helpers to receive incoming messages, stream responses, and wire up tools and widgets.
• chatkit.store: Provides interfaces and utilities for persisting threads, items, and metadata.
• chatkit.agents: Contains helpers and utilities for using ChatKit in conjunction with the Agents SDK.
• chatkit.types: Access Pydantic models for core data structures like threads, items, and events.
• chatkit.errors: Use these structured error types to ensure your integration emits consistent ErrorEvents to the client.
• chatkit.widgets: Use models and helpers like WidgetTemplate, DynamicWidgetRoot, and BasicRoot to build rich UI responses.

In ChatKit, a thread is the central unit representing a single conversation. It acts as an ordered timeline of thread items, which includes conversation history (user and assistant messages), structured content (widgets, workflows), internal signals, and metadata (titles, status flags).

Threads are persisted by your store implementation. ChatKit manages the lifecycle of a thread by loading, paginating, and rendering these items as needed. A thread can be updated, continued, or made read-only based on your application logic.

Tools allow an assistant to execute application logic during a conversation turn. This enables the model to search data, run workflows, or fetch user context, then incorporate the results back into the conversation.

There are two primary types of tools:

1. Server tools: Run on your backend. The assistant calls them through your inference pipeline, and results are streamed back into the conversation.
2. Client tools: Run in the browser or host application. ChatKit surfaces the tool call as a streamed thread item, allows the client to handle the execution, and then resumes the conversation with the client's output.

Choose between two upload strategies by setting ChatKitOptions.api.uploadStrategy:

1. Direct: The client sends bytes to a single uploadUrl provided by your backend. This is simpler and faster if your app server handles uploads directly.
2. Two-phase: The client first requests metadata via the ChatKit API, receives an upload_url (e.g., a presigned cloud storage URL), and then uploads the bytes in a second step. This is preferred for offloading bandwidth to third-party blob storage or using cloud object storage.

Note: Both strategies require an AttachmentStore to handle delete cleanup.

// Example Direct configuration
{
  type: "direct",
  uploadUrl: "/files",
}

// Example Two-phase configuration
{
  type: "two_phase",
}

ThreadStreamEvents are Server-Sent Event (SSE) payloads streamed by ChatKitServer during user interactions. These events serve two primary purposes:

1. UI Synchronization: They keep the client interface in sync with server-side processing.
2. Persistence: They drive the persistence of conversation state in your data store.

Events are categorized into metadata updates, item events, errors, progress updates, client effects, and stream options.

You can use entities to provide citations or references within assistant responses. This allows the assistant to link its text to specific data objects.

To implement this, you should use the EntitySource Pydantic model to define the source of the information. For detailed implementation steps on how to attach these to messages, refer to the guide on adding annotations in assistant messages.

Hidden context items are included in the model input but are not rendered in the chat UI. They allow the model to react to interface actions (like widget interactions or selection states) that aren't explicitly typed by the user.

• HiddenContextItem: Integration-defined context where you control the schema and how it is converted for the model.
• SDKHiddenContextItem: Internal hidden context used by the ChatKit Python SDK. Most applications do not need to modify this.

Thread items are the individual records that constitute a thread's history. They serve two primary roles:

1. Model Input: Your server's respond logic reads thread items to construct the context for the model. This ensures the model maintains conversational continuity.
2. UI Rendering: On the client side, ChatKit.js renders these items incrementally as they stream in or when a past thread is loaded to reconstruct the conversation UI.

Common item types include user messages, assistant messages, widgets, and hidden context items.