VRAM Calculator v3: YaRN coherence ladder, real spec enum, live UI + graphs

Pre-flight VRAM predictor + llama-server command-builder. See PLAN.md for
the full design spine from the grilling session.

Core logic:
- yarn.py: add yarn_coherence_warnings + extension_ratio (monotonic ladder:
<=2x fine, >2-8x tail degradation, >=8x incoherent/not-recommended), wired
into estimate() warnings.
- report.py: command_preview emits --fit on --fit-target <margin MiB>
(complement path; margin from smallest GPU's VRAM share).
- draft.py: rewrite spec surface to the real llama.cpp --spec-type enum
(draft-simple/eagle3/mtp/dflash + ngram-*). Split weightless (n-gram,
zero VRAM, no -md) vs weighted (draft, weights+KV, full --spec-draft-*
namespace). Fixes invalid --spec-type draft shipped previously.
- quant.py: nvfp4 documented as commented placeholder (VERIFY before ship);
not selectable as a floor until a verified bpw is sourced.

Tests: 67 passing (real-enum spec, YaRN coherence ladder, --fit/--fit-target,
weightless/weighted branches).

UI (app.py): two-phase (fetch once -> live estimate() recompute on every
change) + two matplotlib graphs (VRAM-vs-n_ctx by quant; VRAM-vs-quant with
quality/bpw color) + "assumes your build supports the chosen quant" caveat.

Co-Authored-By: Claude <noreply@anthropic.com>

.gitignore

@@ -18,4 +18,8 @@ venv/
 # OS / editor
 .DS_Store
 .idea/
-.vscode/
+.vscode/
+
+# Local Claude Code tooling
+.claude/
+skills-lock.json

PLAN.md

@@ -0,0 +1,141 @@
+# VRAM Calculator — v1 Plan
+
+Pre-flight VRAM predictor + `llama-server` command-builder. Single-GPU and
+mixed-GPU. Hero use case: "I want 1M context on a model trained for 262k —
+give me the command and tell me it'll still be coherent."
+
+This document is the spine agreed in the /grilling session. The grilling is
+closed; everything below is decided.
+
+## Objective
+
+**Maximize quality at a VRAM ceiling.** Quality proxy = highest-bpw quant
+that fits. Floor = the 4-bit class (q4_0 / rocmfp4 / nvfp4, ~4.0+ bpw).
+Sub-4-bit quants (2-bit/3-bit family) are offered only on explicit user
+override and flagged "you asked for it." Backend-agnostic.
+
+## The fit loop (core)
+
+```
+target  = user_target_n_ctx
+yarn    = auto_configure_yarn(training_ctx, target)   # rope_freq_scale
+fit     = max_context(arch, floor_quant, gpus)       # hard VRAM ceiling
+result  = min(target, fit)
+if fit < target:  present "best you can do = fit, because <reason>"
+if extension_ratio crosses ladder: warn (never hard-block)
+```
+
+Says "no" cleanly when impossible at floor + hardware, and offers the
+floor-quant max_context as the honest fallback.
+
+## YaRN coherence ladder (warnings only, never a hard block)
+
+Monotonic — more extension always means same-or-more concern, never goes quiet:
+
+- **≤ 2× extension** — fine, no warning.
+- **> 2× up to 8×** — "expect some quality degradation at the tail."
+- **≥ 8× extension** — "likely incoherent at long range; not recommended."
+
+Source: YaRN paper behavior + community experience, not measured. Extension
+ratio = target_n_ctx / training_ctx (1.0 when target ≤ training or training
+unknown). Implemented as `yarn_coherence_warnings(training_ctx, target_ctx)`
+in `yarn.py`, surfaced in `estimate()` warnings and the UI.
+
+## Margin = the honesty knob
+
+`safety_margin_pct` is the user-facing "how scared am I" knob. **Complement
+path:** the predictor emits *fully explicit* flags (`-c`, `-ngl`, `-sm`,
+`-ts`, `-mg`, `-ctk`, `-ctv`, `--flash-attn`, YaRN flags) **plus**
+`--fit on --fit-target <margin MiB>`. Because everything is already explicit,
+runtime `--fit` is a no-op safety net — the user gets exactly what the
+predictor said. Our number *is* the guarantee, with the margin as the dial.
+Never use the word "guarantee" in UI copy; the margin is the honest version.
+
+## Speculative decoding — two branches (this is a bugfix)
+
+The shipped `--spec-type draft` is **invalid**. The real enum (from the
+llama.cpp server README) is:
+
+```
+none, draft-simple, draft-eagle3, draft-mtp, draft-dflash,
+ngram-simple, ngram-map-k, ngram-map-k4v, ngram-mod, ngram-cache
+```
+
+Rewrite the spec surface to this enum, then split the add-on flow:
+
+- **Weightless** (`ngram-*`): ~zero extra VRAM. Auto-offer when headroom
+  exists; no "acknowledge the tradeoff" checkbox (there's no VRAM tradeoff).
+- **Weighted** (`draft-simple` / `draft-eagle3` / `draft-mtp` /
+  `draft-dflash`): a draft model with weights + its own KV. Headroom-gated +
+  an acknowledge checkbox. Draft rides the main GPU. Emit the full
+  `--spec-draft-*` namespace (`-md`, `--spec-draft-ngl`, `--spec-draft-device`,
+  `--spec-draft-n-max`, `--spec-draft-p-min`, `--spec-draft-p-split`), not
+  the old `-md`-only stub.
+
+`draft-mtp` (a spec *type*) is distinct from `--mtp N` (MTP head count on
+the target). Keep both but emit the right flag for each.
+
+## Backend scope
+
+**Dropped.** Assume it runs. One displayed caveat: "fits in VRAM assuming
+your build supports the chosen quant." Keep the existing stock-build
+ROCmFP4/ROCmFPX incompatibility warning (that's not a backend issue — no
+stock build can read those tensor types at all).
+
+## Quarantined unverified data
+
+Do **not** block v1 on these:
+
+- **nvfp4** (llama.cpp PR #22196): not yet in `QUANT_BPW`. Add a provisional
+  row with a `# VERIFY before ship` comment once we have a verified
+  bits-per-weight; until then it's absent from the table and can't be
+  selected as a floor.
+- **dSpark** (#25167 / #25173 / DeepSeek-V4-Flash-DSpark): folds into the
+  existing draft-model VRAM path and emits `--spec-type draft-mtp`
+  provisionally. For a *predictor*, dSpark's VRAM cost is just
+  draft-weights + draft-KV, same as any MTP draft; the spec-type label only
+  affects the command string.
+- **Vulkan quant matrix:** dropped (consequence of dropping backends).
+
+## UI — two phases, two graphs
+
+1. **Fetch phase:** repo ID + HF token → `parse_hf_range` once → cache
+   `ModelArch`. Network happens here, once, never again.
+2. **Live phase:** everything is `estimate()` recompute on the cached arch
+   (microseconds). Context slider, quant selector, KV-dtype, GPU sizes,
+   margin. The recommended command updates live.
+3. **Graph 1:** VRAM vs `n_ctx`, one curve per quant — the context ceiling,
+   with the slider sitting on it.
+4. **Graph 2:** VRAM vs quant at fixed `n_ctx`, **with quality as
+   color/rank** — the cost+quality frontier (where "maximize quality at the
+   ceiling" becomes visible).
+
+## Implementation order
+
+Done:
+
+1. ✅ **`yarn.py`** — `yarn_coherence_warnings(training_ctx, target_ctx)` +
+   `extension_ratio`; wired into `yarn_warnings()` (and thus `estimate()`).
+2. ✅ **`report.py`** — emits `--fit on --fit-target <margin MiB>` via
+   `_fit_target_mib()` (margin from smallest GPU's VRAM share).
+3. ✅ **`draft.py` + `report.py`** — spec surface rewritten to the real
+   llama.cpp enum (`draft-simple`, `draft-eagle3`, `draft-mtp`,
+   `draft-dflash`, `ngram-*`); weightless (ngram, zero VRAM) vs weighted
+   (draft, weights+KV) split; `command_preview` emits `-md` + the full
+   `--spec-draft-*` namespace for weighted, only `--spec-type` for
+   weightless.
+4. ✅ **`quant.py`** — `nvfp4` documented as a commented placeholder with a
+   VERIFY note; not selectable as a floor until a verified bpw is sourced.
+5. ✅ **Tests** — 67 passing (real-enum spec tests, YaRN coherence-ladder
+   tests, `--fit`/`--fit-target` tests, weightless/weighted branch tests).
+6. ✅ **`app.py`** — two-phase UI (fetch once → live `estimate()` recompute
+   on every change), two graphs (VRAM-vs-n_ctx by quant; VRAM-vs-quant with
+   quality color), the "assumes your build supports the chosen quant"
+   caveat, and the sub-floor "you asked for it" warning. Syntax-checked;
+   graph math verified against presets (gradio not installable locally).
+
+## Out of scope for v1
+
+Per-backend quant compatibility matrices, MLX, Vulkan-specific quants,
+runtime auto-tuning (that's llama.cpp's `--fit`), measured perplexity/WikiText
+quality tables, throughput/token-per-second modeling.

app.py

@@ -1,15 +1,25 @@
 """llama.cpp VRAM Calculator — Hugging Face Space.
 
-A Gradio app that estimates VRAM usage for a Hugging Face GGUF model given
-quantization type, context length, KV cache options, YaRN context-extension
-parameters, MTP heads, and a multi-GPU budget. Architecture is auto-fetched
-from the GGUF header (range-read, no full download) with a manual-override
-tab and presets for offline use.
+A pre-flight VRAM predictor + llama-server command-builder. Hero use case:
+"I want N context on a model trained for less — give me the command and
+warn me about coherence." Two-phase UI:
+
+  1. Fetch phase (network, once): repo id + GGUF file -> parse_hf_range ->
+     cached ModelArch. Network happens here and never again.
+  2. Live phase (microseconds): every input change re-runs estimate() on the
+     cached arch; the command, breakdown, and graphs update live.
+
+Two graphs: VRAM-vs-n_ctx (one curve per quant, the context ceiling) and
+VRAM-vs-quant at fixed n_ctx (the cost+quality frontier, quality as color).
+See PLAN.md for the full design spine.
 """
 
 from __future__ import annotations
 
 import gradio as gr
+import matplotlib
+matplotlib.use("Agg")  # headless: render to PNG, no display needed
+import matplotlib.pyplot as plt
 from huggingface_hub import HfApi
 import spaces  # noqa: F401  — present so ZeroGPU detects a GPU-aware Space
 
@@ -29,7 +39,10 @@ from vramcalc import (
     min_gpu_setup,
     mmproj_bytes_from_tensors,
     auto_configure_yarn,
+    yarn_coherence_warnings,
+    extension_ratio,
 )
+from vramcalc.draft import SPEC_TYPES as REAL_SPEC_TYPES
 from vramcalc.presets import PRESETS, PRESET_NAMES
 
 
@@ -37,9 +50,18 @@ QUANT_CHOICES = list(QUANT_BPW.keys())
 CACHE_DTYPES = ["f16", "bf16", "f32", "q8_0", "q8_1", "q4_0", "q4_1", "q5_0", "q5_1"]
 COMPUTE_DTYPES = ["f16", "bf16", "f32"]
 SPLIT_MODES = ["layer", "tensor", "none"]
-SPEC_TYPES = ["none", "draft", "draft-eagle3", "draft-dflash"]
+SPEC_TYPES = list(REAL_SPEC_TYPES)  # the real llama.cpp --spec-type enum
 MTP_CACHE_DTYPES = ["(same as target)", "f16", "bf16", "f32", "q8_0"]
 
+# The 4-bit-class floor quants (q4_0 / ROCmFP4 / ~nvfp4). Sub-4-bit quants
+# (2-bit/3-bit family) are offered only on explicit override and flagged
+# "you asked for it." See PLAN.md "Objective".
+FLOOR_QUANTS = {"q4_0", "ROCmFP4", "ROCmFPX"}  # ~4.0+ bpw
+
+# n_ctx sweep for the VRAM-vs-context graph (log-ish, capped at 1M).
+GRAPH_CTX_GRID = [1024, 2048, 4096, 8192, 16384, 32768, 65536, 131072, 262144,
+                  524288, 1048576]
+
 
 def list_gguf_files(repo_id: str, hf_token: str):
     """List *.gguf files in a repo and auto-detect their quant names.
@@ -312,10 +334,15 @@ def _parse_tensor_split(text: str) -> list[float] | None:
     return out or None
 
 
-@spaces.GPU
-def compute(
-    arch_fields,
-    quant, n_ctx, cache_dtype, flash_attn, compute_dtype,
+# --- Live recompute + graphs -------------------------------------------------
+#
+# The fetch phase caches a ModelArch; everything below is pure estimate()
+# math on that cached arch, so it runs in microseconds and can fire on every
+# input change (live sliders). No network in the live phase. See PLAN.md.
+
+
+def _build_inputs(
+    arch_fields, quant, n_ctx, cache_dtype, flash_attn, compute_dtype,
     n_batch, n_prompt,
     rope_freq_scale, yarn_ext_factor, yarn_attn_factor,
     yarn_beta_fast, yarn_beta_slow,
@@ -324,15 +351,14 @@ def compute(
     spec_type, draft_quant, draft_params, draft_n_layer, draft_n_max,
     draft_p_min, draft_p_split,
     mmproj_enabled, mmproj_file, mmproj_offload, mmproj_bytes_text,
-):
+) -> tuple[ModelArch, Inputs]:
     arch = _fields_to_arch(arch_fields)
-    # GPU text may carry a 'u' suffix for unified memory; strip it for vram_gb
     gpus = _parse_gpu_list(gpu_vram_text.replace("u", "").replace("U", ""))
     unified = _parse_unified_flags(gpu_vram_text)
     tensor_split = _parse_tensor_split(tensor_split_text)
 
     draft = None
-    if spec_type and spec_type != "none" and draft_params:
+    if spec_type and spec_type != "none":
         draft = DraftInputs(
             spec_type=spec_type,
             quant=draft_quant,
@@ -377,11 +403,135 @@ def compute(
         mmproj=mmproj,
         safety_margin_pct=float(safety_margin),
     )
+    return arch, inp
+
+
+def graph_vram_vs_ctx(arch: ModelArch, inp: Inputs) -> plt.Figure | None:
+    """Graph 1: VRAM vs n_ctx, one curve per quant.
+
+    Shows the context ceiling each quant reaches on the configured GPUs. The
+    user's current n_ctx + the budget total are overlaid so the slider sits
+    on the curve. Returns None when the arch is incomplete.
+    """
+    if arch.n_layer <= 0 or arch.n_embd <= 0 or arch.params <= 0:
+        return None
+    budget_gb = sum(inp.gpu_vram_gb)
+    # sweep the grid up to max(training_ctx*4, current n_ctx, 1M)
+    cap = max(arch.training_ctx * 4, inp.n_ctx, 1 << 20)
+    grid = [c for c in GRAPH_CTX_GRID if c <= cap] or [cap]
+
+    # order quants low->high bpw so the legend reads bottom-to-top
+    quants = sorted(QUANT_CHOICES, key=lambda q: QUANT_BPW[q])
+    fig, ax = plt.subplots(figsize=(7, 4.2))
+    palette = plt.cm.viridis
+    n_q = max(1, len(quants))
+    for i, q in enumerate(quants):
+        ys = []
+        for c in grid:
+            from dataclasses import replace
+            bd = estimate(arch, replace(inp, quant=q, n_ctx=c))
+            ys.append(bd.total_bytes / (1 << 30))
+        color = palette(i / max(1, n_q - 1))
+        ax.plot(grid, ys, marker="o", markersize=3, linewidth=1.6,
+                label=q, color=color)
+
+    # current config marker + budget line
+    cur = estimate(arch, inp)
+    ax.axhline(budget_gb, color="crimson", linestyle="--", linewidth=1.2,
+               label=f"budget {budget_gb:.0f} GB")
+    ax.scatter([inp.n_ctx], [cur.total_bytes / (1 << 30)],
+               color="crimson", zorder=5, s=55,
+               label=f"current ({inp.quant})")
+    ax.set_xscale("log")
+    ax.set_xlabel("context length (n_ctx)")
+    ax.set_ylabel("total VRAM (GiB)")
+    ax.set_title("VRAM vs context, by quant")
+    ax.grid(True, which="both", alpha=0.25)
+    ax.legend(fontsize=7, ncol=2, loc="upper left")
+    fig.tight_layout()
+    return fig
+
+
+def graph_vram_vs_quant(arch: ModelArch, inp: Inputs) -> plt.Figure | None:
+    """Graph 2: VRAM vs quant at fixed n_ctx, colored by quality (bpw).
+
+    The cost+quality frontier: each bar's height is VRAM, its color is the
+    quant's bpw (proxy for quality). The budget is a horizontal line; bars
+    below it fit. Returns None when the arch is incomplete.
+    """
+    if arch.n_layer <= 0 or arch.n_embd <= 0 or arch.params <= 0:
+        return None
+    budget_gb = sum(inp.gpu_vram_gb)
+    from dataclasses import replace
+    quants = sorted(QUANT_CHOICES, key=lambda q: QUANT_BPW[q])
+    ys, bpws, labels = [], [], []
+    for q in quants:
+        bd = estimate(arch, replace(inp, quant=q))
+        ys.append(bd.total_bytes / (1 << 30))
+        bpws.append(QUANT_BPW[q])
+        labels.append(q)
+
+    fig, ax = plt.subplots(figsize=(7, 4.2))
+    cmap = plt.cm.plasma
+    norm = plt.Normalize(vmin=min(bpws), vmax=max(bpws))
+    colors = [cmap(norm(b)) for b in bpws]
+    bars = ax.bar(range(len(quants)), ys, color=colors, edgecolor="black",
+                  linewidth=0.4)
+    ax.axhline(budget_gb, color="crimson", linestyle="--", linewidth=1.2,
+               label=f"budget {budget_gb:.0f} GB")
+    # highlight the currently-selected quant
+    if inp.quant in quants:
+        idx = quants.index(inp.quant)
+        bars[idx].set_edgecolor("crimson")
+        bars[idx].set_linewidth(2.0)
+    ax.set_xticks(range(len(quants)))
+    ax.set_xticklabels(labels, rotation=55, ha="right", fontsize=7)
+    ax.set_ylabel("total VRAM (GiB)")
+    ax.set_title(f"VRAM vs quant @ ctx {inp.n_ctx}  (color = quality/bpw)")
+    ax.grid(True, axis="y", alpha=0.25)
+    ax.legend(fontsize=8, loc="upper left")
+    # colorbar for quality
+    sm = plt.cm.ScalarMappable(cmap=cmap, norm=norm)
+    sm.set_array([])
+    fig.colorbar(sm, ax=ax, label="bits per weight (quality)")
+    fig.tight_layout()
+    return fig
+
+
+def live_compute(
+    arch_fields,
+    quant, n_ctx, cache_dtype, flash_attn, compute_dtype,
+    n_batch, n_prompt,
+    rope_freq_scale, yarn_ext_factor, yarn_attn_factor,
+    yarn_beta_fast, yarn_beta_slow,
+    gpu_vram_text, split_mode, main_gpu, tensor_split_text, safety_margin,
+    mtp_cache_dtype,
+    spec_type, draft_quant, draft_params, draft_n_layer, draft_n_max,
+    draft_p_min, draft_p_split,
+    mmproj_enabled, mmproj_file, mmproj_offload, mmproj_bytes_text,
+):
+    """Live recompute: estimate() on the cached arch + graphs + command.
+
+    Returns (summary_markdown, command_text, graph1, graph2). No network —
+    the arch was fetched once and stored in arch_state. Fires on every input
+    change so sliders are live.
+    """
+    arch, inp = _build_inputs(
+        arch_fields, quant, n_ctx, cache_dtype, flash_attn, compute_dtype,
+        n_batch, n_prompt,
+        rope_freq_scale, yarn_ext_factor, yarn_attn_factor,
+        yarn_beta_fast, yarn_beta_slow,
+        gpu_vram_text, split_mode, main_gpu, tensor_split_text, safety_margin,
+        mtp_cache_dtype,
+        spec_type, draft_quant, draft_params, draft_n_layer, draft_n_max,
+        draft_p_min, draft_p_split,
+        mmproj_enabled, mmproj_file, mmproj_offload, mmproj_bytes_text,
+    )
     if arch.n_layer <= 0 or arch.n_embd <= 0 or arch.params <= 0:
         return (
-            "⚠️ Model architecture is incomplete. Fill n_layer, n_embd, and "
-            "params (or fetch from a GGUF / load a preset).",
-            "", "",
+            "⚠️ Fetch a GGUF (or load a preset) to populate the architecture, "
+            "then adjust the sliders.",
+            "", None, None,
         )
     bd = estimate(arch, inp)
 
@@ -406,12 +556,19 @@ def compute(
         f"| {a} | {b} |" for a, b in rows
     )
 
-    # warnings
-    warn_md = ""
-    if bd.warnings:
-        warn_md = "\n\n**⚠️ Notes:**\n" + "\n".join(
-            f"- {w}" for w in bd.warnings
+    # warnings (incl. the YaRN coherence ladder) + the build-support caveat
+    warns = list(bd.warnings)
+    if quant not in FLOOR_QUANTS and QUANT_BPW.get(quant, 99) < 4.0:
+        warns.append(
+            f"{quant} ({QUANT_BPW[quant]} bpw) is below the 4-bit quality "
+            f"floor — you asked for it."
         )
+    warns.append(
+        "Estimate assumes your llama.cpp build supports the chosen quant "
+        "and KV dtype. ROCmFP4/ROCmFPX need the ciru-ai/ROCmFPX runner."
+    )
+    warn_md = "\n\n**⚠️ Notes:**\n" + "\n".join(f"- {w}" for w in warns) if warns else ""
+
     eff_md = (
         f"\n\nEffective context (training_ctx / rope_freq_scale): "
         f"**{bd.effective_context}**"
@@ -449,10 +606,21 @@ def compute(
         f"**{arch.name or arch.architecture or 'Model'}** @ {quant}, "
         f"ctx {inp.n_ctx} ({cache_dtype} KV"
         + (", FA" if inp.flash_attn else ", no FA")
-        + f"), {len(gpus)} GPU(s) → "
+        + f"), {len(inp.gpu_vram_gb)} GPU(s) → "
         f"**{format_bytes(bd.total_bytes)}** total"
     )
-    return summary + "\n\n" + breakdown_md + eff_md + warn_md + "\n\n" + gpu_md, cmd, cmd
+    md = summary + "\n\n" + breakdown_md + eff_md + warn_md + "\n\n" + gpu_md
+
+    g1 = graph_vram_vs_ctx(arch, inp)
+    g2 = graph_vram_vs_quant(arch, inp)
+    return md, cmd, g1, g2
+
+
+# The live handler is CPU-only estimate math (no GPU needed). `spaces` is
+# imported above so ZeroGPU detects a GPU-aware Space; we don't decorate the
+# hot path with @spaces.GPU because that would queue every slider drag.
+def compute(*args, **kwargs):  # noqa: D401  — backward-compat name
+    return live_compute(*args, **kwargs)
 
 
 def build_ui():
@@ -556,16 +724,25 @@ def build_ui():
                         )
                         yarn_auto_status = gr.Markdown("")
 
-                with gr.Accordion("Speculative decoding (draft model)", open=False):
+                with gr.Accordion("Speculative decoding (speed add-on)", open=False):
+                    gr.Markdown(
+                        "_Two branches. **Weightless** (`ngram-*`): ~zero extra "
+                        "VRAM, no draft model — auto-offered when headroom exists. "
+                        "**Weighted** (`draft-*`): a draft model with its own "
+                        "weights + KV; only enable when you have headroom and "
+                        "accept the tradeoff._"
+                    )
                     spec_type = gr.Dropdown(
                         label="Spec type", choices=SPEC_TYPES, value="none"
                     )
                     with gr.Row():
                         draft_quant = gr.Dropdown(
-                            label="Draft quant", choices=QUANT_CHOICES, value="Q4_K_M"
+                            label="Draft quant (weighted only)",
+                            choices=QUANT_CHOICES, value="Q4_K_M"
                         )
                         draft_params = gr.Number(
-                            label="Draft params", value=0, precision=0
+                            label="Draft params (weighted only)",
+                            value=0, precision=0
                         )
                         draft_n_layer = gr.Number(
                             label="Draft n_layer (1 for EAGLE-3)",
@@ -611,13 +788,20 @@ def build_ui():
                     safety_margin = gr.Number(label="Safety margin %", value=5.0)
 
                 compute_btn = gr.Button("Compute VRAM", variant="primary")
+                gr.Markdown(
+                    "_Live: every slider/dropdown above updates the results "
+                    "and graphs on change. The Compute button is a manual "
+                    "trigger for the same recompute._"
+                )
 
         gr.Markdown("### Results")
         result_md = gr.Markdown("")
-        with gr.Accordion("llama.cpp launch command preview", open=False):
-            cmd_md = gr.Markdown("")
+        with gr.Row():
+            graph_ctx = gr.Plot(label="VRAM vs context (by quant)")
+            graph_quant = gr.Plot(label="VRAM vs quant @ ctx (color = quality)")
+        with gr.Accordion("llama.cpp launch command preview", open=True):
             cmd_text = gr.Textbox(
-                label="Command (copyable)", lines=8, interactive=False
+                label="Command (copyable)", lines=10, interactive=False
             )
 
         with gr.Tab("Auto-fit"):
@@ -689,21 +873,48 @@ def build_ui():
             outputs=[mmproj_bytes_box, fetch_status],
         )
 
+        # Live recompute inputs — every input that affects the estimate.
+        live_inputs = [
+            arch_state, quant, n_ctx, cache_dtype, flash_attn, compute_dtype,
+            n_batch, n_prompt,
+            rope_freq_scale, yarn_ext_factor, yarn_attn_factor,
+            yarn_beta_fast, yarn_beta_slow,
+            gpu_vram_text, split_mode, main_gpu, tensor_split_text,
+            safety_margin,
+            mtp_cache_dtype,
+            spec_type, draft_quant, draft_params, draft_n_layer,
+            draft_n_max, draft_p_min, draft_p_split,
+            mmproj_enabled, mmproj_file, mmproj_offload, mmproj_bytes_box,
+        ]
+        live_outputs = [result_md, cmd_text, graph_ctx, graph_quant]
+
         compute_btn.click(
-            fn=compute,
-            inputs=[
-                arch_state, quant, n_ctx, cache_dtype, flash_attn, compute_dtype,
-                n_batch, n_prompt,
-                rope_freq_scale, yarn_ext_factor, yarn_attn_factor,
-                yarn_beta_fast, yarn_beta_slow,
-                gpu_vram_text, split_mode, main_gpu, tensor_split_text,
-                safety_margin,
-                mtp_cache_dtype,
-                spec_type, draft_quant, draft_params, draft_n_layer,
-                draft_n_max, draft_p_min, draft_p_split,
-                mmproj_enabled, mmproj_file, mmproj_offload, mmproj_bytes_box,
-            ],
-            outputs=[result_md, cmd_md, cmd_text],
+            fn=live_compute,
+            inputs=live_inputs,
+            outputs=live_outputs,
+        )
+
+        # Live: fire on every input change (estimate() is microseconds on the
+        # cached arch — no network). See PLAN.md "Live phase".
+        live_comps = [
+            quant, n_ctx, cache_dtype, flash_attn, compute_dtype,
+            n_batch, n_prompt,
+            rope_freq_scale, yarn_ext_factor, yarn_attn_factor,
+            yarn_beta_fast, yarn_beta_slow,
+            gpu_vram_text, split_mode, main_gpu, tensor_split_text,
+            safety_margin,
+            mtp_cache_dtype,
+            spec_type, draft_quant, draft_params, draft_n_layer,
+            draft_n_max, draft_p_min, draft_p_split,
+            mmproj_enabled, mmproj_file, mmproj_offload, mmproj_bytes_box,
+        ]
+        for comp in live_comps:
+            comp.change(
+                fn=live_compute, inputs=live_inputs, outputs=live_outputs,
+            )
+        # arch_state changes (fetch/preset) also trigger a recompute.
+        arch_state.change(
+            fn=live_compute, inputs=live_inputs, outputs=live_outputs,
         )
 
         # Auto-fit wiring

tests/test_vramcalc.py

@@ -10,6 +10,8 @@ from vramcalc import (
     compute_scratch_bytes,
     yarn_effective_context,
     yarn_warnings,
+    yarn_coherence_warnings,
+    extension_ratio,
     auto_configure_yarn,
     gpu_split,
     estimate,
@@ -320,7 +322,7 @@ def test_estimate_includes_draft_and_mmproj():
     from vramcalc import Inputs, DraftInputs, Mmproj
     arch = PRESETS["Llama-3 8B"]
     base = estimate(arch, Inputs(quant="Q4_K_M", n_ctx=8192, gpu_vram_gb=[24.0]))
-    draft = DraftInputs(spec_type="draft", quant="Q4_K_M",
+    draft = DraftInputs(spec_type="draft-simple", quant="Q4_K_M",
                         params=1_000_000_000, n_layer=4, cache_dtype="f16")
     mm = Mmproj(enabled=True, bytes_=500 * 1e6)
     with_extras = estimate(arch, Inputs(quant="Q4_K_M", n_ctx=8192,
@@ -342,8 +344,8 @@ def test_mmproj_bytes_from_tensors():
 
 def test_draft_bytes_basic():
     from vramcalc import DraftInputs, draft_bytes
-    d = DraftInputs(spec_type="draft", quant="Q4_K_M", params=1_000_000_000,
-                    n_layer=4, cache_dtype="f16")
+    d = DraftInputs(spec_type="draft-simple", quant="Q4_K_M",
+                    params=1_000_000_000, n_layer=4, cache_dtype="f16")
     bd = draft_bytes(draft=d, target_n_ctx=8192, target_n_embd=4096,
                      target_n_head=32, target_n_head_kv=8)
     # weights ~0.6 GB for 1B @ Q4_K_M
@@ -437,14 +439,14 @@ def test_command_preview_none_mode_main_gpu():
 def test_command_preview_draft_and_mmproj():
     from vramcalc import Inputs, DraftInputs, Mmproj
     arch = PRESETS["Llama-3 8B"]
-    draft = DraftInputs(spec_type="draft", quant="Q4_K_M",
+    draft = DraftInputs(spec_type="draft-simple", quant="Q4_K_M",
                        params=1_000_000_000, n_layer=4, cache_dtype="f16")
     mm = Mmproj(filename="mmproj-F16.gguf", enabled=True, offload=True)
     cmd = command_preview(arch, Inputs(quant="Q4_K_M", n_ctx=8192,
                                        gpu_vram_gb=[24.0],
                                        draft=draft, mmproj=mm))
     assert "-md draft-Q4_K_M.gguf" in cmd
-    assert "--spec-type draft" in cmd
+    assert "--spec-type draft-simple" in cmd
     assert "--mmproj mmproj-F16.gguf" in cmd
 
 
@@ -620,4 +622,186 @@ def test_gguf_tensor_section_unreachable_returns_minus_one():
     meta, total = parse_header_with_tensors(buf)
     assert total == -1
     arch = metadata_to_arch(meta, total)
-    assert arch.params == 0  # negative fallback is treated as no fallback
+    assert arch.params == 0  # negative fallback is treated as no fallback
+
+# --- YaRN coherence ladder (warnings only, never a hard block) -----------------
+
+
+def test_extension_ratio():
+    # no extension -> 1.0
+    assert extension_ratio(8192, 8192) == 1.0
+    # 4x extension
+    assert extension_ratio(8192, 32768) == pytest.approx(4.0)
+    # within training context -> 1.0 (no extension counted)
+    assert extension_ratio(131072, 8192) == 1.0
+    # unknown training ctx -> 1.0 (can't grade)
+    assert extension_ratio(0, 32768) == 1.0
+
+
+def test_yarn_coherence_no_warning_within_2x():
+    # 1.5x: fine, no warning
+    assert yarn_coherence_warnings(8192, 12288) == []
+    # exactly 2x: fine, no warning (boundary)
+    assert yarn_coherence_warnings(8192, 16384) == []
+
+
+def test_yarn_coherence_warns_above_2x():
+    # 4x: tail degradation warning
+    w = yarn_coherence_warnings(8192, 32768)
+    assert len(w) == 1
+    assert "degradation" in w[0].lower() or "tail" in w[0].lower()
+
+
+def test_yarn_coherence_warns_at_8x():
+    w = yarn_coherence_warnings(8192, 65536)  # exactly 8x
+    assert len(w) == 1
+    assert "incoherent" in w[0].lower() or "not recommended" in w[0].lower()
+
+
+def test_yarn_coherence_monotonic_ladder():
+    # more extension => same-or-stronger warning severity (never goes quiet)
+    w2x = yarn_coherence_warnings(8192, 16384)   # 2x (boundary, fine)
+    w6x = yarn_coherence_warnings(8192, 49152)   # 6x
+    w8x = yarn_coherence_warnings(8192, 65536)   # 8x
+    w16x = yarn_coherence_warnings(8192, 131072)  # 16x
+    assert w2x == []
+    assert len(w6x) == 1 and "degradation" in w6x[0].lower() or "tail" in w6x[0].lower()
+    assert len(w8x) == 1 and "incoherent" in w8x[0].lower()
+    assert len(w16x) == 1 and "incoherent" in w16x[0].lower()
+
+
+def test_yarn_coherence_no_warning_when_within_training():
+    assert yarn_coherence_warnings(131072, 8192) == []
+
+
+def test_yarn_coherence_invalid_inputs():
+    assert yarn_coherence_warnings(0, 32768) == []
+    assert yarn_coherence_warnings(8192, 0) == []
+
+
+def test_yarn_warnings_includes_coherence():
+    # yarn_warnings should fold in coherence warnings at high extension
+    w = yarn_warnings(
+        training_ctx=262144, target_ctx=1048576,  # 4x
+        rope_freq_scale=0.25, yarn_ext_factor=-1.0, yarn_attn_factor=1.0,
+    )
+    assert any("degradation" in x.lower() or "tail" in x.lower() for x in w)
+
+
+# --- Speculative decoding: real enum + weightless/weighted split ----------------
+
+
+def test_spec_types_real_enum():
+    from vramcalc.draft import SPEC_TYPES, is_weightless, is_weighted
+    # invalid legacy value must not be present
+    assert "draft" not in SPEC_TYPES
+    # real enum members are present
+    for t in ("none", "draft-simple", "draft-eagle3", "draft-mtp",
+              "draft-dflash", "ngram-simple", "ngram-map-k", "ngram-mod",
+              "ngram-cache"):
+        assert t in SPEC_TYPES
+    # weightless classification
+    assert is_weightless("ngram-simple")
+    assert not is_weightless("draft-simple")
+    assert is_weighted("draft-simple")
+    assert not is_weighted("ngram-simple")
+
+
+def test_draft_weightless_zero_vram():
+    from vramcalc import DraftInputs, draft_bytes
+    # ngram spec types: enabled with params=0, zero VRAM
+    d = DraftInputs(spec_type="ngram-simple", params=0)
+    assert d.enabled is True
+    bd = draft_bytes(draft=d, target_n_ctx=8192)
+    assert bd.enabled is True
+    assert bd.total_bytes == 0.0
+
+
+def test_draft_weighted_requires_params():
+    from vramcalc import DraftInputs
+    # weighted type with no params -> disabled
+    d = DraftInputs(spec_type="draft-simple", params=0)
+    assert d.enabled is False
+
+
+def test_command_preview_ngram_no_md_flag():
+    # ngram (weightless) emits --spec-type but no -md draft model
+    from vramcalc import Inputs, DraftInputs
+    arch = PRESETS["Llama-3 8B"]
+    d = DraftInputs(spec_type="ngram-simple", params=0, n_max=4)
+    cmd = command_preview(arch, Inputs(quant="Q4_K_M", n_ctx=8192,
+                                       gpu_vram_gb=[24.0], draft=d))
+    assert "--spec-type ngram-simple" in cmd
+    assert "-md" not in cmd
+    assert "--spec-draft-ngl" not in cmd
+
+
+def test_command_preview_weighted_emits_full_spec_draft_namespace():
+    from vramcalc import Inputs, DraftInputs
+    arch = PRESETS["Llama-3 8B"]
+    d = DraftInputs(spec_type="draft-eagle3", quant="Q4_K_M",
+                    params=1_000_000_000, n_layer=1, n_max=5, p_min=0.5,
+                    p_split=0.1)
+    cmd = command_preview(arch, Inputs(quant="Q4_K_M", n_ctx=8192,
+                                       gpu_vram_gb=[24.0], draft=d))
+    assert "--spec-type draft-eagle3" in cmd
+    assert "-md draft-Q4_K_M.gguf" in cmd
+    assert "--spec-draft-ngl 999" in cmd
+    assert "--spec-draft-device all" in cmd
+    assert "--spec-draft-n-max 5" in cmd
+    assert "--spec-draft-p-min 0.5" in cmd
+    assert "--spec-draft-p-split 0.1" in cmd
+
+
+# --- --fit complement path ---------------------------------------------------
+
+
+def test_command_preview_emits_fit_on():
+    from vramcalc import Inputs
+    arch = PRESETS["Llama-3 8B"]
+    cmd = command_preview(arch, Inputs(quant="Q4_K_M", n_ctx=8192,
+                                       gpu_vram_gb=[24.0],
+                                       safety_margin_pct=5.0))
+    assert "--fit on" in cmd
+    # --fit-target derived from 5% of 24GB = ~1228 MiB
+    assert "--fit-target" in cmd
+
+
+def test_command_preview_fit_target_scales_with_margin():
+    from vramcalc import Inputs
+    arch = PRESETS["Llama-3 8B"]
+    small = command_preview(arch, Inputs(quant="Q4_K_M", n_ctx=8192,
+                                         gpu_vram_gb=[24.0],
+                                         safety_margin_pct=2.0))
+    big = command_preview(arch, Inputs(quant="Q4_K_M", n_ctx=8192,
+                                       gpu_vram_gb=[24.0],
+                                       safety_margin_pct=10.0))
+    def ft_target(cmd):
+        import re
+        m = re.search(r"--fit-target (\d+)", cmd)
+        return int(m.group(1)) if m else 0
+    assert ft_target(big) > ft_target(small) > 0
+
+
+def test_command_preview_fit_target_uses_smallest_gpu():
+    from vramcalc import Inputs
+    arch = PRESETS["Llama-3 8B"]
+    # mixed GPU: margin should be based on the 8GB device, not the 24GB one
+    cmd = command_preview(arch, Inputs(quant="Q4_K_M", n_ctx=8192,
+                                       gpu_vram_gb=[24.0, 8.0],
+                                       safety_margin_pct=10.0))
+    import re
+    m = re.search(r"--fit-target (\d+)", cmd)
+    assert m
+    # 10% of 8GB = ~819 MiB
+    assert 800 < int(m.group(1)) < 840
+
+
+def test_command_preview_no_fit_target_when_margin_zero():
+    from vramcalc import Inputs
+    arch = PRESETS["Llama-3 8B"]
+    cmd = command_preview(arch, Inputs(quant="Q4_K_M", n_ctx=8192,
+                                       gpu_vram_gb=[24.0],
+                                       safety_margin_pct=0.0))
+    assert "--fit on" in cmd
+    assert "--fit-target" not in cmd

vramcalc/__init__.py

@@ -5,7 +5,14 @@ Pure calculation logic, importable without Gradio so it can be unit-tested.
 
 from .quant import QUANT_BPW, weight_bytes, quant_from_filename
 from .kv import kv_cache_bytes, cache_dtype_bytes, compute_scratch_bytes
-from .yarn import yarn_effective_context, yarn_warnings, YarnConfig, auto_configure_yarn
+from .yarn import (
+    yarn_effective_context,
+    yarn_warnings,
+    yarn_coherence_warnings,
+    extension_ratio,
+    YarnConfig,
+    auto_configure_yarn,
+)
 from .gpu import GpuBudget, GpuSpec, gpu_split, fit_gpus, GpuSplitResult
 from .gguf import (
     GGUFMetadata,
@@ -36,6 +43,8 @@ __all__ = [
     "compute_scratch_bytes",
     "yarn_effective_context",
     "yarn_warnings",
+    "yarn_coherence_warnings",
+    "extension_ratio",
     "YarnConfig",
     "auto_configure_yarn",
     "GpuBudget",

vramcalc/draft.py

@@ -21,7 +21,45 @@ from .quant import weight_bytes, QUANT_BPW
 from .kv import kv_cache_bytes, cache_dtype_bytes
 
 
-SPEC_TYPES = ("none", "draft", "draft-eagle3", "draft-dflash")
+SPEC_TYPES = (
+    "none",
+    # weighted (draft model: weights + own KV)
+    "draft-simple",
+    "draft-eagle3",
+    "draft-mtp",
+    "draft-dflash",
+    # weightless (statistical / n-gram; no draft model, ~zero extra VRAM)
+    "ngram-simple",
+    "ngram-map-k",
+    "ngram-map-k4v",
+    "ngram-mod",
+    "ngram-cache",
+)
+
+# Spec types that need no draft model — pure statistical speculation. These
+# have ~zero extra VRAM cost (no draft weights, no draft KV), so they are
+# auto-offered when headroom exists without an "acknowledge the tradeoff"
+# gate. See PLAN.md "Speculative decoding".
+WEIGHTLESS_SPEC_TYPES = (
+    "ngram-simple",
+    "ngram-map-k",
+    "ngram-map-k4v",
+    "ngram-mod",
+    "ngram-cache",
+)
+
+# Spec types backed by a draft model (-md) with its own weights + KV.
+WEIGHTED_SPEC_TYPES = ("draft-simple", "draft-eagle3", "draft-mtp", "draft-dflash")
+
+
+def is_weightless(spec_type: str) -> bool:
+    """True if this spec type needs no draft model (n-gram family)."""
+    return spec_type in WEIGHTLESS_SPEC_TYPES
+
+
+def is_weighted(spec_type: str) -> bool:
+    """True if this spec type needs a draft model (-md)."""
+    return spec_type in WEIGHTED_SPEC_TYPES
 
 
 @dataclass
@@ -38,7 +76,13 @@ class DraftInputs:
 
     @property
     def enabled(self) -> bool:
-        return self.spec_type != "none" and self.params > 0
+        # Weightless (n-gram) spec types need no draft model: enabled as long
+        # as a type is chosen. Weighted types need params > 0.
+        if self.spec_type == "none":
+            return False
+        if is_weightless(self.spec_type):
+            return True
+        return self.params > 0
 
 
 @dataclass
@@ -66,6 +110,10 @@ def draft_bytes(
     if not draft.enabled:
         return DraftBreakdown(enabled=False)
 
+    # Weightless spec types (n-gram family) have no draft model: zero VRAM.
+    if is_weightless(draft.spec_type):
+        return DraftBreakdown(enabled=True)
+
     w = weight_bytes(draft.params, draft.quant)
 
     n_embd = draft.n_embd if getattr(draft, "n_embd", 0) else target_n_embd

vramcalc/quant.py

@@ -59,6 +59,11 @@ QUANT_BPW: dict[str, float] = {
     # ciru-ai/ROCmFPX runner; see command_preview for the warning.
     "ROCmFP4": 4.34,   # 27B Strix Lean: 14.82 GB / 27.32B params
     "ROCmFPX": 7.08,   # 35B A3B MoEQuality: model card states 7.08 BPW
+    # nvfp4 (NVIDIA FP4, llama.cpp PR #22196): NOT yet in this table. The
+    # bits-per-weight is unverified from here, so it cannot be selected as a
+    # floor quant. Add it only once a verified effective bpw is sourced; see
+    # PLAN.md "Quarantined unverified data".
+    # "nvfp4": 4.0,  # VERIFY before ship
 }
 
 

vramcalc/report.py

@@ -220,6 +220,22 @@ def _gpu_specs(inp: Inputs) -> list[GpuSpec]:
     ]
 
 
+def _fit_target_mib(inp: Inputs) -> int:
+    """Per-device --fit-target margin in MiB, from safety_margin_pct.
+
+    --fit-target is a *per-device* MiB reserve. We derive one from the safety
+    margin as a share of the smallest configured GPU's VRAM (the tightest
+    device is what binds). Returns 0 to omit the flag (margin disabled).
+    """
+    if not inp.gpu_vram_gb:
+        return 0
+    if inp.safety_margin_pct <= 0:
+        return 0
+    smallest_gb = min(inp.gpu_vram_gb)
+    margin_bytes = smallest_gb * (1 << 30) * (inp.safety_margin_pct / 100.0)
+    return int(round(margin_bytes / (1 << 20)))
+
+
 def format_bytes(n: float) -> str:
     """Human-readable byte size."""
     n = float(n)
@@ -253,6 +269,16 @@ def command_preview(arch: ModelArch, inp: Inputs) -> str:
     if inp.flash_attn:
         parts.append("--flash-attn")
 
+    # Complement path: we emit fully explicit flags, then --fit on with a
+    # per-device margin target so runtime --fit is a no-op safety net that
+    # can only *reduce* usage, never exceed our estimate. The margin is the
+    # user's "how scared am I" knob (safety_margin_pct). We never claim a
+    # guarantee; the margin is the honest version.
+    parts.append("--fit on")
+    margin_mib = _fit_target_mib(inp)
+    if margin_mib:
+        parts.append(f"--fit-target {margin_mib}")
+
     # Multi-GPU: emit --split-mode / --main-gpu / --tensor-split only when the
     # user has more than one GPU or chose a non-default mode.
     multi = len(inp.gpu_vram_gb) > 1
@@ -272,17 +298,25 @@ def command_preview(arch: ModelArch, inp: Inputs) -> str:
             f"# MTP draft KV dtype: {inp.mtp_cache_dtype} (target: {inp.cache_dtype})"
         )
 
-    # Speculative decoding draft model
+    # Speculative decoding. Two branches:
+    #  - weightless (n-gram family): no draft model, ~zero extra VRAM. Emit
+    #    only --spec-type (no -md).
+    #  - weighted (draft-*): a draft model with weights + KV. Emit -md plus
+    #    the full --spec-draft-* namespace, not the old -md-only stub.
     if inp.draft is not None and inp.draft.enabled:
         d = inp.draft
-        parts.append(f"-md draft-{d.quant}.gguf")
         parts.append(f"--spec-type {d.spec_type}")
-        if d.n_max:
-            parts.append(f"--spec-draft-n-max {d.n_max}")
-        if d.p_min:
-            parts.append(f"--spec-draft-p-min {d.p_min}")
-        if d.p_split:
-            parts.append(f"--spec-draft-p-split {d.p_split}")
+        from .draft import is_weightless
+        if not is_weightless(d.spec_type):
+            parts.append(f"-md draft-{d.quant}.gguf")
+            parts.append("--spec-draft-ngl 999")  # full draft offload
+            parts.append("--spec-draft-device all")
+            if d.n_max:
+                parts.append(f"--spec-draft-n-max {d.n_max}")
+            if d.p_min:
+                parts.append(f"--spec-draft-p-min {d.p_min}")
+            if d.p_split:
+                parts.append(f"--spec-draft-p-split {d.p_split}")
 
     # Multimodal projector
     if inp.mmproj is not None and inp.mmproj.enabled:

vramcalc/yarn.py

@@ -110,4 +110,58 @@ def yarn_warnings(
             "normal long-context YaRN (lower only for high-context YaRN fine-tunes)."
         )
 
-    return warns
+    warns.extend(yarn_coherence_warnings(training_ctx, target_ctx))
+
+    return warns
+
+
+# Extension-ratio thresholds for the coherence ladder. These are warnings
+# only — never a hard block — and come from YaRN-paper behavior and community
+# experience, not measurement. The ladder is monotonic: more extension means
+# same-or-more concern. See PLAN.md "YaRN coherence ladder".
+_YARN_FINE_RATIO = 2.0       # <= 2x: no warning
+_YARN_BAD_RATIO = 8.0        # > 2x..8x: tail degradation; >= 8x: incoherent
+
+
+def extension_ratio(training_ctx: int, target_ctx: int) -> float:
+    """How far the target context stretches beyond the training context.
+
+    Returns 1.0 when target <= training (no extension) or when training_ctx
+    is unknown/invalid.
+    """
+    if not training_ctx or training_ctx <= 0:
+        return 1.0
+    if target_ctx <= 0:
+        return 1.0
+    if target_ctx <= training_ctx:
+        return 1.0
+    return target_ctx / training_ctx
+
+
+def yarn_coherence_warnings(training_ctx: int, target_ctx: int) -> list[str]:
+    """Warn about coherence risk when extending context beyond training.
+
+    These are heuristic warnings, not guarantees. The ladder is monotonic:
+      <= 2x  : fine, no warning
+      > 2x..8x : expect some degradation at the tail of the context window
+      >= 8x  : likely incoherent at long range; not recommended
+    """
+    if training_ctx <= 0 or target_ctx <= 0:
+        return []
+    if target_ctx <= training_ctx:
+        return []
+    ratio = target_ctx / training_ctx
+    w: list[str] = []
+    if ratio >= _YARN_BAD_RATIO:
+        w.append(
+            f"Target context {target_ctx} is {ratio:.1f}x the training "
+            f"context {training_ctx}. Likely incoherent at long range; "
+            f"not recommended."
+        )
+    elif ratio > _YARN_FINE_RATIO:
+        w.append(
+            f"Target context {target_ctx} is {ratio:.1f}x the training "
+            f"context {training_ctx}. Expect some quality degradation at "
+            f"the tail of the context window."
+        )
+    return w