Deploy: docs refresh (ARCHITECTURE.md + READMEs); components-only architecture

README.md

@@ -9,6 +9,12 @@ pinned: false
 
 # AdaptiveUI (vivek)
 
-Claude-style single-call response + widget HTML rendered in an iframe.
+Claude-style single-call response **+ an interactive widget** for each answer. Widgets are
+built **only from the app's own UI components** (a registry), expressed as JSON and rendered
+by Vue components / ECharts — **no LLM-generated HTML, no iframe, no external chart libraries**.
+A Thompson-Sampling bandit adapts the prose-answer style; the widget is independent of it.
+
+See `vivek/ARCHITECTURE.md` for the full pipeline (registry → prompt menu → synthesizer →
+validate → components).
 
 This Space runs the `vivek` server on port 7860.

vivek/ARCHITECTURE.md

@@ -0,0 +1,153 @@
+# Adaptive Presentation Engine — Architecture
+
+A chat app where an LLM (Anthropic Claude) answers a question **and** generates an
+interactive widget for it. The widget is built **only from the app's own UI components**
+(a registry), expressed as **JSON** — there is **no LLM-generated HTML, no iframe, and no
+external chart libraries shipped by the model**. Charts render with bundled **ECharts**.
+
+There are two independent parts in every turn:
+
+- **Part A — Adaptive text strategy** (the bandit): picks *how the prose answer is written*.
+- **Part B — Visualization** (this doc's focus): decides *whether/what to visualize* and
+  generates the widget from the component registry.
+
+The two are decoupled: the bandit strategy only shapes the `<RESPONSE>` text; it never
+controls the `<WIDGET>`.
+
+---
+
+## The single source of truth: `frontend-vue/src/widget-registry.json`
+
+One JSON catalog of everything the app can render. It is read in **three** places so they
+can never drift:
+
+| Use | Reader | Purpose |
+|-----|--------|---------|
+| **GENERATE** | `backend/combined_prompt.py → build_json_widget_rule()` | turns the registry into the prompt "menu" sent to the LLM |
+| **VALIDATE** | `rag_finance/registry.py → allowed_types() / allowed_chart_kinds()` | drops anything off-menu in the LLM's output |
+| **RENDER** | `frontend-vue/src/lib/widgetRegistry.ts (COMPONENTS map)` + `lib/echartsOption.ts` | maps each block `type`/chart `kind` to a Vue component / ECharts option |
+
+### Block types (9)
+`text, kpi_row, chart, table, action_row, image, stat_card, progress, badge_row`
+
+### Chart kinds (33) and their data shapes
+```
+bar | hbar | line | area | stacked | combo | histogram | timeseries
+        → x_categories + series[].values   (also accepts items[] as one series)
+pie | donut | rose | funnel | treemap | sunburst
+        → items[{label,value}]
+scatter | bubble        → series[].values = [x,y]  (bubble: [x,y,size])
+boxplot                 → boxes[[min,q1,med,q3,max]]
+candlestick             → candles[[open,close,low,high]]
+waterfall               → items[{label,value=delta}]
+heatmap                 → x_labels + y_labels + matrix
+sankey | graph          → nodes[] + links[{source,target,value}]
+tree | mindmap | org    → root{name,children[]}
+scatter3d | bar3d | line3d  → series[].values = [x,y,z]   (echarts-gl)
+polar | parallel | themeriver | gauge | radar
+```
+(Removed deliberately: `calendar`, `surface` — they need hundreds of hand-typed values,
+which an LLM with no data backend can't author reliably.)
+
+---
+
+## Part B — Visualization flow (step by step)
+
+**Example query:** `Show NVIDIA's FY2024 revenue by segment as a bar chart`
+
+### 1. Assemble the prompt (`server.py → _build_adaptive_prompt → build_combined_system_prompt`)
+The system message includes the registry-derived **WIDGET RULES** menu plus the guardrails:
+- **OUTPUT CONTRACT** — return exactly `<RESPONSE>…</RESPONSE><WIDGET>{json}</WIDGET>`.
+- **RENDER NOW** — if a visual is warranted and buildable, output the widget *this* turn;
+  never defer (“I will plot…”), ask permission, or ask “which dataset?” when implied.
+- **WIDGET WARRANT** — include a widget only if a visual helps **and** you can fill it with
+  **real** values; else empty + say so.
+- **NO FABRICATED DATA** — never invent/estimate/“mock”/“illustrative” data; if you don't
+  have it, say so and render nothing.
+- **STRICT grounding** — every number/label in the widget must equal what's in `<RESPONSE>`.
+- **Decline** — if a requested chart kind isn't supported, say so and offer supported ones.
+- **action_row = visuals-only** — buttons only redraw the *current* data as another kind.
+
+The user message is just history + the question (no data backend, no tools).
+
+### 2. Synthesizer decides + generates (one LLM call)
+After writing the `<RESPONSE>` text, the model:
+1. **WARRANT** — is a visual helpful, do I have real data, is there a supported kind?
+   - no data → say so, empty widget · unsupported kind → decline · not worth it → text only.
+2. **SELECT KIND** — match the data shape to a kind in the menu (here: categorical
+   comparison → `bar`; an explicit request wins if supported).
+3. **FILL THE SHAPE** — populate that kind's keys with the **same** numbers used in `<RESPONSE>`.
+4. **EMIT:**
+```json
+<RESPONSE>
+In FY2024, NVIDIA's revenue was led by Data Center at $47.5B, Gaming $10.4B,
+Professional Visualization $1.6B, and Automotive $1.1B.
+</RESPONSE>
+<WIDGET>
+{"version":"1.0","layout":[
+  {"type":"text","content":"FY2024 revenue by segment (USD B)."},
+  {"type":"chart","title":"NVIDIA FY2024 Revenue by Segment",
+   "chart":{"kind":"bar","x_label":"Segment","y_label":"USD B",
+     "x_categories":["Data Center","Gaming","Professional Visualization","Automotive"],
+     "series":[{"name":"FY2024","values":[47.5,10.4,1.6,1.1]}]}},
+  {"type":"action_row","buttons":[
+     {"label":"Show as treemap"},{"label":"View as horizontal bars"}]}
+]}
+</WIDGET>
+```
+
+### 3. Parse + validate against the registry (`combined_prompt.py`, deterministic)
+`parse_combined_output` splits RESPONSE/WIDGET → `_dispatch_json_mode_widget`:
+- normalize type aliases (`_TYPE_ALIASES`), keep only `_BLOCK_TYPES`
+- per block `_block_is_renderable` → charts checked by `_chart_has_data`
+  (kind in registry **and** the data-bearing key present)
+- off-menu / no-data blocks are **dropped** (no empty cards)
+- returns `widget_schema` (JSON) + `widget_html=""` (the HTML path does not exist)
+
+### 4. Stream to the UI (SSE)
+`strategy → response_delta → widget_delta → done`. While streaming, the response text is
+run through `cleanAssistantText`/`stripLeakedJson` (no raw JSON/ASCII ever shows), and the
+partial widget renders **block-by-block** via the salvage parser (the chart appears the
+moment its JSON block closes).
+
+### 5. Render with your components (`WidgetRegistryRenderer.vue`)
+`parseLayout` (full parse → salvage → drop empty charts) → for each block:
+```
+resolveWidget("text")       → TextBlock
+resolveWidget("chart")      → ChartBlock → WidgetSchemaChart → buildEChartsOption() → ECharts <div>
+resolveWidget("action_row") → ActionRow (clickable → re-prompts the same data)
+```
+`<component :is>` mounts real Vue components inline. **No iframe, no HTML, no CDN.**
+
+### One-line summary
+```
+widget-registry.json
+  → build_json_widget_rule() → "menu" in the prompt
+  → synthesizer: WARRANT? → pick KIND → fill SHAPE with real values → emit <WIDGET>{json}
+  → validate against registry (drop off-menu/no-data; html="")
+  → SSE stream → WidgetRegistryRenderer → resolveWidget(type) → <component :is> → components / ECharts
+```
+
+---
+
+## Guarantees (by design)
+- **Components only** — everything renders via `<component :is>`; no iframe/HTML/CDN libs.
+- **Registry is the single source** — generate, validate, render can't drift.
+- **No raw JSON, no ASCII art, no mock data, no empty cards** ever reach the UI.
+- **Decline honestly** — unsupported chart type or missing data → say so, render nothing.
+- **The model can only use plots it can actually draw** (the menu), and only with real data.
+
+---
+
+## Extras
+- **HTML export** (`lib/exportWidgetHtml.ts`): deterministic `JSON → self-contained
+  interactive HTML` using the **same** ECharts option builder (no LLM). Charts stay
+  interactive offline (ECharts via CDN; `echarts-gl` added only when a 3D chart is present).
+- **Live block-by-block rendering** while streaming.
+- **Clickable action buttons** that re-prompt (visuals-only).
+
+## Part A (for context)
+A per-user Thompson-Sampling bandit (`backend/engine.py`) selects a text strategy from
+`strategies.json` using a context feature vector (`x ∈ ℝ¹⁰`). It learns from explicit
+(👍/👎 → `/api/rate`) and implicit (next-message sentiment) reward. It shapes only the
+`<RESPONSE>` text — never the widget.

vivek/README.md

@@ -4,33 +4,47 @@ app_port: 7860
 ---
 # Adaptive Presentation Engine — Demo
 
-A web demo of the Contextual Hierarchical Bayesian Architecture pipeline.
+A chat app where Claude answers a question **and** generates an interactive widget for it.
+Widgets are built **only from the app's own UI components** (a registry), as JSON — **no
+LLM-generated HTML, no iframe, no external chart libraries**. Charts render with bundled
+ECharts. A per-user Thompson-Sampling bandit adapts the prose-answer style independently.
 
-## Project structure (modular layout)
+> **Architecture:** see [`ARCHITECTURE.md`](./ARCHITECTURE.md) for the full registry →
+> prompt-menu → synthesizer → validate → components pipeline (Part B / visualization).
+
+## Project structure
 
 ```
 vivek/
-├── frontend/           # UI assets
-│   ├── index.html      # Single-page app (chat, widgets, posterior viz)
-│   └── README.md       # Frontend documentation
-├── backend/            # Python API and logic
-│   ├── config.py       # Env vars, LLM modes, Thompson Sampling params
-│   ├── server.py       # HTTP server, API routes, serves frontend at GET /
-│   ├── llm.py          # Anthropic and OpenAI-compatible LLM calls
-│   ├── engine.py       # Bayesian engine (Thompson Sampling)
-│   ├── widget_prompt.py
-│   ├── combined_prompt.py
-│   └── primitives.json # Strategy definitions
-├── app.py              # Entry point
+├── frontend-vue/                 # Vue 3 + Vite + TypeScript SPA (the live UI)
+│   ├── src/
+│   │   ├── widget-registry.json  # SINGLE SOURCE: block types + 33 chart kinds + data shapes
+│   │   ├── lib/widgetRegistry.ts # type → Vue component map (RENDER)
+│   │   ├── lib/echartsOption.ts  # shared ECharts option builder (live render + HTML export)
+│   │   ├── lib/exportWidgetHtml.ts # deterministic widget → standalone interactive HTML
+│   │   ├── components/WidgetRegistryRenderer.vue  # parses widget JSON → <component :is>
+│   │   ├── components/WidgetSchemaChart.vue       # ECharts chart component
+│   │   └── components/widgets/*.vue               # TextBlock, KpiRow, ChartBlock, ...
+│   └── dist/                     # built SPA (served by the backend in prod)
+├── backend/
+│   ├── config.py                 # env, LLM modes, bandit params, strategy loading
+│   ├── server.py                 # FastAPI: auth, /api/chat[_stream], /api/rate, serves SPA
+│   ├── llm.py                    # Anthropic + OpenAI-compatible calls
+│   ├── engine.py                 # Thompson-Sampling bandit (text strategy)
+│   ├── combined_prompt.py        # builds the combined prompt; registry → menu; validation
+│   ├── db.py / auth.py / utils.py
+├── strategies.json               # bandit text strategies (admin-manageable)
+├── app.py                        # entry point
 ├── requirements.txt
-├── .env.example        # Template for API keys (copy to .env)
-└── .env                # Your keys (gitignored)
+├── .env.example                  # template (copy to .env; .env is gitignored)
+└── ARCHITECTURE.md
 ```
 
 ## What it shows
-- **Live strategy selection** via Thompson Sampling over the Bayesian posterior
+- **Components-only widgets** — 9 block types + 33 chart kinds, all from the registry
+- **Live strategy selection** via Thompson Sampling (text style only)
 - **Posterior updating in real-time** as you rate responses (👍 / 👎)
-- **Feature vector** used for each inference
+- **Feature vector** (`x ∈ ℝ¹⁰`) used for each inference
 - **Per-strategy expected reward** estimates that evolve with each interaction
 
 ---
@@ -79,7 +93,7 @@ http://localhost:5051   # or PORT from env (Docker uses 7860)
 ## Pipeline stages shown
 | Stage | What the demo shows |
 |---|---|
-| Feature extraction | Feature vector panel (x ∈ ℝ⁸) |
+| Feature extraction | Feature vector panel (x ∈ ℝ¹⁰) |
 | Thompson Sampling | Expected reward % per strategy |
 | LLM rendering | Live response with strategy label |
 | Reward observation | 👍/👎 buttons |

vivek/UpdatedReadme.md

@@ -1,5 +1,11 @@
 # Vivek: Adaptive Presentation Engine — Complete Reference
 
+> ⚠️ **Legacy/partial.** Parts of this long reference predate the components-only widget
+> refactor (it still references HTML/iframe widgets, `index.html` SPA, etc.). For the
+> **current** widget pipeline (registry → prompt menu → synthesizer → validate → Vue
+> components / ECharts, no HTML/iframe), see [`ARCHITECTURE.md`](./ARCHITECTURE.md). The
+> bandit/Part-A sections below remain broadly accurate.
+
 A professional, modular backend demonstrating Bayesian strategy selection and real-time posterior updating. This app learns user preferences and adapts its response format (bullet points, prose, questions, etc.) based on observed rewards.
 
 ---