mtplx 2.4.1__tar.gz → 2.4.2__tar.gz

{mtplx-2.4.1 → mtplx-2.4.2}/CHANGELOG.md

@@ -4,6 +4,107 @@ All notable user-facing changes to MTPLX. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
 [Semantic Versioning](https://semver.org/).
 
+## [2.4.2] - 2026-08-02
+
+The agentic-cache release: the session cache stops losing warm state
+mid-run, tool-turn commits stop being ghosts, every serve keeps a durable
+per-request trail by default, an experimental DeepSeek-V4-Flash backend
+lands, and the documentation now matches the code everywhere it was
+audited.
+
+### Added
+
+- DeepSeek-V4-Flash: experimental native AR backend
+  (`model_type: deepseek_v4`) — Hyper-Connections, compressed sparse
+  attention, hash-routed MoE, grouped output-LoRA — loading the
+  mlx-community checkpoints directly, with an optional single-block MTP
+  speculative lane when the checkpoint carries `mtp.0.*` weights
+  (spec == AR gated; K=1-3 measured up to 2.28x on the 2bit-DQ build).
+  MTP-declaring checkpoints that ship no draft weights degrade to AR
+  with a clear message instead of failing at bind. Thanks @davidtai
+  (#216).
+- Request log, default on: every serve writes numeric/hash per-request
+  telemetry to `~/.mtplx/logs/request-log-<port>.jsonl` (64 MB x 4
+  rotation; no prompt or completion content; disable with
+  `MTPLX_REQUEST_LOG_JSONL=off`). Pairs with 2.4.1's opt-in bit-exact
+  request capture to make agent-session incidents diagnosable after the
+  fact (#196/#197). New helpers: `scripts/gauntlet_scoreboard.py`
+  per-session summarizer, `scripts/oc_tap.py` recording proxy and
+  `scripts/oc_tap_diff.py` request-mutation analyzer for content-level
+  wire truth.
+- Session bank, active-session eviction protection: sessions that
+  touched the bank within `MTPLX_SESSION_BANK_ACTIVE_PIN_TTL_S`
+  (default 600 s) are eviction-last, so cross-session pressure evicts
+  idle victims instead of the session that is mid-run.
+- Session bank, newest-K per-session snapshot retention
+  (`MTPLX_SESSION_BANK_PER_SESSION_MAX_ENTRIES`, default 3): divergent
+  per-turn sibling snapshots no longer accumulate unreclaimed.
+  `/health` now reports active sessions, the pin TTL, and recent
+  evictions.
+- Postcommit foreground grace (`MTPLX_POSTCOMMIT_FOREGROUND_GRACE_S`,
+  default 2 s): a nearly-finished background cache commit lands instead
+  of being preempted by the next fast agent-loop request.
+- Session identity honors `x-session-affinity` / `x-session-id` request
+  headers (OpenCode sends these per request), ending cross-request
+  identity churn on that client.
+
+### Fixed
+
+- Tool-turn "ghost re-prefills": the tool-rewrite async commit rendered
+  a canonical history that matched neither the generation nor the next
+  prompt, burning full-history re-forwards (26.8 s observed) without
+  ever storing. It is disabled pending a byte-proven canonical render
+  (`MTPLX_IDLE_POSTCOMMIT_TOOL_REWRITE` re-enables);
+  store-on-prefill and block salvage cover the lane.
+- The bridge's convergence guard now states explicitly that editing and
+  verification tools remain allowed and that its restriction covers
+  only the current reply — a model read the old wording as a
+  session-wide tool ban and stalled an entire session.
+- `mtplx profile thermal`, `profile eval-attribution`,
+  `profile dispatch --trace`, and `thermal fanmax-run` invoked
+  research-workspace scripts that are not part of the distribution, and
+  `--dry-run` printed those phantom paths as runnable commands. They
+  now report availability honestly (exit 2, machine-readable
+  `available: false`) and run the real script when present.
+- `mtplx doctor`: Python floor corrected to 3.11 (matching
+  `requires-python`); remediation texts no longer tell end users to
+  edit source constants or to move a healthy server off its port;
+  `--port` is documented and, when passed explicitly, aims the server
+  connectivity checks.
+- Session-bank near-prefix restores on backends with bounded rollback
+  (DeepSeek-V4) pre-check `max_rollback` and fall back to a cold
+  prefill instead of raising (#216).
+- Help surfaces match their own parsers: the onboarding help no longer
+  promises a Turbo wizard choice that does not exist (Turbo
+  auto-selects for the quantized flagships), `--strict-cold` names the
+  enforced 59 tok/s gate, `--open-dashboard` opens alongside the chosen
+  client (as it always did), and the command reference teaches
+  `mtplx <command> --help`, which also works for multi-word commands.
+
+### Documentation
+
+- Full truth sweep: ~450 documentation claims reconciled against the
+  code across 27 files. Highlights: INSTALL.md no longer references an
+  MLX fork removed in 2.0.0; turbo-verify.md no longer calls the
+  shipped default "experimental, off by default" nor excludes the
+  6-bit lane that ships; the Anthropic base-URL instruction (docs and
+  the canonical example) no longer 404s; `/metrics` no longer claims a
+  Prometheus mode that never existed; the README modes table shows
+  Turbo as the default for the quantized 27B/9B flagships; the Laguna
+  memory requirement states the real ~85.3 GiB preflight gate;
+  version-era staleness ("v0.1", "preview", v0.3.x runbook pins) is
+  cleared; historical release notes gain bracketed corrections where
+  they documented commands that never worked. Thanks
+  @PhilipJohnBasile for #218 (removed the unsupported MTP-sidecar
+  graft guidance; seeded by #215).
+- Dependency-record correction: the transformers pin has been
+  `<5.14,!=5.13.0` since shortly after 2.0.0; the changelog never
+  recorded the relaxation from `<5.13`.
+
+### Dependencies
+
+- pypa/gh-action-pypi-publish 1.14.1 -> 1.14.2 (#217).
+
 ## [2.4.1] - 2026-08-01
 
 The smooth-streaming release: the app's chat render path is overhauled
@@ -726,4 +827,17 @@ working as one product. Full notes:
   completions, and Anthropic `stop_sequences`) and `/v1/completions`
   streams tokens as they are generated with real finish reasons.
 
-[1.0.0]: https://github.com/youssofal/mtplx/releases/tag/v1.0.0
+[2.4.2]: https://github.com/youssofal/MTPLX/releases/tag/v2.4.2
+[2.4.1]: https://github.com/youssofal/MTPLX/releases/tag/v2.4.1
+[2.4.0]: https://github.com/youssofal/MTPLX/releases/tag/v2.4.0
+[2.3.0]: https://github.com/youssofal/MTPLX/releases/tag/v2.3.0
+[2.2.0]: https://github.com/youssofal/MTPLX/releases/tag/v2.2.0
+[2.1.0]: https://github.com/youssofal/MTPLX/releases/tag/v2.1.0
+[2.0.2]: https://github.com/youssofal/MTPLX/releases/tag/v2.0.2
+[2.0.1]: https://github.com/youssofal/MTPLX/releases/tag/v2.0.1
+[2.0.0]: https://github.com/youssofal/MTPLX/releases/tag/v2.0.0
+[1.0.4]: https://github.com/youssofal/MTPLX/releases/tag/v1.0.4
+[1.0.3]: https://github.com/youssofal/MTPLX/releases/tag/v1.0.3
+[1.0.2]: https://github.com/youssofal/MTPLX/releases/tag/v1.0.2
+[1.0.1]: https://github.com/youssofal/MTPLX/releases/tag/v1.0.1
+[1.0.0]: https://github.com/youssofal/MTPLX/releases/tag/v1.0.0

{mtplx-2.4.1 → mtplx-2.4.2}/CITATION.cff

@@ -8,7 +8,7 @@ authors:
 repository-code: "https://github.com/youssofal/mtplx"
 url: "https://github.com/youssofal/mtplx"
 license: Apache-2.0
-version: 0.1.0rc1
+version: 2.4.2
 abstract: "Native MTP speculative decoding for Qwen3-Next on Apple Silicon, using built-in MTP heads with math-correct rejection sampling and an OpenAI/Anthropic-compatible serving surface."
 keywords:
   - speculative decoding

{mtplx-2.4.1 → mtplx-2.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mtplx
-Version: 2.4.1
+Version: 2.4.2
 Summary: Native MTP speculative decoding for Qwen3-Next on Apple Silicon.
 Author-email: Youssof Altoukhi <business@youssofal.com>
 License-Expression: Apache-2.0
@@ -105,9 +105,11 @@ On a 16 GB M4 Mac mini, tuning the 9B model lands on depth 1: 14.4 tok/s baselin
 
 <img src="docs/assets/readme/app-forge.jpg" alt="Forge verifying a freshly built MTP model" width="100%" />
 
-Forge takes a Hugging Face repo and turns it into an MTPLX-ready MTP model: convert to MLX, train the MTP adapter, verify that the result is actually faster and still exact, and publish back to the Hub if you want to share it. The honest part matters: Forge measures before and after on your hardware and shows you the verdict ("Depth 1 is fastest: 227.1 to 296.1, 1.30x") rather than assuming the adapter helped. Available in the app and as `mtplx forge`.
+Forge takes a Hugging Face repo and turns it into an MTPLX-ready MTP model: convert to MLX, train the MTP adapter, verify that the result is actually faster and still exact, and publish back to the Hub if you want to share it. The honest part matters: Forge measures before and after on your hardware and shows you the verdict ("Depth 1 is fastest: 227.1 to 296.1, 1.30x") rather than assuming the adapter helped. Available in the app and as `mtplx forge` subcommands.
 
-The official catalog lives on Hugging Face under [Youssofal](https://huggingface.co/Youssofal): Qwen 3.5 (4B, 9B), Qwen 3.6 (27B, 35B MoE) in speed, balance, and quality builds, plus Gemma 4. The app recommends from these based on your hardware.
+MTPLX does not support attaching a separately supplied MTP sidecar to an arbitrary MLX trunk. Matching architecture fields, tensor shapes, or provenance labels cannot prove that the head was trained against those exact trunk weights. Use a complete model that already includes its matching MTP weights, or use Forge to build and verify an artifact from its original source checkpoint.
+
+The official catalog lives on Hugging Face under [Youssofal](https://huggingface.co/Youssofal): Qwen 3.5 (4B, 9B), Qwen 3.6 (27B, 35B MoE) in speed and quality builds (the 35B MoE adds a balance build), plus Gemma 4. The app recommends from these based on your hardware.
 
 ## The server
 
@@ -119,7 +121,7 @@ curl http://127.0.0.1:8000/v1/chat/completions \
   -d '{"model":"mtplx","messages":[{"role":"user","content":"hi"}],"stream":true}'
 ```
 
-Sessions survive: a warm-prefix session bank keeps multi-turn chats fast, and an optional SSD cache restores sessions near-instantly across restarts.
+Sessions survive: a warm-prefix session bank keeps multi-turn chats fast, and a default-on SSD session cache restores sessions near-instantly across restarts (disable with `--ssd-session-cache off`).
 
 Sampler controls cover `temperature`, `top_p`, `top_k`, and the OpenAI penalty pair `presence_penalty` / `frequency_penalty` — per request, as server defaults (`--default-presence-penalty` / `--default-frequency-penalty` on `start`/`serve`/`quickstart`), or live via `mtplx settings set` and the app's Presence Penalty dial. Penalties default to 0, which is an exact no-op that preserves MTP exactness. Qwen's guidance: leave them at 0 for coding and agent work; ~0.5–1.5 presence penalty helps creative writing or when a model loops on itself.
 
@@ -133,20 +135,21 @@ mtplx pull <hf-repo>       # download a model safely
 mtplx models               # what is cached, sizes, validation
 mtplx inspect <model>      # compatibility report before anything runs
 mtplx tune --retune        # measure AR vs D1/D2/D3 on your Mac
-mtplx forge                # build, verify, and publish MTP models
+mtplx forge --help         # build, verify, and publish MTP models (probe/build/publish/verify subcommands)
 mtplx bench aime --quick   # run the AIME benchmark from the terminal
 mtplx doctor               # install and integration health
 mtplx max --install        # fan control (one sudo prompt, crash-safe)
 mtplx settings get/set     # read or change live server settings
 ```
 
-Every command takes `--json` and `--help`. The CLI works without MLX installed for everything that does not need a model, so `doctor` and `inspect` run on any machine.
+Every command takes `--help`, and most inspection/diagnostic commands take `--json`. The CLI works without MLX installed for everything that does not need a model, so `doctor` and `inspect` run on any machine.
 
 ## Modes
 
 | Mode | What it does | When |
 |---|---|---|
-| **Sustained** | Default. Long-context MTP path with chunked prefill and request-sized KV | Everyday use, big files, 16K-200K prompts |
+| **Turbo** | NAX verify kernels + compiled verify; the default for the quantized 27B and 9B flagship models | Picked automatically for those models |
+| **Sustained** | Default for all other models. Long-context MTP path with chunked prefill and request-sized KV | Everyday use, big files, 16K-200K prompts |
 | **Sustained Max** | Sustained with fans pinned at 100% | Long work where you want maximum cooling |
 | **Burst** | Legacy short-context benchmark lane, loud | Short prompts and benchmarks only |
 
@@ -154,7 +157,7 @@ Fan-backed modes restore your fans to automatic if MTPLX dies for any reason, in
 
 ## Compatibility, honestly
 
-`mtplx inspect` classifies models before anything runs: verified, architecture-compatible but unverified, AR-only, incompatible architecture, or no MTP heads at all. Unverified models refuse to run unless you explicitly force them. There are no silent fallbacks: if MTPLX cannot run a model correctly, it tells you instead of running it badly.
+`mtplx inspect` classifies models before anything runs: verified, family-compatible but unverified, architecture-compatible but unverified, AR-only, incompatible architecture, or no MTP heads at all. Unverified models load with an explicit unverified label. There are no silent fallbacks: if MTPLX cannot run a model correctly, it tells you instead of running it badly.
 
 [Laguna-S-2.1 oQ4e](https://huggingface.co/mlx-community/Laguna-S-2.1-oQ4e) is supported through its exact MLX architecture in target-only AR mode:
 
@@ -170,8 +173,10 @@ MTPLX pins that model to revision
 tokenizer, generation config, special tokens map, and Poolside chat template
 before admitting it. The checkpoint has no native MTP head, so an MTP launch is
 rejected before weights load instead of falling back during execution. The
-weights occupy 59.72 GiB (64.13 GB); use a Mac with at least 96 GiB unified
-memory (128 GiB is recommended). MTPLX defaults Laguna to a 32,768-token context
+weights occupy 59.72 GiB, a 64.13 GB snapshot on disk. The launch preflight
+requires about 85 GiB of unified memory (weights, runtime headroom, and a
+16 GiB system reserve) — in practice a 96 GB Mac; 128 GB is
+comfortable. MTPLX defaults Laguna to a 32,768-token context
 and response cap, and checks larger explicit server contexts against the active
 Metal memory cap.
 

{mtplx-2.4.1 → mtplx-2.4.2}/README.md

@@ -55,9 +55,11 @@ On a 16 GB M4 Mac mini, tuning the 9B model lands on depth 1: 14.4 tok/s baselin
 
 <img src="docs/assets/readme/app-forge.jpg" alt="Forge verifying a freshly built MTP model" width="100%" />
 
-Forge takes a Hugging Face repo and turns it into an MTPLX-ready MTP model: convert to MLX, train the MTP adapter, verify that the result is actually faster and still exact, and publish back to the Hub if you want to share it. The honest part matters: Forge measures before and after on your hardware and shows you the verdict ("Depth 1 is fastest: 227.1 to 296.1, 1.30x") rather than assuming the adapter helped. Available in the app and as `mtplx forge`.
+Forge takes a Hugging Face repo and turns it into an MTPLX-ready MTP model: convert to MLX, train the MTP adapter, verify that the result is actually faster and still exact, and publish back to the Hub if you want to share it. The honest part matters: Forge measures before and after on your hardware and shows you the verdict ("Depth 1 is fastest: 227.1 to 296.1, 1.30x") rather than assuming the adapter helped. Available in the app and as `mtplx forge` subcommands.
 
-The official catalog lives on Hugging Face under [Youssofal](https://huggingface.co/Youssofal): Qwen 3.5 (4B, 9B), Qwen 3.6 (27B, 35B MoE) in speed, balance, and quality builds, plus Gemma 4. The app recommends from these based on your hardware.
+MTPLX does not support attaching a separately supplied MTP sidecar to an arbitrary MLX trunk. Matching architecture fields, tensor shapes, or provenance labels cannot prove that the head was trained against those exact trunk weights. Use a complete model that already includes its matching MTP weights, or use Forge to build and verify an artifact from its original source checkpoint.
+
+The official catalog lives on Hugging Face under [Youssofal](https://huggingface.co/Youssofal): Qwen 3.5 (4B, 9B), Qwen 3.6 (27B, 35B MoE) in speed and quality builds (the 35B MoE adds a balance build), plus Gemma 4. The app recommends from these based on your hardware.
 
 ## The server
 
@@ -69,7 +71,7 @@ curl http://127.0.0.1:8000/v1/chat/completions \
   -d '{"model":"mtplx","messages":[{"role":"user","content":"hi"}],"stream":true}'
 ```
 
-Sessions survive: a warm-prefix session bank keeps multi-turn chats fast, and an optional SSD cache restores sessions near-instantly across restarts.
+Sessions survive: a warm-prefix session bank keeps multi-turn chats fast, and a default-on SSD session cache restores sessions near-instantly across restarts (disable with `--ssd-session-cache off`).
 
 Sampler controls cover `temperature`, `top_p`, `top_k`, and the OpenAI penalty pair `presence_penalty` / `frequency_penalty` — per request, as server defaults (`--default-presence-penalty` / `--default-frequency-penalty` on `start`/`serve`/`quickstart`), or live via `mtplx settings set` and the app's Presence Penalty dial. Penalties default to 0, which is an exact no-op that preserves MTP exactness. Qwen's guidance: leave them at 0 for coding and agent work; ~0.5–1.5 presence penalty helps creative writing or when a model loops on itself.
 
@@ -83,20 +85,21 @@ mtplx pull <hf-repo>       # download a model safely
 mtplx models               # what is cached, sizes, validation
 mtplx inspect <model>      # compatibility report before anything runs
 mtplx tune --retune        # measure AR vs D1/D2/D3 on your Mac
-mtplx forge                # build, verify, and publish MTP models
+mtplx forge --help         # build, verify, and publish MTP models (probe/build/publish/verify subcommands)
 mtplx bench aime --quick   # run the AIME benchmark from the terminal
 mtplx doctor               # install and integration health
 mtplx max --install        # fan control (one sudo prompt, crash-safe)
 mtplx settings get/set     # read or change live server settings
 ```
 
-Every command takes `--json` and `--help`. The CLI works without MLX installed for everything that does not need a model, so `doctor` and `inspect` run on any machine.
+Every command takes `--help`, and most inspection/diagnostic commands take `--json`. The CLI works without MLX installed for everything that does not need a model, so `doctor` and `inspect` run on any machine.
 
 ## Modes
 
 | Mode | What it does | When |
 |---|---|---|
-| **Sustained** | Default. Long-context MTP path with chunked prefill and request-sized KV | Everyday use, big files, 16K-200K prompts |
+| **Turbo** | NAX verify kernels + compiled verify; the default for the quantized 27B and 9B flagship models | Picked automatically for those models |
+| **Sustained** | Default for all other models. Long-context MTP path with chunked prefill and request-sized KV | Everyday use, big files, 16K-200K prompts |
 | **Sustained Max** | Sustained with fans pinned at 100% | Long work where you want maximum cooling |
 | **Burst** | Legacy short-context benchmark lane, loud | Short prompts and benchmarks only |
 
@@ -104,7 +107,7 @@ Fan-backed modes restore your fans to automatic if MTPLX dies for any reason, in
 
 ## Compatibility, honestly
 
-`mtplx inspect` classifies models before anything runs: verified, architecture-compatible but unverified, AR-only, incompatible architecture, or no MTP heads at all. Unverified models refuse to run unless you explicitly force them. There are no silent fallbacks: if MTPLX cannot run a model correctly, it tells you instead of running it badly.
+`mtplx inspect` classifies models before anything runs: verified, family-compatible but unverified, architecture-compatible but unverified, AR-only, incompatible architecture, or no MTP heads at all. Unverified models load with an explicit unverified label. There are no silent fallbacks: if MTPLX cannot run a model correctly, it tells you instead of running it badly.
 
 [Laguna-S-2.1 oQ4e](https://huggingface.co/mlx-community/Laguna-S-2.1-oQ4e) is supported through its exact MLX architecture in target-only AR mode:
 
@@ -120,8 +123,10 @@ MTPLX pins that model to revision
 tokenizer, generation config, special tokens map, and Poolside chat template
 before admitting it. The checkpoint has no native MTP head, so an MTP launch is
 rejected before weights load instead of falling back during execution. The
-weights occupy 59.72 GiB (64.13 GB); use a Mac with at least 96 GiB unified
-memory (128 GiB is recommended). MTPLX defaults Laguna to a 32,768-token context
+weights occupy 59.72 GiB, a 64.13 GB snapshot on disk. The launch preflight
+requires about 85 GiB of unified memory (weights, runtime headroom, and a
+16 GiB system reserve) — in practice a 96 GB Mac; 128 GB is
+comfortable. MTPLX defaults Laguna to a 32,768-token context
 and response cap, and checks larger explicit server contexts against the active
 Metal memory cap.
 

{mtplx-2.4.1 → mtplx-2.4.2}/mtplx/artifacts.py

@@ -313,6 +313,62 @@ def expected_mtp_file(model_dir: Path | str, config: dict[str, Any] | None = Non
     return model_path / "mtp.safetensors"
 
 
+def mtp_weights_present_on_disk(
+    model_dir: Path | str, config: dict[str, Any] | None = None
+) -> bool:
+    """Whether a model that declares MTP layers actually ships MTP weights.
+
+    A conversion can declare ``num_nextn_predict_layers`` in the config while
+    dropping the MTP weights themselves (e.g. the DeepSeek-V4-Flash 2bit-DQ
+    build). The runtime uses this probe to tell that benign case (config field
+    only -> degrade to autoregressive) apart from a genuine injection failure
+    (weights present but unusable -> raise).
+
+    Conservative by design: it only returns ``False`` when it can *positively*
+    confirm absence via a shard index that carries no MTP-shaped keys under any
+    known naming convention. A sidecar file, a missing/unreadable index, or any
+    ambiguity returns ``True`` so the existing injection + validation path runs
+    unchanged and a real detection bug on an MTP-bearing model still surfaces.
+    """
+    model_path = Path(model_dir)
+    config = config if config is not None else load_config(model_path)
+
+    # 1. Explicit MTP sidecar file (Qwen/GLM/hy3 external draft head).
+    if expected_mtp_file(model_path, config).exists():
+        return True
+
+    index_path = model_path / "model.safetensors.index.json"
+    if not index_path.exists():
+        # No index to inspect: cannot prove absence, preserve legacy behavior.
+        return True
+    try:
+        weight_map = json.loads(index_path.read_text(encoding="utf-8")).get(
+            "weight_map", {}
+        )
+    except Exception:
+        return True
+    keys = [str(k) for k in weight_map]
+
+    # 2. Namespaced embedded MTP weights ("mtp.*" / "language_model.mtp.*").
+    if any(is_mtp_key(k) for k in keys):
+        return True
+
+    # 3. DeepSeek-style trailing MTP decoder layer(s) appended after the trunk:
+    #    model.layers.{num_hidden_layers + i}.*
+    start = int(
+        text_config(config).get("num_hidden_layers")
+        or config.get("num_hidden_layers")
+        or 0
+    )
+    count = _num_mtp_layers(config)
+    if start and count:
+        wanted = tuple(f"model.layers.{start + i}." for i in range(count))
+        if any(k.startswith(wanted) for k in keys):
+            return True
+
+    return False
+
+
 @dataclass(frozen=True)
 class TensorInfo:
     key: str

{mtplx-2.4.1 → mtplx-2.4.2}/mtplx/backends/registry.py

@@ -13,6 +13,7 @@ from mtplx.profiles import DEFAULT_PROFILE_NAME, PROFILE_CHOICES, resolve_profil
 RUNTIME_CONTRACT_FILE = "mtplx_runtime.json"
 SUPPORTED_ARCH_IDS = {
     "laguna-s-2.1-ar",
+    "deepseek-v4",
     "qwen3-next-mtp",
     "deepseek-v3-mtp",
     "glm-moe-dsa-mtp",
@@ -192,18 +193,65 @@ ARCHITECTURE_CATALOG: dict[str, ArchitectureSupport] = {
             "MTPLX routes verified-contract artifacts through the DeepSeek MTP backend."
         ),
     ),
+    "deepseek-v4": ArchitectureSupport(
+        arch_id="deepseek-v4",
+        display_name="DeepSeek-V4-Flash (MLX)",
+        family="deepseek",
+        backend="deepseek_v4",
+        support_level="experimental-native-ar-only",
+        runtime_compatibility="native-ar-only",
+        can_run_verified=True,
+        # Keep aliases minimal: "deepseek_v4" is a substring of "deepseek_v4_mtp",
+        # so a longer alias here would out-sort (and wrongly capture) the
+        # deepseek-v4-mtp split config. Detection of the AR checkpoint works via
+        # this alias / the model_type; the MTP-split entry keeps priority for its
+        # own longer "deepseek_v4_mtp" marker.
+        aliases=("deepseek_v4",),
+        config_markers=(),
+        family_gate="deepseek-v4-mlx",
+        references=(
+            "https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash",
+            "https://huggingface.co/mlx-community/DeepSeek-V4-Flash-4bit",
+            "REFERENCES:TOOLS/DeepSeek-V4-Flash/inference/model.py",
+        ),
+        notes=(
+            "Native MLX loader (mtplx.models.deepseek_v4) for DeepSeek-V4-Flash. "
+            "V4 adds Hyper-Connections, Compressed-Sparse-Attention, grouped "
+            "output-LoRA, and hash layers over V3.2. This is also the runnable "
+            "V4 MTP arch: the draft block (mtp.0.*) binds through the ordinary "
+            "load path when the checkpoint ships it, and the speculative lane "
+            "drives it through mtplx.generation like every other native MTP "
+            "backend. The published mlx-community conversions drop the block "
+            "while still declaring num_nextn_predict_layers, which is the case "
+            "the runtime's degrade-to-autoregressive branch covers -- those keep "
+            "running target-only (mtp=False). The runtime_compatibility field "
+            "stays 'native-ar-only' because it is what routes a checkpoint with "
+            "no draft head to the AR-only verdict; an MTP-bearing artifact is "
+            "resolved dynamically by the family gate instead."
+        ),
+    ),
     "deepseek-v4-mtp": ArchitectureSupport(
         arch_id="deepseek-v4-mtp",
-        display_name="DeepSeek V4 MTP",
+        display_name="DeepSeek V4 MTP (split checkpoint)",
         family="deepseek",
         backend="deepseek_v4_mtp",
         support_level="recognized-backend-pending",
         runtime_compatibility="recognized-backend-pending",
-        aliases=("deepseek_v4", "deepseek_v4_mtp"),
+        aliases=("deepseek_v4_mtp",),
         references=(
             "REFERENCES:TOOLS/vllm-official-main/vllm/model_executor/models/deepseek_v4_mtp.py",
         ),
-        notes="Detected separately because vLLM split the V4 MTP implementation from DeepSeek V3.",
+        notes=(
+            "vLLM's SPLIT V4 MTP layout: a standalone checkpoint carrying only "
+            "the draft module (model_type deepseek_v4_mtp / "
+            "DeepseekV4MTPForCausalLM), which vLLM separated out from DeepSeek "
+            "V3. MTPLX now has a real V4 draft-head runtime, but it is not this "
+            "artifact shape -- it loads a MERGED directory whose ordinary shards "
+            "carry mtp.0.* beside the trunk, which detects as arch_id "
+            "'deepseek-v4'. This entry stays pending because MTPLX has no loader "
+            "that assembles a target from two separate repos, not because the "
+            "backend is missing."
+        ),
     ),
     "glm4-moe-mtp": ArchitectureSupport(
         arch_id="glm4-moe-mtp",
@@ -985,7 +1033,18 @@ def _passes_nemotron_h_gate(inspection: Any) -> bool:
     return _has_marker_under_prefixes(keys, last_prefixes, ("final_layernorm.weight",))
 
 
+def _passes_deepseek_v4_gate(inspection: Any) -> bool:
+    """DeepSeek-V4-Flash MLX artifact: model_type deepseek_v4 (or the
+    DeepseekV4ForCausalLM architecture).  The mlx-community conversion drops the
+    MTP block, so this is a target-only AR gate with no MTP-marker requirement."""
+    model_type = _text(getattr(inspection, "model_type", None))
+    architecture = _compact(_text(getattr(inspection, "architecture", None)))
+    return model_type == "deepseek_v4" or "deepseekv4forcausallm" in architecture
+
+
 def _passes_family_runtime_gate(arch_id: str, inspection: Any, tensor_gate: bool) -> bool:
+    if arch_id == "deepseek-v4":
+        return _passes_deepseek_v4_gate(inspection)
     if arch_id == "laguna-s-2.1-ar":
         return bool(
             getattr(inspection, "laguna_s_2_1_mlx_4bit_match", False)
@@ -1259,9 +1318,11 @@ def compatibility_for_inspection(inspection: Any) -> CompatibilityVerdict:
                 message=(
                     f"{marker_text}, but this folder does not contain runnable "
                     "Qwen MTP tensors. mtplx_runtime.json is optional metadata; "
-                    "the blocker is missing MTP weights. Use a model with "
-                    "mtp.safetensors, embedded mtp.* / language_model.mtp.* "
-                    "weights, or graft an MTP sidecar into this base model."
+                    "the blocker is missing MTP weights. Use a complete model with "
+                    "mtp.safetensors or embedded mtp.* / language_model.mtp.* "
+                    "weights, or build and verify one from its original source with "
+                    "Forge. MTPLX cannot safely attach an arbitrary sidecar: matching "
+                    "tensor shapes do not prove it was trained for this trunk."
                 ),
                 recommended_backend="qwen3_next",
                 recommended_profile=DEFAULT_PROFILE_NAME,

{mtplx-2.4.1 → mtplx-2.4.2}/mtplx/cli.py

@@ -76,12 +76,12 @@ NATIVE_MTP_60_MODEL = DEFAULT_MODEL_ID
 
 
 PUBLIC_COMMANDS = (
-    ("start", "Interactive setup → chat (model · mode · web/CLI/Pi/OpenCode/Swival)"),
-    ("tune", "Find the fastest AR/D1/D2/D3 depth for this Mac"),
+    ("start", "Interactive setup → chat (model · mode · web/CLI/Pi/OpenCode/Swival/Hermes/Dashboard)"),
+    ("tune", "Find the fastest AR/MTP draft depth for this Mac (AR, D1-D8)"),
     ("help", "Detailed help; `help commands` / `help flags` / `help <name>`"),
     ("setup", "Prepare config and the model cache"),
     ("quickstart", "Run the local OpenAI/Anthropic server"),
-    ("connect", "Copy settings for Open WebUI or Claude Code"),
+    ("connect", "Copy settings for Open WebUI, Claude Code, OpenCode, or Swival"),
     ("ask", "Ask the verified local model once"),
     ("status", "Check install, model, and integration health"),
     ("stop", "Stop the MTPLX daemon answering on a port"),
@@ -96,7 +96,7 @@ ADVANCED_COMMANDS = {
     "Benchmark and QA": (
         ("bench *", "Nightly gates, no-fan runs, envelope compare"),
         ("qa *", "Exactness and distribution gates"),
-        ("profile *", "Dispatch, thermal, compile, and eval attribution"),
+        ("profile *", "Compile audit; dispatch/thermal/eval-attribution need the research workspace"),
     ),
     "Support": (
         ("doctor --deep", "Deep install and integration checks"),
@@ -241,7 +241,7 @@ On later runs it offers "same as last time?" so the chat is one keypress away.
 
 What gets asked:
   1. Model — your configured model, the verified default, custom HF, or local
-  2. Mode  — Sustained, Turbo, Sustained Max, or Burst (Stable remains available via --profile safe)
+  2. Mode  — Sustained, Sustained Max, or Burst (Turbo auto-selects for the quantized flagships; Stable remains available via --profile safe)
   3. Where — Web UI (default), terminal CLI, Pi, OpenCode Desktop, Swival, or Hermes
 
 Power-user shortcuts (any of these skip the onboarding wizard):
@@ -277,7 +277,9 @@ Inside terminal chat:
   /mtp off         Switch the next turn to target-only AR generation
   /mtp on          Switch the next turn back to MTP without reloading
   /stats           Print the last response stats again
-  /speed           Run a 192-token comparison sample
+  /speed           Run a 192-token speed sample
+  /reasoning on|off|auto
+                   Control reasoning for the next turns
   /exit            Quit
 
 Aliases:
@@ -287,6 +289,8 @@ Aliases:
   `opencode`, `oc`      -> OpenCode Desktop coding-agent connection
   `swival`, `sv`        -> Swival generic-provider connection
   `hermes`              -> Hermes Agent with terminal/file/web/browser/messaging tools
+  `dashboard`, `live`   -> live engine dashboard
+  (hyphenated forms like `open-webui`, `open-code`, `hermes-agent` also work)
 """
 
 
@@ -335,7 +339,7 @@ def _format_verbose_help() -> str:
 
 {_heading("Help subtopics")}
 
-  mtplx help commands         Every command across the consumer + advanced surface
+  mtplx help commands         The consumer + advanced command reference (`help flags` lists every flag)
   mtplx help flags            Every flag, grouped by command
   mtplx help advanced         Benchmarks, QA, publishing, and kernel tools
   mtplx help <command>        Detailed flags for one command (argparse view)
@@ -364,7 +368,7 @@ def _format_commands_help() -> str:
 {public_lines}
 
 """ + "\n".join(advanced_sections) + f"""
-  {_muted("Run `mtplx help <command>` for flags on any command above.")}
+  {_muted("Run `mtplx <command> --help` for flags on any command above (works for multi-word commands too).")}
 """
 
 
@@ -2224,7 +2228,16 @@ def build_parser() -> argparse.ArgumentParser:
     doctor_p.add_argument("topic", nargs="?", choices=["opencode", "pi", "android-studio"], help="Optional focused doctor target")
     doctor_p.add_argument("--project-root", default=".")
     doctor_p.add_argument("--host", default="127.0.0.1")
-    doctor_p.add_argument("--port", type=int, default=8008)
+    doctor_p.add_argument(
+        "--port",
+        type=int,
+        default=8008,
+        help=(
+            "Port for the topic bridge checks (opencode/pi/android-studio; "
+            "default 8008). When passed explicitly it also aims the MTPLX "
+            "server checks, which otherwise probe the shipped default :8000."
+        ),
+    )
     doctor_p.add_argument("--base-url")
     doctor_p.add_argument("--smc-path", default=os.environ.get("MTPLX_SMC_PATH") or shutil.which("smc") or "")
     doctor_p.add_argument("--sovereign-path", default=os.environ.get("MTPLX_SOVEREIGN_PATH") or shutil.which("sovereign") or "")
@@ -2756,7 +2769,7 @@ def build_parser() -> argparse.ArgumentParser:
         ],
     )
     bench_p.add_argument("--strict", action="store_true", help="Run clean-preflight before profile benchmarks")
-    bench_p.add_argument("--strict-cold", action="store_true", help="Enforce cold 55 tok/s regression gate")
+    bench_p.add_argument("--strict-cold", action="store_true", help="Enforce the cold 59 tok/s regression gate")
     bench_p.add_argument("--no-fanmax", action="store_true", help="Mark run as no-fan product candidate")
     bench_p.add_argument("--fanmax", action="store_true", help="Mark run as fan-controlled diagnostic")
     bench_p.add_argument("--max", action="store_true", dest="fanmax", help="Alias for --fanmax")