Metadata-Version: 2.4
Name: chat-sdk
Version: 0.4.27.1
Summary: Multi-platform async chat SDK for Python — port of Vercel Chat
Project-URL: Homepage, https://github.com/Chinchill-AI/chat-sdk-python
Project-URL: Repository, https://github.com/Chinchill-AI/chat-sdk-python
Project-URL: Issues, https://github.com/Chinchill-AI/chat-sdk-python/issues
License: MIT
License-File: LICENSE
Keywords: async,asyncio,bot-framework,chat,chatbot,chatops,discord-bot,slack-bot,teams-bot,telegram-bot,vercel,whatsapp-bot
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: aiohttp>=3.9; extra == 'all'
Requires-Dist: asyncpg>=0.29; extra == 'all'
Requires-Dist: cryptography>=42.0; extra == 'all'
Requires-Dist: google-auth>=2.0; extra == 'all'
Requires-Dist: pyjwt[crypto]>=2.8; extra == 'all'
Requires-Dist: pynacl>=1.5; extra == 'all'
Requires-Dist: redis>=5.0; extra == 'all'
Requires-Dist: slack-sdk>=3.27.0; extra == 'all'
Provides-Extra: crypto
Requires-Dist: cryptography>=42.0; extra == 'crypto'
Provides-Extra: discord
Requires-Dist: aiohttp>=3.9; extra == 'discord'
Requires-Dist: pynacl>=1.5; extra == 'discord'
Provides-Extra: github
Requires-Dist: pyjwt[crypto]>=2.8; extra == 'github'
Provides-Extra: google-chat
Requires-Dist: aiohttp>=3.9; extra == 'google-chat'
Requires-Dist: google-auth>=2.0; extra == 'google-chat'
Requires-Dist: pyjwt[crypto]>=2.8; extra == 'google-chat'
Provides-Extra: linear
Requires-Dist: aiohttp>=3.9; extra == 'linear'
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29; extra == 'postgres'
Provides-Extra: redis
Requires-Dist: redis>=5.0; extra == 'redis'
Provides-Extra: slack
Requires-Dist: slack-sdk>=3.27.0; extra == 'slack'
Provides-Extra: slack-socket
Requires-Dist: aiohttp>=3.9; extra == 'slack-socket'
Requires-Dist: slack-sdk>=3.27.0; extra == 'slack-socket'
Provides-Extra: teams
Requires-Dist: aiohttp>=3.9; extra == 'teams'
Provides-Extra: telegram
Requires-Dist: aiohttp>=3.9; extra == 'telegram'
Provides-Extra: whatsapp
Requires-Dist: aiohttp>=3.9; extra == 'whatsapp'
Description-Content-Type: text/markdown

# chat-sdk-python

[![PyPI](https://img.shields.io/pypi/v/chat-sdk)](https://pypi.org/project/chat-sdk/)
[![Python](https://img.shields.io/pypi/pyversions/chat-sdk)](https://pypi.org/project/chat-sdk/)
[![Tests](https://github.com/Chinchill-AI/chat-sdk-python/actions/workflows/test.yml/badge.svg)](https://github.com/Chinchill-AI/chat-sdk-python/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Multi-platform async chat SDK for Python. Port of [Vercel Chat](https://github.com/vercel/chat).

> **Status: 0.4.27** — synced to upstream [Vercel Chat 4.27.0](https://github.com/vercel/chat) (release commit `f55378a`). See [CHANGELOG.md](CHANGELOG.md) for release notes and [docs/UPSTREAM_SYNC.md](docs/UPSTREAM_SYNC.md) for the known non-parity list.

## Why chat-sdk?

- **Write once, deploy to 8 platforms.** One handler runs on Slack, Discord, Teams, Telegram, WhatsApp, 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

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

## Quick Start

```python
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 |
| Google Chat | `chat-sdk[google-chat]` | Alpha |
| GitHub | `chat-sdk[github]` | Alpha |
| Linear | `chat-sdk[linear]` | Alpha |

## 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 | 8 platforms | 1 per SDK | Teams + limited |
| Async-native (Python 3.10+) | 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](docs/ARCHITECTURE.md) | Module dependency graph, adapter protocol, card system, concurrency strategies, state backends, markdown pipeline, streaming pipeline |
| [Upstream Sync](docs/UPSTREAM_SYNC.md) | How to keep the Python port in sync with the Vercel Chat TS SDK, translation patterns, known footguns |
| [Security](docs/SECURITY.md) | Webhook verification per platform, SSRF protections, crypto details, known limitations, production audit checklist |
| [Testing](docs/TESTING.md) | Test categories, how to run tests, how to add adapter tests, coverage gaps, dispatch key validation |
| [Design Decisions](docs/DECISIONS.md) | Rationale for key architectural choices (hand-rolled parser, PascalCase builders, global singleton, zero deps) |
| [Contributing](CONTRIBUTING.md) | Dev setup, code quality, PR expectations |
| [Changelog](CHANGELOG.md) | Release history |

## Development

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

## License

MIT
