Phase 16 — Web UI

Replace the PySide6 layer with a browser-based frontend served by the existing FastAPI gateway. The Python backend — agents, tools, services, ZMQ bus — is untouched.

Motivation

LoCAL2 is heading toward being shared with others. The current PySide6 UI has real barriers: Qt dependency friction, a chat layout that doesn't match what people expect from frontier models, context and compaction as separate windows, no settings page. Every successful local LLM tool that's been shared widely (Open WebUI, Jan, AnythingLLM) is browser-based. The LoCAL2 backend is the differentiator — the bus architecture, CriticAgent, score-weighted memory, reward loop. The frontend should be as frictionless as possible to install and use.

Install story: git clone + pip install -r requirements.txt → python run_local.py → open localhost:8080

What We're Not Doing

Not adopting Open WebUI. It solves the chat UI problem but has no concept of the critic feedback loop, score-weighted memory, or bus observability. Using it means either gutting it or abandoning LoCAL2's differentiators.
Not touching the backend. Agents, tools, services, ZMQ bus, ConversationService, MemoryService — all unchanged.
Not removing PySide6 in this phase. The two UIs coexist during migration. PySide6 is removed in Phase 17 once the web UI reaches parity.

Architecture

Browser └── WebSocket /ws/chat/{session_id} ──────────────────────────────────┐ └── REST /api/settings, /api/sessions, /api/feedback │ └── Static / (React build served by FastAPI) │ ▼ src/local/api/gateway.py (FastAPI) ZMQ Bus (existing) ├── WebSocket handler │ │ publishes query.received ──────────────────────────────▶ │ │ subscribes generation.thinking ◀──────────────────────── │ │ subscribes tool.activity.* ◀─────────────────────────── │ │ subscribes response.generation ◀─────────────────────── │ │ streams WS events → browser │ ├── Settings endpoints (read/write config YAML) │ ├── Sessions endpoints (list/get/delete) │ └── Serves frontend/dist/ as static files │ │ GeneratorAgent ◀────── query.received ────────────────────────── │ CriticAgent ──────▶ critique.result ──────────────────────── │ MemoryAgent ◀────── response.generation ─────────────────────┘ (all agents unchanged)

WebSocket Event Protocol

The gateway translates ZMQ bus events into a typed WebSocket event stream. The browser receives a sequence of JSON objects for each query:

// Client → server (one message per query)
{ "query": "...", "attachments": [...], "session_id": "..." }

// Server → client (stream)
{ "type": "thinking_chunk", "chunk": "...", "query_id": "..." }
{ "type": "tool_start",  "tool": "web_search", "args": {...},    "query_id": "..." }
{ "type": "tool_result", "tool": "web_search", "result": "...", "query_id": "..." }
{ "type": "response",    "answer": "...", "thinking": "...",
  "tool_calls": [...], "session_id": "...", "query_id": "...", "prompt_tokens": 0 }
{ "type": "error",       "message": "..." }
{ "type": "critique",    "score": 4, "feedback": "...", "query_id": "..." }

The WebSocket stays open for the session lifetime. Subsequent queries on the same connection reuse the same subscription. A separate /ws/bus/{session_id} endpoint streams all bus events for developer mode (state machine transitions, raw tool activity).

Frontend Stack

React + Vite + TypeScript — wider contributor familiarity than Svelte, strong ecosystem for markdown rendering and streaming UI. Component library: shadcn/ui (Tailwind-based, copy-paste components, no runtime dependency). Markdown: react-markdown + remark-gfm + highlight.js.

Build output goes to frontend/dist/
FastAPI mounts frontend/dist/ at / via StaticFiles
Dev: vite dev proxies /ws and /api to the Python server

Milestones

16.1 — WebSocket Gateway

backend

Extend src/local/api/gateway.py with two WebSocket endpoints and new REST endpoints for settings and sessions. No frontend work yet — verify with wscat or a minimal HTML test page.

New endpoints

WS /ws/chat/{session_id} — query/response stream
WS /ws/bus/{session_id} — raw bus event stream (developer mode)
GET /api/settings — returns all YAML configs as JSON
POST /api/settings/{name} — writes a config YAML (validates keys)
GET /api/sessions — lists sessions from ConversationService
GET /api/sessions/{id} — returns session message history
DELETE /api/sessions/{id} — deletes a session
POST /api/sessions/{id}/compact — triggers compaction
POST /api/feedback — publishes user.feedback to bus (completes Phase 4)

Files

src/local/api/gateway.py — add WS handlers + new REST endpoints
src/local/api/ws_bridge.py — ZMQ→WebSocket event translation
src/local/api/settings_api.py — config read/write logic

16.2 — Frontend Scaffold

frontend

Create the React+Vite project, wire the WebSocket client, and implement a minimal chat loop: send query → stream thinking → display response. No styling polish yet; this is about proving the end-to-end data path works.

frontend/ directory with Vite project
useWebSocket hook wrapping the WS connection with reconnect logic
useChatStream hook accumulating event stream into message state
FastAPI serves frontend/dist/; run_local.py --api launches both

Files

frontend/ — Vite + React + TypeScript project
frontend/src/hooks/useWebSocket.ts
frontend/src/hooks/useChatStream.ts
run_local.py — --api mode also serves frontend

16.3 — Chat Interface

frontend

The primary chat experience. Should feel like a frontier model UI: conversation in the main panel, thinking tokens as inline collapsible blocks, tool calls as compact activity chips, response rendered as markdown.

Components

MessageList — scrollable conversation; assistant messages render markdown
ThinkingBlock — inline collapsible block showing thinking tokens as they stream in; collapsed by default once response arrives
ToolCallChip — compact pill showing tool name + status (spinning → done); expandable to show args/result
MessageInput — textarea with attachment button, send on Enter, Shift+Enter for newline
CritiqueBar — subtle score indicator below each assistant message (1–5 dots); appears when critique arrives
TokenGauge — compact arc or progress bar in the chat header showing context usage; Compact button triggers /api/sessions/{id}/compact

Key UX decisions

Context window usage and compaction are inline in the chat header — not separate windows
Thinking tokens are inline but collapsed — users who want them can expand; they don't dominate the view
Tool calls are visible as activity but not disruptive — chips not panels
Critique score is subtle — coloured dots under the response, not a prominent grade

16.4 — Settings Page

frontendbackend

A proper settings UI backed by the /api/settings endpoints. Reads current YAML config, renders editable form fields, writes back on save. No direct YAML file editing required.

Settings sections

Section	Fields
Generator	model, temperature, num_ctx, system_prompt, max_tool_iterations
Critic	model, temperature, grade_timeout, rubric (textarea)
Memory	model, collection names, score_weight, recency_weight
Web Search	provider, api_key (masked), max_results
Location	override toggle, city/region/country fields

Settings changes take effect on next query (ConfigManager invalidation already handles hot-reload for tools that watch CONFIG_NAME).

16.5 — Conversation Navigator

frontend

Left sidebar listing past sessions from /api/sessions. Clicking a session loads its history into the chat view. New session button clears and starts fresh. Mirrors the existing ConversationsWindow but inline in the main layout.

Session list with title (first user message, truncated), date, turn count
Active session highlighted
Delete session with confirmation
Collapse sidebar to icon-only on narrow viewports

16.6 — Developer Mode (Observability)

frontend

A toggleable developer panel that surfaces LoCAL2's observability layer — the differentiating features that no other local LLM frontend has. Hidden by default for end users; one click to reveal for researchers and developers.

Dev panel tabs

Bus — live stream of all bus events (via /ws/bus); filterable by subject prefix
Generator — state machine (current state highlighted), tool registry, system prompt, token count
Critic — recent grades with feedback text; state machine
Memory — recent engram writes; classification intent/entities
Tools — per-tool activity log (request → result, latency)

Uses the /ws/bus stream — no new backend logic required. The frontend filters and routes events to the appropriate panel.

File Map

File	Status	Notes
`src/local/api/gateway.py`	modified	Add WS endpoints, settings/sessions REST, static serving
`src/local/api/ws_bridge.py`	new	ZMQ→WebSocket event translation + bus subscription management
`src/local/api/settings_api.py`	new	Config read/write with validation
`run_local.py`	modified	`--api` mode auto-opens browser; default port 8080
`frontend/`	new	React + Vite + TypeScript project
`frontend/src/hooks/`	new	useWebSocket, useChatStream, useSettings, useSessions
`frontend/src/components/`	new	MessageList, ThinkingBlock, ToolCallChip, TokenGauge, SettingsForm, DevPanel, SessionNav
`src/local/ui/`	kept	PySide6 UI unchanged in Phase 16; removed in Phase 17

What PySide6 Had — Web Equivalent

PySide6 window	Web equivalent	Where
Main chat window	MessageList + MessageInput	Main panel
ThinkingWindow	ThinkingBlock (inline, collapsible)	Inline in message
ToolWindow	ToolCallChip + Dev panel Tools tab	Inline chip + Dev mode
CriticWindow	CritiqueBar + Dev panel Critic tab	Under message + Dev mode
GeneratorWindow	Dev panel Generator tab	Dev mode
MemoryWindow	Dev panel Memory tab	Dev mode
ConversationsWindow	Session navigator sidebar	Left sidebar
DocumentsWindow	Settings → Library section	Settings page
Context gauge + Compact button	TokenGauge in chat header	Chat header
YAML config editing (none)	Settings page	Settings page (new)

Run Modes After Phase 16

# Web UI (default, opens browser)
python run_local.py

# Web UI headless (no browser pop, useful for servers)
python run_local.py --headless

# Legacy PySide6 (during transition)
python run_local.py --desktop

# Web UI + API exposed (for external clients)
python run_local.py --api-port 8080

Non-Goals for Phase 16

Multi-user auth — still single-user local tool
Docker / containerisation
Removing PySide6 (Phase 17)
pip packaging / PyPI (future)
Mobile layout

Acceptance Criteria

Query → streaming thinking tokens → tool call chips → markdown response, all in browser, matches latency of PySide6 UI
Thinking tokens are inline and collapsible, not in a separate window
Settings page reads and writes all five config sections; changes take effect on next query without restart
Conversation navigator lists and rejoins past sessions
Developer mode toggle shows bus stream, generator state, critic grades, memory engrams, tool activity
Token gauge updates after each response; Compact triggers compaction inline
python run_local.py opens the browser automatically on first run
All existing Python tests continue to pass