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.pyindex 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 keepsdiff --git a/strata_cli/cli.py b/strata_cli/cli.pyindex 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.pyindex 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.runrunner_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 stfrom 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 Nonediff --git a/strata_control/tune_api.py b/strata_control/tune_api.pyindex 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.pyindex 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 rollbackcomparison."""+ from strata_control.tuning import flag_argvout: 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 outdiff --git a/strata_control/tune_engine.py b/strata_control/tune_engine.pyindex 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 pathself.env = envself.boot_timeout_s = boot_timeout_sself.request_timeout_s = request_timeout_s@@ -410,12 +413,10 @@ class EngineHarness:self._context: int | None = Nonedef _argv(self) -> list[str]:- from strata_control.tuning import engine_command+ from strata_control.tuning import engine_command, flag_argvargv = [*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 argvdef __enter__(self) -> "EngineHarness":diff --git a/strata_control/tuning.py b/strata_control/tuning.pyindex 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 Noneimport rediff --git a/tests/terminal/test_archive_gaps.py b/tests/terminal/test_archive_gaps.pynew file mode 100644index 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()