types.ChatClient

types.ChatClient(chat, client)

Wraps a chatlas client bound to a :class:~shinychat.Chat instance.

This class is created automatically when you pass a client= argument to :class:~shinychat.Chat. It holds the current client, handles deferred swaps during streaming, and wires up bookmarking.

Attributes

Name	Description
value	The underlying chatlas client.

Methods

Name	Description
clear	Clear the chat and optionally reset the client’s turn history.
new_chat	Save the current conversation and start a new one.
set	Replace the chatlas client.

clear

types.ChatClient.clear(messages=None, greeting=False, client_history='clear')

Clear the chat and optionally reset the client’s turn history.

This is a lower-level operation for chats without conversation history. client_history controls only the underlying client’s turns. When conversation history is enabled, use :meth:new_chat instead so the rendered chat, client turns, and persisted conversation remain synchronized.

Parameters

Name	Type	Description	Default
messages	'list[ChatMessageDict] | None'	A list of messages to set or append on the client. Required when client_history is "set" or "append", and not allowed with "clear" or "keep".	None
greeting	bool	Passed to :meth:~shinychat.Chat.clear_messages.	False
client_history	Literal['clear', 'set', 'append', 'keep']	How to handle the client’s turn history: * "clear" (default): removes all turns from the client. * "set": sets the client’s turns to messages. Requires messages to be provided. * "append": appends messages to the client’s existing turns. Requires messages to be provided. * "keep": leaves the client’s turns untouched.	'clear'

Raises

Name	Type	Description
	shiny.types.NotifyException	If an assistant response is currently streaming. To avoid this error, guard the call by checking chat.latest_message_stream.status() != "running" before calling :meth:clear. The notification message is shown without sanitization because it is a fixed, user-safe string.

new_chat

types.ChatClient.new_chat(greeting=False)

Save the current conversation and start a new one.

This method is available only when conversation history is enabled. It saves the current record, clears the client turns and rendered messages, resets the active conversation ID, and updates the history drawer.

Parameters

Name	Type	Description	Default
greeting	bool	Passed to :meth:~shinychat.Chat.clear_messages. When True, also clears the greeting and resolves the configured greeting for the new conversation.	False

Raises

Name	Type	Description
	ValueError	If conversation history is not enabled.
	shiny.types.NotifyException	If an assistant response is currently streaming. To avoid this error, guard the call by checking chat.latest_message_stream.status() != "running" before calling :meth:new_chat.

set

types.ChatClient.set(new_client, *, sync=True)

Replace the chatlas client.

If a response stream is currently running the swap is deferred until the stream completes.

Parameters

Name	Type	Description	Default
new_client	'chatlas.Chat[Any, Any]'	The replacement chatlas client.	required
sync	bool	When True (the default), copies turns, system_prompt, and tools from the old client to the new one before swapping.	True