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

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.py
index 575aa8931..1d4717ade 100644
--- a/metal/setup_mac.py
+++ b/metal/setup_mac.py
@@ -32,27 +32,19 @@ from pathlib import Path
ROOT = Path(__file__).resolve().parent.parent
sys.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-256
METAL_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 engine
def 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.py
index 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 user
from 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 below
return 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.source
if a.inspect: # headers only: nothing is installed
sys.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.py
index 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 131072
diff --git a/strata_control/mac_fit.py b/strata_control/mac_fit.py
new file mode 100644
index 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 so
diff --git a/tests/terminal/test_launch.py b/tests/terminal/test_launch.py
index 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.py
index 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: BLE001
hw["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), the
Coder below the full model's RAM (setup's RAM table), the low-RAM mode when the GPU makes up for the RAM, and
the 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.py
index 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.py
index 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()