Skip to content

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