feat: expand model library from 12 to 27 models across 8 families

docs/superpowers/specs/2026-05-26-enhanced-web-calculator-design.md

@@ -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)
+

openspec/changes/add-hardware-presets/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-28

openspec/changes/add-hardware-presets/design.md

@@ -0,0 +1,49 @@
+## Context
+
+The web calculator (`website/calculator.html`) currently defines GPU hardware in two places:
+1. `GPU_SPECS` — a minimal array used by the Quick-Start Wizard with only `id`, `name`, and `memory_gb`
+2. `PRESETS` — two full deployment configurations, both using H20 GPUs
+
+Users on A100, H100, L40S, or other GPUs must manually fill every deployment field. The wizard picks a GPU type but doesn't know typical machine topologies or baseline TPS, so it fills in generic defaults (e.g., `baseline_per_card_tps: 1.0`).
+
+## Goals / Non-Goals
+
+**Goals:**
+- Enrich `GPU_SPECS` with typical topology, baseline TPS, and common machine configurations
+- Add model×hardware deployment presets covering the most common combinations
+- Add a GPU hardware selector to the main Deployment form (not just the wizard)
+- Auto-fill deployment fields when a GPU is selected from either the wizard or the main form
+
+**Non-Goals:**
+- Custom/user-defined GPU profiles (future scope)
+- Benchmark-validated TPS numbers (we use reasonable estimates, clearly labeled)
+- Changes to the calculation engine
+
+## Decisions
+
+**1. Enrich GPU_SPECS rather than creating a separate HARDWARE_LIBRARY**
+
+Extend the existing `GPU_SPECS` array with additional fields. This avoids a second data structure and keeps the wizard integration simple.
+
+New fields per GPU entry:
+- `typical_cards_per_machine`: common topology (e.g., 8 for H100 DGX, 1 for L40S workstations)
+- `baseline_tps_per_card`: estimated decode TPS without caching (rough, labeled as estimate)
+- `max_cards_per_machine`: upper bound for validation
+
+Alternative: Separate `HARDWARE_PROFILES` object — rejected because it would duplicate memory_gb and require cross-referencing.
+
+**2. Model×Hardware deployment presets as a generated combination, not a static list**
+
+Instead of manually writing N×M preset entries, create a `DEPLOYMENT_TEMPLATES` array keyed by GPU id. When a user selects both a model preset and a GPU type, the deployment fields auto-fill by combining model weight requirements with GPU capabilities.
+
+Alternative: Static preset matrix — rejected because it scales as O(models × GPUs) and becomes hard to maintain.
+
+**3. GPU selector in Deployment form section**
+
+Add a `<select>` dropdown at the top of the Deployment card. Selecting a GPU auto-fills `machine_spec`, `gpu_memory_gb_per_card`, `cards_per_machine`, and `baseline_per_card_tps`. User can still override any field.
+
+## Risks / Trade-offs
+
+- **Baseline TPS estimates may mislead users** → Label clearly as "estimated baseline, actual performance varies by workload and framework". Use conservative values.
+- **GPU market moves fast, specs become stale** → Keep the data structure simple so adding a new GPU is a 3-line change. Add a comment with date of last update.
+- **cards_per_machine varies by deployment** → Use `typical_cards_per_machine` as a default but don't lock it — the field remains editable.

openspec/changes/add-hardware-presets/proposal.md

@@ -0,0 +1,23 @@
+## Why
+
+The web calculator's deployment presets only include H20 GPU configurations. Users deploying on A100, H100, L40S, or other hardware must manually configure every deployment field. The wizard has a GPU type dropdown but lacks per-GPU baseline TPS estimates and typical machine topologies, making the "guided setup" less useful for non-H20 hardware.
+
+## What Changes
+
+- Expand `GPU_SPECS` with richer metadata: typical cards_per_machine, baseline TPS per card, common machine labels
+- Add full deployment presets combining each model with popular GPU configurations (e.g., Llama 3.1 70B on 4×A100-80G, Qwen3-27B on 1×H100)
+- Update the wizard's Step 2 (Hardware Configuration) to auto-fill deployment fields from enriched GPU_SPECS
+- Add GPU selection dropdown to the main Deployment form section (not just the wizard) so users can pick hardware without going through the wizard
+
+## Capabilities
+
+### New Capabilities
+- `hardware-presets`: Enriched GPU hardware definitions with per-GPU metadata (memory, typical topology, baseline TPS) and model×hardware deployment preset combinations
+
+### Modified Capabilities
+
+## Impact
+
+- `website/calculator.html`: GPU_SPECS data, PRESETS object, wizard Step 2, Deployment form section
+- No backend changes — all client-side
+- No calculation engine changes — deployment parameters are input-only

openspec/changes/add-hardware-presets/specs/hardware-presets/spec.md

@@ -0,0 +1,52 @@
+## ADDED Requirements
+
+### Requirement: Enriched GPU hardware definitions
+The system SHALL define GPU hardware entries in `GPU_SPECS` with the following fields: `id`, `name`, `memory_gb`, `typical_cards_per_machine`, `max_cards_per_machine`, and `baseline_tps_per_card`.
+
+The system SHALL include at minimum these GPU types:
+- H20 (96GB)
+- H100 (80GB)
+- H100 NVL (94GB)
+- H200 (141GB)
+- A100 (80GB)
+- A100 (40GB)
+- A800 (80GB)
+- L40S (48GB)
+- L20 (48GB)
+
+#### Scenario: GPU entry has all required fields
+- **WHEN** a GPU entry exists in `GPU_SPECS`
+- **THEN** it SHALL have `id`, `name`, `memory_gb`, `typical_cards_per_machine`, `max_cards_per_machine`, and `baseline_tps_per_card` fields
+
+#### Scenario: All listed GPU types are present
+- **WHEN** the page loads
+- **THEN** `GPU_SPECS` SHALL contain entries for H20, H100, H100 NVL, H200, A100 (80GB), A100 (40GB), A800, L40S, and L20
+
+### Requirement: GPU selector in Deployment form
+The system SHALL provide a GPU hardware dropdown in the Deployment form section. Selecting a GPU SHALL auto-fill `machine_spec`, `gpu_memory_gb_per_card`, `cards_per_machine`, and `baseline_per_card_tps` from the selected GPU's metadata.
+
+#### Scenario: User selects GPU from deployment dropdown
+- **WHEN** user selects "H100 (80GB)" from the GPU dropdown in the Deployment form
+- **THEN** `machine_spec` SHALL be set to "h100", `gpu_memory_gb_per_card` to 80, `cards_per_machine` to 8, and `baseline_per_card_tps` to the H100's defined baseline
+
+#### Scenario: User selects Custom GPU
+- **WHEN** user selects "Custom" from the GPU dropdown
+- **THEN** no deployment fields SHALL be auto-filled and all fields SHALL remain editable
+
+### Requirement: Wizard uses enriched GPU data
+The wizard's Step 2 (Hardware Configuration) SHALL use the enriched `GPU_SPECS` to auto-fill `cards_per_machine` and `baseline_per_card_tps` in addition to the existing `gpu_memory_gb_per_card`.
+
+#### Scenario: Wizard GPU selection fills topology
+- **WHEN** user selects "A100 (80GB)" in the wizard's GPU type dropdown
+- **THEN** the wizard SHALL use `typical_cards_per_machine` from GPU_SPECS when computing deployment defaults
+
+### Requirement: Model×Hardware deployment presets
+The system SHALL provide combined deployment presets that pair popular models with common GPU configurations. The PRESETS object SHALL include configurations for at least 3 different GPU types (not just H20).
+
+#### Scenario: User selects a non-H20 preset
+- **WHEN** the preset dropdown includes "Llama 3.1 70B (8×A100-80G)"
+- **THEN** selecting it SHALL fill all model profile and deployment fields with A100-specific values
+
+#### Scenario: Preset uses correct GPU-specific values
+- **WHEN** a preset using H100 GPUs is loaded
+- **THEN** `gpu_memory_gb_per_card` SHALL be 80, `machine_spec` SHALL be "h100", and `baseline_per_card_tps` SHALL match the H100 entry in GPU_SPECS

openspec/changes/add-hardware-presets/tasks.md

@@ -0,0 +1,19 @@
+## 1. Enrich GPU Hardware Data
+
+- [x] 1.1 Expand `GPU_SPECS` array with new fields (`typical_cards_per_machine`, `max_cards_per_machine`, `baseline_tps_per_card`) and add H100 NVL, H200, A800, L20 entries alongside existing GPUs
+- [x] 1.2 Update wizard Step 2 to use enriched GPU data: auto-fill `cards_per_machine` from `typical_cards_per_machine` and show `baseline_tps_per_card` in suggestion text
+
+## 2. GPU Selector in Deployment Form
+
+- [x] 2.1 Add GPU hardware `<select>` dropdown to the Deployment form card (above existing fields), populated from `GPU_SPECS` with a "Custom" option
+- [x] 2.2 Wire dropdown change handler to auto-fill `machine_spec`, `gpu_memory_gb_per_card`, `cards_per_machine`, and `baseline_per_card_tps`
+
+## 3. Model×Hardware Deployment Presets
+
+- [x] 3.1 Add deployment presets combining models with non-H20 GPUs (at least: Llama 3.1 70B on 8×A100-80G, Qwen2.5-72B on 8×H100, Mistral 7B on 1×L40S) to the PRESETS object
+- [x] 3.2 Update the preset `<select>` dropdown to list the new model×hardware combinations
+
+## 4. Validation
+
+- [x] 4.1 Run JS parity validation (`node tests/validate_js_parity.mjs`) to confirm the calculation engine is unchanged
+- [x] 4.2 Verify page loads and new GPU selections correctly fill deployment fields