Releases and changelog
Turnspan keeps the OpenAI ChatKit base version and increments the
+turnspan.N suffix for fork builds. Get published builds from
Turnspan's GitHub releases.
The openai-chatkit package on PyPI is published by the
original OpenAI project.
Verify and publish a release
- Set the version in
pyproject.toml, refreshuv.lock, and add a matching changelog section. Commit the candidate and runmake check,make build, andmake release-checkwith Python 3.14. The release check installs the committedHEADin isolation and exercises the quickstart, FastAPI, and Agents SDK with synthetic inputs. - Merge to
mainand wait for CI to pass. Run the Verify Turnspan release workflow once with the full commit SHA. It verifies that commit's CI result and repeats the consumer check using the public GitHub source archive.
gh workflow run turnspan-release.yml --ref main -f sha=COMMIT_SHA
- Copy the release notes from the workflow summary. Create the GitHub release manually with the indicated tag and exact commit. If the tag already exists, verify its target. After publishing, confirm the tag resolves to the tested commit and update the shared install section in the README. The docs landing page renders that same section.
The workflow only verifies and produces notes. The notes include the commit, install command, tested dependency versions, and links to docs at that commit.
Turnspan 7 (1.6.5+turnspan.7)
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 as
commentaryorfinal_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
Turnspan 6 (1.6.5+turnspan.6)
- 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 Turnspan 6.
Streaming actions receive
turn_id. Supply the current ID toupdate_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 completeClientToolTurntoclient_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.
Turnspan 5 (1.6.5+turnspan.5)
- Development milestone.
AgentContexttakes an explicitresume_fromoption for a saved display workflow. UseNonefor a fresh run.
Turnspan 4 (1.6.5+turnspan.4)
- Development milestone. Added control over workflow history reads.
Turnspan 3 (1.6.5+turnspan.3)
- Early published build. Added typed turns, explicit store operations, optional integrations, a FastAPI adapter, and a runnable local demo.
- Improved streamed and reloaded widgets. Image previews and web-search progress use provider item IDs. The web-search work builds on the upstream report and proposed fix.
- Added the durable SQLite example, custom-store checks, and generated docs. Thanks to Mark Zhang for the test import report.
Turnspan 2 (1.6.5+turnspan.2)
- Fixed nested ListView widgets and preserved distinct Chat Completions message IDs across streaming and reload.
- Added a structured feedback example following an upstream persistence question.
Turnspan 1 (1.6.5+turnspan.1)
- Established the Python 3.14 baseline and improved stream cleanup, widget updates, workflow task indexes, and streamed citation handling.