VRAM Calculator v2: unified memory, real multi-GPU, spec decoding, multimodal, MTP, auto-fit

Rewrite the GPU budget to match llama.cpp's real --split-mode behavior
and add the missing components and a solver.

gpu.py: GpuSpec (with is_unified for Strix-Halo-style shared memory);
gpu_split now handles layer (KV distributed with weights, the default
pipeline-parallel mode), tensor (splits weights+KV, warns on quantized
KV / requires FA), and none (all on main-gpu). Supports explicit
--tensor-split ratios and mixed-GPU sizes. Removes the old
kv_on_largest approximation.

draft.py: DraftInputs + draft_bytes for speculative decoding (-md);
weights + own KV, rides on the main GPU.

mmproj.py: mmproj_bytes_from_tensors sums tensor element counts x dtype
bpe from a parsed mmproj GGUF header; folded into total + split.

report.py: Inputs gains split_mode/main_gpu/tensor_split/unified_flags/
mtp_cache_dtype/draft/mmproj. estimate folds draft + mmproj + MTP KV
into the total and the split; MTP extra-layer KV can use a separate
dtype. command_preview emits --split-mode/--main-gpu/--tensor-split
(only when explicit), -md/--spec-type/--spec-draft-*, --mmproj
(+--no-mmproj-offload), and a ROCmFPX note. Breakdown gains draft and
mmproj rows.

autofit.py: max_context (binary search n_ctx that fits), best_quant
(highest-bpw quant that fits + fallback), min_gpu_setup (smallest
largest-first GPU subset). Pure, reuse estimate.

app.py: new split-mode/main-gpu/tensor-split controls, MTP draft KV
dtype dropdown, Speculative decoding + Multimodal accordions, an mmproj
file picker (fetches its size from the header), and an Auto-fit tab
with the three solvers. Per-GPU table shows unified flag and split mode.

46 tests (was 31); verified end-to-end on the Qwen3.6-27B arch with
24GB discrete + 16GB unified, draft model, and mmproj.

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

app.py

@@ -17,11 +17,17 @@ from vramcalc import (
     QUANT_BPW,
     ModelArch,
     Inputs,
+    DraftInputs,
+    Mmproj,
     estimate,
     command_preview,
     format_bytes,
     quant_from_filename,
     parse_hf_range,
+    max_context,
+    best_quant,
+    min_gpu_setup,
+    mmproj_bytes_from_tensors,
 )
 from vramcalc.presets import PRESETS, PRESET_NAMES
 
@@ -29,6 +35,9 @@ from vramcalc.presets import PRESETS, PRESET_NAMES
 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"]
+MTP_CACHE_DTYPES = ["(same as target)", "f16", "bf16", "f32", "q8_0"]
 
 
 def list_gguf_files(repo_id: str, hf_token: str):
@@ -102,6 +111,112 @@ def _empty_arch_fields():
     return _arch_to_fields(ModelArch())
 
 
+def list_mmproj_files(repo_id: str, hf_token: str):
+    """List mmproj-*.gguf files in a repo (for the multimodal projector picker)."""
+    if not repo_id or not repo_id.strip():
+        return gr.update(choices=[], value=None), ""
+    try:
+        api = HfApi(token=hf_token or None)
+        files = api.list_repo_files(repo_id=repo_id.strip())
+    except Exception as e:  # noqa: BLE001
+        return gr.update(choices=[], value=None), f"Error listing repo: {e}"
+    mmps = sorted(
+        f for f in files
+        if f.lower().endswith(".gguf") and "mmproj" in f.lower()
+    )
+    if not mmps:
+        return gr.update(choices=[], value=None), "No mmproj files in this repo."
+    choices = [(f, f) for f in mmps]
+    return gr.update(choices=choices, value=mmps[0]), f"Found {len(mmps)} mmproj file(s)."
+
+
+def fetch_mmproj_bytes(repo_id: str, filename: str, hf_token: str):
+    """Range-read an mmproj GGUF header and estimate its weight bytes."""
+    if not repo_id or not filename:
+        return 0, "Pick an mmproj file first."
+    try:
+        from vramcalc.gguf import parse_hf_range, parse_header_with_tensors
+        # parse_hf_range returns a GGUFMetadata; use the raw dict's dtype hist.
+        meta = parse_hf_range(repo_id.strip(), filename, token=hf_token or None)
+    except Exception as e:  # noqa: BLE001
+        return 0, f"Error reading mmproj header: {e}"
+    hist = meta.raw.get(".tensor_dtype_hist") if meta.raw else None
+    if isinstance(hist, dict) and hist:
+        b = mmproj_bytes_from_tensors({int(k): int(v) for k, v in hist.items()})
+    else:
+        # fall back to params * f16 bpw
+        b = (meta.params or 0) * 2.0
+    return int(b), f"mmproj {filename}: ~{format_bytes(b)} ({meta.params or 0} elems)"
+
+
+def _base_inputs(arch_fields, n_ctx, quant, gpu_vram_text, split_mode, main_gpu,
+                 n_batch, cache_dtype, flash_attn, compute_dtype, safety_margin):
+    """Build (ModelArch, Inputs) for the auto-fit solvers from UI fields."""
+    arch = _fields_to_arch(arch_fields)
+    gpus = _parse_gpu_list(gpu_vram_text.replace("u", "").replace("U", ""))
+    unified = _parse_unified_flags(gpu_vram_text)
+    inp = Inputs(
+        quant=quant, n_ctx=int(n_ctx or 8192),
+        cache_dtype=cache_dtype, flash_attn=bool(flash_attn),
+        compute_dtype=compute_dtype, n_batch=int(n_batch or 512),
+        gpu_vram_gb=gpus, split_mode=split_mode or "layer",
+        main_gpu=int(main_gpu or 0), unified_flags=unified,
+        safety_margin_pct=float(safety_margin or 5.0),
+    )
+    return arch, inp
+
+
+def run_max_context(arch_fields, quant, gpu_vram_text, split_mode, main_gpu,
+                    n_batch, cache_dtype, flash_attn, compute_dtype, safety_margin):
+    arch, inp = _base_inputs(arch_fields, 8192, quant, gpu_vram_text, split_mode,
+                             main_gpu, n_batch, cache_dtype, flash_attn,
+                             compute_dtype, safety_margin)
+    if arch.n_layer <= 0 or arch.params <= 0:
+        return "⚠️ Architecture incomplete — fetch a GGUF or load a preset first."
+    res = max_context(arch, inp, step=1024, max_ctx=max(131072, arch.training_ctx * 4))
+    if not res.fits:
+        return f"❌ {res.note}\n\n(Total @ n_ctx={res.n_ctx}: {format_bytes(res.total_bytes)})"
+    return (
+        f"**Max context that fits:** **{res.n_ctx:,}** tokens\n\n"
+        f"Total VRAM: {format_bytes(res.total_bytes)}\n\n"
+        f"_{res.note}_"
+    )
+
+
+def run_best_quant(arch_fields, n_ctx, gpu_vram_text, split_mode, main_gpu,
+                   n_batch, cache_dtype, flash_attn, compute_dtype, safety_margin):
+    arch, inp = _base_inputs(arch_fields, n_ctx, "Q4_K_M", gpu_vram_text, split_mode,
+                             main_gpu, n_batch, cache_dtype, flash_attn,
+                             compute_dtype, safety_margin)
+    if arch.n_layer <= 0 or arch.params <= 0:
+        return "⚠️ Architecture incomplete — fetch a GGUF or load a preset first."
+    res = best_quant(arch, inp)
+    if not res.fits:
+        return f"❌ {res.note}\n\nLowest-bpw attempt: {res.fallback_quant} ({res.fallback_bpw} bpw) → {format_bytes(res.fallback_total)}"
+    lines = [
+        f"**Recommended quant:** **{res.quant}** ({res.bpw} bpw) → {format_bytes(res.total_bytes)}",
+    ]
+    if res.fallback_quant:
+        lines.append(
+            f"**Safe fallback:** {res.fallback_quant} ({res.fallback_bpw} bpw) → "
+            f"{format_bytes(res.fallback_total)}"
+        )
+    return "\n\n".join(lines)
+
+
+def run_min_gpu_setup(arch_fields, n_ctx, quant, gpu_vram_text, split_mode, main_gpu,
+                      n_batch, cache_dtype, flash_attn, compute_dtype, safety_margin):
+    arch, inp = _base_inputs(arch_fields, n_ctx, quant, gpu_vram_text, split_mode,
+                             main_gpu, n_batch, cache_dtype, flash_attn,
+                             compute_dtype, safety_margin)
+    if arch.n_layer <= 0 or arch.params <= 0:
+        return "⚠️ Architecture incomplete — fetch a GGUF or load a preset first."
+    res = min_gpu_setup(arch, inp)
+    badge = "✅" if res.fits else "❌"
+    subset = ", ".join(f"{g} GB" for g in res.subset)
+    return f"{badge} {res.note}\n\nSubset: [{subset}]\n\nTotal: {format_bytes(res.total_bytes)}"
+
+
 def _arch_to_fields(m: ModelArch):
     return [
         m.name, m.architecture, m.n_layer, m.n_embd, m.n_head, m.n_head_kv,
@@ -153,6 +268,29 @@ def _parse_gpu_list(text: str) -> list[float]:
     return out or [24.0]
 
 
+def _parse_unified_flags(text: str) -> list[bool]:
+    """Parse the 'u' suffix per device: 24,16u -> [False, True]."""
+    flags = []
+    for tok in (text or "").replace(";", ",").split(","):
+        tok = tok.strip().lower()
+        if not tok:
+            continue
+        flags.append(tok.endswith("u"))
+    return flags
+
+
+def _parse_tensor_split(text: str) -> list[float] | None:
+    out = []
+    for tok in (text or "").replace(";", ",").split(","):
+        tok = tok.strip()
+        if tok:
+            try:
+                out.append(float(tok))
+            except ValueError:
+                pass
+    return out or None
+
+
 @spaces.GPU
 def compute(
     arch_fields,
@@ -160,10 +298,41 @@ def compute(
     n_batch, n_prompt,
     rope_freq_scale, yarn_ext_factor, yarn_attn_factor,
     yarn_beta_fast, yarn_beta_slow,
-    gpu_vram_text, kv_on_largest, safety_margin,
+    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,
 ):
     arch = _fields_to_arch(arch_fields)
-    gpus = _parse_gpu_list(gpu_vram_text)
+    # 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:
+        draft = DraftInputs(
+            spec_type=spec_type,
+            quant=draft_quant,
+            params=int(draft_params or 0),
+            n_layer=int(draft_n_layer or 1),
+            n_ctx=int(n_ctx),
+            cache_dtype=cache_dtype,
+            n_max=int(draft_n_max or 0),
+            p_min=float(draft_p_min or 0.0),
+            p_split=float(draft_p_split or 0.0),
+        )
+
+    mmproj = None
+    if mmproj_enabled:
+        mmproj = Mmproj(
+            filename=mmproj_file or "",
+            enabled=True,
+            offload=bool(mmproj_offload),
+            bytes_=float(mmproj_bytes_text or 0.0),
+        )
+
     inp = Inputs(
         quant=quant,
         n_ctx=int(n_ctx),
@@ -178,7 +347,13 @@ def compute(
         yarn_beta_fast=float(yarn_beta_fast),
         yarn_beta_slow=float(yarn_beta_slow),
         gpu_vram_gb=gpus,
-        kv_on_largest=bool(kv_on_largest),
+        split_mode=split_mode or "layer",
+        main_gpu=int(main_gpu or 0),
+        tensor_split=tensor_split,
+        unified_flags=unified,
+        mtp_cache_dtype=mtp_cache_dtype if mtp_cache_dtype else None,
+        draft=draft,
+        mmproj=mmproj,
         safety_margin_pct=float(safety_margin),
     )
     if arch.n_layer <= 0 or arch.n_embd <= 0 or arch.params <= 0:
@@ -195,6 +370,12 @@ def compute(
         ["KV cache (" + cache_dtype + ")", format_bytes(bd.kv_cache_bytes)],
         ["Compute / scratch", format_bytes(bd.compute_scratch_bytes)],
         ["MTP overhead", format_bytes(bd.mtp_overhead_bytes)],
+    ]
+    if bd.draft_bytes_:
+        rows.append(["Draft model (spec. decoding)", format_bytes(bd.draft_bytes_)])
+    if bd.mmproj_bytes_:
+        rows.append(["Multimodal projector", format_bytes(bd.mmproj_bytes_)])
+    rows += [
         ["GGUF header / overhead", format_bytes(bd.gguf_overhead_bytes)],
         ["Safety margin (" + str(inp.safety_margin_pct) + "%)",
          format_bytes(bd.safety_margin_bytes)],
@@ -207,7 +388,7 @@ def compute(
     # warnings
     warn_md = ""
     if bd.warnings:
-        warn_md = "\n\n**⚠️ YaRN / context notes:**\n" + "\n".join(
+        warn_md = "\n\n**⚠️ Notes:**\n" + "\n".join(
             f"- {w}" for w in bd.warnings
         )
     eff_md = (
@@ -219,25 +400,27 @@ def compute(
     gpu_md = ""
     if bd.gpu and bd.gpu.assignments:
         a = bd.gpu.assignments
-        header = "| GPU | VRAM | Weights | KV+Compute | Used | Free | Fits? |"
+        header = "| GPU | VRAM | Weights | KV | Used | Free | Fits? |"
         sep = "|---|---|---|---|---|---|---|"
         body = []
         for g in a:
             kv = format_bytes(g.kv_compute_bytes) if g.kv_compute_bytes else "—"
             badge = "✅" if g.fits else "❌"
+            tag = f" ({g.name})" if g.name else ""
+            unote = " 🔁" if g.is_unified else ""
             body.append(
-                f"| {g.index} | {format_bytes(g.vram_bytes)} | "
+                f"| {g.index}{tag}{unote} | {format_bytes(g.vram_bytes)} | "
                 f"{format_bytes(g.weight_bytes)} | {kv} | "
                 f"{format_bytes(g.used_bytes)} | {format_bytes(g.free_bytes)} "
                 f"| {badge} |"
             )
         total_badge = "✅ all fit" if bd.gpu.all_fit else "❌ over budget"
         gpu_md = (
-            "**Per-GPU split (estimate, proportional weight split):**\n\n"
+            f"**Per-GPU split ({bd.gpu.split_mode} mode):**\n\n"
             + header + "\n" + sep + "\n" + "\n".join(body)
             + f"\n\nTotal VRAM: {format_bytes(bd.gpu.total_vram_bytes)} · "
             f"Total used: {format_bytes(bd.gpu.total_used_bytes)} · "
-            f"{total_badge} · KV on GPU {bd.gpu.kv_gpu_index}"
+            f"{total_badge}"
         )
 
     cmd = command_preview(arch, inp)
@@ -281,6 +464,15 @@ def build_ui():
                     )
                     fetch_btn = gr.Button("Fetch architecture from GGUF header")
                     fetch_status = gr.Markdown("")
+                    mmproj_picker = gr.Dropdown(
+                        label="mmproj file (optional, multimodal)",
+                        choices=[], interactive=True,
+                    )
+                    mmproj_bytes_box = gr.Number(
+                        label="mmproj weight bytes (auto from header; edit if needed)",
+                        value=0, precision=0,
+                    )
+                    fetch_mmproj_btn = gr.Button("Fetch mmproj size from header")
 
                 with gr.Tab("Presets / manual"):
                     preset_dd = gr.Dropdown(
@@ -322,25 +514,74 @@ def build_ui():
                     n_batch = gr.Number(label="n_batch", value=512, precision=0)
                     n_prompt = gr.Number(label="n_prompt (active)", value=0, precision=0)
 
-                gr.Markdown("### YaRN / RoPE context extension")
+                # MTP draft KV dtype (only meaningful when n_mtp > 0)
                 with gr.Row():
-                    rope_freq_scale = gr.Number(label="rope_freq_scale", value=1.0)
-                    yarn_ext_factor = gr.Number(label="yarn_ext_factor", value=-1.0)
-                    yarn_attn_factor = gr.Number(label="yarn_attn_factor", value=1.0)
-                with gr.Row():
-                    yarn_beta_fast = gr.Number(label="yarn_beta_fast", value=32.0)
-                    yarn_beta_slow = gr.Number(label="yarn_beta_slow", value=1.0)
+                    mtp_cache_dtype = gr.Dropdown(
+                        label="MTP draft KV dtype",
+                        choices=MTP_CACHE_DTYPES, value="(same as target)",
+                    )
+
+                with gr.Accordion("YaRN / RoPE context extension", open=False):
+                    with gr.Row():
+                        rope_freq_scale = gr.Number(label="rope_freq_scale", value=1.0)
+                        yarn_ext_factor = gr.Number(label="yarn_ext_factor", value=-1.0)
+                        yarn_attn_factor = gr.Number(label="yarn_attn_factor", value=1.0)
+                    with gr.Row():
+                        yarn_beta_fast = gr.Number(label="yarn_beta_fast", value=32.0)
+                        yarn_beta_slow = gr.Number(label="yarn_beta_slow", value=1.0)
+
+                with gr.Accordion("Speculative decoding (draft model)", open=False):
+                    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"
+                        )
+                        draft_params = gr.Number(
+                            label="Draft params", value=0, precision=0
+                        )
+                        draft_n_layer = gr.Number(
+                            label="Draft n_layer (1 for EAGLE-3)",
+                            value=1, precision=0,
+                        )
+                    with gr.Row():
+                        draft_n_max = gr.Number(
+                            label="--spec-draft-n-max", value=0, precision=0
+                        )
+                        draft_p_min = gr.Number(label="p_min", value=0.0)
+                        draft_p_split = gr.Number(label="p_split", value=0.0)
+
+                with gr.Accordion("Multimodal (mmproj)", open=False):
+                    mmproj_enabled = gr.Checkbox(
+                        label="Include multimodal projector", value=False
+                    )
+                    mmproj_file = gr.Textbox(
+                        label="mmproj filename (e.g. mmproj-F16.gguf)",
+                        value="",
+                    )
+                    mmproj_offload = gr.Checkbox(
+                        label="Offload mmproj to GPU", value=True
+                    )
+                    # mmproj_bytes_box + fetch_mmproj_btn declared above
 
                 gr.Markdown("### 3. Multi-GPU budget")
                 gpu_vram_text = gr.Textbox(
-                    label="Per-GPU VRAM (GB, comma-separated)",
+                    label="Per-GPU VRAM (GB, comma-separated; suffix 'u' = unified)",
                     value="24",
-                    placeholder="e.g. 24,24,16",
+                    placeholder="e.g. 24,16u  (24GB discrete + 16GB unified)",
                 )
                 with gr.Row():
-                    kv_on_largest = gr.Checkbox(
-                        label="Place KV cache on largest GPU", value=False
+                    split_mode = gr.Dropdown(
+                        label="split-mode", choices=SPLIT_MODES, value="layer"
                     )
+                    main_gpu = gr.Number(label="main-gpu (none mode)", value=0, precision=0)
+                tensor_split_text = gr.Textbox(
+                    label="--tensor-split ratios (optional, comma-sep)",
+                    value="",
+                    placeholder="e.g. 3,1 (blank = auto by VRAM)",
+                )
+                with gr.Row():
                     safety_margin = gr.Number(label="Safety margin %", value=5.0)
 
                 compute_btn = gr.Button("Compute VRAM", variant="primary")
@@ -353,6 +594,37 @@ def build_ui():
                 label="Command (copyable)", lines=8, interactive=False
             )
 
+        with gr.Tab("Auto-fit"):
+            gr.Markdown(
+                "### Auto-fit solvers\n"
+                "Uses the current architecture + GPU budget. Run the calculator "
+                "first (or load a preset/fetch a GGUF) so the architecture is "
+                "populated, then pick a solver."
+            )
+            with gr.Row():
+                af_quant = gr.Dropdown(
+                    label="Quant for max-context solver",
+                    choices=QUANT_CHOICES, value="Q4_K_M",
+                )
+                af_maxctx_btn = gr.Button("Max context that fits")
+                af_maxctx_out = gr.Markdown("")
+            with gr.Row():
+                af_bestq_ctx = gr.Number(
+                    label="Context for best-quant solver", value=8192, precision=0
+                )
+                af_bestq_btn = gr.Button("Best quant that fits")
+                af_bestq_out = gr.Markdown("")
+            with gr.Row():
+                af_mingu_ctx = gr.Number(
+                    label="Context for min-GPU solver", value=8192, precision=0
+                )
+                af_mingu_quant = gr.Dropdown(
+                    label="Quant for min-GPU solver",
+                    choices=QUANT_CHOICES, value="Q4_K_M",
+                )
+                af_mingu_btn = gr.Button("Min GPUs needed")
+                af_mingu_out = gr.Markdown("")
+
         # --- wiring ---
         def _store_arch(*fields):
             return list(fields)
@@ -381,6 +653,16 @@ def build_ui():
             fn=_store_arch, inputs=arch_inputs, outputs=arch_state
         )
 
+        # mmproj picker: populate from the same repo's *.gguf (filter mmproj)
+        list_btn.click(
+            fn=list_mmproj_files, inputs=[repo_id, hf_token],
+            outputs=[mmproj_picker, fetch_status],
+        )
+        fetch_mmproj_btn.click(
+            fn=fetch_mmproj_bytes, inputs=[repo_id, mmproj_picker, hf_token],
+            outputs=[mmproj_bytes_box, fetch_status],
+        )
+
         compute_btn.click(
             fn=compute,
             inputs=[
@@ -388,11 +670,37 @@ def build_ui():
                 n_batch, n_prompt,
                 rope_freq_scale, yarn_ext_factor, yarn_attn_factor,
                 yarn_beta_fast, yarn_beta_slow,
-                gpu_vram_text, kv_on_largest, safety_margin,
+                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],
         )
 
+        # Auto-fit wiring
+        af_maxctx_btn.click(
+            fn=run_max_context,
+            inputs=[arch_state, af_quant, gpu_vram_text, split_mode, main_gpu,
+                    n_batch, cache_dtype, flash_attn, compute_dtype, safety_margin],
+            outputs=[af_maxctx_out],
+        )
+        af_bestq_btn.click(
+            fn=run_best_quant,
+            inputs=[arch_state, af_bestq_ctx, gpu_vram_text, split_mode, main_gpu,
+                    n_batch, cache_dtype, flash_attn, compute_dtype, safety_margin],
+            outputs=[af_bestq_out],
+        )
+        af_mingu_btn.click(
+            fn=run_min_gpu_setup,
+            inputs=[arch_state, af_mingu_ctx, af_mingu_quant, gpu_vram_text,
+                    split_mode, main_gpu, n_batch, cache_dtype, flash_attn,
+                    compute_dtype, safety_margin],
+            outputs=[af_mingu_out],
+        )
+
     return demo
 
 

tests/test_vramcalc.py

@@ -155,41 +155,91 @@ def test_yarn_warnings_no_warning_when_within():
     assert w == []
 
 
-def test_gpu_split_proportional_sums():
+def test_gpu_split_layer_distributes_weights_and_kv():
     res = gpu_split(
         gpu_vram_bytes=[24 << 30, 24 << 30, 16 << 30],
         weights_bytes=40 << 30,
-        kv_compute_bytes=4 << 30,
+        kv_bytes=4 << 30,
+        split_mode="layer",
     )
-    # weight shares sum to weights
-    total_w = sum(a.weight_bytes for a in res.assignments)
-    assert total_w == pytest.approx(40 << 30, rel=1e-6)
-    # KV on exactly one GPU (default GPU 0)
+    # weights sum preserved
+    assert sum(a.weight_bytes for a in res.assignments) == pytest.approx(40 << 30, rel=1e-6)
+    # layer mode: KV distributed across ALL gpus (follows the layers), not one
     kv_gpus = [a for a in res.assignments if a.kv_compute_bytes > 0]
-    assert len(kv_gpus) == 1
-    assert kv_gpus[0].index == 0
+    assert len(kv_gpus) == 3
     # used+free == vram for each gpu
     for a in res.assignments:
         assert a.used_bytes + a.free_bytes == pytest.approx(a.vram_bytes, rel=1e-6)
 
 
-def test_gpu_split_kv_on_largest():
+def test_gpu_split_none_mode_all_on_main():
     res = gpu_split(
-        gpu_vram_bytes=[16 << 30, 24 << 30],
+        gpu_vram_bytes=[24 << 30, 24 << 30],
         weights_bytes=10 << 30,
-        kv_compute_bytes=3 << 30,
-        kv_on_largest=True,
+        kv_bytes=2 << 30,
+        split_mode="none",
+        main_gpu=1,
     )
-    kv_gpus = [a for a in res.assignments if a.kv_compute_bytes > 0]
-    assert len(kv_gpus) == 1
-    assert kv_gpus[0].index == 1
+    # only main_gpu carries load
+    assert res.assignments[0].used_bytes == 0.0
+    assert res.assignments[1].weight_bytes == pytest.approx(10 << 30)
+    assert res.assignments[0].role == "unused"
+    assert "main" in res.assignments[1].role
+
+
+def test_gpu_split_tensor_mode_splits_kv():
+    res = gpu_split(
+        gpu_vram_bytes=[24 << 30, 24 << 30],
+        weights_bytes=10 << 30,
+        kv_bytes=2 << 30,
+        split_mode="tensor",
+    )
+    # both gpus get half weights and half KV (even split by default)
+    assert res.assignments[0].weight_bytes == pytest.approx(5 << 30)
+    assert res.assignments[0].kv_compute_bytes == pytest.approx(1 << 30)
+    assert res.assignments[1].weight_bytes == pytest.approx(5 << 30)
+
+
+def test_gpu_split_tensor_quantized_kv_warns():
+    res = gpu_split(
+        gpu_vram_bytes=[24 << 30, 24 << 30],
+        weights_bytes=10 << 30,
+        kv_bytes=2 << 30,
+        split_mode="tensor",
+        cache_dtype_quantized=True,
+    )
+    assert any("quantized KV" in w for w in res.warnings)
+
+
+def test_gpu_split_explicit_tensor_split_ratios():
+    res = gpu_split(
+        gpu_vram_bytes=[24 << 30, 8 << 30],
+        weights_bytes=16 << 30,
+        kv_bytes=0,
+        split_mode="layer",
+        tensor_split=[3, 1],
+    )
+    # 3:1 split -> 12 and 4
+    assert res.assignments[0].weight_bytes == pytest.approx(12 << 30)
+    assert res.assignments[1].weight_bytes == pytest.approx(4 << 30)
+
+
+def test_gpu_split_unified_memory_warns():
+    from vramcalc.gpu import GpuSpec
+    res = gpu_split(
+        gpu_specs=[GpuSpec(24, "RX7900", False), GpuSpec(16, "Strix", True)],
+        weights_bytes=10 << 30,
+        kv_bytes=1 << 30,
+    )
+    assert any("unified" in w for w in res.warnings)
+    assert res.assignments[1].is_unified is True
 
 
 def test_gpu_split_fit_badge():
     res = gpu_split(
         gpu_vram_bytes=[4 << 30],  # tiny
         weights_bytes=10 << 30,
-        kv_compute_bytes=1 << 30,
+        kv_bytes=1 << 30,
     )
     assert res.all_fit is False
     assert res.assignments[0].fits is False
@@ -218,6 +268,99 @@ def test_estimate_mtp_overhead():
     assert bd.mtp_overhead_bytes > 0
 
 
+def test_estimate_mtp_dual_kv_dtype():
+    """MTP extra-layer KV can use a different dtype than the target KV."""
+    arch = PRESETS["DeepSeek-V3 (MoE)"]
+    from vramcalc import Inputs
+    base = estimate(arch, Inputs(quant="Q4_K_M", n_ctx=8192, cache_dtype="q8_0",
+                                 gpu_vram_gb=[80.0], mtp_cache_dtype="q8_0"))
+    mtp_f16 = estimate(arch, Inputs(quant="Q4_K_M", n_ctx=8192, cache_dtype="q8_0",
+                                   gpu_vram_gb=[80.0], mtp_cache_dtype="f16"))
+    # f16 MTP KV (2 bytes) vs q8_0 (1 byte) -> MTP overhead roughly doubles its
+    # KV portion, so the f16 case is larger.
+    assert mtp_f16.mtp_overhead_bytes > base.mtp_overhead_bytes
+
+
+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",
+                        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,
+                                        gpu_vram_gb=[24.0], draft=draft, mmproj=mm))
+    assert with_extras.draft_bytes_ > 0
+    assert with_extras.mmproj_bytes_ == pytest.approx(500e6)
+    assert with_extras.total_bytes > base.total_bytes
+
+
+def test_mmproj_bytes_from_tensors():
+    from vramcalc.mmproj import mmproj_bytes_from_tensors
+    # 1e9 F16 elements (dtype 1) -> 1e9 * 16 / 8 = 2e9 bytes
+    b = mmproj_bytes_from_tensors({1: 1_000_000_000})
+    assert b == pytest.approx(2e9)
+    # mix of F32 (dtype 0, 32 bpe) and F16
+    b2 = mmproj_bytes_from_tensors({0: 1_000_000, 1: 1_000_000})
+    assert b2 == pytest.approx((1e6 * 32 + 1e6 * 16) / 8)
+
+
+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")
+    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
+    assert 0.5e9 < bd.weights_bytes < 0.7e9
+    assert bd.kv_bytes > 0
+    assert bd.enabled
+
+
+def test_draft_bytes_disabled():
+    from vramcalc import DraftInputs, draft_bytes
+    d = DraftInputs(spec_type="none", params=0)
+    bd = draft_bytes(draft=d, target_n_ctx=8192)
+    assert bd.enabled is False
+    assert bd.total_bytes == 0.0
+
+
+def test_autofit_max_context():
+    from vramcalc import Inputs, max_context
+    arch = PRESETS["Llama-3 8B"]
+    inp = Inputs(quant="Q4_K_M", n_ctx=8192, gpu_vram_gb=[24.0])
+    res = max_context(arch, inp, step=1024, max_ctx=131072)
+    # 8B @ Q4_K_M fits a huge context on 24GB; expect a large value
+    assert res.fits
+    assert res.n_ctx >= 8192
+
+
+def test_autofit_best_quant():
+    from vramcalc import Inputs, best_quant
+    arch = PRESETS["Llama-3 8B"]
+    # tight budget at large ctx -> only lower-bpw quants fit
+    inp = Inputs(quant="Q4_K_M", n_ctx=32768, gpu_vram_gb=[8.0])
+    res = best_quant(arch, inp)
+    # something fits (8B is small) and recommendation is a known quant
+    assert res.fits
+    assert res.quant in QUANT_BPW
+    assert res.bpw == QUANT_BPW[res.quant]
+    # fallback is lower bpw than recommendation
+    if res.fallback_quant:
+        assert res.fallback_bpw < res.bpw
+
+
+def test_autofit_min_gpu_setup():
+    from vramcalc import Inputs, min_gpu_setup
+    arch = PRESETS["Llama-3 8B"]
+    inp = Inputs(quant="Q4_K_M", n_ctx=8192, gpu_vram_gb=[4.0, 24.0, 16.0])
+    res = min_gpu_setup(arch, inp)
+    # 8B Q4_K_M fits on a single 24GB GPU (largest first)
+    assert res.fits
+    assert res.n_gpus == 1
+    assert res.subset == [24.0]
+
+
 def test_command_preview_basic():
     arch = PRESETS["Llama-3 8B"]
     from vramcalc import Inputs
@@ -233,9 +376,50 @@ def test_command_preview_basic():
 def test_command_preview_multigpu_split():
     arch = PRESETS["Llama-3 8B"]
     from vramcalc import Inputs
+    # multi-GPU now emits --split-mode (auto-split, no explicit --tensor-split)
     cmd = command_preview(arch, Inputs(quant="Q4_K_M", n_ctx=8192,
                                        gpu_vram_gb=[24.0, 24.0]))
-    assert "--tensor-split 24.0,24.0" in cmd
+    assert "--split-mode layer" in cmd
+    assert "--tensor-split" not in cmd  # not emitted without explicit ratios
+
+    # explicit tensor-split ratios are emitted verbatim
+    cmd2 = command_preview(arch, Inputs(quant="Q4_K_M", n_ctx=8192,
+                                        gpu_vram_gb=[24.0, 24.0],
+                                        tensor_split=[3, 1]))
+    assert "--tensor-split 3,1" in cmd2
+
+
+def test_command_preview_none_mode_main_gpu():
+    arch = PRESETS["Llama-3 8B"]
+    from vramcalc import Inputs
+    cmd = command_preview(arch, Inputs(quant="Q4_K_M", n_ctx=8192,
+                                       gpu_vram_gb=[24.0, 24.0],
+                                       split_mode="none", main_gpu=1))
+    assert "--split-mode none" in cmd
+    assert "--main-gpu 1" in cmd
+
+
+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",
+                       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 "--mmproj mmproj-F16.gguf" in cmd
+
+
+def test_command_preview_mmproj_no_offload():
+    from vramcalc import Inputs, Mmproj
+    arch = PRESETS["Llama-3 8B"]
+    mm = Mmproj(filename="mmproj.gguf", enabled=True, offload=False)
+    cmd = command_preview(arch, Inputs(quant="Q4_K_M", n_ctx=8192,
+                                       gpu_vram_gb=[24.0], mmproj=mm))
+    assert "--no-mmproj-offload" in cmd
 
 
 def test_command_preview_yarn_when_target_exceeds():

vramcalc/__init__.py

@@ -6,7 +6,7 @@ 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
-from .gpu import GpuBudget, gpu_split, fit_gpus, GpuSplitResult
+from .gpu import GpuBudget, GpuSpec, gpu_split, fit_gpus, GpuSplitResult
 from .gguf import (
     GGUFMetadata,
     parse_header_bytes,
@@ -15,6 +15,9 @@ from .gguf import (
     parse_hf_range,
     metadata_to_arch,
 )
+from .draft import DraftInputs, DraftBreakdown, draft_bytes, SPEC_TYPES
+from .mmproj import Mmproj, MmprojBreakdown, mmproj_bytes_from_tensors, mmproj_bytes_from_meta
+from .autofit import max_context, best_quant, min_gpu_setup
 from .report import (
     ModelArch,
     Inputs,
@@ -34,6 +37,7 @@ __all__ = [
     "yarn_effective_context",
     "yarn_warnings",
     "GpuBudget",
+    "GpuSpec",
     "GpuSplitResult",
     "gpu_split",
     "fit_gpus",
@@ -43,6 +47,17 @@ __all__ = [
     "parse_local_file",
     "parse_hf_range",
     "metadata_to_arch",
+    "DraftInputs",
+    "DraftBreakdown",
+    "draft_bytes",
+    "SPEC_TYPES",
+    "Mmproj",
+    "MmprojBreakdown",
+    "mmproj_bytes_from_tensors",
+    "mmproj_bytes_from_meta",
+    "max_context",
+    "best_quant",
+    "min_gpu_setup",
     "ModelArch",
     "Inputs",
     "Breakdown",

vramcalc/autofit.py

@@ -0,0 +1,177 @@
+"""Auto-fit solvers: pick n_ctx, quant, or GPU setup from a VRAM budget.
+
+These call :func:`vramcalc.report.estimate` in a loop — no new VRAM math — so
+they stay consistent with the manual calculator. All three are pure and
+unit-testable.
+
+  max_context   — largest n_ctx that fits the GPU budget at a given quant.
+  best_quant    — highest-bpw quant that fits a given n_ctx (plus fallback).
+  min_gpu_setup — smallest subset of the user's GPUs that fits (largest-first).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from typing import Callable
+
+from .quant import QUANT_BPW
+from .report import ModelArch, Inputs, estimate
+
+
+def _total_vram_bytes(inp: Inputs) -> int:
+    return int(sum(g * (1 << 30) for g in inp.gpu_vram_gb))
+
+
+def _fits(bd) -> bool:
+    return bd.gpu is not None and bd.gpu.all_fit
+
+
+@dataclass
+class MaxContextResult:
+    n_ctx: int = 0
+    total_bytes: float = 0.0
+    fits: bool = False
+    note: str = ""
+
+
+def max_context(
+    arch: ModelArch,
+    inp: Inputs,
+    *,
+    step: int = 512,
+    max_ctx: int | None = None,
+) -> MaxContextResult:
+    """Binary-search the largest n_ctx whose estimate fits the GPU budget.
+
+    Search bounds: [step … max_ctx]. Default max_ctx = max(training_ctx, n_ctx)
+    * 4 to allow YaRN-extended contexts without an unbounded loop. Returns the
+    largest fitting n_ctx (rounded down to a multiple of `step`) and the
+    resulting total; ``fits`` is False if even the minimum doesn't fit.
+    """
+    budget = _total_vram_bytes(inp)
+    hi = max_ctx or max(arch.training_ctx, inp.n_ctx, step) * 4
+    hi = max(hi, step)
+    lo = step
+
+    # quick check: does the minimum fit at all?
+    bd_min = estimate(arch, replace(inp, n_ctx=lo))
+    if not _fits(bd_min):
+        return MaxContextResult(
+            n_ctx=lo, total_bytes=bd_min.total_bytes, fits=False,
+            note=f"Even n_ctx={lo} doesn't fit {budget/1e9:.1f} GiB budget.",
+        )
+
+    # does the maximum fit? (small models on big GPUs)
+    bd_hi = estimate(arch, replace(inp, n_ctx=hi))
+    if _fits(bd_hi):
+        return MaxContextResult(
+            n_ctx=hi, total_bytes=bd_hi.total_bytes, fits=True,
+            note=f"Even n_ctx={hi} fits; try a higher cap.",
+        )
+
+    # binary search the boundary
+    best = lo
+    best_total = bd_min.total_bytes
+    while lo <= hi:
+        mid = (lo + hi) // 2
+        # snap to step
+        mid = (mid // step) * step
+        if mid < step:
+            mid = step
+        bd = estimate(arch, replace(inp, n_ctx=mid))
+        if _fits(bd):
+            best = mid
+            best_total = bd.total_bytes
+            lo = mid + step
+        else:
+            hi = mid - step
+    return MaxContextResult(n_ctx=best, total_bytes=best_total, fits=True)
+
+
+@dataclass
+class BestQuantResult:
+    quant: str = ""
+    bpw: float = 0.0
+    total_bytes: float = 0.0
+    fits: bool = False
+    fallback_quant: str = ""
+    fallback_bpw: float = 0.0
+    fallback_total: float = 0.0
+    note: str = ""
+
+
+def best_quant(arch: ModelArch, inp: Inputs) -> BestQuantResult:
+    """Highest-bpw quant that fits the GPU budget at the current n_ctx.
+
+    Iterates quants from highest to lowest bpw; the first that fits is the
+    recommendation, the next-lower that also fits is the safe fallback.
+    """
+    ordered = sorted(QUANT_BPW.items(), key=lambda kv: kv[1], reverse=True)
+    res = BestQuantResult()
+    found_fit = None
+    fallback = None
+    for q, bpw in ordered:
+        bd = estimate(arch, replace(inp, quant=q))
+        fits = _fits(bd)
+        if fits and found_fit is None:
+            found_fit = (q, bpw, bd.total_bytes)
+        elif fits and found_fit is not None and fallback is None:
+            fallback = (q, bpw, bd.total_bytes)
+            break  # first lower-bpw fit is the fallback
+        elif not fits and found_fit is not None and fallback is None:
+            # keep scanning down for the first that fits as fallback
+            continue
+    if found_fit is None:
+        # nothing fits; report the lowest-bpw attempt (least-bad)
+        last_q, last_bp = ordered[-1]
+        bd = estimate(arch, replace(inp, quant=last_q))
+        res.quant = ""
+        res.fits = False
+        res.note = f"No quant fits the budget at n_ctx={inp.n_ctx}."
+        res.fallback_quant = last_q
+        res.fallback_bpw = last_bp
+        res.fallback_total = bd.total_bytes
+        return res
+    res.quant, res.bpw, res.total_bytes = found_fit
+    res.fits = True
+    if fallback is not None:
+        res.fallback_quant, res.fallback_bpw, res.fallback_total = fallback
+    return res
+
+
+@dataclass
+class MinGpuResult:
+    n_gpus: int = 0
+    subset: list[float] = field(default_factory=list)  # vram_gb of chosen GPUs
+    total_bytes: float = 0.0
+    fits: bool = False
+    note: str = ""
+
+
+def min_gpu_setup(arch: ModelArch, inp: Inputs) -> MinGpuResult:
+    """Smallest subset (largest-first) of the user's GPUs that fits.
+
+    Greedy: sort the configured GPUs by VRAM descending and add them one at a
+    time until the estimate fits. Reports the chosen subset and count.
+    """
+    if not inp.gpu_vram_gb:
+        return MinGpuResult(note="No GPUs configured.")
+    # sort largest-first, keep original-size list
+    sorted_gpus = sorted(inp.gpu_vram_gb, reverse=True)
+    res = MinGpuResult()
+    for k in range(1, len(sorted_gpus) + 1):
+        subset = sorted_gpus[:k]
+        bd = estimate(arch, replace(inp, gpu_vram_gb=subset))
+        if _fits(bd):
+            return MinGpuResult(
+                n_gpus=k, subset=subset, total_bytes=bd.total_bytes,
+                fits=True,
+                note=f"Fits on {k} GPU(s): {[f'{g}GB' for g in subset]}.",
+            )
+    # none fit even with all GPUs
+    bd = estimate(arch, replace(inp, gpu_vram_gb=sorted_gpus))
+    return MinGpuResult(
+        n_gpus=len(sorted_gpus), subset=sorted_gpus,
+        total_bytes=bd.total_bytes, fits=False,
+        note=f"Doesn't fit even on all {len(sorted_gpus)} GPU(s).",
+    )

vramcalc/draft.py

@@ -0,0 +1,95 @@
+"""Speculative-decoding draft model memory.
+
+A draft model (llama.cpp `-md`) runs alongside the target and contributes its
+own weights and KV cache. Supported spec types (see docs/speculative.md):
+  draft        — a standalone small draft model
+  draft-eagle3  — EAGLE-3 single-layer draft (shares the target tokenizer)
+  draft-dflash  — DFlash block-diffusion draft
+  none         — no draft model
+
+For VRAM purposes the draft model's cost is its weights + its own KV cache.
+EAGLE-3 drafts are typically a single layer; standalone drafts have their own
+n_layer. The draft usually rides on the main GPU alongside the target, which
+the caller handles by adding draft_bytes to that GPU's used.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .quant import weight_bytes, QUANT_BPW
+from .kv import kv_cache_bytes, cache_dtype_bytes
+
+
+SPEC_TYPES = ("none", "draft", "draft-eagle3", "draft-dflash")
+
+
+@dataclass
+class DraftInputs:
+    spec_type: str = "none"
+    quant: str = "Q4_K_M"
+    params: int = 0          # draft parameter count
+    n_layer: int = 1        # draft layer count (1 for EAGLE-3 by default)
+    n_ctx: int | None = None  # defaults to target n_ctx
+    cache_dtype: str = "f16"
+    n_max: int = 0          # --spec-draft-n-max (informational)
+    p_min: float = 0.0
+    p_split: float = 0.0
+
+    @property
+    def enabled(self) -> bool:
+        return self.spec_type != "none" and self.params > 0
+
+
+@dataclass
+class DraftBreakdown:
+    weights_bytes: float = 0.0
+    kv_bytes: float = 0.0
+    total_bytes: float = 0.0
+    enabled: bool = False
+
+
+def draft_bytes(
+    *,
+    draft: DraftInputs,
+    target_n_ctx: int,
+    target_n_embd: int = 0,
+    target_n_head: int = 0,
+    target_n_head_kv: int = 0,
+) -> DraftBreakdown:
+    """Return (weights, kv) bytes for a draft model.
+
+    Reuses weight_bytes and kv_cache_bytes. The draft KV uses the draft's own
+    n_head_kv; if unset we fall back to the target's (EAGLE-3 shares the
+    target's attention geometry). n_embd likewise defaults to the target's.
+    """
+    if not draft.enabled:
+        return DraftBreakdown(enabled=False)
+
+    w = weight_bytes(draft.params, draft.quant)
+
+    n_embd = draft.n_embd if getattr(draft, "n_embd", 0) else target_n_embd
+    n_head = draft.n_head if getattr(draft, "n_head", 0) else target_n_head
+    n_head_kv = (
+        draft.n_head_kv if getattr(draft, "n_head_kv", 0) else target_n_head_kv
+    )
+    if n_head_kv == 0:
+        n_head_kv = n_head
+    n_ctx = draft.n_ctx if draft.n_ctx is not None else target_n_ctx
+
+    # kv_cache_bytes raises on an unknown cache dtype; guard.
+    try:
+        kv = kv_cache_bytes(
+            n_layer=max(1, draft.n_layer),
+            n_embd=n_embd,
+            n_head=max(1, n_head),
+            n_head_kv=max(1, n_head_kv),
+            n_ctx=n_ctx,
+            cache_dtype=draft.cache_dtype,
+        )
+    except ValueError:
+        kv = 0.0
+
+    return DraftBreakdown(
+        weights_bytes=w, kv_bytes=kv, total_bytes=w + kv, enabled=True,
+    )

vramcalc/gguf.py

@@ -158,6 +158,10 @@ def parse_header_with_tensors(buf: bytes):
     reach the tensor section we return -1 (unreachable) so callers can tell
     "incomplete" from "zero tensors".
 
+    A per-dtype element histogram is attached to the returned metadata dict
+    under ``".tensor_dtype_hist"`` (dtype id -> total elems) when at least one
+    tensor was parsed — used by the mmproj projector sizing path.
+
     Used as a fallback for `params` when general.parameter_count is absent.
     """
     r = _Reader(buf)
@@ -182,6 +186,7 @@ def parse_header_with_tensors(buf: bytes):
             return meta, 0
     total = 0
     parsed = 0
+    hist: dict[int, int] = {}
     for _ in range(tensor_count):
         if r.eof():
             break
@@ -191,12 +196,15 @@ def parse_header_with_tensors(buf: bytes):
             elems = 1
             for _ in range(n_dims):
                 elems *= r.u64()       # dims multiply, not add
-            total += elems
-            r.u32()                    # dtype
+            dtype = r.u32()
             r.u64()                    # data offset
+            total += elems
+            hist[dtype] = hist.get(dtype, 0) + elems
             parsed += 1
         except (EOFError, ValueError):
             break
+    if parsed > 0:
+        meta[".tensor_dtype_hist"] = hist
     # If we couldn't reach any tensor infos, signal failure with -1 so callers
     # can distinguish "unreachable" from "0 tensors".
     if parsed == 0 and tensor_count > 0:

vramcalc/gpu.py

@@ -1,11 +1,26 @@
-"""Multi-GPU VRAM budgeting and tensor-split estimation.
-
-llama.cpp's real `--tensor-split` distributes tensor rows across devices; we
-approximate it by splitting the **weights** proportionally to each GPU's VRAM
-(this is the common case when users want an even load). The KV cache and
-compute scratch are placed on a single device (GPU 0 by default, or the GPU
-with the most free space) because llama.cpp keeps the cache on the first
-device unless manually offloaded.
+"""Multi-GPU VRAM budgeting, modelled on llama.cpp's real --split-mode.
+
+llama.cpp distributes work across GPUs in one of three split modes
+(see docs/multi-gpu.md):
+
+  layer  (default, pipeline-parallel): each GPU holds a contiguous slice of
+          *layers*. The KV cache for layer l lives on the GPU that owns layer
+          l, so KV is distributed across GPUs in the same proportion as the
+          weights — it is NOT piled on GPU 0.
+
+  tensor (experimental, tensor-parallel): splits both weights *and* KV across
+          the participating GPUs, either evenly or by --tensor-split
+          proportions. Requires flash-attn on and a non-quantized KV cache
+          (f16/bf16/f32); quantized KV is a hard error upstream.
+
+  none   : everything on --main-gpu (default 0); the other GPUs are unused.
+
+We support mixed-GPU setups of differing size (e.g. a 24 GB Radeon + a 16 GB
+unified-memory iGPU). When the caller passes explicit --tensor-split ratios we
+use those; otherwise we split proportionally to each GPU's VRAM (layer mode) or
+to the given ratios (tensor mode). Unified-memory devices (system RAM acting
+as VRAM, e.g. AMD Strix Halo / Apple SoCs) are flagged so callers can warn that
+the estimate is fuzzy — that memory is shared with the OS.
 """
 
 from __future__ import annotations
@@ -13,6 +28,18 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 
 
+@dataclass
+class GpuSpec:
+    """A single device: its VRAM and whether it's unified (shared system RAM)."""
+    vram_gb: float
+    name: str = ""
+    is_unified: bool = False
+
+    @property
+    def vram_bytes(self) -> int:
+        return int(self.vram_gb * (1 << 30))
+
+
 @dataclass
 class GpuBudget:
     vram_bytes: list[int]
@@ -22,11 +49,14 @@ class GpuBudget:
 class GpuAssignment:
     index: int
     vram_bytes: int
-    weight_bytes: float
-    kv_compute_bytes: float
-    used_bytes: float
-    free_bytes: float
-    fits: bool
+    name: str = ""
+    is_unified: bool = False
+    weight_bytes: float = 0.0
+    kv_compute_bytes: float = 0.0
+    used_bytes: float = 0.0
+    free_bytes: float = 0.0
+    fits: bool = True
+    role: str = ""  # human note: "weights+KV", "weights", "all (main)", ...
 
 
 @dataclass
@@ -37,66 +67,163 @@ class GpuSplitResult:
     total_weights_bytes: float = 0.0
     total_kv_compute_bytes: float = 0.0
     all_fit: bool = False
-    kv_gpu_index: int = 0
+    split_mode: str = "layer"
+    main_gpu_index: int = 0
+    warnings: list[str] = field(default_factory=list)
+
+
+def _normalize_shares(ratios: list[float], n: int) -> list[float]:
+    """Turn a list of split ratios into n normalized shares summing to 1.
+
+    None/empty -> equal shares. Otherwise pad/truncate to n and normalize.
+    """
+    if not ratios:
+        s = [1.0] * n
+    else:
+        s = [float(r) for r in ratios[:n]]
+        while len(s) < n:
+            s.append(0.0)
+    tot = sum(s)
+    if tot <= 0:
+        s = [1.0] * n
+        tot = float(n)
+    return [x / tot for x in s]
 
 
 def gpu_split(
     *,
-    gpu_vram_bytes: list[int],
+    gpu_specs: list[GpuSpec] | None = None,
+    gpu_vram_bytes: list[int] | None = None,
     weights_bytes: float,
-    kv_compute_bytes: float,
-    kv_on_largest: bool = False,
+    kv_bytes: float,
+    scratch_bytes: float = 0.0,
+    split_mode: str = "layer",
+    main_gpu: int = 0,
+    tensor_split: list[float] | None = None,
+    cache_dtype_quantized: bool = False,
 ) -> GpuSplitResult:
-    """Split weights proportionally to VRAM; place KV+compute on one GPU."""
-    if not gpu_vram_bytes:
+    """Distribute weights, KV, and scratch across GPUs for a split mode.
+
+    `gpu_specs` is the preferred input; `gpu_vram_bytes` is accepted for
+    backward compatibility (each treated as a discrete, non-unified GPU).
+    `kv_bytes` is the model KV cache; `scratch_bytes` is the compute/activation
+    buffer, which is placed on the main GPU (the one running the active batch).
+    """
+    # Normalize inputs into a list of (vram_bytes, is_unified, name).
+    if gpu_specs is not None:
+        gpus = [(g.vram_bytes, g.is_unified, g.name) for g in gpu_specs]
+    elif gpu_vram_bytes is not None:
+        gpus = [(int(v), False, "") for v in gpu_vram_bytes]
+    else:
         return GpuSplitResult()
 
-    total_vram = sum(gpu_vram_bytes)
-    if total_vram <= 0:
-        return GpuSplitResult(
-            assignments=[
-                GpuAssignment(i, v, 0.0, 0.0, 0.0, float(v), True)
-                for i, v in enumerate(gpu_vram_bytes)
-            ],
-            total_vram_bytes=total_vram,
-        )
+    if not gpus:
+        return GpuSplitResult()
 
-    # weight share per gpu proportional to vram
-    weight_shares = [weights_bytes * (v / total_vram) for v in gpu_vram_bytes]
+    warns: list[str] = []
+    if any(u for _, u, _ in gpus):
+        warns.append(
+            "One or more devices is unified memory (shared system RAM); the "
+            "VRAM budget is fuzzy because that memory is also used by the OS."
+        )
 
-    # choose KV host
-    if kv_on_largest:
-        kv_idx = max(range(len(gpu_vram_bytes)), key=lambda i: gpu_vram_bytes[i])
-    else:
-        kv_idx = 0
+    n = len(gpus)
+    total_vram = sum(v for v, _, _ in gpus)
+    if main_gpu < 0 or main_gpu >= n:
+        main_gpu = 0
+
+    mode = split_mode if split_mode in ("layer", "tensor", "none") else "layer"
+
+    # --- split mode: none -------------------------------------------------
+    if mode == "none":
+        v, uni, nm = gpus[main_gpu]
+        used = weights_bytes + kv_bytes + scratch_bytes
+        assignments = []
+        for i, (vr, ur, nr) in enumerate(gpus):
+            if i == main_gpu:
+                assignments.append(GpuAssignment(
+                    index=i, vram_bytes=vr, name=nr, is_unified=ur,
+                    weight_bytes=weights_bytes, kv_compute_bytes=kv_bytes,
+                    used_bytes=used, free_bytes=vr - used, fits=used <= vr,
+                    role="all (main)",
+                ))
+            else:
+                assignments.append(GpuAssignment(
+                    index=i, vram_bytes=vr, name=nr, is_unified=ur,
+                    used_bytes=0.0, free_bytes=float(vr), fits=True,
+                    role="unused",
+                ))
+        return GpuSplitResult(
+            assignments=assignments, total_vram_bytes=total_vram,
+            total_used_bytes=used,
+            total_weights_bytes=weights_bytes,
+            total_kv_compute_bytes=kv_bytes,
+            all_fit=all(a.fits for a in assignments),
+            split_mode=mode, main_gpu_index=main_gpu, warnings=warns,
+        )
 
-    assignments = []
-    for i, vram in enumerate(gpu_vram_bytes):
-        w = weight_shares[i]
-        kv = kv_compute_bytes if i == kv_idx else 0.0
-        used = w + kv
-        free = vram - used
-        fits = used <= vram
-        assignments.append(
-            GpuAssignment(
-                index=i,
-                vram_bytes=vram,
-                weight_bytes=w,
-                kv_compute_bytes=kv,
-                used_bytes=used,
-                free_bytes=free,
-                fits=fits,
+    # --- split mode: tensor (experimental) -------------------------------
+    if mode == "tensor":
+        if cache_dtype_quantized:
+            warns.append(
+                "--split-mode tensor requires a non-quantized KV cache "
+                "(f16/bf16/f32); quantized KV is a hard error in llama.cpp."
             )
+        shares = _normalize_shares(tensor_split or [], n)
+        # tensor mode splits weights AND KV across all GPUs by the shares;
+        # scratch rides on the main GPU.
+        assignments = []
+        for i, (vr, ur, nr) in enumerate(gpus):
+            w = weights_bytes * shares[i]
+            kv = kv_bytes * shares[i]
+            sc = scratch_bytes if i == main_gpu else 0.0
+            used = w + kv + sc
+            assignments.append(GpuAssignment(
+                index=i, vram_bytes=vr, name=nr, is_unified=ur,
+                weight_bytes=w, kv_compute_bytes=kv,
+                used_bytes=used, free_bytes=vr - used, fits=used <= vr,
+                role="weights+KV" + ("+compute" if i == main_gpu else ""),
+            ))
+        return GpuSplitResult(
+            assignments=assignments, total_vram_bytes=total_vram,
+            total_used_bytes=sum(a.used_bytes for a in assignments),
+            total_weights_bytes=weights_bytes,
+            total_kv_compute_bytes=kv_bytes,
+            all_fit=all(a.fits for a in assignments),
+            split_mode=mode, main_gpu_index=main_gpu, warnings=warns,
         )
 
+    # --- split mode: layer (default, pipeline-parallel) ------------------
+    # Default split is proportional to each GPU's VRAM (llama.cpp's auto-split).
+    # If the user gave explicit --tensor-split ratios, use those as the weight
+    # proportions instead.
+    if tensor_split:
+        shares = _normalize_shares(tensor_split, n)
+    else:
+        if total_vram <= 0:
+            shares = [1.0 / n] * n
+        else:
+            shares = [v / total_vram for v, _, _ in gpus]
+    assignments = []
+    for i, (vr, ur, nr) in enumerate(gpus):
+        w = weights_bytes * shares[i]
+        # KV follows the layer that owns it -> distributed like the weights.
+        kv = kv_bytes * shares[i]
+        sc = scratch_bytes if i == main_gpu else 0.0
+        used = w + kv + sc
+        assignments.append(GpuAssignment(
+            index=i, vram_bytes=vr, name=nr, is_unified=ur,
+            weight_bytes=w, kv_compute_bytes=kv,
+            used_bytes=used, free_bytes=vr - used, fits=used <= vr,
+            role="weights+KV" + ("+compute" if i == main_gpu else ""),
+        ))
     return GpuSplitResult(
-        assignments=assignments,
-        total_vram_bytes=total_vram,
+        assignments=assignments, total_vram_bytes=total_vram,
         total_used_bytes=sum(a.used_bytes for a in assignments),
         total_weights_bytes=weights_bytes,
-        total_kv_compute_bytes=kv_compute_bytes,
+        total_kv_compute_bytes=kv_bytes,
         all_fit=all(a.fits for a in assignments),
-        kv_gpu_index=kv_idx,
+        split_mode=mode, main_gpu_index=main_gpu, warnings=warns,
     )
 
 

vramcalc/mmproj.py

@@ -0,0 +1,89 @@
+"""Multimodal projector (mmproj) memory.
+
+A multimodal projector (--mmproj file.gguf) is a separate small GGUF that
+holds the vision/audio encoder + adapter weights. It is GPU-offloaded by
+default (--no-mmproj-offload disables that). It has no KV cache of its own;
+its cost is just its weight tensor bytes plus a small activation scratch we
+fold into the compute budget.
+
+We size it by summing the tensor element counts from the mmproj GGUF header
+multiplied by each tensor's dtype bits-per-element. The mmproj files in the
+wild (e.g. mmproj-F16.gguf / mmproj-BF16.gguf) are almost entirely one dtype,
+so a per-dtype sum is accurate.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# bits per element for the dtypes mmproj files actually use. Sourced from the
+# GGML type enum; we only need the projector-relevant subset.
+_DTYPE_BPE: dict[int, float] = {
+    0: 32.0,   # F32
+    1: 16.0,   # F16
+    30: 16.0,  # BF16
+    2: 4.5,    # Q4_0
+    4: 4.0,    # Q4_1 (raw 4)
+    8: 8.5,    # Q8_0
+}
+
+
+@dataclass
+class Mmproj:
+    filename: str = ""
+    params: int = 0           # total tensor element count (sum of dims)
+    bytes_: float = 0.0        # weight bytes
+    offload: bool = True       # --mmproj-offload (default on)
+    enabled: bool = False
+
+
+@dataclass
+class MmprojBreakdown:
+    bytes_: float = 0.0
+    enabled: bool = False
+    offload: bool = True
+
+
+def mmproj_bytes_from_tensors(
+    tensor_elems_by_dtype: dict[int, int], params: int | None = None,
+) -> float:
+    """Sum tensor element counts * bits-per-element / 8 -> weight bytes.
+
+    `tensor_elems_by_dtype` maps GGML dtype id -> total element count for that
+    dtype (produced by a header walk). `params` is unused but kept for API
+    symmetry with the GGUFMetadata path.
+    """
+    total_bits = 0.0
+    for dtype, count in tensor_elems_by_dtype.items():
+        bpe = _DTYPE_BPE.get(dtype)
+        if bpe is None:
+            # unknown dtype: assume f16 (most mmproj tensors) as a fallback
+            bpe = 16.0
+        total_bits += count * bpe
+    return total_bits / 8.0
+
+
+def mmproj_bytes_from_meta(meta) -> float:
+    """Estimate projector weight bytes from a parsed GGUFMetadata/header.
+
+    Accepts a `GGUFMetadata` (has .raw dict and .params) or a raw metadata dict.
+    Uses general.parameter_count when present; otherwise sums tensor elems by
+    dtype if a tensor dtype histogram is available in meta['.tensor_dtypes'].
+    """
+    raw = getattr(meta, "raw", None)
+    if raw is None and isinstance(meta, dict):
+        raw = meta
+    if raw is None:
+        return 0.0
+
+    # Prefer an explicit tensor-dtype histogram if the caller attached one.
+    hist = raw.get(".tensor_dtype_hist") if isinstance(raw, dict) else None
+    if isinstance(hist, dict) and hist:
+        return mmproj_bytes_from_tensors(
+            {int(k): int(v) for k, v in hist.items()}
+        )
+    # Fall back to general.parameter_count * a default f16 bpw (2 bytes/elem).
+    pc = raw.get("general.parameter_count") if isinstance(raw, dict) else None
+    if pc:
+        return float(pc) * 2.0
+    return 0.0

vramcalc/report.py

@@ -4,10 +4,12 @@ from __future__ import annotations
 
 from dataclasses import dataclass, field
 
-from .quant import weight_bytes
-from .kv import kv_cache_bytes, compute_scratch_bytes
+from .quant import weight_bytes, QUANT_BPW
+from .kv import kv_cache_bytes, compute_scratch_bytes, cache_dtype_bytes
 from .yarn import yarn_effective_context, yarn_warnings
-from .gpu import gpu_split, GpuSplitResult
+from .gpu import gpu_split, GpuSplitResult, GpuSpec
+from .draft import DraftInputs, draft_bytes
+from .mmproj import Mmproj
 
 
 @dataclass
@@ -42,19 +44,33 @@ class Inputs:
     yarn_attn_factor: float = 1.0
     yarn_beta_fast: float = 32.0
     yarn_beta_slow: float = 1.0
-    # GPU
+    # GPU / multi-GPU
     gpu_vram_gb: list[float] = field(default_factory=lambda: [24.0])
-    kv_on_largest: bool = False
+    split_mode: str = "layer"        # layer | tensor | none
+    main_gpu: int = 0
+    tensor_split: list[float] | None = None   # explicit --tensor-split ratios
+    unified_flags: list[bool] | None = None   # per-device is_unified
+    # MTP
+    mtp_cache_dtype: str | None = None       # MTP extra-layer KV dtype (else cache_dtype)
+    # Speculative decoding
+    draft: DraftInputs | None = None
+    # Multimodal
+    mmproj: Mmproj | None = None
     # margin
     safety_margin_pct: float = 5.0
 
 
+_QUANTIZED_CACHE = {"q8_0", "q8_1", "q4_0", "q4_1", "q5_0", "q5_1"}
+
+
 @dataclass
 class Breakdown:
     weights_bytes: float = 0.0
     kv_cache_bytes: float = 0.0
     compute_scratch_bytes: float = 0.0
     mtp_overhead_bytes: float = 0.0
+    draft_bytes_: float = 0.0
+    mmproj_bytes_: float = 0.0
     gguf_overhead_bytes: float = 0.0
     safety_margin_bytes: float = 0.0
     total_bytes: float = 0.0
@@ -66,7 +82,9 @@ class Breakdown:
 def estimate(arch: ModelArch, inp: Inputs) -> Breakdown:
     weights = weight_bytes(arch.params, inp.quant)
 
-    # KV cache (with MTP layers folded in)
+    mtp_dt = inp.mtp_cache_dtype or inp.cache_dtype
+
+    # KV cache (target; MTP extra layers use mtp_dt when set)
     kv = kv_cache_bytes(
         n_layer=arch.n_layer,
         n_embd=arch.n_embd,
@@ -74,7 +92,7 @@ def estimate(arch: ModelArch, inp: Inputs) -> Breakdown:
         n_head_kv=arch.n_head_kv,
         n_ctx=inp.n_ctx,
         cache_dtype=inp.cache_dtype,
-        n_mtp=arch.n_mtp,
+        n_mtp=0,                     # MTP KV accounted separately for the dual-dtype case
         flash_attn=inp.flash_attn,
     )
 
@@ -91,29 +109,52 @@ def estimate(arch: ModelArch, inp: Inputs) -> Breakdown:
         n_mtp=arch.n_mtp,
     )
 
-    # isolate MTP overhead for display: the extra layer's weights + its KV share
+    # MTP overhead: the extra layers' weights + their KV (routed through the
+    # GPU split below, and also displayed separately).
     mtp_overhead = 0.0
     if arch.n_mtp > 0:
-        # approximate extra weight as one layer's worth: params/n_layer * bpw/8
         if arch.n_layer > 0:
             per_layer_params = arch.params / arch.n_layer
-            mtp_weights = per_layer_params * (
-                __import__("vramcalc.quant", fromlist=["QUANT_BPW"]).QUANT_BPW[inp.quant] / 8.0
-            )
+            mtp_weights = per_layer_params * (QUANT_BPW[inp.quant] / 8.0)
         else:
             mtp_weights = 0.0
-        # KV for the extra layers
         head_dim = arch.n_embd // arch.n_head if arch.n_head > 0 else 0
         mtp_kv = (
             arch.n_mtp * inp.n_ctx * 2 * arch.n_head_kv * head_dim
-            * __import__("vramcalc.kv", fromlist=["cache_dtype_bytes"]).cache_dtype_bytes(inp.cache_dtype)
+            * cache_dtype_bytes(mtp_dt)
         )
         mtp_overhead = mtp_weights + mtp_kv
 
+    # Draft model (speculative decoding): weights + its own KV.
+    draft_bd = draft_bytes(
+        draft=inp.draft or DraftInputs(),
+        target_n_ctx=inp.n_ctx,
+        target_n_embd=arch.n_embd,
+        target_n_head=arch.n_head,
+        target_n_head_kv=arch.n_head_kv,
+    ) if inp.draft is not None else None
+    draft_total = draft_bd.total_bytes if draft_bd and draft_bd.enabled else 0.0
+
+    # Multimodal projector.
+    mmproj_total = 0.0
+    if inp.mmproj is not None and inp.mmproj.enabled:
+        mmproj_total = inp.mmproj.bytes_
+
     # GGUF header / alignment overhead: small constant per file, rough estimate
     gguf_overhead = max(arch.n_layer * 4096, 1 << 20)  # >= 1 MiB
 
-    subtotal = weights + kv + scratch + gguf_overhead
+    # The split handles weights + KV (target) + MTP KV + draft (on main GPU) +
+    # mmproj (on main GPU, if offloaded). scratch rides on the main GPU.
+    split_weights = weights + mtp_weights_only(arch, inp)
+    split_kv = kv + (mtp_overhead - mtp_weights_only(arch, inp))
+    extra_main = draft_total  # draft rides on the main GPU
+    if inp.mmproj is not None and inp.mmproj.enabled and inp.mmproj.offload:
+        extra_main += mmproj_total
+
+    subtotal = (
+        weights + kv + scratch + mtp_overhead + draft_total + mmproj_total
+        + gguf_overhead
+    )
     margin = subtotal * (inp.safety_margin_pct / 100.0)
     total = subtotal + margin
 
@@ -126,19 +167,34 @@ def estimate(arch: ModelArch, inp: Inputs) -> Breakdown:
         yarn_attn_factor=inp.yarn_attn_factor,
     )
 
-    gpu_vram_bytes = [int(g * (1 << 30)) for g in inp.gpu_vram_gb]
+    # GPU split
+    specs = _gpu_specs(inp)
     gpu = gpu_split(
-        gpu_vram_bytes=gpu_vram_bytes,
-        weights_bytes=weights,
-        kv_compute_bytes=kv + scratch,
-        kv_on_largest=inp.kv_on_largest,
+        gpu_specs=specs,
+        weights_bytes=split_weights,
+        kv_bytes=split_kv,
+        scratch_bytes=scratch + extra_main,
+        split_mode=inp.split_mode,
+        main_gpu=inp.main_gpu,
+        tensor_split=inp.tensor_split,
+        cache_dtype_quantized=inp.cache_dtype in _QUANTIZED_CACHE,
     )
+    warns.extend(gpu.warnings)
+
+    if inp.split_mode == "tensor" and not inp.flash_attn:
+        warns.append("--split-mode tensor requires flash attention on.")
+    if inp.split_mode == "tensor" and inp.cache_dtype in _QUANTIZED_CACHE:
+        warns.append(
+            "--split-mode tensor disallows quantized KV cache; use f16/bf16/f32."
+        )
 
     return Breakdown(
         weights_bytes=weights,
         kv_cache_bytes=kv,
         compute_scratch_bytes=scratch,
         mtp_overhead_bytes=mtp_overhead,
+        draft_bytes_=draft_total,
+        mmproj_bytes_=mmproj_total,
         gguf_overhead_bytes=gguf_overhead,
         safety_margin_bytes=margin,
         total_bytes=total,
@@ -148,6 +204,22 @@ def estimate(arch: ModelArch, inp: Inputs) -> Breakdown:
     )
 
 
+def mtp_weights_only(arch: ModelArch, inp: Inputs) -> float:
+    """The weight portion of the MTP overhead (the KV portion is split_kv)."""
+    if arch.n_mtp <= 0 or arch.n_layer <= 0:
+        return 0.0
+    per_layer_params = arch.params / arch.n_layer
+    return per_layer_params * (QUANT_BPW[inp.quant] / 8.0)
+
+
+def _gpu_specs(inp: Inputs) -> list[GpuSpec]:
+    flags = inp.unified_flags or ([False] * len(inp.gpu_vram_gb))
+    return [
+        GpuSpec(vram_gb=v, is_unified=(i < len(flags) and flags[i]))
+        for i, v in enumerate(inp.gpu_vram_gb)
+    ]
+
+
 def format_bytes(n: float) -> str:
     """Human-readable byte size."""
     n = float(n)
@@ -180,10 +252,44 @@ def command_preview(arch: ModelArch, inp: Inputs) -> str:
         parts.append(f"--cache-type-v {inp.cache_dtype}")
     if inp.flash_attn:
         parts.append("--flash-attn")
-    if len(inp.gpu_vram_gb) > 1:
-        # tensor-split proportional to vram
-        split = ",".join(f"{g}" for g in inp.gpu_vram_gb)
-        parts.append(f"--tensor-split {split}")
+
+    # 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
+    if multi or inp.split_mode != "layer":
+        parts.append(f"--split-mode {inp.split_mode}")
+    if inp.split_mode == "none":
+        parts.append(f"--main-gpu {inp.main_gpu}")
+    if multi and inp.tensor_split:
+        parts.append(
+            "--tensor-split " + ",".join(str(s) for s in inp.tensor_split)
+        )
+
+    # MTP draft KV dtype (only when it differs from the target KV dtype)
+    if arch.n_mtp > 0 and inp.mtp_cache_dtype and inp.mtp_cache_dtype != inp.cache_dtype:
+        # llama.cpp applies a single -ctk/-ctv; we note the MTP draft dtype.
+        parts.append(
+            f"# MTP draft KV dtype: {inp.mtp_cache_dtype} (target: {inp.cache_dtype})"
+        )
+
+    # Speculative decoding draft model
+    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}")
+
+    # Multimodal projector
+    if inp.mmproj is not None and inp.mmproj.enabled:
+        parts.append(f"--mmproj {inp.mmproj.filename or 'mmproj.gguf'}")
+        if not inp.mmproj.offload:
+            parts.append("--no-mmproj-offload")
+
     # YaRN / rope
     yarn_args = []
     if inp.rope_freq_scale != 1.0: