Skip to content

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

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.