Skip to content

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++

Own model files: the checker in front of setup accepts what setup --gguf-dir accepted (Unsloth split sets with a metadata-only first shard, links, several sizes in a folder, a folder above the model folder, more than 128 files); Unsloth Q5/Q6/Q8 and Swift IQ3_S are in the table

Niko1221f207907b14e5
diff --git a/data/gguf_fingerprints.json b/data/gguf_fingerprints.json
index ac99a748d..e82ace8b3 100644
--- a/data/gguf_fingerprints.json
+++ b/data/gguf_fingerprints.json
@@ -215,6 +215,86 @@
],
"repo": "agentionai/Qwen3.8-Flash-Next-Gyro-GGUF"
},
+ "unsloth/UD-Q5_K_XL": {
+ "arch": "qwen4exp",
+ "tensors": 1224,
+ "bytes": 158275381760,
+ "expert_bytes": {
+ "Q5_K": 54211379200,
+ "Q6_K": 1376256000,
+ "Q8_0": 42781900800
+ },
+ "experts_bpw": 6.515,
+ "bpw": 7.156,
+ "files": [
+ "UD-Q5_K_XL/Qwen3.8-Flash-Next-UD-Q5_K_XL-00001-of-00006.gguf",
+ "UD-Q5_K_XL/Qwen3.8-Flash-Next-UD-Q5_K_XL-00002-of-00006.gguf",
+ "UD-Q5_K_XL/Qwen3.8-Flash-Next-UD-Q5_K_XL-00003-of-00006.gguf",
+ "UD-Q5_K_XL/Qwen3.8-Flash-Next-UD-Q5_K_XL-00004-of-00006.gguf",
+ "UD-Q5_K_XL/Qwen3.8-Flash-Next-UD-Q5_K_XL-00005-of-00006.gguf",
+ "UD-Q5_K_XL/Qwen3.8-Flash-Next-UD-Q5_K_XL-00006-of-00006.gguf"
+ ],
+ "repo": "unsloth/Qwen3.8-Flash-Next-GGUF"
+ },
+ "unsloth/UD-Q6_K_XL": {
+ "arch": "qwen4exp",
+ "tensors": 1224,
+ "bytes": 169154357760,
+ "expert_bytes": {
+ "Q6_K": 64684032000,
+ "Q8_0": 44564480000
+ },
+ "experts_bpw": 7.235,
+ "bpw": 7.648,
+ "files": [
+ "UD-Q6_K_XL/Qwen3.8-Flash-Next-UD-Q6_K_XL-00001-of-00006.gguf",
+ "UD-Q6_K_XL/Qwen3.8-Flash-Next-UD-Q6_K_XL-00002-of-00006.gguf",
+ "UD-Q6_K_XL/Qwen3.8-Flash-Next-UD-Q6_K_XL-00003-of-00006.gguf",
+ "UD-Q6_K_XL/Qwen3.8-Flash-Next-UD-Q6_K_XL-00004-of-00006.gguf",
+ "UD-Q6_K_XL/Qwen3.8-Flash-Next-UD-Q6_K_XL-00005-of-00006.gguf",
+ "UD-Q6_K_XL/Qwen3.8-Flash-Next-UD-Q6_K_XL-00006-of-00006.gguf"
+ ],
+ "repo": "unsloth/Qwen3.8-Flash-Next-GGUF"
+ },
+ "unsloth/Q8_0": {
+ "arch": "qwen4exp",
+ "tensors": 1224,
+ "bytes": 188214008320,
+ "expert_bytes": {
+ "Q8_0": 128345702400
+ },
+ "experts_bpw": 8.5,
+ "bpw": 8.51,
+ "files": [
+ "Q8_0/Qwen3.8-Flash-Next-Q8_0-00001-of-00006.gguf",
+ "Q8_0/Qwen3.8-Flash-Next-Q8_0-00002-of-00006.gguf",
+ "Q8_0/Qwen3.8-Flash-Next-Q8_0-00003-of-00006.gguf",
+ "Q8_0/Qwen3.8-Flash-Next-Q8_0-00004-of-00006.gguf",
+ "Q8_0/Qwen3.8-Flash-Next-Q8_0-00005-of-00006.gguf",
+ "Q8_0/Qwen3.8-Flash-Next-Q8_0-00006-of-00006.gguf"
+ ],
+ "repo": "unsloth/Qwen3.8-Flash-Next-GGUF"
+ },
+ "swift/IQ3_S": {
+ "arch": "qwen4exp",
+ "tensors": 1224,
+ "bytes": 83732712960,
+ "expert_bytes": {
+ "IQ2_S": 10747904000,
+ "IQ3_S": 7208960000,
+ "IQ3_XXS": 10918297600,
+ "IQ4_NL": 18402508800,
+ "IQ4_XS": 891289600,
+ "Q2_0": 2123366400
+ },
+ "experts_bpw": 3.331,
+ "bpw": 3.786,
+ "files": [
+ "Swift-Qwen3.8-Flash-Next-GSQ-RCO-IQ3_S-00001-of-00002.gguf",
+ "Swift-Qwen3.8-Flash-Next-GSQ-RCO-IQ3_S-00002-of-00002.gguf"
+ ],
+ "repo": "ukisai/Swift-1.5-Qwen3.8-Flash-Next-GSQ-RCO-GGUF"
+ },
"_roles": {
"blk.N.attn_gate.weight": [
"IQ3_S",
diff --git a/strata_control/gguf_preflight.py b/strata_control/gguf_preflight.py
index b8e037485..ed83b1eb0 100644
--- a/strata_control/gguf_preflight.py
+++ b/strata_control/gguf_preflight.py
@@ -86,12 +86,27 @@ class _Reader:
return None
+def real_model_file(path: Path) -> Path:
+ """The regular file a model path stands for. A model file the person picked can be a link (a Hugging Face cache snapshot, an
+ Ollama blob, a shortcut to a bigger drive): it is followed here, once, and the target is what gets opened. Strata's own state files
+ (run configs, profiles, runtime records) keep the strict no-link rule in their readers."""
+ try:
+ target = Path(os.path.realpath(path))
+ info = target.stat()
+ except OSError:
+ if os.path.islink(path):
+ raise ProfileError(f"{Path(path).name} is a link to a file that is not there", 5) from None
+ raise ProfileError(f"{Path(path).name} is missing", 5) from None
+ if not stat.S_ISREG(info.st_mode):
+ raise ProfileError("GGUF shard must be a regular file", 5)
+ return target
+
+
def inspect_metadata(path: Path) -> dict:
- """Return only bounded compatibility signals from one regular GGUF v3 shard."""
+ """Return only bounded compatibility signals from one regular GGUF v3 shard (a link to one is followed)."""
try:
- if stat.S_ISLNK(path.lstat().st_mode):
- raise ProfileError("GGUF shard is a symlink", 5)
- descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
+ path = real_model_file(Path(path))
+ descriptor = os.open(path, os.O_RDONLY)
with os.fdopen(descriptor, "rb") as stream:
details = os.fstat(stream.fileno())
if not stat.S_ISREG(details.st_mode):
@@ -102,7 +117,8 @@ def inspect_metadata(path: Path) -> dict:
version, tensors, keys = reader.u32(), reader.u64(), reader.u64()
if version != 3:
raise ProfileError("Strata metadata preflight requires GGUF v3", 5)
- if not 1 <= tensors <= MAX_TENSORS or keys > MAX_METADATA_KEYS:
+ # tensors == 0 is a real file: a split set made with llama.cpp's gguf-split (Unsloth's) keeps only the metadata in its first shard
+ if not 0 <= tensors <= MAX_TENSORS or keys > MAX_METADATA_KEYS:
raise ProfileError("GGUF tensor or metadata count exceeds the inspection limit", 5)
found: dict[str, object] = {}
for _ in range(keys):
@@ -159,7 +175,7 @@ def inspect_metadata(path: Path) -> dict:
extents.sort()
if any(next_start < end for (_, end), (next_start, _) in zip(extents, extents[1:])):
raise ProfileError("GGUF tensor byte ranges overlap", 5)
- if data_start + required_payload_bytes > details.st_size:
+ if tensors and data_start + required_payload_bytes > details.st_size:
raise ProfileError("GGUF tensor payload is shorter than its directory requires", 5)
if tensors == 1 and details.st_size - (data_start + required_payload_bytes) >= 64:
raise ProfileError("single-tensor GGUF shard has unexplained trailing bytes", 5)
diff --git a/strata_control/models.py b/strata_control/models.py
index f07dc10ed..f499b1c3c 100644
--- a/strata_control/models.py
+++ b/strata_control/models.py
@@ -23,7 +23,7 @@ from pathlib import Path
from strata_control import discovery
from strata_control.doctor import inspect as inspect_components
-from strata_control.gguf_preflight import inspect_metadata
+from strata_control.gguf_preflight import inspect_metadata, real_model_file
from strata_control.profiles import ProfileError
@@ -34,8 +34,9 @@ MAX_CONFIGS = 128
MAX_IMPORT_SHARDS = 128
SHARD = re.compile(r"(.+)-(\d{5})-of-(\d{5})\.gguf\Z", re.I)
SUPPORTED_SELECTIONS = frozenset({"qwen/Q2_0", "qwen/IQ2_XS", "qwen/IQ3_XXS", "qwen/IQ3_S",
- "swift/IQ2_XS", "swift/IQ3_XXS", "coder/IQ1_M",
- "unsloth/UD-IQ4_XS", "unsloth/UD-Q4_K_XL", "gyro/Gyro-S", "gyro/Gyro-M"})
+ "swift/IQ2_XS", "swift/IQ3_XXS", "swift/IQ3_S", "coder/IQ1_M",
+ "unsloth/UD-IQ4_XS", "unsloth/UD-Q4_K_XL", "unsloth/UD-Q5_K_XL", "unsloth/UD-Q6_K_XL",
+ "unsloth/Q8_0", "gyro/Gyro-S", "gyro/Gyro-M"})
def settings_path() -> Path:
@@ -216,10 +217,10 @@ def inspect(model_id: str, override: str | None = None) -> dict:
def _gguf_header(path: Path) -> dict:
+ """The first bytes of one model file (a link to it is followed: Hugging Face cache snapshots and Ollama blobs are links)."""
+ real = real_model_file(path)
try:
- if stat.S_ISLNK(path.lstat().st_mode):
- raise ProfileError("GGUF shard is a symlink", 5)
- descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
+ descriptor = os.open(real, os.O_RDONLY)
with os.fdopen(descriptor, "rb") as stream:
details = os.fstat(stream.fileno())
if not stat.S_ISREG(details.st_mode) or details.st_size < 8:
@@ -333,31 +334,144 @@ def _assess_projector(path: Path) -> dict:
return row
+MAX_LISTED = 5000 # .gguf files looked at in one folder (the checker reads headers of the chosen set only)
+MAX_TREE_DIRS = 300 # folders looked into when the picked folder holds no GGUF itself
+TREE_DEPTH = 3
+SKIP_DIRS = frozenset({"packs", "mtp", "engine", "node_modules", "windows", "program files", "program files (x86)",
+ "$recycle.bin", "system volume information", "appdata"})
+
+
+def _list_gguf(folder: Path) -> tuple[list[Path], list[str], bool]:
+ """(model files, picture-reader file names, cut) of one folder. A link to a file counts (it is followed when read); a name that
+ only ends in .gguf but is a folder does not."""
+ shards: list[Path] = []
+ readers: list[str] = []
+ cut = False
+ try:
+ with os.scandir(folder) as entries:
+ for entry in entries:
+ low = entry.name.lower()
+ if not low.endswith(".gguf"):
+ continue
+ try:
+ is_file = entry.is_file() or entry.is_symlink()
+ except OSError:
+ is_file = False
+ if not is_file:
+ continue
+ if low.startswith("mmproj"):
+ readers.append(entry.name)
+ continue
+ if len(shards) >= MAX_LISTED:
+ cut = True
+ break
+ shards.append(Path(entry.path))
+ except OSError:
+ raise ProfileError("cannot inspect GGUF directory", 5) from None
+ return shards, readers, cut
+
+
+def _folders_with_models(root: Path) -> list[Path]:
+ """The folders under `root` (a Strata data folder, a whole Hugging Face repository, a drive's model folder) that hold model files,
+ breadth first, `TREE_DEPTH` levels deep. A folder with models is not searched further."""
+ found: list[Path] = []
+ seen: set[str] = set()
+ queue = [(root, 0)]
+ while queue and len(seen) < MAX_TREE_DIRS:
+ folder, depth = queue.pop(0)
+ try:
+ key = os.path.normcase(os.path.realpath(folder))
+ except OSError:
+ continue
+ if key in seen:
+ continue
+ seen.add(key)
+ try:
+ with os.scandir(folder) as scan:
+ entries = sorted(scan, key=lambda e: e.name.lower())
+ except OSError:
+ continue
+ if any(e.name.lower().endswith(".gguf") and not e.name.lower().startswith("mmproj") for e in entries):
+ found.append(folder)
+ continue
+ if depth >= TREE_DEPTH:
+ continue
+ for e in entries:
+ try:
+ if e.is_dir() and not e.name.startswith(".") and e.name.lower() not in SKIP_DIRS:
+ queue.append((Path(e.path), depth + 1))
+ except OSError:
+ continue
+ return found
+
+
+def _split_groups(shards: list[Path]) -> dict:
+ """Model files by set: (name before -0000i-of-0000N, N) -> files. A file with no shard number is a set of its own."""
+ groups: dict = {}
+ for item in shards:
+ match = SHARD.fullmatch(item.name)
+ key = (match.group(1), int(match.group(3))) if match else (item.name, 1)
+ groups.setdefault(key, []).append(item)
+ return groups
+
+
+def _known(members: list[Path]) -> dict | None:
+ try:
+ return _candidate_selection(sorted(members, key=lambda item: item.name))
+ except ProfileError:
+ return None
+
+
+def _holds(groups_by_place: list) -> list[dict]:
+ """What a folder (or several) holds, set by set, for the message that asks the person to point at one."""
+ rows = []
+ for place, members_by_key in groups_by_place:
+ for key in sorted(members_by_key):
+ members = sorted(members_by_key[key], key=lambda item: item.name)
+ sel = _known(members)
+ rows.append({"file": members[0].name, "files": len(members), "folder": str(place),
+ "family": sel["family"] if sel else None, "model": sel["model"] if sel else None})
+ return rows
+
+
def plan_import(raw_path: str) -> dict:
- """Inspect a local candidate without copying, parsing tensors or adopting it."""
+ """Inspect a local candidate without copying, parsing tensors or adopting it.
+
+ The picked path can be a .gguf file (any shard of a split set), the folder with the files, or a folder above it (a Strata data
+ folder, a whole Hugging Face repository): the folder with the model is looked for, and when a folder holds several models
+ the one Strata knows is used if it is the only one; with two it says which and asks for the file. The result's `model_dir`
+ is the folder to hand to setup (--gguf-dir). Links to files and folders are followed."""
path = Path(raw_path).expanduser()
if not path.is_absolute():
raise ProfileError("model import path must be absolute")
try:
- details = path.lstat()
+ details = path.stat()
except OSError:
- raise ProfileError("model import path does not exist", 5) from None
- if stat.S_ISLNK(details.st_mode):
- raise ProfileError("model import path must not be a symlink", 5)
+ raise ProfileError("model import path does not exist (or is a link to something that is gone)", 5) from None
+ notes: list[str] = []
+ folder_holds: list[dict] = []
+ issues: list[str] = []
if stat.S_ISDIR(details.st_mode):
- try:
- shards = []
- ignored_auxiliary = []
- for child in path.iterdir():
- if child.name.lower().endswith(".gguf"):
- if child.name.lower().startswith("mmproj"):
- ignored_auxiliary.append(child.name)
- continue
- shards.append(child)
- if len(shards) > MAX_IMPORT_SHARDS:
- raise ProfileError("more than 128 GGUF candidates in the directory", 5)
- except OSError:
- raise ProfileError("cannot inspect GGUF directory", 5) from None
+ shards, ignored_auxiliary, cut = _list_gguf(path)
+ if cut:
+ notes.append(f"This folder holds more than {MAX_LISTED} GGUF files; only the first {MAX_LISTED} were looked at.")
+ if not shards:
+ places = _folders_with_models(path)
+ if not places:
+ raise ProfileError("no GGUF files found at the model import path (or in the folders inside it)", 5)
+ scanned = [(place, *_list_gguf(place)[:2]) for place in places]
+ usable = [(place, files, readers, members) for place, files, readers in scanned
+ for _key, members in sorted(_split_groups(files).items(), key=lambda kv: kv[0]) if _known(members)]
+ if len(usable) == 1:
+ place, shards, ignored_auxiliary, members = usable[0]
+ notes.append(f"The model files are in {place}.")
+ else:
+ place, shards, ignored_auxiliary = scanned[0]
+ if len(usable) > 1 or len(scanned) > 1:
+ issues.append("multiple_model_groups")
+ folder_holds = _holds([(p, _split_groups(f)) for p, f, _r in scanned])
+ else:
+ notes.append(f"The model files are in {place}.")
elif stat.S_ISREG(details.st_mode) and path.name.lower().endswith(".gguf"):
ignored_auxiliary = []
try: # the picture reader that sits next to a chosen model file
@@ -382,31 +496,24 @@ def plan_import(raw_path: str) -> dict:
if not shards:
raise ProfileError("no GGUF files found at the model import path", 5)
shards.sort(key=lambda item: item.name)
- groups = {}
- for item in shards:
- match = SHARD.fullmatch(item.name)
- if match:
- key = (match.group(1), int(match.group(3)))
- groups.setdefault(key, set()).add(int(match.group(2)))
+ groups = _split_groups(shards)
+ if len(groups) != 1 and "multiple_model_groups" not in issues:
+ known_sets = [key for key, members in groups.items() if _known(members)]
+ if len(known_sets) == 1:
+ # one set in the folder is a model Strata knows: use it and say what else is there
+ keep = known_sets[0]
+ others = sorted(sorted(m, key=lambda x: x.name)[0].name for k, m in groups.items() if k != keep)
+ shards = sorted(groups[keep], key=lambda item: item.name)
+ notes.append("The folder also holds " + ", ".join(others[:6]) + (" and more" if len(others) > 6 else "") +
+ f"; Strata uses {shards[0].name} and leaves the others alone.")
+ groups = {keep: shards}
else:
- groups.setdefault((item.name, 1), set()).add(1)
- issues = []
- folder_holds = []
- if len(groups) != 1:
- issues.append("multiple_model_groups")
- # a folder with several models: say which ones Strata knows, so the person can point at one of them
- for key in sorted(groups):
- members = [item for item in shards if (SHARD.fullmatch(item.name) and (SHARD.fullmatch(item.name).group(1),
- int(SHARD.fullmatch(item.name).group(3))) == key) or (not SHARD.fullmatch(item.name) and (item.name, 1) == key)]
- try:
- known = _candidate_selection(members)
- except ProfileError:
- known = None
- folder_holds.append({"file": members[0].name if members else key[0], "files": len(members),
- "family": known["family"] if known else None, "model": known["model"] if known else None})
- if len(groups) == 1:
- (_, total), indices = next(iter(groups.items()))
- if total > MAX_IMPORT_SHARDS or indices != set(range(1, total + 1)):
+ issues.append("multiple_model_groups")
+ folder_holds = _holds([(shards[0].parent, groups)])
+ if len(groups) == 1 and "multiple_model_groups" not in issues:
+ (_, total), members = next(iter(groups.items()))
+ found = {int(m.group(2)) for m in (SHARD.fullmatch(item.name) for item in members) if m} or {1}
+ if total > MAX_IMPORT_SHARDS or found != set(range(1, total + 1)):
issues.append("incomplete_or_invalid_shard_set")
files = []
for item in shards:
@@ -438,9 +545,13 @@ def plan_import(raw_path: str) -> dict:
if metadata["tokenizer_model"] != "gpt2" or not metadata["tokenizer_tokens_present"] or \
not metadata["tokenizer_merges_present"]:
issues.append("unsupported_or_incomplete_tokenizer_metadata")
- projectors = [_assess_projector(path.parent / n if path.is_file() else path / n)
- for n in sorted(ignored_auxiliary)[:8]]
- messages = []
+ model_dir = shards[0].parent
+ projectors = [_assess_projector(model_dir / n) for n in sorted(ignored_auxiliary)[:8]]
+ messages = list(notes)
+ if folder_holds:
+ names = [f"{h['family']} {h['model']} ({h['file']})" if h.get("model") else h["file"] for h in folder_holds[:8]]
+ messages.append(f"The folder holds {len(folder_holds)} models: " + "; ".join(names) + (" and more" if len(folder_holds) > 8 else "") +
+ ". Choose the folder of the one you want, or type the path of its .gguf file.")
if any(i.endswith("unsupported_architecture") or i == "unsupported_or_missing_architecture" for i in issues):
messages.append(UNSUPPORTED_MODEL_TYPE)
elif projectors:
@@ -448,13 +559,15 @@ def plan_import(raw_path: str) -> dict:
candidate = _candidate_selection(shards)
if candidate is None and metadata is not None and not issues:
candidate = _candidate_by_header(shards, observed_tensor_count, observed_payload, observed_experts)
- if candidate is None:
+ if "multiple_model_groups" in issues:
+ candidate = None # nothing is chosen for the person
+ if candidate is None and not {"multiple_model_groups", "incomplete_or_invalid_shard_set"} & set(issues):
issues.append("unrecognized_or_unsupported_model_variant")
- elif metadata is not None:
+ elif candidate is not None and metadata is not None:
expected = set(candidate["expected_expert_types"])
if not observed_experts or observed_experts - expected:
issues.append("missing_or_unexpected_expert_quantization")
- return {"source": str(path), "scope": "local_gguf_candidate", "files": files,
+ return {"source": str(path), "model_dir": str(model_dir), "scope": "local_gguf_candidate", "files": files,
"file_count": len(files), "total_bytes": sum(item["bytes"] for item in files),
"metadata": metadata, "candidate_selection": candidate,
"observed_expert_types": sorted(observed_experts),
diff --git a/tests/terminal/test_own_files.py b/tests/terminal/test_own_files.py
new file mode 100644
index 000000000..4d94bd1af
--- /dev/null
+++ b/tests/terminal/test_own_files.py
@@ -0,0 +1,261 @@
+"""0.2.2: "use my own model files" accepts every layout 0.1.45's `setup.py --gguf-dir` accepted (issues #3316 #3292 #3190 #3209 #3331).
+
+The checker in front of setup (strata_control/models.plan_import) used to be stricter than setup itself: a split set whose first shard
+holds only the metadata (Unsloth's), a link to the file (Hugging Face cache, Ollama), a folder holding several sizes, a folder above the
+model folder (a whole repository, a 0.1.45 data folder), more than 128 files in a folder. Tiny GGUF files with the real shard names
+stand for the real ones (the shard names and the expert types are what the table checks)."""
+
+from __future__ import annotations
+
+import json
+import os
+import struct
+import tempfile
+import unittest
+from pathlib import Path
+
+from strata_control import gguf_preflight, models
+from strata_control.profiles import ProfileError
+from tools.gguf_reader import BLOCK_GEOMETRY
+
+TYPE_IDS = {"Q8_0": 8, "IQ3_S": 21, "IQ4_NL": 20, "IQ4_XS": 23, "IQ3_XXS": 18, "Q2_0": 42, "IQ2_S": 22, "IQ2_XS": 17}
+
+
+def string(value: str) -> bytes:
+ raw = value.encode()
+ return struct.pack("<Q", len(raw)) + raw
+
+
+def gguf_bytes(experts: list[str], *, metadata: bool = True) -> bytes:
+ """A tiny qwen4exp GGUF with one routed-expert tensor per type named; `experts=[]` is the metadata-only first shard of a split set."""
+ pairs = [("general.architecture", 8, string("qwen4exp")), ("tokenizer.ggml.model", 8, string("gpt2")),
+ ("tokenizer.ggml.tokens", 9, struct.pack("<IQ", 8, 1) + string("a")),
+ ("tokenizer.ggml.merges", 9, struct.pack("<IQ", 8, 1) + string("a b"))] if metadata else []
+ header = b"GGUF" + struct.pack("<IQQ", 3, len(experts), len(pairs)) + \
+ b"".join(string(k) + struct.pack("<I", kind) + value for k, kind, value in pairs)
+ offset = 0
+ for i, name in enumerate(experts):
+ block, size = BLOCK_GEOMETRY[name]
+ header += string(f"blk.{i}.ffn_gate_exps.weight") + struct.pack("<IQIQ", 1, block, TYPE_IDS[name], offset)
+ offset += -(-size // 32) * 32
+ header += b"\x00" * (-len(header) % 32)
+ return header + b"\x00" * offset
+
+
+UNSLOTH_Q4 = ["Qwen3.8-Flash-Next-UD-Q4_K_XL-0000%d-of-00004.gguf" % i for i in (1, 2, 3, 4)]
+UNSLOTH_IQ4 = ["Qwen3.8-Flash-Next-UD-IQ4_XS-0000%d-of-00003.gguf" % i for i in (1, 2, 3)]
+Q2 = ["Qwen3.8-Flash-Next-GSQ-RCO-Q2_0-0000%d-of-00002.gguf" % i for i in (1, 2)]
+IQ3XXS = ["Qwen3.8-Flash-Next-GSQ-RCO-IQ3_XXS-0000%d-of-00002.gguf" % i for i in (1, 2)]
+
+
+class Base(unittest.TestCase):
+ def setUp(self):
+ self.tmp = tempfile.TemporaryDirectory(prefix="strata-own-")
+ self.addCleanup(self.tmp.cleanup)
+ self.base = Path(self.tmp.name)
+
+ def put(self, folder: Path, names: list[str], experts: list[str]) -> Path:
+ folder.mkdir(parents=True, exist_ok=True)
+ for n in names:
+ (folder / n).write_bytes(gguf_bytes(experts))
+ return folder
+
+ def gsq(self, folder: Path, names: list[str], kind: str) -> Path:
+ return self.put(folder, names, [kind])
+
+ def unsloth(self, folder: Path, names: list[str], kinds: list[str]) -> Path:
+ """The first shard has only the metadata (what llama.cpp's gguf-split makes), the others carry tensors."""
+ folder.mkdir(parents=True, exist_ok=True)
+ (folder / names[0]).write_bytes(gguf_bytes([]))
+ for n in names[1:]:
+ (folder / n).write_bytes(gguf_bytes(kinds, metadata=False))
+ return folder
+
+
+class MetadataOnlyFirstShard(Base):
+ def test_unsloth_split_set_is_recognised(self):
+ folder = self.unsloth(self.base / "u", UNSLOTH_Q4, ["IQ4_NL"])
+ plan = models.plan_import(str(folder))
+ # the tiny files carry IQ4_NL experts, which UD-Q4_K_XL does not list: the set is found, the quantization is what is flagged
+ self.assertNotIn("unsupported_or_missing_architecture", plan["issues"])
+ self.assertNotIn("unsupported_or_incomplete_tokenizer_metadata", plan["issues"])
+ self.assertNotIn("GGUF tensor or metadata count", " ".join(plan["issues"]))
+ self.assertEqual((plan["candidate_selection"]["family"], plan["candidate_selection"]["model"]), ("unsloth", "UD-Q4_K_XL"))
+
+ def test_unsloth_iq4_xs_passes_with_its_real_expert_types(self):
+ folder = self.unsloth(self.base / "u", UNSLOTH_IQ4, ["IQ3_S", "IQ4_NL", "IQ4_XS", "Q8_0"])
+ plan = models.plan_import(str(folder))
+ self.assertEqual(plan["issues"], [])
+ self.assertEqual(plan["candidate_selection"]["model"], "UD-IQ4_XS")
+ self.assertEqual(plan["model_dir"], str(folder))
+
+ def test_a_shard_with_no_tensors_and_no_metadata_is_still_refused(self):
+ f = self.base / "x.gguf"
+ f.write_bytes(gguf_bytes([], metadata=False))
+ plan = models.plan_import(str(f))
+ self.assertIn("unsupported_or_missing_architecture", plan["issues"])
+
+
+class Links(Base):
+ def make_links(self):
+ blobs = self.base / "blobs"
+ snap = self.base / "snapshots" / "abc" / "Q2_0"
+ blobs.mkdir()
+ snap.mkdir(parents=True)
+ for i, n in enumerate(Q2):
+ (blobs / f"sha{i}").write_bytes(gguf_bytes(["Q2_0"]))
+ try:
+ os.symlink(blobs / f"sha{i}", snap / n)
+ except (OSError, NotImplementedError):
+ self.skipTest("this account cannot create symbolic links")
+ return snap
+
+ def test_a_hugging_face_cache_snapshot_is_used_through_its_links(self):
+ snap = self.make_links()
+ plan = models.plan_import(str(snap))
+ self.assertEqual(plan["issues"], [])
+ self.assertEqual(plan["candidate_selection"]["model"], "Q2_0")
+ self.assertEqual(plan["file_count"], 2)
+
+ def test_a_link_to_the_folder_is_followed(self):
+ real = self.gsq(self.base / "real", Q2, "Q2_0")
+ link = self.base / "link"
+ try:
+ os.symlink(real, link, target_is_directory=True)
+ except (OSError, NotImplementedError):
+ self.skipTest("this account cannot create symbolic links")
+ self.assertEqual(models.plan_import(str(link))["issues"], [])
+
+ def test_a_link_to_a_file_that_is_gone_says_so(self):
+ snap = self.base / "s"
+ snap.mkdir()
+ try:
+ os.symlink(self.base / "gone", snap / Q2[0])
+ except (OSError, NotImplementedError):
+ self.skipTest("this account cannot create symbolic links")
+ with self.assertRaises(ProfileError) as ctx:
+ gguf_preflight.real_model_file(snap / Q2[0])
+ self.assertIn("link to a file that is not there", str(ctx.exception))
+
+ def test_a_missing_file_is_missing_not_a_link(self):
+ with self.assertRaises(ProfileError) as ctx:
+ gguf_preflight.real_model_file(self.base / "nope.gguf")
+ self.assertIn("is missing", str(ctx.exception))
+
+ def test_run_configs_keep_the_no_link_rule(self):
+ cfg = self.base / "real.json"
+ cfg.write_text("{}")
+ link = self.base / "strata-x.json"
+ try:
+ os.symlink(cfg, link)
+ except (OSError, NotImplementedError):
+ self.skipTest("this account cannot create symbolic links")
+ with self.assertRaises(ProfileError) as ctx:
+ models._read(link) # noqa: SLF001
+ self.assertIn("symlink", str(ctx.exception))
+
+
+class Folders(Base):
+ def test_many_other_gguf_files_in_the_folder_do_not_refuse(self):
+ folder = self.gsq(self.base / "m", Q2, "Q2_0")
+ for i in range(140):
+ (folder / f"other-{i:03d}.gguf").write_bytes(b"GGUF")
+ plan = models.plan_import(str(folder))
+ self.assertEqual(plan["candidate_selection"]["model"], "Q2_0")
+ self.assertEqual(plan["file_count"], 2)
+
+ def test_several_sizes_in_one_folder_name_them_and_ask_for_one_file(self):
+ folder = self.gsq(self.base / "many", Q2, "Q2_0")
+ self.gsq(folder, IQ3XXS, "IQ3_XXS")
+ plan = models.plan_import(str(folder))
+ self.assertEqual(plan["issues"], ["multiple_model_groups"])
+ self.assertIsNone(plan["candidate_selection"])
+ self.assertEqual(sorted(h["model"] for h in plan["folder_holds"]), ["IQ3_XXS", "Q2_0"])
+ self.assertTrue(any("holds 2 models" in m and "type the path of its .gguf file" in m for m in plan["messages"]))
+
+ def test_one_known_size_among_other_files_is_used_and_the_rest_is_named(self):
+ folder = self.gsq(self.base / "mix", Q2, "Q2_0")
+ (folder / "some-other-model-Q4_K_M.gguf").write_bytes(gguf_bytes(["IQ3_S"]))
+ plan = models.plan_import(str(folder))
+ self.assertEqual(plan["issues"], [])
+ self.assertEqual(plan["candidate_selection"]["model"], "Q2_0")
+ self.assertEqual(plan["file_count"], 2)
+ self.assertTrue(any("some-other-model-Q4_K_M.gguf" in m and "leaves the others alone" in m for m in plan["messages"]))
+
+ def test_a_shard_file_picks_its_set_out_of_a_folder_of_several(self):
+ folder = self.gsq(self.base / "many", Q2, "Q2_0")
+ self.gsq(folder, IQ3XXS, "IQ3_XXS")
+ plan = models.plan_import(str(folder / IQ3XXS[1]))
+ self.assertEqual(plan["issues"], [])
+ self.assertEqual(plan["candidate_selection"]["model"], "IQ3_XXS")
+ self.assertEqual(plan["model_dir"], str(folder))
+
+ def test_a_folder_above_the_model_folder_is_searched(self):
+ data = self.base / "Strata-data"
+ self.gsq(data / "models" / "q2_0", Q2, "Q2_0")
+ (data / "packs").mkdir()
+ for start in (data, data / "models"):
+ plan = models.plan_import(str(start))
+ self.assertEqual(plan["issues"], [], start)
+ self.assertEqual(plan["model_dir"], str(data / "models" / "q2_0"))
+ self.assertTrue(any("The model files are in" in m for m in plan["messages"]))
+
+ def test_a_whole_repository_with_one_folder_per_size_asks_which(self):
+ repo = self.base / "repo"
+ self.gsq(repo / "Q2_0", Q2, "Q2_0")
+ self.gsq(repo / "IQ3_XXS", IQ3XXS, "IQ3_XXS")
+ plan = models.plan_import(str(repo))
+ self.assertIn("multiple_model_groups", plan["issues"])
+ self.assertEqual(sorted((Path(h["folder"]).name, h["model"]) for h in plan["folder_holds"]),
+ [("IQ3_XXS", "IQ3_XXS"), ("Q2_0", "Q2_0")])
+ self.assertTrue(plan["file_set_status"] == "invalid_or_incomplete")
+
+ def test_one_known_folder_next_to_unrelated_ones_is_used(self):
+ top = self.base / "all"
+ self.gsq(top / "models" / "q2_0", Q2, "Q2_0")
+ (top / "stuff").mkdir()
+ (top / "stuff" / "notes.txt").write_text("x")
+ plan = models.plan_import(str(top))
+ self.assertEqual(plan["candidate_selection"]["model"], "Q2_0")
+
+ def test_a_folder_with_no_gguf_anywhere_says_so(self):
+ (self.base / "empty" / "a" / "b").mkdir(parents=True)
+ with self.assertRaises(ProfileError) as ctx:
+ models.plan_import(str(self.base / "empty"))
+ self.assertIn("no GGUF files found", str(ctx.exception))
+
+ def test_a_folder_name_with_spaces_and_a_second_drive_style_path(self):
+ folder = self.gsq(self.base / "my models" / "Qwen 3.8 files", Q2, "Q2_0")
+ self.assertEqual(models.plan_import(str(folder))["issues"], [])
+
+ def test_a_missing_second_shard_is_one_plain_issue(self):
+ folder = self.put(self.base / "half", Q2[:1], ["Q2_0"])
+ plan = models.plan_import(str(folder))
+ self.assertEqual(plan["issues"], ["incomplete_or_invalid_shard_set"])
+
+
+class Table(unittest.TestCase):
+ def test_every_size_setup_installs_is_in_the_table(self):
+ """Setup can install it from --gguf-dir, so the checker in front of it must know it too (0.2.0 knew 7 of 10)."""
+ import importlib.util
+ spec = importlib.util.spec_from_file_location("strata_setup_for_test", models.ROOT / "setup.py")
+ setup = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(setup)
+ table = json.loads((models.ROOT / "data" / "gguf_fingerprints.json").read_text(encoding="utf-8"))
+ missing = []
+ for family, fam in setup.FAMILIES.items():
+ if fam.get("ready"):
+ continue
+ for model, row in setup.MODELS.items():
+ if family not in row.get("families", ("qwen", "swift")):
+ continue
+ names = {setup.model_file(fam, model, i) for i in range(1, setup.model_shards(fam, model) + 1)}
+ key = f"{family}/{model}"
+ have = {Path(n).name for n in (table.get(key) or {}).get("files", [])}
+ if key not in models.SUPPORTED_SELECTIONS or have != names:
+ missing.append(key)
+ self.assertEqual(missing, [])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tools/strata_inspect.py b/tools/strata_inspect.py
index 5d094d80c..425954a1a 100644
--- a/tools/strata_inspect.py
+++ b/tools/strata_inspect.py
@@ -40,9 +40,13 @@ KNOWN = [
("swift", "Q2_0", "ukisai/Swift-1.5-Qwen3.8-Flash-Next-GSQ-RCO-GGUF", "Swift-Qwen3.8-Flash-Next-GSQ-RCO-Q2_0"),
("swift", "IQ2_XS", "ukisai/Swift-1.5-Qwen3.8-Flash-Next-GSQ-RCO-GGUF", "Swift-Qwen3.8-Flash-Next-GSQ-RCO-IQ2_XS"),
("swift", "IQ3_XXS", "ukisai/Swift-1.5-Qwen3.8-Flash-Next-GSQ-RCO-GGUF", "Swift-Qwen3.8-Flash-Next-GSQ-RCO-IQ3_XXS"),
+ ("swift", "IQ3_S", "ukisai/Swift-1.5-Qwen3.8-Flash-Next-GSQ-RCO-GGUF", "Swift-Qwen3.8-Flash-Next-GSQ-RCO-IQ3_S"),
("coder", "IQ1_M", "ISTA-DASLab/Qwen3.8-Flash-Next-GSQ-RCO-Coder-GGUF", "IQ1_M/"),
("unsloth", "UD-IQ4_XS", "unsloth/Qwen3.8-Flash-Next-GGUF", "UD-IQ4_XS/"),
("unsloth", "UD-Q4_K_XL", "unsloth/Qwen3.8-Flash-Next-GGUF", "UD-Q4_K_XL/"),
+ ("unsloth", "UD-Q5_K_XL", "unsloth/Qwen3.8-Flash-Next-GGUF", "UD-Q5_K_XL/"),
+ ("unsloth", "UD-Q6_K_XL", "unsloth/Qwen3.8-Flash-Next-GGUF", "UD-Q6_K_XL/"),
+ ("unsloth", "Q8_0", "unsloth/Qwen3.8-Flash-Next-GGUF", "Q8_0/"),
]