0 Fork 0

mirror of https://github.com/MervinPraison/PraisonAIUI.git synced 2026-11-11 03:31:28 -10:00

Files

T

MervinPraisonandClaude Opus 5.5 0073018a7a fix: explicit dashboard plugin allowlist for pages and manifests (fixes #340 )

Co-Authored-By: Claude Opus 5.5 <[email protected]>

2026-11-11 09:13:22 +00:00

18 KiB

Raw Blame History

Python SDK API

Reference for import praisonaiui as aiui.

Server Configuration

These functions configure the server. Call them at module level in your app.py, before the server starts.

`aiui.set_style(style)`

Set the UI style.

Parameter	Type	Values
`style`	`str`	`"chat"`, `"dashboard"`, `"agents"`, `"playground"`, `"docs"`, `"custom"`

aiui.set_style("dashboard")

Priority: set_style() → CLI --style flag → auto-detection.

`aiui.set_pages(page_ids)`

Whitelist which built-in sidebar pages to show (dashboard mode). Custom pages registered via @aiui.page() always appear.

aiui.set_pages([
    "chat", "agents", "memory", "knowledge",
    "skills", "sessions", "usage", "config", "logs",
])

Use aiui pages ids to see all available page IDs.

`aiui.set_branding(title, logo)`

Configure the sidebar branding (title text and logo emoji).

Parameter	Type	Default
`title`	`str`	`"PraisonAI"`
`logo`	`str`	`"🦞"`

aiui.set_branding(title="MyApp", logo="🚀")

Also configurable via config.yaml:

site:
  title: MyApp
  logo: 🚀

`aiui.set_datastore(store)`

Set the persistence backend for sessions and messages.

# JSON file store (default)
aiui.set_datastore(aiui.JSONFileDataStore())

# In-memory (no persistence)
aiui.set_datastore(aiui.MemoryDataStore())

`aiui.set_provider(provider)`

Set the AI provider for chat completions.

aiui.set_provider(aiui.PraisonAIProvider())

`aiui.register_agent(config)`

aiui.register_agent({
    "agent_id": "researcher",
    "name": "Researcher",
    "description": "Research assistant",
    "instructions": "You are a research assistant.",
    "model": "gpt-4o-mini",
    "icon": "🔬",
})

`aiui.remove_page(page_id)`

Remove a page from the sidebar.

aiui.remove_page("debug")

`aiui.set_chat_mode(mode, *, position, size, resizable, minimized)`

Configure chat window display mode — full page, floating window, or sidebar panel.

Parameter	Type	Default	Description
`mode`	`str`	`"fullpage"`	`"fullpage"`, `"floating"`, or `"sidebar"`
`position`	`tuple[int, int]`	`(20, 20)`	(bottom, right) pixel offset for floating mode
`size`	`tuple[int, int]`	`(400, 500)`	(width, height) initial size for floating mode
`resizable`	`bool`	`True`	Allow resizing the floating window
`minimized`	`bool`	`False`	Start minimized (floating mode only)

import praisonaiui as aiui

# Full page chat (default)
aiui.set_chat_mode("fullpage")

# Floating chat window
aiui.set_chat_mode("floating", position=(20, 20), size=(420, 550))

# Sidebar panel
aiui.set_chat_mode("sidebar")

`aiui.set_sidebar_config(*, collapsible, default_collapsed, width, min_width, max_width)`

Configure sidebar behavior and dimensions.

Parameter	Type	Default	Description
`collapsible`	`bool`	`True`	Allow sidebar to be collapsed
`default_collapsed`	`bool`	`False`	Start with sidebar collapsed
`width`	`int`	`260`	Default sidebar width in pixels
`min_width`	`int`	`200`	Minimum width when resizing
`max_width`	`int`	`360`	Maximum width when resizing

import praisonaiui as aiui

aiui.set_sidebar_config(collapsible=True, width=280)
aiui.set_sidebar_config(default_collapsed=True)  # Start collapsed

`aiui.set_brand_color(color)`

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

import praisonaiui as aiui

aiui.set_brand_color("#818cf8")  # Indigo-400
aiui.set_brand_color("#22c55e")  # Green-500

`aiui.set_chat_features(*, history, streaming, file_upload, audio, reasoning, tools, multimedia, feedback)`

Configure which chat features are enabled in the UI.

Parameter	Type	Default	Description
`history`	`bool`	`True`	Show session history sidebar
`streaming`	`bool`	`True`	Enable streaming responses
`file_upload`	`bool`	`False`	Show file upload button
`audio`	`bool`	`False`	Show audio input button
`reasoning`	`bool`	`True`	Show reasoning/thinking steps
`tools`	`bool`	`True`	Show tool call displays
`multimedia`	`bool`	`True`	Enable multimedia rendering
`feedback`	`bool`	`False`	Show feedback buttons

import praisonaiui as aiui

# Minimal chat — no history sidebar, no file upload
aiui.set_chat_features(history=False, file_upload=False)

# Full-featured chat
aiui.set_chat_features(
    history=True,
    streaming=True,
    file_upload=True,
    audio=True,
    feedback=True,
)

`aiui.set_dashboard(*, sidebar, page_header, modules, plugin_dirs, plugins)`

Configure dashboard layout options.

Parameter	Type	Default	Description
`sidebar`	`bool`	`True`	Show the left sidebar navigation
`page_header`	`bool`	`True`	Show the page title/description header
`modules`	`list[str] \| None`	`None`	Optional dashboard JS modules (`jobs`, `auth`, `api`)
`plugin_dirs`	`list[str] \| None`	`None`	Extra directories to scan for dashboard plugins
`plugins`	`list[str] \| None`	`None`	Allowlist of dashboard plugin names. `None` = all discovered (bundled, `~/.praisonai/dashboard-plugins`, `plugin_dirs`); `[]` = none

import praisonaiui as aiui

aiui.set_style("dashboard")
aiui.set_dashboard(sidebar=False)       # Chat-only dashboard, no sidebar
aiui.set_dashboard(page_header=False)   # Hide page titles
aiui.set_dashboard(plugins=[])          # No auto-discovered dashboard plugins

plugins filters both the sidebar pages (/api/pages) and the browser plugin manifest (/api/dashboard/plugins), so disabled plugin scripts are never loaded. It scopes navigation only — it is not an authorization boundary for API routes.

`aiui.set_chat_preview(enabled, *, surface_id, width)`

Configure the chat + canvas split preview (chat-canvas page). The vanilla chat page is unchanged.

Parameter	Type	Default	Description
`enabled`	`bool`	`True`	Expose preview settings in `/ui-config.json`
`surface_id`	`str`	`"main"`	Default A2UI surface id for the preview panel
`width`	`str`	`"40%"`	CSS width of the preview column (e.g. `"38%"`, `"420px"`)

aiui.set_chat_preview(enabled=True, surface_id="main", width="38%")
aiui.set_pages(["chat-canvas", "chat", "canvas"])

See A2UI canvas.

`aiui.register_theme(name, variables)`

Parameter	Type	Description
`name`	`str`	Unique theme name (e.g. `"ocean"`, `"sunset"`)
`variables`	`dict[str, str]`	Dict with at least `{"accent": "#hexcolor"}`

import praisonaiui as aiui

# Register a custom theme
aiui.register_theme("ocean", {"accent": "#0077b6"})

# With explicit RGB (auto-derived if omitted)
aiui.register_theme("sunset", {
    "accent": "#ff6b35",
    "accentRgb": "255,107,53",
})

# Apply the custom theme
aiui.set_theme(preset="ocean")

See CSS Architecture for all available CSS variables.

`aiui.set_custom_js(path)`

Inject a local JavaScript file into the UI. Reads the file at path and serves it at /custom.js. A <script src="/custom.js"> tag is injected into the host HTML after the plugin loader, so window.aiui and all registry APIs (registerView, registerComponent) are ready when your code runs.

Parameter	Type	Description
`path`	`str \| Path`	Local filesystem path to a `.js` file

Raises FileNotFoundError if the path does not exist.

import praisonaiui as aiui

aiui.set_custom_js("plugin.js")

Where plugin.js uses the client-side extension APIs:

// plugin.js
window.aiui.registerComponent('timeline', function(comp) {
    const el = document.createElement('div');
    (comp.events || []).forEach(ev => {
        const row = document.createElement('div');
        row.textContent = `${ev.time} — ${ev.label}`;
        el.appendChild(row);
    });
    return el;
});

`aiui.register_component_schema(component_type, schema)`

Register a JSON Schema contract for a component dict. Built-in schemas are auto-derived from every aiui.ui.* builder at startup; user schemas take priority and are merged on top.

Parameter	Type	Description
`component_type`	`str`	Component type string (e.g. `"timeline"`)
`schema`	`dict`	JSON Schema dict (Draft 2020-12 compatible)

import praisonaiui as aiui

aiui.register_component_schema("timeline", {
    "type": "object",
    "required": ["type", "events"],
    "properties": {
        "type": {"const": "timeline"},
        "events": {"type": "array"},
    },
})

`aiui.get_component_schemas()`

Returns the merged registry as a dict[str, dict]. Also available as a JSON endpoint: GET /api/components/schemas.

schemas = aiui.get_component_schemas()
print(sorted(schemas))   # ['accordion', 'alert', ..., 'timeline', ...]

`aiui.prompt(question, *, options=None, timeout=300.0)`

Pause the agent and wait for the user to answer. Preferred entry point for interactive agent flows — supersedes the legacy AskUserMessage class.

Parameter	Type	Description
`question`	`str`	Text shown to the user.
`options`	`list[str] \| None`	Optional list of choices. When given, the user picks one; otherwise they type free text.
`timeout`	`float`	Seconds to wait before giving up. Default 300 (5 min).

Returns a PromptResult dataclass (text, choice, message_id). The result is truthy when the user answered, falsy on timeout.

import praisonaiui as aiui

@aiui.reply
async def on_message(msg: str):
    name = await aiui.prompt("What's your name?")
    if name:
        await aiui.say(f"Hi {name.text}!")

    pick = await aiui.prompt("Pick a colour", options=["red", "blue"])
    if pick:
        await aiui.say(f"You picked {pick.choice}")

`aiui.error(content, *, details=None)`

Emit an error message to the chat. A thin helper around Message with metadata={"kind": "error"} — keeps the public surface small.

try:
    data = await fetch()
except Exception as exc:
    await aiui.error("Couldn't load data", details=str(exc))

`aiui.configure(*, datastore=None, branding=None, theme=None, chat=None, custom_css=None, custom_js=None, style=None)`

One-stop configuration function. Every keyword is optional, so you only set what you need. Replaces the dozen individual set_* setters for most common cases (the set_* functions remain for advanced control).

Parameter	Type	Description
`datastore`	`str`	Storage backend: `"memory"`, `"json"`, `"json:/path"`, `"sdk"`, `"sdk:/path"`.
`branding`	`dict`	Forwarded to `set_branding(...)`. Keys: `title`, `logo`, `subtitle`.
`theme`	`dict`	Forwarded to `set_theme(...)`. Keys: `preset`, `dark`/`dark_mode`, `radius`, `brand_color`.
`chat`	`dict`	Forwarded to `set_chat_features(...)`. Keys: `feedback`, `mode`, plus any chat-feature flag.
`custom_css`	`str \| Path`	Path to a CSS file; same as `set_custom_css`.
`custom_js`	`str \| Path`	Path to a JS file; same as `set_custom_js`.
`style`	`str`	UI style — `"chat"`, `"dashboard"`, etc.

import praisonaiui as aiui

aiui.configure(
    branding={"title": "My App", "logo": "🎨"},
    theme={"preset": "ocean", "dark": True, "radius": "md"},
    chat={"feedback": True, "mode": "single"},
    datastore="json",
    custom_css="styles.css",
    custom_js="plugin.js",
)

import praisonaiui as aiui

# In-memory (default, volatile)
aiui.configure(datastore="memory")

# JSON files at ~/.praisonaiui/sessions/
aiui.configure(datastore="json")

# JSON files at custom path
aiui.configure(datastore="json:/tmp/my-sessions")

# SDK-backed store (unifies with praisonai-agents)
aiui.configure(datastore="sdk")

Callback Decorators

`@aiui.reply`

Handle incoming chat messages. This is the core callback.

@aiui.reply
async def on_reply(message):
    await aiui.stream("Thinking...")
    # Process message.content
    await aiui.say("Here's the answer!")

The message object has:

message.content — user's text
message.session_id — session identifier
message.images — attached images (if any)

`@aiui.welcome`

Send a welcome message when a user connects.

@aiui.welcome
async def on_welcome():
    await aiui.say("Welcome! How can I help you today?")

`@aiui.goodbye`

Cleanup when a user disconnects.

@aiui.goodbye
async def on_goodbye():
    await aiui.say("Goodbye! Your session has been saved.")

`@aiui.starters`

Define conversation starters shown to new users.

@aiui.starters
async def on_starters():
    return [
        {"label": "What can you do?", "message": "Tell me about your capabilities"},
        {"label": "Help me write", "message": "Help me draft an email"},
    ]

`@aiui.profiles`

Define chat profiles (agent personas users can choose).

@aiui.profiles
async def on_profiles():
    return [
        {"name": "Expert", "description": "Expert mode", "icon": "🎓"},
        {"name": "Creative", "description": "Creative writer", "icon": "✍️"},
    ]

`@aiui.page(slug, title, icon, group, order)`

@aiui.page("analytics", title="Analytics", icon="📊", group="Control", order=60)
async def analytics_page():
    return aiui.layout([
        aiui.card("Revenue", aiui.chart(data, "line")),
        aiui.card("Users", aiui.table(headers, rows)),
    ])

`@aiui.on(event)`

Listen for server events.

@aiui.on("session_created")
async def on_session(session):
    print(f"New session: {session.id}")

`@aiui.login`

Handle authentication.

@aiui.login
async def on_login(credentials):
    return {"user_id": "123", "name": "Admin"}

`@aiui.settings`

Provide user settings.

@aiui.settings
async def on_settings():
    return {"theme": "dark", "language": "en"}

`@aiui.resume`

Resume interrupted sessions.

@aiui.resume
async def on_resume(session_id):
    await aiui.say("Welcome back! Resuming your session.")

`@aiui.surface_action(surface_id)`

Handle user actions from an A2UI surface (button clicks, form submits).

@aiui.surface_action("main")
async def on_surface_action(action: dict):
    # action includes component_id, action name, data, session_id
    return {"status": "ok"}

Message Functions

Async functions for sending messages to the user. Call inside callback handlers.

Function	Purpose
`await aiui.say(text)`	Send a complete message
`await aiui.stream(text)`	Stream a response progressively
`await aiui.stream_token(token)`	Stream token-by-token
`await aiui.think(text)`	Show a thinking indicator
`await aiui.ask(question)`	Ask user a question (returns answer)
`await aiui.image(url)`	Send an image
`await aiui.audio(url)`	Send audio
`await aiui.video(url)`	Send video
`await aiui.file(url)`	Send a file
`await aiui.action_buttons(buttons)`	Show action buttons
`await aiui.tool(name, data)`	Show tool call result

UI Components

Build custom page layouts with UI components.

@aiui.page("dashboard", title="My Dashboard", icon="📊")
async def my_dashboard():
    return aiui.layout([
        aiui.columns([
            aiui.card("Metric A", value="42"),
            aiui.card("Metric B", value="98%", footer="+5% this week"),
        ]),
        aiui.card("Data", aiui.table(
            headers=["Name", "Value"],
            rows=[["Alpha", "100"], ["Beta", "200"]],
        )),
        aiui.card("Trend", aiui.chart(
            data=[10, 20, 30, 40],
            type="line",
        )),
    ])

Component	Usage
`aiui.layout(children)`	Root container for a page
`aiui.card(title, *, value, footer)`	Metric/stat card with title, value, and optional footer
`aiui.columns(children)`	Horizontal column layout
`aiui.chart(data, type)`	Chart (line, bar, pie)
`aiui.table(headers, rows)`	Data table
`aiui.text(content)`	Text block

See Component API Reference for all 48 components.

Data Classes

Class	Purpose
`aiui.Message`	Incoming/outgoing message
`aiui.AskUserMessage`	User response to `ask()`
`aiui.Step`	Processing step indicator
`aiui.BaseDataStore`	Abstract datastore interface
`aiui.MemoryDataStore`	In-memory store
`aiui.JSONFileDataStore`	Persistent JSON file store
`aiui.BaseProvider`	Abstract AI provider interface
`aiui.PraisonAIProvider`	PraisonAI provider implementation
`aiui.RunEvent`	Streaming event
`aiui.RunEventType`	Event type enum

Feature Protocol

from praisonaiui import BaseFeatureProtocol, register_feature

class MyFeature(BaseFeatureProtocol):
    name = "my_feature"
    # ... implement protocol methods

register_feature(MyFeature())

Function	Purpose
`aiui.register_feature(feature)`	Register a feature
`aiui.get_features()`	List all features
`aiui.get_feature(name)`	Get a specific feature
`aiui.auto_register_defaults()`	Auto-register built-in features

18 KiB Raw Blame History

Python SDK API

Server Configuration

aiui.set_style(style)

aiui.set_pages(page_ids)

aiui.set_branding(title, logo)

aiui.set_datastore(store)

aiui.set_provider(provider)

aiui.register_agent(config)

aiui.remove_page(page_id)

aiui.set_chat_mode(mode, *, position, size, resizable, minimized)

aiui.set_sidebar_config(*, collapsible, default_collapsed, width, min_width, max_width)

aiui.set_brand_color(color)

aiui.set_chat_features(*, history, streaming, file_upload, audio, reasoning, tools, multimedia, feedback)

aiui.set_dashboard(*, sidebar, page_header, modules, plugin_dirs, plugins)

aiui.set_chat_preview(enabled, *, surface_id, width)

aiui.register_theme(name, variables)

aiui.set_custom_js(path)

aiui.register_component_schema(component_type, schema)

aiui.get_component_schemas()

aiui.prompt(question, *, options=None, timeout=300.0)

aiui.error(content, *, details=None)

aiui.configure(*, datastore=None, branding=None, theme=None, chat=None, custom_css=None, custom_js=None, style=None)