Repository navigation
Turnspan 3
Turnspan 3 installs as openai-chatkit 1.6.5+turnspan.3 and requires Python 3.14 or newer.
What's new
- The FastAPI adapter returns clear HTTP errors for invalid
requests and closes event producers when the client disconnects. The
browser demo runs locally withmake demo. - Use
prepare_user_messageto validate or enrich new messages before ChatKit
writes them. FastAPI integrations can supply astreaming_responsefactory
for custom streaming and cleanup. Server lifecycle - Streamed and reloaded widgets share a lossless representation. Card borders
survive reload, empty widget streams complete cleanly, and a disconnect
closes the widget producer. - Image previews and web-search progress are tracked by provider item ID.
Overlapping calls keep separate progress and results. Thanks to Francis
Poisson-Gagnon for the web-search report
and proposed fix. - The SQLite example
demonstrates durable storage.chatkit.store_checkssupplies reusable checks
for custom thread stores. - Test helpers live outside test modules, and pytest uses
importlibmode
in clean checkouts. Thanks to Mark Zhang for
reporting the import problem. - The docs now build with Zensical and publish to
GitHub Pages. - The pinning guide
shows how to verify the installed package in the artifact serving traffic.
Upgrade from Turnspan 2
- Implement
respond(self, turn)using the typed trigger onturn.input.
Useon_turn_finishedto observe whether the server completed, is waiting
for input, cancelled, or failed. - Implement
ThreadStorefor thread and item persistence. Configure attachment
metadata and file operations throughAttachmentMetadataStoreand
AttachmentStorewhere needed. - Import thread records from
chatkit.models, requests fromchatkit.requests,
and stream events fromchatkit.events. UseThreadItemUpdatedEventfor
item updates andchatkit.icons.IconNamefor widget icons. - Import history conversion from
chatkit.agent_input, widget producers from
chatkit.widget_stream, and widget JSON models fromchatkit.widget_models.
Install thetemplatesextra and importWidgetTemplatefrom
chatkit.templatesto render.widgetfiles. Relative template paths use
the process's working directory. - Custom stores filter hidden items before paginating when
load_thread_items
receivesinclude_hidden=False. New item IDs generated by the SDK use a
full UUID, and new SDK timestamps include a UTC offset. - Configure the
chatkitlogger in your application. Stream errors expose a
code and retry flag. Entity previews use the browser'sonRequestPreview
callback. - Typed
Actionconstructors take an explicit type and payload. The browser
request model accepts actions without a payload, and an action without a
name returns HTTP 422. - Pass provider continuation IDs to
Runner.run_streamed. AnAgentContext
belongs to one response run, and writes after it closes raise
asyncio.QueueShutDown. - Client tool callbacks use
AgentContext.request_client_toolwith the
Agents SDK'sToolContextto bind the browser callback to its invocation. - Custom HTTP transports parse the request with
chatkit.protocol.parse_request,
pass the typed request toChatKitServer.process, and serialize the typed
response or closeable event stream with the protocol helpers. - Thread stores implement atomic
claim_pending_item,patch_thread, and
truncate_afteroperations. Return the retained user message from
truncate_afterafter later items disappear from pagination and direct
reads. The store checks cover both read paths. In a responder, yield the
event fromChatKitServer.update_threadto persist a display change and
show it to the client. UseThreadStore.patch_threadfor metadata-only writes. - Typed widget builders use
.build()to produce a canonical widget tree
for direct item or update construction. UseWidgetTemplate.build()for
every template root, including entity previews. - Install the
agentsextra when usingchatkit.agents. Thefastapiextra
supplies the HTTP adapter's dependencies and Uvicorn.
See the timestamp migration guide for stores that still contain timestamps without offsets.
Install from the tested commit
python -m pip install 'openai-chatkit @ https://github.com/michaelgiraldo/chatkit-python/archive/e0decabf3101e4326af054ebfe2c766112e30e66.tar.gz'See the pinning guide for lockfile installation, optional extras, and deployed artifact verification.
Verification
GitHub Actions passed 247 tests, formatting and type checks, the strict documentation build, distribution builds, and clean wheel installs. CI and docs deployment