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 archive: calibrate refuses in words, models import works, tuner runs a packaged engine and boolean flags

Niko122185c7bfda294e
diff --git a/packaging/package_terminal.py b/packaging/package_terminal.py
index 2b3b2978c..bb207382c 100644
--- a/packaging/package_terminal.py
+++ b/packaging/package_terminal.py
@@ -97,6 +97,7 @@ PAYLOAD = (
"requirements.txt",
"requirements-monitor.txt",
"docs/MANAGEMENT_PROTOCOL.md",
+ "data/gguf_fingerprints.json", # `strata models import --plan` names a known file set from this table
)
#: `tools/` modules the terminal paths import. Adding one here is a deliberate act: this list is what keeps
diff --git a/strata_cli/cli.py b/strata_cli/cli.py
index 81476f0c5..ff7995b85 100644
--- a/strata_cli/cli.py
+++ b/strata_cli/cli.py
@@ -1302,6 +1302,17 @@ def _reopen_run(store, data: dict):
return run
+def _engine_arg(value: str, backend: str) -> Path:
+ """`--engine` is a path, or `component:strata-engine` for the engine package installed for this PC."""
+ from strata_control import engine_component
+ if engine_component.is_reference(value):
+ try:
+ return Path(engine_component.expand(value, {"backend": backend}))
+ except engine_component.EngineMissing as exc:
+ raise ProfileError(str(exc), 5) from None
+ return Path(value)
+
+
def _tune(a: argparse.Namespace) -> int:
"""Engine tuning: a bounded search that returns a recommendation, never an automatic change.
@@ -1383,7 +1394,7 @@ def _tune(a: argparse.Namespace) -> int:
return _tune_rollback(a, store_root=state_root())
# plan
- engine = Path(a.engine)
+ engine = _engine_arg(a.engine, a.backend)
plan = tuning.plan_tuning(engine, a.backend, a.model, a.objective,
{"note": "the workload is supplied by the measurement harness"},
hold=a.hold, max_trials=a.trials, total_time_s=a.total_time,
@@ -1426,7 +1437,7 @@ def _tune_run(a: argparse.Namespace, *, store_root: Path) -> int:
"""
from strata_control import tune_engine, tuning
- engine = Path(a.engine)
+ engine = _engine_arg(a.engine, a.backend)
if not engine.exists():
return _error(f"no engine binary at {engine}", 2, a.output == "json")
diff --git a/strata_control/calibration.py b/strata_control/calibration.py
index cd8042e1d..6850922bf 100644
--- a/strata_control/calibration.py
+++ b/strata_control/calibration.py
@@ -35,6 +35,47 @@ ALLOWED_SETTINGS = {"--pcie-frac", "--spec-min-p", "--pool-workers",
"--adapt-every", "--adapt-swaps", "--adapt-decay"}
+def _full_folder(name: str):
+ """`setup` and `tools.calibrate` belong to a full Strata folder; the Terminal archive carries neither (it never
+ installs or builds). Use them when they are importable, or when STRATA_INSTALL_DIR names a folder that has both;
+ otherwise refuse in words instead of a traceback."""
+ import importlib
+ import sys
+ try:
+ return importlib.import_module(name)
+ except ImportError:
+ pass
+ raw = os.environ.get("STRATA_INSTALL_DIR")
+ if raw:
+ folder = Path(raw).expanduser()
+ if (folder / "setup.py").is_file() and (folder / "tools" / "calibrate.py").is_file():
+ if str(folder) not in sys.path:
+ sys.path.append(str(folder))
+ try:
+ return importlib.import_module(name)
+ except ImportError:
+ pass
+ raise ProfileError(
+ "engine calibrate needs a full Strata folder (setup.py and tools/calibrate.py); this terminal archive has "
+ "neither. Set STRATA_INSTALL_DIR to such a folder, or use `strata tune run --mode api` to tune from the "
+ "archive", 5) from None
+
+
+def _tools_available() -> bool:
+ """False in the Terminal archive without STRATA_INSTALL_DIR: `--measure` would be refused (see `_full_folder`)."""
+ import importlib.util
+ try:
+ if importlib.util.find_spec("setup") and importlib.util.find_spec("tools.calibrate"):
+ return True
+ except (ImportError, ValueError):
+ pass
+ raw = os.environ.get("STRATA_INSTALL_DIR")
+ if raw:
+ folder = Path(raw).expanduser()
+ return (folder / "setup.py").is_file() and (folder / "tools" / "calibrate.py").is_file()
+ return False
+
+
def _digest(path: Path) -> str:
result = hashlib.sha256()
with path.open("rb") as stream:
@@ -59,6 +100,7 @@ def preview(ref: str) -> dict:
"source_config": str(path), "source_sha256": hashlib.sha256(source_bytes).hexdigest(),
"model_name": cfg.get("model_name"), "backend": cfg.get("backend") or "unverified",
"devices_selected": cfg.get("gpu"), "tool": "tools/calibrate.py",
+ "tool_available": _tools_available(),
"estimated_minutes": [15, 30], "requires_exclusive_engine": True,
"settings_measured": ["--pcie-frac", "--spec-min-p", "--pool-workers",
"--adapt-every", "--adapt-swaps", "--adapt-decay"],
@@ -95,12 +137,11 @@ def _runtime_cfg(cfg: dict, profile: dict | None) -> dict:
def _hardware_key(cfg: dict) -> str:
- import setup
- return setup.hardware_key(cfg)
+ return _full_folder("setup").hardware_key(cfg)
def _identity(path: Path, cfg: dict, profile: dict | None, revision: str | None) -> dict:
- import tools.calibrate as cal
+ cal = _full_folder("tools.calibrate")
engine = _resolved(cfg["exe"], cfg, path)
components = inspect_components(path, profile_id=profile["id"] if profile else None)
if not components["ok"]:
@@ -249,7 +290,7 @@ def _measure_locked(ref: str, path: Path, profile: dict | None, revision: str |
if output.exists() or output.is_symlink():
raise ProfileError("calibration report path already exists", 2)
identity = _identity(path, cfg, profile, revision)
- from tools import calibrate as cal
+ cal = _full_folder("tools.calibrate")
execute = runner or cal.run
runner_cfg = _runtime_cfg(cfg, profile)
runner_cfg["exe"] = str(_resolved(cfg["exe"], cfg, path))
@@ -317,7 +358,7 @@ def load_report(path: Path) -> dict:
def review(ref: str, report_path: Path) -> dict:
path, profile, revision, cfg = _target(ref)
report = load_report(report_path)
- from tools import calibrate as cal
+ cal = _full_folder("tools.calibrate")
reasons = []
if report["source_config"] != str(path):
reasons.append("source_config_mismatch")
@@ -343,7 +384,7 @@ def _smoke(cfg: dict, source_path: Path) -> int:
"""Start the candidate and require at least one generated token before writing it."""
import strata_tokenizer as st
from serve.server import StrataEngine, child_env, engine_args
- from tools import calibrate as cal
+ cal = _full_folder("tools.calibrate")
tokdir = _resolved(cfg["tokenizer"], cfg, source_path)
vocab = json.loads((tokdir / "vocab.json").read_text(encoding="utf-8"))
tokens = [None] * len(vocab)
@@ -378,8 +419,7 @@ def _replace_bytes(path: Path, payload: bytes) -> None:
def _settings_candidate(hardware_key: str, result: dict) -> tuple[Path, bytes | None, bytes]:
"""Prepare setup's remembered calibration without accepting a corrupt store."""
- import setup
- target = setup.settings_path()
+ target = _full_folder("setup").settings_path()
try:
previous = target.read_bytes()
settings = json.loads(previous.decode("utf-8"))
@@ -473,8 +513,7 @@ def _load_application(path: Path, report: dict) -> dict:
data["before_config_sha256"] != report["identity"].get("source_sha256"):
raise ProfileError("calibration application record has an unsupported shape", 5)
try:
- import setup
- if data["settings_path"] != str(setup.settings_path()):
+ if data["settings_path"] != str(_full_folder("setup").settings_path()):
raise ProfileError("setup settings path changed since calibration apply", 5)
except (OSError, ValueError):
raise ProfileError("setup settings path is unavailable", 5) from None
diff --git a/strata_control/tune_api.py b/strata_control/tune_api.py
index 4952b0295..635b5c43f 100644
--- a/strata_control/tune_api.py
+++ b/strata_control/tune_api.py
@@ -107,7 +107,15 @@ class ApiHarness:
return ""
try:
text = Path(self._log.name).read_text(encoding="utf-8", errors="replace")
- return f"; log: {text[-limit:].strip()}" if text.strip() else ""
+ if not text.strip():
+ return ""
+ # The engine prints its reason first and a usage dump after it, so the last 500 characters of a
+ # rejected flag are the middle of the usage text. Name the reason line(s) before the tail.
+ reasons = [line.strip() for line in text.splitlines()
+ if re.search(r"unknown argument|unrecognized|invalid value|error|refus|is required|cannot|failed",
+ line, re.IGNORECASE)][:3]
+ lead = f"; reason: {' | '.join(reasons)[:300]}" if reasons else ""
+ return f"{lead}; log: {text[-limit:].strip()}"
except OSError:
return ""
diff --git a/strata_control/tune_apply.py b/strata_control/tune_apply.py
index bef5b76bb..6aced3faa 100644
--- a/strata_control/tune_apply.py
+++ b/strata_control/tune_apply.py
@@ -79,6 +79,7 @@ def args_to_argv(args: dict[str, Any]) -> list[str]:
reshuffled its own output would produce a different digest each time and break the rollback
comparison.
"""
+ from strata_control.tuning import flag_argv
out: list[str] = []
for flag in sorted(args):
value = args[flag]
@@ -87,7 +88,7 @@ def args_to_argv(args: dict[str, Any]) -> list[str]:
if value is True:
out.append(flag)
continue
- out.extend([flag, str(value)])
+ out.extend(flag_argv(flag, value))
return out
diff --git a/strata_control/tune_engine.py b/strata_control/tune_engine.py
index 447e8bab5..b794b7aa6 100644
--- a/strata_control/tune_engine.py
+++ b/strata_control/tune_engine.py
@@ -400,6 +400,9 @@ class EngineHarness:
self.args = dict(args)
self.workload = {**DEFAULT_WORKLOAD, **(workload or {})}
self.cwd = Path(cwd) if cwd else Path.cwd()
+ if env is None:
+ from strata_control.tuning import engine_env
+ env = engine_env(self.engine) # an engine package's own folder first on the library path
self.env = env
self.boot_timeout_s = boot_timeout_s
self.request_timeout_s = request_timeout_s
@@ -410,12 +413,10 @@ class EngineHarness:
self._context: int | None = None
def _argv(self) -> list[str]:
- from strata_control.tuning import engine_command
+ from strata_control.tuning import engine_command, flag_argv
argv = [*engine_command(self.engine), "--serve"]
for flag, value in self.args.items():
- argv.append(flag)
- if value not in ("1", "0", "true", "false", ""):
- argv.append(str(value))
+ argv.extend(flag_argv(flag, value))
return argv
def __enter__(self) -> "EngineHarness":
diff --git a/strata_control/tuning.py b/strata_control/tuning.py
index fdc44668f..3522d1780 100644
--- a/strata_control/tuning.py
+++ b/strata_control/tuning.py
@@ -118,6 +118,20 @@ DIMENSIONS: tuple[Dimension, ...] = (
benchmark_only=True),
)
+#: Flags that take no value: on when present, off when absent. A candidate records them as "1" / "0".
+BOOLEAN_FLAGS = frozenset(flag for _d in DIMENSIONS if all(isinstance(v, bool) for v in _d.values) for flag in _d.flags)
+
+
+def flag_argv(flag: str, value: Any) -> list[str]:
+ """One candidate setting as engine argv. A boolean flag is `--flag` when on and nothing when off; it never
+ gets a value ("--kv-grow 0" is "unknown argument: 0" to the engine, and a bare "--kv-grow" meaning off enabled it)."""
+ if flag in BOOLEAN_FLAGS or isinstance(value, bool):
+ return [flag] if value in (True, "1", "true", "True") else []
+ if value is None or value == "":
+ return [flag]
+ return [flag, str(value)]
+
+
#: Dimensions a backend must never be offered, with the reason kept for the report.
def _why_excluded(dim: Dimension, backend: str) -> str | None:
if backend in dim.backends:
@@ -170,6 +184,21 @@ def engine_command(engine: Path | str) -> list[str]:
return [sys.executable, path] if path.lower().endswith(".py") else [path]
+def engine_env(engine: Path | str) -> dict[str, str] | None:
+ """The environment to run an engine with, or None for the caller's own.
+
+ An engine package (`engine-component.json` beside the binary) carries its GPU runtime libraries in its own
+ folder, and `serve` puts that folder first on the library path. A tuning run that starts the same binary must
+ too, or it cannot even print `--help` ("error while loading shared libraries")."""
+ folder = Path(engine).resolve().parent
+ if not (folder / "engine-component.json").is_file():
+ return None
+ var = "PATH" if os.name == "nt" else "LD_LIBRARY_PATH"
+ env = dict(os.environ)
+ env[var] = os.pathsep.join([str(folder)] + ([env[var]] if env.get(var) else []))
+ return env
+
+
def engine_flag_inventory(engine: Path) -> list[str] | None:
"""Read the flags an engine binary documents, or None when it cannot be run here.
@@ -180,7 +209,8 @@ def engine_flag_inventory(engine: Path) -> list[str] | None:
at all.
"""
try:
- proc = subprocess.run([*engine_command(engine), "--help"], capture_output=True, text=True, timeout=20)
+ proc = subprocess.run([*engine_command(engine), "--help"], capture_output=True, text=True, timeout=20,
+ env=engine_env(engine))
except (OSError, subprocess.SubprocessError):
return None
import re
diff --git a/tests/terminal/test_archive_gaps.py b/tests/terminal/test_archive_gaps.py
new file mode 100644
index 000000000..59b82347d
--- /dev/null
+++ b/tests/terminal/test_archive_gaps.py
@@ -0,0 +1,95 @@
+"""Things a user of the Terminal archive (no setup.py, no tools/calibrate.py, an engine package) hit on real boxes."""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(ROOT))
+
+from strata_control import calibration, tune_apply, tuning # noqa: E402
+from strata_control.profiles import ProfileError # noqa: E402
+
+
+class BooleanFlags(unittest.TestCase):
+ def test_a_boolean_flag_is_on_or_absent_never_given_a_value(self):
+ self.assertEqual(tuning.flag_argv("--kv-grow", "1"), ["--kv-grow"])
+ self.assertEqual(tuning.flag_argv("--kv-grow", "0"), [])
+ self.assertEqual(tuning.flag_argv("--kv-grow", True), ["--kv-grow"])
+ self.assertEqual(tuning.flag_argv("--kv-grow", False), [])
+ self.assertEqual(tuning.flag_argv("--spec-min-p", "0.5"), ["--spec-min-p", "0.5"])
+ self.assertEqual(tuning.flag_argv("--spec", "1"), ["--spec", "1"]) # a numeric flag keeps its 1
+
+ def test_a_candidate_with_kv_grow_off_does_not_become_kv_grow_0(self):
+ self.assertEqual(tune_apply.args_to_argv({"--kv-grow": "0", "--kv": "int8"}), ["--kv", "int8"])
+ self.assertEqual(tune_apply.args_to_argv({"--kv-grow": "1"}), ["--kv-grow"])
+
+ def test_the_harness_argv_follows_the_same_rule(self):
+ from strata_control import tune_engine
+ harness = tune_engine.EngineHarness(Path("engine"), {"--kv-grow": "0", "--pool-workers": "0", "--host-core": "first"})
+ argv = harness._argv()
+ self.assertNotIn("--kv-grow", argv)
+ self.assertIn("--pool-workers", argv)
+ self.assertEqual(argv[argv.index("--pool-workers") + 1], "0")
+
+
+class EnginePackageEnv(unittest.TestCase):
+ def test_a_package_folder_goes_first_on_the_library_path(self):
+ with tempfile.TemporaryDirectory() as d:
+ folder = Path(d)
+ (folder / "engine-component.json").write_text("{}", encoding="utf-8")
+ (folder / "strata").write_text("x", encoding="utf-8")
+ with mock.patch.dict(os.environ, {"LD_LIBRARY_PATH": "/old", "PATH": "/old"}):
+ env = tuning.engine_env(folder / "strata")
+ var = "PATH" if os.name == "nt" else "LD_LIBRARY_PATH"
+ self.assertTrue(env[var].startswith(str(folder.resolve())))
+ self.assertTrue(env[var].endswith("/old") or env[var].endswith("old"))
+
+ def test_a_plain_engine_keeps_the_callers_environment(self):
+ with tempfile.TemporaryDirectory() as d:
+ (Path(d) / "strata").write_text("x", encoding="utf-8")
+ self.assertIsNone(tuning.engine_env(Path(d) / "strata"))
+
+
+class CalibrateWithoutAFullFolder(unittest.TestCase):
+ def test_missing_setup_is_a_refusal_in_words_not_a_traceback(self):
+ with mock.patch.dict(os.environ, {}, clear=False):
+ os.environ.pop("STRATA_INSTALL_DIR", None)
+ with mock.patch("importlib.import_module", side_effect=ImportError("no module")):
+ with self.assertRaises(ProfileError) as ctx:
+ calibration._full_folder("tools.calibrate")
+ self.assertEqual(ctx.exception.code if hasattr(ctx.exception, "code") else 5, 5)
+ self.assertIn("STRATA_INSTALL_DIR", str(ctx.exception))
+ self.assertIn("tune run --mode api", str(ctx.exception))
+
+ def test_tool_availability_is_reported_for_the_plan(self):
+ with mock.patch.dict(os.environ, {}, clear=False):
+ os.environ.pop("STRATA_INSTALL_DIR", None)
+ with mock.patch("importlib.util.find_spec", return_value=None):
+ self.assertFalse(calibration._tools_available())
+ with tempfile.TemporaryDirectory() as d:
+ (Path(d) / "tools").mkdir()
+ (Path(d) / "setup.py").write_text("", encoding="utf-8")
+ (Path(d) / "tools" / "calibrate.py").write_text("", encoding="utf-8")
+ os.environ["STRATA_INSTALL_DIR"] = d
+ with mock.patch("importlib.util.find_spec", return_value=None):
+ self.assertTrue(calibration._tools_available())
+
+
+class ArchiveContents(unittest.TestCase):
+ def test_the_fingerprint_table_models_import_reads_is_in_the_payload(self):
+ sys.path.insert(0, str(ROOT / "packaging"))
+ import package_terminal
+ self.assertIn("data/gguf_fingerprints.json", package_terminal.PAYLOAD)
+ self.assertTrue((ROOT / "data" / "gguf_fingerprints.json").is_file())
+
+
+if __name__ == "__main__":
+ unittest.main()