ShinyChat

0.2.9 · active · verified Thu Apr 16

ShinyChat is a Python library that provides a Shiny toolkit for building generative AI applications like chatbots and streaming content directly within Shiny applications. It offers easy-to-use chat UI components that integrate seamlessly with various LLM frameworks. The library is actively maintained with frequent updates, currently at version 0.2.9.

Common errors

```
ImportError: cannot import name 'ToolResultDisplay' from 'chatlas.types'
```
cause `pydantic` is a soft dependency for `shinychat`'s `providers` extra, and is required by `chatlas` types like `ToolResultDisplay`. If `pydantic` is not installed, this error occurs.

fix Install `pydantic` by running `pip install pydantic` or `pip install shinychat[providers]`.
```
TypeError: Chat() got an unexpected keyword argument 'messages'
```
cause The `messages` parameter in the `Chat` constructor was deprecated in v0.2.0.

fix Initialize `chat = Chat(id="chat")` without the `messages` argument, then pass initial messages to the `chat.ui()` method: `chat.ui(messages=["Your initial message"])`.
```
ModuleNotFoundError: No module named 'shiny.express' or 'ModuleNotFoundError: No module named 'shiny''
```
cause `shinychat` is built on top of `Shiny for Python`. If `shiny` is not installed, any imports from `shiny` or `shinychat.express` will fail.

fix Install the `shiny` package: `pip install shiny`.
```
RuntimeError: Python version 3.9 or earlier is not supported by shinychat.
```
cause Shinychat v0.2.9 and later require Python 3.10 or newer.

fix Upgrade your Python environment to version 3.10, 3.11, or 3.12.

Warnings

deprecated Several `Chat` constructor parameters and related methods were deprecated in v0.2.0. This includes `Chat(messages=...)`, `Chat(tokenizer=...)`, all parameters to `.messages()`, and the `.transform_user_input` and `.transform_assistant_response` decorators.
Fix: Initialize `Chat` without message-related parameters, and use `chat.ui(messages=...)` to set initial messages. Perform input/response transformations manually outside of `Chat` methods.
gotcha `pydantic` is listed as a 'soft dependency' (optional, part of the `providers` extra) but can cause `ImportError` if not installed when using features like `chatlas.types.ToolResultDisplay`. This has been a recurring point of change across several minor versions.
Fix: If encountering import errors related to `pydantic` or `chatlas` types, ensure `pydantic` is installed by running `pip install shinychat[providers]` or `pip install pydantic`.
breaking Shinychat now requires Python 3.10 or later. Running with older Python versions will result in a `RuntimeError` or `SyntaxError` depending on the code.
Fix: Upgrade your Python environment to version 3.10 or newer.
gotcha When integrating with LangChain, ensure `langchain` version 1.0.0 or newer is installed. Older versions may lead to compatibility issues.
Fix: Install or upgrade LangChain using `pip install 'langchain>=1.0.0'` or `pip install shinychat[langchain]`.

Install

pip install shinychat Install core package
pip install shinychat[providers] Install with LLM provider dependencies (e.g., pydantic)
pip install shiny Install Shiny (shinychat is a dependency of shiny)

Imports

Chat
wrong:
```
from shiny.ui import Chat
```
correct:
```
from shinychat.express import Chat
```
While `ui.Chat` also works if `shiny` is imported, `shinychat.express.Chat` is the direct path for `shinychat`'s primary quickstart. For `shiny.App` structure, `chat = ui.Chat()` is used within the `server` function, with `ui.chat_ui()` in `app_ui`.

Quickstart

This quickstart creates a simple ShinyChat application where the AI assistant acts as an echo bot, repeating whatever the user types. It demonstrates the basic setup of a `Chat` instance, displaying its UI, and handling user input with an asynchronous callback.

import os
from shiny.express import ui
from shinychat.express import Chat

# Set some Shiny page options
ui.page_opts(
    title="Hello ShinyChat Echo Bot",
    fillable=True,
    fillable_mobile=True,
)

# Create a chat instance and display its UI
chat = Chat(id="chat")
chat.ui(
    messages=["Hello! I'm an echo bot. Type something and I'll repeat it!"]
)

# Define a callback to run when the user submits a message
@chat.on_user_submit
async def handle_user_input(user_input: str):
    # Simply echo the user's input back to them
    await chat.append_message(f"You said: {user_input}")

# To run this app, save it as `app.py` and execute:
# `uv shiny run --reload app.py` (if using uv)
# or `python -m shiny run --reload app.py` (if using pip/python)

view raw JSON →