Repository navigation
Releases
Turnspan 7
Package openai-chatkit 1.6.5+turnspan.7 · Python 3.14 · Tag v1.6.5+turnspan.7
Source commit 1680fed58b24021581622edd5c75073eb0194ca7.
Upgrading an app from Turnspan 6
Update the backend source pin and refresh your app's dependency lock. Python
3.14 remains the minimum. You can keep your existing ChatKit browser component.
Check the rows that apply to your backend.
| If your app uses… | What to change or verify |
|---|---|
| A custom thread store | For browser reads (include_hidden=False), filter server-only items and ineligible pending browser tools before applying the cursor and limit. Compute after and has_more from visible items. Turnspan now rejects a page containing either hidden context type. Apply the same rule if your responder supplies paginated thread snapshots. Store guide |
| Forms | Record which turn issued the form. In the same transaction that claims it, raise ConflictError and leave it pending if a different turn is ACCEPTED or RUNNING. This prevents an old form submission from interrupting a newer reply. SQLite example |
Extra fields on AgentContext |
Unknown constructor keywords now raise a validation error. Move request-scoped values into request_context or declare typed fields on a subclass. App context guide |
| Agents SDK tools that pause for human approval | Implement ChatKitServer.save_approval_checkpoint(thread, turn_id, checkpoint, context). Save the serialized run privately under the authenticated owner, thread, and turn. Forward ApprovalRequired if your responder filters events. A successful save puts the turn in WAITING. A missing hook or failed save produces FAILED. Approval example |
| Store tests for browser tools | Run both check_thread_store and check_client_tool_store. The first now covers core storage and browser history. The second exercises browser tool callbacks. Store test example |
An import of chatkit.widgets.MinMax |
Remove the import. If your app used this removed annotation for its own data, define the bounds type in your app. Chart JSON schemas are unchanged. |
The agents extra |
Allow openai>=3.57.0,<4 in your app lock. The Agents SDK requirement remains openai-agents>=0.25.0,<0.26. Zensical 0.1.3 is a documentation build dependency. |
Streaming and thread history
- When a visitor leaves during a silent FastAPI stream, the server stops the
producer. On ordinary streaming turns the partial reply survives reload, and
the visitor can send another message. - If a responder streams
Hiand then finishes building that same message,
the saved reply readsHionce. Turnspan also isolates streamed citations
and workflow tasks from subsequent edits the responder hasn't sent. - Widget actions keep app and SDK hidden context out of browser replies.
A private context update leaves an active progress display open while the
agent continues working. - When the app replays thread history, Turnspan sends assistant text as model
input and keeps the recorded Responses phase, such ascommentaryor
final_answer. Stores that serialize individual fields should round-trip
the optional assistantphaseto preserve this behavior.
Optional reviewed replies
For an app that checks an answer before a visitor sees it, configure an Agents
SDK output guardrail and pass delivery="reviewed_text" to
stream_agent_response. The browser receives the approved final text in one
message. A rejection or disconnect during review keeps the candidate out of
the ChatKit transcript. Ordinary streaming remains the default for apps that
show intermediate events or use interactive browser tools.
Reviewed delivery guide
Install
python -m pip install 'openai-chatkit[agents,fastapi] @ https://github.com/michaelgiraldo/chatkit-python/archive/1680fed58b24021581622edd5c75073eb0194ca7.tar.gz'Documentation for this commit · Pin and verify the installed build
Verification
-
Locked versions in the SDK repository were OpenAI Python
3.57.0and Agents SDK0.25.0. -
The consumer smoke ran on Python
3.14.10with OpenAI Python3.57.0and Agents SDK0.25.0. It exercised the quickstart, FastAPI, and mocked model HTTP from an isolated source install. -
GitHub release verification installed the public source archive and passed all 42 consumer tests.
Turnspan 6
Package openai-chatkit 1.6.5+turnspan.6 · Python 3.14 · Tag v1.6.5+turnspan.6
Source commit 0d916c03ef8e48d4d77ddcc461431e1d6f7b8718.
- Breaking store contract. Every streaming response has a durable turn
ID. Custom stores implement atomic turn ownership, fenced responder
writes, and persisted milestones. Use a fresh schema for this candidate.
Streaming actions receiveturn_id. Supply the current ID to
update_threadand other direct responder writes. - The server distinguishes a saved callback from responder start and
completion. Closing a response before processing starts records
ABANDONED. Started responders can reportSUPERSEDEDwhen a new
request takes ownership. - Breaking Python and storage contract. Browser tools publish a
ClientToolCallItemcontaining display data. The server registers a
separateClientToolInvocationwith model data and the turn linkage.
Custom responders yieldClientToolRequestto register the pair.
Pass the completeClientToolTurnto
client_tool_continuation_input. The ChatKit browser still sends the
same callback envelope. - Browser tools return the ID of the exact saved invocation. Each callback can
complete once, and a newer turn can cancel a pending invocation. - The Agents SDK adapter preserves the original model call and any sibling tool
results. Choose local replay or OpenAI-managed Responses context when
registering the tool. - The browser tool guide
documents the current callback, continuation, and storage contracts.
Install
python -m pip install 'openai-chatkit[agents,fastapi] @ https://github.com/michaelgiraldo/chatkit-python/archive/0d916c03ef8e48d4d77ddcc461431e1d6f7b8718.tar.gz'Documentation for this commit · Pin and verify the installed build
Verification
-
Locked versions in the SDK repository were OpenAI Python
3.56.0and Agents SDK0.25.0. -
The consumer smoke ran on Python
3.14.10with OpenAI Python3.57.0and Agents SDK0.25.0. It exercised the quickstart, FastAPI, and mocked model HTTP from an isolated source install. -
GitHub release verification installed the public source archive and passed all 30 smoke tests.
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
Turnspan 2
Turnspan 2 is the public Python 3.14 fork of OpenAI ChatKit. It installs as openai-chatkit 1.6.5+turnspan.2 and uses the existing chatkit imports.
What changed
- Chat Completions replies get distinct IDs that stay consistent during streaming and after reload. Responses keeps the IDs OpenAI supplies. Thanks to Jacob Babula. PR #128
- A
ListViewinside aCardnow parses as a typed list. We verified that it renders, handles clicks, and restores its updated state in the official ChatKit browser client. Thanks to Saloni Garg. PR #137 - Agents requests now use the SDK default User-Agent or the app's configured value. Turnspan's automatic
ChatKit/Pythonsuffix was removed. - Plain
pytestworks in a clean checkout withPYTHONPATHunset. Thanks to Mark Zhang. PR #122 - The response guide shows how tools can access the thread ID and how to persist structured results after a successful stream. Thanks to Jao Garcia. Issue #120
Install
Turnspan 2 requires Python 3.14 or newer, OpenAI Python >=3.56.0,<4, and Agents SDK >=0.25.0,<0.26.
python -m pip install 'openai-chatkit @ https://github.com/michaelgiraldo/chatkit-python/archive/4c7ba491e885fedf5c8cb97aa0546770e0f64e15.tar.gz'See the pinning guide for locking an app to this commit.
Verification
GitHub Actions passed all 164 tests, formatting and type checks, the docs build, and clean wheel installs with and without FastAPI. CI run
Turnspan 1
Turnspan 1 is the first named release of the maintained Python 3.14 fork of OpenAI ChatKit 1.6.5. It installs as openai-chatkit 1.6.5+turnspan.1 and uses the existing chatkit imports.
What changed
- Chat streams close when the user stops or disconnects. The server restores request headers and can save a partial reply so the thread can be reloaded and continued.
- Widget updates handle removed and added properties and text components without IDs. Repeated workflow tasks update the correct position. An empty streamed citation leaves later citations intact.
- The quickstart includes a FastAPI extra and an offline backend smoke test. The Responses examples cover saving a completed response ID and falling back to thread history. The model and transcription examples use current OpenAI models.
Install requirements
Python 3.14 or newer, OpenAI Python >=3.56.0,<4, and Agents SDK >=0.25.0,<0.26. The package also requires Pydantic >=2.14.4,<3, Uvicorn >=0.54.0,<1, and Jinja >=3.1.6,<4. See the pinning guide for the commit-pinned install.
Install from the tested commit with Python 3.14 or newer.
python -m pip install 'openai-chatkit @ https://github.com/michaelgiraldo/chatkit-python/archive/19c16aaee8af715c909471b60534d1a1a4c26c55.tar.gz'Verification
GitHub Actions passed all 161 tests, formatting and type checks, the docs build, and clean wheel installs with and without the FastAPI extra.
Credits
- Andrew Barnes for dynamic widget properties (#134).
- Shubham Padkonde for streamed widget text and the disconnect report (#132, #133).
- Rio Yu for workflow task indexing and the header restoration report (#135, #136).
- Jao Garcia for the backend smoke test (#118).
- Nate Jones for the streamed citation conversion fix (#129).