@ignix-social/editor 0.1.0

package/vendor/hyperframes/dist/skills/media-use/scripts/lib/local-models.mjs

@@ -0,0 +1,318 @@
+// Declarative table of USER-INSTALLED local models, for the spec-gated fallback.
+//
+// These models run on the user's own machine for their own use; media-use
+// recommends, spec-checks, and assists install; it does not bundle, redistribute,
+// or sell them. Because nothing is redistributed, selection is purely by
+// quality / size / spec-fit / word-timestamp support (there is deliberately NO
+// license field gating availability).
+//
+// Tiers (`small`|`medium`|`large`|`xlarge`) are human labels; `needs.ramMB` is
+// what selection actually gates on. selectModel() returns the best model that
+// fits the machine's AVAILABLE RAM, best-first: by explicit `rank` when set
+// (quality that is NOT size, e.g. ASR), else by RAM footprint (the quality
+// proxy for generation). No fit -> recommend the CLI/cloud path.
+//
+// selectModelLadder() returns EVERY fitting model in that same order. Callers
+// that can retry walk it so ONE unusable entry (gated weights, a missing
+// binary, an OOM) demotes to the next tier instead of killing the local path.
+//
+// Picks reflect the 2026 research pass, verified live where noted.
+
+export const CAPABILITIES = ["tts", "asr", "upscale", "videogen", "imagegen"];
+
+const MODELS = {
+  tts: [
+    {
+      id: "kokoro",
+      tier: "medium",
+      sizeMB: 330,
+      needs: { ramMB: 2048, gpu: false },
+      wordTimestamps: "native",
+      install: "pip install kokoro",
+      invoke: "python -m kokoro --text {text} --voice {voice} --out {out}",
+      notes: "CPU, faster-than-realtime, native per-word timestamps. Default floor.",
+    },
+    {
+      id: "fish-speech",
+      tier: "large",
+      sizeMB: 1100,
+      needs: { ramMB: 16000, gpu: true, vramMB: 12000 },
+      wordTimestamps: "whisperx", // needs forced alignment (run ASR over output)
+      install: "pip install fish-speech",
+      invoke: "fish-speech synth --text {text} --ref {ref} --out {out}",
+      notes: "Expressive zero-shot voice cloning; meeting pick. WhisperX for word timing.",
+    },
+  ],
+  asr: [
+    // Parakeet is BETTER than Whisper yet SMALLER (0.6B vs 1.5B), so quality is
+    // not size here: `rank` pins it ahead of whisper regardless of footprint.
+    // Open ASR Leaderboard avg WER: Parakeet ~6.05% vs whisper-large-v3 7.44%
+    // (~19% better); on NOISY test-other 4.73% vs 5.96%, and whisper-v3
+    // hallucinated to 308% WER on meetings where Parakeet held. 5-10x faster.
+    //
+    // Cohere Transcribe 2B tops the leaderboard (5.42%) and is nominally the most
+    // accurate, but its mlx-audio community MLX quants (4bit AND 8bit, with and
+    // without --language en) produced multilingual token-soup garbage AND ran
+    // 40-70x slower than Parakeet on a 24GB Mac (live-tested 2026-07). Excluded
+    // until the mlx-audio Cohere decoder stabilizes; Parakeet is the default.
+    {
+      id: "parakeet-mlx",
+      tier: "small",
+      rank: 0,
+      sizeMB: 2400,
+      needs: { ramMB: 4000, gpu: true },
+      wordTimestamps: "tokens", // sub-word tokens; merged to words by parakeet-words.mjs
+      repo: "mlx-community/parakeet-tdt-0.6b-v3",
+      install:
+        "uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx",
+      invoke:
+        "parakeet-mlx {audio} --model mlx-community/parakeet-tdt-0.6b-v3 --output-format json --output-dir {outdir}",
+      notes:
+        "NVIDIA Parakeet-TDT 0.6B via parakeet-mlx. VERIFIED on 24GB: accurate transcript, ~3s (cached model) for 8s audio, word timestamps drive transcript-cut. English + 25 European languages. Beats whisper.cpp on accuracy (6.05% vs 7.44% WER) AND speed (5-10x).",
+    },
+    {
+      id: "whisperx",
+      tier: "medium",
+      rank: 1,
+      sizeMB: 1500,
+      needs: { ramMB: 4096, gpu: false },
+      wordTimestamps: "native", // faster-whisper + wav2vec2 forced alignment
+      install: "pip install whisperx",
+      invoke: "whisperx {audio} --output_format json --out {out}",
+      notes:
+        "CPU-only fallback (no GPU): faster-whisper + wav2vec2 forced alignment, native word timestamps. The packaged `hyperframes transcribe` (whisper.cpp) is the zero-setup baseline below this.",
+    },
+  ],
+  upscale: [
+    {
+      id: "real-esrgan",
+      tier: "medium",
+      sizeMB: 70,
+      needs: { ramMB: 2048, gpu: false },
+      wordTimestamps: false,
+      install: "brew install real-esrgan-ncnn-vulkan  # or download the ncnn binary",
+      invoke: "realesrgan-ncnn-vulkan -i {in} -o {out} -s 4",
+      notes: "ncnn-vulkan binary, CPU-capable. GFPGAN for faces.",
+    },
+    {
+      id: "seedvr2",
+      tier: "large",
+      sizeMB: 6000,
+      needs: { ramMB: 24000, gpu: true, vramMB: 16000 },
+      wordTimestamps: false,
+      install: "pip install seedvr2",
+      invoke: "seedvr2 upscale --in {in} --out {out}",
+      notes: "Diffusion upscaler, GPU-only. Video2X for video.",
+    },
+  ],
+  videogen: [
+    // 2026-07 X research pass + live verification on a 24GB M-series Mac -
+    // which reaches the q4 tier only: a 24GB machine cannot select the 32GB
+    // entry below it, so that tier's claims stay unverified until someone
+    // runs it on a 32GB+ machine.
+    // The Mac-local video story is LTX 2.3 on MLX via dgrauet/ltx-2-mlx (the
+    // pipeline these weights were converted for; also powers Phosphene).
+    // Wan 2.x MLX exists only as A14B conversions (too large for consumer
+    // unified memory); revisit when a 5B Wan MLX conversion lands.
+    // IMPORTANT: sizeMB below is the FULL repo, because that is what a run
+    // actually downloads. Both invokes pass a repo id to `--model`, and
+    // upstream resolve_model_dir() (ltx_pipelines_mlx/utils/_orchestration.py)
+    // calls snapshot_download(repo) with no allow_patterns - so the whole repo
+    // lands regardless of what you pre-fetched. A targeted `hf download
+    // --include` subset used to be documented here; it was removed because it
+    // is both ineffective (the runner refetches the rest at generate time) and
+    // insufficient (--two-stage needs transformer-dev AND transformer-distilled
+    // AND the x2 spatial upscaler; --distilled needs an upscaler too). The q4
+    // tier verified below only worked BECAUSE the download is unfiltered.
+    {
+      id: "ltx-2.3-mlx-q4",
+      tier: "medium",
+      sizeMB: 59700, // full repo, measured 59.69GB; gemma-3-12b-4bit text encoder adds ~7GB
+      needs: { ramMB: 16384, gpu: true },
+      wordTimestamps: false,
+      install:
+        'git clone https://github.com/dgrauet/ltx-2-mlx && cd ltx-2-mlx && uv sync --all-extras && export PATH="$PWD/.venv/bin:$PATH"',
+      invoke:
+        "ltx-2-mlx generate --prompt {prompt} --distilled --low-ram --model dgrauet/ltx-2.3-mlx-q4 --width {w} --height {h} --frames {frames} --frame-rate 24 --output {out}",
+      notes:
+        "LTX 2.3 int4 on MLX. Verified on 24GB unified: 512x320 x 33 frames in ~19 min cold (incl. text-encoder download), t2v with audio. Dims must be multiples of 64. i2v, retake/extend, keyframe interpolation supported.",
+    },
+    {
+      id: "ltx-2.3-mlx-q8",
+      tier: "large",
+      sizeMB: 87500, // full repo, measured 87.51GB
+      needs: { ramMB: 32768, gpu: true },
+      wordTimestamps: false,
+      install:
+        'git clone https://github.com/dgrauet/ltx-2-mlx && cd ltx-2-mlx && uv sync --all-extras && export PATH="$PWD/.venv/bin:$PATH"',
+      invoke:
+        "ltx-2-mlx generate --prompt {prompt} --two-stage --low-ram --model dgrauet/ltx-2.3-mlx-q8 --width {w} --height {h} --frames {frames} --frame-rate 24 --output {out}",
+      notes:
+        "LTX 2.3 int8 on MLX, two-stage (upstream production default; higher quality than the q4 distilled tier). Replaced dgrauet/ltx-2.3-mlx-bf16, which is gated (HTTP 401) and cannot be downloaded at all. Costs an 87.5GB download against q4's 59.7GB - a real tradeoff, not a rounding difference. --two-stage is dev model + CFG at half-res, upscale, then distilled LoRA refine (upstream's own help text), so it needs transformer-dev + transformer-distilled + spatial_upscaler_x2; the full snapshot carries all three. --low-ram matches this tier's 32GB floor (block streaming); 64-128GB Macs for long/HD runs. NOT live-verified on a 32GB+ machine - the q4 tier below is the verified one.",
+    },
+  ],
+  imagegen: [
+    // 2026-07 X research + live verification on a 24GB M-series Mac. mflux
+    // (FLUX-on-MLX) is the Mac-native runner; FLUX is the quality leader. Two
+    // hard-won findings baked into `needs.ramMB`:
+    //   1. The OFFICIAL FLUX repos are HF-gated (license wall). Point --path at a
+    //      non-gated community 4-bit re-upload (self-contained, incl. VAE).
+    //   2. Without --low-ram, FLUX's T5-XXL text encoder + transformer blow past
+    //      24GB into swap: a 768x512 run took 90 MINUTES. With --low-ram (streams
+    //      components from disk) the SAME machine did 512x512 in ~20s at 7.6GB
+    //      free. So the medium tier's needs.ramMB is the streamed floor, not the
+    //      resident footprint; the large tiers are the no-streaming thresholds.
+    // The runner resolves `repo` to a local snapshot (hf download) before --path;
+    // a bare repo id in --path breaks mlx unflatten.
+    {
+      id: "flux-schnell-mflux-q4",
+      tier: "medium",
+      sizeMB: 8700,
+      needs: { ramMB: 8000, gpu: true },
+      repo: "dhairyashil/FLUX.1-schnell-mflux-4bit",
+      wordTimestamps: false,
+      install: "uv venv ~/.venvs/mflux && VIRTUAL_ENV=~/.venvs/mflux uv pip install mflux==0.9.6",
+      invoke:
+        "mflux-generate --model schnell --path {model_path} --low-ram --steps 4 --prompt {prompt} --width {w} --height {h} --seed {seed} --output {out}",
+      notes:
+        "FLUX.1 schnell int4. VERIFIED on 24GB (7.6GB free): --low-ram 512x512 in ~20s, photoreal. --low-ram is MANDATORY at this tier (streams to avoid swap). Few-step, fast.",
+    },
+    {
+      id: "flux2-klein-mflux-q4",
+      tier: "large",
+      sizeMB: 12000,
+      needs: { ramMB: 32000, gpu: true },
+      repo: "Runpod/FLUX.2-klein-4B-mflux-4bit",
+      wordTimestamps: false,
+      install: "uv venv ~/.venvs/mflux && VIRTUAL_ENV=~/.venvs/mflux uv pip install mflux",
+      invoke:
+        "mflux-generate --base-model flux2-klein-4b --path {model_path} --steps 8 --prompt {prompt} --width {w} --height {h} --seed {seed} --output {out}",
+      notes:
+        "FLUX.2 Klein 4B int4 (most-downloaded mflux community repo). Newer, higher quality than schnell; full-resident (no streaming) so needs 32GB+ to stay fast. Needs mflux >= 0.18 for the flux2-klein base model.",
+    },
+    {
+      id: "qwen-image-mflux",
+      tier: "xlarge",
+      sizeMB: 40000,
+      needs: { ramMB: 64000, gpu: true },
+      repo: "Qwen/Qwen-Image",
+      wordTimestamps: false,
+      install: "uv venv ~/.venvs/mflux && VIRTUAL_ENV=~/.venvs/mflux uv pip install mflux",
+      invoke:
+        "mflux-generate --base-model qwen --steps 20 --prompt {prompt} --width {w} --height {h} --seed {seed} --output {out}",
+      notes:
+        "Qwen-Image, top-tier quality. Heavy: 'several minutes' even on 128GB M4 Max, 'almost fried' a 32GB M4 Pro. 64GB+ only. Below that, the cloud upsell (codex) is faster and better.",
+    },
+  ],
+};
+
+function tableFor(capability) {
+  const t = MODELS[capability];
+  if (!t) throw new Error(`unknown local-model capability: ${capability}`);
+  return t;
+}
+
+/** All local models for a capability. */
+export function listModels(capability) {
+  return tableFor(capability).slice();
+}
+
+// Tokenize an `invoke` template on whitespace first, then substitute each
+// token, so a `{prompt}`/`{model_path}` value with spaces stays a single argv
+// entry. Shared by every local-model provider (mflux, LTX) that builds argv
+// from a MODELS[...].invoke template.
+export function buildArgv(template, vars) {
+  return template
+    .trim()
+    .split(/\s+/)
+    .map((tok) => tok.replace(/\{(\w+)\}/g, (_, k) => (k in vars ? String(vars[k]) : `{${k}}`)));
+}
+
+/** Does this machine meet a model's needs? Apple Silicon unified memory counts as VRAM. */
+export function meetsSpecs(model, specs) {
+  const n = model.needs || {};
+  // Gate on AVAILABLE RAM when the probe reported it (the real budget with the
+  // OS + open apps resident); fall back to total RAM otherwise. Older specs
+  // objects (and unit fixtures) that only set ramMB keep working unchanged.
+  const budget = specs.availableRamMB ?? specs.ramMB;
+  if (n.ramMB && budget < n.ramMB) return false;
+  if (n.gpu && !specs.gpu?.present) return false;
+  if (n.vramMB) {
+    const vram = specs.gpu?.vramMB ?? 0;
+    if (vram < n.vramMB) return false;
+  }
+  return true;
+}
+
+// "Best model the machine can run" == best-first among those that fit. Ordering:
+//   1. explicit `rank` (lower = better) when a model declares it. Needed where
+//      quality is NOT size: Parakeet-0.6B beats Whisper-large-1.5B at ASR, so
+//      footprint would pick the wrong one.
+//   2. otherwise RAM footprint descending, the quality proxy for generation
+//      (a 40GB image model out-renders a 12GB one).
+function rankedByPreference(table) {
+  return [...table].sort((a, b) => {
+    const ra = a.rank ?? Infinity;
+    const rb = b.rank ?? Infinity;
+    if (ra !== rb) return ra - rb;
+    return (b.needs?.ramMB ?? 0) - (a.needs?.ramMB ?? 0);
+  });
+}
+
+/**
+ * Every local model for a capability this machine can actually run, best-first
+ * (same ordering as selectModel, whose pick is this list's head).
+ *
+ * Callers that can retry should walk the whole list: a table entry can be
+ * unusable for reasons no spec check can see - weights pulled or gated behind a
+ * login, the runner missing from PATH, an OOM at a tier that nominally fits. On
+ * a single-select call any one of those fails the entire local path, because the
+ * cascade cannot tell "this model is broken" from "nothing here fits you".
+ * Demoting to the next fitting tier is almost always what the user wanted.
+ */
+export function selectModelLadder(capability, specs, { preferTier } = {}) {
+  const table = tableFor(capability);
+  const pool = preferTier ? table.filter((m) => m.tier === preferTier) : table;
+  return rankedByPreference(pool).filter((model) => meetsSpecs(model, specs));
+}
+
+/**
+ * Pick the best local model the machine can run for a capability: the
+ * highest-footprint model that fits the available-RAM budget (and GPU/VRAM).
+ * `preferTier` pins the search to one tier (e.g. force a smaller/faster model).
+ * Returns `{ model, tier }`, or `{ recommend: "cli", reason }` when nothing fits.
+ */
+export function selectModel(capability, specs, { preferTier } = {}) {
+  const table = tableFor(capability);
+  const [model] = selectModelLadder(capability, specs, { preferTier });
+  if (model) return { model, tier: model.tier };
+  const smallest = table.reduce((a, b) => (a.sizeMB <= b.sizeMB ? a : b));
+  return {
+    recommend: "cli",
+    reason: `machine does not meet specs for any local ${capability} model (smallest needs ~${smallest.needs.ramMB}MB RAM${smallest.needs.gpu ? " + GPU" : ""}); use the CLI path instead`,
+  };
+}
+
+/**
+ * Agent-facing ladder: every model for a capability, best-first, each flagged
+ * with whether it fits this machine and why. Lets the agent see the RAM-graded
+ * options and choose (e.g. trade the auto-picked best for a smaller/faster one,
+ * or step up to a cloud upsell) rather than only getting one auto-selection.
+ */
+export function describeModelLadder(capability, specs) {
+  const budget = specs.availableRamMB ?? specs.ramMB;
+  return rankedByPreference(tableFor(capability)).map((model) => {
+    const fits = meetsSpecs(model, specs);
+    return {
+      id: model.id,
+      tier: model.tier,
+      needsRamMB: model.needs?.ramMB ?? 0,
+      sizeMB: model.sizeMB,
+      fits,
+      reason: fits
+        ? `fits (needs ~${model.needs?.ramMB}MB, ${budget}MB available)`
+        : `too big (needs ~${model.needs?.ramMB}MB${model.needs?.gpu ? " + GPU" : ""}, ${budget}MB available)`,
+      notes: model.notes,
+    };
+  });
+}

package/vendor/hyperframes/dist/skills/media-use/scripts/lib/local-models.test.mjs

@@ -0,0 +1,220 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import {
+  listModels,
+  meetsSpecs,
+  selectModel,
+  selectModelLadder,
+  describeModelLadder,
+  CAPABILITIES,
+} from "./local-models.mjs";
+
+const TIERS = ["small", "medium", "large", "xlarge"];
+
+const strongGpu = {
+  ramMB: 64000,
+  gpu: { present: true, kind: "nvidia", vramMB: 24000 },
+  appleSilicon: false,
+};
+const cpuOnly = { ramMB: 16000, gpu: { present: false, vramMB: 0 }, appleSilicon: false };
+const tiny = { ramMB: 1024, gpu: { present: false, vramMB: 0 }, appleSilicon: false };
+
+test("every capability table is non-empty and well-formed", () => {
+  for (const cap of CAPABILITIES) {
+    const models = listModels(cap);
+    assert.ok(models.length > 0, `no models for ${cap}`);
+    for (const m of models) {
+      assert.ok(m.id && m.tier && m.needs, `${cap}/${m.id} missing fields`);
+      assert.ok(TIERS.includes(m.tier), `${cap}/${m.id} bad tier: ${m.tier}`);
+      assert.equal(typeof m.install, "string", `${cap}/${m.id} needs an install command`);
+      assert.equal(typeof m.invoke, "string", `${cap}/${m.id} needs an invoke command`);
+      // user-installed, local-use-only: there is NO license gate on selection
+      assert.equal("license" in m, false, `${cap}/${m.id} must not carry a license gate`);
+    }
+  }
+});
+
+test("meetsSpecs enforces RAM, GPU presence, and VRAM", () => {
+  const gpuModel = { needs: { ramMB: 8000, gpu: true, vramMB: 12000 } };
+  assert.equal(meetsSpecs(gpuModel, strongGpu), true);
+  assert.equal(meetsSpecs(gpuModel, cpuOnly), false, "no GPU -> fails a GPU model");
+  const cpuModel = { needs: { ramMB: 2000, gpu: false } };
+  assert.equal(meetsSpecs(cpuModel, cpuOnly), true);
+  assert.equal(meetsSpecs(cpuModel, tiny), false, "too little RAM");
+});
+
+test("Apple Silicon unified memory counts as VRAM", () => {
+  const apple = {
+    ramMB: 24000,
+    appleSilicon: true,
+    gpu: { present: true, kind: "apple", vramMB: 24000 },
+  };
+  const gpuModel = { needs: { ramMB: 8000, gpu: true, vramMB: 16000 } };
+  assert.equal(meetsSpecs(gpuModel, apple), true);
+});
+
+test("selectModel picks the large tier on a strong machine", () => {
+  const r = selectModel("tts", strongGpu);
+  assert.equal(r.tier, "large");
+  assert.ok(r.model.id);
+});
+
+test("selectModel falls back to medium on a CPU-only machine", () => {
+  const r = selectModel("tts", cpuOnly);
+  assert.equal(r.tier, "medium");
+  assert.equal(r.model.id, "kokoro", "Kokoro is the CPU/medium default (native word timestamps)");
+});
+
+test("selectModel recommends the CLI path when no tier fits", () => {
+  const r = selectModel("tts", tiny);
+  assert.equal(r.recommend, "cli");
+  assert.ok(r.reason && /spec/i.test(r.reason));
+  assert.equal(r.model, undefined);
+});
+
+test("preferTier:'medium' avoids the large model even on a strong machine", () => {
+  const r = selectModel("tts", strongGpu, { preferTier: "medium" });
+  assert.equal(r.tier, "medium");
+});
+
+test("selectModel gates on AVAILABLE RAM, not total, when both are present", () => {
+  // 64GB total but only 6GB free right now -> the large tier must not be chosen.
+  const busy = {
+    ramMB: 64000,
+    availableRamMB: 6000,
+    appleSilicon: true,
+    gpu: { present: true, kind: "apple", vramMB: 64000 },
+  };
+  const r = selectModel("tts", busy);
+  assert.equal(r.tier, "medium", "available RAM (6GB) rules out the 16GB large tier");
+});
+
+test("imagegen is a RAM-graduated ladder; agent picks the best that fits", () => {
+  const ladder = describeModelLadder("imagegen", {
+    ramMB: 24000,
+    availableRamMB: 12000,
+    appleSilicon: true,
+    gpu: { present: true, kind: "apple", vramMB: 24000 },
+  });
+  // best-first order, each flagged with fit
+  assert.ok(ladder.length >= 3, "imagegen offers multiple RAM tiers");
+  assert.ok(
+    ladder[0].needsRamMB >= ladder[ladder.length - 1].needsRamMB,
+    "ladder is ordered best (biggest) first",
+  );
+  // on 24GB / 12GB-free the schnell --low-ram tier fits, the 32GB+ tiers do not
+  const fitting = ladder.filter((m) => m.fits);
+  assert.ok(fitting.length >= 1, "at least the low-ram tier fits a 24GB Mac");
+  assert.ok(
+    fitting.every((m) => m.needsRamMB <= 12000),
+    "only sub-budget models flagged as fitting",
+  );
+  const pick = selectModel("imagegen", {
+    ramMB: 24000,
+    availableRamMB: 12000,
+    gpu: { present: true, vramMB: 24000 },
+  });
+  assert.equal(
+    pick.model.id,
+    "flux-schnell-mflux-q4",
+    "best fit on 24GB is the low-ram schnell tier",
+  );
+});
+
+test("imagegen on a 64GB Mac steps up to the higher-quality tier", () => {
+  const pick = selectModel("imagegen", {
+    ramMB: 96000,
+    availableRamMB: 80000,
+    gpu: { present: true, vramMB: 96000 },
+  });
+  assert.equal(pick.tier, "xlarge", "80GB free unlocks the top-quality model");
+});
+
+test("ASR prefers Parakeet by rank even though it is smaller than whisper", () => {
+  // quality != size for ASR: Parakeet 0.6B beats whisper-1.5B, so `rank` wins
+  // over footprint. On a capable machine both fit; Parakeet must be chosen.
+  const capable = {
+    ramMB: 24000,
+    availableRamMB: 12000,
+    appleSilicon: true,
+    gpu: { present: true, kind: "apple", vramMB: 24000 },
+  };
+  const pick = selectModel("asr", capable);
+  assert.equal(pick.model.id, "parakeet-mlx", "Parakeet is the rank-0 preferred ASR");
+  // whisperx (rank 1, CPU-only) is the fallback when no GPU
+  const cpu = { ramMB: 16000, availableRamMB: 12000, gpu: { present: false, vramMB: 0 } };
+  assert.equal(selectModel("asr", cpu).model.id, "whisperx", "CPU-only falls back to whisperx");
+});
+
+test("ASR offers word-timestamp-capable models (better than plain whisper)", () => {
+  const asr = listModels("asr");
+  assert.ok(
+    asr.every((m) => m.wordTimestamps),
+    "every ASR model must support word timestamps",
+  );
+});
+
+// A machine that clears BOTH videogen tiers (the 32GB entry and the 16GB one).
+// The existing fixtures deliberately sit under the large tier's floor, which is
+// exactly how a dead 32GB entry stayed invisible: nothing could select it.
+const bothVideogenTiers = { availableRamMB: 40000, gpu: { present: true } };
+
+test("selectModelLadder returns every fitting model, best-first", () => {
+  const ladder = selectModelLadder("videogen", bothVideogenTiers);
+  assert.deepEqual(
+    ladder.map((m) => m.tier),
+    ["large", "medium"],
+    "both tiers fit 40GB, biggest first",
+  );
+  assert.equal(
+    selectModel("videogen", bothVideogenTiers).model.id,
+    ladder[0].id,
+    "selectModel's pick is the ladder's head",
+  );
+});
+
+test("selectModelLadder drops what the machine cannot run", () => {
+  const oneTier = selectModelLadder("videogen", { availableRamMB: 20000, gpu: { present: true } });
+  assert.deepEqual(
+    oneTier.map((m) => m.tier),
+    ["medium"],
+    "20GB cannot reach the 32GB tier",
+  );
+  assert.deepEqual(
+    selectModelLadder("videogen", { availableRamMB: 100, gpu: { present: true } }),
+    [],
+    "nothing fits -> empty ladder, and selectModel recommends the CLI",
+  );
+  assert.equal(
+    selectModel("videogen", { availableRamMB: 100, gpu: { present: true } }).recommend,
+    "cli",
+  );
+});
+
+test("selectModelLadder honours preferTier", () => {
+  const pinned = selectModelLadder("videogen", bothVideogenTiers, { preferTier: "medium" });
+  assert.deepEqual(
+    pinned.map((m) => m.tier),
+    ["medium"],
+    "preferTier pins the ladder to one tier",
+  );
+});
+
+test("an invoke that names an owner/repo model agrees with the entry id", () => {
+  // Guards a half-done repoint: moving an entry to different weights means
+  // changing BOTH the id and the --model argument. Change one and the table
+  // selects one model while the runner downloads another.
+  let checked = 0;
+  for (const cap of CAPABILITIES) {
+    for (const m of listModels(cap)) {
+      if (m.repo) continue; // entries with an explicit repo resolve through it
+      const named = /--model\s+(\S+)/.exec(m.invoke);
+      if (!named) continue;
+      const [, name] = named[1].split("/");
+      if (!name) continue; // a bare model name, not an owner/repo id
+      assert.equal(name, m.id, `${cap}/${m.id}: invoke runs ${named[1]}`);
+      checked += 1;
+    }
+  }
+  assert.ok(checked > 0, "no entry pins an owner/repo model - guard would be vacuous");
+});

package/vendor/hyperframes/dist/skills/media-use/scripts/lib/local-run.mjs

@@ -0,0 +1,78 @@
+import { execFileSync } from "node:child_process";
+import { selectModel, selectModelLadder } from "./local-models.mjs";
+import { probeSpecs } from "./specs.mjs";
+
+// Run a USER-INSTALLED local model for a capability (tts/asr/upscale).
+// Walks the tiers the machine supports best-first (selectModelLadder), checking
+// the tool is on PATH, filling the model's invoke template, and running it. A
+// tier whose tool is missing or whose run fails demotes to the next fitting
+// tier, so one unusable entry does not fail the capability. Returns:
+//   { model, tier, out }                              on success
+//   { recommend:"install", model, sizeMB, command, reason }  tool isn't installed
+//   { recommend:"cli", reason }                        when no tier fits the machine
+// `exec` / `which` are injectable for tests.
+//
+// ponytail: "installed" = the invoke's first token is on PATH (e.g. `whisperx`,
+// `realesrgan-ncnn-vulkan`). For `python -m kokoro` this only proves python
+// exists; good enough to gate — the recommend.command names the real package.
+// Upgrade to a per-tool probe if a "python present but package missing" run ever
+// produces a confusing error instead of a clean recommend.
+
+function defaultWhich(bin) {
+  execFileSync("command", ["-v", bin], { stdio: "ignore", shell: true });
+}
+
+function defaultExec(cmd) {
+  execFileSync(cmd, { stdio: ["ignore", "pipe", "pipe"], shell: true, timeout: 600000 });
+}
+
+const fill = (tpl, vars) =>
+  tpl.replace(/\{(\w+)\}/g, (_, k) => (vars[k] != null ? String(vars[k]) : ""));
+
+export function runLocalModel(capability, opts = {}) {
+  const {
+    specs = probeSpecs(),
+    exec = defaultExec,
+    which = defaultWhich,
+    vars = {},
+    preferTier,
+  } = opts;
+  const ladder = selectModelLadder(capability, specs, { preferTier });
+  // no tier fits at all -> recommend the CLI path (selectModel words the reason)
+  if (!ladder.length) return selectModel(capability, specs, { preferTier });
+
+  // Best tier first, demoting past any tier that cannot run here: a missing
+  // tool or a failed run at the top tier must not hide a lower tier that works
+  // (fish-speech absent should still get you Kokoro). The last tier's failure is
+  // what gets reported, since by then nothing local ran.
+  let lastFailure = null;
+  for (const model of ladder) {
+    const bin = model.invoke.split(/\s+/)[0];
+    try {
+      which(bin);
+    } catch {
+      lastFailure = {
+        recommend: "install",
+        model: model.id,
+        sizeMB: model.sizeMB,
+        command: model.install,
+        reason: `${model.id} not installed (~${(model.sizeMB / 1000).toFixed(1)}GB to download once it is)`,
+      };
+      continue;
+    }
+    try {
+      exec(fill(model.invoke, vars));
+    } catch (e) {
+      lastFailure = {
+        recommend: "install",
+        model: model.id,
+        sizeMB: model.sizeMB,
+        command: model.install,
+        reason: e.message || String(e),
+      };
+      continue;
+    }
+    return { model: model.id, tier: model.tier, out: vars.out };
+  }
+  return lastFailure;
+}