@earendil-works/pi-voice 0.1.0

package/src/model-ratings-help.md

@@ -0,0 +1,41 @@
+## Accuracy
+
+You don't always need the most accurate model. Programming assistants can often understand you even when a few words are wrong.
+The grades we give roughly correspond to the following:
+
+- **A — Very few mistakes.** Your request usually comes through clearly
+- **B — Some mistakes.** The assistant can often work around them
+- **C — Frequent mistakes.** Some details may get lost
+- **D — Many mistakes.** Expect to check or repeat your request
+- **F — Often unclear.** The assistant may struggle to understand you
+
+**+** and **−** give some indication of accuracy within a grade. Small differences may not be noticeable in use.
+
+## Speed
+
+The speed bars represent how long it took to transcribe 30 seconds of audio using a Lenovo T14s laptop (with 4750U CPU/GPU) from 2020.
+Your machine may be faster or slower at transcribing depending on your system configuration.
+
+- **▰▰▰▰▰:** Less than 1.5 seconds
+- **▰▰▰▰▱:** 1.5 to 3 seconds
+- **▰▰▰▱▱:** 3 to 5 seconds
+- **▰▰▱▱▱:** 5 to 10 seconds
+- **▰▱▱▱▱:** 10 to 20 seconds
+- **▱▱▱▱▱:** 20 seconds or more
+
+## Other symbols
+
+- **✓** — Your selected model
+- **—** — The model doesn't support this language
+- **?** — The model supports this language, but we don't have a accuracy grade for it
+- **manual lang** — The model requires you to pick the language you want to transcribe
+
+<!-- catalog-only -->
+## Recommended Models
+
+These suggestions are for your chosen languages
+
+- **Best** — Our suggested balance of speed and accuracy.
+- **Fast** — A choice that prioritizes quick transcription while keeping accuracy usable.
+- **Accurate** — A choice that prioritizes fewer mistakes without an excessive wait.
+<!-- /catalog-only -->

package/src/model-ratings-help.ts

@@ -0,0 +1,146 @@
+import { readFileSync } from "node:fs";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  Markdown,
+  truncateToWidth,
+  visibleWidth,
+  type Component,
+  type TUI,
+} from "@earendil-works/pi-tui";
+import { gradeStyle } from "./model-cells.js";
+import type { VoiceKeys } from "./keybindings.js";
+import { PANEL_PADDING, panelBorder, paneRowBudget } from "./ui-components.js";
+
+type UiTheme = ExtensionContext["ui"]["theme"];
+
+/**
+ * An in-place help view owned by the picker. The picker stays mounted and routes
+ * rendering/input here while open; no overlay, focus transfer, or navigation.
+ * Copy lives in model-ratings-help.md and is read again on each opening.
+ */
+export class ModelRatingsHelp implements Component {
+  private markdown: Markdown | undefined;
+  private title = "Model ratings";
+  private offset = 0;
+  private pageSize = 1;
+  private lineCount = 0;
+
+  constructor(
+    private readonly tui: TUI,
+    private readonly theme: UiTheme,
+    private readonly keys: VoiceKeys,
+    private readonly catalog: boolean,
+  ) {}
+
+  get isOpen(): boolean { return this.markdown !== undefined; }
+
+  open(): void {
+    if (this.isOpen) return;
+    const source = readFileSync(new URL("./model-ratings-help.md", import.meta.url), "utf8")
+      .replace(/<!-- catalog-only -->([\s\S]*?)<!-- \/catalog-only -->/g,
+        (_block, content: string) => this.catalog ? content : "");
+    // A document title is optional; plain section headings work without one.
+    this.title = source.match(/^# (.+)$/m)?.[1] ?? "Model ratings";
+    const theme = this.theme;
+    this.markdown = new Markdown(source.replace(/^# .+\r?\n/m, "").trim(), PANEL_PADDING, 0, {
+      heading: (text) => theme.fg("accent", theme.bold(text)),
+      link: (text) => theme.fg("mdLink", text),
+      linkUrl: (text) => theme.fg("mdLinkUrl", text),
+      code: (text) => theme.fg("mdCode", text),
+      codeBlock: (text) => theme.fg("mdCodeBlock", text),
+      codeBlockBorder: (text) => theme.fg("mdCodeBlockBorder", text),
+      quote: (text) => theme.fg("mdQuote", text),
+      quoteBorder: (text) => theme.fg("mdQuoteBorder", text),
+      hr: (text) => theme.fg("mdHr", text),
+      listBullet: (text) => theme.fg("mdListBullet", text),
+      bold: (text) => {
+        // Match the grade letters in "A — Very few mistakes" so the help
+        // uses the same visual language as the model columns. Keep the
+        // explanation itself bold but uncoloured.
+        const grade = text.match(/^([ABCDF])(?=\s+—)/)?.[1];
+        if (!grade) return theme.bold(text);
+        return gradeStyle(theme, grade as "A" | "B" | "C" | "D" | "F", theme.bold(grade)) +
+          theme.bold(text.slice(grade.length));
+      },
+      italic: (text) => theme.italic(text),
+      strikethrough: (text) => theme.strikethrough(text),
+      underline: (text) => theme.underline(text),
+    });
+    this.offset = 0;
+    this.tui.requestRender();
+  }
+
+  close(): void {
+    if (!this.isOpen) return;
+    this.markdown = undefined;
+    this.tui.requestRender();
+  }
+
+  invalidate(): void { this.markdown?.invalidate(); }
+
+  render(width: number): string[] {
+    if (width < 1 || !this.markdown) return [];
+    const budget = Math.max(1, paneRowBudget(this.tui) ?? 24);
+    const row = (text: string) => truncateToWidth(`${" ".repeat(PANEL_PADDING)}${text}`, width, "");
+    const border = panelBorder(this.theme).render(width);
+    // Match the model pages' full-width horizontal rules and left alignment.
+    // On tiny terminals, drop decoration before sacrificing text or Back.
+    const framed = budget >= 6;
+    const spaced = budget >= 10;
+    const header = [
+      ...(framed ? border : []),
+      ...(spaced ? [""] : []),
+      ...(budget >= 3 ? [row(this.theme.fg("accent", this.theme.bold(this.title)))] : []),
+      ...(spaced ? [""] : []),
+    ];
+    const footerRows = 1 + (spaced ? 2 : 0) + (framed ? border.length : 0);
+    this.pageSize = Math.max(0, budget - header.length - footerRows);
+    const lines = this.markdown.render(width);
+    this.lineCount = lines.length;
+    this.offset = Math.max(0, Math.min(this.offset, lines.length - this.pageSize));
+    const page = lines.slice(this.offset, this.offset + this.pageSize);
+
+    const scrollable = lines.length > this.pageSize;
+    const scroll = scrollable ? `${this.keys.navHint("scroll")}  ` : "";
+    const more = [this.offset > 0 ? "↑ above" : "", this.offset + this.pageSize < lines.length ? "↓ more" : ""]
+      .filter(Boolean).join(" · ");
+    const backKeys = ["voice.ratingsHelp.close", "tui.select.cancel"] as const;
+    const back = this.keys.hint(backKeys, "back to models");
+    const hints = [
+      `${scroll}${more ? `${this.theme.fg("dim", more)}  ` : ""}${back}`,
+      `${scroll}${back}`,
+      back,
+      this.keys.hint(backKeys, "back"),
+      this.keys.hint("voice.ratingsHelp.close", "back"),
+    ];
+    const footer = hints.find((hint) => visibleWidth(hint) <= width - PANEL_PADDING * 2) ?? hints[hints.length - 1]!;
+    return [
+      ...header,
+      ...page,
+      ...(spaced ? [""] : []),
+      row(footer),
+      ...(spaced ? [""] : []),
+      ...(framed ? border : []),
+    ];
+  }
+
+  handleInput(data: string): void {
+    if (
+      this.keys.matches(data, "tui.select.cancel") ||
+      this.keys.matches(data, "voice.ratingsHelp.close")
+    ) {
+      this.close();
+      return;
+    }
+    if (this.keys.matches(data, "tui.select.up")) this.offset--;
+    else if (this.keys.matches(data, "tui.select.down")) this.offset++;
+    // Keep a little context across pages, particularly section headings.
+    else if (this.keys.matches(data, "tui.select.pageUp")) this.offset -= Math.max(1, this.pageSize - 2);
+    else if (this.keys.matches(data, "tui.select.pageDown")) this.offset += Math.max(1, this.pageSize - 2);
+    else if (this.keys.matches(data, "voice.scroll.top")) this.offset = 0;
+    else if (this.keys.matches(data, "voice.scroll.bottom")) this.offset = this.lineCount - this.pageSize;
+    else return; // In particular, Enter and typing never reach the model list.
+    this.offset = Math.max(0, Math.min(this.offset, this.lineCount - this.pageSize));
+    this.tui.requestRender();
+  }
+}

package/src/model-selection-controller.ts

@@ -0,0 +1,185 @@
+import type { CatalogModel } from "./catalog.js";
+import type { CatalogModelActivation } from "./model-activation.js";
+import { findCachedCatalogModel, type CachedCatalogModel } from "./models.js";
+
+export type DownloadState = {
+  readonly model: CatalogModel;
+  readonly downloaded: number;
+  readonly total: number;
+  readonly message: string;
+};
+
+type Activation = {
+  model: CatalogModel;
+  controller: AbortController;
+  cached: CachedCatalogModel | undefined;
+};
+
+/** UI-independent selection lifecycle shared by the recommended and full pickers. */
+export class ModelSelectionController<R> {
+  readonly cachedById = new Map<string, CachedCatalogModel>();
+  committedModelId: string | undefined;
+  selectedDuringSession: boolean;
+  download: DownloadState | undefined;
+  feedback: { type: "success" | "error" | "muted"; text: string } | undefined;
+  private target: Activation | undefined;
+  private pendingExit: { result: R } | undefined;
+  private closed = false;
+  private disposed = false;
+  private samples: { time: number; bytes: number }[] = [];
+  private readonly findCached: typeof findCachedCatalogModel;
+  private readonly now: () => number;
+
+  constructor(
+    private readonly activate: CatalogModelActivation,
+    private readonly options: {
+      models: readonly CatalogModel[];
+      currentModelId?: string;
+      activatedInFlow?: boolean;
+      advance: boolean;
+      completion: R;
+      onChange: () => void;
+      onExit: (result: R) => void;
+      findCached?: typeof findCachedCatalogModel;
+      now?: () => number;
+    },
+  ) {
+    this.findCached = options.findCached ?? findCachedCatalogModel;
+    this.now = options.now ?? Date.now;
+    this.committedModelId = options.currentModelId;
+    this.selectedDuringSession = options.activatedInFlow ?? false;
+    for (const model of options.models) {
+      const cached = this.findCached(model);
+      if (cached) this.cachedById.set(model.id, cached);
+    }
+  }
+
+  get acceptsInput(): boolean {
+    return !this.closed && !this.disposed && !this.pendingExit;
+  }
+
+  get displayedModelId(): string | undefined {
+    return this.target?.model.id ?? this.committedModelId;
+  }
+
+  get downloadSpeed(): number | undefined {
+    const samples = this.samples.filter((sample) => this.now() - sample.time <= 5000);
+    if (samples.length < 2) return undefined;
+    const first = samples[0]!;
+    const last = samples[samples.length - 1]!;
+    const elapsed = last.time - first.time;
+    return elapsed >= 500 ? (last.bytes - first.bytes) * 1000 / elapsed : undefined;
+  }
+
+  private changed(): void {
+    if (this.closed || this.disposed) return;
+    // A rendering failure must not prevent the download/save from running.
+    try { this.options.onChange(); } catch { /* Presentation is not part of the commit. */ }
+  }
+
+  private finish(result: R): void {
+    if (this.closed || this.disposed) return;
+    this.closed = true;
+    this.pendingExit = undefined;
+    try { this.options.onExit(result); } catch { /* Never reinterpret a committed save as a failure. */ }
+  }
+
+  /** Cached saves finish before navigation; download cancellation is explicit. */
+  requestExit(result: R): void {
+    if (!this.acceptsInput || this.download) return;
+    if (this.target) this.pendingExit = { result };
+    else this.finish(result);
+  }
+
+  select(model: CatalogModel): void {
+    if (!this.acceptsInput || this.download) return;
+    const cached = this.cachedById.get(model.id);
+    if (!this.target && cached && model.id === this.committedModelId &&
+        (this.selectedDuringSession || !this.options.advance)) {
+      this.selectedDuringSession = true;
+      if (this.options.advance) this.finish(this.options.completion);
+      else this.changed();
+      return;
+    }
+
+    this.target?.controller.abort();
+    const target: Activation = { model, cached, controller: new AbortController() };
+    this.target = target;
+    this.feedback = undefined;
+    this.samples = [];
+    this.download = cached ? undefined : {
+      model, downloaded: 0, total: 0, message: "Connecting to Hugging Face…",
+    };
+    this.changed();
+
+    // Catch synchronous implementations too. The real pipeline reports only
+    // after its ordered settings commit, not merely after the download.
+    let work: Promise<{ path: string }>;
+    try {
+      work = this.activate(model, {
+        cached,
+        signal: target.controller.signal,
+        onProgress: ({ downloaded, total }) => {
+          if (this.disposed || this.closed || this.target !== target || target.controller.signal.aborted) return;
+          if (!this.download) return;
+          const firstReport = this.download.total === 0 && total > 0;
+          this.download = {
+            model, downloaded, total,
+            message: firstReport
+              ? downloaded > 0 ? "Resuming download from Hugging Face…" : "Downloading from Hugging Face…"
+              : this.download.message,
+          };
+          this.samples.push({ time: this.now(), bytes: downloaded });
+          if (this.samples.length > 64) this.samples.shift();
+          this.changed();
+        },
+      });
+    } catch (error) {
+      work = Promise.reject(error);
+    }
+    void work.then(
+      ({ path }) => {
+        // A superseded save may already have committed. Record that fact even
+        // after disposal; only presentation and navigation ignore stale work.
+        this.cachedById.set(model.id, { path });
+        this.committedModelId = model.id;
+        this.selectedDuringSession = true;
+        if (this.target !== target) { this.changed(); return; }
+        this.target = undefined;
+        this.download = undefined;
+        this.feedback = cached ? undefined : {
+          type: "success", text: `✓ Downloaded and selected ${model.name}`,
+        };
+        if (this.pendingExit) this.finish(this.pendingExit.result);
+        else if (this.options.advance) this.finish(this.options.completion);
+        else this.changed();
+      },
+      (error: unknown) => {
+        const cached = this.findCached(model);
+        if (cached) this.cachedById.set(model.id, cached);
+        else this.cachedById.delete(model.id);
+        if (this.target !== target) { this.changed(); return; }
+        this.target = undefined;
+        this.pendingExit = undefined;
+        this.download = undefined;
+        this.feedback = target.controller.signal.aborted
+          ? { type: "muted", text: "Download stopped — progress saved. Select the model again to resume." }
+          : { type: "error", text: `Could not select ${model.name}: ${error instanceof Error ? error.message : String(error)}` };
+        this.changed();
+      },
+    );
+  }
+
+  cancelDownload(): void {
+    if (!this.acceptsInput || !this.download) return;
+    this.target?.controller.abort();
+    this.download = { ...this.download, message: "Stopping…" };
+    this.changed();
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    // Selecting a cached model is a save, not a cancellable download.
+    if (this.download) this.target?.controller.abort();
+  }
+}

package/src/models.ts

@@ -0,0 +1,263 @@
+import {
+  downloadFile,
+  fileDownloadInfo,
+  getHFHubCachePath,
+  getRepoFolderName,
+} from "@huggingface/hub";
+import { createHash } from "node:crypto";
+import {
+  createReadStream,
+  existsSync,
+  statSync,
+} from "node:fs";
+import {
+  copyFile,
+  mkdir,
+  open,
+  rename,
+  rm,
+  stat,
+  symlink,
+} from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import type { ReadableStream } from "node:stream/web";
+import type { CatalogModel } from "./catalog.js";
+
+function repositoryCacheDirectory(model: CatalogModel): string {
+  return join(
+    getHFHubCachePath(),
+    getRepoFolderName({ name: model.repository, type: "model" }),
+  );
+}
+
+export type CachedCatalogModel = {
+  path: string;
+};
+
+/** Find the exact catalog revision in the standard Hugging Face cache. */
+export function findCachedCatalogModel(model: CatalogModel): CachedCatalogModel | undefined {
+  const path = join(
+    repositoryCacheDirectory(model),
+    "snapshots",
+    model.revision,
+    model.filename,
+  );
+  if (!existsSync(path)) return undefined;
+  try {
+    return statSync(path).size === model.size ? { path } : undefined;
+  } catch {
+    // A cache entry can disappear during concurrent HF cache maintenance.
+    return undefined;
+  }
+}
+
+type DownloadProgress = {
+  downloaded: number;
+  total: number;
+};
+
+async function createCacheLink(blobPath: string, pointerPath: string): Promise<void> {
+  await rm(pointerPath, { force: true });
+  try {
+    await symlink(relative(dirname(pointerPath), blobPath), pointerPath);
+  } catch {
+    // Match Hugging Face's Windows fallback when symlinks are unavailable.
+    await copyFile(blobPath, pointerPath);
+  }
+}
+
+export async function downloadCatalogModel(
+  model: CatalogModel,
+  options: {
+    signal?: AbortSignal;
+    onProgress?: (progress: DownloadProgress) => void;
+    /** Overridable for tests; defaults to the global fetch. */
+    fetch?: typeof fetch;
+  } = {},
+): Promise<string> {
+  const { signal, onProgress } = options;
+  const fetchImpl = options.fetch ?? fetch;
+  signal?.throwIfAborted();
+
+  const storage = repositoryCacheDirectory(model);
+  const pointerPath = join(storage, "snapshots", model.revision, model.filename);
+  if (await stat(pointerPath).then((value) => value.size === model.size, () => false)) {
+    onProgress?.({ downloaded: model.size, total: model.size });
+    return pointerPath;
+  }
+
+  const token = process.env.HF_TOKEN?.trim();
+  const credentials = token ? { accessToken: token } : {};
+  const abortingFetch: typeof fetch = (input, init) =>
+    fetchImpl(input, { ...init, signal });
+  const info = await fileDownloadInfo({
+    repo: model.repository,
+    path: model.filename,
+    revision: model.revision,
+    fetch: abortingFetch,
+    ...credentials,
+  });
+  if (!info) throw new Error(`Could not find ${model.filename} on Hugging Face`);
+  if (info.size !== model.size) {
+    throw new Error(
+      `${model.name} size mismatch: catalog has ${model.size} bytes, Hugging Face reports ${info.size}`,
+    );
+  }
+
+  // Match Hugging Face's standard cache key for these LFS-backed model files.
+  const etag = info.etag.replace(/^W\//, "").replace(/^"|"$/g, "");
+  const blobPath = join(storage, "blobs", etag);
+  // The blob key names this exact content (the size was checked against the
+  // catalog above), so a blob of any other size is a broken write by another
+  // cache user and is replaced by a fresh download.
+  const blobUsable = (): Promise<boolean> =>
+    stat(blobPath).then((value) => value.size === model.size, () => false);
+  await mkdir(dirname(blobPath), { recursive: true });
+  await mkdir(dirname(pointerPath), { recursive: true });
+
+  if (await blobUsable()) {
+    await createCacheLink(blobPath, pointerPath);
+    onProgress?.({ downloaded: model.size, total: model.size });
+    return pointerPath;
+  }
+
+  // A stable partial name lets a later attempt resume after cancellation or a
+  // dropped connection. The picker serializes downloads; simultaneous writes
+  // from separate processes are deliberately outside this best-effort design.
+  const partialPath = `${blobPath}.incomplete`;
+
+  const transfer = async (resume: boolean): Promise<void> => {
+    const digest = createHash("sha256");
+    let downloaded = 0;
+    let body: ReadableStream<Uint8Array> | undefined;
+
+    if (resume) {
+      // Hash the saved prefix, then request and append only the remainder. A
+      // full-size partial skips the payload request and goes to verification.
+      for await (const chunk of createReadStream(partialPath)) {
+        signal?.throwIfAborted();
+        digest.update(chunk as Buffer);
+        downloaded += (chunk as Buffer).length;
+      }
+      if (downloaded < model.size) {
+        const response = await abortingFetch(info.url, {
+          headers: {
+            Range: `bytes=${downloaded}-`,
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+          },
+        });
+        if (response.status === 200 && response.body) {
+          // The server ignored the range; discard the response and restart.
+          await response.body.cancel().catch(() => undefined);
+          await rm(partialPath, { force: true });
+          return transfer(false);
+        }
+        if (response.status !== 206 || !response.body) {
+          // Keep the saved prefix across transient server failures.
+          await response.body?.cancel().catch(() => undefined);
+          throw new Error(
+            `Hugging Face returned HTTP ${response.status} while resuming ${model.name}`,
+          );
+        }
+        const contentRange = response.headers.get("content-range");
+        const range = contentRange?.match(/^bytes (\d+)-\d+\/(\d+)$/);
+        if (!range || Number(range[1]) !== downloaded || Number(range[2]) !== model.size) {
+          // Never append a response for different bytes.
+          await response.body.cancel().catch(() => undefined);
+          throw new Error(
+            `Hugging Face returned an unexpected resume range (${contentRange ?? "missing"}) for ${model.name}`,
+          );
+        }
+        body = response.body as unknown as ReadableStream<Uint8Array>;
+      }
+    } else {
+      await rm(partialPath, { force: true });
+      const blob = await downloadFile({
+        repo: model.repository,
+        path: model.filename,
+        revision: model.revision,
+        downloadInfo: info,
+        fetch: abortingFetch,
+        ...credentials,
+      });
+      if (!blob) throw new Error(`Could not download ${model.filename}`);
+      body = blob.stream() as unknown as ReadableStream<Uint8Array>;
+    }
+
+    onProgress?.({ downloaded, total: model.size });
+    if (body) {
+      let lastReport = 0;
+      const file = await open(partialPath, resume ? "a" : "w");
+      try {
+        for await (const value of body) {
+          signal?.throwIfAborted();
+          const chunk = Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+          // Await each write so any later abort or stream error leaves a clean,
+          // fully written prefix that can safely be resumed.
+          await file.writeFile(chunk);
+          downloaded += chunk.length;
+          digest.update(chunk);
+          const now = Date.now();
+          if (now - lastReport >= 100 || downloaded === model.size) {
+            lastReport = now;
+            onProgress?.({ downloaded, total: model.size });
+          }
+        }
+      } finally {
+        await file.close();
+      }
+    }
+    signal?.throwIfAborted();
+
+    const written = await stat(partialPath);
+    if (written.size < model.size) {
+      throw new Error(`${model.name} download ended early; partial bytes were kept`);
+    }
+    if (written.size > model.size || digest.digest("hex") !== model.sha256) {
+      await rm(partialPath, { force: true });
+      throw new Error(`${model.name} verification failed; incomplete bytes were removed`);
+    }
+  };
+
+  const partialBytes = await stat(partialPath).then((value) => value.size, () => 0);
+  await transfer(partialBytes > 0 && partialBytes <= model.size);
+
+  if (await blobUsable()) {
+    await rm(partialPath, { force: true });
+  } else {
+    try {
+      // rename() replaces a wrong-size blob left by an interrupted writer.
+      await rename(partialPath, blobPath);
+    } catch (error) {
+      // Another process may have published the same verified blob first.
+      if (!(await blobUsable())) throw error;
+      await rm(partialPath, { force: true });
+    }
+  }
+  await createCacheLink(blobPath, pointerPath);
+  onProgress?.({ downloaded: model.size, total: model.size });
+  return pointerPath;
+}
+
+/** A resumable partial download of this model on disk, if any. */
+export function findIncompleteDownload(
+  model: CatalogModel,
+): { bytes: number } | undefined {
+  // For these LFS-backed files the cache key (the server etag) is the content
+  // sha256, so the catalog names the partial exactly; partials from other
+  // revisions can never match. If the server ever reported a different etag,
+  // this merely under-promises: the footer says "download", selecting still
+  // resumes the server-etag partial.
+  const partialPath = join(
+    repositoryCacheDirectory(model),
+    "blobs",
+    `${model.sha256}.incomplete`,
+  );
+  try {
+    const bytes = statSync(partialPath).size;
+    if (bytes > 0 && bytes < model.size) return { bytes };
+  } catch {
+    // Missing file means no partial download.
+  }
+  return undefined;
+}