Web UI

Web UI

The primary operator surface is kazma-ui: FastAPI + Jinja templates + Alpine.js + SSE streaming.

Start

kazma serve          # default 127.0.0.1:9090
# or
python serve.py

Open http://127.0.0.1:9090 (or your KAZMA_HOST/KAZMA_PORT).

Main pages

Page	Path	Purpose
Chat	/ or chat route	SSE streaming agent chat (sse_chat/, streaming.js)
Dashboard	/dashboard	Observability + Memory & Governance (health board, L2 property graph explorer, backups)
Settings	/settings	Models, providers, safety, account, Voice (?tab=voice — STT/TTS pickers; keys stay on Providers), Email (?tab=email), Documents (?tab=documents), About me (Memory tab), Chat step history and Swarm task history retention, the Turn time limit (how long a turn may run before it is stopped, on every surface; 0 = no limit, /long lifts it for a chat) and Proxy Provider (System tab), and Download / Restore settings backup with Undo last restore (System tab; the restore shows what will change first and keeps your keys, Configuration)
Providers control plane	/settings?tab=providers_connectors	Master-detail over every provider: state pill + edge stripe per row, declared capability badges, wire facts (base URL, API version read off it), and Test — GET /models plus a real chat completion (reachable vs chat_ok). Speech models (Whisper) are omitted; STT lives on the Voice tab. Key/model resolution rides the same registry paths a real message uses.
Swarm / Command Center	/swarm	Workers, live tasks, dispatch UI
Time Travel	/replay	Snapshot timeline browser, restore (rewind), fork (branch), compare diff, live SSE snapshot events
Research	/research	Start deep research (live SSE sessions), results list, archive, compare, export
Documents	/documents	Document Intelligence: upload, library, content preview, Knowledge libraries, convert/split/redact, job history, ops panel (capacity, readiness, audit, GC dry-run + confirm)
IDE	/ide	CodeMirror 5 editor, workspace files, apply-patch, run, git, AI-assisted edit
X Studio	/x	Compose, schedule, reschedule, thread hops, delete a live tweet, load saved drafts. Operator click is the approval. All clocks opens /scheduled.
Scheduled	/scheduled	Mixed clock: cron jobs and X posts
Login	/login	Secret / local user / OIDC

Documents page (product path)

1. Drop or pick a file (optional Force OCR). An upload past a limit (size, the storage free-space floor, the queue, the tenant’s caps or rate) is refused before the server reads the file, and the page shows why.
2. Library lists opaque ids + processing state (received … ready / fail states). On a single-operator install the page, the chat commands and the agent’s tools are one principal, the operator, so the documents the agent imported appear here too; with platform users the page lists what the signed-in user owns or was granted.
3. Detail: fenced content preview (first 8,000 characters, dir="auto" for BiDi), versions, jobs with their event history (Cancel while a job runs, Retry for a dead-lettered or rejected one), the Knowledge libraries the document is in (add, remove, or create a library), convert / PDF info / split / redact when the engines are ready (redact asks first), the artifacts with downloads, and Delete / Archive (asks first; the document leaves every library, and garbage collection reclaims its bytes later).
4. Ops card: capacity degraded_reasons, queue (depth, leases, retry waiting, dead letters), storage and quota, readiness (jobs/metadata multi-replica), a notice when saved settings need a restart, audit history, GC dry-run → kazmaConfirm → run. The audit history and GC are for administrators: for anyone else the history stays empty and GC says admin privileges are needed.
5. Settings → Documents for live limits, OCR (including reading ruled tables on scanned pages), malware and rollout without editing YAML.

REST: /api/documents/* · Guide: Document Intelligence · Ops: Document processing.

Dashboard metrics

Cards are fed by the in-memory TraceStore (LLM/tool traces) plus the cost circuit breaker budget state:

Card	Source	Notes
Total Cost	TraceStore total + cost breaker	API returns numbers; UI formats $…. Resets on process restart.
Total Tokens	TraceStore	Same process lifetime as traces.
Tool Calls	TraceStore (trace_type=tool)	Supervisor tool worker traces.
Circuit Breaker	Cost breaker (OK / WARNING / HALTED)	Not swarm worker breakers.
Uptime	TraceStore start time	Process lifetime of the store singleton.

GET /api/dashboard/status and WebSocket /ws/dashboard push numeric metrics (legacy string forms like "$0.00" / "1,234" are parsed safely in dashboard.js). Chat footer token/cost on a turn still comes from the SSE done event for that session.

Tokens Over Time and Cost Over Time draw what was spent, from the per-call LLM ledger (GET /api/dashboard/usage?range=hour|day|week, administrators): each bar is one slot’s tokens or cost, so the history survives restarts and page reloads. 1H shows 12 bars of 5 minutes, 24H 24 hourly bars, 7D 28 bars of 6 hours; the charts refresh once a minute. Until 2026-10-22 they drew the cards’ running totals as sampled by the open page, which only grew and were lost on a reload.

Answer-quality signals (administrators) refresh every 10 s. A failed read keeps the last reading on screen; a second failure in a row adds “Could not refresh; showing the last reading.”

Memory & Governance (Dashboard)

• Component health from build_memory_health() (V2 stack, embedder, packages, optional Neo4j/KB inject).
• V2 topology on the Dashboard canvas (belief graph; SQLite paint by default).
• Backups/maintenance for memory stores.

Memory admin (/memory)

Dedicated ops page (not the chat sidebar):

Area	What you can do
Graph & health (top)	Belief canvas, KPIs, probe, refresh/export; truncation banner when capped (nodes and hidden connections)
Entities	Rename display labels, merge/link shells, delete empty, click row → focus graph. Pagination + diacritic-insensitive/alias-aware search. Inspect: Group under / Ungroup (view-only)
Beliefs	Search (FTS5), Edit triple (single modal), invalidate batch with [Undo]; click row → focus edge endpoints + see “recalled N×” history
Pending merges	Approve/reject quarantine; merge shows a rewired-belief-count receipt
Hygiene	Purge empty, dedupe noted, archive dead (preview counts before run)
Hub identity	Person User / ent_… rename to Mubder updates canvas hub (not a second “You” node)

Multi-tenant isolation: memory is scoped by the request tenant with KAZMA_MEMORY_ENFORCE_TENANT=1, in production and with multi-user on — every /api/memory route, counts and hygiene included; the memory task queue, reconsolidation and golden eval are admin-only. APIs under /api/memory/v2/*. Full guide: Memory & RAG · Memory best path. Audit: AUDIT_MEMORY_SYSTEM_2026-08-24.md. Scale leftovers: MEMORY_REMAINING.md.

Research / scrape runs through chat tools and the Research panel start form + live SSE sessions (see Web research). Tour of the latest stack: Recent features.

Memory used (in each turn)

A turn that used memory shows a Memory used row in its activity: the facts, memories of past conversations, weekly summaries and library passages the model was shown, counted and listed. It is stored with the turn (a reload shows it) and appears in every tab watching the chat. With Settings → Memory → Explain recall on (the default), each line names the channels that found it (fts5, dense, belief_ppr, kb_rrf, …). The Dashboard probe uses the same tags; Run golden eval exercises the golden recall set.

Email (Settings → Email)

Connect real mailboxes for the agent without env-only setup:

Card	Modes
Sandbox	Always on (demo SQLite mailbox)
Gmail / Workspace	OAuth (Gmail API) · IMAP · POP
Microsoft 365	OAuth (Graph browser or device code) · IMAP · POP

API: /api/email/status, OAuth start/callback, POST /api/email/protocol/connect. Full guide: Email integration.

Research progress, results and acquisition settings

Research and Knowledge crawls keep saved job status across reloads. The global notification bell retains completion links to results and distinct partial, failure, cancellation and interruption alerts. No observed progress warns after 180 seconds by default; resumed progress clears the warning. Disconnected streams and failed result-list loads remain visible on their pages.

Settings → System → Web acquisition offers Read cached status without provider calls, an explicit permitted Firecrawl credit refresh, and Read alert settings for monitoring, completion notifications and stall/low-credit thresholds. Unsupported charges and balances remain unknown. External sends use configured ops routes; only platform acceptance proves delivery.

Acquisition defaults to local_only. Hosted fallback needs explicit mode and provider permission through the documented environment settings; a saved key does not enable it. AI planning and writing still use the configured model. See Web research for recovery, retention and platform limits.

Proxy Provider (Settings → System)

Opt-in scraping-resilience addon. Acquisition mode and proxy allowlist permission are required in addition to Settings. When permitted, scrape/crawl paths route through a residential rotating proxy (httpx ladder, Playwright, KB discover, Bing/Wiki SERP). Local SearXNG, Jina/Firecrawl APIs, and LLM traffic stay direct.

• Provider: None (direct) or anyIP.io (residential/mobile rotation).
• Fields: host/port/username/password (password vault-encrypted), network type, optional country, sticky-session toggle.
• Test Connection fetches api.ipify.org through the proxy and shows the exit IP.
• Live config — a Settings change takes effect without a restart.

API: GET/PUT /api/settings/proxy, POST /api/settings/proxy/test.
Coverage matrix: Recent features → Proxy · Web research.

Non-Stop Execution & Self-Healing (Settings → Agent)

Configurable self-healing supervisor watchdog and model failover controls for long-running autonomous workflows:

• Master Toggle: Enable/disable supervisor stall watchdog and automated checkpoint recovery.
• Stall & Timeout Controls: Configure stall threshold (default 60s) and per-tool execution timeout (agent.tool_timeout_seconds, default 120s).
• Recovery Budget: Set maximum recovery attempts (default 3) and exponential backoff parameters (backoff_base_seconds, backoff_max_seconds).
• Model Failover Chain: Toggle failover and specify an ordered list of fallback models with per-model cooldown periods (default 300s).
• Call Ledger: Toggle durable SQLite logging (kazma-data/llm_calls.db) for all LLM calls.
• Full EN/AR i18n support and live re-read (get_nonstop_config()) — settings apply immediately without server restart.

API: GET/PUT /api/settings/agent/nonstop. Coverage matrix: Recent features → Non-Stop Execution.

Auth

• Single-operator: KAZMA_SECRET (opaque sessions preferred over legacy raw cookie).
• Multi-user: platform users + RBAC + optional OIDC — see Multi-user SaaS.
• API routes default-deny when secret is configured.

UI conventions

• Dialogs: window.confirm, window.alert, and window.prompt are globally overridden — every call (current and future) routes through the styled Kazma modal (Alpine-based). Developers can still write if (!await confirm('Delete?')) and get the branded dialog. The kazmaConfirm / kazmaAlert / kazmaPrompt helpers remain available for opts-based calls (title, danger, confirmText, etc.).
• Chat Stop button: the send button transforms into a red pulsing Stop button during generation. Click it or press Escape to abort the SSE stream. The input field stays enabled so the user can type their next message while the agent works.
• Toasts: window.showToast / Alpine $store.toast.
• After an update: a tab opened before Kazma was updated shows one “Kazma was updated. Refresh to load the new version.” toast with a Refresh button. It checks the server’s build when the tab becomes visible and every 5 minutes; a restart of the same build shows nothing.
• Returning to a running turn: leaving a Chat while its turn runs and coming back, by the sidebar or a refresh, shows the turn live, including an approval it paused for. After a server restart the page takes the server’s position in the turn’s event journal instead of the one it saved, which the journal no longer holds.
• Research archive: each research card has an archive button. Archived items move to the “Archived” tab (with restore + delete). Uses the JSON metadata.archived flag — no schema migration.
• Page switching: a sidebar link swaps the page without a full reload (soft navigation, static/js/modules/nav.js). The incoming page’s own scripts run on every visit, the shared scripts in static/js/modules/ (Chat’s turn machinery) load once per version, and the base shell’s scripts run once with the page load. Until 2026-10-03 the shared ones were skipped, so a Chat reached from another page showed no turn until a reload; tests/test_soft_nav_page_scripts.py now checks that no script any page includes is left out.

Theming & design tokens

The Web UI runs on the “ABYSS” design system — a single token table per theme, defined in static/css/kazma.css (§1 dark, §23 light) with shell polish in kazma.v5.css. The same tokens are mirrored onto the docs site (docs/src/css/custom.css).

Aspect	Details
Dark palette	Deep blue-black slate — bg #0e1626, panel #16223a, text #eef3fb. Layered depth (panel → surface → elevated).
Light palette	Ice-blue paper — bg #f0f4fa, panel #ffffff, ink #0c1526. Muted text kept dark for P0 contrast.
Accents	Royal blue #3b82f6 (dark) / #2563eb (light) + sky #38bdf8. Brand gradient azure → royal → sky.
Type + mark	IBM Plex Sans / IBM Plex Sans Arabic (--font-sans / --font-arabic) + JetBrains Mono. Letterhead K is logo, favicon, and avatar. Same pairing as generated documents and Docusaurus.
Single token table	One source of truth per theme — the old v4 cyan palette and the “Abyss” set were folded into one table so they no longer fight (design-token unification, P1).
Server-authoritative theme	Theme is resolved server-side, not just client-side, so your choice persists across devices and browsers (a switch on one machine holds on another).
Real dark canvas	<html> carries color-scheme: only <theme> and is painted with the theme background, so iOS Safari can no longer paint its dark system canvas over Kazma Light.
Mobile chrome	Opaque header + dock (no see-through), keyboard-aware composer, retired hamburger, and the 769–1280px icon-rail dead strip is gone.
Forced HTML revalidation	Templates send cache-busting headers so a stale cached page can’t survive a deploy.
No x-show blink	x-cloak is global; any x-show panel also carries x-cloak, and inline display:flex never sits on an x-show element (flex lives in a class).

Tune the system by editing the token tables in kazma.css; the docs site follows the same values.

Related

• IDE · Command Center · API routes
• Deployment · Troubleshooting