Skip to content

widget stream

Widget state differences and asynchronous widget streaming.

diff_widget

diff_widget(before: WidgetRootInput, after: WidgetRootInput) -> list[WidgetStreamingTextValueDelta | WidgetRootUpdated]

Emit unambiguous text appends, or replace the widget for other changes.

Source code in chatkit/widget_stream.py
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
def diff_widget(
    before: widgets.WidgetRootInput, after: widgets.WidgetRootInput
) -> list[events.WidgetStreamingTextValueDelta | events.WidgetRootUpdated]:
    """Emit unambiguous text appends, or replace the widget for other changes."""
    before_payload = _widget_state(before).model_dump(mode="json")
    after_widget = _widget_state(after)
    after_payload = after_widget.model_dump(mode="json")

    def index_components(root: dict[str, Any]) -> dict[str, list[dict[str, Any]]]:
        by_id: dict[str, list[dict[str, Any]]] = {}

        def visit(node: dict[str, Any]) -> None:
            if component_id := node.get("id"):
                by_id.setdefault(component_id, []).append(node)
            children = node.get("children")
            if isinstance(children, dict):
                visit(children)
            elif isinstance(children, list):
                for child in children:
                    visit(child)

        visit(root)
        return by_id

    before_index = index_components(before_payload)
    deltas: list[events.WidgetStreamingTextValueDelta | events.WidgetRootUpdated] = []
    for component_id, new_nodes in index_components(after_payload).items():
        old_nodes = before_index.get(component_id, [])
        if len(old_nodes) != 1 or len(new_nodes) != 1:
            continue
        old_node, new_node = old_nodes[0], new_nodes[0]
        old_value, new_value = old_node.get("value"), new_node.get("value")
        if (
            old_node["type"] in {"Text", "Markdown"}
            and old_node["type"] == new_node["type"]
            and isinstance(old_value, str)
            and isinstance(new_value, str)
            and new_value != old_value
            and new_value.startswith(old_value)
        ):
            old_node["value"] = new_value
            deltas.append(
                events.WidgetStreamingTextValueDelta(
                    component_id=component_id,
                    delta=new_value[len(old_value) :],
                    done=not new_node.get("streaming", False),
                )
            )

    # Once appends are applied, compare the remaining JSON, including extensions
    # and explicit nulls. JSON equality distinguishes boolean and numeric props.
    if json.dumps(before_payload, sort_keys=True) != json.dumps(
        after_payload, sort_keys=True
    ):
        return [events.WidgetRootUpdated(widget=after_widget)]
    return deltas

stream_widget async

stream_widget(thread: ThreadMetadata, widget: WidgetRootInput | AsyncGenerator[WidgetRootInput], copy_text: str | None = None, generate_id: Callable[[StoreItemType], str] = default_generate_id) -> AsyncGenerator[ThreadStreamEvent]

Stream a widget root or successive root states.

An empty producer emits no events. Closing the returned stream also closes its producer.

Source code in chatkit/widget_stream.py
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
async def stream_widget(
    thread: models.ThreadMetadata,
    widget: widgets.WidgetRootInput | AsyncGenerator[widgets.WidgetRootInput],
    copy_text: str | None = None,
    generate_id: Callable[[store.StoreItemType], str] = store.default_generate_id,
) -> AsyncGenerator[events.ThreadStreamEvent]:
    """Stream a widget root or successive root states.

    An empty producer emits no events. Closing the returned stream also closes
    its producer.
    """

    if not isinstance(widget, AsyncGenerator):
        yield events.ThreadItemDoneEvent(
            item=models.WidgetItem(
                id=generate_id("message"),
                thread_id=thread.id,
                created_at=datetime.now(UTC),
                widget=_widget_state(widget),
                copy_text=copy_text,
            ),
        )
        return

    async with _closing_stream(widget) as states:
        try:
            last_state = _widget_state(await anext(states)).model_copy(deep=True)
        except StopAsyncIteration:
            return

        item = models.WidgetItem(
            id=generate_id("message"),
            created_at=datetime.now(UTC),
            widget=last_state,
            copy_text=copy_text,
            thread_id=thread.id,
        )
        yield events.ThreadItemAddedEvent(item=item)

        async for state in states:
            new_state = _widget_state(state).model_copy(deep=True)
            for update in diff_widget(last_state, new_state):
                yield events.ThreadItemUpdatedEvent(
                    item_id=item.id,
                    update=update,
                )
            last_state = new_state

    yield events.ThreadItemDoneEvent(
        item=item.model_copy(update={"widget": last_state}),
    )