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++
Mac app: the model list, fit words and recommendation judge a Mac by unified memory (strata_control/mac_fit.py, one definition shared with metal/setup_mac.py); setup.py in Control mode installs a Mac model with no source build and no setup_mac.py and writes component:strata-engine with the Metal flags
Niko122178914f55bed9
diff --git a/metal/setup_mac.py b/metal/setup_mac.pyindex 575aa8931..1d4717ade 100644--- a/metal/setup_mac.py+++ b/metal/setup_mac.py@@ -32,27 +32,19 @@ from pathlib import PathROOT = Path(__file__).resolve().parent.parentsys.path.insert(0, str(ROOT))import setup as S # noqa: E402+from strata_control import mac_fit as _fit # noqa: E402+from strata_control.mac_fit import ( # noqa: E402,F401 (re-exported: the tests and callers use these names here)+ BIG_MAC_GB, CONTEXTS, GIB_GB, GPU_SHARE, MAC_ABOUT, MAC_MODELS, MIN_MACOS, OVERHEAD_GB, RECOMMENDED,+ RESIDENT_LEAVE_SHARE, STREAM_COPY_GAIN, STREAM_MEASURED, STREAM_MTP_FROM_GB, STREAM_SPEC, TESTED_CONTEXT,+ _sysctl, gpu_budget_gb, mac_info, mac_problems, macos_tuple, model_need_gb, model_note, recommend_context,+ recommend_model, stream_mtp, streams)# Apple's metal-cpp headers for the macOS 26 SDK (https://developer.apple.com/metal/cpp/), pinned by SHA-256METAL_CPP_URL = "https://developer.apple.com/metal/cpp/files/metal-cpp_26.zip"METAL_CPP_SHA256 = "4df3c078b9aadcb516212e9cb03004cbc5ce9a3e9c068fa3144d021db585a3a4"BUILD_DIR = ROOT / "build-metal"EXE = BUILD_DIR / "strata"-MIN_MACOS = (15, 0) # MTLResidencySet (the engine keeps every buffer resident through one)--# The Mac's packs. shard1_gb: the file the GPU maps (resident in unified memory while the model runs); the n-gram-# table (shard 2, 28.8 GB) is read from the SSD a few rows at a time. tested: measured on the M5 Max (docs/MAC.md).-MAC_MODELS = {- "Q2_0": {"shard1_gb": 37.6, "tested": True},- "IQ3_XXS": {"shard1_gb": 47.0, "tested": True},- "IQ3_S": {"shard1_gb": 54.8, "tested": True},- # Unsloth's ~4-6-bit files (family "unsloth", 4-6 shards cutting through layers): setup repacks the experts and- # dense tensors into one GGUF for the GPU (metal/tools/metal_repack.py); shard1_gb is that file, the n-gram- # table stays in its shard on the SSD- "UD-Q4_K_XL": {"shard1_gb": 82.6, "tested": True, "family": "unsloth", "shards": 4},- "UD-Q5_K_XL": {"shard1_gb": 103.9, "tested": True, "family": "unsloth", "shards": 6},- "UD-Q6_K_XL": {"shard1_gb": 114.8, "tested": True, "family": "unsloth", "shards": 6},-}+# the Unsloth files at setup.py's pinned revision: name -> (bytes, SHA-256), the Hub's LFS pointers (UD-Q4_K_XL's# are setup.py's UNSLOTH_SHARDS)UD_SHARDS = {@@ -81,145 +73,9 @@ def model_shard_names(model: str) -> list[str]:def shard_sha(name: str):return UD_SHARDS.get(name) or getattr(S, "UNSLOTH_SHARDS", {}).get(name)-# The recommended sizes (owner's decision): IQ3_S is the default where it stays resident, UD-Q4_K_XL the higher-quality one-RECOMMENDED = ("IQ3_S", "UD-Q4_K_XL") # the owner's recommended sizes (UD-IQ4_XS is not offered on Mac yet)-# a pack that does not fit Metal's share streams its experts from the SSD (the engine decides by itself, f-mac-ssd):-# measured on a 32 GB M4 Mac mini, one token per step (MTP is slower there: its layer's memory is worth more as cache)-STREAM_MEASURED = {"Q2_0": "~14 tok/s", "IQ3_XXS": "~10 tok/s"}-STREAM_COPY_GAIN = "decoding about 15%, prompts about 25%" # without the experts' copy, on the 32 GB M4 (IQ3_XXS)-# A streaming Mac with this much memory keeps most of the experts in its arena (the 128 GB M5 Max: 80% of UD-Q5_K_XL's):-# there the draft layer pays, and a longer window pays more because every window costs a fixed hand-shake per layer-# (UD-Q5_K_XL, story: 28 tok/s without MTP, 41.8 at --spec 2, 50.6 at --spec 3). Smaller Macs stream without it.-STREAM_MTP_FROM_GB = 96-STREAM_SPEC = 3-# beside the mapped file: the prompt kernels' buffers (chunks of 2,048 rows), the KV cache, the draft layer, the-# Q8_0 copies of the hyper-connection matrices and the macOS desktop-OVERHEAD_GB = 8.0-# the share of the unified memory Metal lets one process keep resident (recommendedMaxWorkingSetSize): 107.5 of 128 GB-# measured on the M5 Max; 3/4 is the conservative rule for the other sizes-GPU_SHARE = 0.75-# what a Mac of BIG_MAC_GB or more leaves to macOS, its file cache and the user's other programs when the pack stays RESIDENT-# (the engine's resident_cap in arena_budget.h, the same rule). A resident pack is mapped file pages: clean, so macOS can-# drop them, never compress them. Measured on the 128 GB M5 Max, UD-Q4_K_XL resident (wired 91.7 GB, 67%) with a 40 GB file-# write and a 16 GB program beside it: no swap-out, nothing compressed. (The streaming arena is anonymous memory and gets a-# tighter cap in the engine: 40% left, from the same measurements.)-RESIDENT_LEAVE_SHARE = 0.30-BIG_MAC_GB = 64.0-GIB_GB = 1.073741824 # a GiB in GB: ram_gb is binary, the model sizes are decimal-CONTEXTS = [8192, 32768, 65536, 131072]-MAC_ABOUT = {"Q2_0": "2-bit, the fastest", "IQ3_XXS": "3-bit i-quant, better quality",- "IQ3_S": "3.5-bit i-quant, the best quality (matches the full model), the slowest",- "UD-Q4_K_XL": "Unsloth ~4.5-bit (111 GB download)", "UD-Q5_K_XL": "Unsloth ~5.5-bit (158 GB download)",- "UD-Q6_K_XL": "Unsloth ~6.5-bit (169 GB download)"}-TESTED_CONTEXT = 32768 # needles and the KL harness ran to 32K on the Mac# ------------------------------------------------------------------------------------------------ the Mac-def _sysctl(name: str, run=subprocess.run) -> str:- try:- return run(["sysctl", "-n", name], capture_output=True, text=True, timeout=10).stdout.strip()- except (OSError, subprocess.SubprocessError):- return ""---def mac_info(run=subprocess.run) -> dict:- """The chip, its unified memory, macOS, the architecture and the Command Line Tools."""- chip = _sysctl("machdep.cpu.brand_string", run) or "unknown chip"- try:- ram = int(_sysctl("hw.memsize", run) or 0) / 2 ** 30 # GB as Apple sells them (128 GB = 2^37 bytes)- except ValueError:- ram = 0.0- try:- ver = run(["sw_vers", "-productVersion"], capture_output=True, text=True, timeout=10).stdout.strip()- except (OSError, subprocess.SubprocessError):- ver = ""- try:- clt = run(["xcode-select", "-p"], capture_output=True, text=True, timeout=10)- clt_path = clt.stdout.strip() if clt.returncode == 0 else ""- except (OSError, subprocess.SubprocessError):- clt_path = ""- return {"chip": chip, "ram_gb": ram, "macos": ver, "arm64": platform.machine() == "arm64",- "clt": clt_path, "perf_cores": int(_sysctl("hw.perflevel0.physicalcpu", run) or 0)}---def macos_tuple(ver: str) -> tuple:- try:- return tuple(int(x) for x in ver.split(".")[:2])- except ValueError:- return (0, 0)---def mac_problems(info: dict) -> list[str]:- """What stops the setup on this Mac (each with what to do)."""- p = []- if not info["arm64"]:- p.append(f"this Mac has an Intel CPU ({info['chip']}): the Metal engine needs Apple Silicon (M1 or newer)")- if macos_tuple(info["macos"]) < MIN_MACOS:- p.append(f"macOS {info['macos'] or '?'}: the Metal engine needs macOS {MIN_MACOS[0]} or newer (System Settings "- "> General > Software Update)")- if not info["clt"]:- p.append("the Command Line Tools are missing (the compiler the engine is built with): run "- "`xcode-select --install`, then this setup again")- return p---def gpu_budget_gb(ram_gb: float) -> float:- """The most a resident pack may hold, in GB: Metal's working set, and on a big Mac the RAM less what macOS and the file- cache keep (the engine's resident_cap: min of the two)."""- ws = ram_gb * GPU_SHARE * GIB_GB- if ram_gb >= BIG_MAC_GB:- return min(ws, ram_gb * GIB_GB * (1.0 - RESIDENT_LEAVE_SHARE))- return ws---def model_need_gb(model: str) -> float:- return MAC_MODELS[model]["shard1_gb"] + OVERHEAD_GB---def streams(model: str, ram_gb: float) -> bool:- """The pack does not fit Metal's share of the memory: the engine streams its experts from the SSD."""- return model_need_gb(model) > gpu_budget_gb(ram_gb)---def recommend_model(ram_gb: float) -> tuple[str, list[str]]:- """The default pack and the notes that go with it. IQ3_S and UD-Q4_K_XL are the recommended sizes (RECOMMENDED):- the default is IQ3_S when it stays resident, with UD-Q4_K_XL named as the higher-quality choice where it fits too;- below that the largest pack that stays resident (IQ3_XXS, Q2_0); nothing fits: Q2_0 streamed from the SSD."""- if not streams("IQ3_S", ram_gb):- notes = []- if not streams("UD-Q4_K_XL", ram_gb):- notes.append("UD-Q4_K_XL (recommended too) also fits this Mac: higher quality than IQ3_S (92.8% top-1 against "- "Q8_0 where IQ3_S has 87.9%), about 20% slower on a story; choose it with --model UD-Q4_K_XL")- return "IQ3_S", notes- for m in ("IQ3_XXS", "Q2_0"):- if not streams(m, ram_gb):- return m, []- return "Q2_0", [f"{ram_gb:.0f} GB of memory: no pack fits whole, so the engine streams the experts from the SSD "- f"(automatic; measured on a 32 GB M4: Q2_0 {STREAM_MEASURED['Q2_0']}, IQ3_XXS "- f"{STREAM_MEASURED['IQ3_XXS']}; smaller Macs are untested). Recommended: Q2_0, without the MTP "- "draft layer (slower when streaming)"]---def model_note(model: str, ram_gb: float) -> list[str]:- """What a chosen pack risks on this Mac (said, never refused)."""- notes = []- if streams(model, ram_gb):- notes.append(f"{model} needs ~{model_need_gb(model):.0f} GB of the {gpu_budget_gb(ram_gb):.0f} GB Metal keeps "- "resident on this Mac: its experts stream from the SSD (automatic)"- + (f"; measured on a 32 GB M4: {STREAM_MEASURED[model]}" if model in STREAM_MEASURED else- "; not measured streaming"))- if MAC_MODELS[model].get("missing"):- notes.append(f"{model} does not run on this Metal engine yet ({MAC_MODELS[model]['missing']} are missing): the "- "engine will stop when it loads; kept as you chose (for testing a newer engine)")- elif not MAC_MODELS[model]["tested"]:- notes.append(f"{model} has not been measured on a Mac yet")- return notes---def recommend_context(ram_gb: float) -> int:- return 32768 if ram_gb < 96 else 65536--# ------------------------------------------------------------------------------------------------ the enginedef metal_cpp() -> Path:"""Apple's metal-cpp headers in third_party/metal-cpp (one zip, pinned)."""@@ -292,28 +148,9 @@ def build_engine(llama: Path, jobs: int | None = None) -> Path:# ------------------------------------------------------------------------------------------------ the config-def stream_mtp(stream: bool, ram_gb: float) -> bool:- """Whether the config carries the MTP draft layer: always when the model is resident; when it streams, only on a- Mac with STREAM_MTP_FROM_GB or more (a 32 GB M4 is faster without it)."""- return (not stream) or ram_gb >= STREAM_MTP_FROM_GB--def engine_args(pack: Path, shards: list, rt: Path, ctx: int, stream: bool = False, ram_gb: float = 0.0) -> list[str]:- """The Metal defaults: --spec 2 with the MTP draft layer (measured best on the M5 Max, docs/MAC.md) and the Q8_0- hyper-connection read (the engine's default on Metal; STRATA_HC_Q8=0 in the config's env gives the exact BF16- read). Streaming from the SSD: one token per step, no draft layer (measured faster on the 32 GB M4); a streaming- Mac with STREAM_MTP_FROM_GB or more keeps the draft layer and uses --spec STREAM_SPEC."""- mtp = stream_mtp(stream, ram_gb)- args = ["--pack", str(pack), "--native", str(shards[0]), "--ple-gguf", str(shards[1])]- if shards[0].name.endswith("-metal.gguf"): # the repacked file: it is its own dense GGUF- args += ["--native-dense-gguf", str(shards[0])]- args += [- "--expert-profile", str(ROOT / "data" / "expert-profile.bin"), "--expert-cache", "64",- "--prefill", "auto", "--spec", str(STREAM_SPEC if stream and mtp else 2)]- args += ["--suffix-draft", "0"] if stream else []- args += ["--mtp", str(rt)] if mtp else []- return args + ["--max-context", str(ctx),- "--mmap-experts"] # what the Metal engine does anyway (the GGUF mapped in place); the server says so+ """The Metal defaults (strata_control/mac_fit.py), with this checkout's expert profile."""+ return _fit.engine_args(pack, shards, rt, ctx, stream, ram_gb, ROOT / "data" / "expert-profile.bin")# the image encoder's projector (setup.py's pinned revision): name -> (bytes, SHA-256)diff --git a/setup.py b/setup.pyindex 81c9870b8..ca2733812 100644--- a/setup.py+++ b/setup.py@@ -6234,13 +6234,149 @@ def preview_family(a) -> int:return 0+def mac_control_setup(a) -> int:+ """The app (and the Terminal's `strata launch`) on a Mac, STRATA_CONTROL_INSTALL=1: the same job as on Windows and Linux. It+ downloads and prepares the model files and writes a run config whose engine is "component:strata-engine"; it builds nothing+ (the Metal engine is a component: a ready-made package from the feed, or the one inside the installer) and runs no+ metal/setup_mac.py. Which sizes a Mac can run, whether one stays in memory or streams its experts from the SSD, and the+ Metal flags of the config are strata_control/mac_fit.py's, the module setup_mac.py and the model list use too."""+ from strata_control import mac_fit as MF+ say("Strata on a Mac (Apple Silicon, Metal)")+ step(1, "checking your Mac")+ info = MF.mac_info()+ ram = float(info["ram_gb"] or ram_gb())+ ok(f"{info['chip']}, {ram:.0f} GB unified memory, macOS {info['macos'] or '?'}")+ problems = MF.mac_problems(info, need_compiler=False) # the app compiles nothing: no Command Line Tools needed+ for p in problems:+ warn(p)+ data, elsewhere = data_folder(a.data_dir)+ roots = [data, *elsewhere]+ models_root = Path(a.models_dir) if a.models_dir else data / "models"+ free = free_gb(data if data.exists() else home())+ ok(f"free disk: {free:.0f} GB at {data}")+ if a.check:+ return 1 if problems else 0+ if problems:+ fail(problems[0])++ step(2, "your choices")+ app_sizes = [m for m, d in MF.MAC_MODELS.items() if d.get("family", "qwen") == "qwen"]+ if a.family not in (None, "qwen"):+ fail(f"the app on a Mac runs the Qwen3.8-Flash-Next sizes ({', '.join(app_sizes)}); {a.family} is not one of them",+ "choose Qwen3.8-Flash-Next")+ rec, notes = MF.recommend_model(ram)+ if rec not in app_sizes:+ rec = "Q2_0"+ model = a.model or rec+ if model not in app_sizes:+ fail(f"{model} is not offered on a Mac in the app", "choose one of: " + ", ".join(app_sizes))+ for n in MF.model_note(model, ram):+ warn(n)+ if a.vision in ("yes", "gpu", "cpu"):+ warn("images are not part of the app's first release: images off for this model")+ ctx = a.context or MF.recommend_context(ram)+ if ctx > MF.TESTED_CONTEXT:+ say(f" context {ctx}: measured on the Mac up to {MF.TESTED_CONTEXT} (needles found at 8K-32K); longer is kept")+ ok(f"{model}, context {ctx}")+ fam = FAMILIES["qwen"]+ tag = fam["tag"] + model+ stream = MF.streams(model, ram)++ step(4, "the Strata engine (Metal)")+ from strata_control import engine_component as EC+ llama = get_llama_cpp() # gguf-py for the preparation tools only: no git, no compiler+ ok(f"llama.cpp {LLAMA_CPP_COMMIT[:7]} (gguf-py for the preparation tools)")+ try:+ found = EC.resolve(full=False)+ ok(f"engine component: {found.version} ({found.platform}-{found.backend})")+ except EC.EngineMissing as e:+ warn(f"no Metal engine is installed for this Mac yet ({e}). The model is downloaded and prepared now; the engine comes "+ "with the app or its update feed, and is looked up when the model loads")+ ok("engine: the engine component (looked up when the model loads)")++ step(5, f"downloading {fam['title']} {model}")+ models_dir = Path(a.gguf_dir) if a.gguf_dir else models_root / tag+ files = gguf_dir_shards(models_dir, fam, model) if a.gguf_dir else \+ [models_dir / model_file(fam, model, i) for i in range(1, model_shards(fam, model) + 1)]+ problem = gguf_dir_problem(models_dir, files[0], fam, model) if a.gguf_dir else None+ if problem: # files Strata cannot run, or another choice's files+ fail(*problem)+ for s in files: # a whole file copied in by hand has no finish mark+ if s.exists() and not done(s) and whole_shard(s):+ try:+ mark(s, "whole (checked against its own tensor directory)")+ except OSError as e: # a read-only folder: the file is still whole+ warn(f"{s.name} is whole but its finish mark cannot be written ({e})")+ need = (0 if a.gguf_dir or all(s.exists() and done(s) for s in files) else MODELS[model]["download_gb"]) + 6+ if free_gb(models_dir if models_dir.exists() else data) < need:+ warn(f"about {need:.0f} GB are needed on the disk: kept as you chose; it may run out")+ if not a.gguf_dir:+ models_dir.mkdir(parents=True, exist_ok=True)+ missing = [s.name for s in files if not (s.exists() and done(s))]+ if missing:+ say(f" The model files go in {models_dir}")+ for s in files:+ if s.exists() and done(s):+ ok(f"{s.name} already downloaded")+ continue+ download(fam["hf"].format(q=model) + s.name, s)+ check_shards(files)+ ok("model files present")++ step(6, "preparing the model for Strata")+ pack = find_in(roots, f"packs/{tag.lower()}") or data / "packs" / tag.lower()+ env = dict(os.environ, STRATA_GGUF_PY=str(llama / "gguf-py"))+ if not (pack / "native_experts.txt").exists() or not (pack / "tokenizer" / "vocab.json").exists():+ run([sys.executable, str(ROOT / "tools" / "iq_pack.py"), "--gguf", str(files[0]), "--out", str(pack)], env=env)+ ok(f"model prepared: {pack}")+ use_mtp = MF.stream_mtp(stream, ram)+ mtp = (find_in(roots, "mtp/mtp-q2_0.gguf") or data / "mtp" / "mtp-q2_0.gguf").parent+ rt = mtp / "rt"+ if stream and not use_mtp:+ ok("the experts stream from the SSD: no MTP draft layer (one token per step is faster there)")+ elif stream:+ ok(f"the experts stream from the SSD; the MTP draft layer stays on, with --spec {MF.STREAM_SPEC}")+ if use_mtp and not (mtp / "mtp-q2_0.gguf").exists():+ say(" The MTP draft layer (speculative decoding) comes from the original Qwen checkpoint: only its ~5 GB of MTP tensors are downloaded.")+ run([sys.executable, str(ROOT / "tools" / "mtp_fetch.py"), "fetch", "--out", str(mtp)],+ env={**env, "STRATA_SOURCE": model_source()})+ run([sys.executable, str(ROOT / "tools" / "mtp_pack.py"), "--src", str(mtp), "--experts", "q2_0",+ "--out", str(mtp / "mtp-q2_0.gguf")], env=env)+ if use_mtp:+ rt.mkdir(parents=True, exist_ok=True) # the Metal engine reads mtp-q2_0.gguf beside it (no rt pack)+ refresh_draft_vocab(rt, a.draft_vocab or "cjk")+ ok(f"MTP draft layer: {mtp / 'mtp-q2_0.gguf'}")++ step(7, "writing the run settings")+ port = a.port or 8080+ args = MF.engine_args(pack, files, rt, ctx, stream, ram, ROOT / "data" / "expert-profile.bin")+ cfg = {"exe": engine_exe(Path("engine")), "args": args, "cwd": str(ROOT), "tokenizer": str(pack / "tokenizer"),+ "model_name": f"{fam['name']}-{model.lower()}", "log": str(home() / f"strata-{tag.lower()}.log"),+ "lib_dirs": [], "port": port, "backend": "metal", "env": {"STRATA_METAL_STREAM": "1" if stream else "0"}}+ if a.host:+ cfg["host"] = a.host+ if a.api_key:+ cfg["api_key"] = a.api_key+ if a.draft_vocab:+ cfg["draft_vocab"] = a.draft_vocab+ if a.browser is not None:+ cfg["open_browser"] = a.browser+ cfg_path = home() / f"strata-{tag.lower()}.json"+ write_setup_config(cfg_path, cfg)+ script = write_run_script(tag, cfg_path, port, cfg.get("open_browser") is not False)+ ok(f"start script: {script.name}")+ say()+ say("All set.")+ return 0++def main() -> int:try: # files made by a run as administrator still belong to the userfrom strata_control import private_files as _pf_pf.adopt_user_defaults()except Exception:pass- if sys.platform == "darwin": # a Mac: metal/setup_mac.py (the Metal engine)+ if sys.platform == "darwin" and not CONTROL: # a Mac: metal/setup_mac.py (the Metal engine); the app (Control mode) goes on belowreturn mac_setup(sys.argv[1:])ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)ap.add_argument("--family", choices=list(FAMILIES) + list(PREVIEW_FAMILIES),@@ -6367,6 +6503,8 @@ def main() -> int:os.environ["STRATA_SOURCE"] = a.sourceif a.inspect: # headers only: nothing is installedsys.exit(subprocess.run([sys.executable, str(ROOT / "tools" / "strata_inspect.py"), *a.inspect[:2]]).returncode)+ if sys.platform == "darwin" and CONTROL: # the app on a Mac: model files only; the Metal engine is a component+ return mac_control_setup(a)if a.backend == "sycl": # Intel Arc: the SYCL port's own setup (sycl/setup_intel.py)return sycl_setup(sys.argv[1:])if a.resident_budget_gib is not None and not a.resident_budget_gib > 0:diff --git a/strata_cli/launch/catalog.py b/strata_cli/launch/catalog.pyindex f69bb0c77..a03ca7f37 100644--- a/strata_cli/launch/catalog.py+++ b/strata_cli/launch/catalog.py@@ -127,6 +127,9 @@ class Computer:def line(self, data_dir: str | None = None) -> str:g = self.usable_gpus+ if g and g[0].get("unified_gb"): # a Mac: one pool of memory, the chip is the graphics+ disk = f"{self.disk_free_gb:,.0f} GB free" if self.disk_free_gb is not None else ""+ return " · ".join(x for x in (g[0].get("name", "Apple silicon"), f"{self.ram_gb:.0f} GB unified memory" if self.ram_gb else "memory unknown", disk) if x)card = (f"{g[0].get('name', 'GPU').replace('NVIDIA GeForce ', '').replace('AMD Radeon ', '')} {g[0].get('vram_gb', 0):.0f} GB"+ (f" x{len(g)}" if len(g) > 1 else "")) if g else "no usable graphics card found"ram = f"{self.ram_gb:.0f} GB RAM" if self.ram_gb else "RAM unknown"@@ -292,6 +295,10 @@ class Catalog:def max_context(self, family: str, model: str, hw: dict | None = None) -> int | None:"""The recommended context for this computer and model (setup.py: VRAM rule, then the RAM rule)."""hw = hw or self.hardware()+ if hw.get("mac") and hw.get("ram_gb"): # a Mac: the context by unified memory (strata_control/mac_fit.py)+ mac = self.strata.mac()+ if mac is not None:+ return int(mac.recommend_context(float(hw["ram_gb"])))usable = [g for g in hw.get("gpus") or [] if g.get("usable", True)]vram = max((float(g.get("vram_gb") or 0) for g in usable), default=12.0)rec = 32768 if vram < 14 else 65536 if vram < 20 else 131072diff --git a/strata_control/mac_fit.py b/strata_control/mac_fit.pynew file mode 100644index 000000000..94183e156--- /dev/null+++ b/strata_control/mac_fit.py@@ -0,0 +1,195 @@+"""The Mac's model rules: which packs a Mac can run, whether one stays resident or streams its experts from the SSD, the+Metal defaults of a run config. ONE definition, read by metal/setup_mac.py (a Mac that builds the engine itself), by setup.py's+Control mode (the app and the Terminal on a Mac: model files only, the engine is a component) and by tools/strata_mcp.py (the+model list, the fit words and the recommendation both show). Pure: nothing here downloads, builds or starts anything.++Unified memory: a Mac has one pool. Metal keeps a share of it resident (GPU_SHARE; on a big Mac the memory less what macOS and+its file cache keep), a pack that does not fit streams its experts from the SSD (the engine decides by itself).+"""+from __future__ import annotations++import platform+import subprocess+from pathlib import Path++MIN_MACOS = (15, 0) # MTLResidencySet (the engine keeps every buffer resident through one)++# The Mac's packs. shard1_gb: the file the GPU maps (resident in unified memory while the model runs); the n-gram+# table (shard 2, 28.8 GB) is read from the SSD a few rows at a time. tested: measured on the M5 Max (docs/MAC.md).+MAC_MODELS = {+ "Q2_0": {"shard1_gb": 37.6, "tested": True},+ "IQ3_XXS": {"shard1_gb": 47.0, "tested": True},+ "IQ3_S": {"shard1_gb": 54.8, "tested": True},+ # Unsloth's ~4-6-bit files (family "unsloth", 4-6 shards cutting through layers): setup repacks the experts and+ # dense tensors into one GGUF for the GPU (metal/tools/metal_repack.py); shard1_gb is that file, the n-gram+ # table stays in its shard on the SSD+ "UD-Q4_K_XL": {"shard1_gb": 82.6, "tested": True, "family": "unsloth", "shards": 4},+ "UD-Q5_K_XL": {"shard1_gb": 103.9, "tested": True, "family": "unsloth", "shards": 6},+ "UD-Q6_K_XL": {"shard1_gb": 114.8, "tested": True, "family": "unsloth", "shards": 6},+}++# The recommended sizes (owner's decision): IQ3_S is the default where it stays resident, UD-Q4_K_XL the higher-quality one+RECOMMENDED = ("IQ3_S", "UD-Q4_K_XL") # the owner's recommended sizes (UD-IQ4_XS is not offered on Mac yet)+# a pack that does not fit Metal's share streams its experts from the SSD (the engine decides by itself, f-mac-ssd):+# measured on a 32 GB M4 Mac mini, one token per step (MTP is slower there: its layer's memory is worth more as cache)+STREAM_MEASURED = {"Q2_0": "~14 tok/s", "IQ3_XXS": "~10 tok/s"}+STREAM_COPY_GAIN = "decoding about 15%, prompts about 25%" # without the experts' copy, on the 32 GB M4 (IQ3_XXS)+# A streaming Mac with this much memory keeps most of the experts in its arena (the 128 GB M5 Max: 80% of UD-Q5_K_XL's):+# there the draft layer pays, and a longer window pays more because every window costs a fixed hand-shake per layer+# (UD-Q5_K_XL, story: 28 tok/s without MTP, 41.8 at --spec 2, 50.6 at --spec 3). Smaller Macs stream without it.+STREAM_MTP_FROM_GB = 96+STREAM_SPEC = 3+# beside the mapped file: the prompt kernels' buffers (chunks of 2,048 rows), the KV cache, the draft layer, the+# Q8_0 copies of the hyper-connection matrices and the macOS desktop+OVERHEAD_GB = 8.0+# the share of the unified memory Metal lets one process keep resident (recommendedMaxWorkingSetSize): 107.5 of 128 GB+# measured on the M5 Max; 3/4 is the conservative rule for the other sizes+GPU_SHARE = 0.75+# what a Mac of BIG_MAC_GB or more leaves to macOS, its file cache and the user's other programs when the pack stays RESIDENT+# (the engine's resident_cap in arena_budget.h, the same rule). A resident pack is mapped file pages: clean, so macOS can+# drop them, never compress them. Measured on the 128 GB M5 Max, UD-Q4_K_XL resident (wired 91.7 GB, 67%) with a 40 GB file+# write and a 16 GB program beside it: no swap-out, nothing compressed. (The streaming arena is anonymous memory and gets a+# tighter cap in the engine: 40% left, from the same measurements.)+RESIDENT_LEAVE_SHARE = 0.30+BIG_MAC_GB = 64.0+GIB_GB = 1.073741824 # a GiB in GB: ram_gb is binary, the model sizes are decimal+CONTEXTS = [8192, 32768, 65536, 131072]+MAC_ABOUT = {"Q2_0": "2-bit, the fastest", "IQ3_XXS": "3-bit i-quant, better quality",+ "IQ3_S": "3.5-bit i-quant, the best quality (matches the full model), the slowest",+ "UD-Q4_K_XL": "Unsloth ~4.5-bit (111 GB download)", "UD-Q5_K_XL": "Unsloth ~5.5-bit (158 GB download)",+ "UD-Q6_K_XL": "Unsloth ~6.5-bit (169 GB download)"}+TESTED_CONTEXT = 32768 # needles and the KL harness ran to 32K on the Mac+# Below this much unified memory the app says a model does not fit (a Mac this small was never run: 32 GB is the smallest that was).+# The Terminal keeps its rule of recommending and never forcing: the person can still pick one there.+MIN_STREAM_RAM_GB = 16.0+++def _sysctl(name: str, run=subprocess.run) -> str:+ try:+ return run(["sysctl", "-n", name], capture_output=True, text=True, timeout=10).stdout.strip()+ except (OSError, subprocess.SubprocessError):+ return ""+++def mac_info(run=subprocess.run) -> dict:+ """The chip, its unified memory, macOS, the architecture and the Command Line Tools."""+ chip = _sysctl("machdep.cpu.brand_string", run) or "unknown chip"+ try:+ ram = int(_sysctl("hw.memsize", run) or 0) / 2 ** 30 # GB as Apple sells them (128 GB = 2^37 bytes)+ except ValueError:+ ram = 0.0+ try:+ ver = run(["sw_vers", "-productVersion"], capture_output=True, text=True, timeout=10).stdout.strip()+ except (OSError, subprocess.SubprocessError):+ ver = ""+ try:+ clt = run(["xcode-select", "-p"], capture_output=True, text=True, timeout=10)+ clt_path = clt.stdout.strip() if clt.returncode == 0 else ""+ except (OSError, subprocess.SubprocessError):+ clt_path = ""+ return {"chip": chip, "ram_gb": ram, "macos": ver, "arm64": platform.machine() == "arm64",+ "clt": clt_path, "perf_cores": int(_sysctl("hw.perflevel0.physicalcpu", run) or 0)}+++def macos_tuple(ver: str) -> tuple:+ try:+ return tuple(int(x) for x in ver.split(".")[:2])+ except ValueError:+ return (0, 0)+++def mac_problems(info: dict, need_compiler: bool = True) -> list[str]:+ """What stops the setup on this Mac (each with what to do). The app brings a ready-made engine and compiles nothing:+ need_compiler=False leaves the Command Line Tools out."""+ p = []+ if not info["arm64"]:+ p.append(f"this Mac has an Intel CPU ({info['chip']}): the Metal engine needs Apple Silicon (M1 or newer)")+ if macos_tuple(info["macos"]) < MIN_MACOS:+ p.append(f"macOS {info['macos'] or '?'}: the Metal engine needs macOS {MIN_MACOS[0]} or newer (System Settings "+ "> General > Software Update)")+ if need_compiler and not info["clt"]:+ p.append("the Command Line Tools are missing (the compiler the engine is built with): run "+ "`xcode-select --install`, then this setup again")+ return p+++def gpu_budget_gb(ram_gb: float) -> float:+ """The most a resident pack may hold, in GB: Metal's working set, and on a big Mac the RAM less what macOS and the file+ cache keep (the engine's resident_cap: min of the two)."""+ ws = ram_gb * GPU_SHARE * GIB_GB+ if ram_gb >= BIG_MAC_GB:+ return min(ws, ram_gb * GIB_GB * (1.0 - RESIDENT_LEAVE_SHARE))+ return ws+++def model_need_gb(model: str) -> float:+ return MAC_MODELS[model]["shard1_gb"] + OVERHEAD_GB+++def streams(model: str, ram_gb: float) -> bool:+ """The pack does not fit Metal's share of the memory: the engine streams its experts from the SSD."""+ return model_need_gb(model) > gpu_budget_gb(ram_gb)+++def recommend_model(ram_gb: float) -> tuple[str, list[str]]:+ """The default pack and the notes that go with it. IQ3_S and UD-Q4_K_XL are the recommended sizes (RECOMMENDED):+ the default is IQ3_S when it stays resident, with UD-Q4_K_XL named as the higher-quality choice where it fits too;+ below that the largest pack that stays resident (IQ3_XXS, Q2_0); nothing fits: Q2_0 streamed from the SSD."""+ if not streams("IQ3_S", ram_gb):+ notes = []+ if not streams("UD-Q4_K_XL", ram_gb):+ notes.append("UD-Q4_K_XL (recommended too) also fits this Mac: higher quality than IQ3_S (92.8% top-1 against "+ "Q8_0 where IQ3_S has 87.9%), about 20% slower on a story; choose it with --model UD-Q4_K_XL")+ return "IQ3_S", notes+ for m in ("IQ3_XXS", "Q2_0"):+ if not streams(m, ram_gb):+ return m, []+ return "Q2_0", [f"{ram_gb:.0f} GB of memory: no pack fits whole, so the engine streams the experts from the SSD "+ f"(automatic; measured on a 32 GB M4: Q2_0 {STREAM_MEASURED['Q2_0']}, IQ3_XXS "+ f"{STREAM_MEASURED['IQ3_XXS']}; smaller Macs are untested). Recommended: Q2_0, without the MTP "+ "draft layer (slower when streaming)"]+++def model_note(model: str, ram_gb: float) -> list[str]:+ """What a chosen pack risks on this Mac (said, never refused)."""+ notes = []+ if streams(model, ram_gb):+ notes.append(f"{model} needs ~{model_need_gb(model):.0f} GB of the {gpu_budget_gb(ram_gb):.0f} GB Metal keeps "+ "resident on this Mac: its experts stream from the SSD (automatic)"+ + (f"; measured on a 32 GB M4: {STREAM_MEASURED[model]}" if model in STREAM_MEASURED else+ "; not measured streaming"))+ if MAC_MODELS[model].get("missing"):+ notes.append(f"{model} does not run on this Metal engine yet ({MAC_MODELS[model]['missing']} are missing): the "+ "engine will stop when it loads; kept as you chose (for testing a newer engine)")+ elif not MAC_MODELS[model]["tested"]:+ notes.append(f"{model} has not been measured on a Mac yet")+ return notes+++def recommend_context(ram_gb: float) -> int:+ return 32768 if ram_gb < 96 else 65536+++def stream_mtp(stream: bool, ram_gb: float) -> bool:+ """Whether the config carries the MTP draft layer: always when the model is resident; when it streams, only on a+ Mac with STREAM_MTP_FROM_GB or more (a 32 GB M4 is faster without it)."""+ return (not stream) or ram_gb >= STREAM_MTP_FROM_GB+++def engine_args(pack: Path, shards: list, rt: Path, ctx: int, stream: bool = False, ram_gb: float = 0.0,+ profile: Path | str = "data/expert-profile.bin") -> list[str]:+ """The Metal defaults: --spec 2 with the MTP draft layer (measured best on the M5 Max, docs/MAC.md) and the Q8_0+ hyper-connection read (the engine's default on Metal; STRATA_HC_Q8=0 in the config's env gives the exact BF16+ read). Streaming from the SSD: one token per step, no draft layer (measured faster on the 32 GB M4); a streaming+ Mac with STREAM_MTP_FROM_GB or more keeps the draft layer and uses --spec STREAM_SPEC."""+ mtp = stream_mtp(stream, ram_gb)+ args = ["--pack", str(pack), "--native", str(shards[0]), "--ple-gguf", str(shards[1])]+ if shards[0].name.endswith("-metal.gguf"): # the repacked file: it is its own dense GGUF+ args += ["--native-dense-gguf", str(shards[0])]+ args += [+ "--expert-profile", str(profile), "--expert-cache", "64",+ "--prefill", "auto", "--spec", str(STREAM_SPEC if stream and mtp else 2)]+ args += ["--suffix-draft", "0"] if stream else []+ args += ["--mtp", str(rt)] if mtp else []+ return args + ["--max-context", str(ctx),+ "--mmap-experts"] # what the Metal engine does anyway (the GGUF mapped in place); the server says sodiff --git a/tests/terminal/test_launch.py b/tests/terminal/test_launch.pyindex adf390fda..6012a07b4 100644--- a/tests/terminal/test_launch.py+++ b/tests/terminal/test_launch.py@@ -112,6 +112,21 @@ class CatalogRules(unittest.TestCase):gyro = fit_on({"mem_total": True, "ram_needed_gb": 27.6}, 64, 12)self.assertEqual(gyro["memoryGb"], 27.6)+ def test_a_mac_is_judged_by_unified_memory_and_the_words_follow(self):+ hw = {"ram_gb": 32.0, "os": "Darwin", "cpu": {"avx2": None, "name": "Apple M4"}, "mac": {"chip": "Apple M4", "macos": "27.2", "unified_gb": 32.0},+ "gpus": [{"index": 0, "name": "Apple M4", "vendor": "apple", "vram_gb": 0.0, "unified_gb": 32.0, "usable": True}]}+ with Home():+ cat = catalog(hw)+ rows = {r.model: r for r in cat.rows()}+ self.assertEqual(set(rows), {"Q2_0", "IQ3_XXS", "IQ3_S"})+ self.assertEqual([r.model for r in rows.values() if r.recommended], ["Q2_0"])+ self.assertEqual((rows["Q2_0"].verdict, rows["Q2_0"].words), ("fits", "fits, part read from SSD"))+ self.assertEqual(rows["IQ3_S"].verdict, "tight")+ self.assertGreater(rows["IQ3_S"].spill_gb, 10)+ self.assertEqual(cat.max_context("qwen", "Q2_0", hw), 32768)+ self.assertEqual(cat.computer().line(), "Apple M4 · 32 GB unified memory · " + cat.computer().line().split(" · ")[-1])+ self.assertNotIn("0 GB", cat.computer().line())+def test_verdict_words_never_block(self):self.assertEqual(verdict("fits")[0], "fits")self.assertEqual(verdict("does not fit")[0], "no")diff --git a/tools/strata_mcp.py b/tools/strata_mcp.pyindex 597813781..f4256dcd3 100644--- a/tools/strata_mcp.py+++ b/tools/strata_mcp.py@@ -731,6 +731,8 @@ class Strata:hw["cpu"] = {"name": name, "cores": os.cpu_count(), "avx2": avx2, "avx512": avx512}except Exception: # noqa: BLE001hw["cpu"] = {"name": platform.processor(), "cores": os.cpu_count()}+ if sys.platform == "darwin": # a Mac: one pool of unified memory, the Metal engine (strata_control/mac_fit.py)+ return self._mac_hardware(hw)nv = []try:nv = S.gpus() if S else own_nvidia_gpus()@@ -763,11 +765,100 @@ class Strata:hw["nvidia_smi"] = bool(shutil.which("nvidia-smi"))return hw+ # ---- a Mac (Apple Silicon): unified memory, the Metal engine. The rules are strata_control/mac_fit.py's (the same module+ # metal/setup_mac.py uses), so the app, the Terminal and a Mac that builds the engine itself judge a model the same way.+ def mac(self):+ """strata_control/mac_fit.py, or None when this Strata folder does not carry it."""+ try:+ if str(self.src) not in sys.path:+ sys.path.insert(0, str(self.src))+ from strata_control import mac_fit+ return mac_fit+ except Exception as e: # noqa: BLE001+ log(f"strata_control/mac_fit.py could not be imported ({e})")+ return None++ def _mac_hardware(self, hw: dict) -> dict:+ mf = self.mac()+ info = mf.mac_info() if mf else {"chip": platform.processor() or "Apple silicon", "ram_gb": hw.get("ram_gb") or 0.0,+ "macos": platform.mac_ver()[0], "arm64": platform.machine() == "arm64", "clt": "x"}+ problems = mf.mac_problems(info, need_compiler=False) if mf else []+ ram = round(float(info.get("ram_gb") or hw.get("ram_gb") or 0.0), 1)+ hw["ram_gb"] = ram+ hw["cpu"] = {"name": info["chip"], "cores": os.cpu_count(), "avx2": None, "avx512": None}+ # The graphics memory IS the RAM here: vram_gb stays 0 so nothing is counted twice (the pages that fit RAM + VRAM add them up).+ hw["gpus"] = [{"index": 0, "name": info["chip"], "vendor": "apple", "vram_gb": 0.0, "unified_gb": ram, "arch": "apple-gpu",+ "problem": problems[0] if problems else None, "usable": not problems}]+ hw["mac"] = {"chip": info["chip"], "macos": info.get("macos"), "unified_gb": ram}+ hw["nvidia_smi"] = False+ return hw++ def _mac_sizes(self, models: dict) -> list:+ """The sizes the app offers on a Mac: the GSQ-RCO files of the Qwen family (two shards, no repack). Unsloth's many-shard files need+ metal/tools/metal_repack.py, which the Terminal's setup uses; the app does not offer them yet."""+ mf = self.mac()+ return [m for m, d in mf.MAC_MODELS.items() if d.get("family", "qwen") == "qwen" and m in models] if mf else []++ def _mac_verdict(self, model: str, ram: float) -> str:+ mf = self.mac()+ if ram < mf.MIN_STREAM_RAM_GB:+ return "does not fit"+ if not mf.streams(model, ram):+ return "fits"+ speed = mf.STREAM_MEASURED.get(model)+ if speed:+ return (f"part of its experts in memory, the rest read from the SSD (slower: {speed} measured on a 32 GB Mac mini)")+ return "slow here: part of its experts read from the SSD (slower, not measured on a Mac of this size)"++ def _mac_recommend(self, hw: dict, models: dict, families: dict) -> dict:+ mf = self.mac()+ ram = float(hw.get("ram_gb") or 0)+ usable = [g for g in hw.get("gpus", []) if g.get("usable")]+ if not mf or not usable:+ why = (hw.get("gpus") or [{}])[0].get("problem") or "this Mac cannot run the Metal engine"+ return {"family": None, "model": None, "why": why}+ if ram < mf.MIN_STREAM_RAM_GB:+ return {"family": None, "model": None,+ "why": f"{ram:.0f} GB of unified memory: Strata needs {mf.MIN_STREAM_RAM_GB:.0f} GB or more on a Mac (32 GB or more is what it was tested on)"}+ model, notes = mf.recommend_model(ram)+ notes = [n for n in notes if "UD-Q4_K_XL" not in n] # the app does not offer the Unsloth files yet+ if model not in self._mac_sizes(models):+ model = "Q2_0"+ if mf.streams(model, ram):+ speed = mf.STREAM_MEASURED.get(model)+ why = (f"{ram:.0f} GB of unified memory: no size fits whole, so {model}'s experts are read from the SSD as it answers"+ + (f" ({speed} measured on a 32 GB Mac mini)" if speed else ""))+ else:+ why = f"{ram:.0f} GB of unified memory: {model} stays in memory (the best size that does)"+ ctx = mf.recommend_context(ram)+ return {"family": "qwen", "model": model, "title": families["qwen"]["title"] + " " + model, "context": ctx,+ "backend": "metal", "gpu": {k: usable[0].get(k) for k in ("index", "name", "vram_gb")},+ "download_gb": models[model]["download_gb"], "why": why, "notes": notes,+ "setup_command": f"./setup.sh --setup --yes --family qwen --model {model} --context {ctx}"}++ def _mac_model_table(self, hw: dict) -> list:+ models, families, _ctx, _src = self.tables()+ ram = float(hw.get("ram_gb") or 0)+ have = {c.stem[len("strata-"):] for c in self.configs()}+ fd = families["qwen"]+ sizes = []+ for m in self._mac_sizes(models):+ d = models[m]+ tag = (fd.get("tag", "") + m).lower()+ sizes.append({"model": m, "about": d["about"], "download_gb": d["download_gb"], "experimental": False,+ "images": False, # the app's first release reads no pictures (setup.py's Control mode says so)+ "ram_needed_gb": d["ram_gb"], "experts_gb": d.get("arena_gb"), "mem_total": False,+ "memory_gb": round(float(d.get("arena_gb") or d["ram_gb"]) + 1.0, 1),+ "on_this_pc": self._mac_verdict(m, ram) if ram else None, "installed": tag in have, "id": tag})+ return [{"family": "qwen", "title": fd["title"], "about": fd.get("about"), "experimental": False, "images": False, "sizes": sizes}]+def recommend(self, hw: dict) -> dict:"""setup.py's own rules: the size it preselects (IQ3_XXS from 60 GB of RAM, else the first, Q2_0), theCoder below the full model's RAM (setup's RAM table), the low-RAM mode when the GPU makes up for the RAM, andthe context it preselects for the card's VRAM (32K under 14 GB, 64K under 20 GB, else 128K)."""models, families, _ctx, _src = self.tables()+ if hw.get("mac"):+ return self._mac_recommend(hw, models, families)S = self.setup_module()usable = [g for g in hw.get("gpus", []) if g.get("usable")]ram = hw.get("ram_gb") or 0@@ -824,6 +915,8 @@ class Strata:"download_gb": models[model]["download_gb"], "why": why, "notes": notes, "setup_command": cmd}def model_table(self, hw: dict | None) -> list:+ if (hw or {}).get("mac"):+ return self._mac_model_table(hw)models, families, _ctx, _src = self.tables()S = self.setup_module()ram = (hw or {}).get("ram_gb")diff --git a/tools/test_setup_mac.py b/tools/test_setup_mac.pyindex 900180a4e..cabaeaacc 100644--- a/tools/test_setup_mac.py+++ b/tools/test_setup_mac.py@@ -251,6 +251,107 @@ class RepackGuard(unittest.TestCase):self.assertNotIn("mmap", src) # no dirty mapping of the output+M4 = {"machdep.cpu.brand_string": "Apple M4", "hw.memsize": str(32 * 2 ** 30), "macos": "27.2", "hw.perflevel0.physicalcpu": "4"}+++class ControlMode(unittest.TestCase):+ """The app on a Mac (STRATA_CONTROL_INSTALL=1): model files and a run config naming the engine component. No source build, no+ metal/setup_mac.py, no Command Line Tools; the Mac rules are strata_control/mac_fit.py's, the module setup_mac.py uses too."""++ def setUp(self):+ self.tmp = tempfile.TemporaryDirectory()+ self.addCleanup(self.tmp.cleanup)+ self.home = Path(self.tmp.name).resolve() / "install"+ self.data = Path(self.tmp.name).resolve() / "data"+ self.models = Path(self.tmp.name).resolve() / "own"+ self.home.mkdir()+ self.models.mkdir()+ fam = setup.FAMILIES["qwen"]+ self.files = []+ for i in (1, 2):+ f = self.models / setup.model_file(fam, "Q2_0", i)+ f.write_bytes(b"x")+ f.with_name(f.name + ".done").write_text("whole")+ self.files.append(f)++ def run_setup(self, hw=M4, argv=("--yes", "--no-start", "--family", "qwen", "--model", "Q2_0", "--context", "8192"), clt_rc=0):+ from strata_control import engine_component, mac_fit+ ran = []++ def fake_tool(cmd, **kw):+ ran.append(cmd)+ pack = Path(cmd[cmd.index("--out") + 1])+ (pack / "tokenizer").mkdir(parents=True, exist_ok=True)+ (pack / "native_experts.txt").write_text("x")+ (pack / "tokenizer" / "vocab.json").write_text("{}")+ patches = [+ mock.patch.object(setup, "CONTROL", True), mock.patch.object(setup, "_CONTROL_HOME", self.home),+ mock.patch.object(setup.sys, "platform", "darwin"),+ mock.patch.object(setup.sys, "argv", ["setup.py", *argv, "--data-dir", str(self.data), "--gguf-dir", str(self.models)]),+ mock.patch.object(mac_fit, "mac_info", lambda run=None, _real=mac_fit.mac_info: _real(fake_run(hw, clt_rc))),+ mock.patch.object(setup, "load_settings", lambda: {}), mock.patch.object(setup, "save_settings", lambda s: None),+ mock.patch.object(setup, "get_llama_cpp", lambda: Path(self.tmp.name) / "llama"),+ mock.patch.object(setup, "whole_shard", lambda s: True), mock.patch.object(setup, "check_shards", lambda s: None),+ mock.patch.object(setup, "run", fake_tool), mock.patch.object(setup, "free_gb", lambda p: 500.0),+ mock.patch.object(setup, "say", lambda *a, **k: None), mock.patch.object(setup, "ok", lambda *a, **k: None),+ mock.patch.object(setup, "step", lambda *a, **k: None),+ mock.patch.object(setup, "warn", lambda *a, **k: self.warnings.append(" ".join(str(x) for x in a))),+ mock.patch.object(mac_fit.platform, "machine", return_value="arm64"),+ mock.patch.object(engine_component, "resolve", side_effect=engine_component.EngineMissing("no package here", None)),+ mock.patch.object(setup, "mac_setup", side_effect=AssertionError("setup_mac.py must not run in Control mode")),+ mock.patch.object(setup.subprocess, "call", side_effect=AssertionError("nothing is started or built")),+ ]+ self.warnings = []+ for p in patches:+ p.start()+ self.addCleanup(p.stop)+ rc = setup.main()+ return rc, ran++ def config(self, tag="q2_0"):+ import json+ return json.loads((self.home / f"strata-{tag}.json").read_text(encoding="utf-8"))++ def test_the_install_writes_a_run_config_for_the_engine_component(self):+ rc, ran = self.run_setup()+ self.assertEqual(rc, 0)+ cfg = self.config()+ self.assertEqual(cfg["exe"], "component:strata-engine")+ self.assertEqual(cfg["backend"], "metal")+ args = cfg["args"]+ # a 32 GB Mac streams Q2_0's experts from the SSD: one token per step, no draft layer, the GGUF mapped in place+ self.assertEqual(args[args.index("--native") + 1], str(self.files[0]))+ self.assertEqual(args[args.index("--ple-gguf") + 1], str(self.files[1]))+ self.assertIn("--mmap-experts", args)+ self.assertNotIn("--mtp", args)+ self.assertEqual(args[args.index("--suffix-draft") + 1], "0")+ self.assertEqual(args[args.index("--max-context") + 1], "8192")+ self.assertEqual(cfg["env"], {"STRATA_METAL_STREAM": "1"})+ self.assertEqual(cfg["tokenizer"], str(self.data / "packs" / "q2_0" / "tokenizer"))+ self.assertEqual(len(ran), 1, "only the pack is made (tools/iq_pack.py): no draft layer, no build")+ self.assertTrue(ran[0][1].endswith("iq_pack.py"))+ self.assertFalse((ROOT / "build-metal").exists() and any((ROOT / "build-metal").glob("*.stamp")))++ def test_a_big_mac_keeps_the_pack_in_memory_and_adds_the_draft_layer(self):+ rc, ran = self.run_setup(hw=M5, argv=("--yes", "--no-start", "--model", "IQ3_XXS"))+ self.assertEqual(rc, 0)+ cfg = self.config("iq3_xxs")+ self.assertIn("--mtp", cfg["args"])+ self.assertEqual(cfg["env"], {"STRATA_METAL_STREAM": "0"})+ self.assertEqual(cfg["args"][cfg["args"].index("--max-context") + 1], "65536") # the default context by memory++ def test_no_command_line_tools_needed_and_the_unsloth_files_are_not_offered(self):+ rc, _ = self.run_setup(clt_rc=2)+ self.assertEqual(rc, 0)+ with self.assertRaises(SystemExit):+ self.run_setup(argv=("--yes", "--no-start", "--model", "UD-Q4_K_XL"))++ def test_other_platforms_and_the_terminal_still_use_their_own_setup(self):+ src = (ROOT / "setup.py").read_text(encoding="utf-8")+ self.assertIn('if sys.platform == "darwin" and not CONTROL:', src)+ self.assertIn('if sys.platform == "darwin" and CONTROL:', src)++class Source(unittest.TestCase):"""setup.py hands a Mac over before its own parser runs, so the Mac parser has to know --source:source_hint() recommends it on every platform (#2363)."""diff --git a/tools/test_strata_mcp.py b/tools/test_strata_mcp.pyindex a1098d87c..5ff8f1df7 100644--- a/tools/test_strata_mcp.py+++ b/tools/test_strata_mcp.py@@ -609,6 +609,73 @@ class Helpers(unittest.TestCase):self.assertEqual(r["context"], 32768)+class MacCatalog(unittest.TestCase):+ """A Mac (Apple Silicon): one pool of unified memory, judged by strata_control/mac_fit.py (the rules metal/setup_mac.py uses)."""++ def hw(self, ram, macos="27.2", chip="Apple M4"):+ from strata_control import mac_fit+ s = M.Strata(HERE.parent)+ info = {"chip": chip, "ram_gb": float(ram), "macos": macos, "arm64": True, "clt": "", "perf_cores": 4}+ with mock.patch.object(M.sys, "platform", "darwin"), mock.patch.object(mac_fit, "mac_info", return_value=info):+ hw = s._hardware()+ return s, hw++ def test_the_hardware_is_one_apple_gpu_with_unified_memory(self):+ s, hw = self.hw(32)+ self.assertEqual(hw["ram_gb"], 32.0)+ self.assertEqual(len(hw["gpus"]), 1)+ g = hw["gpus"][0]+ self.assertEqual((g["vendor"], g["name"], g["usable"], g["vram_gb"], g["unified_gb"]), ("apple", "Apple M4", True, 0.0, 32.0))+ self.assertEqual(hw["mac"]["unified_gb"], 32.0)+ self.assertFalse(hw["nvidia_smi"])++ def test_recommendation_by_unified_memory(self):+ cases = {32: ("Q2_0", 32768), 48: ("Q2_0", 32768), 80: ("IQ3_XXS", 32768), 128: ("IQ3_S", 65536)}+ for ram, (model, ctx) in cases.items():+ s, hw = self.hw(ram)+ r = s.recommend(hw)+ self.assertEqual((r["family"], r["model"], r["context"], r["backend"]), ("qwen", model, ctx, "metal"), ram)+ self.assertNotIn("NVIDIA", r["why"])+ self.assertFalse([n for n in r["notes"] if "UD-" in n], "the Unsloth sizes are not offered in the app yet")+ s, hw = self.hw(32)+ self.assertIn("read from the SSD", s.recommend(hw)["why"])+ s, hw = self.hw(128)+ self.assertIn("stays in memory", s.recommend(hw)["why"])++ def test_a_mac_too_small_or_too_old_has_no_recommendation_and_says_why(self):+ s, hw = self.hw(8)+ r = s.recommend(hw)+ self.assertIsNone(r["model"])+ self.assertIn("8 GB of unified memory", r["why"])+ s, hw = self.hw(32, macos="14.6")+ r = s.recommend(hw)+ self.assertIsNone(r["model"])+ self.assertIn("macOS 15 or newer", r["why"])++ def test_the_model_list_is_the_macs_sizes_with_unified_memory_verdicts(self):+ s, hw = self.hw(32)+ fams = s.model_table(hw)+ self.assertEqual([f["family"] for f in fams], ["qwen"], "no Unsloth, Swift or NVFP4 on a Mac in the app")+ by = {x["model"]: x for x in fams[0]["sizes"]}+ self.assertEqual(list(by), ["Q2_0", "IQ3_XXS", "IQ3_S"])+ self.assertIn("read from the SSD", by["Q2_0"]["on_this_pc"])+ self.assertIn("slower", by["Q2_0"]["on_this_pc"])+ self.assertIn("~14 tok/s", by["Q2_0"]["on_this_pc"])+ self.assertTrue(by["IQ3_S"]["on_this_pc"].startswith("slow here"))+ self.assertFalse(any(x["images"] for x in by.values()))+ s, hw = self.hw(128)+ self.assertEqual({x["on_this_pc"] for x in s.model_table(hw)[0]["sizes"]}, {"fits"})+ s, hw = self.hw(8)+ self.assertEqual({x["on_this_pc"] for x in s.model_table(hw)[0]["sizes"]}, {"does not fit"})++ def test_a_pc_is_unchanged(self):+ s = M.Strata(HERE.parent)+ r = s.recommend({"ram_gb": 96, "gpus": [{"index": 0, "name": "x", "vram_gb": 24.0, "usable": True, "vendor": "nvidia"}],+ "cpu": {"avx2": True}})+ self.assertEqual((r["family"], r["model"]), ("qwen", "IQ3_XXS"))+ self.assertIn("unsloth", [f["family"] for f in s.model_table({"ram_gb": 96, "gpus": []})])++if __name__ == "__main__":unittest.main()