Chat Component - Reference Guide

Read this before creating chat widgets.

Overview

The chat component provides a full-featured conversational UI with:

• Message rendering with inline markdown
• Streaming responses with token-by-token display
• Stop-generation (cancel in-flight LLM responses)
• Thread management (create, switch, delete)
• Slash command palette (type / to see commands)
• Settings panel (model, temperature, system prompt)
• LLM provider adapters (OpenAI, Anthropic, custom callback)

Quick Start

Via MCP Tool

{
  "name": "create_chat_widget",
  "arguments": {
    "title": "AI Assistant",
    "model": "gpt-4",
    "system_prompt": "You are a helpful assistant.",
    "streaming": true,
    "provider": "openai"
  }
}

Via Python

from pywry import App
from pywry.chat import ChatConfig, ChatWidgetConfig

app = App()
config = ChatWidgetConfig(
    title="AI Chat",
    height=600,
    chat=ChatConfig(
        system_prompt="You are helpful.",
        model="gpt-4",
        streaming=True,
        provider="openai",
    ),
)
# Widget creation handled by MCP or directly via app.show()

---

MCP Tools

create_chat_widget

Creates a chat widget. Returns {widget_id, thread_id}.

Parameter	Type	Default	Description
title	string	"Chat"	Window title
height	integer	600	Window height
system_prompt	string	""	System prompt for LLM
model	string	"gpt-4"	Model name
temperature	number	0.7	Sampling temperature (0-2)
max_tokens	integer	4096	Max tokens per response
streaming	boolean	true	Enable streaming
persist	boolean	false	Persist threads in ChatStore
provider	string	—	"openai", "anthropic", "callback"
show_sidebar	boolean	true	Show thread sidebar
slash_commands	array	—	Custom slash commands

chat_send_message

Send a user message. Returns {message_id, thread_id, sent}.

chat_stop_generation

Stop an in-flight generation. Idempotent. Returns partial content.

chat_manage_thread

Thread CRUD: create, switch, delete, rename, list.

chat_register_command

Register a slash command at runtime.

chat_get_history

Paginated conversation history with cursor (before_id).

chat_update_settings

Update model, temperature, system prompt, etc.

chat_set_typing

Show/hide the typing indicator.

---

Event Contract

Incoming Events (Python → Frontend)

Event	Payload
chat:assistant-message	{messageId, text, threadId}
chat:stream-chunk	{chunk, messageId, threadId, done}
chat:typing-indicator	{typing, threadId}
chat:switch-thread	{threadId}
chat:update-thread-list	{threads: [{thread_id, title}]}
chat:clear	{}
chat:register-command	{name, description}
chat:update-settings	{model, temperature, system_prompt}
chat:state-response	{messages, threads, settings, activeThreadId}
chat:generation-stopped	{messageId, threadId, partialContent}

Outgoing Events (Frontend → Python)

Event	Payload
chat:user-message	{text, threadId, timestamp}
chat:slash-command	{command, args, threadId}
chat:thread-create	{title}
chat:thread-switch	{threadId}
chat:thread-delete	{threadId}
chat:settings-change	{key, value}
chat:request-history	{threadId, limit}
chat:stop-generation	{threadId, messageId}
chat:request-state	{}

---

Stop-Generation Mechanics

1. User clicks Stop button → frontend immediately re-enables UI
2. chat:stop-generation sent to backend
3. Backend sets cancel_event on GenerationHandle
4. LLM provider checks cancel_event.is_set() between chunks
5. Provider raises GenerationCancelledError → partial content saved
6. Backend emits chat:generation-stopped with partial content
7. Frontend marks message as "(stopped)"

The UI never waits for backend confirmation — recovery is instant.

---

Default Slash Commands

Command	Description
/clear	Clear conversation
/export	Export chat history
/model	Switch model
/system	Change system prompt

Register custom commands via chat_register_command tool or ChatConfig.slash_commands list.

---

LLM Providers

OpenAI

{"provider": "openai"}

Requires openai package and OPENAI_API_KEY environment variable.

Anthropic

{"provider": "anthropic"}

Requires anthropic package and ANTHROPIC_API_KEY environment variable.

Custom Callback

from pywry.chat.providers.callback import CallbackProvider

provider = CallbackProvider(
    prompt_fn=my_prompt,   # (session_id, content_blocks, cancel_event) → AsyncIterator[SessionUpdate]
)

---

Safety Constants

Constant	Value	Purpose
MAX_RENDERED_MESSAGES	200	DOM cap for performance
MAX_CONTENT_LENGTH	100,000	Per-message content limit
MAX_MESSAGES_PER_THREAD	1,000	Eviction threshold
STREAM_TIMEOUT_SECONDS	30	Max silence before timeout
SEND_COOLDOWN_MS	1,000	Input rate limit
GENERATION_HANDLE_TTL	300	Auto-expire stale handles