Qwen3.8-Flash-Next on any consumer hardware: one-click install for Windows / Linux. Strata inference engine, OpenAI/Anthropic API on localhost, optional image input.
C++
# Copyright (c) 2026 Peasant Smith and the Project Maya contributors (MIT; https://github.com/mw00/project-maya, v1.1.17).
# Ported into Strata (third_party/project-maya/NOTICE.md, LICENSE); changes are in the git history of this file.
"""tools/ds4/pack_gguf.py - the engine's pack for a DeepSeek-V4.1 GGUF (unsloth's DeepSeek-V4.1-Flash-1017 UD-Q8_K_XL
and the like: dense BF16, routed experts MXFP4, Engram tables MXFP8 or Q6_K), beside the model's files (no weights
copied).
python tools/ds4/pack_gguf.py --model ~/models/DeepSeek-V4.1-Flash-1017-GGUF/UD-Q8_K_XL
writes <model>/maya-ds4/ in pack.py's format, so the engine reads both:
ds4.txt the geometry under config.json's names (the GGUF's deepseek41.* keys translated), model_dir, format gguf
tensors.txt every tensor under the checkpoint's names: `file <i> <name>` lines, then
`t <name> <dtype> <file> <offset> <bytes> <dims...>` - dims outermost first (torch order: a matrix is
[out][in]), dtype BF16 / F32 / MXFP4 / MXFP8 (ggml's block layouts, 32 values a block); the routed
experts as one tensor a layer and role ([n_exp][out][in])
engram.bin the Engram hash tables, from the GGUF's metadata (pack.py's layout; no tokenizers package needed)
tokenizer/ the server's tokenizer from the GGUF's vocabulary and merges (pre "deepseek3"), and its chat template
A GGUF has no DSpark drafter: drafter_pack.py makes it from DeepSeek's checkpoint into ../dspark/, and the pack takes it
from there when it is present. Nor a vision tower: vision_pack.py makes it from DeepSeek's checkpoint into ../vision/
(--vision: another folder), and the pack takes it and its geometry (vision.<key>, image_token_id) from there when it is
present; without it the engine reads text only.
For older GGUF converters that omit sparse-attention geometry, pass --config-json /path/to/the/source/model/config.json.
Existing metadata must agree with that configuration; the weights are never rewritten.
A quant that leaves the two Engram tables out (v1.1.16's Maya-S; Maya's quants hold them since) takes them from a set
of GGUF files that holds them, beside it: --engram, else ../Engram/ (unsloth's MXFP8 shard of them, where setups before
v1.1.17 put it) when it is whole.
"""
from __future__ import annotations
import argparse
import json
import os
import pathlib
import re
import struct
import sys
TYPES = {0: ("F32", 1, 4), 1: ("F16", 1, 2), 8: ("Q8_0", 32, 34), 30: ("BF16", 1, 2), 39: ("MXFP4", 32, 17),
67: ("MXFP8", 32, 33), # ggml type -> (name, values a block, bytes a block); 67: unsloth's fork
43: ("MXFP8", 32, 33), # llama.cpp's own id (unsloth's GGUFs from 2026-10-19 on)
# the low-bit expert types (the Maya quants' experts; the engine's ds4_iq kernels)
10: ("Q2_K", 256, 84), 11: ("Q3_K", 256, 110), 12: ("Q4_K", 256, 144), 13: ("Q5_K", 256, 176),
14: ("Q6_K", 256, 210), 16: ("IQ2_XXS", 256, 66), 17: ("IQ2_XS", 256, 74), 18: ("IQ3_XXS", 256, 98),
20: ("IQ4_NL", 32, 18), 21: ("IQ3_S", 256, 110), 22: ("IQ2_S", 256, 82), 23: ("IQ4_XS", 256, 136),
# the two 1.x-bit types the IST-DAS 2.00 set uses: device kernels since 2026-10-23 (ds4_iq.cu), so packs with
# them load and run entirely on the card. (The integer metadata tensors - engram_token_map and the like - stay
# OUT of this table on purpose: the pack tool skips a tensor whose type it does not know, which is exactly right
# for them, and adding them here made them "unmapped" instead.)
19: ("IQ1_S", 256, 50), 29: ("IQ1_M", 256, 56),
# the trellis types (tools/trellis/tqenc.hpp; 145 / 146 are the agentionai fork's ggml ids, 224-227 Strata's own)
145: ("TQK6", 128, 26), 146: ("TQK7", 128, 30), 224: ("TQK5X", 128, 22), 225: ("TQK4X", 128, 18),
226: ("TQK5T", 128, 22), 227: ("TQK4T", 128, 18)}
# the Engram set a quant without the tables takes them from by default, beside it (or inside its folder): unsloth's
# MXFP8 shard of them, where setups before v1.1.17 put it for Maya-S (--engram: any other)
ENGRAM_SETS = ("Engram",)
class Gguf:
"""One GGUF shard's metadata and tensor infos (offsets absolute in the file)."""
def __init__(self, path: pathlib.Path):
self.path = path
with path.open("rb") as f:
self.f = f
magic = f.read(4)
if magic != b"GGUF":
raise SystemExit("%s: not a GGUF file" % path)
self.version, nt, nkv = struct.unpack("<IQQ", f.read(20))
self.kv = {}
for _ in range(nkv):
k = self._str()
self.kv[k] = self._val(struct.unpack("<I", f.read(4))[0])
self.tensors = []
for _ in range(nt):
name = self._str()
nd = struct.unpack("<I", f.read(4))[0]
dims = list(struct.unpack("<%dQ" % nd, f.read(8 * nd)))
typ, off = struct.unpack("<IQ", f.read(12))
self.tensors.append((name, typ, dims, off))
align = int(self.kv.get("general.alignment", 32))
pos = f.tell()
self.data_start = (pos + align - 1) // align * align
del self.f
def _str(self):
n = struct.unpack("<Q", self.f.read(8))[0]
return self.f.read(n).decode("utf-8", "replace")
def _val(self, t):
fmt = {0: "B", 1: "b", 2: "H", 3: "h", 4: "I", 5: "i", 6: "f", 7: "?", 10: "Q", 11: "q", 12: "d"}
if t in fmt:
n = struct.calcsize(fmt[t])
return struct.unpack("<" + fmt[t], self.f.read(n))[0]
if t == 8:
return self._str()
if t == 9:
at, n = struct.unpack("<IQ", self.f.read(12))
if at in fmt:
n_b = struct.calcsize(fmt[at])
return list(struct.unpack("<%d%s" % (n, fmt[at]), self.f.read(n * n_b)))
return [self._val(at) for _ in range(n)]
raise SystemExit("%s: metadata type %d" % (self.path, t))
# GGUF name (blk.N. stripped) -> the checkpoint's name under layers.N. (pack.py / the engine)
LAYER = {
"attn_norm.weight": "attn_norm.weight",
"attn_sinks.weight": "attn.attn_sink",
"attn_q_a.weight": "attn.wq_a.weight",
"attn_q_a_norm.weight": "attn.q_norm.weight",
"attn_q_b.weight": "attn.wq_b.weight",
"attn_kv.weight": "attn.wkv.weight",
"attn_kv_a_norm.weight": "attn.kv_norm.weight",
"attn_output_a.weight": "attn.wo_a.slice", # one entry a group (the engine's slices)
"attn_output_b.weight": "attn.wo_b.weight",
"attn_compressor_kv.weight": "attn.compressor.wkv.weight",
"attn_compressor_gate.weight": "attn.compressor.wgate.weight",
"attn_compressor_norm.weight": "attn.compressor.norm.weight",
"indexer.attn_q_b.weight": "attn.indexer.wq_b.weight",
"indexer.attn_k.weight": "attn.indexer.wk.weight",
"indexer.k_norm.weight": "attn.indexer.k_norm.weight",
"indexer.proj.weight": "attn.indexer.weights_proj.weight",
"hc_attn_fn.weight": "hc_attn_fn",
"hc_attn_base.weight": "hc_attn_base",
"hc_attn_scale.weight": "hc_attn_scale",
"hc_ffn_fn.weight": "hc_ffn_fn",
"hc_ffn_base.weight": "hc_ffn_base",
"hc_ffn_scale.weight": "hc_ffn_scale",
"ffn_norm.weight": "ffn_norm.weight",
"ffn_gate_inp.weight": "ffn.gate.weight",
"exp_probs_b.bias": "ffn.gate.bias",
"exp_probs_b_vl.bias": "ffn.gate.bias_vl",
"ffn_gate_shexp.weight": "ffn.shared_experts.w1.weight",
"ffn_up_shexp.weight": "ffn.shared_experts.w3.weight",
"ffn_down_shexp.weight": "ffn.shared_experts.w2.weight",
"ffn_gate_exps.weight": "ffn.experts.w1", # [n_exp][ff][dim]: one entry an expert
"ffn_up_exps.weight": "ffn.experts.w3",
"ffn_down_exps.weight": "ffn.experts.w2", # [n_exp][dim][ff]
"engram_embd.weight": "engram.embed.weight",
"engram_kv.weight": "engram.wkv.weight",
"engram_gate.weight": "engram.gate.weight", # q_weight * k_weight, folded by the converter
# the IST-DAS sets keep q and k apart (the engine multiplies them at load) and the projection as engram_wkv
"engram_wkv.weight": "engram.wkv.weight",
"engram_q.weight": "engram.q_weight",
"engram_k.weight": "engram.k_weight",
}
GLOBAL = {"token_embd.weight": "embed.weight", "output_norm.weight": "norm.weight", "output.weight": "head.weight"}
ALIASES = {
# the same quantity under another key: llama.cpp's / unsloth's spelling -> the alternative (the IST-DAS sets write
# the engine's own names into the GGUF and keep deepseek41.engram_* instead of the dotted Engram keys)
"attention.kv_source_layers": ("kv_source_layer_ids",),
"attention.indexer.source_layers": ("index_source_layer_ids",),
"attention.indexer.candidate_source_layer": ("attention.candidate_source_layer_id",),
"attention.indexer.candidate_top_k_blocks": ("attention.candidate_topk_blocks",),
"attention.indexer.candidate_block_size": ("attention.candidate_block_size",),
"dspark.target_layers": ("dspark_target_layer_ids",),
"dspark.block_size": ("dspark_block_size",),
"dspark.noise_token_id": ("dspark_noise_token_id",),
"dspark.markov_rank": ("dspark_markov_rank",),
"dspark.expert_count": ("dspark_n_routed_experts",),
"dspark.expert_used_count": ("dspark_num_experts_per_tok",),
"engram.layers": ("engram_layer_ids",),
}
def geometry(kv: dict, vocab: int) -> dict:
"""config.json's text_config names (what the engine reads) from the GGUF's deepseek41.* keys."""
a = kv["general.architecture"]
def g(k, d=None):
v = kv.get("%s.%s" % (a, k))
if v is None:
for alt in ALIASES.get(k, ()):
v = kv.get("%s.%s" % (a, alt))
if v is not None:
break
return d if v is None else v
nl = g("block_count")
ratios = list(g("attention.compress_ratios", []))
out = {
"vocab_size": vocab,
"hidden_size": g("embedding_length"),
"num_hidden_layers": nl,
"num_attention_heads": g("attention.head_count"),
"head_dim": g("attention.key_length"),
"qk_rope_head_dim": g("rope.dimension_count"),
"q_lora_rank": g("attention.q_lora_rank"),
"o_lora_rank": g("attention.output_lora_rank"),
"o_groups": g("attention.output_group_count"),
"n_routed_experts": g("expert_count"),
"num_experts_per_tok": g("expert_used_count"),
"moe_intermediate_size": g("expert_feed_forward_length"),
"sliding_window": g("attention.sliding_window"),
"hc_mult": g("hyper_connection.count"),
"hc_sinkhorn_iters": g("hyper_connection.sinkhorn_iterations"),
"hc_eps": g("hyper_connection.epsilon"),
"index_n_heads": g("attention.indexer.head_count"),
"index_head_dim": g("attention.indexer.key_length"),
"index_topk": g("attention.indexer.top_k"),
"candidate_source_layer_id": g("attention.indexer.candidate_source_layer"),
"candidate_topk_blocks": g("attention.indexer.candidate_top_k_blocks"),
"candidate_block_size": g("attention.indexer.candidate_block_size"),
"rope_scaling.original_max_position_embeddings": g("rope.scaling.original_context_length"),
"rope_scaling.factor": g("rope.scaling.factor"),
"rope_scaling.beta_fast": g("rope.scaling.yarn_beta_fast"),
"rope_scaling.beta_slow": g("rope.scaling.yarn_beta_slow"),
"eos_token_id": kv.get("tokenizer.ggml.eos_token_id", 1),
"rms_norm_eps": g("attention.layer_norm_rms_epsilon"),
"routed_scaling_factor": g("expert_weights_scale"),
"swiglu_limit": (g("swiglu_clamp_exp") or [0.0])[0],
"rope_theta": g("rope.freq_base"),
"compress_rope_theta": g("attention.compress_rope_freq_base"),
"compress_ratios": ratios,
"kv_source_layer_ids": list(g("attention.kv_source_layers", [])),
"index_source_layer_ids": list(g("attention.indexer.source_layers", [])),
"engram_layer_ids": list(g("engram.layers", [])),
"max_position_embeddings": g("context_length"),
"dspark_block_size": g("dspark.block_size", 0),
"dspark_noise_token_id": g("dspark.noise_token_id", 0),
"dspark_markov_rank": g("dspark.markov_rank", 0),
"dspark_n_routed_experts": g("dspark.expert_count", 0),
"dspark_num_experts_per_tok": g("dspark.expert_used_count", 0),
"dspark_target_layer_ids": list(g("dspark.target_layers", [])),
}
clamp = g("swiglu_clamp_exp") or []
if clamp and any(abs(c - clamp[0]) > 1e-6 for c in clamp):
raise SystemExit("swiglu_clamp_exp differs between layers %s: the engine takes one swiglu_limit" % clamp[:8])
return out
def ple_to_engram(kv: dict):
"""llama.cpp's own names for the Engram metadata (unsloth's GGUFs from 2026-10-19 on: ple.*, the hash heads' offsets
counted across the layers' tables) -> the engram.* keys this pack reads (each layer's offsets from its own table)."""
a = kv.get("general.architecture")
g = lambda k, d=None: kv.get("%s.%s" % (a, k), d) # noqa: E731
if g("engram.layers") or not g("ple.layers"):
return
layers, ngram, heads = list(g("ple.layers")), g("ple.ngram_size"), g("ple.heads_per_ngram")
offs, sizes = list(g("ple.head_offsets")), list(g("ple.head_vocab_sizes"))
cols = (ngram - 1) * heads
if len(offs) != len(layers) * cols or len(sizes) != len(offs):
raise SystemExit("ple: %d head offsets, %d sizes for %d layers x %d columns" %
(len(offs), len(sizes), len(layers), cols))
per, rows = [], []
for i in range(len(layers)):
o, s = offs[i * cols:(i + 1) * cols], sizes[i * cols:(i + 1) * cols]
per += [x - o[0] for x in o]
rows.append(o[-1] + s[-1] - o[0])
for k, v in (("layers", layers), ("max_ngram_size", ngram), ("head_count", heads),
("head_dim", g("embedding_length_per_layer_input")), ("multipliers", list(g("ple.layer_multipliers"))),
("primes", sizes), ("offsets", per), ("num_embeddings", rows)):
kv["%s.engram.%s" % (a, k)] = v
def apply_source_config(kv: dict, config: dict):
"""Fill sparse-attention geometry omitted by older converters from the model's own config.json."""
a = kv["general.architecture"]
text = config.get("text_config", config)
fields = {
"embedding_length": "hidden_size", "block_count": "num_hidden_layers",
"expert_count": "n_routed_experts", "attention.compress_ratios": "compress_ratios",
"attention.kv_source_layers": "kv_source_layer_ids",
"attention.indexer.source_layers": "index_source_layer_ids",
"attention.indexer.candidate_source_layer": "candidate_source_layer_id",
"attention.indexer.candidate_top_k_blocks": "candidate_topk_blocks",
"attention.indexer.candidate_block_size": "candidate_block_size",
}
for name, source in fields.items():
if source not in text:
continue
keys = ["%s.%s" % (a, k) for k in (name, *ALIASES.get(name, ()))]
for key in keys:
if key in kv and kv[key] != text[source]:
raise SystemExit("source config %s disagrees with GGUF %s" % (source, key))
kv.setdefault(keys[0], text[source])
def int_tensors_to_engram(gs, kv: dict):
"""The IST-DAS sets carry the Engram's hash parameters as integer tensors of the first shard (engram_token_map I32,
engram_primes / engram_offsets / engram_multipliers I64, one row a layer) instead of metadata: read them into the
engram.* keys this pack reads (when the metadata does not have them already)."""
a = kv.get("general.architecture")
want = {"engram_token_map.weight": ("token_map", "i", 4), "engram_primes.weight": ("primes", "q", 8),
"engram_offsets.weight": ("offsets", "q", 8), "engram_multipliers.weight": ("multipliers", "q", 8)}
for g in gs:
for name, typ, dims, off in g.tensors:
if name not in want:
continue
key, fmt, sz = want[name]
if "%s.engram.%s" % (a, key) in kv:
continue
n = 1
for d in dims:
n *= d
with g.path.open("rb") as f:
f.seek(g.data_start + off)
kv["%s.engram.%s" % (a, key)] = list(struct.unpack("<%d%s" % (n, fmt), f.read(n * sz)))
# the IST-DAS spelling of the Engram's scalar keys -> the dotted ones this pack reads
for dotted, theirs in (("engram.layers", "engram.layer_ids"), ("engram.max_ngram_size", "engram_max_ngram_size"),
("engram.head_count", "engram_n_heads"), ("engram.head_dim", "engram_head_dim"),
("engram.pad_token_id", "engram_pad_token_id"),
("engram.head_dim", "engram.key_length"), ("engram.pad_token_id", "engram.pad_id")):
if "%s.%s" % (a, dotted) not in kv and "%s.%s" % (a, theirs) in kv:
kv["%s.%s" % (a, dotted)] = kv["%s.%s" % (a, theirs)]
def split_ple(g: Gguf, kv: dict):
"""llama.cpp's one Engram tensor (per_layer_token_embd: every layer's table, one after the other) -> each layer's
own blk.N.engram_embd as the earlier GGUFs had it: the same bytes, read in place."""
a = kv["general.architecture"]
ple = [t for t in g.tensors if t[0] == "per_layer_token_embd.weight"]
if not ple:
return
name, typ, dims, off = ple[0]
layers, rows = kv.get("%s.engram.layers" % a, []), kv.get("%s.engram.num_embeddings" % a, [])
if len(dims) != 2 or typ not in TYPES or len(rows) != len(layers) or sum(rows) != dims[1]:
raise SystemExit("%s: %s %s does not split in the Engram layers %s of %s rows" % (g.path.name, name, dims, layers,
rows))
_, per, bpb = TYPES[typ]
row = dims[0] // per * bpb
parts, start = [], 0
for il, n in zip(layers, rows):
parts.append(("blk.%d.engram_embd.weight" % il, typ, [dims[0], n], off + start * row))
start += n
g.tensors = [t for t in g.tensors if t[0] != name] + parts
def short(g: Gguf):
"""Why a GGUF file is shorter than its own tensor directory says (a download still running), or None."""
need = g.data_start
for _, typ, dims, off in g.tensors:
if typ in TYPES:
_, per, bpb = TYPES[typ]
nel = 1
for d in dims:
nel *= d
need = max(need, g.data_start + off + nel // per * bpb)
have = g.path.stat().st_size
return None if have >= need else "%s: %d of %d bytes" % (g.path.name, have, need)
def find_mmproj(model: pathlib.Path):
"""The DeepSeek vision tower beside the model (an automatic find, no --mmproj): an mmproj*.gguf in the model's parent folder whose projector IS
deepseek41v. The folder is shared with other families' files (Qwen keeps its own mmproj-Qwen3.8-Flash-Next-BF16.gguf there, projector
qwen3vl_merger): those are never taken, and never an error - the pack is made without a vision tower. A file named with --mmproj is checked
strictly in main()."""
for p in sorted(model.parent.glob("mmproj*.gguf")):
try:
if Gguf(p).kv.get("clip.projector_type") == "deepseek41v":
return p
except (OSError, ValueError, SystemExit, struct.error):
continue
return None
def is_engram_file(g) -> bool:
"""The Engram table's GGUF: general.architecture 'engram' (the first release) or 'deepseek41-engram' (ISTA-DASLab's final files)."""
arch = str(g.kv.get("general.architecture") or "")
return arch == "engram" or arch.endswith("-engram")
def model_kv(gs):
"""The metadata of the model: of the first group whose architecture IS deepseek41 - never an Engram file's, whatever order they come in."""
return next((g.kv for g in gs if g.kv.get("general.architecture") == "deepseek41"), None)
def engram_set(model: pathlib.Path, explicit: str | None):
"""The Engram tables' GGUF set for a quant that leaves them out: (its folder, its files read), or (None, []).
explicit (--engram): that folder, whole; else the first whole one of ENGRAM_SETS beside the quant or in its
folder - one not whole yet (its download still running) is passed over."""
dirs = ([pathlib.Path(explicit).expanduser().resolve()] if explicit else
[d for n in ENGRAM_SETS for d in (model / n, model.parent / n)])
for d in dirs:
paths = [d] if d.is_file() else sorted(d.glob("*.gguf")) if d.is_dir() else [] # (--engram: a folder, or the one file)
if not paths:
if explicit:
raise SystemExit("%s: no .gguf files (--engram: the folder of the Engram tables' GGUF set)" % d)
continue
try:
egs = [Gguf(p) for p in paths]
why = next((w for w in map(short, egs) if w), None)
except (Exception, SystemExit) as e: # noqa: BLE001 - a header cut short raises anything
why = str(e) or type(e).__name__
if why is None:
return d, egs
if explicit:
raise SystemExit("%s: not whole (%s)" % (d, why))
print("%s: not whole (%s) - not used" % (d, why))
return None, []
def write_engram(out: pathlib.Path, kv: dict, vocab: int):
a = kv["general.architecture"]
g = lambda k, d=None: kv.get("%s.%s" % (a, k), d) # noqa: E731
layers = list(g("engram.layers", []))
if not layers:
return 0, 0
ngram, heads, hd = g("engram.max_ngram_size"), g("engram.head_count"), g("engram.head_dim")
tm = list(g("engram.token_map"))
mult, primes, offs = list(g("engram.multipliers")), list(g("engram.primes")), list(g("engram.offsets"))
cols = (ngram - 1) * heads
nl = len(layers)
if len(mult) != nl * ngram or len(primes) != nl * cols or len(offs) != nl * cols:
raise SystemExit("engram: %d multipliers, %d primes, %d offsets for %d layers x %d columns (ngram %d)" %
(len(mult), len(primes), len(offs), nl, cols, ngram))
pad = int(tm[g("engram.pad_token_id")])
full = tm + [0] * max(0, vocab - len(tm))
with out.open("wb") as f:
f.write(struct.pack("<4s6i", b"DSE1", vocab, nl, ngram, heads, hd, pad))
f.write(struct.pack("<%di" % vocab, *full[:vocab]))
f.write(struct.pack("<%dq" % len(mult), *mult))
f.write(struct.pack("<%dq" % len(primes), *primes))
f.write(struct.pack("<%dq" % len(offs), *offs))
return nl, cols
def write_tokenizer(out: pathlib.Path, kv: dict, template: str | None):
tokens = kv["tokenizer.ggml.tokens"]
types = kv.get("tokenizer.ggml.token_type") or [1] * len(tokens)
merges = kv.get("tokenizer.ggml.merges") or []
if len(set(tokens)) != len(tokens):
raise SystemExit("the GGUF's vocabulary has duplicate token strings")
out.mkdir(parents=True, exist_ok=True)
(out / "vocab.json").write_text(json.dumps({t: i for i, t in enumerate(tokens)}, ensure_ascii=False),
encoding="utf-8")
(out / "merges.txt").write_text("\n".join(merges), encoding="utf-8")
(out / "token_type.json").write_text(json.dumps([int(t) for t in types]))
special = {"bos": int(kv.get("tokenizer.ggml.bos_token_id", 0)), "eos": int(kv.get("tokenizer.ggml.eos_token_id", 1)),
"pad": int(kv.get("tokenizer.ggml.padding_token_id", 2))}
(out / "tokenizer.json").write_text(json.dumps({"pre": "deepseek3", "special_ids": special}, indent=1))
if template:
(out / "chat_template.jinja").write_text(template, encoding="utf-8")
def main() -> int:
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("--model", required=True, help="the directory of the GGUF's shards")
ap.add_argument("--out", help="default: <model>/maya-ds4")
ap.add_argument("--config-json", help="the exact source model config.json, to fill sparse-attention geometry omitted by older GGUF converters")
ap.add_argument("--vision", help="vision_pack.py's folder (default: <model>/../vision; taken when it is there)")
ap.add_argument("--dspark-gguf", help="unsloth's DSpark drafter GGUF (dspark-*-Q8_0.gguf, architecture dflash): its three "
"blocks become mtp.0-2 beside the trunk's tensors (default: the first dspark-*.gguf "
"in <model>/.. when there is one)")
ap.add_argument("--mmproj", help="unsloth's vision tower GGUF (mmproj-*.gguf, clip / deepseek41v): its tensors become the "
"checkpoint's vision.* / aligner.* (default: the first mmproj*.gguf in <model>/.. whose projector is deepseek41v; other families' are ignored)")
ap.add_argument("--tq-experts", nargs="+", help="folders tq_convert.py wrote (tq.json + tq-L<layer>.bin): the routed experts of the layers "
"listed there are read from it as trellis types (TQK5X ..), the others keep their MXFP4")
ap.add_argument("--dense-override", action="append", help="a folder dense_requant.py wrote (dense.json + dense.bin): its tensors replace the same-named "
"dense matrices of the GGUF (K-quants of the attention / shared experts)")
ap.add_argument("--override-experts", nargs="+", help="requantized GGUF folders, each DIR or DIR:roles (requant_gguf.py output): their routed experts replace the main "
"model's for --override-roles (gate,up,down) in --override-layers (default all): mixed-bit packs")
ap.add_argument("--override-roles", default="down")
ap.add_argument("--override-layers", default="")
ap.add_argument("--tq-layers", help="only these layers (comma list) of the --tq-experts folders")
ap.add_argument("--drafter", help="the DSpark drafter's .json (drafter_pack.py's; default <model>/../dspark/dspark.json)")
ap.add_argument("--dspark-noise-token", type=int, help="the drafter's noise token id (dspark_noise_token_id), for a quant "
"whose GGUF does not state it (the IST-DAS sets): DeepSeek-V4.1-Flash's is 128799")
ap.add_argument("--dspark-markov-rank", type=int, help="the markov head's rank (dspark_markov_rank); default: the drafter's "
"markov tensor shape")
ap.add_argument("--skip-tensors", help="a regex of the GGUF's tensor names to leave out (a --dense-override supplies them "
"instead): e.g. attn_output_a, for a quant that stores the grouped wo_a as one "
"interleaved 3-D tensor instead of o_groups matrices")
ap.add_argument("--engram", help="the folder of the Engram tables' GGUF set, for a quant that leaves them out "
"(default: <model>/../Engram, when it is whole)")
ap.add_argument("--engram-meta", help="a GGUF whose metadata carries the Engram's hash parameters (llama.cpp's ple.* / "
"engram.*: layers, head offsets, vocab sizes, multipliers, token map), for a quant whose own "
"shards leave them out (the IST-DAS sets name the Engram only in deepseek41.engram_* keys and "
"carry no token map); the tables themselves still come from --engram")
ap.add_argument("--shards", nargs="+", help="the GGUF's files in --model (default: every .gguf there - one "
"model's; the setup names them: a folder may hold an earlier layout)")
a = ap.parse_args()
model = pathlib.Path(a.model).expanduser().resolve()
out = pathlib.Path(a.out).expanduser() if a.out else model / "maya-ds4"
shards = [model / n for n in a.shards] if a.shards else sorted(model.glob("*.gguf"))
if not shards or not all(p.is_file() for p in shards):
raise SystemExit("%s: no .gguf files" % model if not shards else
"%s: not there" % next(p for p in shards if not p.is_file()))
gs = [Gguf(p) for p in shards]
if not a.shards: # a folder's *.gguf: the Engram table (architecture 'engram', today 'deepseek41-engram') is not a model shard
keep = [i for i, g in enumerate(gs) if not is_engram_file(g)]
shards, gs = [shards[i] for i in keep], [gs[i] for i in keep]
if not gs:
raise SystemExit("%s: no model shards (only an Engram table)" % model)
kv = model_kv(gs)
if kv is None:
arch = next((g.kv.get("general.architecture") for g in gs), None)
raise SystemExit("%s: not a DeepSeek-V4.1 GGUF (architecture %r)" % (model, arch))
if a.config_json:
apply_source_config(kv, json.loads(pathlib.Path(a.config_json).expanduser().read_text()))
split = int(kv.get("split.count", 1))
if split != len(shards):
counts = sorted({m.group(1) for m in (re.search(r"-of-(\d{5})\.gguf$", p.name) for p in shards) if m})
raise SystemExit("%s: %d of the %d shards are here" % (model, len(shards), split) if len(counts) < 2 else
"%s: the shards of more than one GGUF split (-of-%s): name the model's own with --shards" %
(model, ", -of-".join(counts)))
# a quant whose shards leave the Engram's metadata out (the IST-DAS sets: deepseek41.engram_* only, no token map):
# the hash parameters come from --engram-meta, a GGUF of the same model that still has llama.cpp's ple.* / engram.*
if a.engram_meta:
mg = Gguf(pathlib.Path(a.engram_meta).expanduser().resolve())
for k, v in mg.kv.items():
if ".engram." in k or ".ple." in k or k.endswith(".embedding_length_per_layer_input"):
kv.setdefault(k, v)
ple_to_engram(kv)
for g in gs:
split_ple(g, kv)
# the Engram tables may come from a shared set of GGUF files beside the quant (the same tensor names: engram_set) -
# its engram tensors fill in the ones the quant's shards leave out, its engram metadata too. v1.1.16's Maya-S:
# unsloth's UD-Q8_K_XL shard that holds only the tables, as it is (00008 of 9; before 2026-10-19 shards 00008 and
# 00009 of 10, a table each), so no shard count is checked - every Engram layer's tables must be found, below.
# Looked for only when the quant's shards leave some out.
have = {t[0] for g in gs for t in g.tensors}
arch = kv["general.architecture"]
int_tensors_to_engram(gs, kv)
layers = kv.get("%s.engram.layers" % arch, [])
# An official IST-DAS set (helcig/tmp-oct26-2) carries the Engram gate/kv as their own k, q, wkv tensors and a 3-D attn_output_a, and the
# plain recipe (--engram --engram-meta --dspark-gguf, no --skip-tensors, no --dense-override) packs them as they are. Rebuilding them
# (engram_fold.py + a wo_a override) gave a pack with garbage output on the final 2.00 set (P2003, 2026-10-23), and the pack still loads,
# so it fails in the user's chat, not at install. Say so before it is built.
if any(n.endswith(".engram_wkv.weight") for n in have) and (a.skip_tensors or a.dense_override):
sys.stderr.write("pack_gguf: WARNING: this looks like an official IST-DAS set (it has engram_k/q/wkv tensors) and --skip-tensors / "
"--dense-override are used. The official sets pack correctly WITHOUT them; a pack rebuilt with them produced "
"garbage text on the final 2.00 set. Drop both unless you are testing exactly that.\n")
def has_part(il, part, names):
if "blk.%d.%s.weight" % (il, part) in names:
return True
if part == "engram_kv":
return "blk.%d.engram_wkv.weight" % il in names
if part == "engram_gate":
return "blk.%d.engram_q.weight" % il in names and "blk.%d.engram_k.weight" % il in names
return False
lacking = not layers or any(not has_part(il, part, have)
for il in layers for part in ("engram_embd", "engram_kv", "engram_gate"))
eg_dir, egs = engram_set(model, a.engram) if lacking or a.engram else (None, [])
eg_from = {}
if eg_dir is not None:
eshards = [g.path for g in egs]
for g in egs:
for k, v in g.kv.items():
if ".engram." in k or ".ple." in k or k.endswith(".embedding_length_per_layer_input"):
kv.setdefault(k, v)
ple_to_engram(kv)
for g in egs:
split_ple(g, kv)
for p, g in zip(eshards, egs):
picked = [t for t in g.tensors if re.match(r"blk\.\d+\.engram_", t[0]) and t[0] not in have]
picked = [t for t in picked if t[0].endswith("engram_embd.weight") or not has_part(
int(t[0].split(".")[1]), "engram_kv" if t[0].endswith("engram_kv.weight") else "engram_gate", have)]
if picked:
g.tensors = picked
eg_from[p] = g
# what the --dense-override folders supply: a tensor they provide is not "missing" here even though neither the quant's
# shards nor an Engram set carry it (engram_fold.py supplies the Engram gate and kv from the quant's own k/q/wkv, 2026-10-23)
# the GGUF part names -> the engine's names (LAYER maps "engram_kv.weight" -> "engram.kv.weight")
ov_names = set()
for dsrc in (a.dense_override or []):
try:
ov_names |= set(json.loads((pathlib.Path(dsrc).expanduser().resolve() / "dense.json").read_text()).keys())
except (OSError, ValueError):
pass
for il in kv.get("%s.engram.layers" % arch, []):
for part in ("engram_embd", "engram_kv", "engram_gate"):
nm = "blk.%d.%s.weight" % (il, part)
# a dense override names tensors the way the pack does, not the way the GGUF does
eng_nm = "layers.%d.%s" % (il, LAYER[part + ".weight"])
if (not has_part(il, part, have) and eng_nm not in ov_names
and not any(t[0] == nm for g in eg_from.values() for t in g.tensors)):
raise SystemExit("%s: missing - not in the quant's shards nor in an Engram set (--engram, or "
"<model>/../Engram/: unsloth's UD-Q8_K_XL shard of the Engram tables)" % nm)
rel = lambda p: os.path.relpath(p, model).replace(os.sep, "/") # noqa: E731
gs_all = gs + list(eg_from.values())
names = [g.path.name for g in gs] + [rel(p) for p in eg_from]
tensors, unknown, skipped = [], [], []
skip_re = re.compile(a.skip_tensors) if a.skip_tensors else None
for fi, g in enumerate(gs_all):
for name, typ, dims, off in g.tensors:
if skip_re is not None and skip_re.search(name):
skipped.append("%s (asked for)" % name)
continue
if typ not in TYPES:
if typ in (24, 25, 26, 27, 28): # I8 / I16 / I32 / I64 / F64: metadata carried as tensors, not weights
skipped.append("%s (type %d)" % (name, typ)) # (the IST-DAS sets' engram_token_map.weight)
continue
raise SystemExit("%s: %s has ggml type %d, which the engine does not read" % (g.path.name, name, typ))
tname, per, bpb = TYPES[typ]
nel = 1
for d in dims:
nel *= d
if dims[0] % per:
raise SystemExit("%s: %s rows of %d are not whole %s blocks" % (g.path.name, name, dims[0], tname))
nbytes = nel // per * bpb
m = re.match(r"blk\.(\d+)\.(.+)$", name)
if m and m.group(2) in LAYER:
ck = "layers.%s.%s" % (m.group(1), LAYER[m.group(2)])
elif name in GLOBAL:
ck = GLOBAL[name]
else:
unknown.append(name)
continue
shape = list(reversed(dims)) # ggml ne0 innermost -> torch order, outermost first
base = g.data_start + off
if ck.endswith(".attn.wo_a.slice"):
# [o_groups * o_lora][in] -> o_groups entries of [o_lora][in] (group g: rows g * o_lora ..)
n = int(kv["%s.attention.output_group_count" % kv["general.architecture"]])
if len(shape) == 3 and shape[0] == n: # (the IST-DAS sets: [groups][o_lora][in] in one tensor)
shape = [shape[0] * shape[1], shape[2]]
if len(shape) != 2 or shape[0] % n:
raise SystemExit("%s: %s %s does not split in %d groups" % (g.path.name, name, shape, n))
part = nbytes // n
for i in range(n):
tensors.append(("%s.%d.weight" % (ck, i), tname, fi, base + i * part, part,
[shape[0] // n, shape[1]]))
continue
if ".ffn.experts." in ck:
# [n_exp][out][in] -> an entry an expert: layers.N.ffn.experts.E.w1.weight
n, part = shape[0], nbytes // shape[0]
pre, role = ck.rsplit(".", 1)
for i in range(n):
tensors.append(("%s.%d.%s.weight" % (pre, i, role), tname, fi, base + i * part, part, shape[1:]))
continue
tensors.append((ck, tname, fi, base, nbytes, shape))
if unknown:
raise SystemExit("tensors the pack does not map (%d): %s" % (len(unknown), ", ".join(unknown[:12])))
if skipped:
print("not weights, left out (%d): %s" % (len(skipped), ", ".join(skipped[:8])))
# the DSpark drafter (drafter_pack.py's dspark.bin beside the quants' folders, from DeepSeek's checkpoint): its
# three blocks as mtp.0-2, so the engine drafts with them
files = names
if eg_from:
print("Engram tables from %s (%d shards)" % (eg_dir, len(eg_from)))
# experts of a second requantized model replace the main one's for some roles / layers (the byte layouts are per tensor: any mix of types)
n_ov = 0
for spec in (a.override_experts or []):
dpath, _, drl = spec.partition(":")
od = pathlib.Path(dpath).expanduser().resolve()
roles_ov = {"gate": "w1", "up": "w3", "down": "w2"}
want = {roles_ov[r] for r in (drl or a.override_roles).split(",")}
lay_ov = None
if a.override_layers:
lay_ov = set()
for part in a.override_layers.split(","):
lo, _, hi = part.partition("-")
lay_ov.update(range(int(lo), int(hi or lo) + 1))
ogs = [Gguf(pth) for pth in sorted(od.glob("*.gguf"))]
new = []
for og in ogs:
try:
orel = os.path.relpath(og.path, model).replace(os.sep, "/")
except ValueError:
raise SystemExit("%s must be on the model's drive" % od)
files.append(orel)
ofi = len(files) - 1
for name, typ, dims, off in og.tensors:
m = re.match(r"blk\.(\d+)\.ffn_(gate|up|down)_exps\.weight$", name)
if not m or typ not in TYPES:
continue
il, role = int(m.group(1)), {"gate": "w1", "up": "w3", "down": "w2"}[m.group(2)]
if role not in want or (lay_ov is not None and il not in lay_ov):
continue
tname, per, bpb = TYPES[typ]
nel = 1
for d in dims:
nel *= d
nbytes = nel // per * bpb
shape = list(reversed(dims))
n, part = shape[0], nbytes // shape[0]
for i in range(n):
new.append(("layers.%d.ffn.experts.%d.%s.weight" % (il, i, role), tname, ofi, og.data_start + off + i * part, part, shape[1:]))
names_new = {t[0] for t in new}
tensors[:] = [t for t in tensors if t[0] not in names_new] + new
n_ov += len(new)
print("experts overridden from %s: %d tensors (roles %s, layers %s)" % (od, len(new), drl or a.override_roles, a.override_layers or "all"))
# dense matrices requantized by dense_requant.py replace the GGUF's BF16 ones
n_dense = 0
for dsrc in (a.dense_override or []):
dd = pathlib.Path(dsrc).expanduser().resolve()
dj = json.loads((dd / "dense.json").read_text())
try:
relf = os.path.relpath(dd / "dense.bin", model).replace(os.sep, "/")
except ValueError:
raise SystemExit("%s must be on the model's drive" % dd)
if relf not in files:
files.append(relf)
dfi = files.index(relf)
pos = {t[0]: i for i, t in enumerate(tensors)}
n_here = n_add = 0
for name, (tname, fname, off, nb, shape) in dj.items():
if name not in pos:
# a tensor the quant leaves out (a --skip-tensors'd one, or a set that stores it under another layout):
# the override supplies it
tensors.append((name, tname, dfi, off, nb, shape))
pos[name] = len(tensors) - 1
n_add += 1
continue
tensors[pos[name]] = (name, tname, dfi, off, nb, shape)
n_here += 1
n_dense += n_here + n_add
print("dense override from %s: %d tensors replaced, %d added (a later folder wins)" % (dd, n_here, n_add))
# the DSpark drafter from unsloth's GGUF (architecture dflash): blk.N.* -> mtp.N.*, the head tensors under the
# checkpoint's names (fc -> main_proj, enc.output_norm -> main_norm, output_norm -> norm of the last block,
# conf_proj -> confidence_head.proj, markov_w1 / w2 -> markov_head.embed / head)
ds_path = pathlib.Path(a.dspark_gguf).expanduser().resolve() if a.dspark_gguf else next(
iter(sorted(model.parent.glob("dspark-*.gguf"))), None)
dspark_gguf = False
if ds_path is not None:
if not ds_path.is_file():
raise SystemExit("%s: no DSpark GGUF there" % ds_path)
dg = Gguf(ds_path)
if dg.kv.get("general.architecture") != "dflash":
raise SystemExit("%s: not a DSpark (dflash) GGUF" % ds_path)
# the engine's dspark.* geometry: a quant built by another tool (the IST-DAS sets) leaves it out, the drafter
# carries all of it except the noise token (a model constant) and the markov head's rank (the tensor's shape)
for k, dk in (("block_size", "block_size"), ("expert_count", "expert_count"),
("expert_used_count", "expert_used_count"), ("target_layers", "target_layers")):
v = dg.kv.get("dflash." + dk)
if v is not None:
kv.setdefault("%s.dspark.%s" % (arch, k), v)
if a.dspark_noise_token is not None:
kv.setdefault("%s.dspark.noise_token_id" % arch, int(a.dspark_noise_token))
if a.dspark_markov_rank is not None:
kv.setdefault("%s.dspark.markov_rank" % arch, int(a.dspark_markov_rank))
else:
for name, typ, dims, off in dg.tensors:
if "markov" in name and len(dims) == 2:
kv.setdefault("%s.dspark.markov_rank" % arch, int(dims[0]))
break
nb = int(dg.kv["dflash.block_count"])
files.append(rel(ds_path))
fi = len(files) - 1
HEAD = {"fc.weight": "mtp.0.main_proj.weight", "enc.output_norm.weight": "mtp.0.main_norm.weight",
"output_norm.weight": "mtp.%d.norm.weight" % (nb - 1),
"conf_proj.weight": "mtp.%d.confidence_head.proj.weight" % (nb - 1),
"markov_w1.weight": "mtp.%d.markov_head.embed.weight" % (nb - 1),
"markov_w2.weight": "mtp.%d.markov_head.head.weight" % (nb - 1)}
groups = int(kv["%s.attention.output_group_count" % kv["general.architecture"]])
bad = []
for name, typ, dims, off in dg.tensors:
if typ not in TYPES:
raise SystemExit("%s: %s has ggml type %d, which the engine does not read" % (ds_path.name, name, typ))
tname, per, bpb = TYPES[typ]
nel = 1
for d in dims:
nel *= d
nbytes = nel // per * bpb
m = re.match(r"blk\.(\d+)\.(.+)$", name)
if m and m.group(2) in LAYER:
ck = "mtp.%s.%s" % (m.group(1), LAYER[m.group(2)])
elif name in HEAD:
ck = HEAD[name]
else:
bad.append(name)
continue
shape = list(reversed(dims))
base = dg.data_start + off
if ck.endswith(".attn.wo_a.slice"):
part = nbytes // groups
for i in range(groups):
tensors.append(("%s.%d.weight" % (ck, i), tname, fi, base + i * part, part, [shape[0] // groups, shape[1]]))
elif ".ffn.experts." in ck:
n, part = shape[0], nbytes // shape[0]
pre, role = ck.rsplit(".", 1)
for i in range(n):
tensors.append(("%s.%d.%s.weight" % (pre, i, role), tname, fi, base + i * part, part, shape[1:]))
else:
tensors.append((ck, tname, fi, base, nbytes, shape))
if bad:
raise SystemExit("DSpark GGUF tensors the pack does not map (%d): %s" % (len(bad), ", ".join(bad[:12])))
dspark_gguf = True
print("DSpark drafter from %s: %d blocks" % (ds_path.name, nb))
# the vision tower from unsloth's mmproj GGUF (clip, projector deepseek41v): llama.cpp's names -> the checkpoint's;
# the F32 norms / biases / marker rows are read as BF16 by the engine; mlp.w1 is the file's gate and up
mm_path = pathlib.Path(a.mmproj).expanduser().resolve() if a.mmproj else find_mmproj(model)
mm_geo = {}
if mm_path is not None:
if not mm_path.is_file():
raise SystemExit("%s: no mmproj GGUF there" % mm_path)
mg = Gguf(mm_path)
if mg.kv.get("clip.projector_type") != "deepseek41v":
raise SystemExit("%s: not a DeepSeek-V4.1 vision GGUF (projector %r)" % (mm_path, mg.kv.get("clip.projector_type")))
files.append(rel(mm_path))
fi = len(files) - 1
FIX = {"v.patch_embd.weight": "vision.patch_embed.proj.weight", "v.patch_embd.bias": "vision.patch_embed.proj.bias",
"v.post_ln.weight": "vision.norm.weight", "mm.1.weight": "aligner.w1.weight", "mm.1.bias": "aligner.w1.bias",
"mm.2.weight": "aligner.w2.weight", "mm.2.bias": "aligner.w2.bias", "v.token_embd.img_start": "image_start",
"v.image_newline": "image_newline", "v.token_embd.img_end": "image_end"}
BLK = {"ln1.weight": "norm1.weight", "ln2.weight": "norm2.weight", "attn_qkv.weight": "attn.wqkv.weight",
"attn_qkv.bias": "attn.wqkv.bias", "attn_out.weight": "attn.wo.weight", "attn_out.bias": "attn.wo.bias",
"ffn_gate.weight": "mlp.gate.weight", "ffn_up.weight": "mlp.up.weight", "ffn_down.weight": "mlp.w2.weight"}
bad = []
for name, typ, dims, off in mg.tensors:
if typ not in TYPES:
raise SystemExit("%s: %s has ggml type %d, which the engine does not read" % (mm_path.name, name, typ))
tname, per, bpb = TYPES[typ]
nel = 1
for d in dims:
nel *= d
m = re.match(r"v\.blk\.(\d+)\.(.+)$", name)
if m and m.group(2) in BLK:
ck = "vision.blocks.%s.%s" % (m.group(1), BLK[m.group(2)])
elif name in FIX:
ck = FIX[name]
else:
bad.append(name)
continue
shape = list(reversed(dims))
if name == "v.patch_embd.weight": # conv [out][3][14][14] -> [out][3 * 14 * 14], the same bytes
shape = [shape[0], nel // shape[0]]
tensors.append((ck, tname, fi, mg.data_start + off, nel // per * bpb, shape))
if bad:
raise SystemExit("mmproj tensors the pack does not map (%d): %s" % (len(bad), ", ".join(bad[:12])))
k = lambda n, d=None: mg.kv.get("clip.vision." + n, d) # noqa: E731
toks = kv.get("tokenizer.ggml.tokens", [])
img_id = next((i for i, t in enumerate(toks) if t == "<|deepseek_image|>"), None)
if img_id is None:
raise SystemExit("the vocabulary has no <|deepseek_image|> token")
mm_geo = {"vision.num_hidden_layers": k("block_count"), "vision.hidden_size": k("embedding_length"),
"vision.num_attention_heads": k("attention.head_count"), "vision.intermediate_size": k("feed_forward_length"),
"vision.patch_size": k("patch_size"), "vision.downsample_ratio": k("projector.scale_factor"),
"vision.rope_theta": 10000, "vision.max_image_tokens": 1024, "vision.min_pixels": k("image_min_pixels"),
"image_token_id": img_id}
print("vision tower from %s: %d blocks, image token %d" % (mm_path.name, mm_geo["vision.num_hidden_layers"], img_id))
# trellis experts from tq_convert.py: per layer the three roles stacked [n_exp][rows][row bytes] in one file
tq_layers = []
if a.tq_experts:
by_layer, tq_dirs = {}, {}
for d in a.tq_experts:
tqd = pathlib.Path(d).expanduser().resolve()
for key, ent in json.loads((tqd / "tq.json").read_text()).items():
m = re.match(r"layers\.(\d+)\.ffn\.experts\.(w[123])$", key)
if not m:
raise SystemExit("tq.json: %s is not a layer's expert role" % key)
by_layer.setdefault(int(m.group(1)), {})[m.group(2)] = ent
tq_dirs[(int(m.group(1)), m.group(2))] = tqd
if a.tq_layers:
keep = {int(x) for x in a.tq_layers.split(",")}
by_layer = {il: r for il, r in by_layer.items() if il in keep}
TQTYPES = {v[0]: k for k, v in TYPES.items()}
for il, roles in sorted(by_layer.items()):
if sorted(roles) != ["w1", "w2", "w3"]:
raise SystemExit("tq.json: layer %d lacks a role (has %s)" % (il, sorted(roles)))
if len({r[0] for r in roles.values()}) != 1 or roles["w1"][0] != roles["w3"][0]:
raise SystemExit("tq.json: layer %d: gate and up must be one type" % il)
drop = re.compile(r"layers\.%d\.ffn\.experts\.\d+\.w[123]\.weight$" % il)
kept = [t for t in tensors if not drop.match(t[0])]
if len(kept) == len(tensors):
raise SystemExit("layer %d has no routed experts in the GGUF to replace" % il)
tensors[:] = kept
for role, (tname, fname, off, total, shape) in roles.items():
if tname not in TQTYPES:
raise SystemExit("tq.json: unknown type %s" % tname)
n_exp, rows, cols = shape
per = total // n_exp
f = tq_dirs[(il, role)] / fname
if not f.is_file() or f.stat().st_size < off + total:
raise SystemExit("%s: missing or short" % f)
try:
relf = os.path.relpath(f, model).replace(os.sep, "/")
except ValueError:
raise SystemExit("%s must be on the model's drive" % f)
if relf not in files:
files.append(relf)
fi = files.index(relf)
for e in range(n_exp):
tensors.append(("layers.%d.ffn.experts.%d.%s.weight" % (il, e, role), tname, fi, off + e * per, per, [rows, cols]))
tq_layers.append(il)
print("trellis experts from %s: layers %s" % (", ".join(a.tq_experts), tq_layers))
drafter = pathlib.Path(a.drafter).expanduser().resolve() if a.drafter else model.parent / "dspark" / "dspark.json"
if a.drafter and not drafter.is_file():
raise SystemExit("%s: no drafter there" % drafter)
drafter_in = (drafter.is_file() and drafter.with_suffix(".bin").is_file()) and not dspark_gguf
if drafter_in:
files.append(rel(drafter.with_suffix(".bin")))
groups = int(kv["%s.attention.output_group_count" % kv["general.architecture"]])
for name, dt, off, nb, shape in json.loads(drafter.read_text())["tensors"]:
if name.endswith(".attn.wo_a.weight"): # (one entry a group, as the trunk's)
for i in range(groups):
tensors.append(("%s.slice.%d.weight" % (name[:-len(".weight")], i), dt, len(files) - 1,
off + i * (nb // groups), nb // groups, [shape[0] // groups, shape[1]]))
continue
tensors.append((name, dt, len(files) - 1, off, nb, shape))
# the vision tower (vision_pack.py's vision.bin, from DeepSeek's checkpoint): its tensors under the checkpoint's
# names, the picture span's marker rows, and the geometry config.json gives them
vdir = pathlib.Path(a.vision).expanduser().resolve() if a.vision else model.parent / "vision"
vision = {}
if (vdir / "vision.json").is_file() and (vdir / "vision.bin").is_file():
try:
rel = os.path.relpath(vdir / "vision.bin", model).replace(os.sep, "/")
except ValueError: # (Windows: another drive)
raise SystemExit("%s: the vision folder must be on the model's drive" % vdir)
if " " in rel:
raise SystemExit("%s: the vision folder's path relative to the model has a space" % vdir)
files.append(rel)
info = json.loads((vdir / "vision.json").read_text())
for name, dt, off, nb, shape in info["tensors"]:
tensors.append((name, dt, len(files) - 1, off, nb, shape))
vision = info["config"]
if mm_geo and not vision:
vision = mm_geo
vocab = next(t[5][0] for t in tensors if t[0] == "embed.weight")
geo = geometry(kv, vocab)
out.mkdir(parents=True, exist_ok=True)
with (out / "ds4.txt").open("w") as f:
for k, v in geo.items():
if v is None:
continue
if isinstance(v, bool):
v = int(v)
f.write("%s %s\n" % (k, ",".join(str(x) for x in v) if isinstance(v, list) else v))
for k, v in vision.items():
f.write("%s %s\n" % (k, v))
f.write("format gguf\n")
f.write("model_dir %s\n" % model)
with (out / "tensors.txt").open("w") as f:
for i, name in enumerate(files):
f.write("file %d %s\n" % (i, name))
for name, dt, fi, off, nb, shape in tensors:
f.write("t %s %s %d %d %d %s\n" % (name, dt, fi, off, nb, " ".join(map(str, shape))))
nl, cols = write_engram(out / "engram.bin", kv, vocab)
# the server's chat template: the GGUF's own (unsloth's, byte-identical to DeepSeek's encoding.py on the 9 cases we
# checked: chat, thinking, effort, system, multi-turn, tools, tool results). Project Maya's tools/ds4/chat_template.jinja
# lost the tool associations and later system instructions (their #299), so it is NOT used here.
template = kv.get("tokenizer.chat_template")
if not template:
sys.exit("%s: the GGUF has no tokenizer.chat_template; refusing to fall back to the old Maya template (#299)" % model)
write_tokenizer(out / "tokenizer", kv, template)
by = {}
for t in tensors:
by[t[1]] = by.get(t[1], 0) + t[4]
extras = [w for w, there in (("the DSpark drafter", drafter_in or dspark_gguf), ("the vision tower", bool(vision)), ("trellis experts in layers %s" % tq_layers, bool(tq_layers)), ("%d dense matrices requantized" % n_dense, bool(n_dense)), ("%d experts from %s" % (n_ov, a.override_experts), bool(n_ov))) if there]
print("%s: %d tensors in %d files (%s), Engram %d layers x %d hash columns%s -> %s" %
(model.name, len(tensors), len(files), ", ".join("%s %.1f GB" % (k, v / 1e9) for k, v in sorted(by.items())),
nl, cols, "".join(", " + w for w in extras), out))
return 0
if __name__ == "__main__":
sys.exit(main())