update api ref pages; fix links

jiwon-oai · jiwon-oai · commit cce4d65ff5e2 · 2025-12-07T22:52:56.000-08:00
diff --git a/chatkit/widgets.py b/chatkit/widgets.py
@@ -1171,6 +1171,7 @@ def from_file(cls, file_path: str) -> WidgetTemplate:
     def build(
         self, data: dict[str, Any] | BaseModel | None = None
     ) -> DynamicWidgetRoot:
+        """Build a widget from the template and data."""
         rendered = self.template.render(**self._normalize_data(data))
         widget_dict = json.loads(rendered)
         return DynamicWidgetRoot.model_validate(widget_dict)
diff --git a/docs/api/chatkit/index.md b/docs/api/chatkit/index.md
@@ -0,0 +1,10 @@
+# Chatkit Python API Reference
+
+What you'll find here:
+
+- **Core server API**: [`chatkit.server`](server.md) &ndash; `ChatKitServer` and related helpers for receiving messages, streaming responses, and wiring up tools and widgets.
+- **Store integration**: [`chatkit.store`](store.md) &ndash; interfaces and utilities for persisting threads, items, and metadata.
+- **Agents integration helpers**: [`chatkit.agents`](agents.md) &ndash; helpers and utilities for using ChatKit together with the Agents SDK.
+- **Data models and types**: [`chatkit.types`](types.md) &ndash; Pydantic models for threads, items, events, and other shared types.
+- **Errors**: [`chatkit.errors`](errors.md) &ndash; structured error types your ChatKit integration can raise so ChatKit can emit consistent `ErrorEvent`s to the client.
+- **Widgets**: [`chatkit.widgets`](widgets.md) &ndash; models and helpers such as `WidgetTemplate`, `DynamicWidgetRoot`, and `BasicRoot` for building rich UI responses.
diff --git a/docs/concepts/entities.md b/docs/concepts/entities.md
@@ -16,7 +16,7 @@ Entities can be used as cited sources in assistant responses.
 
 **References:**
 
-- The [EntitySource](../../api/chatkit/types/#chatkit.types.EntitySource) Pydantic model definition
+- The [EntitySource](../api/chatkit/types.md#chatkit.types.EntitySource) Pydantic model definition
 - [Add annotations in assistant messages](../guides/add-annotations.md#annotating-with-custom-entities).
 
 ## Entity tags as @-mentions in user messages
@@ -26,5 +26,5 @@ Users can tag your entities in the composer using @-mentions.
 **References**:
 
 - The [Entity](https://openai.github.io/chatkit-js/api/openai/chatkit-react/type-aliases/entity/) TypeScript type definition
-- The [UserMessageTagContent](../../api/chatkit/types/#chatkit.types.UserMessageTagContent) Pydantic model definition
+- The [UserMessageTagContent](../api/chatkit/types.md#chatkit.types.UserMessageTagContent) Pydantic model definition
 - [Accept rich user input](../guides/accept-rich-user-input.md#-mentions-tag-entities-in-user-messages).
diff --git a/docs/concepts/thread-stream-events.md b/docs/concepts/thread-stream-events.md
@@ -1,45 +1,45 @@
 # Thread stream events
 
-[`ThreadStreamEvent`](../../api/chatkit/types/#chatkit.types.ThreadStreamEvent)s are the Server-Sent Event (SSE) payloads streamed by ChatKitServer while responding to a user message or action. They keep the client UI in sync with server-side processing and drive persistence in your store.
+[`ThreadStreamEvent`](../api/chatkit/types.md#chatkit.types.ThreadStreamEvent)s are the Server-Sent Event (SSE) payloads streamed by ChatKitServer while responding to a user message or action. They keep the client UI in sync with server-side processing and drive persistence in your store.
 
 ## Thread metadata updates
 
 ChatKitServer emits these after it creates a thread or notices metadata changes (title, status, etc.) so the UI stays in sync.
 
-- [`ThreadCreatedEvent`](../../api/chatkit/types/#chatkit.types.ThreadCreatedEvent): introduce a new thread
-- [`ThreadUpdatedEvent`](../../api/chatkit/types/#chatkit.types.ThreadUpdatedEvent): update the current thread metadata such as title or status
+- [`ThreadCreatedEvent`](../api/chatkit/types.md#chatkit.types.ThreadCreatedEvent): introduce a new thread
+- [`ThreadUpdatedEvent`](../api/chatkit/types.md#chatkit.types.ThreadUpdatedEvent): update the current thread metadata such as title or status
 
 ## Thread item events
 
 Thread item events drive the conversation state. ChatKitServer processes these events to persist conversation state before streaming them back to the client.
 
-- [`ThreadItemAddedEvent`](../../api/chatkit/types/#chatkit.types.ThreadItemAddedEvent): introduce a new item (message, tool call, workflow, widget, etc).
-- [`ThreadItemUpdatedEvent`](../../api/chatkit/types/#chatkit.types.ThreadItemUpdatedEvent): mutate a pending item (e.g., stream text deltas, workflow task updates).
-- [`ThreadItemDoneEvent`](../../api/chatkit/types/#chatkit.types.ThreadItemDoneEvent): mark an item complete and persist it.
-- [`ThreadItemRemovedEvent`](../../api/chatkit/types/#chatkit.types.ThreadItemRemovedEvent): delete an item by id.
-- [`ThreadItemReplacedEvent`](../../api/chatkit/types/#chatkit.types.ThreadItemReplacedEvent): swap an item in place.
+- [`ThreadItemAddedEvent`](../api/chatkit/types.md#chatkit.types.ThreadItemAddedEvent): introduce a new item (message, tool call, workflow, widget, etc).
+- [`ThreadItemUpdatedEvent`](../api/chatkit/types.md#chatkit.types.ThreadItemUpdatedEvent): mutate a pending item (e.g., stream text deltas, workflow task updates).
+- [`ThreadItemDoneEvent`](../api/chatkit/types.md#chatkit.types.ThreadItemDoneEvent): mark an item complete and persist it.
+- [`ThreadItemRemovedEvent`](../api/chatkit/types.md#chatkit.types.ThreadItemRemovedEvent): delete an item by id.
+- [`ThreadItemReplacedEvent`](../api/chatkit/types.md#chatkit.types.ThreadItemReplacedEvent): swap an item in place.
 
 Note: `ThreadItemAddedEvent` does not persist the item. `ChatKitServer` saves on `ThreadItemDoneEvent`/`ThreadItemReplacedEvent`, tracks pending items in between, and handles store writes for all `ThreadItem*Event`s.
 
 ## Errors
 
-Stream [`ErrorEvent`](../../api/chatkit/types/#chatkit.types.ErrorEvent)s for user-facing errors in the chat UI. You can configure a custom message and whether a retry button is shown to the user.
+Stream [`ErrorEvent`](../api/chatkit/types.md#chatkit.types.ErrorEvent)s for user-facing errors in the chat UI. You can configure a custom message and whether a retry button is shown to the user.
 
 ## Progress updates
 
-Stream [`ProgressUpdateEvent`](../../api/chatkit/types/#chatkit.types.ProgressUpdateEvent)s to show the user transient status while work is in flight.
+Stream [`ProgressUpdateEvent`](../api/chatkit/types.md#chatkit.types.ProgressUpdateEvent)s to show the user transient status while work is in flight.
 
 See [Show progress while tools run](../guides/update-client-during-response.md#show-progress-while-tools-run) for more info.
 
 ## Client effects
 
-Use [`ClientEffectEvent`](../../api/chatkit/types/#chatkit.types.ClientEffectEvent) to trigger fire-and-forget behavior on the client such as opening a dialog or pushing updates.
+Use [`ClientEffectEvent`](../api/chatkit/types.md#chatkit.types.ClientEffectEvent) to trigger fire-and-forget behavior on the client such as opening a dialog or pushing updates.
 
 See [Trigger client-side effects without blocking](../guides/update-client-during-response.md#trigger-client-side-effects-without-blocking) for more info.
 
 ## Stream options
 
-[`StreamOptionsEvent`](../../api/chatkit/types/#chatkit.types.StreamOptionsEvent) configures runtime stream behavior (for example, allowing user cancellation). `ChatKitServer` emits one at the start of every stream using `get_stream_options`; override that method to change defaults such as `allow_cancel`.
+[`StreamOptionsEvent`](../api/chatkit/types.md#chatkit.types.StreamOptionsEvent) configures runtime stream behavior (for example, allowing user cancellation). `ChatKitServer` emits one at the start of every stream using `get_stream_options`; override that method to change defaults such as `allow_cancel`.
 
 
 ## Related guides
diff --git a/docs/concepts/threads.md b/docs/concepts/threads.md
@@ -41,7 +41,7 @@ Thread items serve two primary purposes in ChatKit:
 
 ### Model input
 
-Your server's [`respond`](../../api/chatkit/server/#chatkit.server.ChatKitServer.respond) logic reads thread items to construct input for the model input. This ensures the model sees the full conversational context both during an active response and when a user resumes a past thread. 
+Your server's [`respond`](../api/chatkit/server.md#chatkit.server.ChatKitServer.respond) logic reads thread items to construct input for the model input. This ensures the model sees the full conversational context both during an active response and when a user resumes a past thread. 
 
 See [Respond to a user message](../guides/respond-to-user-message.md) for a full walkthrough.
 
@@ -53,7 +53,7 @@ On the client, ChatKit.js renders items incrementally as they stream in for the
 
 ### User messages
 
-[`UserMessageItem`](../../api/chatkit/types/#chatkit.types.UserMessageItem)s represent end-user input. They may include:
+[`UserMessageItem`](../api/chatkit/types.md#chatkit.types.UserMessageItem)s represent end-user input. They may include:
 
 - Plain text entered by the user
 - Optional `quoted_text` for reply-style UIs
@@ -65,7 +65,7 @@ User text is not Markdown-rendered, but it may contain [@-mentions](../guides/ac
 
 ### Assistant messages
 
-[`AssistantMessageItem`](../../api/chatkit/types/#chatkit.types.AssistantMessageItem)s represent assistant output. Their content can include:
+[`AssistantMessageItem`](../api/chatkit/types.md#chatkit.types.AssistantMessageItem)s represent assistant output. Their content can include:
 
 - Markdown-rendered text
 - Tool call outputs
@@ -92,9 +92,9 @@ Hidden context items are included in model input but are not rendered in the cha
 
 Typical use cases include recording widget actions, selection state, or system signals.
 
-- **[`HiddenContextItem`](../../api/chatkit/types/#chatkit.types.HiddenContextItem)**: Integration-defined hidden context. You control its schema and how it is converted for the model.
+- **[`HiddenContextItem`](../api/chatkit/types.md#chatkit.types.HiddenContextItem)**: Integration-defined hidden context. You control its schema and how it is converted for the model.
 
-- **[`SDKHiddenContextItem`](../../api/chatkit/types/#chatkit.types.SDKHiddenContextItem)**: Hidden context inserted by the ChatKit Python SDK for its own internal operations. Most applications do not need to modify this unless overriding conversion behavior.
+- **[`SDKHiddenContextItem`](../api/chatkit/types.md#chatkit.types.SDKHiddenContextItem)**: Hidden context inserted by the ChatKit Python SDK for its own internal operations. Most applications do not need to modify this unless overriding conversion behavior.
 
 ## Thread item actions
 
@@ -104,7 +104,7 @@ Actions are configured client-side using the [threadItemActions option](https://
 
 ## Converting items to model input
 
-[`ThreadItemConverter`](../../api/chatkit/agents/#chatkit.agents.ThreadItemConverter) translates stored thread items into model-ready input items. The default converter understands common ChatKit item types such as messages, widgets, workflows, and tasks.
+[`ThreadItemConverter`](../api/chatkit/agents.md#chatkit.agents.ThreadItemConverter) translates stored thread items into model-ready input items. The default converter understands common ChatKit item types such as messages, widgets, workflows, and tasks.
 
 You can override the converter when you need custom behavior. For example:
 
diff --git a/docs/concepts/widgets.md b/docs/concepts/widgets.md
@@ -10,11 +10,11 @@ Here&rsquo;s how a widget is represented from design time through runtime streaming.
 | --- | --- |
 | Working definition | [Widget UI language](#widget-ui-language) plus a schema (Zod/JSON) and example data you author in <https://widgets.chatkit.studio>. |
 | Published definition | The exported [`.widget` file](#widget-files) bundling the layout, schema, and sample data. |
-| Server runtime (definition only) | [`WidgetTemplate`](../../api/chatkit/widgets/#chatkit.widgets.WidgetTemplate) instance loaded from the `.widget` file. |
-| Server runtime (hydrated) | [`DynamicWidgetRoot`](../../api/chatkit/widgets/#chatkit.widgets.DynamicWidgetRoot) or [`BasicRoot`](../../api/chatkit/widgets/#chatkit.widgets.BasicRoot) Pydantic model instance built from the template and real data. |
-| Streamed to the client | The hydrated root serialized to JSON and included inside a [`WidgetItem`](../../api/chatkit/types/#chatkit.types.WidgetItem) streamed by `ChatKitServer`. |
+| Server runtime (definition only) | [`WidgetTemplate`](../api/chatkit/widgets.md#chatkit.widgets.WidgetTemplate) instance loaded from the `.widget` file. |
+| Server runtime (hydrated) | [`DynamicWidgetRoot`](../api/chatkit/widgets.md#chatkit.widgets.DynamicWidgetRoot) or [`BasicRoot`](../api/chatkit/widgets.md#chatkit.widgets.BasicRoot) Pydantic model instance built from the template and real data. |
+| Streamed to the client | The hydrated root serialized to JSON and included inside a [`WidgetItem`](../api/chatkit/types.md#chatkit.types.WidgetItem) streamed by `ChatKitServer`. |
 | Rendered by the client | ChatKit.js deserializes the JSON into typed widget objects (for example, [`Card`](https://openai.github.io/chatkit-js/api/openai/chatkit-react/namespaces/widgets/type-aliases/card/) or [`ListView`](https://openai.github.io/chatkit-js/api/openai/chatkit/namespaces/widgets/type-aliases/listview/)) and renders them; entity previews use [`BasicRoot`](https://openai.github.io/chatkit-js/api/openai/chatkit-react/namespaces/widgets/type-aliases/basicroot/) returned from [`entities.onRequestPreview`](#entity-previews). |
-| Sent as model input | A Responses API `Message` produced from a [`WidgetItem`](../../api/chatkit/types/#chatkit.types.WidgetItem) via [`ThreadItemConverter.widget_to_input`](../../api/chatkit/agents/#chatkit.agents.ThreadItemConverter.widget_to_input). |
+| Sent as model input | A Responses API `Message` produced from a [`WidgetItem`](../api/chatkit/types.md#chatkit.types.WidgetItem) via [`ThreadItemConverter.widget_to_input`](../api/chatkit/agents.md#chatkit.agents.ThreadItemConverter.widget_to_input). |
 
 
 ## Widget UI language
@@ -35,7 +35,7 @@ Exported `.widget` files are JSON blobs that include the widget template, the ex
 
 ## WidgetItem
 
-[`WidgetItem`](../../api/chatkit/types/#chatkit.types.WidgetItem) represents a widget rendered as a [thread item](threads.md#what-are-thread-items) in the chat UI. In addition to a reference to the widget instance, it contains a `copy_text` field that represents the text value copied to the clipboard when the user clicks the copy button below the response.
+[`WidgetItem`](../api/chatkit/types.md#chatkit.types.WidgetItem) represents a widget rendered as a [thread item](threads.md#what-are-thread-items) in the chat UI. In addition to a reference to the widget instance, it contains a `copy_text` field that represents the text value copied to the clipboard when the user clicks the copy button below the response.
 
 ## Entity previews
 
diff --git a/docs/gen_ref_pages.py b/docs/gen_ref_pages.py
@@ -26,7 +26,7 @@
 for path in SRC_ROOT.rglob("*.py"):
     if path.name.startswith("_"):
         continue
-    if path.name in {"version.py", "logger.py"}:
+    if path.name in {"version.py", "logger.py", "actions.py"}:
         continue
 
     module_path = path.with_suffix("").relative_to(SRC_ROOT)
@@ -40,4 +40,19 @@
     mkdocs_gen_files.set_edit_path(doc_path, path)
     with mkdocs_gen_files.open(doc_path, "w") as f:
         f.write(f"# {path.stem}\n\n")
-        f.write(f"::: {identifier}\n")
+
+        # For the widgets module, keep the module-level directive but only include
+        # a curated set of public members so we preserve nice headings.
+        if identifier == "chatkit.widgets":
+            f.write(f"::: {identifier}\n")
+            f.write("    options:\n")
+            f.write("      members:\n")
+            for symbol in (
+                "WidgetTemplate",
+                "DynamicWidgetRoot",
+                "BasicRoot",
+                "DynamicWidgetComponent",
+            ):
+                f.write(f"        - {symbol}\n")
+        else:
+            f.write(f"::: {identifier}\n")
diff --git a/docs/guides/respond-to-user-message.md b/docs/guides/respond-to-user-message.md
@@ -269,8 +269,12 @@ async def load_document(ctx: RunContextWrapper[AgentContext], document_id: str):
 
 - [Let users browse past threads](browse-past-threads.md)
 - [Accept rich user input](accept-rich-user-input.md)
+- [Let users pick tools and models](let-users-pick-tools-and-models.md)
+- [Pass extra app context to your model](pass-extra-app-context-to-your-model.md)
 - [Update the client during a response](update-client-during-response.md)
 - [Build interactive responses with widgets](build-interactive-responses-with-widgets.md)
-- [Handle feedback](handle-feedback.md)
-- [Allow @-mentions in user messages](accept-rich-user-input.md#-mentions-tag-entities-in-user-messages)
 - [Add annotations in assistant messages](add-annotations.md)
+- [Keep your app in sync with ChatKit](keep-your-app-in-sync-with-chatkit.md)
+- [Let your app draft and send messages](let-your-app-draft-and-send-messages.md)
+- [Handle feedback](handle-feedback.md)
+- [Prepare your app for production](prepare-your-app-for-production.md)
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -62,7 +62,6 @@ nav:
   - API Reference:
       - Overview: api/chatkit/index.md
       - Modules:
-          - actions: api/chatkit/actions.md
           - agents: api/chatkit/agents.md
           - errors: api/chatkit/errors.md
           - server: api/chatkit/server.md

-Original file line number
+Diff line change
@@ @@ -0,0 +1,10 @@ @@
 +# Chatkit Python API Reference
++
 +What you'll find here:
++
 +- **Core server API**: [`chatkit.server`](server.md) – `ChatKitServer` and related helpers for receiving messages, streaming responses, and wiring up tools and widgets.
 +- **Store integration**: [`chatkit.store`](store.md) – interfaces and utilities for persisting threads, items, and metadata.
 +- **Agents integration helpers**: [`chatkit.agents`](agents.md) – helpers and utilities for using ChatKit together with the Agents SDK.
 +- **Data models and types**: [`chatkit.types`](types.md) – Pydantic models for threads, items, events, and other shared types.
 +- **Errors**: [`chatkit.errors`](errors.md) – structured error types your ChatKit integration can raise so ChatKit can emit consistent `ErrorEvent`s to the client.
 +- **Widgets**: [`chatkit.widgets`](widgets.md) – models and helpers such as `WidgetTemplate`, `DynamicWidgetRoot`, and `BasicRoot` for building rich UI responses.