@openparachute/vault 0.6.4 → 0.6.5-rc.10

package/src/transcription/providers/onnx-asr.ts

@@ -0,0 +1,239 @@
+/**
+ * `onnx-asr` — the local Linux-tier transcription provider
+ * (scribe-fold Phase 2b).
+ *
+ * Turns audio into text by subprocessing the `onnx-asr` CLI
+ * (github.com/istupakov/onnx-asr — ONNX Runtime ASR, CPU-friendly). Ported
+ * from scribe's proven `src/transcribe/onnx-asr.ts`; structurally a sibling
+ * of the `transcribe-cpp` provider (same SpawnRunner seam, same
+ * terminal-vs-retriable error contract). The ratified default model is
+ * `nemo-parakeet-tdt-0.6b-v3` (int8 ONNX, ~670MB, fetched into the HF cache
+ * on first use / warm-pulled at install).
+ *
+ * ## The audio path
+ *
+ * onnx-asr only accepts WAV, so we ALWAYS transcode through
+ * `ffmpeg -ar 16000 -ac 1 -c:a pcm_s16le` first. (Scribe passed a `.wav`
+ * input straight through; we transcode even those — the transcribe-cpp
+ * live-verify taught us an incoming WAV's sample rate can't be trusted, and
+ * re-encoding a WAV is harmless.) Then:
+ *
+ *   onnx-asr <model> --vad silero <wav>
+ *
+ * `--vad silero` chunks audio longer than Parakeet's ~20s context window —
+ * required for meeting-length audio (scribe's proven flag).
+ *
+ * ## Reading the output
+ *
+ * With `--vad`, stdout is timestamped lines like `[  0.0,  3.2]: text`; we
+ * strip the timestamps and join. Untimestamped output (short clips / future
+ * CLI changes) passes through unchanged. See `parseOnnxAsrOutput`.
+ *
+ * ## Error mapping (mirrors transcribe-cpp)
+ *
+ *   - binary not installed → non-retriable `missing_provider` (never spawns).
+ *   - ffmpeg not found (127) → non-retriable `ffmpeg_missing`.
+ *   - ffmpeg transcode non-zero exit → non-retriable `transcode_failed`.
+ *   - `onnx-asr` launch failure (127) → non-retriable `missing_provider`.
+ *   - `onnx-asr` non-zero exit → RETRIABLE `onnx_asr_error`.
+ *   - empty stdout → plain `Error` (retriable via the worker).
+ */
+
+import { randomUUID } from "crypto";
+import { existsSync } from "fs";
+import { writeFile, unlink } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import {
+  TranscriptionError,
+  type TranscriptionProvider,
+  type TranscribeInput,
+  type TranscribeResult,
+  type ProviderAvailability,
+} from "../../../core/src/transcription/provider.ts";
+import { defaultSpawnRunner, type SpawnRunner } from "./transcribe-cpp.ts";
+import { DEFAULT_ONNX_ASR_MODEL } from "../select.ts";
+
+/** First-use model download + CPU inference can be slow; generous default. */
+const DEFAULT_TIMEOUT_MS = 600_000;
+
+export interface OnnxAsrProviderOpts {
+  /** Path to the `onnx-asr` binary. Undefined ⇒ unavailable + terminal. */
+  binPath?: string;
+  /** onnx-asr model id (default: the ratified parakeet-tdt-0.6b-v3). */
+  model?: string;
+  /** ffmpeg binary (default "ffmpeg"; resolved on PATH). */
+  ffmpegPath?: string;
+  /** Per-transcription timeout (ms). Default 600s. */
+  timeoutMs?: number;
+  /** Subprocess runner (tests inject a mock). Default `defaultSpawnRunner`. */
+  spawn?: SpawnRunner;
+  /** Existence probe (tests inject). Default `fs.existsSync`. */
+  existsImpl?: (p: string) => boolean;
+  /** Scratch dir for the temp audio/wav files. Default `os.tmpdir()`. */
+  tmpDir?: string;
+}
+
+/**
+ * Build the `onnx-asr` argv. Scribe's proven invocation:
+ *   `onnx-asr <model> --vad silero <wav>`
+ * Exported so a test pins the shape.
+ */
+export function buildOnnxAsrArgs(binPath: string, model: string, wavPath: string): string[] {
+  return [binPath, model, "--vad", "silero", wavPath];
+}
+
+/**
+ * Build the ffmpeg transcode argv → 16kHz mono PCM-s16le WAV (onnx-asr's
+ * input contract; `pcm_s16le` is scribe's proven codec pick). Exported for
+ * tests.
+ */
+export function buildOnnxFfmpegArgs(
+  ffmpegPath: string,
+  inputPath: string,
+  wavPath: string,
+): string[] {
+  return [
+    ffmpegPath,
+    "-nostdin",
+    "-y",
+    "-i",
+    inputPath,
+    "-ar",
+    "16000",
+    "-ac",
+    "1",
+    "-c:a",
+    "pcm_s16le",
+    wavPath,
+  ];
+}
+
+/**
+ * Extract the transcript from onnx-asr's stdout. With `--vad silero` the
+ * output is timestamped lines (`[  0.0,  3.2]: text`); we strip the
+ * timestamp prefix per line and join with spaces. Lines without the prefix
+ * pass through unchanged, so untimestamped output (short clips) still parses.
+ * Returns "" for empty/blank stdout. Exported for tests.
+ */
+export function parseOnnxAsrOutput(stdout: string): string {
+  const lines = stdout
+    .trim()
+    .split("\n")
+    .filter((l) => l.trim());
+  return lines
+    .map((l) => l.replace(/^\[\s*[\d.]+,\s*[\d.]+\]:\s*/, "").trim())
+    .filter((l) => l.length > 0)
+    .join(" ")
+    .trim();
+}
+
+export class OnnxAsrProvider implements TranscriptionProvider {
+  readonly name = "onnx-asr";
+
+  private readonly binPath: string | undefined;
+  private readonly model: string;
+  private readonly ffmpegPath: string;
+  private readonly timeoutMs: number;
+  private readonly spawn: SpawnRunner;
+  private readonly existsImpl: (p: string) => boolean;
+  private readonly tmpDir: string;
+  /** Once available, stays available for this process — avoids re-statting. */
+  private cachedAvailable = false;
+
+  constructor(opts: OnnxAsrProviderOpts = {}) {
+    this.binPath = opts.binPath;
+    this.model = opts.model ?? DEFAULT_ONNX_ASR_MODEL;
+    this.ffmpegPath = opts.ffmpegPath ?? "ffmpeg";
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.spawn = opts.spawn ?? defaultSpawnRunner;
+    this.existsImpl = opts.existsImpl ?? existsSync;
+    this.tmpDir = opts.tmpDir ?? tmpdir();
+  }
+
+  /**
+   * Cheap readiness probe — a runnable `onnx-asr` binary on disk. NEVER
+   * spawns. The MODEL is not checked (HF cache, downloads on first use), so
+   * binary presence is the honest cheap signal. Memoizes the once-true result.
+   */
+  async available(): Promise<ProviderAvailability> {
+    if (this.cachedAvailable) return { ok: true };
+    if (!this.binPath || !this.existsImpl(this.binPath)) {
+      return {
+        ok: false,
+        reason:
+          "onnx-asr is not installed (run `parachute-vault transcription install`, or set ONNX_ASR_BIN)",
+      };
+    }
+    this.cachedAvailable = true;
+    return { ok: true };
+  }
+
+  async transcribe(input: TranscribeInput): Promise<TranscribeResult> {
+    if (!this.binPath || !this.existsImpl(this.binPath)) {
+      throw new TranscriptionError("onnx-asr not installed", {
+        code: "missing_provider",
+        retriable: false,
+      });
+    }
+
+    const id = randomUUID();
+    const inExt = extFor(input.filename, input.mimeType);
+    const inputPath = join(this.tmpDir, `parachute-ox-${id}.${inExt}`);
+    const wavPath = join(this.tmpDir, `parachute-ox-${id}.16k.wav`);
+    const cleanup: string[] = [inputPath, wavPath];
+
+    try {
+      await writeFile(inputPath, input.audio);
+
+      // ALWAYS transcode to 16kHz mono s16le WAV — even an incoming .wav,
+      // whose sample rate we can't trust (see the module header).
+      const ff = await this.spawn(buildOnnxFfmpegArgs(this.ffmpegPath, inputPath, wavPath), {
+        timeoutMs: this.timeoutMs,
+      });
+      if (ff.exitCode !== 0) {
+        const missing = ff.exitCode === 127;
+        throw new TranscriptionError(
+          missing
+            ? "ffmpeg not found — install it to transcode audio to 16kHz mono WAV for onnx-asr (apt install ffmpeg / brew install ffmpeg)"
+            : `ffmpeg transcode failed (exit ${ff.exitCode}): ${ff.stderr.trim().slice(0, 500)}`,
+          { code: missing ? "ffmpeg_missing" : "transcode_failed", retriable: false },
+        );
+      }
+
+      const res = await this.spawn(buildOnnxAsrArgs(this.binPath, this.model, wavPath), {
+        timeoutMs: this.timeoutMs,
+      });
+      if (res.exitCode !== 0) {
+        if (res.exitCode === 127) {
+          throw new TranscriptionError(`onnx-asr could not be launched: ${res.stderr.trim()}`, {
+            code: "missing_provider",
+            retriable: false,
+          });
+        }
+        throw new TranscriptionError(
+          `onnx-asr exited ${res.exitCode}: ${res.stderr.trim().slice(0, 500)}`,
+          { code: "onnx_asr_error", retriable: true },
+        );
+      }
+
+      const text = parseOnnxAsrOutput(res.stdout);
+      if (!text) {
+        // Empty/unparseable — plain Error is treated as retriable by the worker.
+        throw new Error("onnx-asr produced no transcript text");
+      }
+      return { text };
+    } finally {
+      await Promise.all(cleanup.map((p) => unlink(p).catch(() => {})));
+    }
+  }
+}
+
+/** Choose a temp-file extension from the filename or mime type. */
+function extFor(filename: string, mimeType: string): string {
+  const fromName = filename.split(".").pop();
+  if (fromName && fromName.length <= 5 && /^[a-z0-9]+$/i.test(fromName)) return fromName.toLowerCase();
+  const sub = mimeType.split("/")[1]?.split(";")[0]?.trim();
+  if (sub && /^[a-z0-9]+$/i.test(sub)) return sub.toLowerCase();
+  return "bin";
+}

package/src/transcription/providers/parakeet-mlx.test.ts

@@ -0,0 +1,290 @@
+import { describe, test, expect, afterEach } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync, existsSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import {
+  ParakeetMlxProvider,
+  buildParakeetMlxArgs,
+  looksLikeFfmpegMissing,
+} from "./parakeet-mlx.ts";
+import type { SpawnRunner, SubprocessResult } from "./transcribe-cpp.ts";
+import { TranscriptionError } from "../../../core/src/transcription/provider.ts";
+
+/**
+ * Conformance tests for the `parakeet-mlx` local provider (scribe-fold
+ * Phase 2b). The subprocess is mocked so no real binary runs; the temp
+ * input/output files are REAL (in a per-test tmp dir) so the output-discovery
+ * logic — including scribe's proven "the tool may name the .txt after its own
+ * stem" fallback and the ffmpeg-missing exit-0 mask — is exercised for real.
+ */
+
+const AUDIO = new Uint8Array([1, 2, 3, 4]);
+
+const tmpDirs: string[] = [];
+function freshTmp(): string {
+  const d = mkdtempSync(join(tmpdir(), "pk-test-"));
+  tmpDirs.push(d);
+  return d;
+}
+afterEach(() => {
+  for (const d of tmpDirs.splice(0)) rmSync(d, { recursive: true, force: true });
+});
+
+/** A spawn mock that records argv and lets the test act on the out dir. */
+function recordingSpawn(
+  handler: (cmd: string[]) => SubprocessResult,
+): { spawn: SpawnRunner; calls: string[][] } {
+  const calls: string[][] = [];
+  const spawn: SpawnRunner = async (cmd) => {
+    calls.push(cmd);
+    return handler(cmd);
+  };
+  return { spawn, calls };
+}
+
+/** Extract the --output-dir value from a recorded argv. */
+function outDirOf(cmd: string[]): string {
+  return cmd[cmd.indexOf("--output-dir") + 1]!;
+}
+
+const ok: SubprocessResult = { exitCode: 0, stdout: "", stderr: "" };
+
+function provider(
+  spawn: SpawnRunner,
+  tmpDir: string,
+  opts: Partial<{ existsImpl: (p: string) => boolean; model: string; binPath: string | undefined }> = {},
+) {
+  return new ParakeetMlxProvider({
+    binPath: "binPath" in opts ? opts.binPath : "/venv/bin/parakeet-mlx",
+    model: opts.model,
+    spawn,
+    tmpDir,
+    // Binary existence is stubbed; output-file discovery uses the REAL fs.
+    existsImpl: opts.existsImpl ?? ((p) => (p.includes("parakeet-mlx") ? true : existsSync(p))),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+
+describe("buildParakeetMlxArgs", () => {
+  test("matches scribe's proven invocation: <bin> <audio> --output-format txt --output-dir <dir>", () => {
+    expect(buildParakeetMlxArgs("/bin/parakeet-mlx", "/a.webm", "/out")).toEqual([
+      "/bin/parakeet-mlx",
+      "/a.webm",
+      "--output-format",
+      "txt",
+      "--output-dir",
+      "/out",
+    ]);
+  });
+
+  test("appends --model when a model id is set", () => {
+    const args = buildParakeetMlxArgs("/bin/pk", "/a.wav", "/out", "mlx-community/parakeet-tdt-0.6b-v3");
+    expect(args).toContain("--model");
+    expect(args[args.indexOf("--model") + 1]).toBe("mlx-community/parakeet-tdt-0.6b-v3");
+  });
+});
+
+describe("looksLikeFfmpegMissing (ported from scribe backend-error.ts)", () => {
+  test("classic python ENOENT traceback", () => {
+    expect(looksLikeFfmpegMissing("[Errno 2] No such file or directory: 'ffmpeg'")).toBe(true);
+  });
+  test("shell not-found phrasing", () => {
+    expect(looksLikeFfmpegMissing("ffmpeg: command not found")).toBe(true);
+  });
+  test("multi-line co-occurrence matches", () => {
+    expect(looksLikeFfmpegMissing("error decoding audio\nffmpeg is required\nnot installed on PATH")).toBe(true);
+  });
+  test("ffmpeg mentioned without a missing phrasing → false", () => {
+    expect(looksLikeFfmpegMissing("ffmpeg version 6.0 Copyright")).toBe(false);
+  });
+  test("empty output → false", () => {
+    expect(looksLikeFfmpegMissing("")).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// available() — cheap, no spawn
+// ---------------------------------------------------------------------------
+
+describe("ParakeetMlxProvider.available", () => {
+  test("name is stable 'parakeet-mlx'", () => {
+    expect(provider(recordingSpawn(() => ok).spawn, freshTmp()).name).toBe("parakeet-mlx");
+  });
+
+  test("ok:true when the binary exists — and NEVER spawns", async () => {
+    const { spawn, calls } = recordingSpawn(() => ok);
+    const p = provider(spawn, freshTmp());
+    expect(await p.available()).toEqual({ ok: true });
+    expect(calls.length).toBe(0);
+  });
+
+  test("ok:false with an actionable reason when the binary is missing", async () => {
+    const { spawn, calls } = recordingSpawn(() => ok);
+    const p = provider(spawn, freshTmp(), { existsImpl: () => false });
+    const avail = await p.available();
+    expect(avail.ok).toBe(false);
+    expect(avail.reason).toContain("transcription install");
+    expect(calls.length).toBe(0);
+  });
+
+  test("unconfigured (no binPath) → ok:false, no throw", async () => {
+    const p = provider(recordingSpawn(() => ok).spawn, freshTmp(), { binPath: undefined });
+    expect((await p.available()).ok).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// transcribe() — happy paths
+// ---------------------------------------------------------------------------
+
+describe("ParakeetMlxProvider.transcribe — happy path", () => {
+  test("hands the raw audio file over (no pre-transcode) and reads <stem>.txt", async () => {
+    const tmp = freshTmp();
+    const { spawn, calls } = recordingSpawn((cmd) => {
+      // Simulate the tool writing the transcript named after the input stem.
+      const outDir = outDirOf(cmd);
+      const stem = cmd[1]!.split("/").pop()!.replace(/\.webm$/, "");
+      writeFileSync(join(outDir, `${stem}.txt`), "hello from parakeet\n");
+      return ok;
+    });
+    const p = provider(spawn, tmp);
+    const res = await p.transcribe({ audio: AUDIO, filename: "memo.webm", mimeType: "audio/webm" });
+
+    expect(res.text).toBe("hello from parakeet");
+    // Exactly ONE spawn — parakeet-mlx decodes internally; no ffmpeg pre-pass.
+    expect(calls.length).toBe(1);
+    expect(calls[0]![0]).toBe("/venv/bin/parakeet-mlx");
+    expect(calls[0]![1]).toMatch(/\.webm$/); // the raw input, not a transcoded wav
+    expect(calls[0]).toContain("--output-format");
+    expect(calls[0]).toContain("txt");
+  });
+
+  test("falls back to any .txt when the tool uses its own output stem", async () => {
+    const tmp = freshTmp();
+    const { spawn } = recordingSpawn((cmd) => {
+      writeFileSync(join(outDirOf(cmd), "some-other-stem.txt"), "  fallback transcript  ");
+      return ok;
+    });
+    const p = provider(spawn, tmp);
+    const res = await p.transcribe({ audio: AUDIO, filename: "a.m4a", mimeType: "audio/mp4" });
+    expect(res.text).toBe("fallback transcript");
+  });
+
+  test("passes --model when configured", async () => {
+    const tmp = freshTmp();
+    const { spawn, calls } = recordingSpawn((cmd) => {
+      writeFileSync(join(outDirOf(cmd), "x.txt"), "t");
+      return ok;
+    });
+    const p = provider(spawn, tmp, { model: "mlx-community/parakeet-tdt-0.6b-v3" });
+    await p.transcribe({ audio: AUDIO, filename: "a.wav", mimeType: "audio/wav" });
+    expect(calls[0]).toContain("--model");
+    expect(calls[0]).toContain("mlx-community/parakeet-tdt-0.6b-v3");
+  });
+
+  test("cleans up the temp input + output dir afterwards", async () => {
+    const tmp = freshTmp();
+    let seenOutDir = "";
+    const { spawn, calls } = recordingSpawn((cmd) => {
+      seenOutDir = outDirOf(cmd);
+      writeFileSync(join(seenOutDir, "x.txt"), "t");
+      return ok;
+    });
+    await provider(spawn, tmp).transcribe({ audio: AUDIO, filename: "a.wav", mimeType: "audio/wav" });
+    expect(existsSync(calls[0]![1]!)).toBe(false);
+    expect(existsSync(seenOutDir)).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// transcribe() — error mapping
+// ---------------------------------------------------------------------------
+
+describe("ParakeetMlxProvider.transcribe — error mapping", () => {
+  async function catchErr(fn: () => Promise<unknown>): Promise<unknown> {
+    try {
+      await fn();
+    } catch (err) {
+      return err;
+    }
+    throw new Error("expected transcribe() to throw");
+  }
+
+  test("binary missing → non-retriable missing_provider, NEVER spawns", async () => {
+    const { spawn, calls } = recordingSpawn(() => ok);
+    const p = provider(spawn, freshTmp(), { existsImpl: () => false });
+    const err = (await catchErr(() =>
+      p.transcribe({ audio: AUDIO, filename: "a.webm", mimeType: "audio/webm" }),
+    )) as TranscriptionError;
+    expect(err).toBeInstanceOf(TranscriptionError);
+    expect(err.code).toBe("missing_provider");
+    expect(err.retriable).toBe(false);
+    expect(calls.length).toBe(0);
+  });
+
+  test("launch failure (127) → non-retriable missing_provider", async () => {
+    const { spawn } = recordingSpawn(() => ({ exitCode: 127, stdout: "", stderr: "gone" }));
+    const p = provider(spawn, freshTmp());
+    const err = (await catchErr(() =>
+      p.transcribe({ audio: AUDIO, filename: "a.webm", mimeType: "audio/webm" }),
+    )) as TranscriptionError;
+    expect(err.code).toBe("missing_provider");
+    expect(err.retriable).toBe(false);
+  });
+
+  test("non-zero exit → RETRIABLE parakeet_mlx_error", async () => {
+    const { spawn } = recordingSpawn(() => ({ exitCode: 1, stdout: "", stderr: "boom" }));
+    const p = provider(spawn, freshTmp());
+    const err = (await catchErr(() =>
+      p.transcribe({ audio: AUDIO, filename: "a.webm", mimeType: "audio/webm" }),
+    )) as TranscriptionError;
+    expect(err).toBeInstanceOf(TranscriptionError);
+    expect(err.code).toBe("parakeet_mlx_error");
+    expect(err.retriable).toBe(true);
+  });
+
+  test("exit 0 + no output + ffmpeg signature → non-retriable ffmpeg_missing (the scribe mask)", async () => {
+    // parakeet-mlx shells to ffmpeg internally; when ffmpeg is missing it
+    // prints the error then EXITS 0 with no output file. The signature in the
+    // combined output is the only signal.
+    const { spawn } = recordingSpawn(() => ({
+      exitCode: 0,
+      stdout: "",
+      stderr: "[Errno 2] No such file or directory: 'ffmpeg'",
+    }));
+    const p = provider(spawn, freshTmp());
+    const err = (await catchErr(() =>
+      p.transcribe({ audio: AUDIO, filename: "a.webm", mimeType: "audio/webm" }),
+    )) as TranscriptionError;
+    expect(err).toBeInstanceOf(TranscriptionError);
+    expect(err.code).toBe("ffmpeg_missing");
+    expect(err.retriable).toBe(false);
+  });
+
+  test("exit 0 + no output, no ffmpeg signature → plain Error (retriable via worker)", async () => {
+    const { spawn } = recordingSpawn(() => ({ exitCode: 0, stdout: "done?", stderr: "" }));
+    const p = provider(spawn, freshTmp());
+    const err = (await catchErr(() =>
+      p.transcribe({ audio: AUDIO, filename: "a.webm", mimeType: "audio/webm" }),
+    )) as Error;
+    expect(err).toBeInstanceOf(Error);
+    expect(err).not.toBeInstanceOf(TranscriptionError);
+    expect(err.message).toContain("no transcript output");
+  });
+
+  test("empty transcript file → plain Error (retriable via worker)", async () => {
+    const { spawn } = recordingSpawn((cmd) => {
+      writeFileSync(join(outDirOf(cmd), "x.txt"), "   \n ");
+      return ok;
+    });
+    const p = provider(spawn, freshTmp());
+    const err = (await catchErr(() =>
+      p.transcribe({ audio: AUDIO, filename: "a.wav", mimeType: "audio/wav" }),
+    )) as Error;
+    expect(err).not.toBeInstanceOf(TranscriptionError);
+    expect(err.message).toContain("no transcript text");
+  });
+});