feat(pkg-py): Improvements for statically rendered messages (#131)

* fix: ChatMessage() can now be constructed outside a Shiny session context

* feat: Chat.chat_ui() can now render any type that message_contents() supports

* Update changelog

* Always return dependencies

* html_deps needs to be a dictionary

* Simplify

* Avoid deprecated API in tests

* Provider more type hints

* Various fixes

* Minimize diff; add missing docstrings

* Fix lints

Author: cpsievert

pkg-py/CHANGELOG.md

@@ -7,7 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [UNRELEASED]
 
+### New features
 
+* `ChatMessage()` can now be constructed outside of a Shiny session. (#131)
+* `Chat.chat_ui(messages=...)` now supports any type also supported by `message_content()`. (#131)
 
 ## [0.2.0] - 2025-09-10
 

pkg-py/src/shinychat/_chat.py

@@ -22,7 +22,7 @@
 
 from htmltools import (
     HTML,
-    RenderedHTML,
+    HTMLDependency,
     Tag,
     TagAttrValue,
     TagChild,
@@ -595,6 +595,7 @@ async def append_message(
             * A dictionary with `content` and `role` keys. The `content` key can contain
               content as described above, and the `role` key can be "assistant" or
               "user".
+            * More generally, any type registered with :func:`shinychat.message_content`.
 
             **NOTE:** content may include specially formatted **input suggestion** links
             (see note below).
@@ -829,6 +830,7 @@ async def append_message_stream(
             * A dictionary with `content` and `role` keys. The `content` key can contain
               content as described above, and the `role` key can be "assistant" or
               "user".
+            * More generally, any type registered with :func:`shinychat.message_content_chunk`.
 
             **NOTE:** content may include specially formatted **input suggestion** links
             (see note below).
@@ -1588,7 +1590,9 @@ class ChatExpress(Chat):
     def ui(
         self,
         *,
-        messages: Optional[Sequence[TagChild | ChatMessageDict]] = None,
+        messages: Optional[
+            Iterable[str | TagChild | ChatMessageDict | ChatMessage | Any]
+        ] = None,
         placeholder: str = "Enter a message...",
         width: CssUnit = "min(680px, 100%)",
         height: CssUnit = "auto",
@@ -1690,12 +1694,14 @@ def enable_bookmarking(
 def chat_ui(
     id: str,
     *,
-    messages: Optional[Sequence[TagChild | ChatMessageDict]] = None,
+    messages: Optional[
+        Iterable[str | TagChild | ChatMessageDict | ChatMessage | Any]
+    ] = None,
     placeholder: str = "Enter a message...",
     width: CssUnit = "min(680px, 100%)",
     height: CssUnit = "auto",
     fill: bool = True,
-    icon_assistant: HTML | Tag | TagList | None = None,
+    icon_assistant: Optional[HTML | Tag | TagList] = None,
     **kwargs: TagAttrValue,
 ) -> Tag:
     """
@@ -1722,6 +1728,7 @@ def chat_ui(
               interpreted as markdown as long as they're not inside HTML.
         * A dictionary with `content` and `role` keys. The `content` key can contain a
           content as described above, and the `role` key can be "assistant" or "user".
+        * More generally, any type registered with :func:`shinychat.message_content`.
 
         **NOTE:** content may include specially formatted **input suggestion** links
         (see :method:`~shiny.ui.Chat.append_message` for more info).
@@ -1755,34 +1762,14 @@ def chat_ui(
     if messages is None:
         messages = []
     for x in messages:
-        role = "assistant"
-        content: TagChild = None
-        if not isinstance(x, dict):
-            content = x
-        else:
-            if "content" not in x:
-                raise ValueError(
-                    "Each message dictionary must have a 'content' key."
-                )
-
-            content = x["content"]
-            if "role" in x:
-                role = x["role"]
-
-        # `content` is most likely a string, so avoid overhead in that case
-        # (it's also important that we *don't escape HTML* here).
-        if isinstance(content, str):
-            ui: RenderedHTML = {"html": content, "dependencies": []}
-        else:
-            ui = TagList(content).render()
-
+        msg = message_content(x)
         message_tags.append(
             Tag(
                 "shiny-chat-message",
-                ui["dependencies"],
-                content=ui["html"],
+                *[HTMLDependency(**d) for d in msg.html_deps],
+                content=msg.content,
                 icon=icon_attr,
-                data_role=role,
+                data_role=msg.role,
             )
         )
 

pkg-py/src/shinychat/_chat_types.py

@@ -4,7 +4,7 @@
 from typing import Literal, TypedDict
 
 from htmltools import HTML, Tag, TagChild, Tagifiable, TagList
-from shiny.session import require_active_session
+from shiny.session import get_current_session
 
 from ._typing_extensions import NotRequired
 
@@ -32,10 +32,14 @@ def __init__(
         # markdown), so only process it if it's not a string.
         deps = []
         if not isinstance(content, str):
-            session = require_active_session(None)
-            res = session._process_ui(content)
+            session = get_current_session()
+            if session and not session.is_stub_session():
+                res = session._process_ui(content)
+                deps = res["deps"]
+            else:
+                res = TagList(content).render()
+                deps = [d.as_dict() for d in res["dependencies"]]
             content = res["html"]
-            deps = res["deps"]
 
         if is_html:
             # Code blocks with `{=html}` infostrings are rendered as-is by a

pkg-py/tests/playwright/chat/basic/app.py

@@ -5,15 +5,10 @@
 ui.page_opts(title="Hello Chat")
 
 # Create a chat instance, with an initial message
-chat = Chat(
-    id="chat",
-    messages=[
-        {"content": "Hello! How can I help you today?", "role": "assistant"},
-    ],
-)
+chat = Chat(id="chat")
 
 # Display the chat
-chat.ui()
+chat.ui(messages=["Hello! How can I help you today?"])
 
 
 # Define a callback to run when the user submits a message

pkg-py/tests/playwright/chat/basic/test_chat_basic.py

@@ -42,7 +42,6 @@ def test_validate_chat_basic(page: Page, local_app: ShinyAppProc) -> None:
     message_state = controller.OutputCode(page, "message_state")
     message_state_expected = tuple(
         [
-            {"content": initial_message, "role": "assistant"},
             {"content": f"\n{user_message}", "role": "user"},
             {"content": f"You said: \n{user_message}", "role": "assistant"},
             {"content": f"{user_message2}", "role": "user"},

pkg-py/tests/playwright/chat/icon/app.py

@@ -11,19 +11,14 @@
 
 with ui.layout_columns():
     # Default Bot ---------------------------------------------------------------------
-    chat_default = Chat(
-        id="chat_default",
-        messages=[
-            {
-                "content": "Hello! I'm Default Bot. How can I help you today?",
-                "role": "assistant",
-            },
-        ],
-    )
+    chat_default = Chat(id="chat_default")
 
     with ui.div():
         ui.h2("Default Bot")
-        chat_default.ui(icon_assistant=None)
+        chat_default.ui(
+            messages=["Hello! I'm Default Bot. How can I help you today?"],
+            icon_assistant=None,
+        )
 
     @chat_default.on_user_submit
     async def handle_user_input_default(user_input: str):

pkg-py/tests/playwright/chat/input-suggestion/app.py

@@ -12,9 +12,9 @@
 And <span id="fifth" data-suggestion="another suggestion" data-suggestion-submit="true">this suggestion will also auto-submit</span>.</p>
 """
 
-chat = Chat("chat", messages=[suggestion2])
+chat = Chat("chat")
 
-chat.ui(messages=[suggestions1])
+chat.ui(messages=[suggestions1, suggestion2])
 
 
 @chat.on_user_submit

pkg-py/tests/playwright/chat/shiny_input/app.py

@@ -19,11 +19,11 @@
     ),
 )
 
-chat = Chat(
-    id="chat",
+chat = Chat(id="chat")
+chat.ui(
     messages=[welcome],
+    class_="mb-5",
 )
-chat.ui(class_="mb-5")
 
 
 @reactive.effect