Turnspan for ChatKit
Turnspan is a maintained fork of OpenAI's ChatKit Python SDK for self-hosted ChatKit applications. It connects the official ChatKit browser component to a Python backend you control.
Coming from OpenAI's repository? Install openai-chatkit from this fork
and import its modules through chatkit. Turnspan requires Python 3.14 or
newer. Application responders implement respond(self, turn: Turn).
The Agents SDK and FastAPI adapters are optional extras.
Use a fresh thread store for your first setup. The
server guide
shows how to wire the responder and storage.
Try the demo
With Git, uv, and make installed, clone the fork and run the demo.
If you already have the checkout you want to try, run make demo there.
git clone https://github.com/michaelgiraldo/chatkit-python.git turnspan-demo
cd turnspan-demo
make demo
Open the demo on port 8000 and send hello.
The demo uses sample replies and runs without a model API key.
Install Turnspan in an app
Turnspan 7
is the latest stable release (openai-chatkit 1.6.5+turnspan.7). Install
the verified source commit in your app's Python environment.
python -m pip install 'openai-chatkit[agents,fastapi] @ https://github.com/michaelgiraldo/chatkit-python/archive/1680fed58b24021581622edd5c75073eb0194ca7.tar.gz'
Omit [agents,fastapi] for the core server alone. Add templates to the
extras if your app loads .widget files. See the
docs at the release commit
for the matching Python and storage contracts.
Upgrading from Turnspan 6 to 7? Check your thread store's history queries and form handling. Apps using Agents SDK tool approvals also need to save paused runs. The app migration checklist covers the affected integrations. The ChatKit browser component can stay on its current version for this upgrade.
To install a local development checkout, run this from its repository root.
python -m pip install '.[agents,fastapi]'
Documentation
- Try the demo and connect a model
- Core concepts
- Respond to a user message
- Prepare your app for production
- API reference
- ChatKit JS docs
- Changelog
- Upstream status
Project scope
Turnspan connects the ChatKit browser component to an application-owned Python backend. It handles ChatKit requests, thread and widget events, stream cleanup, and the lifecycle of browser tools. It defines the storage contract for those operations, and each application supplies its store. The optional Agents SDK adapter translates model streams into ChatKit events and carries native model context across browser tool callbacks.
Each application defines its responses, authentication, models, and provider configuration. Prompts, lead routing, other business rules, and app-specific tests belong with the application.
When proposing a change for Turnspan, ask whether a second application would need the same ChatKit server behavior. A browser tool result reaching the right pending call is a shared SDK behavior. What a business does with that result is an application decision.