feat(mtp): DSpark speculative decoding for DeepSeek-V4-Flash 0731

CHANGELOG.md

@@ -8,6 +8,26 @@ adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- Speculative decoding for the GA DeepSeek-V4-Flash 0731 checkpoint via its
+  DSpark draft model (three chained draft blocks replacing the legacy
+  single-block MTP head). The drafter loads from a sidecar GGUF discovered
+  next to the target (preferred over legacy `deepseek4_mtp_support`
+  sidecars; `--draft-gguf` selects one explicitly) - measured +20% decode
+  over plain on UD-Q2_K_XL at ~0.99 acceptance. `GMLX_DSPARK_CONF` moves
+  the confidence gate (default 0.9, the model's own calibration) and
+  `GMLX_DSPARK_ROWS` the draft rows per block (default 3, the measured
+  optimum: fewer noise rows sharpen the non-causal block and keep verify
+  widths on the compiled attention paths).
+- `scripts/convert_dspark_sidecar.py` builds that sidecar from the three
+  draft shards of the upstream release (~10 GiB read instead of the full
+  167 GB checkpoint): expert tensors repack bit-exact into GGML MXFP4,
+  dense tensors encode Q8_0. `--experts-codec q3_k` (or `q4_k`/`q2_k`)
+  trades a little acceptance for a smaller file, with a round-trip RMS
+  report against the upstream weights.
+- Draft-model sidecars whose codecs are all fp4-wire capable load in wire
+  mode by default: the DSpark MXFP4 experts stay zero-copy and file-backed
+  instead of pinning ~9.6 GiB of anonymous memory (an explicit
+  `GMLX_NATIVE_FP` setting still wins).
 - Shared-prefix cascade decode for concurrent serving: streams that share a
   prefix (same system prompt, warm history, cold or cached alike) read it
   once per step for the whole batch instead of once per stream - measured
@@ -36,18 +56,6 @@ adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   retain the reply up to the divergence point (`GMLX_APC_DECODE_CKPT`,
   default 512 generated tokens; `0` off).
 
-### Changed
-
-- Informational `[stream]` banners (streaming summary, feeder/arena sizes,
-  keep-warm, lookahead, MoE lever confirmations, runtime stats) and the
-  `[prefill]` chunk-size note only print under `--verbose`; warnings
-  (ignored flags, fallbacks, wedged reads, clamps) stay visible.
-- Scaffolded config comments now sit on their own line above live keys
-  instead of trailing them (no more wrapped lines on narrow terminals); the
-  redundant mmproj `# VLM companion` comment is gone.
-
-### Added
-
 - `run`/`chat --thinking on|off|adaptive` and `--reasoning-effort LEVEL`:
   first-class switches for thinking models. The chat template picks the
   spelling: MiniMax's three-state `thinking_mode`
@@ -106,20 +114,27 @@ adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Changed
 
+- The DSpark draft-model module (`deepseek_v4_dspark.py`) and the sidecar
+  converter are MIT licensed (LICENSE-MIT, SPDX headers); the rest of gmlx
+  stays BUSL-1.1.
+- Informational `[stream]` banners (streaming summary, feeder/arena sizes,
+  keep-warm, lookahead, MoE lever confirmations, runtime stats) and the
+  `[prefill]` chunk-size note only print under `--verbose`; warnings
+  (ignored flags, fallbacks, wedged reads, clamps) stay visible.
+- Scaffolded config comments now sit on their own line above live keys
+  instead of trailing them (no more wrapped lines on narrow terminals); the
+  redundant mmproj `# VLM companion` comment is gone.
 - glm-dsa/DeepSeek-V3.2 sparse decode uses the stock top-k gather again
   (O(index_topk) per step); the mask-path workaround is now opt-in via
   `GMLX_DSV32_MASK_DECODE=1`.
 - The server's APC prompt-cache manager is now gmlx-owned, built at model
   load; config `cache.enabled` and a plain `APC_ENABLED=1` both keep working.
-
 - gemma-4 batched decode runs the global (hd512) layers as one ragged
   kernel call per layer instead of a per-row loop (needs mlx-kquant with
   `sdpa_decode_gqa` starts; older wheels keep the loop).
-
 - gemma4 text MTP targets now build gmlx-owned mask/attention classes at
   construction (`GMLX_GEMMA_OWNED=0` reverts to the stock classes plus the
   patch regime; numerics identical either way).
-
 - Quantized-KV (`kv_bits: 8`) decode routes through the fused mlx_kquant
   kernel when available, ~1.4x per attention call at depth
   (`GMLX_QSDPA_KQ=0` restores the stock path).

LICENSE

@@ -25,6 +25,11 @@ Change License:         Apache License, Version 2.0
 For information about alternative licensing arrangements for the Licensed Work,
 please contact asher_feldman@icloud.com.
 
+File-level exception: files that carry an "SPDX-License-Identifier: MIT"
+header (the DSpark draft-model module and the DSpark sidecar converter)
+are licensed under the MIT license (see LICENSE-MIT), not under this
+License.
+
 Notice
 
 Business Source License 1.1

LICENSE-MIT

@@ -0,0 +1,26 @@
+This license applies only to the files in this repository that carry an
+"SPDX-License-Identifier: MIT" header. All other files are covered by the
+Business Source License 1.1 in LICENSE. MIT files derived from mlx-lm
+retain Apple's copyright on the derived portions.
+
+MIT License
+
+Copyright (c) 2026 Asher Feldman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -477,6 +477,12 @@ version converts to the Apache License 2.0 four years after its release. No clai
 are made against inference outputs, and downloaded model weights carry their own
 licenses.
 
+Exception: the DSpark draft-model module (`deepseek_v4_dspark.py`) and the
+sidecar converter (`scripts/convert_dspark_sidecar.py`) are MIT licensed
+(see [LICENSE-MIT](https://github.com/asher/gmlx/blob/main/LICENSE-MIT)), so
+both can be reused freely alongside the MIT-licensed ds4 and gguf tooling
+they reimplement from. MIT-licensed files carry an SPDX header saying so.
+
 Third-party code vendored into gmlx is documented in
 [THIRD_PARTY_NOTICES.md](https://github.com/asher/gmlx/blob/main/THIRD_PARTY_NOTICES.md), with license texts under
 [`licenses/`](https://github.com/asher/gmlx/tree/main/licenses).

THIRD_PARTY_NOTICES.md

@@ -9,7 +9,8 @@ provenance, live in [`licenses/`](licenses/).
 | [mlx-lm](https://github.com/ml-explore/mlx-lm) | MIT | Vendored model/cache classes from unmerged PRs: `deepseek_v4_model.py` + `deepseek_v4_hyper_connection.py` + `deepseek_v4_cache.py` (PR #1192), `minimax_m3_model.py` (PR #1401), `hy_v3_model.py` (PR #1485). The installed package is also a runtime dependency. |
 | [omlx](https://github.com/jundot/omlx) | Apache-2.0 | DeepSeek-V4-Flash MTP port (`deepseek_v4_mtp.py`), the rotating-cache MTP undo wrap in `deepseek_v4_cache.py`, and the native-kernel dispatch pattern in `deepseek_v4_model.py`. |
 | [llama.cpp / ggml](https://github.com/ggml-org/llama.cpp) | MIT | Pre-tokenizer split regex patterns in `tokenizer.py`; GGUF metadata and quantization-type conventions. |
-| [ds4.c (dwarfstar)](licenses/ds4.c-LICENSE) | MIT | QAT round-trip and sink-attention reference semantics reimplemented in `deepseek_v4_model.py` (cited per function in comments). |
+| [ds4.c (dwarfstar)](licenses/ds4.c-LICENSE) | MIT | QAT round-trip and sink-attention reference semantics reimplemented in `deepseek_v4_model.py` (cited per function in comments); the DSpark drafter runtime reimplemented in `deepseek_v4_dspark.py`; the `deepseek4-dspark` sidecar layout (`gguf-tools/deepseek4-quantize.c` and the published DSpark-support sidecar) emitted by `scripts/convert_dspark_sidecar.py`. |
+| [DeepSeek-V4-Flash-0731](https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash-0731) | MIT | Reference DSparkBlock forward semantics (`inference/model.py`) reimplemented in `deepseek_v4_dspark.py` (license text in [`licenses/deepseek-v4-LICENSE`](licenses/deepseek-v4-LICENSE)). |
 | [misaki](https://github.com/hexgrad/misaki) | Apache-2.0 | Whole package vendored at `gmlx/_vendor/misaki` (commit `fba1236`): Kokoro's grapheme-to-phoneme front-end, used by the TTS service until upstream's next PyPI release. |
 
 The [mlx-kquant](https://github.com/asher/mlx-kquant) dependency ships its own

gmlx/deepseek_v4_cache.py

@@ -157,15 +157,15 @@ def accumulate_windows(self, kv: mx.array, gate: mx.array, offset):
         # One-update undo log for MTP draft rejection: trim() needs the
         # pre-update state plus this update's raw inputs to undo the last
         # token(s) when they completed a pool window. Only decode / MTP-verify
-        # sized updates (L <= 4; block-total-B rounds verify B-1+1 wide) are
-        # ever trimmed; skipping the stash for prompt chunks avoids pinning
-        # large prefill projections. Buffer slices are taken before any
-        # mutation, so they reference the pre-update array node.
-        # update_and_fetch extends the tuple with the post-append pooled
-        # tensor so a confirmed-prefix replay that re-completes a window can
-        # slice its pooled row back instead of recompressing (the compressor
-        # inputs are gone).
-        if L <= 4:
+        # sized updates (L <= 6; block-total-B rounds verify B-1+1 wide, and
+        # the dspark drafter verifies up to 6) are ever trimmed; skipping the
+        # stash for prompt chunks avoids pinning large prefill projections.
+        # Buffer slices are taken before any mutation, so they reference the
+        # pre-update array node. update_and_fetch extends the tuple with the
+        # post-append pooled tensor so a confirmed-prefix replay that
+        # re-completes a window can slice its pooled row back instead of
+        # recompressing (the compressor inputs are gone).
+        if L <= 6:
             self._undo = (
                 self.buf_kv[:, : self.remainder] if self.remainder > 0 else None,
                 self.buf_gate[:, : self.remainder] if self.remainder > 0 else None,
@@ -1069,14 +1069,15 @@ def _wrap_rotating(cls, fields) -> None:
     orig_trim = cls.trim
 
     def update_and_fetch(self, keys, values):
-        # Only armed verify-sized updates (qL 2-4) are undoable: S == 1
-        # uses the in-place ring write (setitem mutates the wrapper, which
-        # would invalidate reference snapshots) and prompt chunks have no
-        # rollback consumer. S >= 2 always routes through the concat path,
-        # which REBINDS keys/values to fresh wrappers, so plain references
-        # keep the pre-update value -- no detach copy (a full-ring copy per
-        # field per layer, ~200 MB/round across 43 caches).
-        if keys.shape[2] in (2, 3, 4) and _is_undo_armed():
+        # Only armed verify-sized updates (qL 2-6: legacy nextn verifies up
+        # to 4, dspark up to 6) are undoable: S == 1 uses the in-place ring
+        # write (setitem mutates the wrapper, which would invalidate
+        # reference snapshots) and prompt chunks have no rollback consumer.
+        # S >= 2 always routes through the concat path, which REBINDS
+        # keys/values to fresh wrappers, so plain references keep the
+        # pre-update value -- no detach copy (a full-ring copy per field
+        # per layer, ~200 MB/round across 43 caches).
+        if 2 <= keys.shape[2] <= 6 and _is_undo_armed():
             self._mtp_undo = ({f: getattr(self, f) for f in fields}, keys, values)
         else:
             self._mtp_undo = None