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

Terminal and app checker: the folder holding the model is found above the picked one, links keep their model name, one plain wording for every refusal (file name + why)

Niko1221bf2926e05a8e
diff --git a/strata_cli/cli.py b/strata_cli/cli.py
index 62aa0f7a1..c15e00a6b 100644
--- a/strata_cli/cli.py
+++ b/strata_cli/cli.py
@@ -597,12 +597,9 @@ def _import_problem(plan: dict) -> str:
issues = [x for x in issues if x != "unrecognized_or_unsupported_model_variant"]
words = "; ".join(dict.fromkeys(plain_issue(x) for x in issues))
text = f"These files cannot be used as they are: {words}."
- holds = plan.get("folder_holds") or []
+ holds = next((m for m in plan.get("messages") or [] if "holds" in m), "")
if holds:
- known = [f"{h['family']} {h['model']} ({h['file']})" for h in holds if h.get("model")]
- other = [h["file"] for h in holds if not h.get("model")]
- text += " The folder holds " + str(len(holds)) + " models" + (": " + ", ".join(known + other) if known or other else "") + \
- ". Point at the .gguf file of the one you want."
+ text += " " + holds
return text
diff --git a/strata_cli/launch/runner.py b/strata_cli/launch/runner.py
index ef1565fde..4a3ebb066 100644
--- a/strata_cli/launch/runner.py
+++ b/strata_cli/launch/runner.py
@@ -621,7 +621,7 @@ class Runner:
def ensure_model(self) -> Path:
s, cat = self.s, self.catalog
- if s.model_path and not (s.family and s.model):
+ if s.model_path:
self.resolve_own_files()
self.resolved_vision()
if not (s.family and s.model):
@@ -732,20 +732,34 @@ class Runner:
return path
def resolve_own_files(self) -> None:
- """"Use model files I already have": the fingerprint table says which catalog model the files are."""
+ """"Use model files I already have": the fingerprint table says which catalog model the files are, and which folder holds them (the
+ person may have named the folder above it). When the person also named the model (--model), the files are never refused here: setup
+ takes the files of that model out of the folder by name, as it always did (0.1.45), and says what is wrong when it cannot."""
from strata_control import models
s = self.s
+ given = bool(s.family and s.model)
try:
- plan = models.plan_import(str(Path(s.model_path).expanduser().resolve()))
+ plan = models.plan_import(models.absolute(s.model_path))
except Exception as e: # noqa: BLE001
+ if given:
+ return
raise LaunchError(f"These model files cannot be used: {e}.", "Pick the folder with every shard of one model, or a .gguf file of it.", 5) from None
+ if given:
+ hold = [h for h in plan.get("folder_holds") or [] if (h.get("family"), h.get("model")) == (s.family, s.model)]
+ if len(hold) == 1 and hold[0].get("folder"):
+ s.model_path = hold[0]["folder"]
+ elif not plan.get("issues"):
+ s.model_path = models.import_target(s.model_path, plan)
+ return
sel = plan.get("candidate_selection") or {}
fam, model = sel.get("family"), sel.get("model")
if not (fam and model) or plan.get("issues"):
issues = "; ".join(plain_issue(str(x)) for x in (plan.get("issues") or [])[:3]) or "they are not a model Strata knows"
- raise LaunchError(f"These files cannot be used as they are ({issues}).",
+ more = " " + next((m for m in plan.get("messages") or [] if "holds" in m), "")
+ raise LaunchError(f"These files cannot be used as they are ({issues}).{more.rstrip()}",
"Choose the matching model in the list, or check that every shard is in the folder.", 5)
s.family, s.model = fam, model
+ s.model_path = models.import_target(s.model_path, plan)
self.emit("model", f"These files are {fam} {model}.", None)
# ---- 3. config and profile
@@ -955,30 +969,7 @@ class Runner:
return out
-ISSUE_WORDS = {
- "multiple_model_groups": "the folder holds more than one model",
- "incomplete_or_invalid_shard_set": "some shards are missing",
- "unrecognized_or_unsupported_model_variant": "this is not a model size Strata knows",
- "unsupported_or_missing_architecture": "this model type is not supported by the Strata engine (add it as a Custom model API with llama-server instead)",
- "unsupported_or_incomplete_tokenizer_metadata": "the file has no usable tokenizer",
- "missing_or_unexpected_expert_quantization": "its quantization is not one Strata knows",
-}
-
-
-def plain_issue(code: str) -> str:
- """One problem from the GGUF preview, in words (it may be `file.gguf: GGUF shard is not a nonempty regular file` and the like)."""
- if code in ISSUE_WORDS:
- return ISSUE_WORDS[code]
- low = code.lower()
- if "not a nonempty regular file" in low or "unreadable" in low:
- return "a file is empty, unreadable or not a regular file"
- if "does not begin with a gguf header" in low or "header version" in low:
- return "a file is not a GGUF model file"
- if "unsupported_architecture" in low:
- return "this model type is not supported by the Strata engine (add it as a Custom model API with llama-server instead)"
- if "symlink" in low:
- return "a file is a shortcut (symbolic link); point at the real file"
- return code.replace("_", " ")
+from strata_control.models import ISSUE_WORDS, plain_issue # noqa: E402,F401 (one wording for the app, the Terminal and `models import`)
def _read_json(path: Path) -> dict | None:
diff --git a/strata_cli/launch/screens.py b/strata_cli/launch/screens.py
index 5d7bf172e..617363ba1 100644
--- a/strata_cli/launch/screens.py
+++ b/strata_cli/launch/screens.py
@@ -495,14 +495,14 @@ class ModelScreen(Base):
from strata_cli.launch.runner import plain_issue
from strata_control import models
try:
- plan = models.plan_import(str(Path(path).expanduser().resolve()))
+ plan = models.plan_import(models.absolute(path))
except Exception as e: # noqa: BLE001
self.say(f"These files cannot be used: {e}. Pick the folder with every shard of one model, or a .gguf file of it.", True)
return
sel = plan.get("candidate_selection") or {}
if sel.get("family") and sel.get("model") and not plan.get("issues"):
s = self.ctx.settings
- s.model_path, s.family, s.model = str(Path(path).expanduser()), sel["family"], sel["model"]
+ s.model_path, s.family, s.model = models.import_target(path, plan), sel["family"], sel["model"]
self.ctx.picked_in_list = False
self.close_field("own")
gb = plan.get("total_bytes", 0) / 1e9
@@ -511,7 +511,9 @@ class ModelScreen(Base):
self.paint()
else:
why = "; ".join(plain_issue(str(x)) for x in (plan.get("issues") or [])[:3]) or "they are not a model Strata knows"
- self.say(f"These files cannot be used as they are ({why}). Check that every shard is in the folder, or pick a model from the list.", True)
+ holds = next((m for m in plan.get("messages") or [] if "holds" in m), "")
+ self.say(f"These files cannot be used as they are ({why}). " + (holds + " " if holds else "") +
+ "Check that every shard is in the folder, or pick a model from the list.", True)
def action_back(self) -> None:
if self.input_open():
diff --git a/strata_control/models.py b/strata_control/models.py
index f499b1c3c..74914ed28 100644
--- a/strata_control/models.py
+++ b/strata_control/models.py
@@ -294,6 +294,51 @@ def _already_set_up(shards: list[Path], candidate: dict | None) -> dict | None:
return {"config": str(cfg) if cfg else None, **{k: (str(v) if v else None) for k, v in beside.items()}}
+ISSUE_WORDS = {
+ "multiple_model_groups": "the folder holds more than one model",
+ "incomplete_or_invalid_shard_set": "some parts of the model are missing",
+ "unrecognized_or_unsupported_model_variant": "this is not a model size Strata knows",
+ "unsupported_or_missing_architecture": "this model type is not supported by the Strata engine (add it as a Custom model API with llama-server instead)",
+ "unsupported_or_incomplete_tokenizer_metadata": "the file has no usable tokenizer",
+ "missing_or_unexpected_expert_quantization": "its quantization is not one Strata knows",
+}
+# the checker's own sentences about one file, in words
+_REASON_WORDS = (
+ ("not a nonempty regular file", "the file is empty or is not a file"),
+ ("unreadable", "the file cannot be read (is it open in another program, or on a drive that is gone?)"),
+ ("could not be read", "the file cannot be read (is it open in another program, or on a drive that is gone?)"),
+ ("is missing", "the file is not there"),
+ ("link to a file that is not there", "this is a shortcut to a file that is not there any more"),
+ ("does not begin with a gguf header", "this is not a GGUF model file"),
+ ("header version", "this GGUF is from a format Strata does not read"),
+ ("requires gguf v3", "this GGUF is in an old format (version 2); Strata reads version 3"),
+ ("metadata is truncated", "the file is cut short (a download or copy that did not finish)"),
+ ("payload is shorter", "the file is shorter than its own header says (a download or copy that did not finish)"),
+ ("exceeds the bounded inspection limit", "its header is larger than Strata reads"),
+ ("too large to inspect", "its header is larger than Strata reads"),
+ ("unsupported encoding or shape", "it stores weights in a format Strata does not read"),
+ ("unsupported array type", "its header uses a type Strata does not read"),
+ ("unsupported value type", "its header uses a type Strata does not read"),
+ ("byte ranges overlap", "its header is damaged"),
+ ("unsupported_architecture", "this model type is not supported by the Strata engine (add it as a Custom model API with llama-server instead)"),
+ ("symlink", "this is a shortcut (symbolic link) that cannot be followed"),
+)
+
+
+def plain_issue(code: str) -> str:
+ """One problem from the GGUF preview, in words, with the file's name when it is about one file
+ (`file.gguf: GGUF shard is not a nonempty regular file`)."""
+ code = str(code)
+ if code in ISSUE_WORDS:
+ return ISSUE_WORDS[code]
+ name, sep, reason = code.partition(": ")
+ if not (sep and name.lower().endswith(".gguf")):
+ name, reason = "", code
+ low = reason.lower()
+ words = next((w for key, w in _REASON_WORDS if key in low), reason.replace("_", " "))
+ return f"{name}: {words}" if name else words
+
+
UNSUPPORTED_MODEL_TYPE = ("This model type isn't supported by the Strata engine. "
"Add it as a Custom model API (llama-server) instead.")
# The picture readers Strata ships a pinned copy of (setup downloads and checks one of these next to the model).
@@ -434,6 +479,23 @@ def _holds(groups_by_place: list) -> list[dict]:
return rows
+def absolute(picked: str) -> str:
+ """The picked path as an absolute path, links left alone (a snapshot file in the Hugging Face cache keeps its model name)."""
+ return os.path.abspath(os.path.expanduser(str(picked)))
+
+
+def import_target(picked: str, plan: dict) -> str:
+ """What to hand on as the person's model files: the file when they picked a file (a folder of several sizes needs the name), else the
+ folder the model files are really in (they may have picked the folder above it)."""
+ picked = absolute(picked)
+ try:
+ if Path(picked).is_file():
+ return picked
+ except OSError:
+ pass
+ return plan.get("model_dir") or picked
+
+
def plan_import(raw_path: str) -> dict:
"""Inspect a local candidate without copying, parsing tensors or adopting it.
@@ -549,7 +611,9 @@ def plan_import(raw_path: str) -> dict:
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]]
+ several = len({h.get("folder") for h in folder_holds}) > 1
+ names = [(f"{h['family']} {h['model']}" if h.get("model") else h["file"]) + (f" in {h['folder']}" if several else f" ({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):
@@ -570,6 +634,7 @@ def plan_import(raw_path: str) -> dict:
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,
+ "plain_issues": list(dict.fromkeys(plain_issue(i) for i in issues)),
"observed_expert_types": sorted(observed_experts),
"observed_tensor_count": observed_tensor_count,
"ignored_auxiliary_files": sorted(ignored_auxiliary),
diff --git a/tests/terminal/test_discovery.py b/tests/terminal/test_discovery.py
index 2dcdcb115..7ea7efca9 100644
--- a/tests/terminal/test_discovery.py
+++ b/tests/terminal/test_discovery.py
@@ -198,7 +198,7 @@ class GuiLayout(unittest.TestCase):
self.assertIn("more than one model", text)
self.assertIn("holds 2 models", text)
self.assertIn("gyro Gyro-S", text)
- self.assertIn("Point at the .gguf file of the one you want", text)
+ self.assertIn("type the path of its .gguf file", text)
self.assertNotIn("multiple_model_groups", text)
self.assertNotIn("not a model size", text)
diff --git a/tests/terminal/test_launch_tui.py b/tests/terminal/test_launch_tui.py
index 50ac23182..003fb3055 100644
--- a/tests/terminal/test_launch_tui.py
+++ b/tests/terminal/test_launch_tui.py
@@ -262,7 +262,7 @@ class ModelStep(Base):
with mock.patch("strata_control.models.plan_import", return_value=plan) as pi:
await typed(pilot, "/data/models/IQ3_XXS")
await press(pilot, "enter")
- self.assertEqual(ctx.settings.model_path, str(Path("/data/models/IQ3_XXS")))
+ self.assertEqual(ctx.settings.model_path, os.path.abspath("/data/models/IQ3_XXS"))
self.assertEqual((ctx.settings.family, ctx.settings.model), ("qwen", "IQ3_XXS"))
self.assertIn("These files are qwen IQ3_XXS (2 file(s), 44 GB)", text_of(app))
await press(pilot, "enter")
@@ -278,7 +278,7 @@ class ModelStep(Base):
await typed(pilot, "/x")
await press(pilot, "enter")
t = flat(app)
- self.assertIn("some shards are missing", t)
+ self.assertIn("some parts of the model are missing", t)
self.assertIn("pick a model from the list", t)
self.assertIsNone(ctx.settings.model_path)
self.run_app(case)
diff --git a/tests/terminal/test_own_files.py b/tests/terminal/test_own_files.py
index 4d94bd1af..e4f0de8b9 100644
--- a/tests/terminal/test_own_files.py
+++ b/tests/terminal/test_own_files.py
@@ -234,6 +234,79 @@ class Folders(Base):
self.assertEqual(plan["issues"], ["incomplete_or_invalid_shard_set"])
+class Launcher(Base):
+ """`strata launch --model-path` and the TUI's "use my own files" (strata_cli/launch/runner.py, screens.py)."""
+
+ def runner(self, **kw):
+ from strata_cli.launch import settings as S
+ from strata_cli.launch.catalog import Catalog
+ from strata_cli.launch.runner import Runner
+ from tests.terminal.launch_support import HW_12
+ return Runner(S.LaunchSettings(**kw), catalog=Catalog(hardware=HW_12))
+
+ def test_a_folder_above_the_model_is_resolved_to_the_model_folder(self):
+ data = self.base / "Strata-data"
+ self.gsq(data / "models" / "q2_0", Q2, "Q2_0")
+ r = self.runner(model_path=str(data))
+ r.resolve_own_files()
+ self.assertEqual((r.s.family, r.s.model), ("qwen", "Q2_0"))
+ self.assertEqual(Path(r.s.model_path), data / "models" / "q2_0")
+ argv = r.setup_args()
+ self.assertEqual(Path(argv[argv.index("--gguf-dir") + 1]), data / "models" / "q2_0")
+
+ def test_a_named_model_in_a_folder_of_several_sizes_is_never_refused_here(self):
+ folder = self.gsq(self.base / "many", Q2, "Q2_0")
+ self.gsq(folder, IQ3XXS, "IQ3_XXS")
+ r = self.runner(model_path=str(folder), family="qwen", model="IQ3_XXS")
+ r.resolve_own_files()
+ self.assertEqual(Path(r.s.model_path), folder) # setup picks the IQ3_XXS files by name, as in 0.1.45
+ self.assertEqual((r.s.family, r.s.model), ("qwen", "IQ3_XXS"))
+
+ def test_a_named_model_is_found_in_the_folder_that_holds_it(self):
+ repo = self.base / "repo"
+ self.gsq(repo / "Q2_0", Q2, "Q2_0")
+ self.gsq(repo / "IQ3_XXS", IQ3XXS, "IQ3_XXS")
+ r = self.runner(model_path=str(repo), family="qwen", model="IQ3_XXS")
+ r.resolve_own_files()
+ self.assertEqual(Path(r.s.model_path), repo / "IQ3_XXS")
+
+ def test_two_models_and_none_named_says_which_in_plain_words(self):
+ from strata_cli.launch.runner import LaunchError
+ repo = self.base / "repo"
+ self.gsq(repo / "Q2_0", Q2, "Q2_0")
+ self.gsq(repo / "IQ3_XXS", IQ3XXS, "IQ3_XXS")
+ r = self.runner(model_path=str(repo))
+ with self.assertRaises(LaunchError) as ctx:
+ r.resolve_own_files()
+ text = str(ctx.exception)
+ self.assertIn("more than one model", text)
+ self.assertIn("holds 2 models", text)
+
+ def test_a_linked_model_file_keeps_its_name(self):
+ snap = Links.make_links(self)
+ r = self.runner(model_path=str(snap / Q2[0]))
+ r.resolve_own_files()
+ self.assertEqual((r.s.family, r.s.model), ("qwen", "Q2_0"))
+ self.assertEqual(Path(r.s.model_path).name, Q2[0]) # not the blob's hash name
+
+
+class Words(unittest.TestCase):
+ def test_a_file_problem_names_the_file_and_says_why(self):
+ self.assertEqual(models.plain_issue("model-00002-of-00002.gguf: GGUF metadata is truncated"),
+ "model-00002-of-00002.gguf: the file is cut short (a download or copy that did not finish)")
+ self.assertIn("shorter than its own header", models.plain_issue("a.gguf: GGUF tensor payload is shorter than its directory requires"))
+ self.assertIn("old format (version 2)", models.plain_issue("a.gguf: Strata metadata preflight requires GGUF v3"))
+ self.assertEqual(models.plain_issue("incomplete_or_invalid_shard_set"), "some parts of the model are missing")
+
+ def test_the_plan_carries_the_words(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ f = Path(tmp) / Q2[0]
+ f.write_bytes(gguf_bytes(["Q2_0"])[:60])
+ plan = models.plan_import(str(f))
+ self.assertTrue(plan["plain_issues"])
+ self.assertTrue(any(x.startswith(Q2[0] + ":") or x.startswith(Q2[1] + ":") for x in plan["plain_issues"]), plan["plain_issues"])
+
+
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)."""