Follow up to #1846: replace .get_latest_stream_result() with a more general .get_message_stream()

Author: cpsievert

CHANGELOG.md

@@ -25,7 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * The `ui.Chat()` component also gains the following:
     * The `.on_user_submit()` decorator method now passes the user input to the decorated function. This makes it a bit easier to access the user input. See the new templates (mentioned below) for examples. (#1801)
     * The assistant icon is now configurable via `ui.chat_ui()` (or the `ui.Chat.ui()` method in Shiny Express) or for individual messages in the `.append_message()` and `.append_message_stream()` methods of `ui.Chat()`. (#1853)
-    * A new `get_latest_stream_result()` method was added for an easy way to access the final result of the stream when it completes. (#1846)
+    * A new `get_message_stream()` method was added for an easy way to reactive read the stream's status, result, and also cancel an in progress stream. (#1846)
     * The `.append_message_stream()` method now returns the `reactive.extended_task` instance that it launches. (#1846)
     * The `ui.Chat()` component's `.update_user_input()` method gains `submit` and `focus` options that allow you to submit the input on behalf of the user and to choose whether the input receives focus after the update. (#1851)
 

shiny/ui/_chat.py

@@ -210,9 +210,13 @@ def __init__(
                 reactive.Value(None)
             )
 
-            self._latest_stream: reactive.Value[
-                reactive.ExtendedTask[[], str] | None
-            ] = reactive.Value(None)
+            @reactive.extended_task
+            async def _mock_task() -> str:
+                return ""
+
+            self._latest_stream: reactive.Value[reactive.ExtendedTask[[], str]] = (
+                reactive.Value(_mock_task)
+            )
 
             # TODO: deprecate messages once we start promoting managing LLM message
             # state through other means
@@ -669,32 +673,34 @@ async def _handle_error():
 
         return _stream_task
 
-    def get_latest_stream_result(self) -> str | None:
+    def get_message_stream(self) -> reactive.ExtendedTask[[], str]:
         """
-        Reactively read the latest message stream result.
+        React to changes in the latest message stream.
+
+        Reactively reads for the latest :class:`~shiny.reactive.ExtendedTask` behind the
+        latest message stream.
 
-        This method reads a reactive value containing the result of the latest
-        `.append_message_stream()`. Therefore, this method must be called in a reactive
-        context (e.g., a render function, a :func:`~shiny.reactive.calc`, or a
-        :func:`~shiny.reactive.effect`).
+        From the return value (i.e., the extended task), you can then:
+
+        1. Reactively read for the final `.result()`.
+        2. `.cancel()` the stream.
+        3. Check the `.status()` of the stream.
 
         Returns
         -------
         :
-            The result of the latest stream (a string).
+            An extended task that represents the streaming task. The `.result()` method
+            of the task can be called in a reactive context to get the final state of the
+            stream.
 
-        Raises
-        ------
-        :
-            A silent exception if no stream has completed yet.
+        Note
+        ----
+        If no stream has yet been started when this method is called, then a "mock" task
+        is returned. This mock task behaves much like a stream that hasn't yet completed,
+        except it has a `.status()` of "initial" instead of "running", and `.cancel()`
+        is a no-op.
         """
-        stream = self._latest_stream()
-        if stream is None:
-            from .. import req
-
-            req(False)
-        else:
-            return stream.result()
+        return self._latest_stream()
 
     async def _append_message_stream(
         self,