Reference for import praisonaiui as aiui.
import praisonaiui as aiui
These functions configure the server. Call them at module level in your app.py, before the server starts.
app.py
Set the UI style.
| Parameter | Type | Values |
|-----------|------|--------|
| style | str | "chat", "dashboard", "agents", "playground", "docs", "custom" |
style
str
"chat"
"dashboard"
"agents"
"playground"
"docs"
"custom"
Priority: set_style() → CLI --style flag → auto-detection.
set_style()
--style
Configure the sidebar branding (title text and logo emoji).
| Parameter | Type | Default |
|-----------|------|---------|
| title | str | "PraisonAI" |
title
"PraisonAI"
| logo | str | "🦞" |
logo
"🦞"
Also configurable via config.yaml:
config.yaml
---
Set the persistence backend for sessions and messages.
Set the AI provider for chat completions.
Register an AI agent for the dashboard. Agents appear in the sidebar and can be selected for chat.
Remove a page from the sidebar.
Configure chat window display mode — full page, floating window, or sidebar panel.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| mode | str | "fullpage" | "fullpage", "floating", or "sidebar" |
mode
"fullpage"
"floating"
"sidebar"
| position | tuple[int, int] | (20, 20) | (bottom, right) pixel offset for floating mode |
position
tuple[int, int]
(20, 20)
| size | tuple[int, int] | (400, 500) | (width, height) initial size for floating mode |
size
(400, 500)
| resizable | bool | True | Allow resizing the floating window |
resizable
bool
True
| minimized | bool | False | Start minimized (floating mode only) |
minimized
False
Configure sidebar behavior and dimensions.
| collapsible | bool | True | Allow sidebar to be collapsed |
collapsible
| default_collapsed | bool | False | Start with sidebar collapsed |
default_collapsed
| width | int | 260 | Default sidebar width in pixels |
width
int
260
| min_width | int | 200 | Minimum width when resizing |
min_width
200
| max_width | int | 360 | Maximum width when resizing |
max_width
360
Set the brand/primary accent color. Overrides the theme's default accent.
| Parameter | Type | Description |
|-----------|------|-------------|
| color | str | Hex color (e.g. "#6366f1") or CSS color value |
color
"#6366f1"
Configure which chat features are enabled in the UI.
| history | bool | True | Show session history sidebar |
history
| streaming | bool | True | Enable streaming responses |
streaming
| file_upload | bool | False | Show file upload button |
file_upload
| audio | bool | False | Show audio input button |
audio
| reasoning | bool | True | Show reasoning/thinking steps |
reasoning
| tools | bool | True | Show tool call displays |
tools
| multimedia | bool | True | Enable multimedia rendering |
multimedia
| feedback | bool | False | Show feedback buttons |
feedback
Configure dashboard layout options.
| sidebar | bool | True | Show the left sidebar navigation |
sidebar
| page_header | bool | True | Show the page title/description header |
page_header
Configure the chat + canvas split preview (chat-canvas page). The vanilla chat page is unchanged.
chat-canvas
chat
| enabled | bool | True | Expose preview settings in /ui-config.json |
enabled
/ui-config.json
| surface_id | str | "main" | Default A2UI surface id for the preview panel |
surface_id
"main"
| width | str | "40%" | CSS width of the preview column (e.g. "38%", "420px") |
"40%"
"38%"
"420px"
See A2UI canvas.
Register a custom theme preset. The theme becomes available in the theme picker UI and via /api/theme.
/api/theme
| name | str | Unique theme name (e.g. "ocean", "sunset") |
name
"ocean"
"sunset"
| variables | dict[str, str] | Dict with at least {"accent": "#hexcolor"} |
variables
dict[str, str]
{"accent": "#hexcolor"}
See CSS Architecture for all available CSS variables.
Inject a local JavaScript file into the UI. Reads the file at path and
path
serves it at /custom.js. A <script src="/custom.js"> tag is injected
/custom.js
<script src="/custom.js">
into the host HTML after the plugin loader, so window.aiui and all
window.aiui
registry APIs (registerView, registerComponent) are ready when your
registerView
registerComponent
code runs.
| path | str \| Path | Local filesystem path to a .js file |
str \| Path
.js
Raises FileNotFoundError if the path does not exist.
FileNotFoundError
Where plugin.js uses the client-side extension APIs:
plugin.js
Register a JSON Schema contract for a component dict. Built-in schemas
are auto-derived from every aiui.ui.* builder at startup; user schemas
aiui.ui.*
take priority and are merged on top.
| component_type | str | Component type string (e.g. "timeline") |
component_type
"timeline"
| schema | dict | JSON Schema dict (Draft 2020-12 compatible) |
schema
dict
Returns the merged registry as a dict[str, dict]. Also available as a
dict[str, dict]
JSON endpoint: GET /api/components/schemas.
GET /api/components/schemas
Pause the agent and wait for the user to answer. Preferred entry point
for interactive agent flows — supersedes the legacy AskUserMessage
AskUserMessage
class.
| question | str | Text shown to the user. |
question
| options | list[str] \| None | Optional list of choices. When given, the user picks one; otherwise they type free text. |
options
list[str] \| None
| timeout | float | Seconds to wait before giving up. Default 300 (5 min). |
timeout
float
Returns a PromptResult dataclass (text, choice, message_id).
PromptResult
text
choice
message_id
The result is truthy when the user answered, falsy on timeout.
Emit an error message to the chat. A thin helper around Message with
Message
metadata={"kind": "error"} — keeps the public surface small.
metadata={"kind": "error"}
One-stop configuration function. Every keyword is optional, so you only
set what you need. Replaces the dozen individual set_* setters for
set_*
most common cases (the set_* functions remain for advanced control).
| datastore | str | Storage backend: "memory", "json", "json:/path", "sdk", "sdk:/path". |
datastore
"memory"
"json"
"json:/path"
"sdk"
"sdk:/path"
| branding | dict | Forwarded to set_branding(...). Keys: title, logo, subtitle. |
branding
set_branding(...)
subtitle
| theme | dict | Forwarded to set_theme(...). Keys: preset, dark/dark_mode, radius, brand_color. |
theme
set_theme(...)
preset
dark
dark_mode
radius
brand_color
| chat | dict | Forwarded to set_chat_features(...). Keys: feedback, mode, plus any chat-feature flag. |
set_chat_features(...)
| custom_css| str \| Path | Path to a CSS file; same as set_custom_css. |
custom_css
set_custom_css
| custom_js | str \| Path | Path to a JS file; same as set_custom_js. |
custom_js
set_custom_js
| style | str | UI style — "chat", "dashboard", etc. |
Handle incoming chat messages. This is the core callback.
The message object has:
message
message.content
message.session_id
message.images
Send a welcome message when a user connects.
Cleanup when a user disconnects.
Define conversation starters shown to new users.
Define chat profiles (agent personas users can choose).
Register a custom dashboard page.
Listen for server events.
Handle authentication.
Provide user settings.
Resume interrupted sessions.
Handle user actions from an A2UI surface (button clicks, form submits).
Async functions for sending messages to the user. Call inside callback handlers.
| Function | Purpose |
|----------|---------|
| await aiui.say(text) | Send a complete message |
await aiui.say(text)
| await aiui.stream(text) | Stream a response progressively |
await aiui.stream(text)
| await aiui.stream_token(token) | Stream token-by-token |
await aiui.stream_token(token)
| await aiui.think(text) | Show a thinking indicator |
await aiui.think(text)
| await aiui.ask(question) | Ask user a question (returns answer) |
await aiui.ask(question)
| await aiui.image(url) | Send an image |
await aiui.image(url)
| await aiui.audio(url) | Send audio |
await aiui.audio(url)
| await aiui.video(url) | Send video |
await aiui.video(url)
| await aiui.file(url) | Send a file |
await aiui.file(url)
| await aiui.action_buttons(buttons) | Show action buttons |
await aiui.action_buttons(buttons)
| await aiui.tool(name, data) | Show tool call result |
await aiui.tool(name, data)
Build custom page layouts with UI components.
| Component | Usage |
|-----------|-------|
| aiui.layout(children) | Root container for a page |
aiui.layout(children)
| aiui.card(title, *, value, footer) | Metric/stat card with title, value, and optional footer |
aiui.card(title, *, value, footer)
| aiui.columns(children) | Horizontal column layout |
aiui.columns(children)
| aiui.chart(data, type) | Chart (line, bar, pie) |
aiui.chart(data, type)
| aiui.table(headers, rows) | Data table |
aiui.table(headers, rows)
| aiui.text(content) | Text block |
aiui.text(content)
See Component API Reference for all 48 components.
| Class | Purpose |
|-------|---------|
| aiui.Message | Incoming/outgoing message |
aiui.Message
| aiui.AskUserMessage | User response to ask() |
aiui.AskUserMessage
ask()
| aiui.Step | Processing step indicator |
aiui.Step
| aiui.BaseDataStore | Abstract datastore interface |
aiui.BaseDataStore
| aiui.MemoryDataStore | In-memory store |
aiui.MemoryDataStore
| aiui.JSONFileDataStore | Persistent JSON file store |
aiui.JSONFileDataStore
| aiui.BaseProvider | Abstract AI provider interface |
aiui.BaseProvider
| aiui.PraisonAIProvider | PraisonAI provider implementation |
aiui.PraisonAIProvider
| aiui.RunEvent | Streaming event |
aiui.RunEvent
| aiui.RunEventType | Event type enum |
aiui.RunEventType
Register custom features that appear in the dashboard.
| aiui.register_feature(feature) | Register a feature |
aiui.register_feature(feature)
| aiui.get_features() | List all features |
aiui.get_features()
| aiui.get_feature(name) | Get a specific feature |
aiui.get_feature(name)
| aiui.auto_register_defaults() | Auto-register built-in features |
aiui.auto_register_defaults()