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}.

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)

Outgoing Events (Frontend → Python)

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

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