Skip to content

Free, open-source AI video generator for Mac. Run LTX-2.5 and MiniMax H3 (Hailuo) locally on Apple Silicon: text-to-video and image-to-video with sound, lip-sync, character LoRA training, songs from lyrics (YuE2) and image editing (Qwen-Image-Edit). One-click install via Pinokio. Offline: no cloud, no API key, no NVIDIA GPU.

release(v4.8.0): Hailuo H3 uses half the memory, and runs on smaller Macs

mrbizarrof97ea3c13c4c
diff --git a/VERSION b/VERSION
index f6cdf40..88f1811 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-4.7.0
+4.8.0
diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.py
index b7b6702..5f432c0 100644
--- a/mlx_ltx_panel.py
+++ b/mlx_ltx_panel.py
@@ -1257,6 +1257,10 @@ def get_settings_public() -> dict:
"spicy_mode": bool(s.get("spicy_mode", False)),
"memory_policy": s.get("memory_policy", DEFAULT_MEMORY_POLICY),
"live_preview": str(s.get("live_preview", "on")),
+ # Write-only until now: `update_settings` validated and stored it, but
+ # the GET never returned it, so any control would open showing "auto"
+ # no matter what the user had chosen.
+ "h3_dit": str(s.get("h3_dit", "auto") or "auto"),
"update_banner_dismissed": str(s.get("update_banner_dismissed", "") or ""),
"star_prompt_done": bool(s.get("star_prompt_done", False)),
# Analytics. Same has_X-boolean treatment as the other secrets —
@@ -6977,6 +6981,37 @@ def _detect_total_ram_gb() -> float:
SYSTEM_RAM_GB = _detect_total_ram_gb()
+# The RAM floor of each tier, in GB. `_detect_tier()` gates on these AND
+# `min_ram_gb_for()` quotes them, so a refusal can no longer name a number the
+# gate does not use.
+#
+# THE BUG THIS CLOSES (@fiction, Pinokio, 2026-08-29 — "the high720P Q8 is not
+# clickable"): four separate refusals told the user to "bump to 64+ GB" for
+# High, Extend, FFLF and the HQ chip. All four are `allows_*` flags that the
+# table grants on `standard`, whose floor is 48 — and the tier modal three
+# clicks away says so in its own words ("48-79 GB ... Every video mode works").
+# So the app simultaneously told a 36 GB owner to buy 64 and told them 48 was
+# enough, and 16 GB of unnecessary hardware is an expensive way to find out
+# which sentence was maintained.
+TIER_MIN_RAM_GB: dict[str, int] = {
+ "base": 0,
+ "standard": 48,
+ "high": 80,
+ "pro": 120,
+}
+
+
+def min_ram_gb_for(capability: str) -> int | None:
+ """Lowest RAM in GB at which `capability` is True in CAPABILITIES.
+
+ Returns None if no tier offers it — callers fall back to prose rather than
+ printing "None GB", because a capability nothing serves is a bug in the
+ table, not something to quote a number for.
+ """
+ floors = [TIER_MIN_RAM_GB[k] for k, caps in CAPABILITIES.items()
+ if caps.get(capability) and k in TIER_MIN_RAM_GB]
+ return min(floors) if floors else None
+
def _detect_tier() -> str:
"""Pick a tier based on `hw.memsize`. Cached at module load — RAM is
@@ -6988,9 +7023,9 @@ def _detect_tier() -> str:
gb = SYSTEM_RAM_GB
if gb <= 0:
return "standard" # safe default
- if gb < 48: return "base"
- if gb < 80: return "standard"
- if gb < 120: return "high"
+ if gb < TIER_MIN_RAM_GB["standard"]: return "base"
+ if gb < TIER_MIN_RAM_GB["high"]: return "standard"
+ if gb < TIER_MIN_RAM_GB["pro"]: return "high"
return "pro"
@@ -7107,7 +7142,31 @@ H3_MIN_RAM_GB = 60.0
# calls measured-safe) the render peak drops from 42.8 to 27.3 GiB measured at
# 1024x576/124f — which puts H3 in reach of 48 GB Macs. 46 leaves the same
# ~4 GB guard band under the marketing number that 60-under-64 does.
-H3_MIN_RAM_GB_Q8 = 46.0
+# LOWERED 46 -> 36 on 2026-08-29, on measurement rather than on a guard band.
+#
+# 46 was picked to sit ~4 GB under a 48 GB Mac's marketing number, back when the
+# only number anyone had was "27.3 GiB peak". The full phase profile since then:
+#
+# text_encode 25.63 GiB <- the run peak, a 7-second phase
+# dit_load 20.22
+# joint_denoise 21.26 (5 s) / 24.68 (10 s)
+# video_vae 8.42
+#
+# 25.63 GiB is 27.5 GB. The panel now also caps H3's memory budget so the render
+# leaves the user real headroom (h3_memory_budget: the larger of 6 GB and RAM/8),
+# where before it took everything but one gigabyte. 27.5 + 6 = 33.5, so a 36 GB
+# Mac clears it with room; 48 GB was never the real requirement.
+#
+# EVIDENCE: Q8 rendered clean at a simulated 36 GB budget (--memory-gb 30
+# --wired-gb 26) AND at a simulated 32 GB budget (26/22), both rc=0 and both
+# byte-identical (sha256 ba65bc6a...) to the unconstrained render.
+#
+# 32 IS DELIBERATELY NOT THE FLOOR. 27.5 GB of peak on a 32 GB Mac leaves ~4.5
+# GB for macOS and everything else, which is the "it's tight so you can't use
+# your Mac" state the owner explicitly rejected. Those runs also simulated the
+# limit on a 64 GB machine, which caps MLX without reproducing real pressure
+# from the rest of the system. Moving to 32 needs a real 32 GB Mac, not a flag.
+H3_MIN_RAM_GB_Q8 = 36.0
H3_DIT_Q8_DIRNAME = "h3-dit-q8"
H3_DIT_FILENAME = "MiniMax-H3-FL2VA-pruned_bf16.safetensors"
H3_COMPACT_FILES = ("text_encoder.safetensors", "video_vae.safetensors",
@@ -8886,7 +8945,8 @@ def ltx_tiers_payload() -> dict:
f"Not available on the {SYSTEM_CAPS['label']} hardware "
f"tier — the Q8 dev transformer (~19 GB) plus the "
f"upscaler stage doesn't fit in this Mac's memory. "
- f"Standard and Quick run here; High needs 64+ GB.")
+ f"Standard and Quick run here; High needs "
+ f"{min_ram_gb_for('allows_q8') or 48} GB or more.")
return {
"tiers": tiers,
"qualities": [dict(q) for q in sorted(
@@ -9033,6 +9093,99 @@ def _h3_venv_present() -> bool:
return (venv / "pyvenv.cfg").is_file() or (venv / "bin" / "activate").is_file()
+# =============================================================================
+# H3 PROMPT-EMBEDDING CACHE — the 26 GB model that sets H3's memory ceiling
+# =============================================================================
+#
+# MEASURED 2026-08-29, and it is not where anyone was looking. Per-phase peaks
+# from the staged runner, identical across every arm to two decimals:
+#
+# text_encode_q8 25.71 GiB <- the RUN PEAK on the Q8 path
+# dit_load 20.22 GiB (Q8) 38.56 GiB (bf16)
+# joint_denoise 21.28 GiB (5 s) 24.68 GiB (10 s)
+# video_vae_decode 8.04 GiB
+#
+# On the Q8 path H3's memory requirement is therefore set by a SEVEN-SECOND
+# phase at the start of a twenty-minute render, not by the render. The cause is
+# `ddalcu-q8/text_encoder.safetensors` — 26.28 GB, a ~23B-parameter LLM that is
+# already 88% 8-bit (439 quantized tensors, 23.13 GB) with only 3.15 GB left
+# dense. There is no easy win inside the file.
+#
+# The win is not loading it. The runner has always accepted `--prompt-cache`:
+# a read-through .npz of the prompt embedding, with NO draft-only restriction
+# (unlike `--draft-cache-dir`, which the runner refuses outside `--draft-decode
+# tae`). The panel never passed it, so every H3 render re-encoded the same
+# prompt from a 26 GB model — paying both the peak and the seconds.
+#
+# KEYING. The runner validates the cache against the prompt AND the first-frame
+# key, and RAISES on a mismatch rather than rendering the wrong thing. Its own
+# first-frame key is the PATH STRING, so a file edited in place would pass its
+# check while carrying different pixels. This key includes the first frame's
+# size and mtime as well, which is strictly finer: a changed file lands on a
+# different cache entry and re-encodes, instead of hitting a stale embedding.
+H3_PROMPT_CACHE_KEEP = 40
+
+
+def h3_prompt_cache_dir() -> Path:
+ return STATE_DIR / "h3_prompt_cache"
+
+
+def h3_prompt_cache_path(prompt: str, first_frame) -> Path | None:
+ """Cache file for this (prompt, first frame), or None if it cannot be keyed.
+
+ Returns None for an empty prompt: the chained shot-list path drives windows
+ from `--chain-prompts` and passes no positional prompt, and the runner
+ already disables the cache for every window after the first.
+ """
+ if not (prompt or "").strip():
+ return None
+ ff_key = ""
+ if first_frame:
+ ff = Path(str(first_frame))
+ ff_key = str(ff)
+ try:
+ st = ff.stat()
+ ff_key = f"{ff}|{st.st_size}|{int(st.st_mtime)}"
+ except OSError:
+ # An unreadable first frame is not a reason to fail the render; it
+ # only means this key is the path alone, exactly like the runner's.
+ pass
+ digest = hashlib.sha256(
+ (prompt + "\x00" + ff_key).encode("utf-8")).hexdigest()[:32]
+ path = h3_prompt_cache_dir() / f"{digest}.npz"
+ # A POISONED ENTRY WOULD BE PERMANENT. `np.savez_compressed` writes to the
+ # destination directly, so a render stopped mid-write (the /stop button, a
+ # crash, a full disk) leaves a truncated file — and the runner's loader
+ # would then raise on THAT prompt for every future render, with no way for
+ # the user to know why one prompt had stopped working. An .npz is a zip, so
+ # a torn one is cheap to spot and cheaper to throw away: the only cost of
+ # deleting it is re-encoding once, which is what happened before the cache
+ # existed anyway.
+ if path.exists() and not zipfile.is_zipfile(path):
+ try:
+ path.unlink()
+ except OSError:
+ return None
+ return path
+
+
+def h3_prune_prompt_cache(keep: int = H3_PROMPT_CACHE_KEEP) -> int:
+ """Drop the oldest entries. Embeddings are megabytes, not gigabytes, but an
+ unbounded cache in the user's state dir is a slow leak either way."""
+ d = h3_prompt_cache_dir()
+ if not d.is_dir():
+ return 0
+ files = sorted(d.glob("*.npz"), key=lambda f: f.stat().st_mtime, reverse=True)
+ dropped = 0
+ for f in files[keep:]:
+ try:
+ f.unlink()
+ dropped += 1
+ except OSError:
+ pass
+ return dropped
+
+
def h3_paths() -> dict:
"""Resolve every H3 component. Never raises — reports what's missing so
the UI can render an honest install card instead of a stack trace."""
@@ -9161,7 +9314,26 @@ def h3_dit_choice() -> tuple[str, Path | None]:
return "bf16", None
if pref == "q8" and q8 is None:
pref = "auto" # fall through, surfaced via /status
- if SYSTEM_RAM_GB < H3_MIN_RAM_GB and q8 is not None:
+ # AUTO NOW MEANS Q8 WHEREVER IT EXISTS, not just on small Macs.
+ #
+ # Until 2026-08-29 a 64 GB machine was handed the bf16 master because "its
+ # peak fits". It does fit, and it also leaves nothing behind it: measured on
+ # one prompt and seed at 640x384/73f,
+ #
+ # bf16 dit_load 38.56 GiB denoise peak 38.89 GiB 196.9 s
+ # q8 dit_load 20.22 GiB denoise peak 21.38 GiB 200.1 s
+ #
+ # 45% less memory for 1.6% more time. The campaign note that priced Q8 at
+ # "~12% slower" was seven times too pessimistic, and that number is why the
+ # heavy default went unquestioned for so long.
+ #
+ # The owner watched H3 sit at ~50 GB, asked for the memory back, and graded
+ # the pair himself: "b look fine they are slightly different but quality is
+ # good." Faces are his metric, so that grade is the authority here — not the
+ # fact that bf16 technically fits.
+ #
+ # `h3_dit: bf16` still forces the master for anyone who wants it.
+ if q8 is not None:
return "q8", q8
return "bf16", None
@@ -10394,6 +10566,69 @@ def h3_supports_chain_prompts() -> bool:
return _h3_runner_has_flag("--chain-prompts")
+def h3_supports_memory_limits() -> bool:
+ """Whether the INSTALLED runner accepts `--memory-gb` / `--wired-gb`."""
+ return (_h3_runner_has_flag("--memory-gb")
+ and _h3_runner_has_flag("--wired-gb"))
+
+
+def h3_memory_budget(total_ram_gb: float | None = None) -> tuple[float, float]:
+ """(memory_gb, wired_gb) for THIS Mac, leaving the user room to keep using it.
+
+ THE BUG THIS FIXES. The runner's defaults are `--wired-gb 50` and
+ `--memory-gb 58`, and it clamps them with
+
+ memory_bytes = min(memory_gb * GiB, device.memory_size - 1 GiB)
+
+ so on ANY Mac below 59 GB the 58 never binds and the clamp does: MLX is
+ allowed everything except ONE gigabyte. Measured across the sizes people
+ actually own:
+
+ 32 GB Mac -> limit 31.0 GB, 1.0 GB left for the user
+ 36 GB Mac -> limit 35.0 GB, 1.0 GB left
+ 48 GB Mac -> limit 47.0 GB, 1.0 GB left
+ 64 GB Mac -> limit 58.0 GB, 6.0 GB left (the dev machine, where it was tuned)
+
+ One gigabyte is not enough to keep a browser open, which is exactly the
+ owner's complaint: "when it's tight, you cannot use your Mac, so this is
+ bad." The defaults were shaped by the machine they were written on.
+
+ This costs no render speed and changes no output, because H3 does not need
+ the memory it was being handed: the measured Q8 peak is 25.63 GiB and bf16
+ is 42.17 GiB. The smallest Mac we serve H3 on (the 46 GB Q8 floor, i.e. a
+ 48 GB machine) keeps 42 GB of budget against a 25.63 GiB peak — a limit
+ that was never the binding constraint, standing in front of headroom that
+ was.
+
+ Headroom is the larger of 6 GB and an eighth of RAM: a fixed number starves
+ a big machine of nothing and a proportional one leaves a small machine too
+ little, so take whichever is kinder.
+ """
+ ram = float(total_ram_gb if total_ram_gb is not None else SYSTEM_RAM_GB)
+ if ram <= 0:
+ return (0.0, 0.0)
+ headroom = max(6.0, ram / 8.0)
+ memory_gb = max(8.0, ram - headroom)
+ # Wired memory cannot be paged out at all, so it gets a wider margin than
+ # the overall limit. The runner clamps this again to the device's own
+ # max_recommended_working_set_size, which is the real ceiling.
+ wired_gb = max(4.0, memory_gb - max(4.0, ram / 16.0))
+ return (round(memory_gb, 1), round(wired_gb, 1))
+
+
+def h3_supports_prompt_cache() -> bool:
+ """Whether the INSTALLED runner accepts `--prompt-cache`.
+
+ Same discipline as --chain-prompts / --draft-decode: PROBE, never assume.
+ The flag is present on `codex/h3-engine-v2` (the branch install_h3.js
+ clones, verified 2026-08-29 at scripts/generate_staged.py:831), but a pack
+ cloned before it renders perfectly well and would die on an argparse error
+ thirty seconds in. Without the cache such a user simply re-encodes the
+ prompt, which is exactly what every user did until today.
+ """
+ return _h3_runner_has_flag("--prompt-cache")
+
+
def h3_supports_tae_draft() -> bool:
"""Whether the INSTALLED runner accepts `--draft-decode` (TAE fast decode).
@@ -20632,6 +20867,24 @@ def run_h3_job_inner(job: dict) -> None:
cmd += ["--chain-prompts", str(chain_prompts_path)]
if first_frame is not None:
cmd += ["--first-frame", str(first_frame)]
+ # Skip the 26 GB text encoder when this exact prompt+first-frame has been
+ # encoded before. On the Q8 path that phase IS the run peak (25.71 GiB vs
+ # 21.28-24.68 GiB for denoise), so a hit lowers the ceiling as well as
+ # saving the 7-8 s. On bf16 the ceiling stays the DiT and only the seconds
+ # come back. Read-through: the runner writes the entry on a miss.
+ if h3_supports_memory_limits():
+ _mem_gb, _wired_gb = h3_memory_budget()
+ if _mem_gb > 0:
+ cmd += ["--memory-gb", str(_mem_gb), "--wired-gb", str(_wired_gb)]
+ _pc = h3_prompt_cache_path(prompt, first_frame) if h3_supports_prompt_cache() else None
+ if _pc is not None:
+ # Prune BEFORE the render, so the entry this run is about to write is
+ # never the one evicted.
+ try:
+ h3_prune_prompt_cache()
+ except Exception: # noqa: BLE001
+ pass
+ cmd += ["--prompt-cache", str(_pc)]
# ---- Fast draft decode (TAE) --------------------------------------------
# H3's video decoder is a 36-layer ViT and it is the single largest FIXED
# cost in a render: 88 s of a 501 s clip, 77% of everything that is not
@@ -21114,7 +21367,8 @@ def run_job_inner(job: dict) -> None:
"hardware_tier",
f"Extend isn't supported on the {SYSTEM_CAPS['label']} hardware "
f"tier — the dev transformer needs more headroom than this Mac "
- f"has. Bump to 64+ GB or render the longer clip in one shot."
+ f"has. It works from {min_ram_gb_for('allows_extend') or 48} GB "
+ f"— or render the longer clip in one shot."
)
# Y1.036 — Extend always loads the Q8 `transformer-dev.safetensors`
# weights (CFG-guided dev transformer, not the 8-step distilled).
@@ -21754,7 +22008,7 @@ def run_job_inner(job: dict) -> None:
f"FFLF (keyframe interpolation) isn't supported on the "
f"{SYSTEM_CAPS['label']} hardware tier — Q8 + the dev "
f"transformer's two-stage memory peak doesn't fit. "
- f"Bump to 64+ GB."
+ f"It works from {min_ram_gb_for('allows_keyframe') or 48} GB."
)
# Check the SAME file list the menu + /status report on. The old
# "directory exists and non-empty" check let half-downloaded Q8
@@ -22300,7 +22554,8 @@ def run_job_inner(job: dict) -> None:
f"High quality (Q8 two-stage) isn't supported on the "
f"{SYSTEM_CAPS['label']} hardware tier — Q8 dev transformer "
f"(~19 GB) plus the upscaler stage doesn't fit. "
- f"Use Standard or Quick instead, or upgrade to 64+ GB."
+ f"Use Standard or Quick instead — High works from "
+ f"{min_ram_gb_for('allows_q8') or 48} GB."
)
# Route to TwoStageHQPipeline (Q8 dev model + res_2s sampler + CFG anchor + TeaCache).
# Defaults from ltx-2-mlx CLAUDE.md LTX_2_3_PARAMS.
@@ -44606,6 +44861,29 @@ HTML = r"""<!doctype html>
<option value="off">Off</option>
</select>
</div>
+ <!-- H3 DiT. The setting has been honoured by `h3_dit_choice()` and
+ validated by the settings handler since it was added, and its own
+ docstring says "`h3_dit` in Settings" — but no control was ever
+ built, so the only way to reach it was a hand-written POST. The
+ owner watched H3 sit at ~50 GB and asked why we could not reduce it;
+ the answer was a setting he could not see. Numbers here are measured,
+ not estimated (640x384/73f, seed 424242, same-seed A/B). -->
+ <div class="settings-row" style="margin-top:10px" id="settingsH3DitRow" hidden>
+ <label>Hailuo H3 model</label>
+ <select id="settingsH3Dit" style="flex:1">
+ <option value="auto">Automatic — best quality this Mac can hold</option>
+ <option value="bf16">Full (bf16) — 42 GiB peak</option>
+ <option value="q8">Compact (Q8) — 21 GiB peak, half the memory</option>
+ </select>
+ </div>
+ <div class="hint" id="settingsH3DitHint" style="margin-top:6px" hidden>
+ Measured on the same prompt and seed: <b>Full 38.9 GiB</b> peak in 196.9 s
+ versus <b>Compact 21.4 GiB</b> in 200.1 s — <b>45 % less memory for 1.6 %
+ more time</b>. Automatic gives a 64 GB Mac the full model and anything
+ smaller the compact one. Choose Compact if you want to keep using the Mac
+ while it renders; the memory it gives back is memory H3 was holding, not
+ memory it needed.
+ </div>
<div class="hint" style="margin-top:6px">
Never changes the result — the clip is byte-for-byte the same either way.
Costs a fraction of the render: about 0.2 % on High, a few per cent on a
@@ -57020,6 +57298,18 @@ async function openSettingsModal() {
lpSelect.value = (cur.live_preview === 'off') ? 'off' : 'on';
renderMemoryPolicyHint();
}
+ // H3 model. Hidden entirely when H3 is not installed — an install that
+ // cannot render H3 has no use for a control that only changes how it does.
+ const ditRow = document.getElementById('settingsH3DitRow');
+ const ditHint = document.getElementById('settingsH3DitHint');
+ const ditSelect = document.getElementById('settingsH3Dit');
+ if (ditRow && ditSelect) {
+ const haveH3 = !!(LAST_STATUS && LAST_STATUS.h3 && LAST_STATUS.h3.available);
+ ditRow.hidden = !haveH3;
+ if (ditHint) ditHint.hidden = !haveH3;
+ const v = String(cur.h3_dit || 'auto').toLowerCase();
+ ditSelect.value = ['auto', 'bf16', 'q8'].includes(v) ? v : 'auto';
+ }
// Token rows. We never receive the actual key from the server (the
// /settings GET returns has_X booleans only), so we display either
@@ -57419,6 +57709,8 @@ async function applySettings() {
}
fd.set('memory_policy', document.getElementById('settingsMemoryPolicy')?.value || 'auto');
fd.set('live_preview', document.getElementById('settingsLivePreview')?.value || 'on');
+ const _dit = document.getElementById('settingsH3Dit')?.value;
+ if (_dit) fd.set('h3_dit', _dit);
// Tokens — only send a key when the input has a value. Empty input
// means "leave as-is" (clearing is explicit via the Clear button).
// This protects against accidentally wiping a saved key by clicking
diff --git a/mlx_warm_helper.py b/mlx_warm_helper.py
index 375279b..ebb888a 100644
--- a/mlx_warm_helper.py
+++ b/mlx_warm_helper.py
@@ -129,6 +129,75 @@ def _log_memory_pressure() -> None:
pass
+# =============================================================================
+# PER-PHASE MLX MEMORY — the number that decides whether a render fits
+# =============================================================================
+#
+# WHY THIS EXISTS
+# ---------------
+# `_log_memory_pressure()` above measures the whole MACHINE via vm_stat. That
+# answers "is this Mac under pressure", which is not the same question as
+# "which part of OUR render is the spike". H3's staged runner has printed a
+# per-phase peak since the port, and that is exactly why its memory questions
+# get answered in minutes; LTX had no equivalent, so the 2026-08 allocator-cache
+# win (a third of peak, free) was found by a global A/B rather than by looking
+# at a profile. 38.8% of the fleet renders below 48 GB, where the peak phase is
+# the difference between a finished clip and a swap storm — those users deserve
+# a log line that names the phase, and so do we.
+#
+# Peak is RESET at each phase boundary so every line is that phase's own high
+# water mark rather than a running maximum that only ever reports the worst
+# phase. The run maximum is tracked separately and emitted once at the end.
+
+_MLX_RUN_PEAK_GIB = 0.0
+
+
+def _mlx_mem_reset_run() -> None:
+ """Start a fresh per-run memory profile."""
+ global _MLX_RUN_PEAK_GIB
+ _MLX_RUN_PEAK_GIB = 0.0
+ try:
+ import mlx.core as mx # noqa: PLC0415
+ mx.reset_peak_memory()
+ except Exception: # noqa: BLE001
+ pass
+
+
+def _mlx_phase_mem(label: str) -> float | None:
+ """Log this phase's MLX peak, then reset so the next phase stands alone.
+
+ Returns the phase peak in GiB, or None when MLX cannot be queried (an old
+ library, or a build without the memory API) — callers treat it as optional
+ telemetry and never branch on it.
+ """
+ global _MLX_RUN_PEAK_GIB
+ try:
+ import mlx.core as mx # noqa: PLC0415
+ gib = 1024.0 ** 3
+ peak = mx.get_peak_memory() / gib
+ active = mx.get_active_memory() / gib
+ cache = mx.get_cache_memory() / gib
+ except Exception: # noqa: BLE001
+ return None
+ if peak > _MLX_RUN_PEAK_GIB:
+ _MLX_RUN_PEAK_GIB = peak
+ emit({"event": "log",
+ "line": f"[mlx] {label}: peak {peak:.2f} GiB · active {active:.2f} · cache {cache:.2f}"})
+ try:
+ mx.reset_peak_memory()
+ except Exception: # noqa: BLE001
+ pass
+ return peak
+
+
+def _mlx_mem_summary() -> float:
+ """Emit the whole run's peak — the one number a Compact Mac cares about."""
+ if _MLX_RUN_PEAK_GIB > 0:
+ emit({"event": "log",
+ "line": f"[mlx] run peak {_MLX_RUN_PEAK_GIB:.2f} GiB"})
+ return _MLX_RUN_PEAK_GIB
+
+
def _aggressive_cleanup_before_generate() -> None:
"""Minimize Metal heap fragmentation before pipeline generation."""
try:
@@ -2595,6 +2664,7 @@ for line in sys.__stdin__:
_is_busy = True
try:
t0 = time.time()
+ _mlx_mem_reset_run()
# Granular breadcrumbs so a silent helper death is traceable:
# if the panel's last log line is "step:get_pipe" then we died
# during pipeline init (likely OOM or weight-load issue). If
@@ -2621,6 +2691,12 @@ for line in sys.__stdin__:
model_dir=p.get("model_dir"))
emit({"event": "log", "line": "step:get_pipe done"})
_log_memory_pressure()
+ # NOT "weights": measured on a live 4.7.0 render, this reads
+ # 0.00 GiB because `get_pipe` is lazy — the pack is faulted in
+ # during generate, so its residency lands in the denoise figure.
+ # Labelling it "weights" would have every reader conclude the
+ # model is free.
+ _mlx_phase_mem("pipeline init")
accel_mode = configure_acceleration(p.get("accel", "off"))
negative_prompt = _clean_text(p.get("negative_prompt"))
effective_prompt = _prompt_with_soft_negative(p["prompt"], negative_prompt)
@@ -2716,6 +2792,7 @@ for line in sys.__stdin__:
# Step 1: generate latents (no save)
video_latent, audio_latent = _generate_latents(pipe, needs_image=needs_image, kwargs=kwargs)
emit({"event": "log", "line": "step:generate done"})
+ _mlx_phase_mem("denoise")
# Free DiT + text encoder before the upscale + VAE decode peak.
emit({"event": "log", "line": "step:free_generation_modules start"})
_free_pipe_for_decode(pipe)
@@ -2724,6 +2801,7 @@ for line in sys.__stdin__:
emit({"event": "log", "line": "step:latent_upscale_x2 start"})
video_latent = _model_upscale_video_latent(pipe, video_latent)
emit({"event": "log", "line": f"step:latent_upscale_x2 done — latent {video_latent.shape[-2]}×{video_latent.shape[-1]}"})
+ _mlx_phase_mem("latent upscale")
# Free the upscaler before VAE decode (can be ~2-3 GB peak).
_free_upscaler()
# Step 3: VAE decode + save (decoder loads inside _decode_and_save_video).
@@ -2734,11 +2812,14 @@ for line in sys.__stdin__:
# panel's wait_done while MLX tears down ~10 GB of Metal
# buffers + lazy graph nodes synchronously.
emit({"event": "log", "line": "step:decode_and_save done"})
+ _mlx_phase_mem("decode+save")
+ _mlx_mem_summary()
_aggressive_cleanup_before_generate()
if not use_model_upscale:
emit({"event": "log", "line": f"step:generate mode={mode} {kwargs['width']}x{kwargs['height']} {kwargs['num_frames']}f @{kwargs['frame_rate']:.1f}fps steps={kwargs['num_steps']} accel={accel_mode}"})
video_latent, audio_latent = _generate_latents(pipe, needs_image=needs_image, kwargs=kwargs)
emit({"event": "log", "line": "step:generate done"})
+ _mlx_phase_mem("denoise")
emit({"event": "log", "line": "step:free_generation_modules start"})
_free_pipe_for_decode(pipe)
emit({"event": "log", "line": "step:free_generation_modules done"})
@@ -2757,6 +2838,8 @@ for line in sys.__stdin__:
# FIX 2026-05-14: upstream renamed fps= → frame_rate= (keyword-only).
out_path = pipe._decode_and_save_video(video_latent, audio_latent, kwargs["output_path"], frame_rate=kwargs["frame_rate"])
emit({"event": "log", "line": "step:decode_and_save done"})
+ _mlx_phase_mem("decode+save")
+ _mlx_mem_summary()
elapsed = round(time.time() - t0, 2)
_last_activity = time.time()
done_event = {
@@ -2833,6 +2916,7 @@ for line in sys.__stdin__:
_is_busy = True
try:
t0 = time.time()
+ _mlx_mem_reset_run()
configure_acceleration("off")
# Extend supports LoRAs via the same _pending_loras hook;
# the dev transformer picks them up at load time just like T2V/I2V.
@@ -2938,6 +3022,7 @@ for line in sys.__stdin__:
_is_busy = True
try:
t0 = time.time()
+ _mlx_mem_reset_run()
configure_acceleration("off")
# LoRAs flow through the same wire shape as t2v/i2v. HQ is the
# only path where dev-base character LoRAs actually transfer
@@ -3131,6 +3216,7 @@ for line in sys.__stdin__:
_is_busy = True
try:
t0 = time.time()
+ _mlx_mem_reset_run()
configure_acceleration("off")
num_frames = int(p["frames"])
@@ -3248,6 +3334,7 @@ for line in sys.__stdin__:
_is_busy = True
try:
t0 = time.time()
+ _mlx_mem_reset_run()
configure_acceleration("off")
audio_path = p.get("audio_path") or ""
if not audio_path:
@@ -3356,6 +3443,7 @@ for line in sys.__stdin__:
_is_busy = True
try:
t0 = time.time()
+ _mlx_mem_reset_run()
configure_acceleration("off")
audio_path = p.get("audio_path") or ""
if not audio_path:
@@ -3442,6 +3530,7 @@ for line in sys.__stdin__:
_is_busy = True
try:
t0 = time.time()
+ _mlx_mem_reset_run()
configure_acceleration("off")
from ltx_pipelines_mlx.hdr_ic_lora import HDRICLoraPipeline
loras = p.get("loras") or []
@@ -3554,6 +3643,7 @@ for line in sys.__stdin__:
_is_busy = True
try:
t0 = time.time()
+ _mlx_mem_reset_run()
configure_acceleration("off")
from ltx_pipelines_mlx.ic_lora import ICLoraPipeline
loras = p.get("loras") or []
@@ -3707,6 +3797,7 @@ for line in sys.__stdin__:
_is_busy = True
try:
t0 = time.time()
+ _mlx_mem_reset_run()
lm = get_gemma_lm()
# Build augmented system prompt: official + Phosphene addendum.
base_sys = (lm.default_gemma_t2v_system_prompt if mode == "t2v"
diff --git a/test_h3_dit_setting.py b/test_h3_dit_setting.py
new file mode 100644
index 0000000..22bbc5e
--- /dev/null
+++ b/test_h3_dit_setting.py
@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""The H3 model choice existed for months with no way to reach it.
+
+`h3_dit_choice()` has always honoured a `h3_dit` setting, `update_settings()`
+has always validated it (auto|bf16|q8), and the docstring says in as many words
+"`h3_dit` in Settings overrides both ways". There was no control in Settings.
+It was reachable only by hand-writing a POST.
+
+That mattered on 2026-08-29: the owner watched H3 sit at ~50 GB and asked why
+we could not reduce it. The answer was a setting he could not see — Automatic
+gives a 64 GB Mac the bf16 master (38.9 GiB peak) when the Q8 pack renders the
+same shot at 21.4 GiB, 45% less memory for 1.6% more time, measured same-seed.
+
+It was ALSO write-only: `update_settings` stored it but `get_settings_public()`
+never returned it, so any control would have opened showing "auto" regardless
+of what was saved. Both halves are covered here.
+"""
+from __future__ import annotations
+
+import os
+import re
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+os.environ["LTX_STATE_DIR"] = str(Path(tempfile.mkdtemp(prefix="phos-dit-")))
+os.environ["PHOSPHENE_ANALYTICS_DISABLED"] = "1"
+os.environ["PHOSPHENE_DISABLE_VERSION_CHECK"] = "1"
+os.environ.setdefault("LTX_PORT", "8307")
+sys.path.insert(0, str(ROOT))
+
+import mlx_ltx_panel as P # noqa: E402
+
+SRC = (ROOT / "mlx_ltx_panel.py").read_text(encoding="utf-8")
+
+
+class TheSettingRoundTrips(unittest.TestCase):
+
+ def test_the_ui_can_read_the_current_value(self):
+ self.assertIn("h3_dit", P.get_settings_public())
+
+ def test_a_saved_choice_comes_back(self):
+ for want in ("q8", "bf16", "auto"):
+ with self.subTest(want=want):
+ P.update_settings({"h3_dit": want})
+ self.assertEqual(P.get_settings_public()["h3_dit"], want)
+
+ def test_junk_is_refused_with_the_valid_values_named(self):
+ _, err = P.update_settings({"h3_dit": "tiny"})
+ self.assertIsNotNone(err)
+ for v in ("auto", "bf16", "q8"):
+ self.assertIn(v, err)
+
+ def test_the_choice_actually_reaches_the_dit_picker(self):
+ P.update_settings({"h3_dit": "bf16"})
+ kind, _ = P.h3_dit_choice()
+ self.assertEqual(kind, "bf16")
+
+
+class AutoPrefersTheLightModel(unittest.TestCase):
+ """Owner graded the pair 2026-08-29: "b look fine ... quality is good."
+
+ Before that, `auto` gave any Mac with 60 GB+ the bf16 master, so the machine
+ with the most memory was the one that spent the most: 38.89 GiB peak versus
+ 21.38 GiB for the same shot at the same seed.
+ """
+
+ def test_auto_picks_q8_whenever_the_pack_is_present(self):
+ P.update_settings({"h3_dit": "auto"})
+ real = P._h3_q8_dit_dir
+ try:
+ P._h3_q8_dit_dir = lambda: Path("/tmp/pretend-q8")
+ kind, path = P.h3_dit_choice()
+ self.assertEqual(kind, "q8")
+ self.assertIsNotNone(path)
+ finally:
+ P._h3_q8_dit_dir = real
+
+ def test_auto_falls_back_to_bf16_when_q8_is_absent(self):
+ P.update_settings({"h3_dit": "auto"})
+ real = P._h3_q8_dit_dir
+ try:
+ P._h3_q8_dit_dir = lambda: None
+ self.assertEqual(P.h3_dit_choice()[0], "bf16")
+ finally:
+ P._h3_q8_dit_dir = real
+
+ def test_bf16_can_still_be_forced(self):
+ P.update_settings({"h3_dit": "bf16"})
+ real = P._h3_q8_dit_dir
+ try:
+ P._h3_q8_dit_dir = lambda: Path("/tmp/pretend-q8")
+ self.assertEqual(P.h3_dit_choice()[0], "bf16")
+ finally:
+ P._h3_q8_dit_dir = real
+ P.update_settings({"h3_dit": "auto"})
+
+
+class TheControlExists(unittest.TestCase):
+ """The whole defect was a capability with no surface."""
+
+ def test_there_is_a_select_with_all_three_values(self):
+ self.assertIn('id="settingsH3Dit"', SRC)
+ block = SRC[SRC.index('id="settingsH3Dit"'):][:900]
+ for v in ('value="auto"', 'value="bf16"', 'value="q8"'):
+ self.assertIn(v, block)
+
+ def test_the_control_is_populated_and_saved(self):
+ self.assertIn("ditSelect.value =", SRC, "the control never shows the saved value")
+ self.assertIn("fd.set('h3_dit', _dit)", SRC, "the control never saves")
+
+ def test_it_reads_a_status_global_that_exists(self):
+ m = re.search(r"const haveH3 = !!\((\w+) &&", SRC)
+ self.assertIsNotNone(m, "the H3-installed check is gone")
+ self.assertIn(f"let {m.group(1)} = null;", SRC,
+ f"{m.group(1)} is not a declared global")
+
+ def test_the_memory_numbers_shown_are_the_measured_ones(self):
+ block = SRC[SRC.index('id="settingsH3DitHint"'):][:900]
+ for n in ("38.9", "21.4", "45"):
+ self.assertIn(n, block, f"the measured figure {n} is not shown")
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/test_h3_memory_budget.py b/test_h3_memory_budget.py
new file mode 100644
index 0000000..086429f
--- /dev/null
+++ b/test_h3_memory_budget.py
@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""H3 was leaving the user one gigabyte of their own Mac.
+
+The runner defaults to `--wired-gb 50` / `--memory-gb 58` and clamps with
+
+ memory_bytes = min(memory_gb * GiB, device.memory_size - 1 GiB)
+
+so on any Mac below 59 GB the 58 never binds and the clamp does — MLX is
+allowed everything except ONE gigabyte. Measured:
+
+ 32 GB -> 31.0 GB limit, 1.0 GB left 48 GB -> 47.0 GB limit, 1.0 GB left
+ 36 GB -> 35.0 GB limit, 1.0 GB left 64 GB -> 58.0 GB limit, 6.0 GB left
+
+64 GB is the machine the defaults were written on, which is why nobody saw it.
+The owner's words: "even if it is tight, when it's tight, you cannot use your
+Mac, so this is bad."
+
+It costs nothing to fix, because H3 never needed that memory: measured peak is
+25.63 GiB on Q8 and 42.17 GiB on bf16. The limit was standing in front of
+headroom without ever being the binding constraint.
+"""
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+os.environ["LTX_STATE_DIR"] = str(Path(tempfile.mkdtemp(prefix="phos-h3-mem-")))
+os.environ["PHOSPHENE_ANALYTICS_DISABLED"] = "1"
+os.environ["PHOSPHENE_DISABLE_VERSION_CHECK"] = "1"
+os.environ.setdefault("LTX_PORT", "8305")
+sys.path.insert(0, str(ROOT))
+
+import mlx_ltx_panel as P # noqa: E402
+
+PANEL_SRC = (ROOT / "mlx_ltx_panel.py").read_text(encoding="utf-8")
+
+# Measured 2026-08-29 on the staged runner, 640x384 73f and 768x416 243f.
+H3_PEAK_Q8_GIB = 25.63
+H3_PEAK_BF16_GIB = 42.17
+
+
+class EveryMacKeepsUsableHeadroom(unittest.TestCase):
+
+ def test_no_machine_is_left_with_the_old_one_gigabyte(self):
+ for ram in (32, 36, 48, 64, 96, 128, 256):
+ with self.subTest(ram=ram):
+ mem, _ = P.h3_memory_budget(ram)
+ self.assertGreaterEqual(
+ ram - mem, 6.0,
+ f"a {ram} GB Mac keeps only {ram - mem:.1f} GB")
+
+ def test_headroom_grows_with_the_machine(self):
+ small = 32 - P.h3_memory_budget(32)[0]
+ big = 128 - P.h3_memory_budget(128)[0]
+ self.assertGreater(big, small)
+
+ def test_wired_is_below_the_overall_limit(self):
+ """Wired memory cannot be paged out, so it must be the tighter of the
+ two or the limit is meaningless."""
+ for ram in (32, 48, 64, 128):
+ mem, wired = P.h3_memory_budget(ram)
+ with self.subTest(ram=ram):
+ self.assertLess(wired, mem)
+
+ def test_the_budget_still_clears_h3s_measured_peak(self):
+ """Headroom must not be bought by making renders fail. The smallest Mac
+ we serve H3 on is the 46 GB Q8 floor, i.e. a 48 GB machine."""
+ mem48, _ = P.h3_memory_budget(48)
+ self.assertGreater(mem48, H3_PEAK_Q8_GIB + 4)
+ mem64, _ = P.h3_memory_budget(64)
+ self.assertGreater(mem64, H3_PEAK_BF16_GIB + 4)
+
+ def test_unknown_ram_disables_the_override(self):
+ """Better the runner's own defaults than a number computed from zero."""
+ self.assertEqual(P.h3_memory_budget(0), (0.0, 0.0))
+ self.assertEqual(P.h3_memory_budget(-1), (0.0, 0.0))
+
+ def test_a_tiny_machine_still_gets_a_sane_floor(self):
+ mem, wired = P.h3_memory_budget(8)
+ self.assertGreaterEqual(mem, 8.0)
+ self.assertGreaterEqual(wired, 4.0)
+
+
+class TheQ8FloorMatchesTheMeasurement(unittest.TestCase):
+ """The floor must follow the peak, not a guard band round a marketing number."""
+
+ def test_the_floor_clears_the_measured_peak_plus_real_headroom(self):
+ floor = P.H3_MIN_RAM_GB_Q8
+ peak_gb = H3_PEAK_Q8_GIB * (1024 ** 3) / (1000 ** 3) # GiB -> GB
+ mem, _ = P.h3_memory_budget(floor)
+ self.assertGreater(
+ mem, peak_gb,
+ f"a {floor} GB Mac is offered H3 but its budget ({mem} GB) is "
+ f"below the measured peak ({peak_gb:.1f} GB)")
+ self.assertGreaterEqual(floor - mem, 6.0, "no headroom left for the user")
+
+ def test_the_floor_is_not_set_below_what_was_demonstrated(self):
+ """32 GB ran in SIMULATION only, on a 64 GB machine with a flag. That
+ is not evidence a real 32 GB Mac survives, so the floor stays above it."""
+ self.assertGreater(P.H3_MIN_RAM_GB_Q8, 32.0)
+
+ def test_q8_floor_is_below_the_bf16_floor(self):
+ self.assertLess(P.H3_MIN_RAM_GB_Q8, P.H3_MIN_RAM_GB)
+
+
+class ItIsProbedAndWired(unittest.TestCase):
+
+ def test_the_probe_asks_for_both_flags(self):
+ import inspect
+ src = inspect.getsource(P.h3_supports_memory_limits)
+ self.assertIn('_h3_runner_has_flag("--memory-gb")', src)
+ self.assertIn('_h3_runner_has_flag("--wired-gb")', src)
+
+ def test_the_argv_passes_both_and_is_gated(self):
+ self.assertIn('cmd += ["--memory-gb", str(_mem_gb), "--wired-gb", str(_wired_gb)]',
+ PANEL_SRC)
+ self.assertIn("if h3_supports_memory_limits():", PANEL_SRC)
+
+ def test_a_zero_budget_passes_nothing(self):
+ self.assertIn("if _mem_gb > 0:", PANEL_SRC)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/test_h3_prompt_cache.py b/test_h3_prompt_cache.py
new file mode 100644
index 0000000..a0af2fb
--- /dev/null
+++ b/test_h3_prompt_cache.py
@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+"""H3's memory ceiling is a 7-second phase, and this is the switch that skips it.
+
+MEASURED 2026-08-29 (staged-runner phase peaks, identical across every arm):
+
+ text_encode_q8 25.71 GiB <- the RUN PEAK on the Q8 path
+ dit_load 20.22 GiB (Q8) / 38.56 GiB (bf16)
+ joint_denoise 21.28 GiB (5 s) / 24.68 GiB (10 s)
+
+So on Q8, what a Mac must fit to run H3 at all is decided by loading a 26.28 GB
+text encoder for seven seconds — not by the twenty-minute render. The encoder is
+already 88% 8-bit, so there is nothing cheap left inside the file; the win is
+not loading it.
+
+`--prompt-cache` has always been in the runner and the panel never passed it.
+This suite pins that it is passed, and pins the KEY, because the runner RAISES
+on a cache built for a different prompt or first frame — a key that is too
+coarse turns a silent cache hit into a failed render.
+"""
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+import time
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+STATE = Path(tempfile.mkdtemp(prefix="phos-h3-pc-"))
+os.environ["LTX_STATE_DIR"] = str(STATE)
+os.environ["PHOSPHENE_ANALYTICS_DISABLED"] = "1"
+os.environ["PHOSPHENE_DISABLE_VERSION_CHECK"] = "1"
+os.environ.setdefault("LTX_PORT", "8301")
+sys.path.insert(0, str(ROOT))
+
+import mlx_ltx_panel as P # noqa: E402
+
+PANEL_SRC = (ROOT / "mlx_ltx_panel.py").read_text(encoding="utf-8")
+
+
+class TheKeyIsFineEnoughToBeSafe(unittest.TestCase):
+
+ def test_same_prompt_same_frame_is_the_same_entry(self):
+ a = P.h3_prompt_cache_path("a marble bust", None)
+ b = P.h3_prompt_cache_path("a marble bust", None)
+ self.assertEqual(a, b)
+ self.assertTrue(str(a).endswith(".npz"))
+
+ def test_different_prompt_is_a_different_entry(self):
+ self.assertNotEqual(P.h3_prompt_cache_path("bust", None),
+ P.h3_prompt_cache_path("bust ", None))
+ self.assertNotEqual(P.h3_prompt_cache_path("a", None),
+ P.h3_prompt_cache_path("b", None))
+
+ def test_a_first_frame_changes_the_entry(self):
+ with tempfile.TemporaryDirectory() as d:
+ f = Path(d) / "ff.png"
+ f.write_bytes(b"x" * 100)
+ self.assertNotEqual(P.h3_prompt_cache_path("p", None),
+ P.h3_prompt_cache_path("p", f))
+
+ def test_editing_the_first_frame_in_place_changes_the_entry(self):
+ """The runner keys on the PATH alone, so an edited file would pass its
+ own check while carrying different pixels. Ours must not."""
+ with tempfile.TemporaryDirectory() as d:
+ f = Path(d) / "ff.png"
+ f.write_bytes(b"x" * 100)
+ before = P.h3_prompt_cache_path("p", f)
+ time.sleep(1.1) # mtime has 1 s resolution
+ f.write_bytes(b"y" * 250) # same path, different content
+ after = P.h3_prompt_cache_path("p", f)
+ self.assertNotEqual(before, after)
+
+ def test_missing_first_frame_still_yields_a_key(self):
+ """An unreadable frame must not take the render down."""
+ got = P.h3_prompt_cache_path("p", Path("/nope/does/not/exist.png"))
+ self.assertIsNotNone(got)
+
+ def test_empty_prompt_disables_the_cache(self):
+ """The chained shot-list path passes no positional prompt, and the
+ runner disables the cache for every window after the first anyway."""
+ self.assertIsNone(P.h3_prompt_cache_path("", None))
+ self.assertIsNone(P.h3_prompt_cache_path(" ", None))
+ self.assertIsNone(P.h3_prompt_cache_path(None, None))
+
+
+class APoisonedEntryIsThrownAwayNotInherited(unittest.TestCase):
+ """`np.savez_compressed` writes straight to the destination, so a render
+ stopped mid-write leaves a truncated .npz — and the runner's loader would
+ then raise on THAT prompt forever, with nothing telling the user why one
+ prompt had quietly stopped working."""
+
+ def test_a_truncated_entry_is_deleted(self):
+ d = P.h3_prompt_cache_dir(); d.mkdir(parents=True, exist_ok=True)
+ path = P.h3_prompt_cache_path("poison me", None)
+ path.write_bytes(b"PK\x03\x04 truncated mid-write") # torn zip
+ again = P.h3_prompt_cache_path("poison me", None)
+ self.assertEqual(again, path)
+ self.assertFalse(path.exists(), "the torn entry survived")
+
+ def test_a_valid_entry_is_left_alone(self):
+ import zipfile as _z
+ d = P.h3_prompt_cache_dir(); d.mkdir(parents=True, exist_ok=True)
+ path = P.h3_prompt_cache_path("keep me", None)
+ with _z.ZipFile(path, "w") as z:
+ z.writestr("embeds.npy", b"\x00" * 32)
+ self.assertTrue(_z.is_zipfile(path))
+ again = P.h3_prompt_cache_path("keep me", None)
+ self.assertEqual(again, path)
+ self.assertTrue(path.exists(), "a good entry was deleted")
+
+ def test_an_empty_file_counts_as_torn(self):
+ d = P.h3_prompt_cache_dir(); d.mkdir(parents=True, exist_ok=True)
+ path = P.h3_prompt_cache_path("zero bytes", None)
+ path.write_bytes(b"")
+ P.h3_prompt_cache_path("zero bytes", None)
+ self.assertFalse(path.exists())
+
+
+class ThePruneIsBounded(unittest.TestCase):
+
+ def test_prune_keeps_the_newest_and_drops_the_rest(self):
+ d = P.h3_prompt_cache_dir()
+ d.mkdir(parents=True, exist_ok=True)
+ for f in d.glob("*.npz"):
+ f.unlink()
+ made = []
+ for i in range(8):
+ f = d / f"{i:032x}.npz"
+ f.write_bytes(b"0")
+ os.utime(f, (1000 + i, 1000 + i))
+ made.append(f)
+ dropped = P.h3_prune_prompt_cache(keep=3)
+ left = sorted(x.name for x in d.glob("*.npz"))
+ self.assertEqual(dropped, 5)
+ self.assertEqual(len(left), 3)
+ self.assertEqual(left, sorted(x.name for x in made[-3:]))
+
+ def test_prune_on_an_absent_dir_is_a_no_op(self):
+ import shutil
+ shutil.rmtree(P.h3_prompt_cache_dir(), ignore_errors=True)
+ self.assertEqual(P.h3_prune_prompt_cache(), 0)
+
+
+class AnOlderRunnerMustNotBeHandedAFlagItCannotParse(unittest.TestCase):
+ """The bug this closes: `--prompt-cache` was passed unconditionally.
+
+ A pack cloned before the flag existed renders every tier correctly and
+ would have died on an argparse error thirty seconds into a render. The
+ panel already probes for --chain-prompts, --draft-decode and
+ --live-preview for exactly this reason; the cache must use the same gate.
+ """
+
+ def test_the_probe_exists_and_asks_for_the_right_flag(self):
+ self.assertTrue(hasattr(P, "h3_supports_prompt_cache"))
+ import inspect
+ src = inspect.getsource(P.h3_supports_prompt_cache)
+ self.assertIn('_h3_runner_has_flag("--prompt-cache")', src)
+
+ def test_the_argv_is_gated_on_the_probe(self):
+ line = next(ln for ln in PANEL_SRC.splitlines()
+ if "_pc = h3_prompt_cache_path(" in ln)
+ self.assertIn("h3_supports_prompt_cache()", line,
+ "the cache path is computed without probing the runner")
+
+ def test_no_probe_means_no_flag(self):
+ real = P.h3_supports_prompt_cache
+ try:
+ P.h3_supports_prompt_cache = lambda: False
+ self.assertFalse(P.h3_supports_prompt_cache())
+ finally:
+ P.h3_supports_prompt_cache = real
+
+
+class ItIsActuallyWiredIntoTheRender(unittest.TestCase):
+
+ def test_the_argv_passes_prompt_cache(self):
+ self.assertIn('cmd += ["--prompt-cache", str(_pc)]', PANEL_SRC,
+ "the H3 argv no longer passes --prompt-cache")
+
+ def test_it_prunes_before_writing_not_after(self):
+ i_prune = PANEL_SRC.index("h3_prune_prompt_cache()")
+ i_pass = PANEL_SRC.index('cmd += ["--prompt-cache"')
+ self.assertLess(i_prune, i_pass,
+ "prune must run before the entry this render writes")
+
+ def test_draft_cache_dir_is_never_passed_to_the_runner(self):
+ """`--draft-cache-dir` is refused by the runner outside --draft-decode
+ tae, so passing it on a delivery render would hard-fail. Prose may name
+ it (the comment explains why we chose the other one); an argv line may
+ not."""
+ offenders = [ln.strip() for ln in PANEL_SRC.splitlines()
+ if "--draft-cache-dir" in ln
+ and not ln.lstrip().startswith("#")]
+ self.assertEqual(offenders, [],
+ "--draft-cache-dir reached the runner argv")
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/test_mlx_phase_memory.py b/test_mlx_phase_memory.py
new file mode 100644
index 0000000..c4af459
--- /dev/null
+++ b/test_mlx_phase_memory.py
@@ -0,0 +1,172 @@
+"""Per-phase MLX memory reporting — the profile a Compact Mac renders against.
+
+`_log_memory_pressure()` measures the whole MACHINE (vm_stat). That is a
+different question from "which phase of OUR render is the spike", and only the
+second one tells you what to fix. H3's staged runner has printed a per-phase
+peak since the port; LTX printed nothing, which is why the allocator-cache win
+was found by a global A/B instead of by reading a profile.
+
+38.8% of the fleet boots under 48 GB. For those machines the PEAK PHASE decides
+whether a clip finishes or the Mac swaps, so these lines are a user-facing
+diagnostic as much as an internal one.
+
+Like `test_mlx_cache_policy`, the functions are pulled out of the real helper
+with `ast` rather than imported — the helper's module body ends in a blocking
+stdin read, so importing it would hang. Extraction RAISES if a function is
+renamed, so this cannot rot into testing a copy.
+"""
+
+import ast
+import sys
+import types
+import unittest
+from pathlib import Path
+
+HELPER = Path(__file__).with_name("mlx_warm_helper.py")
+GIB = 1024 ** 3
+
+_WANTED = ("_mlx_mem_reset_run", "_mlx_phase_mem", "_mlx_mem_summary")
+_WANTED_CONST = "_MLX_RUN_PEAK_GIB"
+
+
+def _load(fake_mlx):
+ """Exec the three real functions with a fake `emit` and a fake mlx.core."""
+ tree = ast.parse(HELPER.read_text())
+ picked, seen_fns, seen_const = [], set(), False
+ for node in tree.body:
+ if isinstance(node, ast.Assign):
+ if {t.id for t in node.targets if isinstance(t, ast.Name)} & {_WANTED_CONST}:
+ picked.append(node)
+ seen_const = True
+ elif isinstance(node, ast.FunctionDef) and node.name in _WANTED:
+ picked.append(node)
+ seen_fns.add(node.name)
+ missing = set(_WANTED) - seen_fns
+ if missing or not seen_const:
+ raise AssertionError(
+ f"helper no longer defines {sorted(missing) or _WANTED_CONST} — "
+ "the memory profile was renamed or removed, not merely edited")
+
+ logged = []
+ ns = {"emit": lambda msg: logged.append(msg)}
+ # The functions do `import mlx.core as mx` at call time, so a fake package
+ # in sys.modules is enough and no real MLX is needed to run this suite.
+ pkg = types.ModuleType("mlx"); pkg.core = fake_mlx
+ saved = {k: sys.modules.get(k) for k in ("mlx", "mlx.core")}
+ sys.modules["mlx"], sys.modules["mlx.core"] = pkg, fake_mlx
+ try:
+ exec(compile(ast.Module(body=picked, type_ignores=[]), str(HELPER), "exec"), ns)
+ ns["_run"] = lambda: None
+ return ns, logged, saved
+ except BaseException:
+ for k, v in saved.items():
+ if v is None: sys.modules.pop(k, None)
+ else: sys.modules[k] = v
+ raise
+
+
+def _fake_mlx(peaks, active=1.0, cache=0.5, broken=False):
+ """A stand-in that hands out `peaks` (GiB) one call at a time."""
+ m = types.ModuleType("mlx.core")
+ seq = list(peaks)
+ m.resets = 0
+ if not broken:
+ m.get_peak_memory = lambda: (seq.pop(0) if seq else 0.0) * GIB
+ m.get_active_memory = lambda: active * GIB
+ m.get_cache_memory = lambda: cache * GIB
+ def _reset():
+ m.resets += 1
+ m.reset_peak_memory = _reset
+ return m
+
+
+class PhaseMemory(unittest.TestCase):
+
+ def _restore(self, saved):
+ for k, v in saved.items():
+ if v is None: sys.modules.pop(k, None)
+ else: sys.modules[k] = v
+
+ def test_each_phase_reports_its_own_peak_and_resets(self):
+ fake = _fake_mlx([4.0, 11.5, 6.25])
+ ns, logged, saved = _load(fake)
+ try:
+ ns["_mlx_mem_reset_run"]()
+ self.assertEqual(ns["_mlx_phase_mem"]("weights"), 4.0)
+ self.assertEqual(ns["_mlx_phase_mem"]("denoise"), 11.5)
+ self.assertEqual(ns["_mlx_phase_mem"]("decode+save"), 6.25)
+ lines = [m["line"] for m in logged]
+ self.assertIn("[mlx] weights: peak 4.00 GiB", lines[0])
+ self.assertIn("[mlx] denoise: peak 11.50 GiB", lines[1])
+ self.assertIn("[mlx] decode+save: peak 6.25 GiB", lines[2])
+ # A reset after every phase is what makes each line that phase's
+ # OWN high-water mark instead of a running maximum.
+ self.assertGreaterEqual(fake.resets, 3)
+ finally:
+ self._restore(saved)
+
+ def test_run_summary_is_the_max_phase_not_the_last(self):
+ """The decode phase is smaller than denoise; the run peak is denoise."""
+ fake = _fake_mlx([4.0, 11.5, 6.25])
+ ns, logged, saved = _load(fake)
+ try:
+ ns["_mlx_mem_reset_run"]()
+ for label in ("weights", "denoise", "decode+save"):
+ ns["_mlx_phase_mem"](label)
+ self.assertEqual(ns["_mlx_mem_summary"](), 11.5)
+ self.assertIn("[mlx] run peak 11.50 GiB", logged[-1]["line"])
+ finally:
+ self._restore(saved)
+
+ def test_reset_run_clears_the_previous_jobs_peak(self):
+ """Job N's spike must not be reported as job N+1's."""
+ fake = _fake_mlx([30.0, 2.0])
+ ns, logged, saved = _load(fake)
+ try:
+ ns["_mlx_mem_reset_run"]()
+ ns["_mlx_phase_mem"]("huge job")
+ self.assertEqual(ns["_mlx_mem_summary"](), 30.0)
+ ns["_mlx_mem_reset_run"]() # next job starts here
+ ns["_mlx_phase_mem"]("small job")
+ self.assertEqual(ns["_mlx_mem_summary"](), 2.0)
+ finally:
+ self._restore(saved)
+
+ def test_missing_mlx_memory_api_is_silent_not_fatal(self):
+ """Telemetry may never take a render down on an older library."""
+ ns, logged, saved = _load(_fake_mlx([], broken=True))
+ try:
+ ns["_mlx_mem_reset_run"]()
+ self.assertIsNone(ns["_mlx_phase_mem"]("weights"))
+ self.assertEqual(logged, [])
+ self.assertEqual(ns["_mlx_mem_summary"](), 0.0)
+ finally:
+ self._restore(saved)
+
+ def test_summary_is_silent_when_nothing_was_measured(self):
+ ns, logged, saved = _load(_fake_mlx([]))
+ try:
+ ns["_mlx_mem_reset_run"]()
+ self.assertEqual(ns["_mlx_mem_summary"](), 0.0)
+ self.assertEqual([m for m in logged if "run peak" in m["line"]], [])
+ finally:
+ self._restore(saved)
+
+
+class WiredIntoTheRenderPath(unittest.TestCase):
+ """The probes are useless if they are defined but never called."""
+
+ def test_every_phase_boundary_calls_the_probe(self):
+ src = HELPER.read_text()
+ for call, least in (('_mlx_mem_reset_run()', 1),
+ ('_mlx_phase_mem("pipeline init")', 1),
+ ('_mlx_phase_mem("denoise")', 2),
+ ('_mlx_phase_mem("decode+save")', 2),
+ ('_mlx_mem_summary()', 2)):
+ self.assertGreaterEqual(
+ src.count(call), least,
+ f"{call} is no longer wired into the render path")
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/test_refusal_gates.py b/test_refusal_gates.py
index 43e6f08..b1dafdf 100644
--- a/test_refusal_gates.py
+++ b/test_refusal_gates.py
@@ -297,8 +297,15 @@ class TestH3RamRefusalStatesTheRealFloor(unittest.TestCase):
return P.h3_ram_verdict()
def test_the_two_floors_are_the_ones_the_product_believes(self):
+ # The Q8 floor moved 46 -> 36 on 2026-08-29, when the full phase profile
+ # replaced the single "27.3 GiB" figure it had been guessed from and the
+ # panel started leaving the user real headroom. The bf16 floor is
+ # unchanged. These are asserted as ORDER and RELATION, not as literals:
+ # pinning the number is what made this test fail for a correct change,
+ # and a stale literal here is the same defect the class exists to catch.
self.assertEqual(P.H3_MIN_RAM_GB, 60.0)
- self.assertEqual(P.H3_MIN_RAM_GB_Q8, 46.0)
+ self.assertLess(P.H3_MIN_RAM_GB_Q8, P.H3_MIN_RAM_GB)
+ self.assertGreater(P.H3_MIN_RAM_GB_Q8, 32.0)
def test_a_big_mac_is_not_blocked(self):
v = self._band(64.0, False)
@@ -318,12 +325,13 @@ class TestH3RamRefusalStatesTheRealFloor(unittest.TestCase):
self.assertIn("runs on this Mac", v["message"])
self.assertIn("Install Hailuo H3", v["message"])
- def test_a_small_mac_is_told_46_not_64(self):
+ def test_a_small_mac_is_told_the_real_floor_not_64(self):
+ """The message must quote the floor the code actually gates on."""
v = self._band(32.0, False)
self.assertIsNone(v["lane"])
self.assertTrue(v["blocked"])
self.assertFalse(v["needs_q8_dit"])
- self.assertIn("46", v["message"])
+ self.assertIn(str(int(P.H3_MIN_RAM_GB_Q8)), v["message"])
self.assertNotIn("about 64", v["message"])
self.assertIn("LTX", v["message"])
diff --git a/test_tier_ram_advice.py b/test_tier_ram_advice.py
new file mode 100644
index 0000000..2a3d2a5
--- /dev/null
+++ b/test_tier_ram_advice.py
@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""The RAM number a refusal quotes must be the one the gate actually uses.
+
+REPORTED (@fiction, Pinokio, 2026-08-29): "the high720P Q8 is not clickable,
+could you solve this?" — the chip is disabled on purpose below the Q8 tier,
+so the honest answer is the reason text. Reading it is what found the real
+bug: four refusals told the user to "bump to 64+ GB" for High, Extend, FFLF
+and the HQ chip, and all four are `allows_*` flags the table grants on
+`standard`, whose floor is 48 GB. The tier modal a few clicks away already
+said "48-79 GB ... Every video mode works", so the app contradicted itself and
+the losing sentence cost 16 GB of hardware to act on.
+
+`test_refusal_gates` records that this same High refusal was 23 events across
+6 people in one 14-day fleet read, so the text is not hypothetical: people
+reach it, and some of them will go buy a Mac because of it.
+
+The fix derives the number from CAPABILITIES + TIER_MIN_RAM_GB. This suite
+pins the derivation AND scans the shipped strings, because the failure mode
+was never a wrong function — it was prose drifting away from a correct gate.
+"""
+from __future__ import annotations
+
+import os
+import re
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+STATE = Path(tempfile.mkdtemp(prefix="phos-tier-ram-"))
+os.environ["LTX_STATE_DIR"] = str(STATE)
+os.environ["PHOSPHENE_ANALYTICS_DISABLED"] = "1"
+os.environ["PHOSPHENE_DISABLE_VERSION_CHECK"] = "1"
+os.environ.setdefault("LTX_PORT", "8298")
+sys.path.insert(0, str(ROOT))
+
+import mlx_ltx_panel as P # noqa: E402
+
+PANEL_SRC = (ROOT / "mlx_ltx_panel.py").read_text(encoding="utf-8")
+
+
+class TheFloorTableIsTheOneSourceOfTruth(unittest.TestCase):
+
+ def test_detect_tier_gates_on_the_published_floors(self):
+ """A boundary the table names must be the boundary the gate uses."""
+ for tier, floor in P.TIER_MIN_RAM_GB.items():
+ if floor == 0:
+ continue
+ self.assertEqual(
+ P._detect_tier.__globals__["TIER_MIN_RAM_GB"][tier], floor)
+ # Exercised at the edges, since off-by-one here mis-tiers real Macs.
+ cases = [(47.9, "base"), (48.0, "standard"), (79.9, "standard"),
+ (80.0, "high"), (119.9, "high"), (128.0, "pro")]
+ for gb, expected in cases:
+ with self.subTest(gb=gb):
+ old = P.SYSTEM_RAM_GB
+ try:
+ P.SYSTEM_RAM_GB = gb
+ self.assertEqual(P._detect_tier(), expected)
+ finally:
+ P.SYSTEM_RAM_GB = old
+
+ def test_the_big_three_are_available_from_48(self):
+ """High / FFLF / Extend all unlock on `standard`, not on 64 GB."""
+ for cap in ("allows_q8", "allows_keyframe", "allows_extend"):
+ with self.subTest(cap=cap):
+ self.assertEqual(P.min_ram_gb_for(cap), 48)
+
+ def test_unknown_capability_returns_none_not_a_number(self):
+ """Better no number than a confidently wrong one."""
+ self.assertIsNone(P.min_ram_gb_for("allows_a_thing_that_does_not_exist"))
+
+ def test_derivation_follows_the_table_if_the_table_moves(self):
+ real = P.CAPABILITIES
+ try:
+ P.CAPABILITIES = {
+ "base": dict(real["base"], allows_q8=False),
+ "standard": dict(real["standard"], allows_q8=False),
+ "high": dict(real["high"], allows_q8=True),
+ }
+ self.assertEqual(P.min_ram_gb_for("allows_q8"), 80)
+ finally:
+ P.CAPABILITIES = real
+
+
+class NoRefusalQuotesAHardcodedRamNumber(unittest.TestCase):
+ """The regression was prose, so the prose is what gets scanned."""
+
+ # H3 is the one honest 64: H3_MIN_RAM_GB is 60, so a 64 GB machine really
+ # is the floor. Its lines are allowed to say so.
+ _H3_OK = re.compile(r"h3|hailuo|~75 GB", re.IGNORECASE)
+
+ def test_no_ltx_capability_message_hardcodes_a_ram_figure(self):
+ """Scan ADVICE only.
+
+ The tier table's own `ram_label`/blurb legitimately name GB — they are
+ the source the advice should be derived FROM. What must never be
+ hardcoded is the imperative: "bump to N", "upgrade to N", "needs N".
+ """
+ advice = re.compile(r"(bump to|upgrade to|needs \d+\+? GB"
+ r"|requires \d+\+? GB)", re.IGNORECASE)
+ offenders = []
+ for i, line in enumerate(PANEL_SRC.splitlines(), 1):
+ stripped = line.lstrip()
+ if stripped.startswith(("#", "*", "//")):
+ continue # commentary may cite history
+ if not advice.search(line):
+ continue
+ if self._H3_OK.search(line):
+ continue # H3's 64 is real
+ if "min_ram_gb_for" in line:
+ continue # derived: exactly right
+ offenders.append(f"{i}: {stripped[:110]}")
+ self.assertEqual(
+ offenders, [],
+ "these tell the user a RAM number the tier table does not own — "
+ "derive it with min_ram_gb_for() instead:\n "
+ + "\n ".join(offenders))
+
+ def test_the_four_fixed_sites_derive_their_number(self):
+ """Pin the specific sites @fiction's report exposed."""
+ self.assertGreaterEqual(
+ PANEL_SRC.count("min_ram_gb_for('allows_q8')"), 2,
+ "the High chip reason and the HQ refusal must both derive it")
+ for cap in ("allows_extend", "allows_keyframe"):
+ self.assertIn(f"min_ram_gb_for('{cap}')", PANEL_SRC)
+
+
+if __name__ == "__main__":
+ unittest.main()