@openparachute/vault 0.7.4 → 0.7.5-rc.5

package/src/transcription/install-whisper-exec.ts

@@ -0,0 +1,237 @@
+/**
+ * Executing a {@link WhisperInstallPlan}.
+ *
+ * The planner decides; this does. Kept separate so every decision stays
+ * testable without a network, and so the one genuinely irreversible-feeling
+ * step — spawning a package manager — sits in a small, obvious place.
+ *
+ * ## The verification step is the point
+ *
+ * The provider this replaces was activated by an install verb that never
+ * checked whether what it configured could run. That is precisely how
+ * `TRANSCRIPTION_PROVIDER=transcribe-cpp` came to point at a CLI that has
+ * never shipped, and why local transcription silently did nothing for anyone
+ * who "installed" it.
+ *
+ * So {@link verifyTranscription} generates a real WAV, runs the real CLI
+ * against the real model, and requires a real exit code. `TRANSCRIPTION_
+ * PROVIDER` flips only after that passes. An install that cannot transcribe is
+ * a failed install, and it says so at install time rather than silently at the
+ * operator's first voice memo.
+ */
+
+import { existsSync, mkdirSync, renameSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { downloadTo } from "./download.ts";
+import type { WhisperInstallPlan } from "./install-whisper-cpp.ts";
+import { binaryNameFor } from "./resolve-binary.ts";
+import { defaultSpawnRunner, type SpawnRunner } from "./providers/transcribe-cpp.ts";
+
+export interface ExecDeps {
+  spawn?: SpawnRunner;
+  download?: (url: string, dest: string) => Promise<void>;
+  existsImpl?: (p: string) => boolean;
+  log?: (line: string) => void;
+}
+
+export interface StepResult {
+  ok: boolean;
+  /** What happened, for the operator. */
+  message: string;
+}
+
+/**
+ * Ensure the CLI binaries exist.
+ *
+ * `already-present` is a no-op by design — re-running install shouldn't drag a
+ * package manager through a reinstall, and an operator who installed
+ * whisper.cpp themselves has already solved this.
+ */
+export async function ensureBinaries(
+  plan: WhisperInstallPlan,
+  deps: ExecDeps = {},
+): Promise<StepResult> {
+  const spawn = deps.spawn ?? defaultSpawnRunner;
+  const exists = deps.existsImpl ?? existsSync;
+  const log = deps.log ?? (() => {});
+
+  switch (plan.binary.kind) {
+    case "already-present":
+      return { ok: true, message: `${binaryNameFor(plan.model.engine)} already installed at ${plan.binary.path}` };
+
+    case "unsupported":
+      return { ok: false, message: plan.binary.reason };
+
+    case "homebrew": {
+      // Probe brew first so a box without it gets an honest refusal rather
+      // than an opaque exit 127 from the install attempt.
+      const probe = await spawn(["brew", "--version"], { timeoutMs: 30_000 });
+      if (probe.exitCode !== 0) {
+        return {
+          ok: false,
+          message:
+            "Homebrew isn't installed, and it's the only way to get whisper.cpp's CLIs on macOS " +
+            "(upstream ships no macOS CLI tarball — the macOS artifact is an xcframework for " +
+            "embedding). Install Homebrew from https://brew.sh, then re-run this. Or build " +
+            "whisper.cpp yourself and set WHISPER_CPP_BIN_DIR.",
+        };
+      }
+      log(`Running: brew install ${plan.binary.formula} …`);
+      const res = await spawn(["brew", "install", plan.binary.formula], { timeoutMs: 900_000 });
+      if (res.exitCode !== 0) {
+        return { ok: false, message: `brew install ${plan.binary.formula} failed: ${tail(res.stderr)}` };
+      }
+      return { ok: true, message: `Installed ${plan.binary.formula} (whisper-cli + parakeet-cli)` };
+    }
+
+    case "tarball": {
+      const download = deps.download ?? downloadTo;
+      mkdirSync(plan.binDir, { recursive: true });
+      const marker = join(plan.binDir, binaryNameFor(plan.model.engine));
+      if (exists(marker)) {
+        return { ok: true, message: `Binaries already present in ${plan.binDir}` };
+      }
+      const tmp = join(plan.binDir, `.${plan.binary.assetName}.part`);
+      log(`Downloading ${plan.binary.assetName} …`);
+      await download(plan.binary.url, tmp);
+      // Extract with --strip-components=1: the tarball nests everything under
+      // `whisper-bin-ubuntu-<arch>/`, and we want the binaries and their
+      // shared objects side by side in binDir so the loader finds them.
+      const res = await spawn(["tar", "xzf", tmp, "-C", plan.binDir, "--strip-components=1"], {
+        timeoutMs: 300_000,
+      });
+      try {
+        const { unlinkSync } = await import("fs");
+        unlinkSync(tmp);
+      } catch {
+        /* best effort */
+      }
+      if (res.exitCode !== 0) {
+        return { ok: false, message: `extracting ${plan.binary.assetName} failed: ${tail(res.stderr)}` };
+      }
+      if (!exists(marker)) {
+        return {
+          ok: false,
+          message: `${plan.binary.assetName} extracted but ${binaryNameFor(plan.model.engine)} isn't in ${plan.binDir}`,
+        };
+      }
+      await spawn(["chmod", "+x", marker], { timeoutMs: 30_000 });
+      return { ok: true, message: `Installed whisper.cpp binaries to ${plan.binDir}` };
+    }
+  }
+}
+
+/**
+ * Ensure the model file is on disk.
+ *
+ * Downloads to a `.part` and renames on success, so an interrupted install
+ * never leaves a truncated file that looks complete to the readiness probe —
+ * which would present as a mystery CLI failure at the first transcription
+ * rather than an obvious missing download.
+ */
+export async function ensureModel(
+  plan: WhisperInstallPlan,
+  deps: ExecDeps = {},
+): Promise<StepResult> {
+  const exists = deps.existsImpl ?? existsSync;
+  const download = deps.download ?? downloadTo;
+  const log = deps.log ?? (() => {});
+
+  if (exists(plan.modelPath)) {
+    return { ok: true, message: `Model already downloaded (${plan.model.label})` };
+  }
+  mkdirSync(dirOf(plan.modelPath), { recursive: true });
+  const part = `${plan.modelPath}.part`;
+  log(`Downloading ${plan.model.label} (${plan.model.sizeMb} MB) …`);
+  await download(plan.model.url, part);
+  renameSync(part, plan.modelPath);
+  return { ok: true, message: `Downloaded ${plan.model.label} to ${plan.modelPath}` };
+}
+
+/**
+ * Prove the install can actually transcribe.
+ *
+ * Generates a one-second silent 16 kHz mono WAV in-process (no ffmpeg needed —
+ * the CLIs take WAV directly, and this sidesteps making verification depend on
+ * a second tool) and runs the real CLI against the real model. We assert on the
+ * EXIT CODE, not on transcript content: silence legitimately produces no text,
+ * and a model that loads and runs cleanly is what we're checking.
+ */
+export async function verifyTranscription(
+  plan: WhisperInstallPlan,
+  binPath: string,
+  deps: ExecDeps = {},
+): Promise<StepResult> {
+  const spawn = deps.spawn ?? defaultSpawnRunner;
+  const log = deps.log ?? (() => {});
+  // Scratch, so it belongs in tmp — NOT beside the models, where a leftover
+  // from an interrupted run would sit next to real downloads forever.
+  const wav = join(tmpdir(), `parachute-verify-${process.pid}-16k-mono.wav`);
+  try {
+    await Bun.write(wav, silentWav16kMono(1));
+    log("Verifying the install can transcribe …");
+    const args =
+      plan.model.engine === "whisper"
+        ? [binPath, "-m", plan.modelPath, "-f", wav, "-np", "-nt"]
+        : [binPath, "-m", plan.modelPath, "-f", wav, "-np"];
+    const res = await spawn(args, { timeoutMs: 300_000 });
+    if (res.exitCode !== 0) {
+      return {
+        ok: false,
+        message:
+          `${binaryNameFor(plan.model.engine)} could not run the model (exit ${res.exitCode}). ` +
+          `This usually means a truncated download or a model/binary mismatch: ${tail(res.stderr)}`,
+      };
+    }
+    return { ok: true, message: "Verified — the model loads and transcribes." };
+  } finally {
+    try {
+      const { unlinkSync } = await import("fs");
+      unlinkSync(wav);
+    } catch {
+      /* best effort */
+    }
+  }
+}
+
+/**
+ * A minimal valid RIFF/WAVE file: `seconds` of 16-bit PCM silence at 16 kHz
+ * mono — exactly the shape both CLIs want.
+ *
+ * Written by hand rather than shelling ffmpeg so verification doesn't depend
+ * on the very tool whose absence we're trying to report clearly elsewhere.
+ */
+export function silentWav16kMono(seconds: number): Uint8Array {
+  const sampleRate = 16000;
+  const samples = Math.max(1, Math.floor(sampleRate * seconds));
+  const dataBytes = samples * 2; // 16-bit mono
+  const buf = new ArrayBuffer(44 + dataBytes);
+  const view = new DataView(buf);
+  const ascii = (off: number, s: string) => {
+    for (let i = 0; i < s.length; i++) view.setUint8(off + i, s.charCodeAt(i));
+  };
+  ascii(0, "RIFF");
+  view.setUint32(4, 36 + dataBytes, true);
+  ascii(8, "WAVE");
+  ascii(12, "fmt ");
+  view.setUint32(16, 16, true); // PCM chunk size
+  view.setUint16(20, 1, true); // PCM
+  view.setUint16(22, 1, true); // mono
+  view.setUint32(24, sampleRate, true);
+  view.setUint32(28, sampleRate * 2, true); // byte rate
+  view.setUint16(32, 2, true); // block align
+  view.setUint16(34, 16, true); // bits per sample
+  ascii(36, "data");
+  view.setUint32(40, dataBytes, true);
+  // Samples stay zero — silence.
+  return new Uint8Array(buf);
+}
+
+function dirOf(p: string): string {
+  return p.slice(0, p.lastIndexOf("/"));
+}
+
+function tail(s: string, lines = 3): string {
+  return s.trim().split("\n").slice(-lines).join(" | ").slice(0, 400);
+}

package/src/transcription/models.test.ts

@@ -0,0 +1,87 @@
+/**
+ * The model catalog.
+ *
+ * These tests care about two things a catalog gets wrong quietly: URLs that
+ * don't match the filename we save to (so a re-run re-downloads forever), and
+ * a default-picker that hands a 1.5 GB model to a 1 GB box.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  DEFAULT_MODEL_ID,
+  findModel,
+  pickDefaultModel,
+  TRANSCRIPTION_MODELS,
+} from "./models.ts";
+
+describe("catalog integrity", () => {
+  test("ids are unique", () => {
+    const ids = TRANSCRIPTION_MODELS.map((m) => m.id);
+    expect(ids.length).toBe(new Set(ids).size);
+  });
+
+  test("every URL's basename matches the filename we write", () => {
+    // Drift here means the downloader saves to a name the resolver never
+    // looks for, so every boot re-downloads and nothing ever becomes ready.
+    for (const m of TRANSCRIPTION_MODELS) {
+      expect(m.url.split("/").pop()).toBe(m.filename);
+    }
+  });
+
+  test("Parakeet models come from ggml-org, Whisper from ggerganov", () => {
+    // Load-bearing: handy-computer's GGUFs are NOT loadable by whisper.cpp's
+    // parakeet-cli (verified — "failed to load Parakeet model"). Pointing a
+    // Parakeet entry at handy-computer would produce a model that downloads
+    // fine and then fails at every transcription.
+    for (const m of TRANSCRIPTION_MODELS) {
+      if (m.engine === "parakeet") expect(m.url).toContain("ggml-org/parakeet-GGUF");
+      else expect(m.url).toContain("ggerganov/whisper.cpp");
+    }
+  });
+
+  test("catalog is ordered smallest-first", () => {
+    const sizes = TRANSCRIPTION_MODELS.map((m) => m.sizeMb);
+    expect([...sizes].sort((a, b) => a - b)).toEqual(sizes);
+  });
+
+  test("the default exists and is a Parakeet model", () => {
+    const d = findModel(DEFAULT_MODEL_ID);
+    expect(d).toBeDefined();
+    expect(d!.engine).toBe("parakeet");
+  });
+
+  test("covers the small and mid size classes an operator asks for", () => {
+    const sizes = TRANSCRIPTION_MODELS.map((m) => m.sizeMb);
+    expect(sizes.some((s) => s < 150)).toBe(true); // ~100 MB class
+    expect(sizes.some((s) => s >= 300 && s <= 700)).toBe(true); // ~400–700 MB class
+  });
+});
+
+describe("pickDefaultModel", () => {
+  test("a comfortable box gets the recommended Parakeet", () => {
+    expect(pickDefaultModel(16384).id).toBe(DEFAULT_MODEL_ID);
+  });
+
+  test("a small box steps DOWN rather than swapping itself to death", () => {
+    const picked = pickDefaultModel(1024);
+    expect(picked.minRamMb).toBeLessThanOrEqual(1024);
+    expect(picked.sizeMb).toBeLessThan(200);
+  });
+
+  test("never returns undefined, even on an absurdly small box", () => {
+    const picked = pickDefaultModel(64);
+    expect(picked).toBeDefined();
+    expect(picked.id).toBe(TRANSCRIPTION_MODELS[0]!.id);
+  });
+
+  test("a mid box gets something that fits its RAM floor", () => {
+    const picked = pickDefaultModel(2048);
+    expect(picked.minRamMb).toBeLessThanOrEqual(2048);
+  });
+});
+
+describe("findModel", () => {
+  test("unknown id → undefined, not a throw", () => {
+    expect(findModel("nope")).toBeUndefined();
+  });
+});

package/src/transcription/models.ts

@@ -0,0 +1,191 @@
+/**
+ * The local-transcription model catalog (whisper.cpp era).
+ *
+ * ## Why this replaced the transcribe.cpp plan
+ *
+ * The 2026-07-03 ratification adopted transcribe.cpp as the local provider.
+ * That decision assumed a `transcribe-cli` binary would ship. It never did:
+ * v0.1.3 (2026-07-12, latest as of this writing) still publishes only
+ * `libtranscribe.{dylib,so}` + `libggml*` + `contract.json` in its release
+ * tarballs — the CLI is build-from-source — and its N-API binding crashes on
+ * Bun, so the in-process route is closed too. Four weeks and three releases
+ * after the ratification, `parachute-vault transcription install` still could
+ * not produce a runnable setup.
+ *
+ * whisper.cpp ships what transcribe.cpp doesn't: **prebuilt CLIs on both
+ * platforms**. `brew install whisper-cpp` (bottled for arm64 macOS) installs
+ * BOTH `whisper-cli` and `parakeet-cli`, and the Linux release tarballs carry
+ * the same two binaries. Models are prebuilt too — `ggml-org/parakeet-GGUF`
+ * and `ggerganov/whisper.cpp` — so nothing has to be converted, and no Python
+ * is involved anywhere.
+ *
+ * Note that handy-computer's own GGUFs (68 repos, 16 model families) are NOT
+ * format-compatible with whisper.cpp's `parakeet-cli` — verified: loading
+ * `parakeet-tdt-0.6b-v3-Q4_K_M.gguf` fails with "failed to load Parakeet
+ * model". They are two ecosystems, and this catalog lives in whisper.cpp's.
+ * If transcribe.cpp ships a CLI later, its 16-family catalog becomes a
+ * genuinely attractive swap — the provider seam is where that would land.
+ *
+ * ## Why Parakeet is the default
+ *
+ * On the Open ASR Leaderboard, Parakeet TDT 0.6b v3 beats Whisper large-v3 on
+ * average WER (6.32% vs 7.44%) at roughly a third of the parameters, and runs
+ * substantially faster. The property that matters most for voice memos:
+ * **Parakeet does not hallucinate during silence**, which is Whisper's
+ * best-known failure mode and precisely what a recording with pauses triggers.
+ *
+ * The trade-off is language coverage — Parakeet v3 handles 25 European
+ * languages, Whisper 99 — which is why the Whisper models stay in the catalog
+ * rather than being dropped. A vault whose audio isn't in Parakeet's range
+ * picks a Whisper model and everything else works the same.
+ */
+
+/**
+ * Which whisper.cpp CLI runs a given model. The two binaries take slightly
+ * different flags and read different model formats, so this is not cosmetic —
+ * it selects the argv builder and the readiness probe.
+ */
+export type TranscriptionEngine = "parakeet" | "whisper";
+
+/** A model an operator can pick, with everything needed to fetch and run it. */
+export interface TranscriptionModel {
+  /** Stable id — what `TRANSCRIPTION_MODEL` is set to. */
+  id: string;
+  /** Short label for the admin UI. */
+  label: string;
+  /** Which CLI runs it. */
+  engine: TranscriptionEngine;
+  /** Download URL for the ggml `.bin`. */
+  url: string;
+  /** On-disk filename under `<root>/transcription/models/`. */
+  filename: string;
+  /** Approximate download size, MB. Real measured values, not estimates. */
+  sizeMb: number;
+  /**
+   * Rough floor of usable system RAM, MB. Used to pick a sane default on a
+   * given box and to warn when an operator picks something their machine will
+   * struggle with — NOT a hard refusal; an operator may know better.
+   */
+  minRamMb: number;
+  /** One line for the picker — what this trades away. */
+  note: string;
+}
+
+/**
+ * The catalog, smallest first.
+ *
+ * Sizes are measured from the HuggingFace API, not estimated. The Parakeet
+ * entries come from `ggml-org/parakeet-GGUF` (whisper.cpp's own conversions,
+ * which is what makes them loadable by `parakeet-cli`); the Whisper entries
+ * from `ggerganov/whisper.cpp`, the canonical source `download-ggml-model.sh`
+ * uses.
+ */
+export const TRANSCRIPTION_MODELS: readonly TranscriptionModel[] = [
+  {
+    id: "whisper-tiny.en",
+    label: "Whisper Tiny (English)",
+    engine: "whisper",
+    url: "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.en.bin",
+    filename: "ggml-tiny.en.bin",
+    sizeMb: 74,
+    minRamMb: 1024,
+    note: "Smallest option. Noticeably less accurate — for very constrained boxes.",
+  },
+  {
+    id: "whisper-base.en",
+    label: "Whisper Base (English)",
+    engine: "whisper",
+    url: "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin",
+    filename: "ggml-base.en.bin",
+    sizeMb: 141,
+    minRamMb: 2048,
+    note: "Small and quick. English only.",
+  },
+  {
+    id: "parakeet-tdt-0.6b-v3-q4",
+    label: "Parakeet TDT 0.6b v3 (q4)",
+    engine: "parakeet",
+    url: "https://huggingface.co/ggml-org/parakeet-GGUF/resolve/main/ggml-parakeet-tdt-0.6b-v3-q4_0.bin",
+    filename: "ggml-parakeet-tdt-0.6b-v3-q4_0.bin",
+    sizeMb: 339,
+    // 1.5 GB rather than 2: the q4 weights are 339 MB and peak usage lands
+    // well under 1 GB, so the common 2 GB VPS should get Parakeet rather than
+    // being stepped down to Whisper Tiny — a large accuracy loss to buy
+    // headroom it didn't need.
+    minRamMb: 1536,
+    note: "Parakeet at the smallest quantization. 25 European languages.",
+  },
+  {
+    id: "parakeet-tdt-0.6b-v3",
+    label: "Parakeet TDT 0.6b v3 (recommended)",
+    engine: "parakeet",
+    url: "https://huggingface.co/ggml-org/parakeet-GGUF/resolve/main/ggml-parakeet-tdt-0.6b-v3-q4_k.bin",
+    filename: "ggml-parakeet-tdt-0.6b-v3-q4_k.bin",
+    sizeMb: 396,
+    minRamMb: 3072,
+    note: "Best accuracy-per-byte, and doesn't hallucinate on silence. 25 European languages.",
+  },
+  {
+    id: "whisper-small.en",
+    label: "Whisper Small (English)",
+    engine: "whisper",
+    url: "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.en.bin",
+    filename: "ggml-small.en.bin",
+    sizeMb: 465,
+    minRamMb: 4096,
+    note: "More accurate Whisper. English only.",
+  },
+  {
+    id: "parakeet-tdt-0.6b-v3-q8",
+    label: "Parakeet TDT 0.6b v3 (q8)",
+    engine: "parakeet",
+    url: "https://huggingface.co/ggml-org/parakeet-GGUF/resolve/main/ggml-parakeet-tdt-0.6b-v3-q8_0.bin",
+    filename: "ggml-parakeet-tdt-0.6b-v3-q8_0.bin",
+    sizeMb: 638,
+    minRamMb: 6144,
+    note: "Parakeet at higher precision. Marginal gain over q4_k for most audio.",
+  },
+  {
+    id: "whisper-large-v3-turbo",
+    label: "Whisper Large v3 Turbo (multilingual)",
+    engine: "whisper",
+    url: "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin",
+    filename: "ggml-large-v3-turbo.bin",
+    sizeMb: 1549,
+    minRamMb: 8192,
+    note: "All 99 Whisper languages. Pick this when Parakeet's 25 aren't enough.",
+  },
+] as const;
+
+/**
+ * The default model when nothing is configured.
+ *
+ * Parakeet q4_k rather than the smallest option: at 396 MB it is a reasonable
+ * download on any machine that can host a vault, and choosing accuracy by
+ * default is the right call for transcripts an operator will read months
+ * later. `pickDefaultModel` steps down on low-RAM boxes.
+ */
+export const DEFAULT_MODEL_ID = "parakeet-tdt-0.6b-v3";
+
+/** Look a model up by id. `undefined` for an unknown id. */
+export function findModel(id: string): TranscriptionModel | undefined {
+  return TRANSCRIPTION_MODELS.find((m) => m.id === id);
+}
+
+/**
+ * Pick a sensible default for a machine with `totalRamMb`.
+ *
+ * Walks DOWN from the default to the largest model the box comfortably fits,
+ * so a small VPS gets something that runs rather than something that swaps.
+ * Never returns undefined — the smallest entry is the floor, and a box too
+ * small even for that has bigger problems than model choice.
+ */
+export function pickDefaultModel(totalRamMb: number): TranscriptionModel {
+  const preferred = findModel(DEFAULT_MODEL_ID);
+  if (preferred && totalRamMb >= preferred.minRamMb) return preferred;
+  // Largest model that fits, else the smallest we have.
+  const fits = TRANSCRIPTION_MODELS.filter((m) => totalRamMb >= m.minRamMb);
+  return fits.length > 0
+    ? fits.reduce((a, b) => (b.sizeMb > a.sizeMb ? b : a))
+    : TRANSCRIPTION_MODELS[0]!;
+}