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

auto-tuner: single-knob candidates from the measured spec, interleaved rounds with noise and drift guards, memory guards, saved presets (one store for CLI and app), re-check, strata tune auto / strata presets

Niko1221f23eda8c952f
diff --git a/serve/server.py b/serve/server.py
index 606b70260..c819fda4a 100644
--- a/serve/server.py
+++ b/serve/server.py
@@ -7182,6 +7182,10 @@ def sampling_defaults_from_config(cfg: dict) -> dict:
if not number or value != int(value) or value <= 0:
raise SystemExit(f"[strata] config sampling.seed={value!r}: expected a positive integer")
out[key] = int(value)
+ elif key == "strata_tune": # a saved tuning's per-request settings (strata_control/presets.py)
+ if not isinstance(value, dict):
+ raise SystemExit(f"[strata] config sampling.strata_tune={value!r}: expected an object")
+ out[key] = {k: v for k, v in value.items() if k in ("pcie_frac", "spec_min_p", "aux_cpus")}
elif key == "experimental_speed_projection":
if not isinstance(value, bool):
raise SystemExit(f"[strata] config sampling.experimental_speed_projection={value!r}: expected true or "
@@ -7409,6 +7413,23 @@ def main(argv=None, *, lifecycle_event=None, interrupt_exit_code: int = 0) -> in
ap.error("--shutdown-timeout must be in 0..300 seconds")
config_bytes = Path(a.config).read_bytes() if a.config else b""
cfg = json.loads(config_bytes.decode("utf-8-sig")) if a.config else {} # Notepad adds a BOM
+ if a.config and a.engine == "strata" and not os.environ.get("STRATA_NO_PRESET"):
+ # the saved tuning for this model and these choices (strata_control/presets.py): applied with no measurement. A tune's
+ # own worker sets STRATA_NO_PRESET so that it measures the configuration it was given. Never fails the start.
+ try:
+ from strata_control import presets as _presets
+ cfg, _applied = _presets.overlay(cfg)
+ if _applied.get("applied"):
+ print(f"[strata] saved tuning '{_applied['preset']['name']}' applied: "
+ f"{' '.join(f'{k} {v}' for k, v in {**(_applied.get('args') or {}), **(_applied.get('env') or {})}.items())}"
+ f"{'; ' + _applied['notice'] if _applied.get('notice') and 'identical' not in _applied['notice'] else ''}", flush=True)
+ if _applied.get("state") == "soft":
+ print("[strata] this PC or engine changed since it was saved (" + "; ".join(_applied["reasons"]) +
+ "): a short re-check is available (strata presets recheck)", flush=True)
+ elif _applied.get("why_not"):
+ print(f"[strata] saved tuning '{_applied['preset']['name']}' {_applied['why_not']}; re-tune with strata tune auto", flush=True)
+ except Exception as _e: # noqa: BLE001
+ print(f"[strata] saved tuning could not be read ({type(_e).__name__}); starting with the configuration as it is", flush=True)
attestation_key = os.environ.pop("STRATA_OWNER_ATTEST_KEY", None)
launch_attestation = None
if a.owner_fd is not None:
diff --git a/strata_cli/cli.py b/strata_cli/cli.py
index 001ae1250..784590f2a 100644
--- a/strata_cli/cli.py
+++ b/strata_cli/cli.py
@@ -24,7 +24,7 @@ BACKENDS = ("metal", "cuda", "hip", "sycl", "cpu")
from strata_control.doctor import inspect as inspect_components
from strata_control.profiles import ProfileError
from strata_cli.client import ClientError, Endpoint
-from strata_cli import monitor_commands
+from strata_cli import monitor_commands, tune_commands
class _VersionAction(argparse.Action):
@@ -440,6 +440,8 @@ def parser() -> argparse.ArgumentParser:
tune_list.add_argument("--state-dir", default=None)
tune_list.add_argument("--output", choices=("human", "json"), default="human")
+ tune_commands.add_tune_auto(tune_sp)
+ tune_commands.add_presets(sp)
monitor_commands.add_status(sp)
monitor_commands.add_monitor(sp)
monitor_commands.add_logs(sp)
@@ -1351,6 +1353,9 @@ def _tune(a: argparse.Namespace) -> int:
from strata_control.paths import state_base
return state_base() / "tuning"
+ if a.tune_command == "auto":
+ return tune_commands.auto(a)
+
if a.tune_command == "list":
root = state_root()
jobs = []
@@ -1795,6 +1800,8 @@ def _run(a: argparse.Namespace) -> int:
return _bench(a)
if a.command == "timeskip":
return _timeskip(a)
+ if a.command == "presets":
+ return tune_commands.presets_command(a)
if a.command == "tune":
return _tune(a)
if a.command == "runtime":
diff --git a/strata_cli/tune_commands.py b/strata_cli/tune_commands.py
new file mode 100644
index 000000000..d0a4bf0cb
--- /dev/null
+++ b/strata_cli/tune_commands.py
@@ -0,0 +1,401 @@
+"""`strata tune auto` (the real tuner) and `strata presets` (the saved results), for the Terminal and, through JSON output
+and a status file, for the desktop app. The same code and the same store serve both."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import tempfile
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+
+# --------------------------------------------------------------------------- parsers
+
+def add_tune_auto(tune_sp: argparse._SubParsersAction) -> None:
+ p = tune_sp.add_parser(
+ "auto", help="find the fastest settings for this PC and save them as a preset (quick: about 20 minutes)",
+ description="Measures your configuration, tries single-knob changes in interleaved rounds against it, keeps only gains "
+ "above the noise, and saves the result as a named preset that is applied at every start. "
+ "Nothing changes if the current settings are already the fastest.")
+ p.add_argument("target", help="a saved profile name or a run configuration (JSON) to tune")
+ p.add_argument("--mode", choices=("quick", "thorough"), default="quick",
+ help="quick: about 20 minutes. thorough: up to 2 hours, 5-pair confirmation (default quick)")
+ p.add_argument("--goal", default="speed", help="speed (full performance), room (leave memory free), or room:MiB "
+ "(leave that much graphics memory free)")
+ p.add_argument("--leave-ram", type=int, default=0, metavar="PERCENT", help="leave this share of system memory free (0-50)")
+ p.add_argument("--use", choices=("chat", "coding"), default="chat", help="coding judges long-prompt speed as well")
+ p.add_argument("--allow-small-differences", action="store_true",
+ help="also try settings that can change answers slightly (expert cache split, speculative window)")
+ p.add_argument("--allow-not-repeatable", action="store_true", help="also try settings whose answers are not repeatable")
+ p.add_argument("--name", default=None, help="the preset's name (default: model, context and your wish)")
+ p.add_argument("--time", dest="minutes", type=float, default=None, help="time to spend, in minutes")
+ p.add_argument("--no-save", action="store_true", help="measure and report, but do not save a preset")
+ p.add_argument("--gpu-lock", default=os.environ.get("STRATA_TUNE_GPU_LOCK"),
+ help="a lock file held around every engine run (shared boxes)")
+ p.add_argument("--no-quiet-check", action="store_true", help="do not wait for other engines or a busy CPU")
+ p.add_argument("--serve-dir", default=None, help="the folder that holds serve/ (default: this installation)")
+ p.add_argument("--work-dir", default=None, help="where the run's configs and logs go (default: a temp folder)")
+ p.add_argument("--status-file", default=None, help="progress as JSON, rewritten at every step (for the desktop app)")
+ p.add_argument("--boot-timeout", type=float, default=900.0)
+ p.add_argument("--output", choices=("human", "json"), default="human")
+
+
+def add_presets(sp: argparse._SubParsersAction) -> None:
+ pr = sp.add_parser("presets", help="saved tuning presets: list, apply, rename, delete, undo, re-check")
+ psp = pr.add_subparsers(dest="presets_command", required=True)
+
+ def common(x: argparse.ArgumentParser) -> argparse.ArgumentParser:
+ x.add_argument("--output", choices=("human", "json"), default="human")
+ return x
+
+ l = common(psp.add_parser("list", help="every saved preset (or those for one model/configuration)"))
+ l.add_argument("--model", default=None, help="only presets whose model or quant contains this text")
+ s = common(psp.add_parser("status", help="which preset a configuration would start with, and whether it is still valid"))
+ s.add_argument("target", help="a saved profile name or a run configuration (JSON)")
+ sh = common(psp.add_parser("show", help="one preset in full"))
+ sh.add_argument("preset")
+ ap = common(psp.add_parser("apply", help="make a preset the active one for its choices (the previous one is kept for undo)"))
+ ap.add_argument("preset")
+ rn = common(psp.add_parser("rename", help="give a preset another name"))
+ rn.add_argument("preset")
+ rn.add_argument("name")
+ de = common(psp.add_parser("delete", help="delete a preset"))
+ de.add_argument("preset")
+ un = common(psp.add_parser("undo", help="go back to the preset that was active before (or the standard settings)"))
+ un.add_argument("preset", help="a preset, or a configuration target with --config")
+ un.add_argument("--config", default=None, help="a profile name or run configuration whose slot to undo")
+ ex = common(psp.add_parser("export", help="write a preset to a file (or print it)"))
+ ex.add_argument("preset")
+ ex.add_argument("--file", default=None)
+ im = common(psp.add_parser("import", help="read a preset from a file"))
+ im.add_argument("file")
+ rc = common(psp.add_parser("recheck", help="a short check (about 2 minutes) that a preset is still as fast"))
+ rc.add_argument("preset")
+ rc.add_argument("target", help="the profile name or run configuration the preset belongs to")
+ rc.add_argument("--gpu-lock", default=os.environ.get("STRATA_TUNE_GPU_LOCK"))
+ rc.add_argument("--serve-dir", default=None)
+ rc.add_argument("--work-dir", default=None)
+ rc.add_argument("--status-file", default=None)
+ rc.add_argument("--boot-timeout", type=float, default=900.0)
+ rc.add_argument("--no-quiet-check", action="store_true")
+
+
+# --------------------------------------------------------------------------- helpers
+
+def _print(payload: dict[str, Any], machine: bool, human: str) -> int:
+ if machine:
+ print(json.dumps({"schema_version": 1, "ok": True, **payload}, ensure_ascii=False, default=str))
+ else:
+ print(human)
+ return 0
+
+
+def _fail(message: str, code: int, machine: bool) -> int:
+ if machine:
+ print(json.dumps({"schema_version": 1, "ok": False, "error": {"code": code, "message": message}}))
+ else:
+ print(f"strata: {message}", file=sys.stderr)
+ return code
+
+
+def _load_target(target: str) -> tuple[Path, dict[str, Any]]:
+ from strata_control import profiles
+ path, _profile, _rev = profiles.resolve(target)
+ return path, profiles.read_run_config(path)
+
+
+def _engine_exe(cfg: dict[str, Any]) -> str:
+ from strata_control import engine_component
+ ref = cfg.get("exe")
+ if engine_component.is_reference(ref):
+ return engine_component.expand(ref, cfg, full=False)
+ p = Path(ref)
+ return str(p if p.is_absolute() else Path(cfg.get("cwd") or ".") / p)
+
+
+def _serve_dir(a: argparse.Namespace) -> Path:
+ if getattr(a, "serve_dir", None):
+ return Path(a.serve_dir)
+ return Path(__file__).resolve().parent.parent
+
+
+def _lock_factory(a: argparse.Namespace, log):
+ if not getattr(a, "gpu_lock", None):
+ return None
+ from strata_control.tune_session import FileLock
+ return lambda: FileLock(a.gpu_lock, log=log)
+
+
+def _parse_goal(text: str) -> tuple[str, int]:
+ if text in ("speed", "full"):
+ return "speed", 0
+ if text == "room":
+ return "room", 0
+ if text.startswith("room:"):
+ return "room", max(0, int(text[5:]))
+ raise ValueError("goal is speed, room or room:MiB")
+
+
+def _write_status(path: str | None, payload: dict[str, Any]) -> None:
+ if not path:
+ return
+ try:
+ tmp = path + ".tmp"
+ Path(tmp).write_text(json.dumps(payload, ensure_ascii=False, default=str), encoding="utf-8")
+ os.replace(tmp, path)
+ except OSError:
+ pass
+
+
+def minutes_text(seconds: float | None) -> str:
+ if seconds is None:
+ return ""
+ m = max(1, int(round(seconds / 60.0)))
+ return f"about {m} min left"
+
+
+def _hw_hash(identity: dict[str, Any]) -> str:
+ from strata_control import tune_machine
+ return tune_machine.stable_hash((identity.get("hardware") or {}).get("hard"))
+
+
+# --------------------------------------------------------------------------- tune auto
+
+def auto(a: argparse.Namespace) -> int:
+ from strata_control import autotune, engine_component, presets, tune_knobs, tune_machine, tuning
+ from strata_control.tune_session import WorkerSession
+
+ machine = a.output == "json"
+ try:
+ goal, reserve = _parse_goal(a.goal)
+ cfg_path, cfg = _load_target(a.target)
+ except Exception as e: # noqa: BLE001
+ return _fail(str(e), getattr(e, "exit_code", 2), machine)
+ if not 0 <= a.leave_ram <= 50:
+ return _fail("--leave-ram is a percentage from 0 to 50", 2, machine)
+ if a.leave_ram and goal == "speed":
+ goal = "room"
+ exe = _engine_exe(cfg)
+ if not Path(exe).exists():
+ return _fail(f"no engine was found at {exe}", 5, machine)
+ identity = presets.current_identity(cfg, exe=exe)
+ backend = (identity.get("engine") or {}).get("backend") or engine_component.detect_backend()[0] or "cpu"
+ flags = tuning.engine_flag_inventory(Path(exe))
+ opts = autotune.Options(mode=a.mode, goal=goal, reserve_mib=reserve, ram_wish_pct=a.leave_ram, use=a.use,
+ allow_placement=a.allow_small_differences, allow_nonrepeatable=a.allow_not_repeatable,
+ budget_s=(a.minutes * 60.0 if a.minutes else None), check_busy=not a.no_quiet_check)
+ ctx = autotune.context_from_config(cfg, engine_backend=backend, opts=opts, engine_flags=flags)
+ hw = _hw_hash(identity)
+ digest = (identity.get("model") or {}).get("sha256_shard1")
+ bad = presets.bad_signatures(hw_hash=hw, model_digest=digest, engine_sha=(identity.get("engine") or {}).get("sha256"))
+
+ cancel = threading.Event()
+ state: dict[str, Any] = {"stage": "start", "message": "Starting", "state": "running"}
+
+ def say(line: str) -> None:
+ if not machine:
+ print(line, file=sys.stderr, flush=True)
+
+ def progress(p: dict[str, Any]) -> None:
+ state.update(p)
+ state["minutes_left"] = None if p.get("eta_s") is None else max(1, int(round(p["eta_s"] / 60.0)))
+ state["text"] = (f"Finding the fastest settings for your PC… {minutes_text(p.get('eta_s'))}"
+ if p.get("eta_s") is not None else "Finding the fastest settings for your PC…")
+ _write_status(a.status_file, state)
+ say(f"[{p.get('elapsed_s', 0) // 60:>3d}m] {p['message']}" + (f" ({minutes_text(p['eta_s'])})" if p.get("eta_s") else ""))
+
+ workdir = Path(a.work_dir) if a.work_dir else Path(tempfile.mkdtemp(prefix="strata-tune-"))
+ session = WorkerSession(base_config=cfg, python=sys.executable, serve_dir=_serve_dir(a), workdir=workdir,
+ boot_timeout_s=a.boot_timeout, lock=_lock_factory(a, say), log=say)
+ base_args = [str(x) for x in cfg.get("args") or []]
+ # the wish becomes part of the base: leave-room asks the engine for the reserve if the configuration has none yet
+ if goal == "room" and reserve and "--vram-reserve-mib" not in base_args and ctx.family == "flash-next" \
+ and backend in ("cuda", "hip") and (flags is None or "--vram-reserve-mib" in flags):
+ base_args += ["--vram-reserve-mib", str(reserve)]
+ ctx.base_args = list(base_args)
+ tuner = autotune.Tuner(session, base_args, dict(cfg.get("env") or {}), ctx, opts, progress=progress, cancel=cancel,
+ history_bad=bad, quiet=None)
+ say(f"Tuning {presets.choices_from_config(cfg).get('model')} ({a.mode}); engine {exe}")
+ try:
+ result = tuner.run()
+ except KeyboardInterrupt:
+ cancel.set()
+ result = tuner.result
+ result.outcome, result.message = "cancelled", "Stopped. Your settings were not changed."
+ out = result.to_dict()
+ choices = presets.choices_from_config(cfg, use=a.use)
+ choices["goal"], choices["reserve_mib"] = goal, reserve
+ if a.leave_ram:
+ choices["leave_ram_pct"] = a.leave_ram
+ saved = None
+ try:
+ presets.record_trials(result.trials, hw_hash=hw, model_digest=digest,
+ engine_sha=(identity.get("engine") or {}).get("sha256"))
+ except OSError:
+ pass
+ if result.outcome in ("improved", "default_confirmed") and not a.no_save:
+ try:
+ saved = presets.create(out, choices=choices, identity=identity, name=a.name, mode=a.mode)
+ except presets.PresetError as e:
+ result.notes.append(str(e))
+ out["preset"] = ({"id": saved["id"], "name": saved["name"]} if saved else None)
+ state.update({"state": "done", "result": out, "stage": "done"})
+ _write_status(a.status_file, state)
+ if machine:
+ print(json.dumps({"schema_version": 1, "ok": True, "result": out}, ensure_ascii=False, default=str))
+ else:
+ print(_human_result(out, saved))
+ return {"improved": 0, "default_confirmed": 0, "cancelled": 130}.get(result.outcome, 6)
+
+
+def _human_result(r: dict[str, Any], saved: dict[str, Any] | None) -> str:
+ lines = [""]
+ if r["outcome"] == "improved":
+ lines.append(f"Done in {r['seconds'] / 60:.0f} min: +{r['gain_pct']:.0f}% faster answers"
+ + (f", saved as '{saved['name']}'." if saved else "."))
+ s = r["settings"]
+ shown = {**{k: v for k, v in s["args"].items()}, **s["env"], **{f"per request {k}": v for k, v in s["per_request"].items()}}
+ lines.append(" Changed: " + ", ".join(f"{k} {v}" for k, v in shown.items()))
+ lines.append(f" Measured: {r['base'].get('decode_tok_s')} -> {r['chosen'].get('decode_tok_s')} tok/s "
+ f"({r['faster_pairs']} of {r['pairs']} pairs faster)")
+ from strata_control.tune_knobs import ANSWER_NOTICE
+ lines.append(" " + ANSWER_NOTICE.get(r["answers"]["class"], ""))
+ else:
+ lines.append(r["message"] or r["outcome"])
+ if saved:
+ lines.append(f" Saved as '{saved['name']}' so it is not tuned again on reopen.")
+ for n in r.get("notes") or []:
+ lines.append(f" note: {n}")
+ return "\n".join(lines)
+
+
+# --------------------------------------------------------------------------- presets
+
+def presets_command(a: argparse.Namespace) -> int:
+ from strata_control import autotune, presets, tune_knobs
+
+ machine = a.output == "json"
+ cmd = a.presets_command
+ try:
+ if cmd == "list":
+ items = presets.list_presets(model=a.model)
+ human = "\n".join(f"{'*' if p['active'] else ' '} {p['id'][:8]} {p['name']} "
+ f"{(p.get('measured') or {}).get('gain_pct') or 0:+.0f}% {p['answers']['class']}"
+ for p in items) or "No saved presets yet. Run: strata tune auto <profile>"
+ return _print({"presets": [_summary(p) for p in items]}, machine, human)
+ if cmd == "status":
+ return _status(a, machine)
+ if cmd == "show":
+ p = presets.find(a.preset)
+ return _print({"preset": p}, machine, json.dumps(p, indent=2, ensure_ascii=False))
+ if cmd == "apply":
+ p = presets.activate_preset(a.preset)
+ return _print({"preset": _summary(p), "notice": presets.notice(p)}, machine,
+ f"'{p['name']}' is now active. It is used the next time the model starts. Undo: strata presets undo {p['id'][:8]}")
+ if cmd == "rename":
+ p = presets.rename(a.preset, a.name)
+ return _print({"preset": _summary(p)}, machine, f"Renamed to '{p['name']}'.")
+ if cmd == "delete":
+ p = presets.find(a.preset)
+ presets.delete(a.preset)
+ return _print({"deleted": p["id"]}, machine, f"Deleted '{p['name']}'.")
+ if cmd == "undo":
+ if a.config:
+ _path, cfg = _load_target(a.config)
+ ident = presets.current_identity(cfg)
+ slot = presets.slot_key(presets.choices_from_config(cfg), (ident.get("model") or {}).get("sha256_shard1"))
+ else:
+ slot = a.preset
+ back = presets.undo(slot)
+ return _print({"active": _summary(back) if back else None}, machine,
+ f"Back to '{back['name']}'." if back else "Back to the standard settings.")
+ if cmd == "export":
+ data = presets.export_preset(a.preset)
+ if a.file:
+ Path(a.file).write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+ return _print({"file": a.file}, machine, f"Wrote {a.file}")
+ print(json.dumps(data, indent=2, ensure_ascii=False))
+ return 0
+ if cmd == "import":
+ data = json.loads(Path(a.file).read_text(encoding="utf-8-sig"))
+ p = presets.import_preset(data)
+ return _print({"preset": _summary(p)}, machine, f"Imported '{p['name']}'. Apply it with: strata presets apply {p['id'][:8]}")
+ if cmd == "recheck":
+ return _recheck(a, machine)
+ except presets.PresetError as e:
+ return _fail(str(e), 5, machine)
+ except (OSError, ValueError) as e:
+ return _fail(str(e), getattr(e, "exit_code", 2), machine)
+ return _fail("unknown presets command", 2, machine)
+
+
+def _summary(p: dict[str, Any]) -> dict[str, Any]:
+ from strata_control import presets
+ m = p.get("measured") or {}
+ return {"id": p["id"], "name": p["name"], "active": bool(p.get("active")), "created": p.get("created"),
+ "choices": p.get("choices"), "settings": p.get("settings"), "answers": p.get("answers"),
+ "notice": presets.notice(p), "gain_pct": m.get("gain_pct"), "decode_tok_s": m.get("decode_tok_s"),
+ "baseline_decode_tok_s": (p.get("baseline") or {}).get("decode_tok_s"), "tuner": p.get("tuner"),
+ "recheck": p.get("recheck"), "slot": p.get("slot")}
+
+
+def _status(a: argparse.Namespace, machine: bool) -> int:
+ from strata_control import presets
+ _path, cfg = _load_target(a.target)
+ ident = presets.current_identity(cfg)
+ choices = presets.choices_from_config(cfg)
+ slot = presets.slot_key(choices, (ident.get("model") or {}).get("sha256_shard1"))
+ idx = presets._index().get(slot) or {}
+ items = [p for p in presets.list_presets() if p.get("slot") == slot]
+ active = next((p for p in items if p["id"] == idx.get("active")), None)
+ stale = presets.staleness(active, ident) if active else None
+ default = presets.default_name(choices)
+ return _print({"slot": slot, "suggested_name": default, "choices": choices,
+ "active": _summary(active) if active else None, "state": stale["state"] if stale else None,
+ "reasons": stale["reasons"] if stale else [], "presets": [_summary(p) for p in items],
+ "can_undo": bool(idx.get("history")) or bool(active)},
+ machine, (f"Active: '{active['name']}' ({stale['state']})" if active else "No saved tuning for these choices yet."))
+
+
+def _recheck(a: argparse.Namespace, machine: bool) -> int:
+ from strata_control import autotune, presets, tuning
+ from strata_control.tune_session import WorkerSession
+ preset = presets.find(a.preset)
+ _path, cfg = _load_target(a.target)
+ exe = _engine_exe(cfg)
+ ident = presets.current_identity(cfg, exe=exe)
+ stale = presets.staleness(preset, ident)
+ if stale["state"] == "hard":
+ return _fail("this PC changed too much for a re-check (" + "; ".join(stale["reasons"]) + "): tune again with strata tune auto", 5, machine)
+ engine_changed = int((preset.get("identity", {}).get("engine") or {}).get("tuning_epoch") or 0) != \
+ int((ident.get("engine") or {}).get("tuning_epoch") or 0)
+ opts = autotune.Options(use=(preset.get("choices") or {}).get("use", "chat"))
+ ctx = autotune.context_from_config(cfg, engine_backend=(ident.get("engine") or {}).get("backend"), opts=opts,
+ engine_flags=tuning.engine_flag_inventory(Path(exe)))
+ say = (lambda s: None) if machine else (lambda s: print(s, file=sys.stderr, flush=True))
+ workdir = Path(a.work_dir) if a.work_dir else Path(tempfile.mkdtemp(prefix="strata-recheck-"))
+ session = WorkerSession(base_config=cfg, python=sys.executable, serve_dir=_serve_dir(a), workdir=workdir,
+ boot_timeout_s=a.boot_timeout, lock=_lock_factory(a, say), log=say)
+ state: dict[str, Any] = {"state": "running"}
+
+ def progress(p: dict[str, Any]) -> None:
+ state.update(p)
+ _write_status(a.status_file, state)
+ say(p["message"])
+
+ out = autotune.recheck(session, [str(x) for x in cfg.get("args") or []], preset, ctx=ctx, engine_changed=engine_changed,
+ progress=progress)
+ out["identity"] = ident
+ updated = presets.record_recheck(preset["id"], out)
+ state.update({"state": "done", "result": {k: v for k, v in out.items() if k != "identity"}})
+ _write_status(a.status_file, state)
+ human = {"keep": "Still as fast as when it was saved. Kept.",
+ "retune": "Not as fast as before: " + str(out.get("reason")) + "\nYou can tune again with: strata tune auto",
+ "inconclusive": "Could not tell (the PC was busy). Kept; try again later."}[out["verdict"]]
+ return _print({"verdict": out["verdict"], "reason": out.get("reason"), "result": {k: v for k, v in out.items() if k != "identity"},
+ "preset": _summary(updated)}, machine, human)
diff --git a/strata_control/autotune.py b/strata_control/autotune.py
new file mode 100644
index 000000000..b98e76602
--- /dev/null
+++ b/strata_control/autotune.py
@@ -0,0 +1,796 @@
+"""The auto-tuner: find the fastest settings for this PC, for this model, for what the user asked for.
+
+What it does (TUNING-SPEC.md sections 5-6, measured on five machines):
+
+1. **Starts from the user's own configuration** (the "base") and changes one knob at a time (`tune_knobs`). It never starts
+ a candidate at "the first value of every dimension".
+2. Measures with the real worker over HTTP, on the engine's own clock (`tune_session`), the same fixed request set every
+ time. Restart knobs are tried as **interleaved rounds**: every round runs the base and each candidate once, in a
+ rotating order, so machine drift cannot favour one of them. Per-request knobs need no restart and are tried first, in
+ one engine.
+3. Accepts a candidate only if the **median of its per-round ratios** to the base beats the noise: at least +3%, and twice
+ the drift and twice the A/A gap measured on the base runs, in every round (quick) or at least 4 of 5 (thorough
+ confirm), without losing more than 2% elsewhere (prompt speed). A gain the noise can explain is not a gain: the result
+ is then "your current settings are already the fastest" and nothing changes.
+4. Guards before every start: free RAM, free graphics memory, other engines running, the CPU busy with something else.
+ A candidate that does not fit is skipped, never started. A candidate must not use more memory than the base the user
+ asked for (so "leave 20% for my work" is respected). The first crash stops the stage.
+5. Only knobs whose answers are byte-identical (class exact) are chosen on their own; the others need the user's tick.
+
+Progress and time left are reported through a callback; a cancel stops at the next run and keeps nothing half-measured.
+"""
+
+from __future__ import annotations
+
+import math
+import statistics
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from strata_control import tune_knobs, tune_machine
+from strata_control.tune_session import RequestSet, RunResult, Session, StartFailed
+
+MIN_FREE_RAM_MIB = 3584 # 3.5 GiB left for the system at every start (6.5)
+STAGE_GAP_NOISY = 0.04 # an A/A gap above this: the machine is noisy (6.5)
+
+
+class Cancelled(Exception):
+ """The user stopped the tune; what was measured so far is kept in the result."""
+
+
+# --------------------------------------------------------------------------- options and result
+
+@dataclass
+class Options:
+ mode: str = "quick" # quick | thorough
+ goal: str = "speed" # speed | room
+ reserve_mib: int = 0 # graphics memory to leave free (goal room)
+ ram_wish_pct: int = 0 # system memory to leave free, in percent (goal room, e.g. 20)
+ use: str = "chat" # chat | coding
+ allow_placement: bool = False
+ allow_nonrepeatable: bool = False
+ budget_s: float | None = None # quick 20 min, thorough 2 h
+ margin: float = 0.03
+ rounds: int | None = None # quick 2, thorough 3 (screen); confirm 5 in thorough
+ confirm_pairs: int | None = None # thorough: 5
+ per_request: bool = True
+ min_free_ram_mib: int = MIN_FREE_RAM_MIB
+ wait_ram_s: float = 600.0
+ busy_pct: float = 25.0
+ wait_busy_s: float = 300.0
+ check_busy: bool = True
+
+ def resolved(self) -> "Options":
+ o = Options(**self.__dict__)
+ thorough = o.mode == "thorough"
+ o.budget_s = o.budget_s or (7200.0 if thorough else 1200.0)
+ o.rounds = o.rounds or (3 if thorough else 2)
+ o.confirm_pairs = o.confirm_pairs if o.confirm_pairs is not None else (5 if thorough else 0)
+ return o
+
+
+@dataclass
+class ArmReport:
+ id: str
+ label: str
+ settings: dict[str, Any]
+ env: dict[str, Any]
+ answer: str
+ status: str = "pending" # pending | tested | dropped | failed | skipped
+ reason: str = ""
+ runs: list[dict[str, Any]] = field(default_factory=list) # per round: ratios vs that round's base
+ ratio_decode: float | None = None
+ ratio_pp: float | None = None
+ pairs: int = 0
+ faster: int = 0
+ won: bool = False
+
+ def to_dict(self) -> dict[str, Any]:
+ return dict(self.__dict__)
+
+
+@dataclass
+class TuneResult:
+ outcome: str = "default_confirmed" # improved | default_confirmed | inconclusive | base_failed | cancelled
+ message: str = ""
+ mode: str = "quick"
+ seconds: float = 0.0
+ runs: int = 0
+ base: dict[str, Any] = field(default_factory=dict)
+ chosen: dict[str, Any] = field(default_factory=dict)
+ gain_pct: float = 0.0
+ gain_decode_pct: float = 0.0
+ gain_pp_pct: float = 0.0
+ settings: dict[str, Any] = field(default_factory=lambda: {"args": {}, "env": {}, "per_request": {}})
+ answers: dict[str, Any] = field(default_factory=lambda: {"class": "exact", "fields": []})
+ arms: list[dict[str, Any]] = field(default_factory=list)
+ skipped: list[dict[str, str]] = field(default_factory=list)
+ noise: dict[str, Any] = field(default_factory=dict)
+ pairs: int = 0
+ faster_pairs: int = 0
+ per_request: list[dict[str, Any]] = field(default_factory=list)
+ notes: list[str] = field(default_factory=list)
+ classes: list[str] = field(default_factory=list)
+ facts: dict[str, Any] = field(default_factory=dict)
+ trials: list[dict[str, Any]] = field(default_factory=list) # every engine run, for the history store
+
+ def to_dict(self) -> dict[str, Any]:
+ return dict(self.__dict__)
+
+
+# --------------------------------------------------------------------------- pure decision rules
+
+def metric(run: dict[str, Any] | RunResult, use: str) -> float | None:
+ """The number a configuration is judged on (6.1): decode speed for chat; for coding the geometric mean of decode
+ speed and long-prompt speed (the 4K prompt when no long one was measured)."""
+ get = (lambda k: run.get(k)) if isinstance(run, dict) else (lambda k: getattr(run, k, None))
+ d = get("decode_tok_s")
+ if not d:
+ return None
+ if use == "coding":
+ p = get("pp_long_tok_s") or get("pp_tok_s")
+ if p:
+ return math.sqrt(d * p)
+ return float(d)
+
+
+def median_ratio(ratios: list[float]) -> float | None:
+ return statistics.median(ratios) if ratios else None
+
+
+def accept_threshold(margin: float, aa_gap: float, drift: float) -> float:
+ """How far above 1.0 a median ratio has to be: the margin, or twice the noise the base runs showed (6.7 rule 3)."""
+ return 1.0 + max(margin, 2.0 * aa_gap, 2.0 * drift)
+
+
+def is_win(ratios: list[float], pp_ratios: list[float], *, threshold: float, need: int | None = None) -> bool:
+ """A win: the median ratio beats the threshold, enough rounds were faster, and the prompt speed lost at most 2%."""
+ if not ratios:
+ return False
+ need = len(ratios) if need is None else need
+ faster = sum(1 for r in ratios if r > 1.0)
+ if faster < need or statistics.median(ratios) < threshold:
+ return False
+ if pp_ratios and statistics.median(pp_ratios) < 0.98:
+ return False
+ return True
+
+
+def rotate(items: list[Any], r: int) -> list[Any]:
+ k = r % len(items) if items else 0
+ return items[k:] + items[:k]
+
+
+# --------------------------------------------------------------------------- the tuner
+
+class Tuner:
+ def __init__(self, session: Session, base_args: list[str], base_env: dict[str, str], ctx: tune_knobs.Context,
+ options: Options, *, progress: Callable[[dict[str, Any]], None] | None = None,
+ cancel: threading.Event | None = None, history_bad: set[str] | None = None,
+ clock: Callable[[], float] = time.monotonic, sleep: Callable[[float], None] = time.sleep,
+ system: Callable[[], dict[str, Any]] | None = None, total_ram_mib: int | None = None,
+ total_vram_mib: int | None = None, quiet: Callable[[], str | None] | None = None) -> None:
+ self.session = session
+ self.base_args = list(base_args)
+ self.base_env = dict(base_env)
+ self.ctx = ctx
+ self.o = options.resolved()
+ self.progress = progress or (lambda p: None)
+ self.cancel = cancel or threading.Event()
+ self.history_bad = history_bad or set()
+ self.clock = clock
+ self.sleep = sleep
+ self.system = system or session.system
+ self.result = TuneResult(mode=self.o.mode)
+ self.started = 0.0
+ self.run_times: list[float] = []
+ self.planned_runs = 0
+ self.done_runs = 0
+ self.base_runs: list[RunResult] = []
+ self.total_ram = total_ram_mib or (tune_machine.memory().get("total_mib") or 0)
+ self.total_vram = total_vram_mib
+ self.quiet = quiet
+ self.storm = False
+
+ # ---- bookkeeping
+ def _say(self, stage: str, message: str, **extra: Any) -> None:
+ elapsed = self.clock() - self.started
+ avg = statistics.mean(self.run_times) if self.run_times else 150.0
+ remaining = max(0, self.planned_runs - self.done_runs)
+ eta = min(max(0.0, self.o.budget_s - elapsed), remaining * avg) if self.planned_runs else None
+ self.progress({"stage": stage, "message": message, "elapsed_s": round(elapsed), "runs_done": self.done_runs,
+ "runs_planned": self.planned_runs, "eta_s": None if eta is None else round(eta), **extra})
+
+ def _check_cancel(self) -> None:
+ if self.cancel.is_set():
+ raise Cancelled()
+
+ def _over_budget(self, reserve_s: float = 0.0) -> bool:
+ return (self.clock() - self.started) + reserve_s > self.o.budget_s
+
+ def _avg_run(self) -> float:
+ return statistics.mean(self.run_times) if self.run_times else 150.0
+
+ # ---- guards
+ def _wait_for_quiet(self) -> None:
+ """Pause while another engine runs or the CPU is busy with something else (6.5, 6.7 rule 5)."""
+ if not self.o.check_busy:
+ return
+ waited = 0.0
+ while True:
+ why = self.quiet() if self.quiet else self._machine_busy()
+ if not why:
+ return
+ if waited >= self.o.wait_busy_s:
+ self.result.notes.append(f"measured while the machine was busy ({why})")
+ return
+ self._say("waiting", f"Waiting for the PC to be quiet ({why})")
+ self._check_cancel()
+ self.sleep(10.0)
+ waited += 10.0
+
+ def _machine_busy(self) -> str | None:
+ eng = tune_machine.other_engines()
+ if eng:
+ return "another Strata engine is running"
+ busy = tune_machine.cpu_busy_percent(1.0)
+ if busy is not None and busy > self.o.busy_pct:
+ return f"the CPU is {busy:.0f}% busy"
+ return None
+
+ def _ram_guard(self, delta_mib: int, label: str) -> str | None:
+ """None when a start fits; otherwise the plain reason it does not."""
+ waited = 0.0
+ while True:
+ mem = self.system().get("memory", {})
+ avail = mem.get("available_mib")
+ if avail is None:
+ return None # unreadable: the engine's own guard decides
+ need = self.o.min_free_ram_mib + delta_mib
+ base_rss = self.base_runs[0].rss_peak_mib if self.base_runs else None
+ if base_rss:
+ need += base_rss
+ elif self.total_ram:
+ need = max(need, self.o.min_free_ram_mib)
+ if avail >= need:
+ return None
+ if waited >= self.o.wait_ram_s:
+ return (f"not enough free memory to start it safely ({avail / 1024:.1f} GiB free, "
+ f"{need / 1024:.1f} GiB needed)")
+ self._say("waiting", f"Waiting for memory to be freed before trying {label}")
+ self._check_cancel()
+ self.sleep(10.0)
+ waited += 10.0
+
+ # ---- one engine run
+ def _run(self, args: list[str], env: dict[str, str | None], spec: RequestSet, label: str,
+ points: Callable[[Any], None] | None = None) -> RunResult:
+ self._check_cancel()
+ self._wait_for_quiet()
+ t0 = self.clock()
+ try:
+ with self.session.engine(args, env) as eng:
+ res = eng.measure(spec)
+ if points is not None and res.status == "PASS":
+ points(eng)
+ except StartFailed as e:
+ res = RunResult(status=e.status, reason=e.reason)
+ dt = self.clock() - t0
+ self.run_times.append(dt)
+ self.done_runs += 1
+ res.wall_s = round(dt, 1)
+ self.result.runs += 1
+ self.result.trials.append({"label": label, "args": args, "env": env, "status": res.status, "reason": res.reason,
+ "decode_tok_s": res.decode_tok_s, "pp_tok_s": res.pp_tok_s,
+ "rss_peak_mib": res.rss_peak_mib, "load_s": res.load_s, "at": time.time()})
+ return res
+
+ # ---- the whole job
+ def run(self) -> TuneResult:
+ self.started = self.clock()
+ r = self.result
+ try:
+ self._run_stages()
+ except Cancelled:
+ r.outcome, r.message = "cancelled", "Stopped. Your settings were not changed."
+ r.seconds = round(self.clock() - self.started, 1)
+ return r
+
+ def _spec(self) -> RequestSet:
+ long_tokens = 0
+ if self.o.use == "coding" and self.o.mode == "thorough":
+ long_tokens = min(28000, int(0.8 * self.ctx.context_tokens))
+ return RequestSet(warmups=2 if self.o.mode == "thorough" else 1, decodes=3, decode_tokens=200,
+ pp_tokens=4096 if self.ctx.context_tokens >= 6000 else 1024, long_tokens=long_tokens)
+
+ def _run_stages(self) -> None:
+ r, o = self.result, self.o
+ spec = self._spec()
+ self.planned_runs = 6 # corrected once the candidates are known
+ self._say("start", "Checking your PC before the first measurement")
+
+ # ---- stage 1: the base run (the user's configuration, untouched), with the per-request guard in the same engine
+ why = self._ram_guard(0, "your current settings")
+ if why:
+ r.outcome, r.message = "base_failed", "Not tuned: " + why
+ return
+ pr_rows: list[dict[str, Any]] = []
+
+ def per_request_points(eng: Any) -> None:
+ if o.per_request:
+ pr_rows.extend(self._per_request_stage(eng))
+
+ self._say("base", "Measuring your current settings")
+ base1 = self._run(self.base_args, {}, spec, "base", points=per_request_points)
+ self.base_runs.append(base1)
+ if base1.status != "PASS" or not metric(base1, o.use):
+ r.outcome = "base_failed"
+ r.message = "Your current settings could not be measured: " + (base1.reason or base1.status)
+ return
+ r.base = base1.to_dict()
+ r.facts = dict(base1.facts)
+ self.ctx.facts = dict(base1.facts)
+ if base1.vram_used_mib is not None and self.total_vram is None:
+ cards = [g for g in self.system().get("gpus", []) if g.get("vram_total_mib")]
+ self.total_vram = sum(g["vram_total_mib"] for g in cards) if cards else None
+ r.per_request = pr_rows
+ r.classes = tune_knobs.machine_classes(self.ctx)
+
+ # ---- stage 2: plan the candidates for this machine; how many depends on the time chosen
+ planned, skipped = tune_knobs.plan_arms(self.ctx, mode=o.mode, history_bad=self.history_bad)
+ r.skipped = skipped
+ per_arm = o.rounds or 2
+ if o.mode == "thorough":
+ n_arms = len(planned)
+ else:
+ left = int((o.budget_s - (self.clock() - self.started)) / max(1.0, self._avg_run()))
+ fixed = (per_arm - 1) + 1 + 2 # extra base rounds, the final base, a combined-confirm margin
+ n_arms = min(len(planned), max(0, (left - fixed) // per_arm))
+ for p in planned[n_arms:]:
+ skipped.append({"id": p.arm.id, "label": p.arm.label, "reason": "left out to stay inside the time you chose"})
+ planned = planned[:n_arms]
+ arms = [ArmReport(p.arm.id, p.arm.label, dict(p.args), dict(p.env), p.arm.answer) for p in planned]
+ by_id = {a.id: a for a in arms}
+ self.planned_runs = self.done_runs + per_arm * (len(planned) + 1) - 1 + 1 + (o.confirm_pairs or 0) * 2
+ if not planned:
+ self._say("plan", "No other setting is worth trying on this PC")
+
+ # ---- stage 3: interleaved rounds. Every round runs the base and each live candidate once, in a rotating order.
+ round_runs: list[dict[str, RunResult]] = [{} for _ in range(per_arm)]
+ round_runs[0]["base"] = base1
+ alive = list(planned)
+ stop = False
+ for rnd in range(per_arm):
+ if stop or self.storm or (rnd > 0 and not alive):
+ break
+ for item in rotate(["base"] + alive, rnd):
+ self._check_cancel()
+ if self._over_budget(reserve_s=2 * self._avg_run()):
+ r.notes.append("the time you chose ran out before every round finished")
+ stop = True
+ break
+ if item == "base":
+ if rnd == 0:
+ continue # round 1's base is the run above
+ if self._ram_guard(0, "your current settings"):
+ r.notes.append("not enough free memory for another measurement of your current settings; the search stopped")
+ stop = True
+ break
+ self._say("rounds", f"Measuring your current settings again (round {rnd + 1} of {per_arm})")
+ b = self._run(self.base_args, {}, spec, f"base r{rnd + 1}")
+ if b.status != "PASS":
+ r.notes.append("your current settings failed to start a second time; the search stopped")
+ self.storm = stop = True
+ break
+ self.base_runs.append(b)
+ round_runs[rnd]["base"] = b
+ continue
+ p = item
+ rep = by_id[p.arm.id]
+ why = self._ram_guard(p.arm.ram_delta_mib, p.arm.label)
+ if why:
+ rep.status, rep.reason = "skipped", why
+ alive = [x for x in alive if x.arm.id != p.arm.id]
+ continue
+ self._say("rounds", f"Trying: {p.arm.label} (round {rnd + 1} of {per_arm})", arm=p.arm.id)
+ res = self._run(tune_knobs.apply_to_argv(self.base_args, p.args), dict(p.env), spec, p.arm.id)
+ if res.status != "PASS":
+ rep.status, rep.reason = "failed", f"{res.status}: {res.reason}"
+ alive = [x for x in alive if x.arm.id != p.arm.id]
+ if res.status == "OOM":
+ self.storm = stop = True
+ r.notes.append("an engine ran out of memory; the search stopped (nothing was retried)")
+ break
+ continue
+ over = self._memory_overrun(res, base1)
+ if over:
+ rep.status, rep.reason = "failed", over
+ alive = [x for x in alive if x.arm.id != p.arm.id]
+ continue
+ round_runs[rnd][p.arm.id] = res
+ # a candidate that lost by more than the margin against its own round's base is dropped from later rounds
+ for p in list(alive):
+ b, c = round_runs[rnd].get("base"), round_runs[rnd].get(p.arm.id)
+ m_b, m_c = (metric(b, o.use) if b else None), (metric(c, o.use) if c else None)
+ if m_b and m_c and m_c / m_b < 1.0 - o.margin:
+ by_id[p.arm.id].status = "dropped"
+ by_id[p.arm.id].reason = f"slower by {100 * (1 - m_c / m_b):.1f}% in round {rnd + 1}"
+ alive = [x for x in alive if x.arm.id != p.arm.id]
+ data: dict[str, list[tuple[RunResult, RunResult]]] = {
+ a.id: [(rr["base"], rr[a.id]) for rr in round_runs if a.id in rr and "base" in rr] for a in arms}
+
+ # ---- noise: the A/A gap between base runs, the drift against a final base run
+ end_base: RunResult | None = None
+ ran_any = any(len(v) for v in data.values())
+ if not self.storm and not self.cancel.is_set() and ran_any and not self._over_budget() and not self._ram_guard(0, "your current settings"):
+ self._say("drift", "Measuring your current settings once more to check the PC did not drift")
+ end_base = self._run(self.base_args, {}, spec, "base end")
+ if end_base.status == "PASS":
+ self.base_runs.append(end_base)
+ mb = [metric(b, o.use) for b in self.base_runs if metric(b, o.use)]
+ aa = abs(mb[1] / mb[0] - 1.0) if len(mb) >= 2 else 0.0
+ drift = abs(mb[-1] / mb[0] - 1.0) if len(mb) >= 3 else (aa if len(mb) == 2 else 0.0)
+ spread = (max(mb) / min(mb) - 1.0) if len(mb) >= 2 else 0.0
+ r.noise = {"aa_gap": round(aa, 4), "drift": round(drift, 4), "spread": round(spread, 4),
+ "base_runs": [round(x, 2) for x in mb], "noisy": spread > STAGE_GAP_NOISY}
+ threshold = accept_threshold(o.margin, aa, drift)
+
+ # ---- evaluate the candidates
+ winners: list[ArmReport] = []
+ for p in planned:
+ rep = by_id[p.arm.id]
+ rows = data[p.arm.id]
+ if rep.status in ("failed", "skipped") or not rows:
+ continue
+ ratios, pps = [], []
+ for b, c in rows:
+ mc, mbb = metric(c, o.use), metric(b, o.use)
+ if mc and mbb:
+ ratios.append(mc / mbb)
+ if c.pp_tok_s and b.pp_tok_s:
+ pps.append(c.pp_tok_s / b.pp_tok_s)
+ rep.pairs = len(ratios)
+ rep.faster = sum(1 for x in ratios if x > 1.0)
+ rep.ratio_decode = round(statistics.median(ratios), 4) if ratios else None
+ rep.ratio_pp = round(statistics.median(pps), 4) if pps else None
+ rep.runs = [{"ratio": round(x, 4)} for x in ratios]
+ if rep.status == "dropped":
+ continue
+ rep.status = "tested"
+ if len(ratios) >= per_arm and is_win(ratios, pps, threshold=threshold):
+ rep.won = True
+ winners.append(rep)
+ r.arms = [a.to_dict() for a in arms]
+
+ if r.noise["noisy"] and not winners:
+ r.notes.append(f"the PC was noisy ({spread * 100:.1f}% between identical runs)")
+
+ # ---- stage 4: stack the winners, then (thorough) confirm against the base with more pairs
+ chosen_args: dict[str, Any] = {}
+ chosen_env: dict[str, str | None] = {}
+ final_pairs: list[tuple[RunResult, RunResult]] = []
+ if winners:
+ winners.sort(key=lambda a: a.ratio_decode or 0.0, reverse=True)
+ incumbent = [winners[0]]
+ for extra in winners[1:]:
+ conflict = set(extra.settings) & {k for w in incumbent for k in w.settings}
+ if not conflict:
+ incumbent.append(extra)
+ for w in incumbent:
+ chosen_args.update(w.settings)
+ chosen_env.update(w.env)
+ need_confirm = len(incumbent) > 1 or (o.confirm_pairs or 0) > 0
+ if need_confirm and not self._over_budget(reserve_s=2 * self._avg_run()):
+ n = o.confirm_pairs or 2
+ self._say("confirm", "Confirming the combined result against your current settings")
+ final_pairs = self._confirm(chosen_args, chosen_env, spec, n)
+ ratios = [metric(c, o.use) / metric(b, o.use) for b, c in final_pairs if metric(c, o.use) and metric(b, o.use)]
+ pps = [c.pp_tok_s / b.pp_tok_s for b, c in final_pairs if c.pp_tok_s and b.pp_tok_s]
+ need = max(2, int(math.ceil(0.8 * len(ratios)))) if len(ratios) >= 5 else len(ratios)
+ if not (ratios and is_win(ratios, pps, threshold=threshold, need=need)):
+ # the stack did not hold; fall back to the best single winner, which already won its own pairs
+ if len(incumbent) > 1:
+ r.notes.append("the combination did not beat the best single change; keeping the best single change")
+ best = incumbent[0]
+ chosen_args, chosen_env = dict(best.settings), dict(best.env)
+ final_pairs = [(b, c) for b, c in data[best.id]]
+ else:
+ winners, chosen_args, chosen_env, final_pairs = [], {}, {}, []
+ r.notes.append("the gain did not hold up in the confirmation, so nothing was changed")
+ else:
+ pass
+ else:
+ best = incumbent[0]
+ chosen_args, chosen_env = dict(best.settings), dict(best.env)
+ final_pairs = list(data[best.id])
+ if not final_pairs and winners:
+ final_pairs = list(data[winners[0].id])
+
+ # ---- per-request winners (found in the base engine): keep only the ones that won every round
+ per_request_chosen = {row["key"]: row["value"] for row in r.per_request if row.get("won")}
+
+ # ---- result
+ if end_base is not None and end_base.status == "PASS" and drift > 0.03 and winners:
+ gain_guess = statistics.median([metric(c, o.use) / metric(b, o.use) for b, c in final_pairs]) - 1.0 if final_pairs else 0.0
+ if gain_guess < 2 * drift:
+ chosen_args, chosen_env, winners, final_pairs = {}, {}, [], []
+ per_request_chosen = {}
+ r.outcome = "inconclusive"
+ r.message = ("The PC changed speed while measuring (about %.0f%%), more than the gain found, so nothing "
+ "was changed. Try again when nothing else is running." % (drift * 100))
+ if r.outcome != "inconclusive":
+ if chosen_args or chosen_env or per_request_chosen:
+ r.outcome = "improved"
+ elif r.noise["noisy"] and (spread > 2 * STAGE_GAP_NOISY):
+ r.outcome = "inconclusive"
+ r.message = "The PC was too noisy to tell settings apart, so nothing was changed. Try again when it is idle."
+ else:
+ r.outcome = "default_confirmed"
+ r.message = "Your current settings are already the fastest we found. Nothing was changed."
+ r.settings = {"args": chosen_args, "env": chosen_env, "per_request": per_request_chosen}
+ cls, fields = "exact", []
+ for rep in arms:
+ if rep.won and any(k in chosen_args for k in rep.settings) or (rep.won and any(k in chosen_env for k in rep.env)):
+ if tune_knobs.ANSWER_ORDER.index(rep.answer) > tune_knobs.ANSWER_ORDER.index(cls):
+ cls = rep.answer
+ if rep.answer != "exact":
+ fields += list(rep.settings) + list(rep.env)
+ for key in per_request_chosen:
+ for row in tune_knobs.PER_REQUEST:
+ if row["key"] == key and tune_knobs.ANSWER_ORDER.index(row["answer"]) > tune_knobs.ANSWER_ORDER.index(cls):
+ cls = row["answer"]
+ if row["key"] == key and row["answer"] != "exact":
+ fields.append(key)
+ r.answers = {"class": cls, "fields": sorted(set(fields))}
+ if final_pairs:
+ ratios = [metric(c, o.use) / metric(b, o.use) for b, c in final_pairs if metric(c, o.use) and metric(b, o.use)]
+ pps = [c.pp_tok_s / b.pp_tok_s for b, c in final_pairs if c.pp_tok_s and b.pp_tok_s]
+ r.pairs = len(ratios)
+ r.faster_pairs = sum(1 for x in ratios if x > 1.0)
+ r.gain_pct = round(100 * (statistics.median(ratios) - 1.0), 1) if ratios else 0.0
+ r.gain_pp_pct = round(100 * (statistics.median(pps) - 1.0), 1) if pps else 0.0
+ dec = [c.decode_tok_s / b.decode_tok_s for b, c in final_pairs if c.decode_tok_s and b.decode_tok_s]
+ r.gain_decode_pct = round(100 * (statistics.median(dec) - 1.0), 1) if dec else 0.0
+ c_runs = [c for _, c in final_pairs]
+ r.chosen = {"decode_tok_s": round(statistics.median([c.decode_tok_s for c in c_runs if c.decode_tok_s]), 2)
+ if any(c.decode_tok_s for c in c_runs) else None,
+ "pp_tok_s": round(statistics.median([c.pp_tok_s for c in c_runs if c.pp_tok_s]), 1)
+ if any(c.pp_tok_s for c in c_runs) else None,
+ "rss_peak_mib": max([c.rss_peak_mib for c in c_runs if c.rss_peak_mib] or [None]) if any(c.rss_peak_mib for c in c_runs) else None,
+ "vram_used_mib": max([c.vram_used_mib for c in c_runs if c.vram_used_mib] or [None]) if any(c.vram_used_mib for c in c_runs) else None}
+ elif r.outcome == "improved" and per_request_chosen:
+ r.gain_pct = r.gain_decode_pct = round(100 * (statistics.median(
+ [row["ratio"] for row in r.per_request if row.get("won")]) - 1.0), 1)
+ r.chosen = dict(r.base)
+ else:
+ r.chosen = {k: r.base.get(k) for k in ("decode_tok_s", "pp_tok_s", "rss_peak_mib", "vram_used_mib")}
+ if r.outcome == "improved":
+ r.message = "+%.0f%% faster answers" % r.gain_pct if r.gain_pct >= 0.5 else "slightly faster"
+ self._say("done", r.message or "Done")
+
+ # ---- helpers
+ def _memory_overrun(self, res: RunResult, base: RunResult) -> str | None:
+ """A candidate that takes more memory than the base the user asked for is not a candidate (their wish, 20% left
+ for work, is a promise about memory)."""
+ if res.rss_peak_mib and base.rss_peak_mib and res.rss_peak_mib > base.rss_peak_mib * 1.05 + 512 and self.o.goal == "room":
+ return "it needs more memory than your current settings, which would eat into the memory you wanted left free"
+ if res.min_avail_mib is not None and res.min_avail_mib < self.o.min_free_ram_mib:
+ return "it left the PC with too little free memory"
+ if self.o.goal == "room" and self.o.ram_wish_pct and self.total_ram and res.min_avail_mib is not None and \
+ base.min_avail_mib is not None:
+ if res.min_avail_mib < base.min_avail_mib - max(512, 0.03 * self.total_ram):
+ return "it left less memory free than your current settings"
+ if self.o.goal == "room" and res.vram_used_mib is not None and base.vram_used_mib is not None and \
+ res.vram_used_mib > base.vram_used_mib + 256:
+ return "it uses more graphics memory than your current settings"
+ if self.o.goal == "room" and self.o.reserve_mib and self.total_vram and res.vram_used_mib is not None and \
+ base.vram_used_mib is not None and self.total_vram - base.vram_used_mib >= self.o.reserve_mib - 128 and \
+ self.total_vram - res.vram_used_mib < self.o.reserve_mib - 128:
+ return "it would not leave the graphics memory you wanted free"
+ return None
+
+ def _confirm(self, args: dict[str, Any], env: dict[str, str | None], spec: RequestSet, pairs: int) -> list[tuple[RunResult, RunResult]]:
+ """Interleaved pairs of the combined settings against the base (the order alternates)."""
+ out: list[tuple[RunResult, RunResult]] = []
+ cand_args = tune_knobs.apply_to_argv(self.base_args, args)
+ for i in range(pairs):
+ self._check_cancel()
+ if self._over_budget(reserve_s=2 * self._avg_run()):
+ self.result.notes.append("confirmation stopped early: the time you chose ran out")
+ break
+ first = "cand" if i % 2 == 0 else "base"
+ runs: dict[str, RunResult] = {}
+ for who in (first, "base" if first == "cand" else "cand"):
+ self._say("confirm", f"Confirming (pair {i + 1} of {pairs})")
+ runs[who] = self._run(cand_args if who == "cand" else self.base_args, env if who == "cand" else {}, spec,
+ f"confirm {who} {i + 1}")
+ if runs["cand"].status == "PASS" and runs["base"].status == "PASS":
+ if self.o.use and metric(runs["cand"], self.o.use) and metric(runs["base"], self.o.use):
+ out.append((runs["base"], runs["cand"]))
+ self.base_runs.append(runs["base"])
+ else:
+ break
+ return out
+
+ def _per_request_stage(self, eng: Any) -> list[dict[str, Any]]:
+ """Per-request settings against the engine's own choice, in this one engine, 3 interleaved rounds (6.3 step 2).
+
+ A value is kept only if it beat the default by the margin in every round. No restart is needed, so these are
+ tried before any restart (5). One value per key can win."""
+ points: list[tuple[str, Any]] = []
+ for spec in tune_knobs.PER_REQUEST:
+ if self.ctx.backend not in spec["backends"]:
+ continue
+ if spec["answer"] != "exact" and not tune_knobs.allowed(spec["answer"], self.ctx):
+ continue
+ for v in spec["values"]:
+ points.append((spec["key"], v))
+ if not points:
+ return []
+ rounds = 3
+ default: dict[int, float] = {}
+ vals: dict[tuple[str, Any], dict[int, float]] = {pt: {} for pt in points}
+ self._say("per_request", "Trying settings that need no restart")
+ for rnd in range(rounds):
+ for item in rotate([None] + points, rnd):
+ self._check_cancel()
+ if item is None:
+ d = eng.decode_once(None, 200)
+ if d:
+ default[rnd] = d
+ else:
+ d = eng.decode_once({item[0]: item[1]}, 200)
+ if d:
+ vals[item][rnd] = d
+ rows: list[dict[str, Any]] = []
+ for pt in points:
+ ratios = [vals[pt][i] / default[i] for i in range(rounds) if i in vals[pt] and i in default]
+ won = len(ratios) == rounds and all(x >= 1.0 + self.o.margin for x in ratios)
+ rows.append({"key": pt[0], "value": pt[1], "ratios": [round(x, 4) for x in ratios],
+ "ratio": round(statistics.median(ratios), 4) if ratios else None, "won": won})
+ best: dict[str, dict[str, Any]] = {}
+ for row in rows:
+ if row["won"] and (row["key"] not in best or row["ratio"] > best[row["key"]]["ratio"]):
+ best[row["key"]] = row
+ for row in rows:
+ row["won"] = best.get(row["key"]) is row
+ return rows
+
+
+# --------------------------------------------------------------------------- building a tuner from a run configuration
+
+def split_args(argv: list[str]) -> list[str]:
+ return [str(a) for a in argv]
+
+
+def detect_family(args: list[str]) -> str:
+ for i, a in enumerate(args):
+ if a == "--mtp" and i + 1 < len(args):
+ return "qwen36" if str(args[i + 1]).isdigit() else "flash-next"
+ if "--pack" in args or "--native" in args:
+ return "flash-next"
+ return "flash-next"
+
+
+def model_gib_of(args: list[str]) -> float:
+ """Total size of the model files a configuration names, shards included."""
+ from pathlib import Path
+ import re
+ total = 0
+ seen: set[str] = set()
+ for i, a in enumerate(args):
+ if a in ("--native", "--model", "--ple-gguf") and i + 1 < len(args):
+ p = Path(str(args[i + 1]))
+ if not p.is_file() or str(p) in seen:
+ continue
+ m = re.match(r"(.*)-(\d{5})-of-(\d{5})\.gguf$", p.name)
+ group = sorted(p.parent.glob(f"{m.group(1)}-*-of-{m.group(3)}.gguf")) if m else [p]
+ for f in group:
+ if str(f) not in seen:
+ seen.add(str(f))
+ total += f.stat().st_size
+ return round(total / 1024 ** 3, 1)
+
+
+def context_from_config(cfg: dict[str, Any], *, engine_backend: str | None, opts: Options,
+ engine_flags: list[str] | None = None, system: dict[str, Any] | None = None,
+ family: str | None = None) -> tune_knobs.Context:
+ args = split_args(cfg.get("args") or [])
+ system = system or {"memory": tune_machine.memory(), "gpus": tune_machine.gpus(), "cpu": tune_machine.cpu()}
+ gpu_cfg = cfg.get("gpu")
+ wanted = gpu_cfg if isinstance(gpu_cfg, list) else ([gpu_cfg] if isinstance(gpu_cfg, int) else None)
+ cards = system.get("gpus") or []
+ used = [g for g in cards if not wanted or g.get("index") in wanted] or cards
+ ctx_tokens = 32768
+ for i, a in enumerate(args):
+ if a == "--max-context" and i + 1 < len(args) and str(args[i + 1]).isdigit():
+ ctx_tokens = int(args[i + 1])
+ mem = system.get("memory") or {}
+ cpu = system.get("cpu") or {}
+ backend = engine_backend or ("cuda" if any(g.get("vendor") == "nvidia" for g in cards) else
+ "hip" if any(g.get("vendor") == "amd" for g in cards) else "cpu")
+ arch = None
+ return tune_knobs.Context(
+ backend=backend, family=family or detect_family(args), gpu_count=max(1, len(used)),
+ vram_mib=min((g["vram_total_mib"] for g in used if g.get("vram_total_mib")), default=0),
+ ram_gib=int((mem.get("total_mib") or 0) // 1024), model_gib=model_gib_of(args),
+ hybrid_cpu=bool(cpu.get("hybrid")), logical_threads=int(cpu.get("logical") or 0), arch=arch,
+ context_tokens=ctx_tokens, goal=opts.goal, use=opts.use, allow_placement=opts.allow_placement,
+ allow_nonrepeatable=opts.allow_nonrepeatable, engine_flags=engine_flags, base_args=args)
+
+
+# --------------------------------------------------------------------------- the short "still good?" re-check (8.3)
+
+def recheck(session: Session, base_args: list[str], preset: dict[str, Any], *, ctx: tune_knobs.Context,
+ engine_changed: bool = False, progress: Callable[[dict[str, Any]], None] | None = None,
+ cancel: threading.Event | None = None, clock: Callable[[], float] = time.monotonic) -> dict[str, Any]:
+ """Is a saved preset still as fast as when it was made? One restart with the preset's settings and 30-45 s of requests.
+
+ Pass rule (against the stored numbers, not a fresh baseline): decode and the 4K prompt at least 95% of what was stored,
+ memory within the stored +5%. A failing prompt rate is measured once more with a second start before it counts (the
+ prompt rate of some cards is bimodal between engine starts). When the engine changed in a way that can move speed
+ (``tuning_epoch``) a baseline start is added and the preset must be at least as fast as doing nothing.
+ The result is ``keep``, ``retune`` (suggested, never forced) or ``inconclusive`` (noise or a competing process)."""
+ progress = progress or (lambda p: None)
+ cancel = cancel or threading.Event()
+ t0 = clock()
+ s = preset.get("settings") or {}
+ stored = preset.get("measured") or {}
+ args = tune_knobs.apply_to_argv(base_args, s.get("args") or {})
+ env = dict(s.get("env") or {})
+ spec = RequestSet(warmups=1, decodes=3, decode_tokens=200, pp_tokens=4096 if ctx.context_tokens >= 6000 else 1024, long_tokens=0)
+ if ctx.backend == "sycl":
+ spec.pp_tokens = 0 # the A750's 4K prompt takes a minute: decode only (8.3)
+ out: dict[str, Any] = {"verdict": "inconclusive", "request_set": RECHECK_SET_NAME, "notes": []}
+
+ def one(a: list[str], e: dict[str, str | None], label: str) -> RunResult:
+ if cancel.is_set():
+ raise Cancelled()
+ progress({"stage": "recheck", "message": label, "elapsed_s": round(clock() - t0)})
+ try:
+ with session.engine(a, e) as eng:
+ r = eng.measure(spec)
+ except StartFailed as ex:
+ return RunResult(status=ex.status, reason=ex.reason)
+ return r
+
+ try:
+ run = one(args, env, "Checking your saved settings")
+ if run.status != "PASS":
+ out.update(verdict="retune", reason=f"the saved settings did not start now: {run.status} {run.reason}")
+ out["seconds"] = round(clock() - t0, 1)
+ return out
+ out["measured"] = {"decode_tok_s": run.decode_tok_s, "pp4k_tok_s": run.pp_tok_s, "rss_peak_mib": run.rss_peak_mib,
+ "vram_peak_mib": run.vram_used_mib}
+ sd, sp = stored.get("decode_tok_s"), stored.get("pp4k_tok_s")
+ problems: list[str] = []
+ if sd and run.decode_tok_s and run.decode_tok_s < 0.95 * sd:
+ problems.append(f"answers are {100 * (1 - run.decode_tok_s / sd):.0f}% slower than when it was saved")
+ if sp and run.pp_tok_s and run.pp_tok_s < 0.95 * sp:
+ again = one(args, env, "Checking prompt speed once more")
+ if again.status == "PASS" and again.pp_tok_s and again.pp_tok_s >= 0.95 * sp:
+ out["notes"].append("prompt speed varied between starts; the second start was fine")
+ else:
+ problems.append("long prompts are slower than when it was saved")
+ for key, got in (("rss_peak_mib", run.rss_peak_mib), ("vram_peak_mib", run.vram_used_mib)):
+ ref = stored.get(key)
+ if ref and got and got > 1.05 * ref:
+ problems.append("it now uses more memory than when it was saved")
+ break
+ if engine_changed:
+ base = one(base_args, {}, "Checking against the standard settings after the engine update")
+ if base.status == "PASS" and base.decode_tok_s and run.decode_tok_s and run.decode_tok_s < base.decode_tok_s:
+ problems.append("the standard settings are now faster than the saved ones")
+ out["baseline"] = {"decode_tok_s": base.decode_tok_s, "pp4k_tok_s": base.pp_tok_s}
+ out["problems"] = problems
+ out["verdict"] = "retune" if problems else "keep"
+ out["reason"] = ("Still as fast as when it was saved." if not problems else "; ".join(problems))
+ except Cancelled:
+ out.update(verdict="inconclusive", reason="Stopped.")
+ out["seconds"] = round(clock() - t0, 1)
+ return out
+
+
+RECHECK_SET_NAME = "recheck/1"
diff --git a/strata_control/presets.py b/strata_control/presets.py
new file mode 100644
index 000000000..f99e5f7be
--- /dev/null
+++ b/strata_control/presets.py
@@ -0,0 +1,517 @@
+"""Saved tuning presets: tune once, keep it.
+
+One store for the Terminal and the desktop app: a folder of small JSON files (``presets/`` beside the profiles), so tuning in
+one place covers the other. A preset holds
+
+* the settings the tuner found (``settings``: engine arguments, environment, per-request defaults),
+* what was measured (speeds and the baseline they were compared to),
+* the user's choices it was made for (model, context, KV format, "leave room" or "full performance", chat or coding), and
+* the identity it is valid for: the PC (graphics card and driver, memory, processor), the engine build and the model file.
+
+On every start the **active** preset for the model's choices is applied with no measurement (`overlay`, called by the
+server before it starts the engine). When the identity changed the preset says how much: a new graphics card or model file
+is a *hard* change (settings may not even start, so they are not applied on their own); a new driver or an engine build
+with a new ``tuning_epoch`` is a *soft* change (the preset still applies, and a 2-minute re-check is offered, never forced).
+
+Several named presets per model; activating one keeps the one it replaced, so **undo** restores it exactly. Nothing here
+starts an engine or changes anything but its own folder.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tempfile
+import time
+import uuid
+from pathlib import Path
+from typing import Any
+
+from strata_control import tune_knobs, tune_machine
+
+SCHEMA = "strata.preset/1"
+RECHECK_SET = "recheck/1"
+DEFAULT_LAST_OK_DAYS = 90
+
+
+class PresetError(ValueError):
+ """A preset is missing or invalid; the message is for the user."""
+
+
+# --------------------------------------------------------------------------- the folder
+
+def preset_dir() -> Path:
+ explicit = os.environ.get("STRATA_PRESET_DIR")
+ if explicit:
+ return Path(explicit).expanduser()
+ from strata_control import profiles
+ return profiles.profile_dir().parent / "presets"
+
+
+def _atomic(path: Path, payload: bytes) -> None:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ fd, tmp = tempfile.mkstemp(prefix=f".{path.name}-", suffix=".tmp", dir=path.parent)
+ try:
+ with os.fdopen(fd, "wb") as fh:
+ fh.write(payload)
+ fh.flush()
+ os.fsync(fh.fileno())
+ os.replace(tmp, path)
+ finally:
+ if os.path.exists(tmp):
+ os.unlink(tmp)
+
+
+def _write_json(path: Path, obj: Any) -> None:
+ _atomic(path, (json.dumps(obj, indent=2, ensure_ascii=False, sort_keys=True) + "\n").encode("utf-8"))
+
+
+def _read_json(path: Path, default: Any) -> Any:
+ try:
+ return json.loads(path.read_text(encoding="utf-8-sig"))
+ except (OSError, ValueError):
+ return default
+
+
+def _path(pid: str) -> Path:
+ if not re.fullmatch(r"[0-9a-f]{32}", pid):
+ raise PresetError("that is not a preset id")
+ return preset_dir() / f"{pid}.json"
+
+
+# --------------------------------------------------------------------------- the choices a preset belongs to
+
+_QUANT = re.compile(r"(UD-Q\d_K_\w+|IQ\d_[A-Z]+|Q\d_K_[A-Z]+|Q\d_K|Q\d_\d|Q\d|BF16|F16)", re.I)
+
+
+def choices_from_config(cfg: dict[str, Any], *, use: str = "chat") -> dict[str, Any]:
+ """What the user chose, read from a run configuration: model, context, KV format, pictures, and whether they asked to
+ leave room for other work. The slot a preset is active in is made from these."""
+ args = [str(a) for a in cfg.get("args") or []]
+
+ def val(flag: str) -> str | None:
+ for i, a in enumerate(args):
+ if a == flag and i + 1 < len(args) and not args[i + 1].startswith("--"):
+ return args[i + 1]
+ return None
+
+ ctx = val("--max-context")
+ native = val("--native") or val("--model") or ""
+ quant = (_QUANT.search(Path(native).name) or _QUANT.search(str(cfg.get("model_name") or "")))
+ profile = cfg.get("ui_resource_profile")
+ reserve = cfg.get("vram_reserve_mib")
+ room = profile == "work"
+ return {
+ "model": str(cfg.get("model_name") or Path(native).stem or "model"),
+ "quant": quant.group(1).upper() if quant else None,
+ "model_file": native,
+ "context": int(ctx) if ctx and ctx.isdigit() else None,
+ "kv": val("--kv") or "int8",
+ "vision": bool(cfg.get("ui_vision_enabled")) or "--vision" in args,
+ "goal": "room" if room else "speed",
+ "reserve_mib": int(reserve) if isinstance(reserve, (int, float)) else 0,
+ "use": use,
+ "family": "qwen36" if (val("--mtp") or "").isdigit() else "flash-next",
+ }
+
+
+def default_name(choices: dict[str, Any]) -> str:
+ ctx = choices.get("context")
+ ctx_s = f"{ctx // 1024}K" if ctx else "?"
+ label = choices.get("quant") or choices.get("model") or "Model"
+ wish = "Work" if choices.get("goal") == "room" else "Full speed"
+ return f"{label} {ctx_s} – {wish}"
+
+
+def slot_key(choices: dict[str, Any], model_digest: str | None) -> str:
+ """Presets of the same model file, context, KV format, pictures and wish compete for the active place."""
+ return tune_machine.stable_hash({"m": model_digest, "ctx": choices.get("context"), "kv": choices.get("kv"),
+ "v": bool(choices.get("vision")), "g": choices.get("goal")})
+
+
+# --------------------------------------------------------------------------- identity and staleness
+
+def current_identity(cfg: dict[str, Any], *, exe: str | None = None, pcie: str | None = None) -> dict[str, Any]:
+ """The identity this PC, engine and model file have now."""
+ from strata_control import engine_component
+ args = [str(a) for a in cfg.get("args") or []]
+ files = [a for a in args if a.lower().endswith(".gguf")]
+ native = None
+ for i, a in enumerate(args):
+ if a == "--native" and i + 1 < len(args):
+ native = args[i + 1]
+ first = native or (files[0] if files else None)
+ engine_path = exe
+ if engine_path is None:
+ try:
+ ref = cfg.get("exe")
+ engine_path = engine_component.expand(ref, cfg, full=False) if ref else None
+ except Exception: # noqa: BLE001
+ engine_path = cfg.get("exe")
+ return {"hardware": tune_machine.hardware_identity(pcie=pcie),
+ "engine": tune_machine.engine_identity(engine_path) if engine_path else {},
+ "model": tune_machine.model_identity([first]) if first and Path(first).is_file() else {}}
+
+
+def staleness(preset: dict[str, Any], now: dict[str, Any], *, today: float | None = None) -> dict[str, Any]:
+ """Compare a preset's identity with the current one: ``state`` is fresh, soft (re-check offered) or hard (settings
+ are not applied on their own; re-tune offered). ``reasons`` are plain words."""
+ old = preset.get("identity") or {}
+ hard: list[str] = []
+ soft: list[str] = []
+ oh, nh = (old.get("hardware") or {}).get("hard") or {}, (now.get("hardware") or {}).get("hard") or {}
+ if oh and nh:
+ if oh.get("gpus") != nh.get("gpus"):
+ hard.append("the graphics card changed")
+ if oh.get("cpu") != nh.get("cpu") or oh.get("logical") != nh.get("logical"):
+ hard.append("the processor changed")
+ a, b = oh.get("ram_gib"), nh.get("ram_gib")
+ if a and b and abs(a - b) / max(a, b) > 0.10:
+ hard.append("the amount of memory changed")
+ if oh.get("pcie") and nh.get("pcie") and oh["pcie"] != nh["pcie"]:
+ hard.append("the PCIe link changed")
+ om, nm = (old.get("model") or {}), (now.get("model") or {})
+ if om.get("sha256_shard1") and nm.get("sha256_shard1") and om["sha256_shard1"] != nm["sha256_shard1"]:
+ hard.append("the model file changed")
+ oe, ne = (old.get("engine") or {}), (now.get("engine") or {})
+ if oe.get("backend") and ne.get("backend") and oe["backend"] != ne["backend"]:
+ hard.append("the engine's graphics backend changed")
+ if oe and ne and int(oe.get("tuning_epoch") or 0) != int(ne.get("tuning_epoch") or 0):
+ soft.append("the engine was updated in a way that can change speed")
+ elif oe.get("version") and ne.get("version") and oe["version"] != ne["version"] and \
+ oe.get("sha256") and ne.get("sha256") and oe["sha256"] != ne["sha256"] and \
+ int(oe.get("tuning_epoch") or 0) != int(ne.get("tuning_epoch") or 0):
+ soft.append("the engine was updated")
+ os_, ns = (old.get("hardware") or {}).get("soft") or {}, (now.get("hardware") or {}).get("soft") or {}
+ if os_.get("driver") and ns.get("driver") and os_["driver"] != ns["driver"]:
+ soft.append("the graphics driver changed")
+ last_ok = ((preset.get("recheck") or {}).get("last_ok_epoch")) or preset.get("created_epoch")
+ if last_ok and (today or time.time()) - last_ok > DEFAULT_LAST_OK_DAYS * 86400:
+ soft.append("it has not been checked for a while")
+ if hard:
+ return {"state": "hard", "reasons": hard + soft}
+ if soft:
+ return {"state": "soft", "reasons": soft}
+ return {"state": "fresh", "reasons": []}
+
+
+# --------------------------------------------------------------------------- the store
+
+def _index() -> dict[str, Any]:
+ idx = _read_json(preset_dir() / "active.json", {})
+ return idx if isinstance(idx, dict) else {}
+
+
+def _save_index(idx: dict[str, Any]) -> None:
+ _write_json(preset_dir() / "active.json", idx)
+
+
+def load(pid: str) -> dict[str, Any]:
+ data = _read_json(_path(pid), None)
+ if not isinstance(data, dict) or data.get("schema") != SCHEMA:
+ raise PresetError("that preset does not exist")
+ return data
+
+
+def find(ref: str) -> dict[str, Any]:
+ """A preset by id, id prefix or exact name (case-insensitive); an ambiguous name is refused."""
+ items = list_presets()
+ exact = [p for p in items if p["id"] == ref]
+ if exact:
+ return exact[0]
+ by_prefix = [p for p in items if len(ref) >= 4 and p["id"].startswith(ref)]
+ by_name = [p for p in items if p["name"].lower() == ref.lower()]
+ found = by_name or by_prefix
+ if not found:
+ raise PresetError(f"no preset called '{ref}'")
+ if len(found) > 1:
+ raise PresetError(f"'{ref}' matches {len(found)} presets; use the id")
+ return found[0]
+
+
+def list_presets(*, model: str | None = None) -> list[dict[str, Any]]:
+ out: list[dict[str, Any]] = []
+ d = preset_dir()
+ if not d.is_dir():
+ return out
+ idx = _index()
+ active_ids = {v.get("active") for v in idx.values() if isinstance(v, dict)}
+ for f in sorted(d.glob("*.json")):
+ if f.name == "active.json":
+ continue
+ data = _read_json(f, None)
+ if not isinstance(data, dict) or data.get("schema") != SCHEMA:
+ continue
+ if model and model.lower() not in json.dumps(data.get("choices", {})).lower():
+ continue
+ data["active"] = data.get("id") in active_ids
+ out.append(data)
+ out.sort(key=lambda p: p.get("created_epoch", 0), reverse=True)
+ return out
+
+
+def _name_taken(name: str, exclude: str | None = None) -> bool:
+ return any(p["name"].lower() == name.lower() and p["id"] != exclude for p in list_presets())
+
+
+def _unique_name(name: str) -> str:
+ if not _name_taken(name):
+ return name
+ n = 2
+ while _name_taken(f"{name} ({n})"):
+ n += 1
+ return f"{name} ({n})"
+
+
+def create(result: dict[str, Any], *, choices: dict[str, Any], identity: dict[str, Any], name: str | None = None,
+ mode: str = "quick", activate: bool = True, base_args: dict[str, Any] | None = None) -> dict[str, Any]:
+ """Save a tune result as a named preset (active at once unless ``activate`` is False)."""
+ settings = result.get("settings") or {"args": {}, "env": {}, "per_request": {}}
+ problems = tune_knobs.check_setting(settings.get("args") or {}, settings.get("env") or {},
+ tune_knobs.Context(context_tokens=choices.get("context") or 32768,
+ family=choices.get("family") or "flash-next"))
+ if problems:
+ raise PresetError("these settings are outside the safe rules and cannot be saved: " + "; ".join(problems))
+ base = result.get("base") or {}
+ chosen = result.get("chosen") or {}
+ pid = uuid.uuid4().hex
+ now = time.time()
+ digest = (identity.get("model") or {}).get("sha256_shard1")
+ preset = {
+ "schema": SCHEMA, "id": pid, "name": _unique_name(name or default_name(choices)),
+ "created": time.strftime("%Y-%m-%dT%H:%M:%S%z", time.localtime(now)), "created_epoch": now,
+ "tuner": {"mode": mode, "version": "1", "seconds": result.get("seconds"), "outcome": result.get("outcome")},
+ "choices": choices, "identity": identity, "slot": slot_key(choices, digest),
+ "settings": {"args": settings.get("args") or {}, "env": settings.get("env") or {},
+ "per_request": settings.get("per_request") or {}},
+ "answers": result.get("answers") or {"class": "exact", "fields": []},
+ "baseline": {"args": base_args or {}, "decode_tok_s": base.get("decode_tok_s"), "pp4k_tok_s": base.get("pp_tok_s"),
+ "pairs": result.get("pairs"), "noise_aa_decode": (result.get("noise") or {}).get("aa_gap")},
+ "measured": {"decode_tok_s": chosen.get("decode_tok_s"), "pp4k_tok_s": chosen.get("pp_tok_s"),
+ "vram_peak_mib": chosen.get("vram_used_mib"), "rss_peak_mib": chosen.get("rss_peak_mib"),
+ "pairs": result.get("pairs"), "faster_pairs": result.get("faster_pairs"),
+ "gain_pct": result.get("gain_pct"), "gain_decode_pct": result.get("gain_decode_pct"),
+ "gain_pp_pct": result.get("gain_pp_pct")},
+ "noise": result.get("noise") or {},
+ "evidence": {"arms": result.get("arms"), "per_request": result.get("per_request"), "notes": result.get("notes"),
+ "classes": result.get("classes")},
+ "recheck": {"request_set": RECHECK_SET, "last_ok": None, "last_ok_epoch": None, "last_result": None},
+ "previous": None,
+ }
+ _write_json(_path(pid), preset)
+ if activate:
+ activate_preset(pid)
+ preset = load(pid)
+ return preset
+
+
+def activate_preset(ref: str) -> dict[str, Any]:
+ """Make a preset the active one for its slot; the one it replaces is kept for undo."""
+ p = find(ref)
+ idx = _index()
+ entry = idx.get(p["slot"]) if isinstance(idx.get(p["slot"]), dict) else {"active": None, "history": []}
+ if entry.get("active") == p["id"]:
+ return p
+ if entry.get("active"):
+ entry.setdefault("history", []).append(entry["active"])
+ entry["history"] = entry["history"][-20:]
+ p["previous"] = entry.get("active")
+ entry["active"] = p["id"]
+ idx[p["slot"]] = entry
+ _write_json(_path(p["id"]), {k: v for k, v in p.items() if k != "active"})
+ _save_index(idx)
+ p["active"] = True
+ return p
+
+
+def deactivate_slot(slot: str) -> None:
+ """Back to the standard setup for this slot (the active preset is kept for undo)."""
+ idx = _index()
+ entry = idx.get(slot)
+ if isinstance(entry, dict) and entry.get("active"):
+ entry.setdefault("history", []).append(entry["active"])
+ entry["active"] = None
+ _save_index(idx)
+
+
+def undo(slot_or_ref: str) -> dict[str, Any] | None:
+ """Restore the preset that was active before the current one (None = the standard setup). ``slot_or_ref`` is a slot
+ key or any preset of the slot."""
+ idx = _index()
+ slot = slot_or_ref if slot_or_ref in idx else None
+ if slot is None:
+ slot = find(slot_or_ref)["slot"]
+ entry = idx.get(slot)
+ if not isinstance(entry, dict) or not entry.get("history") and entry.get("active") is None:
+ raise PresetError("there is nothing to undo")
+ hist = entry.get("history") or []
+ if not hist:
+ entry["active"] = None
+ _save_index(idx)
+ return None
+ prev = hist.pop()
+ entry["history"] = hist
+ entry["active"] = prev if _path(prev).exists() else None
+ _save_index(idx)
+ return load(entry["active"]) if entry["active"] else None
+
+
+def rename(ref: str, name: str) -> dict[str, Any]:
+ name = name.strip()
+ if not name or len(name) > 80 or re.search(r"[\r\n\0]", name):
+ raise PresetError("choose a name of 1 to 80 characters")
+ p = find(ref)
+ if _name_taken(name, p["id"]):
+ raise PresetError("another preset already has that name")
+ p["name"] = name
+ p.pop("active", None)
+ _write_json(_path(p["id"]), p)
+ return find(p["id"])
+
+
+def delete(ref: str) -> None:
+ p = find(ref)
+ idx = _index()
+ for slot, entry in list(idx.items()):
+ if not isinstance(entry, dict):
+ continue
+ entry["history"] = [h for h in entry.get("history", []) if h != p["id"]]
+ if entry.get("active") == p["id"]:
+ entry["active"] = entry["history"].pop() if entry["history"] else None
+ _save_index(idx)
+ try:
+ _path(p["id"]).unlink()
+ except OSError:
+ pass
+
+
+def export_preset(ref: str) -> dict[str, Any]:
+ p = find(ref)
+ p.pop("active", None)
+ return p
+
+
+def import_preset(data: dict[str, Any]) -> dict[str, Any]:
+ if not isinstance(data, dict) or data.get("schema") != SCHEMA:
+ raise PresetError("that file is not a Strata preset")
+ problems = tune_knobs.check_setting((data.get("settings") or {}).get("args") or {}, (data.get("settings") or {}).get("env") or {},
+ tune_knobs.Context(context_tokens=(data.get("choices") or {}).get("context") or 32768))
+ if problems:
+ raise PresetError("the preset has settings outside the safe rules: " + "; ".join(problems))
+ data = dict(data)
+ data["id"] = uuid.uuid4().hex
+ data["name"] = _unique_name(str(data.get("name") or "Imported preset"))
+ data["previous"] = None
+ data.pop("active", None)
+ _write_json(_path(data["id"]), data)
+ return find(data["id"])
+
+
+def record_recheck(ref: str, outcome: dict[str, Any]) -> dict[str, Any]:
+ p = find(ref)
+ p.pop("active", None)
+ rc = dict(p.get("recheck") or {})
+ rc["last_result"] = outcome
+ if outcome.get("verdict") == "keep":
+ rc["last_ok"] = time.strftime("%Y-%m-%dT%H:%M:%S%z")
+ rc["last_ok_epoch"] = time.time()
+ # an identity that was soft-stale is refreshed once the settings were checked on this PC
+ if outcome.get("identity"):
+ p["identity"] = outcome["identity"]
+ better = outcome.get("measured")
+ if better and p.get("measured", {}).get("decode_tok_s") and better.get("decode_tok_s") and \
+ better["decode_tok_s"] > 1.03 * p["measured"]["decode_tok_s"]:
+ p["measured"].update({k: v for k, v in better.items() if v is not None})
+ p["recheck"] = rc
+ _write_json(_path(p["id"]), p)
+ return find(p["id"])
+
+
+# --------------------------------------------------------------------------- applying the active preset at every start
+
+def notice(preset: dict[str, Any]) -> str:
+ return tune_knobs.ANSWER_NOTICE.get((preset.get("answers") or {}).get("class", "exact"), "")
+
+
+def overlay(cfg: dict[str, Any], *, now: dict[str, Any] | None = None, use: str = "chat") -> tuple[dict[str, Any], dict[str, Any]]:
+ """The run configuration with the active preset for its choices put on top, and what was done.
+
+ No measurement happens here. A preset whose identity changed in a *hard* way is not applied (it says why); a *soft* change
+ applies it and marks it for a re-check. A setting that is outside the safe rules is left out, never applied. Never raises:
+ a store that cannot be read means "no preset", and the engine starts with the configuration as it is."""
+ info: dict[str, Any] = {"applied": False}
+ try:
+ if not preset_dir().is_dir():
+ return cfg, info
+ choices = choices_from_config(cfg, use=use)
+ now = now or current_identity(cfg)
+ digest = (now.get("model") or {}).get("sha256_shard1")
+ entry = _index().get(slot_key(choices, digest))
+ if not isinstance(entry, dict) or not entry.get("active"):
+ return cfg, info
+ preset = load(entry["active"])
+ stale = staleness(preset, now)
+ info.update({"preset": {"id": preset["id"], "name": preset["name"]}, "state": stale["state"], "reasons": stale["reasons"]})
+ if stale["state"] == "hard":
+ info["why_not"] = "not applied: " + "; ".join(stale["reasons"])
+ return cfg, info
+ s = preset.get("settings") or {}
+ ctx = tune_knobs.Context(context_tokens=choices.get("context") or 32768, family=choices.get("family") or "flash-next")
+ problems = tune_knobs.check_setting(s.get("args") or {}, s.get("env") or {}, ctx)
+ if problems:
+ info["why_not"] = "not applied: " + "; ".join(problems)
+ return cfg, info
+ out = json.loads(json.dumps(cfg))
+ out["args"] = tune_knobs.apply_to_argv([str(a) for a in out.get("args") or []], s.get("args") or {})
+ if s.get("env"):
+ out["env"] = tune_knobs.apply_to_env(dict(out.get("env") or {}), s["env"])
+ if s.get("per_request"):
+ sampling = dict(out.get("sampling") or {})
+ sampling.setdefault("strata_tune", {k: v for k, v in s["per_request"].items() if v is not None})
+ out["sampling"] = sampling
+ info.update({"applied": True, "args": s.get("args"), "env": s.get("env"), "per_request": s.get("per_request"),
+ "answers": preset.get("answers"), "notice": notice(preset)})
+ return out, info
+ except Exception as e: # noqa: BLE001 - serving must never fail because of the preset store
+ info["error"] = f"{type(e).__name__}: {e}"
+ return cfg, info
+
+
+# --------------------------------------------------------------------------- history of every trial
+
+def history_path() -> Path:
+ return preset_dir() / "history.jsonl"
+
+
+def record_trials(trials: list[dict[str, Any]], *, hw_hash: str, model_digest: str | None, engine_sha: str | None) -> None:
+ from strata_control import tune_knobs as k
+ rows = []
+ for t in trials:
+ args = {}
+ a = t.get("args") or []
+ rows.append({"at": t.get("at"), "hw": hw_hash, "model": model_digest, "engine": engine_sha, "label": t.get("label"),
+ "sig": " ".join(str(x) for x in a) + "|" + json.dumps(t.get("env") or {}, sort_keys=True),
+ "status": t.get("status"), "reason": t.get("reason"), "decode_tok_s": t.get("decode_tok_s"),
+ "pp_tok_s": t.get("pp_tok_s"), "rss_peak_mib": t.get("rss_peak_mib")})
+ if not rows:
+ return
+ p = history_path()
+ p.parent.mkdir(parents=True, exist_ok=True)
+ with open(p, "a", encoding="utf-8") as fh:
+ for r in rows:
+ fh.write(json.dumps(r, sort_keys=True) + "\n")
+
+
+def bad_signatures(*, hw_hash: str, model_digest: str | None, engine_sha: str | None) -> set[str]:
+ """Candidates that did not start on this PC with this engine and model before (UNSUPPORTED or OOM): never retried."""
+ bad: set[str] = set()
+ try:
+ for line in history_path().read_text(encoding="utf-8").splitlines():
+ r = json.loads(line)
+ if r.get("hw") == hw_hash and r.get("model") == model_digest and r.get("engine") == engine_sha and \
+ r.get("status") in ("UNSUPPORTED", "OOM"):
+ bad.add(r.get("label") or "")
+ except (OSError, ValueError):
+ pass
+ return bad
diff --git a/strata_control/tune_knobs.py b/strata_control/tune_knobs.py
new file mode 100644
index 000000000..5785f88cc
--- /dev/null
+++ b/strata_control/tune_knobs.py
@@ -0,0 +1,473 @@
+"""The tuner's knowledge, as data: which settings it may try, the bounds, the never-pick list, and what each costs.
+
+Everything here comes from the measured study in ``phaseA-tests/split/TUNING-SPEC.md`` (S5a, draft 1; section numbers
+below are that document's). The rules are tables, not code, so a new measurement changes a row, and the same rows check a
+candidate before it runs and a preset before it is applied.
+
+Rule 1 (6.6): a candidate is a **single-knob change of the user's own configuration**. It never starts at "the first
+value of every dimension" (that is how the old Terminal sweep put ``--expert-cache 0 --kv fp16 --spec-min-p 0.001`` in
+place of the user's settings). Rule 2: a value outside the bounds, or on the never list, is not tried. Rule 3: boolean
+flags are present or absent (``--kv-grow 0`` is an unknown argument).
+
+Answer classes (3.2): ``exact`` (byte-identical to the standard setup), ``placement`` (same math, a different CPU/GPU
+split, so near-ties can flip), ``quality`` (changes the numbers on purpose; never automatic), ``nonrepeatable`` (not
+bit-exact run to run). Only ``exact`` is picked on its own; the others need the user's tick.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Sequence
+
+ANSWER_ORDER = ("exact", "placement", "nonrepeatable", "quality")
+
+#: What the Tune screen says about a preset's answer class (3.4), in plain words.
+ANSWER_NOTICE = {
+ "exact": "Answers are identical to the standard setup.",
+ "placement": "Answers may differ slightly from the standard setup.",
+ "nonrepeatable": "Answers are not repeatable run to run.",
+ "quality": "Includes a quality setting that changes the numbers.",
+}
+
+#: Flags that take no value (present = on, absent = off).
+BOOL_FLAGS = frozenset({"--kv-grow", "--trim-stage-weights", "--no-host-worker", "--no-pool", "--mmap-experts",
+ "--resident-experts", "--prompt-cache-tail", "--vram-elastic", "--split-skip-if-fits",
+ "--resident-cpu-experts", "--no-hit-poke", "--expert-cache-per-layer", "--batch-mtp"})
+
+
+# --------------------------------------------------------------------------- the arms
+
+@dataclass(frozen=True)
+class Arm:
+ """One candidate: a single knob (or one tied group) changed from the user's configuration."""
+
+ id: str
+ label: str # plain words, shown in the progress and the result
+ answer: str # exact | placement | nonrepeatable | quality
+ set_args: dict[str, Any] = field(default_factory=dict) # flag -> value | True (present) | None (remove)
+ env: dict[str, str | None] = field(default_factory=dict)
+ families: tuple[str, ...] = ("flash-next",)
+ backends: tuple[str, ...] = ("cuda", "hip")
+ classes: tuple[str, ...] = () # machine classes (6.2) whose list this arm is on
+ needs: tuple[str, ...] = () # machine facts that must hold, see `condition_holds`
+ goals: tuple[str, ...] = ("speed", "coding", "chat", "room")
+ ram_delta_mib: int = 0 # extra memory the engine is predicted to take over the base run
+ deep_only: bool = False
+ #: a dynamic value: name of a computed number ("workers-2" ...), filled from the base run's engine log
+ dynamic: dict[str, str] = field(default_factory=dict)
+
+ def requires_flags(self) -> list[str]:
+ return [f for f in self.set_args if self.set_args[f] is not None]
+
+
+ARMS: tuple[Arm, ...] = (
+ # --- class A: RAM-bound resident mode (6.2) ---------------------------------------------------------------
+ Arm("adapt_async", "Learn which experts to keep while you chat, in the background", "nonrepeatable",
+ {"--adapt-async": 1}, backends=("cuda",), classes=("A",), needs=("resident_ram", "one_gpu")),
+ Arm("pin_by_need", "Pin memory only when needed", "exact", {}, {"STRATA_PIN_BY_NEED": "1"},
+ backends=("cuda",), classes=("A",), needs=("one_gpu",)),
+ Arm("host_core_last", "Run the control thread on the last CPU core", "exact", {"--host-core": "last"},
+ classes=("A", "F")),
+ # --- class B: large graphics memory (experts mostly resident) ---------------------------------------------
+ Arm("adapt_tier_fast", "Re-balance the expert cache faster", "placement",
+ {"--adapt-every": 1, "--adapt-swaps": 80, "--adapt-decay": 0.97}, classes=("B",)),
+ Arm("spec3", "Shorter speculative window (3 tokens)", "placement", {"--spec": 3}, classes=("A", "B")),
+ Arm("prefill_32k", "Larger prompt chunks (faster very long prompts)", "exact", {"--prefill": "auto:32768"},
+ classes=("B",), goals=("coding",), ram_delta_mib=4096, needs=("vram_ge_24g",)),
+ # --- class C: mid graphics memory, PCIe-bound -------------------------------------------------------------
+ Arm("adapt_decay_09", "Forget old expert use a little faster", "placement", {"--adapt-decay": 0.9},
+ classes=("C", "G"), backends=("cuda", "hip", "sycl")),
+ Arm("trim_stage", "Trim stage weights on two cards", "exact", {"--trim-stage-weights": True},
+ backends=("cuda",), classes=("C",), needs=("two_gpus",)),
+ Arm("workers_minus2", "Two fewer CPU helper threads", "exact", {}, classes=("C",),
+ dynamic={"--pool-workers": "workers-2"}),
+ # --- class F: hybrid CPU (performance + efficiency cores) -------------------------------------------------
+ Arm("workers_minus1", "One fewer CPU helper thread", "exact", {}, classes=("F",),
+ dynamic={"--pool-workers": "workers-1"}, needs=("hybrid_cpu",)),
+ # --- class G: Intel Arc (SYCL) ----------------------------------------------------------------------------
+ Arm("pcie_start_02", "Start with a smaller PCIe share", "placement", {"--pcie-frac": 0.2},
+ backends=("sycl",), classes=("G",)),
+ # --- Qwen3.6 hybrid (class D) -----------------------------------------------------------------------------
+ Arm("q36_workers_explicit", "Fix the CPU helper thread count", "exact", {}, families=("qwen36",),
+ backends=("cuda", "hip"), classes=("D",), dynamic={"--pool-workers": "workers"}, needs=("hybrid_experts",)),
+ Arm("q36_mtp1", "Shorter draft window (1)", "placement", {"--mtp": 1}, families=("qwen36",),
+ backends=("cuda", "hip"), classes=("D",), needs=("hybrid_experts",)),
+ Arm("q36_prefill_4096", "Larger prompt chunks (twice the prompt speed, a little slower answers)", "exact",
+ {"--prefill": 4096}, families=("qwen36",), backends=("cuda", "hip"), classes=("D",), goals=("coding",),
+ needs=("hybrid_experts",)),
+ Arm("q36_hybrid_rows_256", "Larger hybrid row blocks", "exact", {"--hybrid-rows": 256}, families=("qwen36",),
+ backends=("cuda", "hip"), classes=("D",), needs=("hybrid_experts",), deep_only=True),
+ # --- thorough only: effects measured as flat, tried last --------------------------------------------------
+ Arm("kv_grow", "Allocate the conversation memory as it grows", "exact", {"--kv-grow": True},
+ classes=("B", "C"), backends=("cuda", "hip", "sycl"), deep_only=True),
+)
+
+#: The per-request settings (3.1, 4.1). They need no restart, so every one is tried before any restart (5).
+#: `values` are tried against the engine's own choice (absent); a win needs >= 3% in every round.
+PER_REQUEST: tuple[dict[str, Any], ...] = (
+ {"key": "pcie_frac", "values": (0.2, 0.35, 0.0), "backends": ("cuda", "hip", "sycl"),
+ "label": "PCIe share", "answer": "placement"},
+ {"key": "spec_min_p", "values": (0.7, 0.5), "backends": ("cuda", "hip", "sycl", "metal"),
+ "label": "speculative confidence floor", "answer": "exact"},
+ {"key": "aux_cpus", "values": (1, 0), "backends": ("cuda", "hip"), "label": "spare CPU cores for helper threads",
+ "answer": "exact"},
+)
+
+# --------------------------------------------------------------------------- bounds and the never list
+
+#: Safe bounds (6.6, column 3). A value outside them is not tried and is refused in a preset.
+BOUNDS: dict[str, dict[str, Any]] = {
+ "--spec": {"choices": (3, 4)},
+ "--spec-min-p": {"min": 0.3, "max": 0.7},
+ "--mtp": {"choices": (1, 2, 3), "numeric_only": True}, # Qwen3.6; Flash-Next's --mtp is a path
+ "--pcie-frac": {"min": 0.0, "max": 0.55},
+ "--adapt-every": {"min": 1, "max": 4},
+ "--adapt-swaps": {"min": 80, "max": 160},
+ "--adapt-decay": {"min": 0.7, "max": 0.97},
+ "--hybrid-rows": {"min": 64, "max": 256},
+ "--host-core": {"choices": ("first", "last")},
+ "--prefill": {"choices": ("auto", "auto:16384", "auto:32768", 2048, 4096)},
+}
+
+#: The never-pick list (4.5), as rows: ``flag`` (or ``env``), a condition on the machine, the value test and the reason
+#: in plain words. ``when`` names facts from `condition_holds`; empty = always.
+NEVER: tuple[dict[str, Any], ...] = (
+ {"env": "STRATA_SH_STREAM", "when": ("gfx12",), "reason": "it halves decode speed on this graphics card"},
+ {"env": "STRATA_RDNA2_SGEMM", "value": "all", "when": ("gfx12",), "reason": "it makes long prompts five times slower"},
+ {"env": "STRATA_SELECT_SIMT", "reason": "its gain is below the 3% margin"},
+ {"env": "STRATA_HIP_WMMA", "reason": "it changes the numbers (a quality setting)"},
+ {"flag": "--pool-affinity", "when": ("hybrid_cpu",), "values": ("auto", "p-cores"),
+ "reason": "it made answers 47% slower on a CPU with performance and efficiency cores"},
+ {"flag": "--pool-workers", "test": "above_engine_default", "reason": "more helper threads than the engine chose made it 36% slower"},
+ {"flag": "--ple-io", "values": ("ram", "mmap"), "when": ("ram_bound",),
+ "reason": "it needs the table in memory, which this PC does not have to spare (-61% speed)"},
+ {"flag": "--adapt-every", "test": "at_least", "limit": 100000, "reason": "turning the expert re-balancing off cost 3% to 44%"},
+ {"flag": "--kv-resident", "test": "below_context", "reason": "it made answers 27% to 34% slower and changes them"},
+ {"flag": "--pcie-frac", "test": "at_least", "limit": 0.75, "when": ("pcie_bound",),
+ "reason": "a high PCIe share made answers 14% to 37% slower"},
+ {"flag": "--prefill", "test": "fixed_below_auto", "reason": "smaller prompt chunks made long prompts 11% to 75% slower"},
+ {"flag": "--expert-vram", "test": "without_prefill", "families": ("qwen36",),
+ "reason": "without a matching prompt chunk it made prompts 44% slower"},
+ {"flag": "--spec", "test": "at_least", "limit": 6, "reason": "wider speculative windows were 4% to 16% slower"},
+ {"flag": "--spec", "test": "at_most", "limit": 2, "families": ("flash-next",), "reason": "a 2-token window was 4% to 11% slower"},
+ {"flag": "--lookup-chain", "reason": "it was 3% to 8.5% slower"},
+ {"flag": "--vram-reserve-mib", "when": ("vram_le_8g",), "reason": "this card cannot start with a reserve"},
+ {"flag": "--expert-cache", "test": "zero_or_small", "reason": "turning the GPU expert cache off or very small costs speed"},
+ {"flag": "--mtp", "test": "mtp_extreme", "families": ("qwen36",), "reason": "that draft window was 10% to 28% slower"},
+)
+
+#: Which flags change answers by themselves, for the notice on a preset (3.4).
+ANSWER_OF_FLAG: dict[str, str] = {
+ "--expert-cache": "placement", "--vram-reserve-mib": "placement", "--adapt-every": "placement",
+ "--adapt-swaps": "placement", "--adapt-decay": "placement", "--adapt-min-gain": "placement",
+ "--pcie-frac": "placement", "--spec": "placement", "--mtp": "placement", "--lookup-chain": "placement",
+ "--kv-resident": "placement", "--kv": "quality", "--adapt-async": "nonrepeatable",
+}
+
+
+# --------------------------------------------------------------------------- the context rules run in
+
+@dataclass
+class Context:
+ """The machine and the choices a candidate plan is made for."""
+
+ backend: str = "cuda" # cuda | hip | sycl | metal | cpu
+ family: str = "flash-next" # flash-next | qwen36
+ gpu_count: int = 1
+ vram_mib: int = 0 # the card the model runs on (smallest if several)
+ ram_gib: int = 0
+ model_gib: float = 0.0
+ hybrid_cpu: bool = False
+ logical_threads: int = 0
+ arch: str | None = None # e.g. gfx1201
+ context_tokens: int = 32768
+ goal: str = "speed" # speed | room
+ use: str = "chat" # chat | coding
+ allow_placement: bool = False
+ allow_nonrepeatable: bool = False
+ facts: dict[str, Any] = field(default_factory=dict) # parsed from the base run's engine log
+ engine_flags: Sequence[str] | None = None
+ base_args: list[str] = field(default_factory=list)
+
+
+def condition_holds(name: str, ctx: Context) -> bool:
+ f = ctx.facts
+ return {
+ "resident_ram": bool(f.get("resident_ram")),
+ "one_gpu": ctx.gpu_count <= 1,
+ "two_gpus": ctx.gpu_count == 2,
+ "hybrid_cpu": ctx.hybrid_cpu,
+ "hybrid_experts": bool(f.get("hybrid_experts")),
+ "vram_ge_24g": ctx.vram_mib >= 24000,
+ "vram_le_8g": 0 < ctx.vram_mib <= 8400,
+ "gfx12": bool(ctx.arch and ctx.arch.startswith("gfx12")),
+ "pcie_bound": 0 < ctx.vram_mib < 24000,
+ "ram_bound": bool(ctx.ram_gib and ctx.model_gib and ctx.ram_gib - ctx.model_gib < 30),
+ }.get(name, False)
+
+
+def machine_classes(ctx: Context) -> list[str]:
+ """The classes of 6.2 this machine belongs to, in the order their candidate lists are walked."""
+ classes: list[str] = []
+ if ctx.family == "qwen36":
+ classes.append("D" if ctx.facts.get("hybrid_experts") else "E")
+ return classes
+ if ctx.backend == "sycl":
+ return ["G"]
+ if ctx.facts.get("resident_ram") or (ctx.ram_gib and ctx.model_gib and ctx.ram_gib - ctx.model_gib < 12):
+ classes.append("A")
+ classes.append("B" if ctx.vram_mib >= 24000 else "C")
+ if ctx.hybrid_cpu:
+ classes.append("F")
+ return classes
+
+
+# --------------------------------------------------------------------------- rule checks
+
+def _as_number(value: Any) -> float | None:
+ try:
+ return float(value)
+ except (TypeError, ValueError):
+ return None
+
+
+def _prefill_below_auto(value: Any) -> bool:
+ n = _as_number(value)
+ return n is not None and not str(value).startswith("auto")
+
+
+def check_setting(args: dict[str, Any], env: dict[str, str | None], ctx: Context) -> list[str]:
+ """Reasons (plain words) a setting must not be applied; an empty list means it is inside the rules.
+
+ ``args`` maps flag -> value (True for a present boolean flag); ``env`` maps name -> value."""
+ problems: list[str] = []
+ ctx_tokens = ctx.context_tokens
+ default_workers = ctx.facts.get("workers")
+ for rule in NEVER:
+ fams = rule.get("families")
+ if fams and ctx.family not in fams:
+ continue
+ if any(not condition_holds(w, ctx) for w in rule.get("when", ())):
+ continue
+ if "env" in rule:
+ if rule["env"] in env and env[rule["env"]] not in (None, "", "0") and \
+ ("value" not in rule or env[rule["env"]] == rule["value"]):
+ problems.append(f"{rule['env']}: {rule['reason']}")
+ continue
+ flag = rule["flag"]
+ if flag not in args or args[flag] is None:
+ continue
+ value = args[flag]
+ test = rule.get("test")
+ hit = False
+ if "values" in rule:
+ hit = str(value) in rule["values"]
+ elif test is None:
+ hit = True
+ elif test == "above_engine_default":
+ n = _as_number(value)
+ hit = n is not None and default_workers is not None and n > float(default_workers)
+ elif test == "at_least":
+ n = _as_number(value)
+ hit = n is not None and n >= rule["limit"]
+ elif test == "at_most":
+ n = _as_number(value)
+ hit = n is not None and n <= rule["limit"] and flag == "--spec"
+ elif test == "below_context":
+ n = _as_number(value)
+ hit = n is not None and n < ctx_tokens
+ elif test == "fixed_below_auto":
+ hit = _prefill_below_auto(value) and ctx.family == "flash-next"
+ if ctx.family == "qwen36":
+ n = _as_number(value)
+ hit = n is not None and n <= 512
+ elif test == "without_prefill":
+ hit = "--prefill" not in args and "--prefill" not in _flags_of(ctx.base_args)
+ elif test == "zero_or_small":
+ n = _as_number(value)
+ hit = n is not None and str(value) != "auto" and n < 0.5 * float(ctx.facts.get("auto_slots") or 0 or 1)
+ elif test == "mtp_extreme":
+ n = _as_number(value)
+ hit = n is not None and (n == 0 or n >= 4)
+ if hit:
+ problems.append(f"{flag} {value}: {rule['reason']}")
+ for flag, value in args.items():
+ bound = BOUNDS.get(flag)
+ if not bound or value is None or value is True:
+ continue
+ if bound.get("numeric_only") and _as_number(value) is None:
+ continue
+ if "choices" in bound and value not in bound["choices"] and str(value) not in [str(c) for c in bound["choices"]]:
+ problems.append(f"{flag} {value}: outside the safe values {list(bound['choices'])}")
+ n = _as_number(value)
+ if n is not None and "min" in bound and n < bound["min"]:
+ problems.append(f"{flag} {value}: below the safe minimum {bound['min']}")
+ if n is not None and "max" in bound and n > bound["max"]:
+ problems.append(f"{flag} {value}: above the safe maximum {bound['max']}")
+ return problems
+
+
+def _flags_of(argv: Sequence[str]) -> set[str]:
+ return {a for a in argv if isinstance(a, str) and a.startswith("--")}
+
+
+def answer_class(args: dict[str, Any], env: dict[str, str | None] | None = None,
+ base_args: dict[str, Any] | None = None) -> tuple[str, list[str]]:
+ """The worst answer class among the settings that differ from the base, and which flags cause it."""
+ worst, fields = "exact", []
+ base_args = base_args or {}
+ for flag, value in args.items():
+ if base_args.get(flag) == value:
+ continue
+ cls = ANSWER_OF_FLAG.get(flag)
+ if cls:
+ fields.append(flag)
+ if ANSWER_ORDER.index(cls) > ANSWER_ORDER.index(worst):
+ worst = cls
+ return worst, fields
+
+
+def allowed(answer: str, ctx: Context) -> bool:
+ """May an arm of this answer class be picked on its own? Exact always; the rest need the user's tick; quality never."""
+ return answer == "exact" or (answer == "placement" and ctx.allow_placement) or \
+ (answer == "nonrepeatable" and ctx.allow_nonrepeatable)
+
+
+# --------------------------------------------------------------------------- planning
+
+def dynamic_value(spec: str, ctx: Context) -> Any:
+ f = ctx.facts
+ workers = f.get("workers")
+ if spec == "workers":
+ return int(workers) if workers else None
+ if spec.startswith("workers-") and workers:
+ value = int(workers) - int(spec[len("workers-"):])
+ floor = max(2, int(workers) // 4 + 1) # never below N/4 (6.6)
+ return value if value >= floor else None
+ return None
+
+
+@dataclass
+class PlannedArm:
+ arm: Arm
+ args: dict[str, Any]
+ env: dict[str, str | None]
+
+
+def plan_arms(ctx: Context, *, mode: str = "quick", history_bad: set[str] | None = None) -> tuple[list[PlannedArm], list[dict[str, str]]]:
+ """The candidates for this machine in the order they are tried, and the ones left out with the reason.
+
+ Order: the machine's classes in order (6.2), each class's arms in the table order. Quick keeps the first ones the
+ time budget allows; thorough keeps all of them, flat knobs last."""
+ classes = machine_classes(ctx)
+ base_flags = _flags_of(ctx.base_args)
+ chosen: list[PlannedArm] = []
+ skipped: list[dict[str, str]] = []
+ seen: set[str] = set()
+ for cls in classes:
+ for arm in ARMS:
+ if cls not in arm.classes or arm.id in seen:
+ continue
+ seen.add(arm.id)
+
+ def skip(reason: str) -> None:
+ skipped.append({"id": arm.id, "label": arm.label, "reason": reason})
+
+ if ctx.family not in arm.families:
+ continue
+ if ctx.backend not in arm.backends:
+ skip(f"not a {ctx.backend} setting")
+ continue
+ if arm.deep_only and mode != "thorough":
+ skip("only tried in the thorough tune (it was measured as flat)")
+ continue
+ if ctx.goal not in arm.goals and ctx.use not in arm.goals:
+ skip("does not serve what you asked for")
+ continue
+ if not allowed(arm.answer, ctx):
+ skip({"placement": "it can change answers slightly; tick 'allow small answer differences' to try it",
+ "nonrepeatable": "answers would not repeat run to run; tick 'allow settings that are not repeatable' to try it",
+ "quality": "it is a quality setting, never chosen automatically"}.get(arm.answer, "not allowed"))
+ continue
+ miss = [n for n in arm.needs if not condition_holds(n, ctx)]
+ if miss:
+ skip("this PC does not match: " + ", ".join(miss).replace("_", " "))
+ continue
+ args = dict(arm.set_args)
+ bad = False
+ for flag, spec in arm.dynamic.items():
+ v = dynamic_value(spec, ctx)
+ if v is None:
+ skip("the engine's current value could not be read")
+ bad = True
+ break
+ args[flag] = v
+ if bad:
+ continue
+ if ctx.engine_flags is not None:
+ unknown = [f for f in args if f not in ctx.engine_flags]
+ if unknown:
+ skip("this engine does not accept " + ", ".join(unknown))
+ continue
+ problems = check_setting(args, dict(arm.env), ctx)
+ if problems:
+ skip("; ".join(problems))
+ continue
+ if all(_current(ctx.base_args, f) == _norm(v) for f, v in args.items()) and not arm.env:
+ skip("already the current setting")
+ continue
+ sig = signature(args, arm.env)
+ if history_bad and (sig in history_bad or arm.id in history_bad):
+ skip("did not start on this PC before")
+ continue
+ chosen.append(PlannedArm(arm, args, dict(arm.env)))
+ return chosen, skipped
+
+
+def _norm(value: Any) -> str | None:
+ return None if value is None else ("" if value is True else str(value))
+
+
+def _current(argv: Sequence[str], flag: str) -> str | None:
+ """The value a flag has in an argv list: '' for a bare flag, None when absent."""
+ for i, a in enumerate(argv):
+ if a == flag:
+ if flag in BOOL_FLAGS or i + 1 >= len(argv) or str(argv[i + 1]).startswith("--"):
+ return ""
+ return str(argv[i + 1])
+ return None
+
+
+def signature(args: dict[str, Any], env: dict[str, str | None] | None = None) -> str:
+ parts = [f"{k}={_norm(v)}" for k, v in sorted(args.items())] + [f"{k}={v}" for k, v in sorted((env or {}).items())]
+ return "|".join(parts)
+
+
+def apply_to_argv(argv: Sequence[str], args: dict[str, Any]) -> list[str]:
+ """The user's argv with the candidate's settings put on top (Rule 3: a boolean is present or absent)."""
+ out = list(argv)
+ for flag, value in args.items():
+ i = 0
+ while i < len(out):
+ if out[i] == flag:
+ n = 1 if (flag in BOOL_FLAGS or i + 1 >= len(out) or str(out[i + 1]).startswith("--")) else 2
+ del out[i:i + n]
+ else:
+ i += 1
+ if value is None or value is False:
+ continue
+ if value is True or flag in BOOL_FLAGS:
+ out.append(flag)
+ else:
+ out.extend([flag, str(value)])
+ return out
+
+
+def apply_to_env(env: dict[str, str], changes: dict[str, str | None]) -> dict[str, str]:
+ out = dict(env)
+ for k, v in changes.items():
+ if v is None:
+ out.pop(k, None)
+ else:
+ out[k] = str(v)
+ return out
diff --git a/strata_control/tune_machine.py b/strata_control/tune_machine.py
new file mode 100644
index 000000000..7410f444b
--- /dev/null
+++ b/strata_control/tune_machine.py
@@ -0,0 +1,313 @@
+"""What the tuner needs to know about this PC, read without ever raising.
+
+Every probe here is optional: a missing tool or an unreadable file gives ``None`` (or an empty list), never an
+exception, because the tuner must still run on a machine whose sensors it cannot read, only with fewer guards.
+A guard that cannot read its input says so in the report ("the free graphics memory could not be read"); it does not
+pretend the memory was free.
+
+Stdlib only, like the rest of Strata Control.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import platform
+import re
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+MIB = 1024 * 1024
+
+
+# --------------------------------------------------------------------------- memory
+
+def memory() -> dict[str, int | None]:
+ """System RAM in MiB: ``total`` and ``available`` (what a new process could use without swapping)."""
+ try:
+ if os.name == "nt":
+ import ctypes
+
+ class _Status(ctypes.Structure):
+ _fields_ = [("dwLength", ctypes.c_ulong), ("dwMemoryLoad", ctypes.c_ulong),
+ ("ullTotalPhys", ctypes.c_ulonglong), ("ullAvailPhys", ctypes.c_ulonglong),
+ ("ullTotalPageFile", ctypes.c_ulonglong), ("ullAvailPageFile", ctypes.c_ulonglong),
+ ("ullTotalVirtual", ctypes.c_ulonglong), ("ullAvailVirtual", ctypes.c_ulonglong),
+ ("ullAvailExtendedVirtual", ctypes.c_ulonglong)]
+
+ status = _Status()
+ status.dwLength = ctypes.sizeof(_Status)
+ if ctypes.windll.kernel32.GlobalMemoryStatusEx(ctypes.byref(status)):
+ return {"total_mib": int(status.ullTotalPhys // MIB), "available_mib": int(status.ullAvailPhys // MIB)}
+ elif sys.platform == "darwin":
+ total = int(subprocess.run(["sysctl", "-n", "hw.memsize"], capture_output=True, text=True,
+ timeout=5).stdout.strip()) // MIB
+ vm = subprocess.run(["vm_stat"], capture_output=True, text=True, timeout=5).stdout
+ page = int(re.search(r"page size of (\d+)", vm).group(1)) if re.search(r"page size of (\d+)", vm) else 16384
+ pages = 0
+ for key in ("Pages free", "Pages inactive", "Pages speculative"):
+ m = re.search(rf"{key}:\s+(\d+)", vm)
+ pages += int(m.group(1)) if m else 0
+ return {"total_mib": total, "available_mib": pages * page // MIB}
+ else:
+ info: dict[str, int] = {}
+ for line in Path("/proc/meminfo").read_text().splitlines():
+ key, _, rest = line.partition(":")
+ info[key] = int(rest.split()[0])
+ return {"total_mib": info["MemTotal"] // 1024, "available_mib": info["MemAvailable"] // 1024}
+ except Exception: # noqa: BLE001 - a probe must not raise
+ pass
+ return {"total_mib": None, "available_mib": None}
+
+
+# --------------------------------------------------------------------------- graphics cards
+
+def _run(argv: list[str], timeout: float = 10.0) -> str | None:
+ try:
+ return subprocess.run(argv, capture_output=True, text=True, timeout=timeout).stdout
+ except Exception: # noqa: BLE001
+ return None
+
+
+def gpus() -> list[dict[str, Any]]:
+ """Graphics cards with their memory: ``name``, ``vram_total_mib``, ``vram_used_mib`` (None when unreadable),
+ ``driver``, ``vendor``. NVIDIA through nvidia-smi, AMD through the kernel's sysfs files; Intel and Apple report
+ their name only where it is known, and leave the memory unreadable."""
+ out: list[dict[str, Any]] = []
+ smi = shutil.which("nvidia-smi")
+ if smi:
+ text = _run([smi, "--query-gpu=index,name,memory.total,memory.used,driver_version",
+ "--format=csv,noheader,nounits"])
+ for line in (text or "").splitlines():
+ parts = [p.strip() for p in line.split(",")]
+ if len(parts) >= 5:
+ try:
+ out.append({"vendor": "nvidia", "index": int(parts[0]), "name": parts[1],
+ "vram_total_mib": int(float(parts[2])), "vram_used_mib": int(float(parts[3])),
+ "driver": parts[4]})
+ except ValueError:
+ continue
+ if not out and sys.platform.startswith("linux"):
+ base = Path("/sys/class/drm")
+ if base.is_dir():
+ index = 0
+ for card in sorted(base.glob("card[0-9]*")):
+ dev = card / "device"
+ try:
+ vendor = (dev / "vendor").read_text().strip()
+ total = int((dev / "mem_info_vram_total").read_text()) // MIB
+ used = int((dev / "mem_info_vram_used").read_text()) // MIB
+ except (OSError, ValueError):
+ continue
+ if vendor != "0x1002":
+ continue
+ name = None
+ try:
+ name = (dev / "product_name").read_text().strip()
+ except OSError:
+ pass
+ out.append({"vendor": "amd", "index": index, "name": name or f"AMD GPU {index}",
+ "vram_total_mib": total, "vram_used_mib": used, "driver": None})
+ index += 1
+ return out
+
+
+def gpu_used_mib(indexes: list[int] | None = None) -> int | None:
+ """Graphics memory in use now, summed over the cards the model runs on (all when ``indexes`` is None)."""
+ cards = gpus()
+ if not cards:
+ return None
+ vals = [c["vram_used_mib"] for c in cards if c.get("vram_used_mib") is not None
+ and (not indexes or c["index"] in indexes)]
+ return sum(vals) if vals else None
+
+
+# --------------------------------------------------------------------------- processor
+
+def cpu() -> dict[str, Any]:
+ """``model``, ``logical`` and ``physical`` thread counts, and ``hybrid`` (performance plus efficiency cores)."""
+ logical = os.cpu_count() or 1
+ model = platform.processor() or platform.machine()
+ physical: int | None = None
+ hybrid = False
+ try:
+ if sys.platform.startswith("linux"):
+ text = Path("/proc/cpuinfo").read_text()
+ m = re.search(r"model name\s*:\s*(.+)", text)
+ if m:
+ model = m.group(1).strip()
+ cores = set()
+ for block in text.split("\n\n"):
+ pid = re.search(r"physical id\s*:\s*(\d+)", block)
+ cid = re.search(r"core id\s*:\s*(\d+)", block)
+ if pid and cid:
+ cores.add((pid.group(1), cid.group(1)))
+ physical = len(cores) or None
+ hybrid = Path("/sys/devices/cpu_core").exists() and Path("/sys/devices/cpu_atom").exists()
+ elif os.name == "nt":
+ try:
+ import winreg
+ with winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, r"HARDWARE\DESCRIPTION\System\CentralProcessor\0") as k:
+ model = str(winreg.QueryValueEx(k, "ProcessorNameString")[0]).strip() or model
+ except OSError:
+ pass
+ physical, hybrid = _windows_cores()
+ elif sys.platform == "darwin":
+ model = (_run(["sysctl", "-n", "machdep.cpu.brand_string"]) or model).strip()
+ phys = _run(["sysctl", "-n", "hw.physicalcpu"])
+ physical = int(phys) if phys and phys.strip().isdigit() else None
+ hybrid = False
+ except Exception: # noqa: BLE001
+ pass
+ return {"model": model, "logical": logical, "physical": physical, "hybrid": hybrid}
+
+
+def _windows_cores() -> tuple[int | None, bool]:
+ """(physical cores, hybrid) from GetLogicalProcessorInformationEx: hybrid when the cores have more than one
+ efficiency class (performance and efficiency cores)."""
+ try:
+ import ctypes
+ from ctypes import wintypes
+
+ k = ctypes.windll.kernel32
+ k.GetLogicalProcessorInformationEx.argtypes = [wintypes.DWORD, ctypes.c_void_p, ctypes.POINTER(wintypes.DWORD)]
+ size = wintypes.DWORD(0)
+ k.GetLogicalProcessorInformationEx(0, None, ctypes.byref(size)) # 0 = RelationProcessorCore
+ buf = ctypes.create_string_buffer(size.value)
+ if not k.GetLogicalProcessorInformationEx(0, buf, ctypes.byref(size)):
+ return None, False
+ raw = bytes(buf.raw[:size.value])
+ classes, cores, offset = set(), 0, 0
+ while offset + 10 <= len(raw):
+ rel_size = int.from_bytes(raw[offset + 4:offset + 8], "little")
+ if rel_size <= 0:
+ break
+ classes.add(raw[offset + 9]) # PROCESSOR_RELATIONSHIP.EfficiencyClass
+ cores += 1
+ offset += rel_size
+ return (cores or None), len(classes) > 1
+ except Exception: # noqa: BLE001
+ return None, False
+
+
+_last_cpu: tuple[float, int, int] | None = None
+
+
+def cpu_busy_percent(sample_s: float = 1.0) -> float | None:
+ """How busy the whole CPU was over the last ``sample_s`` seconds (0-100), or None when unreadable."""
+ def read() -> tuple[int, int] | None:
+ try:
+ if sys.platform.startswith("linux"):
+ f = Path("/proc/stat").read_text().splitlines()[0].split()[1:]
+ v = [int(x) for x in f]
+ idle = v[3] + (v[4] if len(v) > 4 else 0)
+ return sum(v), idle
+ if os.name == "nt":
+ import ctypes
+ from ctypes import wintypes
+ idle, kern, user = wintypes.FILETIME(), wintypes.FILETIME(), wintypes.FILETIME()
+ if not ctypes.windll.kernel32.GetSystemTimes(ctypes.byref(idle), ctypes.byref(kern), ctypes.byref(user)):
+ return None
+ q = lambda t: (t.dwHighDateTime << 32) | t.dwLowDateTime # noqa: E731
+ return q(kern) + q(user), q(idle)
+ except Exception: # noqa: BLE001
+ return None
+ return None
+
+ a = read()
+ if a is None:
+ return None
+ time.sleep(sample_s)
+ b = read()
+ if b is None or b[0] == a[0]:
+ return None
+ return round(100.0 * (1.0 - (b[1] - a[1]) / (b[0] - a[0])), 1)
+
+
+def other_engines(own_pids: set[int] | None = None) -> list[str]:
+ """Command lines of Strata engines that this tune did not start (a second engine changes every number)."""
+ own = own_pids or set()
+ found: list[str] = []
+ try:
+ if os.name == "nt":
+ text = _run(["powershell", "-NoProfile", "-Command",
+ "Get-CimInstance Win32_Process -Filter \"Name='strata.exe'\" | "
+ "Select-Object ProcessId,CommandLine | ConvertTo-Json -Compress"], timeout=20)
+ if text and text.strip():
+ data = json.loads(text)
+ for row in data if isinstance(data, list) else [data]:
+ if int(row.get("ProcessId", 0)) not in own and "--serve" in (row.get("CommandLine") or ""):
+ found.append((row.get("CommandLine") or "")[:160])
+ else:
+ text = _run(["ps", "-eo", "pid=,args="]) or ""
+ for line in text.splitlines():
+ pid_s, _, args = line.strip().partition(" ")
+ if pid_s.isdigit() and int(pid_s) not in own and re.search(r"(^|/)strata(\s|$)", args.split(" --serve")[0]) \
+ and " --serve" in args:
+ found.append(args[:160])
+ except Exception: # noqa: BLE001
+ pass
+ return found
+
+
+# --------------------------------------------------------------------------- the key a preset is valid for
+
+def _round_down(value: int | None, step: int) -> int | None:
+ return None if value is None else value - value % step
+
+
+def hardware_identity(*, pcie: str | None = None) -> dict[str, Any]:
+ """Hardware in two parts. ``hard``: a change means the stored settings may not even start (graphics card,
+ memory sizes, processor). ``soft``: a change deserves a short re-check (graphics driver)."""
+ cards = gpus()
+ mem = memory()
+ c = cpu()
+ return {
+ "hard": {
+ "gpus": [{"name": g["name"], "vram_mib": g["vram_total_mib"]} for g in cards],
+ "cpu": c["model"], "logical": c["logical"], "physical": c["physical"], "hybrid": c["hybrid"],
+ "ram_gib": _round_down((mem["total_mib"] or 0) // 1024 or None, 2),
+ "pcie": pcie, "os": platform.system(),
+ },
+ "soft": {"driver": sorted({g["driver"] for g in cards if g.get("driver")}), "os_release": platform.release()},
+ }
+
+
+def engine_identity(exe: str | os.PathLike[str]) -> dict[str, Any]:
+ """The engine build: version, backend, build id and executable SHA-256 from its manifest, plus the manifest's
+ ``tuning_epoch`` (bumped when a kernel or default change can move a tuning result)."""
+ folder = Path(exe).resolve().parent
+ manifest: dict[str, Any] = {}
+ try:
+ manifest = json.loads((folder / "engine-component.json").read_text(encoding="utf-8"))
+ except (OSError, ValueError):
+ pass
+ sha = None
+ for entry in manifest.get("files") or []:
+ if entry.get("path") == manifest.get("entrypoint", Path(exe).name):
+ sha = entry.get("sha256")
+ return {"version": manifest.get("version"), "backend": manifest.get("backend"),
+ "build_id": manifest.get("build_id"), "sha256": sha,
+ "tuning_epoch": int(manifest.get("tuning_epoch") or 0), "path": str(exe)}
+
+
+def model_identity(files: list[str | os.PathLike[str]]) -> dict[str, Any]:
+ """The model file(s): size and a digest of the head, middle and tail of the first shard (the whole file would
+ mean reading tens of gigabytes before every tune)."""
+ from strata_control import tune_history
+ out: list[dict[str, Any]] = []
+ for f in files[:2]:
+ ident = tune_history.file_identity(Path(f))
+ out.append({"name": Path(f).name, "bytes": ident.get("bytes"), "digest": ident.get("digest"),
+ "method": ident.get("method")})
+ first = out[0] if out else {}
+ return {"files": out, "sha256_shard1": first.get("digest"), "bytes": first.get("bytes")}
+
+
+def stable_hash(obj: Any) -> str:
+ return hashlib.sha256(json.dumps(obj, sort_keys=True, default=str).encode()).hexdigest()[:16]
diff --git a/strata_control/tune_session.py b/strata_control/tune_session.py
new file mode 100644
index 000000000..6c1759ac2
--- /dev/null
+++ b/strata_control/tune_session.py
@@ -0,0 +1,478 @@
+"""Running one engine configuration and measuring it, for the tuner.
+
+A *session* is what the tuner needs from the outside world: start an engine with these arguments and environment, run the
+fixed request set, report numbers, stop. The real session (`WorkerSession`) starts Strata's own worker (``serve.server``)
+on a **copy** of the user's run configuration and talks to it over HTTP, so the engine, the queueing and the prompt
+handling are exactly the ones the user gets. The numbers come from the engine's own clock (the ``timings`` block of the
+reply), not from this process's stopwatch. The stub session in the tests implements the same two methods.
+
+Never invents a number: an engine that does not start, answers nothing or answers too little raises `StartFailed` or
+returns a result whose ``status`` says why, and the tuner records that as the candidate's result.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import random
+import re
+import secrets
+import socket
+import statistics
+import subprocess
+import sys
+import tempfile
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Iterator, Protocol
+
+from strata_control import tune_machine
+
+# --------------------------------------------------------------------------- the contract
+
+
+class StartFailed(RuntimeError):
+ """The engine did not come up. ``status``: FAIL_BOOT | OOM | UNSUPPORTED | TIMEOUT."""
+
+ def __init__(self, status: str, reason: str) -> None:
+ super().__init__(reason)
+ self.status = status
+ self.reason = reason
+
+
+@dataclass
+class RequestSet:
+ """The fixed work every run does, so two configurations are compared on the same requests."""
+
+ warmups: int = 1
+ decodes: int = 3
+ decode_tokens: int = 200
+ pp_tokens: int = 4096
+ long_tokens: int = 0 # 0 = no long prompt
+
+
+@dataclass
+class RunResult:
+ status: str = "PASS" # PASS | FAIL_BOOT | OOM | UNSUPPORTED | TIMEOUT | NO_TOKENS
+ reason: str = ""
+ load_s: float | None = None
+ decode_tok_s: float | None = None # median of the measured decodes
+ decode_runs: list[float] = field(default_factory=list)
+ pp_tok_s: float | None = None # the warm prompt (the second one; the first is cold)
+ pp_cold_tok_s: float | None = None
+ ttft_s: float | None = None
+ pp_long_tok_s: float | None = None
+ rss_peak_mib: float | None = None
+ vram_used_mib: float | None = None # this run's total graphics memory in use (all cards, absolute)
+ vram_added_mib: float | None = None # ... minus what was in use before the engine started
+ min_avail_mib: float | None = None # lowest free system RAM seen while the engine ran
+ facts: dict[str, Any] = field(default_factory=dict)
+ wall_s: float = 0.0
+
+ def to_dict(self) -> dict[str, Any]:
+ return dict(self.__dict__)
+
+
+class Engine(Protocol):
+ facts: dict[str, Any]
+
+ def measure(self, spec: RequestSet) -> RunResult: ...
+
+ def decode_once(self, tune: dict[str, Any] | None = None, tokens: int = 200) -> float | None: ...
+
+
+class Session(Protocol):
+ def engine(self, args: list[str], env: dict[str, str | None]) -> contextlib.AbstractContextManager[Engine]: ...
+
+ def system(self) -> dict[str, Any]: ...
+
+
+# --------------------------------------------------------------------------- the engine log
+
+_FACTS = [
+ ("slots", re.compile(r"expert cache (\d+) slots"), int),
+ ("workers", re.compile(r"(\d+) (?:expert-)?pool workers"), int),
+ ("cpu_threads", re.compile(r"(\d+) CPU threads"), int),
+ ("pcie_gbs", re.compile(r"PCIe probe: ([\d.]+) GB/s"), float),
+ ("pcie_frac", re.compile(r"-> pcie_frac ([\d.]+)"), float),
+ ("chunk", re.compile(r"prompt chunk auto: (\d+) tokens"), int),
+ ("avail_gib", re.compile(r"available ([\d.]+) GiB \(MemAvailable"), float),
+ ("loaded_gib", re.compile(r"loaded ([\d.]+) GiB at"), float),
+]
+
+
+def parse_facts(text: str) -> dict[str, Any]:
+ """What the engine's own log says about the setup it chose (the last value of each fact wins)."""
+ facts: dict[str, Any] = {}
+ for key, rx, cast in _FACTS:
+ found = rx.findall(text)
+ if found:
+ try:
+ facts[key] = cast(found[-1])
+ except ValueError:
+ pass
+ if "workers" not in facts and "cpu_threads" in facts:
+ facts["workers"] = facts["cpu_threads"]
+ low = text.lower()
+ facts["resident_ram"] = bool(re.search(r"resident[- ](?:ram|experts)|low-ram mode|resident ram", low))
+ facts["hybrid_experts"] = "hybrid experts" in low or "hybrid:" in low
+ facts["unknown_argument"] = bool(re.search(r"unknown argument|unrecognized (?:argument|option)", low))
+ return facts
+
+
+def failure_kind(text: str, returncode: int | None) -> tuple[str, str]:
+ """Classify an engine that ended before it was ready: (status, one plain line)."""
+ low = text.lower()
+ lines = [ln.strip() for ln in text.splitlines() if re.search(
+ r"unknown argument|unrecognized|invalid value|out of memory|memory guard|cannot|failed|error|refus|killed", ln, re.I)]
+ reason = " | ".join(lines[:3])[:300]
+ if re.search(r"unknown argument|unrecognized (argument|option)", low):
+ return "UNSUPPORTED", reason or "the engine does not accept one of the settings"
+ if re.search(r"out of memory|memory guard|cannot allocate|std::bad_alloc|oom", low) or returncode in (-9, 137, 3221226505):
+ return "OOM", reason or "the engine ran out of memory"
+ return "FAIL_BOOT", reason or f"the engine stopped while starting (exit {returncode})"
+
+
+# --------------------------------------------------------------------------- prompts
+
+_SENTENCES = (
+ "The harbour town woke slowly, with fishing boats knocking against the wooden piers.",
+ "A small team measured how long each step of the process took and wrote the numbers in a notebook.",
+ "Rain fell on the old railway station while a clerk sorted letters by hand.",
+ "The recipe asked for two cups of flour, a pinch of salt and patience.",
+ "In the library, a quiet reader turned pages while the clock in the hall struck three.",
+ "Engineers compared the two bridges and noted how each handled wind and weight.",
+ "The orchard produced more apples than the village could eat, so the surplus went to the city market.",
+ "She packed a map, a flask of tea and a spare pair of boots for the long walk north.",
+ "Each morning the baker lit the oven before dawn and left the shop door unlocked for the milkman.",
+ "A careful gardener keeps a record of when each seed is planted and when it first sprouts.",
+ "The museum's new wing displayed instruments that once guided ships across open water.",
+ "Traffic slowed near the tunnel entrance, and the radio suggested taking the coast road instead.",
+ "Two neighbours argued kindly over whose tomato plants had grown taller that summer.",
+ "The orchestra tuned together, a single note spreading through the hall until the conductor raised a hand.",
+ "He wrote down every question he had about the machine before opening its case.",
+ "A river of lanterns floated past the bridge as the festival reached its final evening.",
+)
+
+
+def make_prompt(tokens: int, salt: str, chars_per_token: float = 4.4) -> str:
+ """A prompt of about ``tokens`` tokens that no earlier run has seen: its first line is the salt, so a cached prefix is
+ never reused, and the rest is shuffled prose."""
+ rng = random.Random(salt)
+ target = int(tokens * chars_per_token)
+ parts = [f"Reference {salt}."]
+ size = len(parts[0])
+ while size < target:
+ s = rng.choice(_SENTENCES)
+ parts.append(s)
+ size += len(s) + 1
+ parts.append("Now answer in one short sentence: what is the main subject of the text above?")
+ return " ".join(parts)
+
+
+DECODE_PROMPTS = (
+ "Write a long, detailed story about a lighthouse keeper who finds a message in a bottle. Keep going without stopping.",
+ "Explain step by step how a bicycle works, covering the frame, wheels, gears, chain and brakes in depth.",
+)
+
+
+# --------------------------------------------------------------------------- a flock for the box locks
+
+class FileLock:
+ """An exclusive advisory lock on a file, held around each engine run (the lent boxes' /data/gpu.lock rule)."""
+
+ def __init__(self, path: str | os.PathLike[str], wait_s: float = 5400.0, log: Callable[[str], None] = lambda s: None) -> None:
+ self.path = str(path)
+ self.wait_s = wait_s
+ self.log = log
+ self._fh = None
+
+ def __enter__(self) -> "FileLock":
+ Path(self.path).parent.mkdir(parents=True, exist_ok=True)
+ self._fh = open(self.path, "a+")
+ deadline = time.time() + self.wait_s
+ told = False
+ while True:
+ try:
+ if os.name == "nt":
+ import msvcrt
+ self._fh.seek(0)
+ msvcrt.locking(self._fh.fileno(), msvcrt.LK_NBLCK, 1)
+ else:
+ import fcntl
+ fcntl.flock(self._fh.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+ return self
+ except OSError:
+ if time.time() > deadline:
+ self._fh.close()
+ raise StartFailed("TIMEOUT", f"the lock {self.path} was not free within {int(self.wait_s)} s")
+ if not told:
+ self.log(f"waiting for the lock {self.path}")
+ told = True
+ time.sleep(2.0)
+
+ def __exit__(self, *exc: object) -> None:
+ try:
+ if os.name == "nt":
+ import msvcrt
+ self._fh.seek(0)
+ msvcrt.locking(self._fh.fileno(), msvcrt.LK_UNLCK, 1)
+ else:
+ import fcntl
+ fcntl.flock(self._fh.fileno(), fcntl.LOCK_UN)
+ except OSError:
+ pass
+ finally:
+ if self._fh:
+ self._fh.close()
+
+
+# --------------------------------------------------------------------------- the real session
+
+def _free_port() -> int:
+ with socket.socket() as s:
+ s.bind(("127.0.0.1", 0))
+ return s.getsockname()[1]
+
+
+class WorkerEngine:
+ """One running worker and the requests that measure it."""
+
+ def __init__(self, session: "WorkerSession", proc: subprocess.Popen, port: int, key: str, log_files: list[Path],
+ load_s: float, vram_before: int | None, log: Callable[[str], None]) -> None:
+ self.s = session
+ self.proc = proc
+ self.port = port
+ self.key = key
+ self.log_files = log_files
+ self.load_s = load_s
+ self.vram_before = vram_before
+ self.log = log
+ self.model = "strata-local"
+ self.min_avail: float | None = None
+ self.facts: dict[str, Any] = parse_facts(self.log_text())
+ self.salt_n = 0
+ self._model_id()
+
+ # ---- helpers
+ def log_text(self) -> str:
+ out = []
+ for f in self.log_files:
+ try:
+ out.append(f.read_text(encoding="utf-8", errors="replace"))
+ except OSError:
+ pass
+ return "\n".join(out)
+
+ def _model_id(self) -> None:
+ try:
+ req = urllib.request.Request(f"http://127.0.0.1:{self.port}/v1/models", headers=self._h())
+ with urllib.request.urlopen(req, timeout=10) as r:
+ data = json.loads(r.read())
+ self.model = ((data.get("data") or [{}])[0]).get("id") or self.model
+ except Exception: # noqa: BLE001
+ pass
+
+ def _h(self) -> dict[str, str]:
+ return {"content-type": "application/json", "authorization": f"Bearer {self.key}"}
+
+ def _sample_mem(self) -> None:
+ a = tune_machine.memory().get("available_mib")
+ if a is not None:
+ self.min_avail = a if self.min_avail is None else min(self.min_avail, a)
+
+ def chat(self, prompt: str, max_tokens: int, tune: dict[str, Any] | None = None, timeout: float = 1800.0) -> dict[str, Any]:
+ body: dict[str, Any] = {"model": self.model, "stream": False, "max_tokens": max_tokens, "temperature": 0.0,
+ "messages": [{"role": "user", "content": prompt}], "strata_checkpoint": False}
+ if tune:
+ body["strata_tune"] = tune
+ req = urllib.request.Request(f"http://127.0.0.1:{self.port}/v1/chat/completions",
+ data=json.dumps(body).encode(), headers=self._h(), method="POST")
+ try:
+ with urllib.request.urlopen(req, timeout=timeout) as r:
+ data = json.loads(r.read())
+ except urllib.error.HTTPError as e:
+ raise StartFailed("NO_TOKENS", f"the worker refused the request ({e.code}): {e.read()[:200]!r}") from None
+ except (urllib.error.URLError, OSError, ValueError) as e:
+ code = self.proc.poll()
+ status, why = failure_kind(self.log_text()[-4000:], code) if code is not None else ("TIMEOUT", str(e))
+ raise StartFailed(status, f"the engine did not answer: {why}") from None
+ self._sample_mem()
+ return data
+
+ # ---- measurements
+ def decode_once(self, tune: dict[str, Any] | None = None, tokens: int = 200) -> float | None:
+ for prompt in DECODE_PROMPTS:
+ data = self.chat(prompt, tokens, tune)
+ t = data.get("timings") or {}
+ n, rate = t.get("predicted_n"), t.get("predicted_per_second")
+ if n and rate and n >= max(32, tokens // 2):
+ return float(rate)
+ return None
+
+ def prompt_once(self, tokens: int) -> dict[str, float | None]:
+ self.salt_n += 1
+ salt = secrets.token_hex(6)
+ text = make_prompt(tokens, salt, self.s.chars_per_token)
+ data = self.chat(text, 8)
+ t = data.get("timings") or {}
+ usage = data.get("usage") or {}
+ pt = usage.get("prompt_tokens")
+ if isinstance(pt, int) and pt > 64 and not self.s.calibrated:
+ self.s.chars_per_token = max(2.0, min(8.0, self.s.chars_per_token * tokens / pt))
+ self.s.calibrated = True
+ rate = t.get("prompt_per_second")
+ # a prompt that was partly cached is not a prompt-speed measurement
+ if t.get("cache_n") and t.get("prompt_n") and t["cache_n"] > 0.1 * (t["prompt_n"] + t["cache_n"]):
+ rate = None
+ ms = t.get("prompt_ms")
+ return {"rate": float(rate) if rate else None, "ttft_s": float(ms) / 1000.0 if ms else None,
+ "tokens": pt if isinstance(pt, int) else None}
+
+ def measure(self, spec: RequestSet) -> RunResult:
+ t0 = time.time()
+ res = RunResult(load_s=self.load_s, facts=dict(self.facts))
+ for _ in range(spec.warmups):
+ self.decode_once(None, 64)
+ runs: list[float] = []
+ for _ in range(spec.decodes):
+ r = self.decode_once(None, spec.decode_tokens)
+ if r:
+ runs.append(r)
+ res.decode_runs = [round(x, 3) for x in runs]
+ if not runs:
+ res.status, res.reason = "NO_TOKENS", "the engine produced no measurable decode"
+ else:
+ res.decode_tok_s = round(statistics.median(runs), 3)
+ if spec.pp_tokens:
+ cold = self.prompt_once(spec.pp_tokens)
+ warm = self.prompt_once(spec.pp_tokens)
+ res.pp_cold_tok_s = cold["rate"]
+ res.pp_tok_s, res.ttft_s = warm["rate"], warm["ttft_s"]
+ if spec.long_tokens:
+ res.pp_long_tok_s = self.prompt_once(spec.long_tokens)["rate"]
+ res.rss_peak_mib = tune_engine_peak(self.proc.pid)
+ used = tune_machine.gpu_used_mib()
+ if used is not None:
+ res.vram_used_mib = used
+ if self.vram_before is not None:
+ res.vram_added_mib = used - self.vram_before
+ res.min_avail_mib = self.min_avail
+ res.facts = dict(parse_facts(self.log_text()))
+ res.wall_s = round(time.time() - t0, 1)
+ return res
+
+
+def tune_engine_peak(pid: int) -> float | None:
+ try:
+ from strata_control.tune_engine import process_tree_peak_mib
+ return process_tree_peak_mib(pid)
+ except Exception: # noqa: BLE001
+ return None
+
+
+class WorkerSession:
+ """Starts ``serve.server`` on a copy of the run configuration for each configuration the tuner asks for."""
+
+ def __init__(self, *, base_config: dict[str, Any], python: str | os.PathLike[str] | None = None,
+ serve_dir: str | os.PathLike[str], workdir: str | os.PathLike[str] | None = None,
+ boot_timeout_s: float = 900.0, lock: Callable[[], contextlib.AbstractContextManager] | None = None,
+ log: Callable[[str], None] = lambda s: None, extra_env: dict[str, str] | None = None) -> None:
+ self.base = json.loads(json.dumps(base_config))
+ self.python = str(python or sys.executable)
+ self.serve_dir = Path(serve_dir)
+ self.workdir = Path(workdir) if workdir else Path(tempfile.mkdtemp(prefix="strata-tune-"))
+ self.workdir.mkdir(parents=True, exist_ok=True)
+ self.boot_timeout_s = boot_timeout_s
+ self.lock = lock
+ self.log = log
+ self.extra_env = dict(extra_env or {})
+ self.chars_per_token = 4.4
+ self.calibrated = False
+ self.runs = 0
+
+ def system(self) -> dict[str, Any]:
+ return {"memory": tune_machine.memory(), "gpus": tune_machine.gpus(), "cpu": tune_machine.cpu()}
+
+ @contextlib.contextmanager
+ def engine(self, args: list[str], env: dict[str, str | None]) -> Iterator[WorkerEngine]:
+ with contextlib.ExitStack() as stack:
+ if self.lock is not None:
+ stack.enter_context(self.lock())
+ self.runs += 1
+ n = self.runs
+ cfg = json.loads(json.dumps(self.base))
+ cfg["args"] = list(args)
+ cenv = dict(cfg.get("env") or {})
+ for k, v in env.items():
+ if v is None:
+ cenv.pop(k, None)
+ else:
+ cenv[k] = str(v)
+ cfg["env"] = cenv
+ key = secrets.token_hex(16)
+ port = _free_port()
+ engine_log = self.workdir / f"engine-{n}.log"
+ worker_log = self.workdir / f"worker-{n}.log"
+ engine_log.write_text("")
+ cfg.update({"api_key": key, "port": port, "host": "127.0.0.1", "open_browser": False, "log": str(engine_log)})
+ cfg_path = self.workdir / f"run-{n}.json"
+ cfg_path.write_text(json.dumps(cfg, indent=1), encoding="utf-8")
+ spawn_env = dict(os.environ)
+ spawn_env.update(self.extra_env)
+ for k, v in env.items():
+ if v is None:
+ spawn_env.pop(k, None)
+ spawn_env["PYTHONUNBUFFERED"] = "1"
+ spawn_env["STRATA_NO_PRESET"] = "1" # measure the configuration as given, not a saved tuning on top
+ before = tune_machine.gpu_used_mib()
+ wl = open(worker_log, "w")
+ argv = [self.python, "-m", "serve.server", "--engine", "strata", "--config", str(cfg_path),
+ "--host", "127.0.0.1", "--port", str(port)]
+ t0 = time.time()
+ try:
+ from serve import lifeline
+ proc = lifeline.popen(argv, "worker", cwd=str(self.serve_dir), env=spawn_env, stdout=wl,
+ stderr=subprocess.STDOUT)
+ except OSError as e:
+ wl.close()
+ raise StartFailed("FAIL_BOOT", f"the worker could not be started: {e}") from None
+ try:
+ deadline = t0 + self.boot_timeout_s
+ ready = False
+ while time.time() < deadline:
+ if proc.poll() is not None:
+ text = (engine_log.read_text(errors="replace") if engine_log.exists() else "") + "\n" + \
+ worker_log.read_text(errors="replace")
+ status, why = failure_kind(text, proc.returncode)
+ raise StartFailed(status, why)
+ try:
+ req = urllib.request.Request(f"http://127.0.0.1:{port}/health",
+ headers={"authorization": f"Bearer {key}"})
+ with urllib.request.urlopen(req, timeout=2) as r:
+ if r.status == 200:
+ ready = True
+ break
+ except (urllib.error.URLError, OSError):
+ time.sleep(0.5)
+ if not ready:
+ raise StartFailed("TIMEOUT", f"the engine was not ready within {int(self.boot_timeout_s)} s")
+ eng = WorkerEngine(self, proc, port, key, [engine_log, worker_log], time.time() - t0, before, self.log)
+ yield eng
+ finally:
+ try:
+ if proc.poll() is None:
+ proc.terminate()
+ try:
+ proc.wait(timeout=60)
+ except subprocess.TimeoutExpired:
+ proc.kill()
+ proc.wait(timeout=30)
+ finally:
+ wl.close()
+ # the engine gives its graphics memory back a moment after it exits
+ time.sleep(3.0)
diff --git a/tests/tuning/stub_session.py b/tests/tuning/stub_session.py
new file mode 100644
index 000000000..7d954c7ec
--- /dev/null
+++ b/tests/tuning/stub_session.py
@@ -0,0 +1,90 @@
+"""A stand-in for `tune_session.WorkerSession`: speeds are computed from the flags it is given, so the tuner's decisions can be
+tested without an engine. The numbers mean nothing about any hardware."""
+
+from __future__ import annotations
+
+import contextlib
+import random
+from typing import Any, Callable
+
+from strata_control.tune_session import RequestSet, RunResult, StartFailed
+
+
+class StubEngine:
+ def __init__(self, session: "StubSession", args: list[str], env: dict[str, Any]) -> None:
+ self.s = session
+ self.args = args
+ self.env = env
+ self.facts = dict(session.facts)
+
+ def _rate(self, tune: dict[str, Any] | None = None) -> float:
+ base = self.s.model(self.args, self.env, tune)
+ return base * (1.0 + self.s.rng.gauss(0.0, self.s.noise))
+
+ def decode_once(self, tune: dict[str, Any] | None = None, tokens: int = 200) -> float | None:
+ self.s.decodes += 1
+ return self._rate(tune)
+
+ def measure(self, spec: RequestSet) -> RunResult:
+ d = [self._rate() for _ in range(spec.decodes)]
+ import statistics
+ pp = self.s.pp(self.args, self.env) * (1.0 + self.s.rng.gauss(0.0, self.s.noise / 3))
+ r = RunResult(load_s=20.0, decode_tok_s=statistics.median(d), decode_runs=d, pp_tok_s=pp, pp_cold_tok_s=pp * 0.8,
+ ttft_s=4096 / pp, rss_peak_mib=self.s.rss(self.args, self.env), vram_used_mib=self.s.vram(self.args),
+ vram_added_mib=self.s.vram(self.args) - 400, min_avail_mib=self.s.avail - self.s.rss(self.args, self.env),
+ facts=dict(self.facts), wall_s=self.s.run_s)
+ return r
+
+
+class StubSession:
+ def __init__(self, *, model: Callable[..., float], pp: Callable[..., float] | None = None, noise: float = 0.005,
+ seed: int = 1, facts: dict[str, Any] | None = None, fail: Callable[[list[str], dict], StartFailed | None] | None = None,
+ rss: Callable[..., float] | None = None, vram: Callable[..., float] | None = None, avail: float = 40000,
+ run_s: float = 90.0, clock: Any = None) -> None:
+ self.clock = clock
+ self.model = model
+ self.pp = pp or (lambda a, e: 1500.0)
+ self.noise = noise
+ self.rng = random.Random(seed)
+ self.facts = facts or {"workers": 6, "slots": 3000, "resident_ram": False}
+ self.fail = fail
+ self.rss = rss or (lambda a, e: 12000.0)
+ self.vram = vram or (lambda a: 10000.0)
+ self.avail = avail
+ self.run_s = run_s
+ self.runs: list[tuple[list[str], dict]] = []
+ self.decodes = 0
+ self.mem = {"total_mib": 64000, "available_mib": avail}
+
+ def system(self) -> dict[str, Any]:
+ return {"memory": dict(self.mem), "gpus": [{"vendor": "nvidia", "index": 0, "name": "Stub GPU", "vram_total_mib": 12000,
+ "vram_used_mib": 400, "driver": "1"}], "cpu": {"model": "stub", "logical": 12, "hybrid": False}}
+
+ @contextlib.contextmanager
+ def engine(self, args: list[str], env: dict[str, Any]):
+ self.runs.append((list(args), dict(env)))
+ if self.clock is not None:
+ self.clock.t += self.run_s
+ if self.fail:
+ err = self.fail(args, env)
+ if err:
+ raise err
+ yield StubEngine(self, list(args), dict(env))
+
+
+def flag(args: list[str], name: str) -> str | None:
+ for i, a in enumerate(args):
+ if a == name:
+ return args[i + 1] if i + 1 < len(args) and not str(args[i + 1]).startswith("--") else ""
+ return None
+
+
+class FakeClock:
+ def __init__(self) -> None:
+ self.t = 0.0
+
+ def __call__(self) -> float:
+ return self.t
+
+ def sleep(self, s: float) -> None:
+ self.t += s
diff --git a/tests/tuning/test_autotune.py b/tests/tuning/test_autotune.py
new file mode 100644
index 000000000..1e95d3042
--- /dev/null
+++ b/tests/tuning/test_autotune.py
@@ -0,0 +1,332 @@
+"""The auto-tuner's decisions, tested with a stub engine whose speed is computed from the flags it is given."""
+
+from __future__ import annotations
+
+import threading
+import unittest
+
+from strata_control import autotune, tune_knobs
+from strata_control.tune_session import StartFailed
+
+from tests.tuning.stub_session import FakeClock, StubSession, flag
+
+BASE = ["--pack", "P", "--native", "m.gguf", "--expert-cache", "auto", "--prefill", "auto", "--spec", "4",
+ "--spec-min-p", "0.5", "--mtp", "D", "--max-context", "131072", "--kv", "int8", "--kv-resident", "32768",
+ "--vram-reserve-mib", "1536"]
+
+
+def make_ctx(**kw):
+ ctx = tune_knobs.Context(backend="cuda", family="flash-next", gpu_count=1, vram_mib=12000, ram_gib=64, model_gib=60.0,
+ context_tokens=131072, base_args=list(BASE), logical_threads=12, **kw)
+ ctx.facts = {"workers": 6, "slots": 3000}
+ return ctx
+
+
+def speed_with(gains: dict[str, float], base=60.0):
+ """tok/s as a function of the flags: each (flag, value) in `gains` multiplies the speed."""
+ def model(args, env, tune=None):
+ v = base
+ for (f, val), g in gains.items():
+ if f.startswith("STRATA_"):
+ if env.get(f) == val:
+ v *= g
+ elif flag(args, f) == val:
+ v *= g
+ if tune:
+ for k, g in (gains.get(("tune", None)) or {}).items() if False else []:
+ pass
+ return v
+ return model
+
+
+def run_tuner(model, *, opts=None, ctx=None, clock=None, session_kw=None, cancel=None, progress=None, **kw):
+ clock = clock or FakeClock()
+ session = StubSession(model=model, clock=clock, **(session_kw or {}))
+ t = autotune.Tuner(session, BASE, {}, ctx or make_ctx(), opts or autotune.Options(), clock=clock, sleep=clock.sleep,
+ system=session.system, total_ram_mib=64000, total_vram_mib=12000, quiet=lambda: None,
+ cancel=cancel, progress=progress, **kw)
+ return t, session, t.run()
+
+
+class RulesTest(unittest.TestCase):
+ def test_never_list(self):
+ ctx = make_ctx(arch="gfx1201")
+ bad = [({"--expert-cache": 0}, {}), ({"--kv-resident": 20480}, {}), ({"--pcie-frac": 0.75}, {}),
+ ({"--spec": 6}, {}), ({"--spec": 2}, {}), ({"--lookup-chain": 4}, {}), ({"--adapt-every": 100000}, {}),
+ ({"--prefill": 512}, {}), ({"--ple-io": "ram"}, {}), ({}, {"STRATA_SH_STREAM": "1"}),
+ ({}, {"STRATA_RDNA2_SGEMM": "all"}), ({}, {"STRATA_HIP_WMMA": "1"}), ({"--pool-workers": 8}, {})]
+ for args, env in bad:
+ self.assertTrue(tune_knobs.check_setting(args, env, ctx), (args, env))
+ ok = [({"--spec": 3}, {}), ({"--host-core": "last"}, {}), ({"--pool-workers": 4}, {}), ({"--prefill": "auto:32768"}, {}),
+ ({"--adapt-every": 1, "--adapt-swaps": 80, "--adapt-decay": 0.97}, {}), ({"--pcie-frac": 0.2}, {})]
+ for args, env in ok:
+ self.assertEqual(tune_knobs.check_setting(args, env, ctx), [], (args, env))
+
+ def test_hybrid_cpu_affinity_never(self):
+ ctx = make_ctx()
+ ctx.hybrid_cpu = True
+ self.assertTrue(tune_knobs.check_setting({"--pool-affinity": "auto"}, {}, ctx))
+ ctx.hybrid_cpu = False
+ self.assertEqual(tune_knobs.check_setting({"--pool-affinity": "auto"}, {}, ctx), [])
+
+ def test_boolean_flags_are_present_or_absent(self):
+ self.assertEqual(tune_knobs.apply_to_argv(["--a", "1"], {"--kv-grow": True}), ["--a", "1", "--kv-grow"])
+ self.assertEqual(tune_knobs.apply_to_argv(["--kv-grow", "--a", "1"], {"--kv-grow": None}), ["--a", "1"])
+ self.assertNotIn("0", tune_knobs.apply_to_argv(["--kv-grow"], {"--kv-grow": False}))
+
+ def test_candidates_are_single_knob_changes_of_the_users_config(self):
+ ctx = make_ctx(allow_placement=True)
+ arms, skipped = tune_knobs.plan_arms(ctx, mode="thorough")
+ self.assertTrue(arms)
+ for p in arms:
+ argv = tune_knobs.apply_to_argv(BASE, p.args)
+ # everything the user had that the arm does not name is untouched (Rule 1)
+ for f in ("--expert-cache", "--kv", "--spec-min-p", "--vram-reserve-mib", "--max-context"):
+ if f not in p.args:
+ self.assertEqual(flag(argv, f), flag(BASE, f), (p.arm.id, f))
+ self.assertEqual(tune_knobs.check_setting(p.args, p.env, ctx), [])
+
+ def test_answer_changing_arms_need_the_users_tick(self):
+ ctx = make_ctx()
+ ids = {p.arm.id for p in tune_knobs.plan_arms(ctx, mode="thorough")[0]}
+ self.assertNotIn("spec3", ids)
+ self.assertNotIn("adapt_async", ids)
+ ctx2 = make_ctx(allow_placement=True)
+ self.assertIn("spec3", {p.arm.id for p in tune_knobs.plan_arms(ctx2, mode="thorough")[0]})
+ ctx3 = make_ctx(allow_nonrepeatable=True)
+ ctx3.facts = {"workers": 6, "resident_ram": True}
+ self.assertIn("adapt_async", {p.arm.id for p in tune_knobs.plan_arms(ctx3, mode="thorough")[0]})
+
+ def test_engine_without_a_flag_drops_the_arm_with_a_reason(self):
+ ctx = make_ctx()
+ ctx.engine_flags = ["--spec"]
+ arms, skipped = tune_knobs.plan_arms(ctx, mode="thorough")
+ self.assertFalse(any(p.arm.id == "host_core_last" for p in arms))
+ self.assertTrue(any("does not accept" in s["reason"] for s in skipped))
+
+ def test_qwen36_and_sycl_lists(self):
+ q = make_ctx()
+ q.family = "qwen36"
+ q.facts = {"workers": 6, "hybrid_experts": True}
+ ids = [p.arm.id for p in tune_knobs.plan_arms(q, mode="thorough")[0]]
+ self.assertIn("q36_workers_explicit", ids)
+ self.assertNotIn("host_core_last", ids)
+ s = make_ctx(allow_placement=True)
+ s.backend = "sycl"
+ ids = [p.arm.id for p in tune_knobs.plan_arms(s, mode="thorough")[0]]
+ self.assertEqual(set(ids) - {"adapt_decay_09", "pcie_start_02"}, set())
+
+ def test_workers_arm_never_goes_below_a_quarter(self):
+ c = make_ctx()
+ c.facts = {"workers": 4}
+ self.assertEqual(tune_knobs.dynamic_value("workers-2", c), 2)
+ c.facts = {"workers": 2}
+ self.assertIsNone(tune_knobs.dynamic_value("workers-2", c))
+
+
+class TunerTest(unittest.TestCase):
+ def test_finds_a_real_gain_and_changes_one_knob(self):
+ model = speed_with({("--host-core", "last"): 1.08})
+ t, s, r = run_tuner(model, ctx=make_ctx())
+ self.assertEqual(r.outcome, "improved", r.notes)
+ self.assertEqual(r.settings["args"], {"--host-core": "last"})
+ self.assertAlmostEqual(r.gain_pct, 8.0, delta=2.0)
+ self.assertEqual(r.answers["class"], "exact")
+ for args, env in s.runs: # every run kept the user's own flags
+ self.assertEqual(flag(args, "--expert-cache"), "auto")
+ self.assertEqual(flag(args, "--kv"), "int8")
+ self.assertLessEqual(r.seconds, 1200 + 90 * 2)
+
+ def test_no_gain_keeps_the_default(self):
+ t, s, r = run_tuner(lambda a, e, tune=None: 60.0, session_kw={"noise": 0.02})
+ self.assertEqual(r.outcome, "default_confirmed")
+ self.assertEqual(r.settings, {"args": {}, "env": {}, "per_request": {}})
+ self.assertIn("already the fastest", r.message)
+
+ def test_a_gain_below_the_margin_is_not_taken(self):
+ model = speed_with({("--host-core", "last"): 1.02})
+ t, s, r = run_tuner(model, session_kw={"noise": 0.001})
+ self.assertEqual(r.settings["args"], {})
+
+ def test_losing_candidates_are_dropped_after_one_loss(self):
+ model = speed_with({("--host-core", "last"): 0.85})
+ t, s, r = run_tuner(model, session_kw={"noise": 0.001})
+ arm = [a for a in r.arms if a["id"] == "host_core_last"][0]
+ self.assertEqual(arm["status"], "dropped")
+ self.assertEqual(sum(1 for args, _ in s.runs if flag(args, "--host-core") == "last"), 1)
+
+ def test_machine_drift_is_not_mistaken_for_a_gain(self):
+ clock = FakeClock()
+ counter = {"n": 0}
+
+ def model(args, env, tune=None): # the machine slows 1.2% per engine start
+ return 60.0 * (1.0 - 0.012 * len(session.runs)) * (1.03 if flag(args, "--host-core") == "last" else 1.0)
+ session = StubSession(model=model, clock=clock, noise=0.0005)
+ t = autotune.Tuner(session, BASE, {}, make_ctx(), autotune.Options(), clock=clock, sleep=clock.sleep, system=session.system,
+ total_ram_mib=64000, quiet=lambda: None)
+ r = t.run()
+ self.assertEqual(r.settings["args"], {}, r.notes)
+
+ def test_candidate_that_does_not_fit_is_never_started(self):
+ model = speed_with({("--host-core", "last"): 1.10})
+ clock = FakeClock()
+ session = StubSession(model=model, clock=clock, avail=9000, rss=lambda a, e: 12000.0)
+ calls = {"n": 0}
+ real = session.system
+
+ def system():
+ out = real()
+ out["memory"]["available_mib"] = 40000 if not session.runs else 9000 # after the base run only 9 GB is free
+ return out
+ t = autotune.Tuner(session, BASE, {}, make_ctx(), autotune.Options(wait_ram_s=30), clock=clock, sleep=clock.sleep,
+ system=system, total_ram_mib=64000, quiet=lambda: None)
+ r = t.run()
+ self.assertEqual(len(session.runs), 1, "only the base was started")
+ self.assertEqual(r.outcome, "default_confirmed")
+ self.assertTrue(any(a["status"] == "skipped" and "memory" in a["reason"] for a in r.arms))
+
+ def test_first_oom_stops_the_search(self):
+ def fail(args, env):
+ return StartFailed("OOM", "out of memory") if flag(args, "--host-core") == "last" else None
+ t, s, r = run_tuner(speed_with({}), session_kw={"fail": fail})
+ self.assertTrue(any("ran out of memory" in n for n in r.notes))
+ self.assertEqual(sum(1 for a, _ in s.runs if flag(a, "--host-core") == "last"), 1)
+ self.assertEqual(r.settings["args"], {})
+
+ def test_unsupported_candidate_fails_alone(self):
+ def fail(args, env):
+ return StartFailed("UNSUPPORTED", "unknown argument: --host-core") if flag(args, "--host-core") else None
+ ctx = make_ctx()
+ ctx.facts = {"workers": 6}
+ t, s, r = run_tuner(speed_with({("--pool-workers", "4"): 1.1}), ctx=ctx, session_kw={"fail": fail})
+ failed = [a for a in r.arms if a["status"] == "failed"]
+ self.assertTrue(failed and "UNSUPPORTED" in failed[0]["reason"])
+ self.assertEqual(r.settings["args"], {"--pool-workers": 4})
+
+ def test_room_goal_refuses_a_faster_candidate_that_takes_more_memory(self):
+ model = speed_with({("--host-core", "last"): 1.1})
+ rss = lambda a, e: 20000.0 if flag(a, "--host-core") == "last" else 12000.0
+ t, s, r = run_tuner(model, opts=autotune.Options(goal="room", ram_wish_pct=20, reserve_mib=1536), session_kw={"rss": rss})
+ self.assertEqual(r.settings["args"], {})
+ self.assertTrue(any("more memory" in a["reason"] for a in r.arms))
+ t, s, r = run_tuner(model, opts=autotune.Options(goal="speed"), session_kw={"rss": rss})
+ self.assertEqual(r.settings["args"], {"--host-core": "last"})
+
+ def test_cancel_changes_nothing(self):
+ cancel = threading.Event()
+ model = speed_with({("--host-core", "last"): 1.1})
+ n = {"i": 0}
+
+ def progress(p):
+ if p["stage"] == "rounds":
+ cancel.set()
+ t, s, r = run_tuner(model, cancel=cancel, progress=progress)
+ self.assertEqual(r.outcome, "cancelled")
+ self.assertEqual(r.settings["args"], {})
+
+ def test_the_time_chosen_bounds_the_number_of_restarts(self):
+ model = speed_with({})
+ t, s, r = run_tuner(model, session_kw={"run_s": 300.0}, opts=autotune.Options(budget_s=1200))
+ self.assertLessEqual(len(s.runs), 1200 / 300 + 1)
+ t, s, r = run_tuner(model, session_kw={"run_s": 60.0}, opts=autotune.Options(budget_s=1200))
+ self.assertGreater(len(s.runs), 4)
+
+ def test_progress_reports_stage_and_time_left(self):
+ seen = []
+ t, s, r = run_tuner(speed_with({}), progress=seen.append)
+ self.assertTrue(any(p["stage"] == "base" for p in seen))
+ etas = [p["eta_s"] for p in seen if p.get("eta_s") is not None]
+ self.assertTrue(etas)
+ self.assertLessEqual(etas[-1], etas[0])
+ self.assertEqual(seen[-1]["stage"], "done")
+
+ def test_per_request_value_needs_every_round(self):
+ wins = {"n": 0}
+
+ def model(args, env, tune=None):
+ if tune and tune.get("spec_min_p") == 0.7:
+ return 60.0 * 1.06
+ return 60.0
+ t, s, r = run_tuner(model, session_kw={"noise": 0.002})
+ self.assertEqual(r.settings["per_request"].get("spec_min_p"), 0.7)
+ self.assertEqual(r.outcome, "improved")
+
+ calls = {"n": 0}
+
+ def noisy(args, env, tune=None):
+ if tune and tune.get("spec_min_p") == 0.7:
+ calls["n"] += 1
+ return 60.0 * (1.06 if calls["n"] % 3 else 0.99) # one round in three it does not win
+ return 60.0
+ t, s2, r = run_tuner(noisy, session_kw={"noise": 0.0})
+ self.assertNotIn("spec_min_p", r.settings["per_request"])
+
+ def test_thorough_confirms_with_five_pairs(self):
+ model = speed_with({("--host-core", "last"): 1.06})
+ t, s, r = run_tuner(model, opts=autotune.Options(mode="thorough", budget_s=7200), session_kw={"noise": 0.003})
+ self.assertEqual(r.outcome, "improved")
+ self.assertEqual(r.pairs, 5)
+ self.assertGreaterEqual(r.faster_pairs, 4)
+
+ def test_prompt_regression_blocks_a_decode_win(self):
+ model = speed_with({("--host-core", "last"): 1.08})
+ pp = lambda a, e: 1500.0 * (0.8 if flag(a, "--host-core") == "last" else 1.0)
+ t, s, r = run_tuner(model, session_kw={"pp": pp, "noise": 0.001})
+ self.assertEqual(r.settings["args"], {})
+
+ def test_base_that_cannot_start_is_reported(self):
+ t, s, r = run_tuner(speed_with({}), session_kw={"fail": lambda a, e: StartFailed("FAIL_BOOT", "x")})
+ self.assertEqual(r.outcome, "base_failed")
+ self.assertEqual(len(s.runs), 1)
+
+ def test_coding_metric_uses_prompt_speed(self):
+ m = autotune.metric({"decode_tok_s": 100.0, "pp_tok_s": 400.0}, "coding")
+ self.assertAlmostEqual(m, 200.0)
+ self.assertEqual(autotune.metric({"decode_tok_s": 100.0, "pp_tok_s": 400.0}, "chat"), 100.0)
+
+
+class DecisionRulesTest(unittest.TestCase):
+ def test_threshold_follows_the_noise(self):
+ self.assertAlmostEqual(autotune.accept_threshold(0.03, 0.0, 0.0), 1.03)
+ self.assertAlmostEqual(autotune.accept_threshold(0.03, 0.025, 0.0), 1.05)
+ self.assertAlmostEqual(autotune.accept_threshold(0.03, 0.0, 0.04), 1.08)
+
+ def test_is_win(self):
+ self.assertTrue(autotune.is_win([1.05, 1.06], [1.0], threshold=1.03))
+ self.assertFalse(autotune.is_win([1.05, 0.99], [1.0], threshold=1.03))
+ self.assertFalse(autotune.is_win([1.04, 1.04], [0.9], threshold=1.03))
+ self.assertTrue(autotune.is_win([1.05, 1.06, 1.04, 1.05, 0.99], [1.0], threshold=1.03, need=4))
+
+
+class RecheckTest(unittest.TestCase):
+ def _preset(self):
+ return {"settings": {"args": {"--host-core": "last"}, "env": {}, "per_request": {}},
+ "measured": {"decode_tok_s": 60.0, "pp4k_tok_s": 1500.0, "rss_peak_mib": 12000.0, "vram_peak_mib": 10000.0}}
+
+ def test_keep_when_as_fast(self):
+ s = StubSession(model=lambda a, e, tune=None: 59.0, noise=0.0)
+ out = autotune.recheck(s, BASE, self._preset(), ctx=make_ctx())
+ self.assertEqual(out["verdict"], "keep")
+ self.assertEqual(len(s.runs), 1)
+ self.assertEqual(flag(s.runs[0][0], "--host-core"), "last")
+
+ def test_retune_suggested_when_slower(self):
+ s = StubSession(model=lambda a, e, tune=None: 50.0, noise=0.0)
+ out = autotune.recheck(s, BASE, self._preset(), ctx=make_ctx())
+ self.assertEqual(out["verdict"], "retune")
+ self.assertIn("slower", out["reason"])
+
+ def test_engine_update_adds_a_baseline_start(self):
+ s = StubSession(model=lambda a, e, tune=None: 60.0 if flag(a, "--host-core") else 62.0, noise=0.0)
+ out = autotune.recheck(s, BASE, self._preset(), ctx=make_ctx(), engine_changed=True)
+ self.assertEqual(len(s.runs), 2)
+ self.assertEqual(out["verdict"], "retune")
+
+ def test_a_start_that_fails_suggests_retune(self):
+ s = StubSession(model=lambda a, e, tune=None: 60.0, fail=lambda a, e: StartFailed("UNSUPPORTED", "unknown argument"))
+ out = autotune.recheck(s, BASE, self._preset(), ctx=make_ctx())
+ self.assertEqual(out["verdict"], "retune")
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/tuning/test_presets.py b/tests/tuning/test_presets.py
new file mode 100644
index 000000000..ab46de518
--- /dev/null
+++ b/tests/tuning/test_presets.py
@@ -0,0 +1,175 @@
+"""The preset store: save, name, apply on load, stale detection, undo."""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import tempfile
+import time
+import unittest
+from pathlib import Path
+
+from strata_control import presets
+
+CFG = {"exe": "strata", "model_name": "swift-iq2_xs", "ui_resource_profile": "work", "vram_reserve_mib": 1536,
+ "args": ["--pack", "P", "--native", "Swift-IQ3_S-00001-of-00002.gguf", "--expert-cache", "auto", "--prefill", "auto",
+ "--spec", "4", "--max-context", "131072", "--kv", "int8"]}
+
+
+def identity(driver="610.47", sha="aaa", epoch=0, gpu="RTX 5070", ram=64):
+ return {"hardware": {"hard": {"gpus": [{"name": gpu, "vram_mib": 12227}], "cpu": "cpu", "logical": 12, "physical": 6,
+ "hybrid": False, "ram_gib": ram, "pcie": None, "os": "Windows"},
+ "soft": {"driver": [driver], "os_release": "11"}},
+ "engine": {"version": "0.1.45", "backend": "cuda", "sha256": "e1", "tuning_epoch": epoch},
+ "model": {"sha256_shard1": sha, "bytes": 1}}
+
+
+RESULT = {"outcome": "improved", "seconds": 1100, "settings": {"args": {"--host-core": "last"}, "env": {}, "per_request": {}},
+ "answers": {"class": "exact", "fields": []}, "base": {"decode_tok_s": 60.0, "pp_tok_s": 1500.0},
+ "chosen": {"decode_tok_s": 65.0, "pp_tok_s": 1500.0, "rss_peak_mib": 12000, "vram_used_mib": 9000},
+ "gain_pct": 8.3, "pairs": 2, "faster_pairs": 2, "noise": {"aa_gap": 0.004}}
+
+
+class StoreTest(unittest.TestCase):
+ def setUp(self):
+ self.tmp = tempfile.TemporaryDirectory()
+ os.environ["STRATA_PRESET_DIR"] = str(Path(self.tmp.name) / "presets")
+ self.addCleanup(lambda: os.environ.pop("STRATA_PRESET_DIR", None))
+ self.addCleanup(self.tmp.cleanup)
+ self.choices = presets.choices_from_config(CFG)
+
+ def make(self, name=None, ident=None, result=None, choices=None):
+ return presets.create(result or RESULT, choices=choices or self.choices, identity=ident or identity(), name=name)
+
+ def test_default_name_is_plain_words(self):
+ self.assertEqual(self.choices["quant"], "IQ3_S")
+ self.assertEqual(presets.default_name(self.choices), "IQ3_S 128K – Work")
+ full = dict(self.choices, goal="speed")
+ self.assertEqual(presets.default_name(full), "IQ3_S 128K – Full speed")
+
+ def test_create_list_rename_delete(self):
+ p = self.make()
+ self.assertTrue(p["name"].startswith("IQ3_S 128K"))
+ self.assertEqual(len(presets.list_presets()), 1)
+ self.assertTrue(presets.list_presets()[0]["active"])
+ q = presets.rename(p["id"], "My fast one")
+ self.assertEqual(q["name"], "My fast one")
+ with self.assertRaises(presets.PresetError):
+ presets.rename(p["id"], "")
+ p2 = self.make(name="My fast one") # a duplicate name gets a number, never overwrites
+ self.assertEqual(p2["name"], "My fast one (2)")
+ presets.delete("My fast one (2)")
+ self.assertEqual([x["name"] for x in presets.list_presets()], ["My fast one"])
+
+ def test_activation_keeps_the_previous_one_and_undo_restores_it(self):
+ a = self.make(name="A")
+ b = self.make(name="B")
+ self.assertEqual(presets.find("B")["id"], b["id"])
+ slot = a["slot"]
+ self.assertEqual(presets._index()[slot]["active"], b["id"])
+ self.assertEqual(presets.load(b["id"])["previous"], a["id"])
+ restored = presets.undo(slot)
+ self.assertEqual(restored["id"], a["id"])
+ self.assertEqual(presets._index()[slot]["active"], a["id"])
+ self.assertIsNone(presets.undo(slot)) # undo once more: back to the standard setup
+ self.assertIsNone(presets._index()[slot]["active"])
+ with self.assertRaises(presets.PresetError):
+ presets.undo(slot)
+
+ def test_unsafe_settings_are_refused(self):
+ bad = copy.deepcopy(RESULT)
+ bad["settings"]["args"] = {"--expert-cache": 0}
+ with self.assertRaises(presets.PresetError):
+ self.make(result=bad)
+
+ def test_overlay_applies_the_active_preset_without_measuring(self):
+ self.make()
+ out, info = presets.overlay(CFG, now=identity())
+ self.assertTrue(info["applied"])
+ self.assertEqual(info["state"], "fresh")
+ self.assertEqual(out["args"][-2:], ["--host-core", "last"])
+ self.assertEqual(out["args"][:len(CFG["args"])], CFG["args"]) # the user's own flags are untouched
+ self.assertNotIn("--host-core", CFG["args"]) # the input is not modified
+ self.assertIn("identical", info["notice"])
+
+ def test_overlay_other_choices_get_no_preset(self):
+ self.make()
+ other = copy.deepcopy(CFG)
+ other["args"][other["args"].index("--max-context") + 1] = "32768"
+ out, info = presets.overlay(other, now=identity())
+ self.assertFalse(info["applied"])
+ self.assertEqual(out, other)
+ full = copy.deepcopy(CFG)
+ full["ui_resource_profile"] = "performance"
+ self.assertFalse(presets.overlay(full, now=identity())[1]["applied"])
+
+ def test_hard_change_does_not_apply_and_says_why(self):
+ self.make()
+ for kw, word in ((dict(gpu="RTX 4090"), "graphics card"), (dict(sha="zzz"), "model file")):
+ out, info = presets.overlay(CFG, now=identity(**kw))
+ if "model file" in word:
+ self.assertFalse(info["applied"]) if info.get("state") else None
+ self.assertFalse(info["applied"], kw)
+
+ def test_soft_change_applies_and_asks_for_a_recheck(self):
+ self.make()
+ out, info = presets.overlay(CFG, now=identity(driver="620.1"))
+ self.assertTrue(info["applied"])
+ self.assertEqual(info["state"], "soft")
+ self.assertTrue(any("driver" in r for r in info["reasons"]))
+ out, info = presets.overlay(CFG, now=identity(epoch=1))
+ self.assertEqual(info["state"], "soft")
+
+ def test_staleness_rules(self):
+ p = self.make()
+ self.assertEqual(presets.staleness(p, identity())["state"], "fresh")
+ self.assertEqual(presets.staleness(p, identity(ram=32))["state"], "hard")
+ self.assertEqual(presets.staleness(p, identity(ram=62))["state"], "fresh") # within 10%
+ old = dict(p, created_epoch=time.time() - 100 * 86400)
+ self.assertEqual(presets.staleness(old, identity())["state"], "soft")
+
+ def test_per_request_defaults_reach_the_sampling_block(self):
+ res = copy.deepcopy(RESULT)
+ res["settings"]["per_request"] = {"spec_min_p": 0.7}
+ self.make(result=res)
+ out, info = presets.overlay(CFG, now=identity())
+ self.assertEqual(out["sampling"]["strata_tune"], {"spec_min_p": 0.7})
+
+ def test_a_broken_store_never_breaks_a_start(self):
+ self.make()
+ for f in Path(os.environ["STRATA_PRESET_DIR"]).glob("*.json"):
+ f.write_text("{not json")
+ out, info = presets.overlay(CFG, now=identity())
+ self.assertEqual(out, CFG)
+ self.assertFalse(info["applied"])
+
+ def test_export_import_roundtrip(self):
+ p = self.make(name="Shared")
+ data = presets.export_preset(p["id"])
+ presets.delete(p["id"])
+ q = presets.import_preset(data)
+ self.assertEqual(q["settings"], p["settings"])
+ self.assertNotEqual(q["id"], p["id"])
+ data["settings"]["args"] = {"--spec": 6}
+ with self.assertRaises(presets.PresetError):
+ presets.import_preset(data)
+
+ def test_recheck_keep_refreshes_the_identity(self):
+ p = self.make()
+ out = presets.record_recheck(p["id"], {"verdict": "keep", "identity": identity(driver="620.1"),
+ "measured": {"decode_tok_s": 70.0}})
+ self.assertEqual(presets.staleness(out, identity(driver="620.1"))["state"], "fresh")
+ self.assertEqual(out["measured"]["decode_tok_s"], 70.0) # better by more than 3%: stored
+ self.assertIsNotNone(out["recheck"]["last_ok"])
+
+ def test_trial_history_blocks_a_candidate_that_did_not_start(self):
+ presets.record_trials([{"label": "host_core_last", "args": ["--x"], "env": {}, "status": "OOM", "at": 1}],
+ hw_hash="h", model_digest="m", engine_sha="e")
+ self.assertEqual(presets.bad_signatures(hw_hash="h", model_digest="m", engine_sha="e"), {"host_core_last"})
+ self.assertEqual(presets.bad_signatures(hw_hash="h2", model_digest="m", engine_sha="e"), set())
+ self.assertEqual(presets.bad_signatures(hw_hash="h", model_digest="m", engine_sha="e2"), set())
+
+
+if __name__ == "__main__":
+ unittest.main()