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

Pin SHA-256 and size for every model file setup downloads; stop when the pinned version is gone

Niko1221e193161de219
diff --git a/docs/SAFETY.md b/docs/SAFETY.md
index 5ccaf9a79..1f65082de 100644
--- a/docs/SAFETY.md
+++ b/docs/SAFETY.md
@@ -12,8 +12,11 @@ you trust can check it. Where Strata does less than you might hope, the page say
- **There is no telemetry.** Strata sends no usage data, no crash reports and no analytics, and has no account to sign in to.
- **Starting and running a model never downloads anything.** Downloads and updates are separate steps that you start.
- **The server listens on your PC only.** Reaching it from another device needs an API key.
-- **Downloads are checked.** Updates come from a signed feed. Some model files are checked against a fixed SHA-256, others
- against a fixed version of their repository and for completeness (the details are [below](#how-downloads-are-checked)).
+- **Once a model is downloaded, Strata runs without internet.** Starting, loading, serving and chatting need no
+ connection. Only things you ask for use it: the agent's web search and web pages, an outside model service, the tunnel,
+ and installs and updates (a first model install also fetches llama.cpp's preparation scripts).
+- **Downloads are checked.** Updates come from a signed feed. Every model file has a fixed SHA-256 and size, and an install
+ stops if the pinned version of a file is gone (the details are [below](#how-downloads-are-checked)).
- **The coding agent asks before it changes anything** in its default mode. It does not ask before it searches the web.
- **The code is open.** Anyone can read it, and security problems go to [SECURITY.md](../SECURITY.md).
@@ -107,18 +110,24 @@ Updates never replace your models or saved tuning. The full description is in [p
(`apps/desktop/src-tauri/tauri.conf.json`). The updater refuses an installer whose signature does not match. The Terminal
checks the same signature when you run `strata update --app`.
-**Model files.** There are two levels, and they are not the same.
-
-- *A fixed SHA-256 and size per file*: the Unsloth sizes, the Gyro files, Qwen3.6, the NVFP4 packs, the image model files
- and the speed-up layer (MTP, tensor by tensor). A file that does not match is deleted and the install stops
- (`setup.py`, `verify_sha256`; `tools/mtp_fetch.py`; `apps/host/server/image-models.mjs`).
-- *A fixed repository version, with no SHA-256*: the main Qwen3.8-Flash-Next files (Q2_0, IQ2_XS, IQ3_XXS, IQ3_S), Swift 1.5 and
- the Coder, and the picture reader. Strata downloads them from a fixed commit of the repository and checks that each file is
- complete, but it does not compare a hash. If that commit has disappeared from Hugging Face, setup says so and takes the
- repository's current file instead (`setup.py`, `HF_REVISIONS` and `download`).
-- Files from ModelScope are checked against the SHA-256 that ModelScope itself publishes. Setup warns when it publishes none.
-- The app also has a short model list of its own (`apps/host/server/real-model-catalog.mjs`). The app downloads those files
- from the repository's current `main` branch and checks that they have about the expected size.
+**Model files.** Every model file that `setup.py` downloads has a fixed SHA-256 and size, written in the code, so the check
+needs no network: the main Qwen3.8-Flash-Next files (Q2_0, IQ2_XS, IQ3_XXS, IQ3_S), Swift 1.5, the Coder, the Unsloth sizes,
+the Gyro files, Qwen3.6, the NVFP4 packs, the picture reader, the image model files and the speed-up layer (MTP, tensor by
+tensor). A file that does not match is deleted and the install stops. A file whose size on the server is not the pinned
+size stops it before the download starts.
+
+- If the pinned version of a file is gone from Hugging Face, the install stops and says to update Strata. It does not take
+ the repository's current file instead. A tester can set `STRATA_ALLOW_UNPINNED=1` to take the current file anyway, without
+ the check. It is off by default, and setup says so when it is set.
+- Starting a model does not check its files, and running setup again for a model you have does not download or hash them
+ again. A file installed before these hashes existed is kept as it is.
+- Files from ModelScope are checked against the same fixed SHA-256. ModelScope serves a repository's current files, so a file
+ it has changed fails the check. A file without a pin is checked against the hash ModelScope publishes, and setup warns
+ when it publishes none.
+- The app installs these models by running the same setup, so it has the same checks. The app's host also keeps a short
+ starter list of its own (`apps/host/server/real-model-catalog.mjs`). Its download path takes files from the repository's
+ current `main` branch and checks only that they have about the expected size. The 0.2.0 app screens do not use it.
+ (`setup.py`: `REPO_PINS`, `download`, `verify_sha256`; `tools/mtp_fetch.py`; `apps/host/server/image-models.mjs`.)
**Engine in the source route.** `setup.py` checks the engine zip against the SHA-256 that GitHub's API publishes for that
release file. If GitHub cannot say (offline, rate limit), setup warns and installs anyway. `STRATA_SKIP_SHA256=1` switches the
diff --git a/setup.py b/setup.py
index f54d89072..9c69f5757 100644
--- a/setup.py
+++ b/setup.py
@@ -78,10 +78,11 @@ def home() -> Path:
WIN = os.name == "nt"
# #214: every Hugging Face file comes from a fixed commit of its repository (the `sha` of
# https://huggingface.co/api/models/<repo> when this was pinned), so a checkout installs the same files on any
-# day. A revision the repository no longer has falls back to its current files, with a message (download()).
+# day. Every file has a fixed size and SHA-256 too (REPO_PINS); a revision the repository no longer has stops the
+# download (download()), unless a tester sets STRATA_ALLOW_UNPINNED=1.
HF_REVISIONS = {
"ISTA-DASLab/Qwen3.8-Flash-Next-GSQ-RCO-GGUF": "ed59f92082b1e93c0e96d60a8b11aab089b52f09", # 2026-09-29
- "ukisai/Swift-1.5-Qwen3.8-Flash-Next-GSQ-RCO-GGUF": "b22d729eae29b5796f76fb70f91aef549b9fc52c", # 2026-09-24
+ "ukisai/Swift-1.5-Qwen3.8-Flash-Next-GSQ-RCO-GGUF": "99bb8f7f95c7aa7b24a36a7786a4f657b30f5d3d", # 2026-10-07 (adds IQ3_S)
"ISTA-DASLab/Qwen3.8-Flash-Next-GSQ-RCO-Coder-GGUF": "5348543e0147355ac9cbcb031184a3546350988e", # 2026-09-29
"unsloth/Qwen3.8-Flash-Next-GGUF": "38bb39ee97821de2c9009abb7e93950eec396e66", # 2026-09-30
"unsloth/Qwen3.6-35B-A3B-MTP-GGUF": "5bc3e238d916f48a861bac2f8a1990a0e9b7e98d", # 2026-10-12
@@ -108,6 +109,28 @@ def hf_unpinned(url: str) -> str:
return re.sub(r"^(https?://[^/]+/.+?/resolve/)[0-9a-f]{40}/", r"\1main/", url, count=1)
+_unpinned_said = []
+
+
+def allow_unpinned() -> bool:
+ """STRATA_ALLOW_UNPINNED=1: a tester's opt-out. A file whose pinned version is gone from Hugging Face is then taken
+ from the repository's current files, without the SHA-256 check (nothing pins them). Off by default, announced when set."""
+ on = (os.environ.get("STRATA_ALLOW_UNPINNED") or "").strip() == "1"
+ if on and not _unpinned_said:
+ _unpinned_said.append(1)
+ warn("STRATA_ALLOW_UNPINNED=1: a model file whose pinned version is gone from Hugging Face is taken from its "
+ "current files instead, and is NOT checked against a SHA-256. Unset it to get the checked files only")
+ return on
+
+
+def file_pin(url: str):
+ """(bytes, sha256) pinned for the Hugging Face file `url` names (REPO_PINS), else None."""
+ m = HF_FILE.match(url)
+ if m is None:
+ return None
+ return REPO_PINS.get(m.group("repo"), {}).get(m.group("path").rsplit("/", 1)[-1])
+
+
# ModelScope (www.modelscope.cn) hosts every repository above under the same name, with the same file paths and
# sizes, and is reachable from mainland China where huggingface.co often is not. It serves a repository's current
# files (no pinned revision), so a file from it is checked against the SHA-256 ModelScope publishes for it, and the
@@ -314,6 +337,59 @@ GYRO_FILES = {
(91965774272, "7aa36d15131d255179ab6c87fa9c9f81a0b541fc9e81e959d4c3e29eb20feb5f"),
}
+# ISTA-DASLab's Qwen3.8-Flash-Next shards (Q2_0, IQ2_XS, IQ3_XXS, IQ3_S) and the picture reader at the revision pinned in HF_REVISIONS: name -> (bytes, sha256),
+# the Hub's LFS pointers (tools/hf_pin_fetch.py). The n-gram table (shard 2) is the same file for all four sizes.
+ISTA_FILES = {
+ "Qwen3.8-Flash-Next-GSQ-RCO-IQ2_XS-00001-of-00002.gguf":
+ (39225954592, "92cee27ae5bbadcd732416a0f7a7f0acc092399dbbe8f5a5efa707c2ec0a49d7"),
+ "Qwen3.8-Flash-Next-GSQ-RCO-IQ2_XS-00002-of-00002.gguf":
+ (28800138432, "316b46f3a2dbd68c900f43136ab9449f9dcc3725dfd8c794847c204bc161e113"),
+ "Qwen3.8-Flash-Next-GSQ-RCO-IQ3_S-00001-of-00002.gguf":
+ (54817524224, "4c1eb2ceb4915e1192f4f386021897bde56a97f40a0bb78bb86465e0f7d2aca3"),
+ "Qwen3.8-Flash-Next-GSQ-RCO-IQ3_S-00002-of-00002.gguf":
+ (28800138432, "316b46f3a2dbd68c900f43136ab9449f9dcc3725dfd8c794847c204bc161e113"),
+ "Qwen3.8-Flash-Next-GSQ-RCO-IQ3_XXS-00001-of-00002.gguf":
+ (47039860096, "219ea929900dfa9ef091f3aa473fdba6874b65fcb36526d7d851ac9e95856d15"),
+ "Qwen3.8-Flash-Next-GSQ-RCO-IQ3_XXS-00002-of-00002.gguf":
+ (28800138432, "316b46f3a2dbd68c900f43136ab9449f9dcc3725dfd8c794847c204bc161e113"),
+ "Qwen3.8-Flash-Next-GSQ-RCO-Q2_0-00001-of-00002.gguf":
+ (37623740192, "69820c02ec7d0b45ef2ebb19d6620299db749fe2aded7f39f93c6b88b199b720"),
+ "Qwen3.8-Flash-Next-GSQ-RCO-Q2_0-00002-of-00002.gguf":
+ (28800138432, "316b46f3a2dbd68c900f43136ab9449f9dcc3725dfd8c794847c204bc161e113"),
+ "mmproj-Qwen3.8-Flash-Next-BF16.gguf":
+ (907543008, "b1a82259702816a5330d7bd7607cd9676b11780e79ff7348c21103ff3ce49bd0"),
+}
+# Swift 1.5's shards (Q2_0, IQ2_XS, IQ3_XXS, IQ3_S) and its picture reader, same source and form.
+SWIFT_FILES = {
+ "Swift-Qwen3.8-Flash-Next-GSQ-RCO-IQ2_XS-00001-of-00002.gguf":
+ (39788473344, "ca3b302d3d1eb6eddce3ea4acc79854e6cc5fdc0583e374a6a8b6bb67327743b"),
+ "Swift-Qwen3.8-Flash-Next-GSQ-RCO-IQ2_XS-00002-of-00002.gguf":
+ (28363693824, "e4996a6de18fd49c58d9a0040fcfd73787db6407c51973f29884bee7b14c9dbb"),
+ "Swift-Qwen3.8-Flash-Next-GSQ-RCO-IQ3_S-00001-of-00002.gguf":
+ (44900816736, "46cb3996cd1a17fe8bc5ae1f9bb16869480de5a03f17f868d6047a20a46edd3b"),
+ "Swift-Qwen3.8-Flash-Next-GSQ-RCO-IQ3_S-00002-of-00002.gguf":
+ (38842920384, "70ce6fb48a94fe34bd7e9a53a526be68066c64b5a5077cdc82fb31350b66b608"),
+ "Swift-Qwen3.8-Flash-Next-GSQ-RCO-IQ3_XXS-00001-of-00002.gguf":
+ (39785790560, "3bddaa667c750f63baca766df9433e1afd35a139f401c5ca5e7ff560ceff3d23"),
+ "Swift-Qwen3.8-Flash-Next-GSQ-RCO-IQ3_XXS-00002-of-00002.gguf":
+ (36180282560, "b0b15f782af71eb471909d2f3313b2927c324962f86c084325c247cd411a0160"),
+ "Swift-Qwen3.8-Flash-Next-GSQ-RCO-Q2_0-00001-of-00002.gguf":
+ (39799117984, "79e2a3873f1b05df835a1a191b20f2e74b9e12df949cd89861d17d98b6ef9678"),
+ "Swift-Qwen3.8-Flash-Next-GSQ-RCO-Q2_0-00002-of-00002.gguf":
+ (26750834816, "ef3bb04fb4e14f04624abd8acf25faf1603594a034050b048df85ec152ad5ae0"),
+ "mmproj-Swift-Qwen3.8-Flash-Next-BF16.gguf":
+ (907543520, "cd1140f4abba943ce8d9fa92fed8407e389954d26907efde7b72153c75bd8a60"),
+}
+# The Coder's IQ1_M shards and its picture reader (the original's file), same source and form.
+CODER_FILES = {
+ "Qwen3.8-Flash-Next-GSQ-RCO-IQ1_M-00001-of-00002.gguf":
+ (29608446496, "e11083ba855e7666b48ea3f2db6a9c3a20c18751a012cc24f948de91b7087fad"),
+ "Qwen3.8-Flash-Next-GSQ-RCO-IQ1_M-00002-of-00002.gguf":
+ (28800138432, "316b46f3a2dbd68c900f43136ab9449f9dcc3725dfd8c794847c204bc161e113"),
+ "mmproj-Qwen3.8-Flash-Next-BF16.gguf":
+ (907543008, "b1a82259702816a5330d7bd7607cd9676b11780e79ff7348c21103ff3ce49bd0"),
+}
+
MODELS = {
# the original model only for now: Swift 1.5's Q2_0 files split one layer's experts across the two shards, which
# the pack tool (tools/iq_pack.py) cannot prepare yet (#171)
@@ -565,6 +641,18 @@ OWN_PATH_FAMILIES = {
"vision": True, "state_gb": 0.07}
}
PREVIEW_FAMILIES = OWN_PATH_FAMILIES # the earlier name (tools and tests that import it)
+
+# Every model file Strata downloads has a fixed size and SHA-256: (repository, file name) -> (bytes, sha256). download()
+# checks the file against it as soon as it is whole (a wrong file is deleted and setup stops), and stops before the
+# download when the server's size is not the pinned one. The files are fetched from the commits in HF_REVISIONS.
+REPO_PINS = {
+ "ISTA-DASLab/Qwen3.8-Flash-Next-GSQ-RCO-GGUF": ISTA_FILES,
+ "ukisai/Swift-1.5-Qwen3.8-Flash-Next-GSQ-RCO-GGUF": SWIFT_FILES,
+ "ISTA-DASLab/Qwen3.8-Flash-Next-GSQ-RCO-Coder-GGUF": CODER_FILES,
+ "unsloth/Qwen3.8-Flash-Next-GGUF": {**UNSLOTH_SHARDS, **UNSLOTH_IQ4_XS_SHARDS, **UNSLOTH_BIG_SHARDS},
+ "unsloth/Qwen3.6-35B-A3B-MTP-GGUF": QWEN36_FILES,
+ "agentionai/Qwen3.8-Flash-Next-Gyro-GGUF": GYRO_FILES,
+}
# EXPERIMENTAL, off by default (setup asks): a control vector shipped with the repository, see its README
ESP_VECTOR = ROOT / "data" / "experimental-speed-projection" / "Qwen3.8-Flash-Next-experimental-speed-projection.gguf"
# the image encoder on the GPU (~1.2 GB at 1024 image tokens) warms up before the engine starts, so the engine
@@ -1841,16 +1929,22 @@ def download(url, dst: Path, what=None):
ms = None
part = dst.with_name(dst.name + ".part")
total = 0
+ # the file's pinned size and SHA-256, when it has them (ModelScope's copy is checked against the same pin)
+ pin = REPO_PINS.get(ms[0], {}).get(ms[1].rsplit("/", 1)[-1]) if ms is not None else file_pin(url)
for attempt in range(5):
try:
req = urllib.request.Request(url, method="HEAD", headers={"User-Agent": "strata-setup"})
total = int(_urlopen(req, timeout=60).headers.get("Content-Length", 0))
break
except urllib.error.HTTPError as e:
- if e.code == 404 and hf_unpinned(url) != url: # #214: the pinned revision is gone from the repository
+ if e.code == 404 and hf_unpinned(url) != url: # the pinned revision is gone from the repository
+ if not allow_unpinned():
+ fail(f"the pinned version of {what or dst.name} is no longer on Hugging Face",
+ "update Strata: a newer version pins the files that are there now")
warn(f"{what or dst.name}: not at the pinned revision any more; downloading the repository's "
- "current file")
+ "current file (not checked against a SHA-256)")
url = hf_unpinned(url)
+ pin = None
continue
if attempt == 4:
fail(f"cannot reach {url.split('/')[2]} ({e})",
@@ -1861,6 +1955,9 @@ def download(url, dst: Path, what=None):
fail(f"cannot reach {url.split('/')[2]} ({e})",
"check your internet connection and run it again" + source_hint(url))
time.sleep(5)
+ if pin and total and total != pin[0]: # not the pinned file: stop before the download, not after
+ fail(f"{what or dst.name} is {total:,} bytes on {url.split('/')[2]}, not the pinned {pin[0]:,}",
+ "update Strata (the file there has changed since this version pinned it)")
if dst.exists() and total and dst.stat().st_size == total: # finished by an older setup (no mark yet)
mark(dst)
ok(f"{what or dst.name} already downloaded")
@@ -1900,7 +1997,9 @@ def download(url, dst: Path, what=None):
"check your internet connection and run it again (the download resumes where it stopped)")
part.replace(dst)
meta = ms_meta(*ms) if ms is not None else None
- if meta is not None and meta[1]:
+ if pin:
+ verify_sha256(dst, *pin) # the fixed hash: a wrong file is deleted and setup stops
+ elif meta is not None and meta[1]:
verify_sha256(dst, meta[0], meta[1]) # ModelScope's published hash; kept in the finish mark
else:
if ms is not None:
diff --git a/tools/hf_pin_fetch.py b/tools/hf_pin_fetch.py
new file mode 100644
index 000000000..afe941dea
--- /dev/null
+++ b/tools/hf_pin_fetch.py
@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""Print the size and SHA-256 Hugging Face's API metadata gives for the files of a repository at a pinned commit.
+Nothing is downloaded: https://huggingface.co/api/models/<repo>/tree/<revision>?recursive=1 lists each LFS file with
+`lfs.oid` (the SHA-256) and `size`.
+
+ python tools/hf_pin_fetch.py ISTA-DASLab/Qwen3.8-Flash-Next-GSQ-RCO-GGUF ed59f92082b1e93c0e96d60a8b11aab089b52f09
+ python tools/hf_pin_fetch.py --json <repo> <revision> # {path: [size, sha256]} as JSON
+ python tools/hf_pin_fetch.py --setup # every repository in setup.py's HF_REVISIONS, as JSON
+"""
+from __future__ import annotations
+
+import json
+import sys
+import urllib.request
+from pathlib import Path
+
+
+def tree(repo: str, revision: str) -> dict:
+ """{path: (size, sha256)} of the repository's LFS files at `revision` (the API pages its answer with Link headers)."""
+ out = {}
+ url = f"https://huggingface.co/api/models/{repo}/tree/{revision}?recursive=1&expand=0"
+ while url:
+ with urllib.request.urlopen(urllib.request.Request(url, headers={"User-Agent": "strata-pin"}), timeout=60) as r:
+ for e in json.load(r):
+ if e.get("type") == "file" and e.get("lfs"):
+ out[e["path"]] = (int(e["lfs"]["size"]), e["lfs"]["oid"])
+ link = r.headers.get("Link", "")
+ url = next((p.split(";")[0].strip(" <>") for p in link.split(",") if 'rel="next"' in p), None)
+ return out
+
+
+def main(argv: list) -> int:
+ if argv and argv[0] == "--setup":
+ sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+ import setup
+ print(json.dumps({r: {p: list(v) for p, v in tree(r, rev).items()} for r, rev in setup.HF_REVISIONS.items()}, indent=1))
+ return 0
+ as_json = bool(argv) and argv[0] == "--json"
+ repo, revision = argv[1:3] if as_json else argv[:2]
+ t = tree(repo, revision)
+ if as_json:
+ print(json.dumps({p: list(v) for p, v in t.items()}, indent=1))
+ else:
+ for p, (size, sha) in sorted(t.items()):
+ print(f"{size:>14,} {sha} {p}")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv[1:]))
diff --git a/tools/mtp_fetch.py b/tools/mtp_fetch.py
index ea74b1c86..f31c221a6 100644
--- a/tools/mtp_fetch.py
+++ b/tools/mtp_fetch.py
@@ -28,7 +28,7 @@ import urllib.request
# #214: a fixed commit of the checkpoint (its `sha` from https://huggingface.co/api/models/Qwen/Qwen3.8-Flash-Next
# on 2026-09-30), so every install reads the same tensors; STRATA_MTP_REVISION overrides it (e.g. main). When the
-# repository no longer has it, the current files are read instead, with a message (resolve_repo).
+# repository no longer has it, reading stops (resolve_repo) unless STRATA_ALLOW_UNPINNED=1.
PINNED_REVISION = "de4b8e4d43b917e7706784d8bb445c9af86a3540"
REVISION = os.environ.get("STRATA_MTP_REVISION") or PINNED_REVISION
# #495: HF_ENDPOINT (a mirror, e.g. https://hf-mirror.com) serves the same revision; the SHA256 checks below still apply
@@ -157,16 +157,19 @@ def sha256_of(path):
def resolve_repo():
- """REPO, or the repository's current files when the pinned revision is gone from it (a 404 on its index)."""
+ """REPO. When the pinned revision is gone from the repository (a 404 on its index) it stops, unless
+ STRATA_ALLOW_UNPINNED=1: then the current files are read (their tensors are still checked against the pinned SHA256)."""
global REPO
try:
req = urllib.request.Request(REPO + "model.safetensors.index.json", method="HEAD",
headers={"User-Agent": "strata-mtp-fetch"})
urllib.request.urlopen(req, timeout=120).close()
except urllib.error.HTTPError as e:
- if e.code == 404 and "/resolve/main/" not in REPO:
- print("the checkpoint's pinned revision %s is gone: reading its current files (main)" % REVISION,
- file=sys.stderr)
+ if e.code == 404 and "/resolve/%s/" % REVISION in REPO:
+ if (os.environ.get("STRATA_ALLOW_UNPINNED") or "").strip() != "1":
+ sys.exit("the pinned version of the checkpoint (%s) is no longer on Hugging Face: update Strata" % REVISION)
+ print("STRATA_ALLOW_UNPINNED=1: the checkpoint's pinned revision %s is gone: reading its current files "
+ "(main); every tensor is still checked against the pinned SHA256" % REVISION, file=sys.stderr)
REPO = REPO.replace("/resolve/%s/" % REVISION, "/resolve/main/")
except OSError:
pass # no answer: get() retries and reports it
diff --git a/tools/test_setup_model_pins.py b/tools/test_setup_model_pins.py
new file mode 100644
index 000000000..1b5319592
--- /dev/null
+++ b/tools/test_setup_model_pins.py
@@ -0,0 +1,258 @@
+"""Tests for the fixed SHA-256 and size of every model file setup downloads (REPO_PINS): every file a choice can
+download has one, a wrong file is deleted and setup stops, a pinned commit that answers 404 stops the download
+(STRATA_ALLOW_UNPINNED=1 is the tester's opt-out), and an installed model needs no network. Mocked network - nothing
+is downloaded.
+
+ python -m unittest tools.test_setup_model_pins
+"""
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import io
+import re
+import sys
+import tempfile
+import unittest
+import urllib.error
+from pathlib import Path
+from unittest import mock
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+sys.path.insert(0, str(ROOT / "tools"))
+import setup # noqa: E402
+
+REPO = "ISTA-DASLab/Qwen3.8-Flash-Next-GSQ-RCO-GGUF"
+HEX = re.compile(r"^[0-9a-f]{64}$")
+
+
+class Response(io.BytesIO):
+ def __init__(self, body=b"", status=200, length=None):
+ super().__init__(body)
+ self.status = status
+ self.headers = {"Content-Length": str(len(body) if length is None else length)}
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *exc):
+ self.close()
+
+
+def quiet(fn, *args, **kw):
+ out = io.StringIO()
+ with contextlib.redirect_stdout(out):
+ return fn(*args, **kw), out.getvalue()
+
+
+def pinned_url(name):
+ return setup.hf(REPO) + name
+
+
+def with_pin(name, data):
+ """REPO_PINS with one more file of the repository: `data`'s size and SHA-256."""
+ pins = dict(setup.REPO_PINS)
+ pins[REPO] = {**pins[REPO], name: (len(data), hashlib.sha256(data).hexdigest())}
+ return mock.patch.object(setup, "REPO_PINS", pins)
+
+
+class EveryFileIsPinned(unittest.TestCase):
+ def pinned(self, url):
+ pin = setup.file_pin(url)
+ self.assertIsNotNone(pin, url)
+ self.assertGreater(pin[0], 0)
+ self.assertRegex(pin[1], HEX)
+
+ def test_every_shard_of_every_choice(self):
+ for fam_name, fam in {**setup.FAMILIES, **setup.OWN_PATH_FAMILIES}.items():
+ if fam.get("ready"): # ready-made packs: pinned file by file (ready_files)
+ continue
+ for model in (setup.MODELS if fam_name in setup.FAMILIES else fam["models"]):
+ if fam_name in setup.FAMILIES and fam_name not in setup.MODELS[model].get("families", ("qwen", "swift")):
+ continue
+ with self.subTest(family=fam_name, model=model):
+ if fam_name in setup.FAMILIES:
+ for i in range(1, setup.model_shards(fam, model) + 1):
+ self.pinned(fam["hf"].format(q=model) + setup.model_file(fam, model, i))
+ else:
+ self.pinned(fam["hf"] + fam["file"].format(q=model))
+
+ def test_the_picture_reader_of_every_family(self):
+ for name, fam in {**setup.FAMILIES, **setup.OWN_PATH_FAMILIES}.items():
+ with self.subTest(family=name):
+ self.pinned(fam["mmproj_hf"] + fam["mmproj"])
+
+ def test_the_nvfp4_packs_still_pin_their_files(self):
+ for model in setup.MODELS:
+ if setup.MODELS[model].get("repo"):
+ for f in setup.ready_files(model):
+ self.assertRegex(f[5], HEX)
+
+ def test_every_pin_is_well_formed_and_every_repository_is_pinned(self):
+ for repo, files in setup.REPO_PINS.items():
+ self.assertIn(repo, setup.HF_REVISIONS)
+ for name, (size, sha) in files.items():
+ with self.subTest(repo=repo, file=name):
+ self.assertIsInstance(size, int)
+ self.assertGreater(size, 1000)
+ self.assertRegex(sha, HEX)
+
+ def test_known_values(self):
+ # the Hub's LFS pointers; the picture reader is the same file the NVFP4 family already pinned
+ self.assertEqual(setup.file_pin(pinned_url("mmproj-Qwen3.8-Flash-Next-BF16.gguf")),
+ setup.FAMILIES["nvfp4"]["mmproj_sha256"])
+ self.assertEqual(setup.file_pin(pinned_url("Q2_0/Qwen3.8-Flash-Next-GSQ-RCO-Q2_0-00001-of-00002.gguf")),
+ (37623740192, "69820c02ec7d0b45ef2ebb19d6620299db749fe2aded7f39f93c6b88b199b720"))
+ # the n-gram table is one file for the four sizes and the Coder
+ shard2 = {setup.ISTA_FILES["Qwen3.8-Flash-Next-GSQ-RCO-%s-00002-of-00002.gguf" % q] for q in
+ ("Q2_0", "IQ2_XS", "IQ3_XXS", "IQ3_S")}
+ self.assertEqual(len(shard2), 1)
+ self.assertEqual(setup.CODER_FILES["Qwen3.8-Flash-Next-GSQ-RCO-IQ1_M-00002-of-00002.gguf"], shard2.pop())
+
+ def test_an_unknown_file_has_no_pin(self):
+ self.assertIsNone(setup.file_pin(pinned_url("nothing.gguf")))
+ self.assertIsNone(setup.file_pin("https://example.com/a/b/resolve/main/x.gguf"))
+
+
+class DownloadChecksThePin(unittest.TestCase):
+ def serve(self, body, length=None):
+ seen = []
+
+ def urlopen(req, timeout=None):
+ seen.append(req.get_method())
+ if req.get_method() == "HEAD":
+ return Response(b"", length=length)
+ return Response(body, status=200)
+
+ return seen, mock.patch.object(setup.urllib.request, "urlopen", urlopen)
+
+ def run_download(self, name, served, pinned, length=None):
+ seen, patch = self.serve(served, length if length is not None else len(served))
+ with tempfile.TemporaryDirectory() as d, with_pin(name, pinned), patch, \
+ mock.patch.dict(setup.os.environ, {"STRATA_SOURCE": "huggingface"}):
+ setup.os.environ.pop("STRATA_ALLOW_UNPINNED", None)
+ dst = Path(d) / name
+ try:
+ _, out = quiet(setup.download, pinned_url(name), dst)
+ code = None
+ except SystemExit as e:
+ code, out = e.code, ""
+ result = (code, dst.exists(), dst.with_name(dst.name + ".done").exists(),
+ dst.with_name(dst.name + ".part").exists(),
+ dst.with_name(dst.name + ".done").read_text() if dst.with_name(dst.name + ".done").exists() else "")
+ return seen, result
+
+ def test_the_right_file_is_kept_with_its_hash_in_the_mark(self):
+ data = b"the model" * 100
+ seen, (code, exists, marked, part, mark_text) = self.run_download("t.gguf", data, data)
+ self.assertIsNone(code)
+ self.assertTrue(exists and marked and not part)
+ self.assertIn("sha256 " + hashlib.sha256(data).hexdigest(), mark_text)
+
+ def test_a_wrong_file_is_deleted_and_setup_stops(self):
+ data = b"the model" * 100
+ wrong = b"THE MODEL" * 100 # the pinned size, another content
+ seen, (code, exists, marked, part, _) = self.run_download("t.gguf", wrong, data)
+ self.assertEqual(code, 1)
+ self.assertFalse(exists or marked or part)
+
+ def test_a_wrong_size_stops_before_the_download(self):
+ data = b"the model" * 100
+ seen, (code, exists, marked, part, _) = self.run_download("t.gguf", data + b"x", data)
+ self.assertEqual(code, 1)
+ self.assertEqual(seen, ["HEAD"]) # no GET: nothing of the wrong file was fetched
+ self.assertFalse(exists or marked or part)
+
+
+class NotFoundOnThePinnedCommit(unittest.TestCase):
+ def urlopen(self, seen):
+ def urlopen(req, timeout=None):
+ seen.append((req.get_method(), req.full_url))
+ if "/resolve/main/" not in req.full_url:
+ raise urllib.error.HTTPError(req.full_url, 404, "Not Found", {}, None)
+ return Response(b"current file")
+ return urlopen
+
+ def test_it_stops_with_a_plain_message(self):
+ seen = []
+ out = io.StringIO()
+ with tempfile.TemporaryDirectory() as d, mock.patch.object(setup.urllib.request, "urlopen", self.urlopen(seen)), \
+ mock.patch.dict(setup.os.environ, {"STRATA_SOURCE": "huggingface"}), contextlib.redirect_stdout(out):
+ setup.os.environ.pop("STRATA_ALLOW_UNPINNED", None)
+ dst = Path(d) / "t.gguf"
+ with self.assertRaises(SystemExit):
+ setup.download(pinned_url("Q2_0/Qwen3.8-Flash-Next-GSQ-RCO-Q2_0-00001-of-00002.gguf"), dst, "the model")
+ self.assertFalse(dst.exists())
+ self.assertIn("the pinned version of the model is no longer on Hugging Face", out.getvalue())
+ self.assertIn("update Strata", out.getvalue())
+ self.assertEqual(len(seen), 1) # no second try on main
+
+ def test_the_opt_out_takes_the_current_file_and_says_so(self):
+ seen = []
+ with tempfile.TemporaryDirectory() as d, mock.patch.object(setup.urllib.request, "urlopen", self.urlopen(seen)), \
+ mock.patch.dict(setup.os.environ, {"STRATA_SOURCE": "huggingface", "STRATA_ALLOW_UNPINNED": "1"}), \
+ mock.patch.object(setup, "_unpinned_said", []):
+ dst = Path(d) / "Qwen3.8-Flash-Next-GSQ-RCO-Q2_0-00001-of-00002.gguf"
+ _, out = quiet(setup.download, pinned_url("Q2_0/" + dst.name), dst)
+ self.assertEqual(dst.read_bytes(), b"current file") # not checked against the pin: it is not the pinned file
+ self.assertIn("STRATA_ALLOW_UNPINNED=1", out)
+
+ def test_the_opt_out_is_off_by_default(self):
+ with mock.patch.dict(setup.os.environ, {}, clear=False):
+ setup.os.environ.pop("STRATA_ALLOW_UNPINNED", None)
+ self.assertFalse(setup.allow_unpinned())
+ for value in ("", "0", "no"):
+ setup.os.environ["STRATA_ALLOW_UNPINNED"] = value
+ self.assertFalse(setup.allow_unpinned())
+
+
+class InstalledModelsNeedNoNetwork(unittest.TestCase):
+ """Once a model is downloaded, setup and the start do not contact Hugging Face (they run offline)."""
+
+ def test_an_installed_file_is_not_asked_for(self):
+ def urlopen(req, timeout=None):
+ raise AssertionError("network used for an installed file: " + req.full_url)
+
+ with tempfile.TemporaryDirectory() as d, mock.patch.object(setup.urllib.request, "urlopen", urlopen), \
+ mock.patch.dict(setup.os.environ, {"HF_ENDPOINT": "http://127.0.0.1:9", "STRATA_SOURCE": "auto"}):
+ dst = Path(d) / "Qwen3.8-Flash-Next-GSQ-RCO-Q2_0-00001-of-00002.gguf"
+ dst.write_bytes(b"installed by an earlier setup") # no hash in its mark (installed before the pins)
+ setup.mark(dst)
+ _, out = quiet(setup.download, pinned_url("Q2_0/" + dst.name), dst)
+ self.assertIn("already downloaded", out)
+ self.assertEqual(dst.read_bytes(), b"installed by an earlier setup") # kept, not hashed, not deleted
+
+ def test_a_dead_host_is_reported_for_a_download_only(self):
+ def urlopen(req, timeout=None):
+ raise urllib.error.URLError("no route to host")
+
+ with tempfile.TemporaryDirectory() as d, mock.patch.object(setup.urllib.request, "urlopen", urlopen), \
+ mock.patch.object(setup.time, "sleep", lambda s: None), \
+ mock.patch.dict(setup.os.environ, {"STRATA_SOURCE": "huggingface"}):
+ with self.assertRaises(SystemExit):
+ quiet(setup.download, pinned_url("Q2_0/x.gguf"), Path(d) / "x.gguf")
+
+ def test_the_runtime_has_no_model_host_in_it(self):
+ """strata launch, serve, the monitor and the API reach no model host: the names are in setup.py and the install
+ tools only (and strata_control.acquisition refuses a download under STRATA_NO_ACQUIRE=1)."""
+ hosts = re.compile(r"huggingface\.co|hf-mirror|HF_ENDPOINT|modelscope|hf_hub_download", re.I)
+ found = []
+ for folder in ("strata_cli", "serve", "strata_control"):
+ for p in (ROOT / folder).rglob("*.py"):
+ if "test" in p.name:
+ continue
+ text = p.read_text(encoding="utf-8", errors="replace")
+ if hosts.search(text):
+ found.append(str(p.relative_to(ROOT)))
+ self.assertEqual(found, [])
+
+ def test_a_download_is_refused_while_serving(self):
+ from strata_control import acquisition
+ with acquisition.forbidden():
+ with self.assertRaises(acquisition.AcquisitionRefused):
+ setup.download(pinned_url("Q2_0/x.gguf"), Path(tempfile.gettempdir()) / "strata-never.gguf")
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tools/test_setup_modelscope.py b/tools/test_setup_modelscope.py
index cf1cdf23c..50301d465 100644
--- a/tools/test_setup_modelscope.py
+++ b/tools/test_setup_modelscope.py
@@ -99,6 +99,11 @@ class Download(Base):
os.environ["MODELSCOPE_ENDPOINT"] = "http://127.0.0.1:%d" % self.server.server_address[1]
os.environ["STRATA_SOURCE"] = "modelscope"
self.dst = Path(self.tmp.name) / "out" / Path(PATH).name
+ # a file with no pin of its own (the hash ModelScope publishes is the check); the pinned case is below
+ pins = {**setup.REPO_PINS, REPO: {k: v for k, v in setup.REPO_PINS[REPO].items() if k != Path(PATH).name}}
+ patch = mock.patch.object(setup, "REPO_PINS", pins)
+ patch.start()
+ self.addCleanup(patch.stop)
def api(self, sha):
p = self.www / "api" / "v1" / "models" / REPO / "repo" / "files"
@@ -124,6 +129,19 @@ class Download(Base):
self.assertEqual(self.dst.read_bytes(), self.data)
self.assertTrue(self.dst.with_name(self.dst.name + ".done").exists())
+ def test_the_pin_decides_over_what_modelscope_publishes(self):
+ """A pinned file is checked against its fixed SHA-256 whatever the host says: ModelScope serves current files."""
+ sha = hashlib.sha256(self.data).hexdigest()
+ self.api(sha) # ModelScope vouches for its own copy ...
+ pins = {**setup.REPO_PINS, REPO: {**setup.REPO_PINS[REPO], Path(PATH).name: (len(self.data), "1" * 64)}}
+ with mock.patch.object(setup, "REPO_PINS", pins), mock.patch.object(setup, "say"), self.assertRaises(SystemExit): # ... but it is not the pinned file
+ setup.download(HF_URL, self.dst)
+ self.assertFalse(self.dst.exists())
+ pins[REPO][Path(PATH).name] = (len(self.data), sha)
+ with mock.patch.object(setup, "REPO_PINS", pins):
+ setup.download(HF_URL, self.dst)
+ self.assertIn("sha256 " + sha, self.dst.with_name(self.dst.name + ".done").read_text())
+
def test_falls_back_when_modelscope_is_silent(self):
calls = []
with mock.patch.object(setup, "reachable", return_value=False), \
diff --git a/tools/test_setup_pins.py b/tools/test_setup_pins.py
index cf82cbd26..49fee8129 100644
--- a/tools/test_setup_pins.py
+++ b/tools/test_setup_pins.py
@@ -1,5 +1,5 @@
"""Tests for setup.py's reproducible installs (#214): the engine of the checkout's own release first (the latest as
-the fallback), Hugging Face files at pinned revisions (the current files when a revision is gone), the pinned
+the fallback), Hugging Face files at pinned revisions (a gone revision stops the download), the pinned
requirements file, and an existing install left as it is. Mocked network - nothing is downloaded.
python -m unittest tools.test_setup_pins
@@ -94,7 +94,25 @@ class HuggingFacePins(unittest.TestCase):
"https://huggingface.co/ukisai/Swift-1.5-Qwen3.8-Flash-Next-GSQ-RCO-GGUF/resolve/main/x.gguf")
self.assertEqual(setup.hf_unpinned("https://example.com/a/b"), "https://example.com/a/b")
- def test_a_gone_revision_downloads_the_current_file(self):
+ def test_a_gone_revision_stops_the_download(self):
+ """The pinned commit answers 404: setup stops with a plain message and fetches no current file."""
+ seen = []
+
+ def urlopen(req, timeout=None):
+ seen.append((req.get_method(), req.full_url))
+ raise not_found(req.full_url)
+
+ with tempfile.TemporaryDirectory() as d, mock.patch.object(setup.urllib.request, "urlopen", urlopen), mock.patch.dict(setup.os.environ, {"STRATA_SOURCE": "huggingface"}):
+ setup.os.environ.pop("STRATA_ALLOW_UNPINNED", None)
+ dst = Path(d) / "m.gguf"
+ with self.assertRaises(SystemExit):
+ _, out = quiet(setup.download, setup.FAMILIES["qwen"]["mmproj_hf"] + "m.gguf", dst)
+ self.assertFalse(dst.exists())
+ self.assertEqual([m for m, _ in seen], ["HEAD"])
+ self.assertTrue(all("/resolve/main/" not in u for _, u in seen))
+
+ def test_the_opt_out_downloads_the_current_file(self):
+ """STRATA_ALLOW_UNPINNED=1 (a tester's choice): the repository's current file, announced, off by default."""
seen = []
def urlopen(req, timeout=None):
@@ -104,11 +122,11 @@ class HuggingFacePins(unittest.TestCase):
return Response(b"model bytes", status=200)
# the pinned Hugging Face path itself (setup's --source huggingface; auto may pick ModelScope)
- with tempfile.TemporaryDirectory() as d, mock.patch.object(setup.urllib.request, "urlopen", urlopen), \
- mock.patch.dict(setup.os.environ, {"STRATA_SOURCE": "huggingface"}):
+ with tempfile.TemporaryDirectory() as d, mock.patch.object(setup.urllib.request, "urlopen", urlopen), mock.patch.dict(setup.os.environ, {"STRATA_SOURCE": "huggingface", "STRATA_ALLOW_UNPINNED": "1"}), mock.patch.object(setup, "_unpinned_said", []):
dst = Path(d) / "m.gguf"
_, out = quiet(setup.download, setup.FAMILIES["qwen"]["mmproj_hf"] + "m.gguf", dst)
self.assertEqual(dst.read_bytes(), b"model bytes")
+ self.assertIn("STRATA_ALLOW_UNPINNED=1", out)
self.assertIn("not at the pinned revision any more", out)
self.assertEqual([m for m, _ in seen], ["HEAD", "HEAD", "GET"])
self.assertTrue(all("/resolve/main/" in u for _, u in seen[1:]))
@@ -133,7 +151,7 @@ class HuggingFacePins(unittest.TestCase):
self.assertTrue(setup.done(dst))
self.assertEqual(seen, [("HEAD", None)])
- def test_mtp_fetch_is_pinned_and_falls_back(self):
+ def test_mtp_fetch_is_pinned_and_stops_when_the_revision_is_gone(self):
import mtp_fetch
self.assertRegex(mtp_fetch.REPO, SHA)
self.assertIn(mtp_fetch.REVISION, mtp_fetch.REPO)
@@ -143,10 +161,14 @@ class HuggingFacePins(unittest.TestCase):
raise not_found(req.full_url)
try:
- with mock.patch.object(mtp_fetch.urllib.request, "urlopen", urlopen), \
- contextlib.redirect_stderr(io.StringIO()) as err:
+ with mock.patch.object(mtp_fetch.urllib.request, "urlopen", urlopen), mock.patch.dict(mtp_fetch.os.environ, {"STRATA_ALLOW_UNPINNED": ""}):
+ with self.assertRaises(SystemExit) as stop:
+ mtp_fetch.resolve_repo()
+ self.assertIn("no longer on Hugging Face", str(stop.exception))
+ self.assertEqual(mtp_fetch.REPO, pinned)
+ with mock.patch.object(mtp_fetch.urllib.request, "urlopen", urlopen), mock.patch.dict(mtp_fetch.os.environ, {"STRATA_ALLOW_UNPINNED": "1"}), contextlib.redirect_stderr(io.StringIO()) as err:
self.assertEqual(mtp_fetch.resolve_repo(), "https://huggingface.co/Qwen/Qwen3.8-Flash-Next/resolve/main/")
- self.assertIn("pinned revision", err.getvalue())
+ self.assertIn("STRATA_ALLOW_UNPINNED=1", err.getvalue())
finally:
mtp_fetch.REPO = pinned