## Overview

The Citizen AI Streaming Chat widget embeds a streaming, conversational AI assistant on a cplace page. It is **config-first**: the widget points at an **Assistant Configuration** page (via `assistantConfiguration`), which defines the assistant's behavior — system message, model, tools, and data access. Optional low-code scripts refine that behavior at runtime, but no script is required to use the widget.

This is the current replacement for the deprecated Chat Widget (`cf.cplace.lowcode.ai.chatWidget`), which was script-first (it required a CplaceJS script with `checkAccess()`/`call()`). Streaming Chat inverts that: configuration is the anchor, scripting is optional.

## Use Cases

### Page-Contextual AI Assistants
Give users a chat assistant that answers questions about the current page and its related data, driven entirely by an Assistant Configuration page.

### Guided Q&A and Summaries
Let users ask for summaries, explanations, or management reports over the data an Assistant Configuration exposes.

### User-Specific vs. Shared Conversations
Choose between individual chat histories (each user sees their own conversation) and a shared conversation visible to everyone, via `isUserSpecificChat`.

## Design Considerations

### Config-First Architecture
The required anchor is `assistantConfiguration` — a reference to an Assistant Configuration page. Behavior lives there, not in the widget. The optional `configurationScript` and `postProcessingScript` adjust behavior without changing the configuration page.

### Memory
Conversation history is retained up to `maxMessages`. When there is no room for a new message, the oldest is evicted. Set it to balance context depth against cost and latency.

### Streaming and Tool Visibility
Responses stream token by token. `showToolExecutions` controls whether the tool calls the assistant makes are shown to the user in the chat.

## Common Pitfalls

- Leaving `assistantConfiguration` unset — the widget has nothing to drive it.
- Assuming a script is required — it is not; scripts only refine an already-working configuration.
- Embedding without the Citizen AI (`cf.cplace.lowcode.ai`) app installed in the space.

## Alternatives

| Widget | When to Use Instead |
|--------|---------------------|
| **[DEPRECATED] Citizen AI Chat** (`cf.cplace.lowcode.ai.chatWidget`) | Do not use for new work — Streaming Chat is its replacement. |
| **Ask Your Page Widget** (`cf.cplace.citizenAi.askYourPageWidget`) | When you need simple, pre-configured "Ask Your Page" functionality without an Assistant Configuration. |

## Related Patterns

- **Assistant Configuration page** — where the assistant's system message, model, tools, and data access are defined.