chat-sdk-python

Multi-platform async chat SDK for Python. Port of Vercel Chat.

Status: 0.4.31 — synced to Vercel Chat 4.31.0 (UPSTREAM_PARITY = "4.31.0"). See CHANGELOG.md.

Why chat-sdk?

Write once, deploy to 9 platforms. One handler runs on Slack, Discord, Teams, Telegram, WhatsApp, Messenger, Google Chat, GitHub, and Linear.
Built-in concurrency primitives. Deduplication, thread locking, and message queuing are handled for you.
Cross-platform cards. Author a Card once and it renders as Block Kit (Slack), Adaptive Cards (Teams), embeds (Discord), and more.
Not a replacement for platform SDKs. chat-sdk is built on top of them. You can always drop down to the native SDK when you need to.

Install

pip install chat-sdk                   # core only
pip install chat-sdk[slack]            # + Slack adapter
pip install chat-sdk[all]              # all adapters + state backends

Quick Start

from chat_sdk import Chat, Card, Button, Actions, MemoryStateAdapter
from chat_sdk.adapters.slack import create_slack_adapter

chat = Chat(
    adapters={"slack": create_slack_adapter()},
    state=MemoryStateAdapter(),
    user_name="my-bot",
)

@chat.on_mention
async def handle_mention(thread, message):
    await thread.post(
        Card(title="Hello!", children=[
            Actions([Button(id="hi", label="Say Hi")])
        ])
    )

Adapters

Platform	Install Extra	Status
Slack	`chat-sdk[slack]`	Alpha
Discord	`chat-sdk[discord]`	Alpha
Teams	`chat-sdk[teams]`	Alpha
Telegram	`chat-sdk[telegram]`	Alpha
WhatsApp	`chat-sdk[whatsapp]`	Alpha
Messenger (Meta)	`chat-sdk[messenger]`	Alpha
Google Chat	`chat-sdk[google-chat]`	Alpha
GitHub	`chat-sdk[github]`	Alpha
Linear	`chat-sdk[linear]`	Alpha

AI / LLM Integration

Expose chat actions to an LLM agent as tools (chat/ai parity, vercel/chat#492):

from chat_sdk.ai import create_chat_tools, to_ai_messages

tools = create_chat_tools(chat, preset="messenger", require_approval=True)
# {"postMessage": ChatTool(description=..., input_schema={...}, execute=..., needs_approval=True), ...}

Each ChatTool is SDK-agnostic: input_schema is a JSON-Schema dict you can hand to any agent runtime (Anthropic tool use, OpenAI tools, pydantic-ai, ...), execute is the async implementation, and needs_approval flags write tools for human-in-the-loop gating. Presets: reader, messenger, moderator. to_ai_messages(thread) converts thread history into model-ready messages. Runnable demo: examples/ai_tools_example.py.

State Backends

Backend	Install Extra
In-Memory	Built-in
Redis	`chat-sdk[redis]`
PostgreSQL	`chat-sdk[postgres]`

Compared to Alternatives

Feature	chat-sdk	Raw platform SDKs	BotFramework SDK
Multi-platform from one codebase	9 platforms	1 per SDK	Teams + limited
Async-native (Python 3.12+)	Yes	Varies	No
Cross-platform cards	Card model	Platform-specific	Adaptive Cards only
Thread locking / dedup	Built-in	DIY	DIY
State abstraction (mem/redis/pg)	Built-in	DIY	DIY
Drop down to native SDK	Yes	N/A	Partially

Documentation

Document	Description
Architecture	Module dependency graph, adapter protocol, card system, concurrency strategies, state backends, markdown pipeline, streaming pipeline
Upstream Sync	How to keep the Python port in sync with the Vercel Chat TS SDK, translation patterns, known footguns
Security	Webhook verification per platform, SSRF protections, crypto details, known limitations, production audit checklist
Testing	Test categories, how to run tests, how to add adapter tests, coverage gaps, dispatch key validation
Design Decisions	Rationale for key architectural choices (hand-rolled parser, PascalCase builders, global singleton, zero deps)
Contributing	Dev setup, code quality, PR expectations
Changelog	Release history

Development

uv sync --group dev
uv run pytest tests/
uv run ruff check src/

License

MIT

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

chat_sdk-0.4.31.tar.gz (1.2 MB view details)

Uploaded Jun 20, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

chat_sdk-0.4.31-py3-none-any.whl (544.8 kB view details)

Uploaded Jun 20, 2026 Python 3

File details

Details for the file chat_sdk-0.4.31.tar.gz.

File metadata

Download URL: chat_sdk-0.4.31.tar.gz
Upload date: Jun 20, 2026
Size: 1.2 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for chat_sdk-0.4.31.tar.gz
Algorithm	Hash digest
SHA256	`0982e17d555f466b3ca6e685de0d0a09c9eb46b8f6bb6cf4e89e5efa0ec9b303`
MD5	`eee929d553b4c2d48405ab892f203678`
BLAKE2b-256	`bcff5d45b1e0fac2d5bcb77e5af25ce2a350aed63ae276f2664535cbdc9a7336`

See more details on using hashes here.

Provenance

The following attestation bundles were made for chat_sdk-0.4.31.tar.gz:

Publisher: publish.yml on Chinchill-AI/chat-sdk-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: chat_sdk-0.4.31.tar.gz
- Subject digest: 0982e17d555f466b3ca6e685de0d0a09c9eb46b8f6bb6cf4e89e5efa0ec9b303
- Sigstore transparency entry: 1881988928
- Sigstore integration time: Jun 20, 2026
Source repository:
- Permalink: Chinchill-AI/chat-sdk-python@3d753c048e1ee4aa1629a78a0c9f5bfc26f6a76c
- Branch / Tag: refs/tags/v0.4.31
- Owner: https://github.com/Chinchill-AI
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@3d753c048e1ee4aa1629a78a0c9f5bfc26f6a76c
- Trigger Event: release