express.ui.Chat
express.ui.Chat(self, id, *, messages=(), on_error='auto', tokenizer=None)
Create a chat interface.
A UI component for building conversational interfaces. With it, end users can submit messages, which will cause a .on_user_submit()
callback to run. In that callback, a response can be generated based on the chat's .messages()
, and appended to the chat using .append_message()
or .append_message_stream()
.
Here's a rough outline for how to implement a Chat
:
from shiny.express import ui
# Create and display chat instance
= ui.Chat(id="my_chat")
chat
chat.ui()
# Define a callback to run when the user submits a message
@chat.on_user_submit
async def _():
# Get messages currently in the chat
= chat.messages()
messages # Create a response message stream
= await my_model.generate_response(messages, stream=True)
response # Append the response into the chat
await chat.append_message_stream(response)
In the outline above, my_model.generate_response()
is a placeholder for the function that generates a response based on the chat's messages. This function will look different depending on the model you're using, but it will generally involve passing the messages to the model and getting a response back. Also, you'll typically have a choice to stream=True
the response generation, and in that case, you'll use .append_message_stream()
instead of .append_message()
to append the response to the chat. Streaming is preferrable when available since it allows for more responsive and scalable chat interfaces.
Parameters
id: str
-
A unique identifier for the chat session. In Shiny Core, make sure this id matches a corresponding
chat_ui
call in the UI. messages: Sequence[Any] = ()
-
A sequence of messages to display in the chat. Each message can be a dictionary with a
content
androle
key. Thecontent
key should contain the message text, and therole
key can be âassistantâ, âuserâ, or âsystemâ. Note that system messages are not actually displayed in the chat, but will still be stored in the chatâs.messages()
. on_error: Literal[âautoâ, âactualâ, âsanitizeâ, âunhandledâ] = âautoâ
-
How to handle errors that occur in response to user input. When
"unhandled"
, the app will stop running when an error occurs. Otherwise, a notification is displayed to the user and the app continues to run."auto"
: Sanitize the error message if the app is set to sanitize errors, otherwise display the actual error message."actual"
: Display the actual error message to the user."sanitize"
: Sanitize the error message before displaying it to the user."unhandled"
: Do not display any error message to the user.
tokenizer:
TokenEncoding
| None = None-
The tokenizer to use for calculating token counts, which is required to impose
token_limits
in.messages()
. If not provided, a default generic tokenizer is attempted to be loaded from the tokenizers library. A specific tokenizer may also be provided by following theTokenEncoding
(tiktoken or tozenizers) protocol (e.g.,tiktoken.encoding_for_model("gpt-4o")
).
Examples
#| standalone: true
#| components: [editor, viewer]
#| layout: vertical
#| viewerHeight: 400
## file: app.py
from shiny.express import ui
# Set some Shiny page options
ui.page_opts(
title="Hello Shiny Chat",
fillable=True,
fillable_mobile=True,
)
# Create a welcome message
welcome = ui.markdown(
"""
Hi! This is a simple Shiny `Chat` UI. Enter a message below and I will
simply repeat it back to you. For more examples, see this
[folder of examples](https://github.com/posit-dev/py-shiny/tree/main/examples/chat).
"""
)
# Create a chat instance
chat = ui.Chat(
id="chat",
messages=[welcome],
)
# Display it
chat.ui()
# Define a callback to run when the user submits a message
@chat.on_user_submit
async def _():
# Get the user's input
user = chat.user_input()
# Append a response to the chat
await chat.append_message(f"You said: {user}")
Methods
Name | Description |
---|---|
append_message | Append a message to the chat. |
append_message_stream | Append a message as a stream of message chunks. |
clear_messages | Clear all chat messages. |
destroy | Destroy the chat instance. |
messages | Reactively read chat messages |
on_user_submit | Define a function to invoke when user input is submitted. |
set_user_message | Deprecated. Use update_user_input(value=value) instead. |
transform_assistant_response | Transform assistant responses. |
transform_user_input | Transform user input. |
ui | Place a chat component in the UI. |
update_user_input | Update the user input. |
user_input | Reactively read the userâs message. |
append_message
express.ui.Chat.append_message(message)
Append a message to the chat.
Parameters
message: Any
-
The message to append. A variety of message formats are supported including a string, a dictionary with
content
androle
keys, or a relevant chat completion object from platforms like OpenAI, Anthropic, Ollama, and others.
Note
Use .append_message_stream()
instead of this method when stream=True
(or similar) is specified in modelâs completion method.
append_message_stream
express.ui.Chat.append_message_stream(message)
Append a message as a stream of message chunks.
Parameters
message: Iterable[Any] | AsyncIterable[Any]
-
An iterable or async iterable of message chunks to append. A variety of message chunk formats are supported, including a string, a dictionary with
content
androle
keys, or a relevant chat completion object from platforms like OpenAI, Anthropic, Ollama, and others.
Note
Use this method (over .append_message()
) when stream=True
(or similar) is specified in modelâs completion method.
clear_messages
express.ui.Chat.clear_messages()
Clear all chat messages.
destroy
express.ui.Chat.destroy()
Destroy the chat instance.
messages
express.ui.Chat.messages(format=MISSING, token_limits=None, transform_user='all', transform_assistant=False)
Reactively read chat messages
Obtain chat messages within a reactive context. The default behavior is intended for passing messages along to a model for response generation where you typically want to:
- Cap the number of tokens sent in a single request (i.e.,
token_limits
). - Apply user input transformations (i.e.,
transform_user
), if any. - Not apply assistant response transformations (i.e.,
transform_assistant
) since these are predominantly for display purposes (i.e., the model shouldn't concern itself with how the responses are displayed).
Parameters
format: MISSING_TYPE |
ProviderMessageFormat
= MISSING-
The message format to return. The default value of
MISSING
means chat messages are returned asChatMessage
objects (a dictionary withcontent
androle
keys). Other supported formats include:"anthropic"
: Anthropic message format."google"
: Google message (aka content) format."langchain"
: LangChain message format."openai"
: OpenAI message format."ollama"
: Ollama message format.
token_limits: tuple[int, int] | None = None
-
Limit the conversation history based on token limits. If specified, only the most recent messages that fit within the token limits are returned. This is useful for avoiding âexceeded token limitâ errors when sending messages to the relevant model, while still providing the most recent context available. A specified value must be a tuple of two integers. The first integer is the maximum number of tokens that can be sent to the model in a single request. The second integer is the amount of tokens to reserve for the modelâs response. Note that token counts based on the
tokenizer
provided to theChat
constructor. transform_user: Literal[âallâ, âlastâ, ânoneâ] = âallâ
-
Whether to return user input messages with transformation applied. This only matters if a
transform_user_input
was provided to the chat constructor. The default value of"all"
means all user input messages are transformed. The value of"last"
means only the last user input message is transformed. The value of"none"
means no user input messages are transformed. transform_assistant: bool = False
-
Whether to return assistant messages with transformation applied. This only matters if an
transform_assistant_response
was provided to the chat constructor.
Note
Messages are listed in the order they were added. As a result, when this method is called in a .on_user_submit()
callback (as it most often is), the last message will be the most recent one submitted by the user.
Returns
Type | Description |
---|---|
tuple[ChatMessage , âŚ] |
A tuple of chat messages. |
on_user_submit
express.ui.Chat.on_user_submit(fn=None)
Define a function to invoke when user input is submitted.
Apply this method as a decorator to a function (fn
) that should be invoked when the user submits a message. The function should take no arguments.
In many cases, the implementation of fn
should do at least the following:
- Call
.messages()
to obtain the current chat history. - Generate a response based on those messages.
- Append the response to the chat history using
.append_message()
( or.append_message_stream()
if the response is streamed).
Parameters
fn:
SubmitFunction
|SubmitFunctionAsync
| None = None-
A function to invoke when user input is submitted.
Note
This method creates a reactive effect that only gets invalidated when the user submits a message. Thus, the function fn
can read other reactive dependencies, but it will only be re-invoked when the user submits a message.
set_user_message
express.ui.Chat.set_user_message(value)
Deprecated. Use update_user_input(value=value)
instead.
transform_assistant_response
express.ui.Chat.transform_assistant_response(fn=None)
Transform assistant responses.
Use this method as a decorator on a function (fn
) that transforms assistant responses before displaying them in the chat. This is useful for post-processing model responses before displaying them to the user.
Parameters
fn:
TransformAssistantResponseFunction
| None = None-
A function that takes a string and returns either a string, shiny.express.ui.HTML, or
None
. Iffn
returns a string, it gets interpreted and parsed as a markdown on the client (and the resulting HTML is then sanitized). Iffn
returns shiny.express.ui.HTML, it will be displayed as-is. Iffn
returnsNone
, the response is effectively ignored.
Note
When doing an .append_message_stream()
, fn
gets called on every chunk of the response (thus, it should be performant), and can optionally access more information (i.e., arguments) about the stream. The 1st argument (required) contains the accumulated content, the 2nd argument (optional) contains the current chunk, and the 3rd argument (optional) is a boolean indicating whether this chunk is the last one in the stream.
transform_user_input
express.ui.Chat.transform_user_input(fn=None)
Transform user input.
Use this method as a decorator on a function (fn
) that transforms user input before storing it in the chat messages returned by .messages()
. This is useful for implementing RAG workflows, like taking a URL and scraping it for text before sending it to the model.
Parameters
fn:
TransformUserInput
|TransformUserInputAsync
| None = None-
A function to transform user input before storing it in the chat
.messages()
. Iffn
returnsNone
, the user input is effectively ignored, and.on_user_submit()
callbacks are suspended until more input is submitted. This behavior is often useful to catch and handle errors that occur during transformation. In this case, the transform function should append an error message to the chat (via.append_message()
) to inform the user of the error.
ui
express.ui.Chat.ui(placeholder='Enter a message...', width='min(680px, 100%)', height='auto', fill=True, **kwargs)
Place a chat component in the UI.
This method is only relevant fpr Shiny Express. In Shiny Core, use chat_ui
instead to insert the chat UI.
Parameters
placeholder: str = âEnter a messageâŚâ
-
Placeholder text for the chat input.
width:
CssUnit
= âmin(680px, 100%)â-
The width of the chat container.
height:
CssUnit
= âautoâ-
The height of the chat container.
fill: bool = True
-
Whether the chat should vertically take available space inside a fillable container.
kwargs: TagAttrValue = {}
-
Additional attributes for the chat container element.
update_user_input
express.ui.Chat.update_user_input(value=None, placeholder=None)
Update the user input.
Parameters
user_input
express.ui.Chat.user_input(transform=False)
Reactively read the user's message.
Parameters
transform: bool = False
-
Whether to apply the user input transformation function (if one was provided).
Returns
Type | Description |
---|---|
str | None | The user input message (before any transformation). |
Note
Most users shouldnât need to use this method directly since the last item in .messages()
contains the most recent user input. It can be useful for:
- Taking a reactive dependency on the userâs input outside of a
.on_user_submit()
callback. - Maintaining message state separately from
.messages()
.