Add WidgetTemplate and DynamicWidgetRoot/Component types

Author: jiwon-oai

chatkit/server.py

@@ -69,7 +69,7 @@
     is_streaming_req,
 )
 from .version import __version__
-from .widgets import Markdown, Text, WidgetComponent, WidgetComponentBase, WidgetRoot
+from .widgets import WidgetComponent, WidgetComponentBase, WidgetRoot
 
 DEFAULT_PAGE_SIZE = 20
 DEFAULT_ERROR_MESSAGE = "An error occurred when generating a response."
@@ -82,6 +82,11 @@ def diff_widget(
     Compare two WidgetRoots and return a list of deltas.
     """
 
+    def is_streaming_text(component: WidgetComponentBase) -> bool:
+        return getattr(component, "type", None) in {"Markdown", "Text"} and isinstance(
+            getattr(component, "value", None), str
+        )
+
     def full_replace(before: WidgetComponentBase, after: WidgetComponentBase) -> bool:
         if (
             before.type != after.type
@@ -108,10 +113,10 @@ def full_replace_value(before_value: Any, after_value: Any) -> bool:
 
         for field in before.model_fields_set.union(after.model_fields_set):
             if (
-                isinstance(before, (Markdown, Text))
-                and isinstance(after, (Markdown, Text))
+                is_streaming_text(before)
+                and is_streaming_text(after)
                 and field == "value"
-                and after.value.startswith(before.value)
+                and getattr(after, "value", "").startswith(getattr(before, "value", ""))
             ):
                 # Appends to the value prop of Markdown or Text do not trigger a full replace
                 continue
@@ -129,11 +134,11 @@ def full_replace_value(before_value: Any, after_value: Any) -> bool:
 
     def find_all_streaming_text_components(
         component: WidgetComponent | WidgetRoot,
-    ) -> dict[str, Markdown | Text]:
+    ) -> dict[str, WidgetComponentBase]:
         components = {}
 
         def recurse(component: WidgetComponent | WidgetRoot):
-            if isinstance(component, (Markdown, Text)) and component.id:
+            if is_streaming_text(component) and component.id:
                 components[component.id] = component
 
             if hasattr(component, "children"):
@@ -154,16 +159,19 @@ def recurse(component: WidgetComponent | WidgetRoot):
                 f"Node {id} was not present when the widget was initially rendered. All nodes with ID must persist across all widget updates."
             )
 
-        if before_node.value != after_node.value:
-            if not after_node.value.startswith(before_node.value):
+        before_value = str(getattr(before_node, "value", None))
+        after_value = str(getattr(after_node, "value", None))
+
+        if before_value != after_value:
+            if not after_value.startswith(before_value):
                 raise ValueError(
                     f"Node {id} was updated with a new value that is not a prefix of the initial value. All widget updates must be cumulative."
                 )
-            done = not after_node.streaming
+            done = not getattr(after_node, "streaming", False)
             deltas.append(
                 WidgetStreamingTextValueDelta(
                     component_id=id,
-                    delta=after_node.value[len(before_node.value) :],
+                    delta=after_value[len(before_value) :],
                     done=done,
                 )
             )

chatkit/widgets.py

@@ -1,22 +1,30 @@
 from __future__ import annotations
 
+import inspect
+import json
 from datetime import datetime
+from pathlib import Path
 from typing import (
     Annotated,
+    Any,
     Literal,
 )
 
+from jinja2 import Environment, StrictUndefined, Template
 from pydantic import (
     BaseModel,
     ConfigDict,
     Field,
+    TypeAdapter,
     model_serializer,
 )
 from typing_extensions import NotRequired, TypedDict
 
 from .actions import ActionConfig
 from .icons import IconName
 
+env = Environment(undefined=StrictUndefined)
+
 
 class ThemeColor(TypedDict):
     """Color values for light and dark themes."""
@@ -1006,32 +1014,23 @@ class LineSeries(BaseModel):
 """Union of all supported chart series types."""
 
 
-class BasicRoot(WidgetComponentBase):
-    """Layout root capable of nesting components or other roots."""
-
-    type: Literal["Basic"] = Field(default="Basic", frozen=True)  # pyright: ignore
-    children: list[WidgetComponent | WidgetRoot]
-    """Children to render inside this root. Can include widget components or nested roots."""
-    theme: Literal["light", "dark"] | None = None
-    """Force light or dark theme for this subtree."""
-    direction: Literal["row", "col"] | None = None
-    """Flex direction for laying out direct children."""
-    gap: int | str | None = None
-    """Gap between direct children; spacing unit or CSS string."""
-    padding: float | str | Spacing | None = None
-    """Inner padding; spacing unit, CSS string, or padding object."""
-    align: Alignment | None = None
-    """Cross-axis alignment of children."""
-    justify: Justification | None = None
-    """Main-axis distribution of children."""
-
-
 WidgetRoot = Annotated[
     Card | ListView,
     Field(discriminator="type"),
 ]
 
-WidgetComponent = Annotated[
+
+class DynamicWidgetComponent(WidgetComponentBase):
+    """
+    A widget component with a statically defined base shape but dynamically
+    defined additional fields loaded from a widget template or JSON schema.
+    """
+
+    model_config = ConfigDict(extra="allow")
+    children: list["DynamicWidgetComponent"] | None = None
+
+
+StrictWidgetComponent = Annotated[
     Text
     | Title
     | Caption
@@ -1058,8 +1057,103 @@ class BasicRoot(WidgetComponentBase):
     | Transition,
     Field(discriminator="type"),
 ]
+
+
+StrictWidgetRoot = Annotated[
+    Card | ListView,
+    Field(discriminator="type"),
+]
+
+
+class DynamicWidgetRoot(DynamicWidgetComponent):
+    """Dynamic root widget restricted to root types."""
+
+    type: Literal["Card", "ListView"]  # pyright: ignore
+
+
+class BasicRoot(WidgetComponentBase):
+    """Layout root capable of nesting components or other roots."""
+
+    type: Literal["Basic"] = Field(default="Basic", frozen=True)  # pyright: ignore
+    children: list[WidgetComponent | WidgetRoot]
+    """Children to render inside this root. Can include widget components or nested roots."""
+    theme: Literal["light", "dark"] | None = None
+    """Force light or dark theme for this subtree."""
+    direction: Literal["row", "col"] | None = None
+    """Flex direction for laying out direct children."""
+    gap: int | str | None = None
+    """Gap between direct children; spacing unit or CSS string."""
+    padding: float | str | Spacing | None = None
+    """Inner padding; spacing unit, CSS string, or padding object."""
+    align: Alignment | None = None
+    """Cross-axis alignment of children."""
+    justify: Justification | None = None
+    """Main-axis distribution of children."""
+
+
+WidgetComponent = StrictWidgetComponent | DynamicWidgetComponent
 """Union of all renderable widget components."""
 
+WidgetRoot = StrictWidgetRoot | DynamicWidgetRoot
+"""Union of all renderable top-level widgets."""
+
 
 WidgetIcon = IconName
 """Icon names accepted by widgets that render icons."""
+
+
+class WidgetTemplate:
+    """
+    Utility for loading and building widgets from a .widget file.
+
+    Example using .widget file on disc:
+    ```python
+    template = WidgetTemplate.from_file("path/to/my_widget.widget")
+    widget = template.build({"name": "Harry Potter"})
+    ```
+
+    Example using already parsed widget definition:
+    ```python
+    template = WidgetTemplate(definition={"version": "1.0", "name": "...", "template": Template(...), "jsonSchema": {...}})
+    widget = template.build({"name": "Harry Potter"})
+    ```
+    """
+
+    adapter: TypeAdapter[DynamicWidgetRoot] = TypeAdapter(DynamicWidgetRoot)
+
+    def __init__(self, definition: dict[str, Any]):
+        self.version = definition["version"]
+        if self.version != "1.0":
+            raise ValueError(f"Unsupported widget spec version: {self.version}")
+
+        self.name = definition["name"]
+        template = definition["template"]
+        if isinstance(template, Template):
+            self.template = template
+        else:
+            self.template = env.from_string(template)
+        self.data_schema = definition.get("jsonSchema", {})
+
+    @classmethod
+    def from_file(cls, file_path: str) -> "WidgetTemplate":
+        path = Path(file_path)
+        if not path.is_absolute():
+            caller_frame = inspect.stack()[1]
+            caller_path = Path(caller_frame.filename).resolve()
+            path = caller_path.parent / path
+
+        with path.open("r", encoding="utf-8") as file:
+            payload = json.load(file)
+
+        return cls(payload)
+
+    def build(
+        self, data: dict[str, Any] | BaseModel | None = None
+    ) -> DynamicWidgetRoot:
+        if data is None:
+            data = {}
+        if isinstance(data, BaseModel):
+            data = data.model_dump()
+        rendered = self.template.render(**data)
+        widget_dict = json.loads(rendered)
+        return self.adapter.validate_python(widget_dict)

pyproject.toml

@@ -4,7 +4,7 @@ version = "1.3.1"
 description = "A ChatKit backend SDK."
 readme = "README.md"
 requires-python = ">=3.10"
-dependencies = ["pydantic", "uvicorn", "openai", "openai-agents>=0.3.2"]
+dependencies = ["pydantic", "uvicorn", "openai", "openai-agents>=0.3.2", "jinja2"]
 
 [dependency-groups]
 dev = [

tests/assets/widgets/card_no_data.json

@@ -0,0 +1,71 @@
+{
+  "type": "Card",
+  "children": [
+    {
+      "type": "Col",
+      "align": "center",
+      "gap": 4,
+      "padding": 4,
+      "children": [
+        {
+          "type": "Box",
+          "background": "green-400",
+          "radius": "full",
+          "padding": 3,
+          "children": [
+            {
+              "type": "Icon",
+              "name": "check",
+              "size": "3xl",
+              "color": "white"
+            }
+          ]
+        },
+        {
+          "type": "Col",
+          "align": "center",
+          "gap": 1,
+          "children": [
+            {
+              "type": "Title",
+              "value": "Enable notification"
+            },
+            {
+              "type": "Text",
+              "value": "Notify me when this item ships",
+              "color": "secondary"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "type": "Row",
+      "children": [
+        {
+          "type": "Button",
+          "label": "Yes",
+          "block": true,
+          "onClickAction": {
+            "type": "notification.settings",
+            "payload": {
+              "enable": true
+            }
+          }
+        },
+        {
+          "type": "Button",
+          "label": "No",
+          "block": true,
+          "variant": "outline",
+          "onClickAction": {
+            "type": "notification.settings",
+            "payload": {
+              "enable": true
+            }
+          }
+        }
+      ]
+    }
+  ]
+}