Skip to content

Releases

Turnspan 7

Choose a tag to compare

@michaelgiraldo michaelgiraldo released this 21 Nov 18:38
1680fed

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 Hi and then finishes building that same message,
    the saved reply reads Hi once. 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 commentary or
    final_answer. Stores that serialize individual fields should round-trip
    the optional assistant phase to 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

  • Passing CI run

  • Locked versions in the SDK repository were OpenAI Python 3.57.0 and Agents SDK 0.25.0.

  • The consumer smoke ran on Python 3.14.10 with OpenAI Python 3.57.0 and Agents SDK 0.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

Choose a tag to compare

@michaelgiraldo michaelgiraldo released this 21 Nov 06:56
0d916c0

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 receive turn_id. Supply the current ID to
    update_thread and 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 report SUPERSEDED when a new
    request takes ownership.
  • Breaking Python and storage contract. Browser tools publish a
    ClientToolCallItem containing display data. The server registers a
    separate ClientToolInvocation with model data and the turn linkage.
    Custom responders yield ClientToolRequest to register the pair.
    Pass the complete ClientToolTurn to
    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

  • Passing CI run

  • Locked versions in the SDK repository were OpenAI Python 3.56.0 and Agents SDK 0.25.0.

  • The consumer smoke ran on Python 3.14.10 with OpenAI Python 3.57.0 and Agents SDK 0.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

Choose a tag to compare

@michaelgiraldo michaelgiraldo released this 20 Nov 07:16

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 with make demo.
  • Use prepare_user_message to validate or enrich new messages before ChatKit
    writes them. FastAPI integrations can supply a streaming_response factory
    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_checks supplies reusable checks
    for custom thread stores.
  • Test helpers live outside test modules, and pytest uses importlib mode
    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 on turn.input.
    Use on_turn_finished to observe whether the server completed, is waiting
    for input, cancelled, or failed.
  • Implement ThreadStore for thread and item persistence. Configure attachment
    metadata and file operations through AttachmentMetadataStore and
    AttachmentStore where needed.
  • Import thread records from chatkit.models, requests from chatkit.requests,
    and stream events from chatkit.events. Use ThreadItemUpdatedEvent for
    item updates and chatkit.icons.IconName for widget icons.
  • Import history conversion from chatkit.agent_input, widget producers from
    chatkit.widget_stream, and widget JSON models from chatkit.widget_models.
    Install the templates extra and import WidgetTemplate from
    chatkit.templates to render .widget files. Relative template paths use
    the process's working directory.
  • Custom stores filter hidden items before paginating when load_thread_items
    receives include_hidden=False. New item IDs generated by the SDK use a
    full UUID, and new SDK timestamps include a UTC offset.
  • Configure the chatkit logger in your application. Stream errors expose a
    code and retry flag. Entity previews use the browser's onRequestPreview
    callback.
  • Typed Action constructors 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. An AgentContext
    belongs to one response run, and writes after it closes raise
    asyncio.QueueShutDown.
  • Client tool callbacks use AgentContext.request_client_tool with the
    Agents SDK's ToolContext to bind the browser callback to its invocation.
  • Custom HTTP transports parse the request with chatkit.protocol.parse_request,
    pass the typed request to ChatKitServer.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_after operations. Return the retained user message from
    truncate_after after later items disappear from pagination and direct
    reads. The store checks cover both read paths. In a responder, yield the
    event from ChatKitServer.update_thread to persist a display change and
    show it to the client. Use ThreadStore.patch_thread for metadata-only writes.
  • Typed widget builders use .build() to produce a canonical widget tree
    for direct item or update construction. Use WidgetTemplate.build() for
    every template root, including entity previews.
  • Install the agents extra when using chatkit.agents. The fastapi extra
    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

Full changes since Turnspan 2

Turnspan 2

Choose a tag to compare

@michaelgiraldo michaelgiraldo released this 20 Nov 00:11

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 ListView inside a Card now 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/Python suffix was removed.
  • Plain pytest works in a clean checkout with PYTHONPATH unset. 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

Full changes since Turnspan 1

Turnspan 1

Choose a tag to compare

@michaelgiraldo michaelgiraldo released this 19 Nov 22:55

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).

Full changes since OpenAI ChatKit 1.6.5