Skip to content

feat: enhance web calculator with model library, wizard, charts and export #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
stmatengss wants to merge 4 commits into
base: main
Choose a base branch
from
Open

feat: enhance web calculator with model library, wizard, charts and export #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c03a2d0
feat: add interactive web calculator for multi-agent heuristic analysis
stmatengss May 25, 2026
a2ac0af
docs: add design spec for enhanced web calculator
stmatengss May 25, 2026
08b1a11
docs: update model preset list with confirmed architectures
stmatengss May 26, 2026
c0a89d5
feat: enhance web calculator with model library, wizard, charts, expo…
stmatengss May 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
248 changes: 248 additions & 0 deletions docs/superpowers/specs/2026-05-26-enhanced-web-calculator-design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,248 @@
# Enhanced KVCache Web Calculator — Design Spec

## Overview

Redesign the web calculator (`website/calculator.html`) into a comprehensive, guided KVCache sizing tool that serves platform architects, ML engineers, and non-technical stakeholders equally well. All computation remains fully client-side (no backend).

## Goals

- Let users go from "I don't know where to start" to "I have a capacity plan" in under 60 seconds via the Quick-Start Wizard
- Provide pre-built model profiles for 10+ popular models so users never need to look up layer counts
- Enable side-by-side "what-if" scenario comparison with delta highlighting
- Add TPS-vs-machines curves and sensitivity analysis beyond the current hit-rate chart
- Allow exporting and sharing results (markdown, PNG, JSON, URL hash)
- Improve input validation, documentation (tooltips), and responsive layout

## Non-Goals

- No server-side computation or APIs
- No trace-based oracle analysis (future scope)
- No multi-language / i18n for this iteration
- No database or user accounts

---

## Component 1: Model Preset Library

### Data Structure

```javascript
const MODEL_LIBRARY = [
{
id: "qwen3-27b",
family: "Qwen",
name: "Qwen3-27B (MLA)",
params: {
n_layers: 64, kv_cache_layer_count: 16, n_kv_heads: 4,
head_dim: 256, dtype_bytes: 2, parameter_count: 27781419504,
weight_dtype_bytes: 2, block_size: 16
},
notes: "Multi-head Latent Attention — only 16 KV layers"
},
// ... 10+ models
];
```

### Models to Include


| Family | Model | Params (B) | KV Heads | Head Dim | KV Layers | Architecture Note |
| -------- | ---------------- | ---------- | -------- | -------- | --------- | ---------------------------------------------------------------------------------- |
| Qwen | Qwen3-27B | 27.8 | 4 | 256 | 16 | MLA |
| Qwen | Qwen2.5-72B | 72.7 | 8 | 128 | 80 | GQA |
| Qwen | Qwen2.5-7B | 7.6 | 4 | 128 | 28 | GQA |
| Llama | Llama 3.1 70B | 70.6 | 8 | 128 | 80 | GQA |
| Llama | Llama 3.1 8B | 8.0 | 8 | 128 | 32 | GQA |
| Llama | Llama 3.3 70B | 70.6 | 8 | 128 | 80 | GQA |
| DeepSeek | DeepSeek-V2 236B | 236 | 128 | 128 | 60 | MLA + MoE (compressed KV — use effective n_kv_heads=16, head_dim=512 for kv_bytes) |
| DeepSeek | DeepSeek-V3 671B | 671 | 128 | 128 | 61 | MLA + MoE (compressed KV — same note) |
| Mistral | Mixtral 8x22B | 141 | 8 | 128 | 56 | MoE, GQA |
| Mistral | Mistral 7B | 7.2 | 8 | 128 | 32 | GQA |
| GLM | GLM-4 9B | 9.4 | 2 | 128 | 40 | MQA |
| Yi | Yi-1.5 34B | 34.4 | 8 | 128 | 60 | GQA |


### UX

- Dropdown at top of Model Profile section, grouped by family
- Type-ahead filter for quick search
- Selecting a model fills all model profile fields
- Fields remain editable after preset selection (badge shows "Modified" if changed)
- "Custom" option leaves fields empty for manual entry

---

## Component 2: Scenario Comparison Mode

### Interaction Flow

1. User clicks "Compare" button (top of results panel)
2. Current configuration snapshots as **Scenario A** (locked, grayed form or collapsed summary)
3. Form becomes **Scenario B** (editable, highlighted border)
4. Results panel splits into two columns: A (frozen) | B (live-updating)
5. Delta row below each metric shows the difference (green = improvement, red = regression)
6. User can click "Swap" to make B the new A, or "Exit Compare" to return to single mode

### Delta Display

```
┌─────────────────────────┬─────────────────────────┐
│ Scenario A (Base) │ Scenario B (What-if) │
├─────────────────────────┼─────────────────────────┤
│ Strict Hit: 80.30% │ Strict Hit: 87.45% │
│ │ Δ +7.15pp ▲ │
│ LRU Hit: 79.26% │ LRU Hit: 84.12% │
│ │ Δ +4.86pp ▲ │
│ Min Machines: 4 │ Min Machines: 2 │
│ │ Δ -2 ▼ (better) │
└─────────────────────────┴─────────────────────────┘
```

### What to Compare

- All summary metrics (hit rates, TPS gains, saturation capacities)
- Tier table rows (matched by tier label)
- Chart overlay (both scenarios on same chart, A as dashed line)

---

## Component 3: Quick-Start Wizard

### Step 1 — Model Selection

- Shows the model preset library as a card grid (logo/icon per family)
- Click to select; shows key stats (param count, KV bytes/token)
- "Skip — I'll configure manually" link at bottom

### Step 2 — Hardware Configuration

- **GPU type** dropdown: H20 (96GB) / A100 (80GB) / A100 (40GB) / H100 (80GB) / L40S (48GB)
- **GPU count**: number input (1–128)
- **Auto-suggest TP/PP**: based on model size vs. GPU memory, recommend a TP/PP split
- Rule: if model_weights_gb > 0.8 × gpu_memory_gb, suggest TP = ceil(model_weights_gb / (0.7 × gpu_memory_gb))
- User can override TP/PP

### Step 3 — Workload Template

- **Template** dropdown with presets:
- **Multi-agent chat** (default): concurrent_agents=2048, shared_prefix=4096, avg_turns=8, avg_new_tokens=4096, private_window=65536
- **RAG pipeline**: concurrent_agents=512, shared_prefix=8192, avg_turns=2, avg_new_tokens=2048, private_window=16384
- **Code assistant**: concurrent_agents=1024, shared_prefix=16384, avg_turns=6, avg_new_tokens=8192, private_window=32768
- **Light chatbot**: concurrent_agents=4096, shared_prefix=2048, avg_turns=4, avg_new_tokens=1024, private_window=8192
- **Custom**: all fields editable
- Each template shows a 1-line description

### Completion

- "Calculate" button closes wizard, opens full calculator with all fields pre-filled
- Results appear immediately
- Wizard state not persistent — can be re-opened from a "Guided Setup" button

---

## Component 4: Enhanced Charts

### Chart A: Hit Rate vs. Capacity (existing, enhanced)

- Keep current line chart
- Add: shaded area between strict-prefix and LRU (shows "policy gap")
- Add: vertical annotation line at current HBM capacity
- In comparison mode: overlay Scenario A as dashed lines

### Chart B: TPS vs. Machine Count (new)

- X-axis: number of machines (1 to 2× current)
- Y-axis: cluster TPS capacity
- Lines: strict-prefix policy, LRU policy
- Horizontal dashed line: target TPS
- Intersection point highlighted: "minimum machines needed"

### Chart C: Parameter Sensitivity (new)

- Bar chart or tornado chart
- Shows: if each parameter changes by ±20%, how much does HBM hit rate change?
- Parameters tested: concurrent_agents, shared_prefix, avg_turns, private_window, zipf_s, lru_efficiency
- Helps users understand which lever matters most

---

## Component 5: Export & Share

### Export Options

1. **Copy as Markdown** — button copies the results table + summary as a markdown-formatted text block to clipboard
2. **Download Chart (PNG)** — per-chart download button using Chart.js `toBase64Image()`
3. **Download Results (JSON)** — full analysis output including all tier rows, summary, and input config
4. **Share via URL** — encode full configuration in URL hash:
```
calculator.html#config=eyJtb2RlbF9wcm9maWxlIjp7...}
```
- Base64-encoded JSON of all form parameters
- Loading page with hash auto-fills all fields and runs calculation
- Length limit: if config > 2KB encoded, offer "Copy shareable link" that uses compression (lz-string)

### UI Placement

- Export toolbar above results panel: `[📋 Markdown] [📊 PNG] [📄 JSON] [🔗 Share]`
- Tooltip explains each on hover

---

## Component 6: UX Polish

### Input Validation


| Rule | Display |
| ------------------------------------------------------------ | ------------------------------------------------------ |
| tp_size × pp_size must divide evenly into n_kv_heads | Red border + "TP×PP must divide n_kv_heads" |
| accelerator_count must be divisible by cards_per_machine | Red border + "GPU count must be N × cards_per_machine" |
| Numeric fields must be > 0 | Red border + "Must be positive" |
| parameter_count unrealistically small (< 1B for > 32 layers) | Yellow warning |


### Tooltips

Every input field gets a `title` attribute with a 1-line explanation:

- `concurrent_agents`: "Number of simultaneous agent sessions sharing the cache pool"
- `shared_prefix_tokens`: "System prompt tokens shared identically across all agents"
- etc.

### Responsive Layout

- ≥1200px: side-by-side (form left, results right) — current layout
- 800–1200px: stacked (form top, results bottom), form sections in 2-column grid
- <800px: single column, accordion for form sections

### Dark/Light Mode

- Toggle button in header (sun/moon icon)
- Uses CSS custom properties (already in place) — just swap the `:root` values
- Persist preference in `localStorage`

---

## File Structure

All changes remain in `website/calculator.html` (single file, no build step). The embedded JS grows but stays under 2000 LOC total. If it exceeds this, split into:

- `website/calculator.html` (HTML + CSS)
- `website/js/engine.js` (calculation engine)
- `website/js/models.js` (preset library)
- `website/js/ui.js` (interactivity)

For now, keep everything in one file for simplicity.

---

## Implementation Priority

1. Model Preset Library (immediate value, low complexity)
2. Quick-Start Wizard (onboarding, medium complexity)
3. Enhanced Charts — TPS vs. Machines (high value, low complexity)
4. Export & Share (medium value, low complexity)
5. Scenario Comparison (high value, high complexity)
6. UX Polish (ongoing, can be incremental)
7. Sensitivity Chart (nice-to-have, medium complexity)

2 changes: 2 additions & 0 deletions openspec/changes/add-web-ui/.openspec.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-05-25
67 changes: 67 additions & 0 deletions openspec/changes/add-web-ui/design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
## Context

The KVCache Upper Bound Oracle has a Python-based CLI that runs heuristic analysis for multi-agent KVCache sizing. There is already a `website/index.html` results dashboard that visualizes pre-computed JSON outputs using Chart.js. The goal is to add an interactive calculator page that performs the same `estimate-multi-agent` analysis entirely in the browser, requiring no backend.

The core calculation (`_hit_rate_for_capacity_tokens`, `_shape_fraction`, `_generalized_harmonic`, TPS gain) is pure math with no I/O dependencies — ideal for client-side porting.

## Goals / Non-Goals

**Goals:**
- Fully client-side calculator: zero backend, works from any static hosting (GitHub Pages, file://)
- Parity with `estimate-multi-agent` CLI output for hit rates, TPS gains, and capacity planning
- Preset configurations loadable from dropdown (matching `configs/public_multi_agent_*.json`)
- All parameters editable with immediate recalculation
- Visual output: results table + Chart.js charts for hit rate curves

**Non-Goals:**
- Porting the trace-based `analyze-buckets` command (requires large JSONL data files)
- Porting the `calibrate-multi-agent` command (requires trace I/O)
- Server-side rendering or API endpoints
- Mobile-first design (desktop-first, responsive as bonus)
- i18n for the calculator page (English only for v1)

## Decisions

### 1. Single HTML file with embedded JS/CSS

**Choice**: One self-contained `website/calculator.html` file.

**Rationale**: Matches the existing `website/index.html` pattern. No build step, no bundler, trivially deployable. The calculation logic is ~200 lines of JS — not enough to warrant modules.

**Alternatives considered**:
- Separate `.js`/`.css` files: adds complexity for marginal benefit at this scale
- React/Vue SPA: massive overkill for a form + table + chart

### 2. Port only the heuristic math to JavaScript

**Choice**: Re-implement `_hit_rate_for_capacity_tokens`, `_shape_fraction`, `_generalized_harmonic`, `tps_gain`, `cluster_capacity_tps`, and the saturation/capacity helpers.

**Rationale**: These are pure functions with clear inputs/outputs. The Python code is the reference implementation; the JS port can be validated against known config outputs.

**Alternatives considered**:
- Pyodide (Python in WASM): 10MB+ download, slow startup — unacceptable for an interactive calculator
- WebAssembly compiled from Python: complex toolchain, same startup penalty

### 3. Preset configs embedded as JSON objects in the HTML

**Choice**: Embed 2-3 preset configs (matching `configs/public_multi_agent_*.json`) as JS objects inside the calculator page.

**Rationale**: Avoids fetch/CORS issues when opening from `file://`. Keeps the page fully self-contained. Configs are small (<2KB each).

### 4. Chart.js for visualization (same as existing dashboard)

**Choice**: Use Chart.js (already loaded by the existing dashboard via CDN).

**Rationale**: Consistency with existing page. Already proven to work. Line chart showing hit rate vs. capacity GB is the primary visualization.

### 5. Real-time recalculation on parameter change

**Choice**: Debounced recalculation (100ms) triggered on any input change.

**Rationale**: The calculation is O(n) where n = zipf_population_blocks (max ~4096 iterations for harmonic sum). This completes in <5ms on any modern device — no need for web workers or lazy evaluation.

## Risks / Trade-offs

- **Numerical drift**: JS uses float64 exclusively vs Python's float64. Risk is minimal for this use case (hit rates are reported to 2-4 decimal places). → Mitigation: validate JS output against Python for all preset configs.
- **Maintenance burden**: Two implementations of the same math (Python + JS). → Mitigation: the JS port is small (~200 LOC), and the Python reference is authoritative. Add a comment in the JS referencing the Python source file.
- **Preset staleness**: If configs change, the embedded presets in HTML diverge. → Mitigation: document which config files each preset mirrors.
26 changes: 26 additions & 0 deletions openspec/changes/add-web-ui/proposal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
## Why

The KVCache Upper Bound Oracle currently requires Python installation and CLI usage to estimate cache hit rates and capacity planning. A browser-based interactive calculator would let users experiment with parameters (model profile, deployment config, multi-agent heuristic settings) instantly without any backend or installation — making the tool accessible to product managers, architects, and anyone evaluating KVCache sizing.

## What Changes

- Add a new interactive web page (`website/calculator.html`) that runs the full `estimate-multi-agent` heuristic analysis entirely in the browser using JavaScript
- Port the core calculation logic (hit rate curves, TPS gain estimation, capacity planning) from Python to JavaScript
- Provide preset configurations (e.g., Qwen3-27B on H20) selectable via dropdown, with all parameters editable
- Display results as interactive tables and charts (hit rate vs. capacity, TPS gains per tier)
- Link the new calculator page from the existing results dashboard

## Capabilities

### New Capabilities
- `browser-calculator`: Interactive browser-based KVCache heuristic calculator that ports the `estimate-multi-agent` analysis to client-side JavaScript, with parameter controls and visual result display

### Modified Capabilities
<!-- No existing spec-level requirements are changing -->

## Impact

- **New files**: `website/calculator.html` (single-page app with embedded JS/CSS)
- **Modified files**: `website/index.html` (add navigation link to calculator)
- **Dependencies**: Chart.js (already used by existing dashboard), no server-side dependencies
- **No breaking changes**: existing CLI and Python library behavior is unchanged
Loading