sailfork / t3code-github / apps/ server/ scripts/ speech-catalog.ts

import {
  accuracyGrade,
  canonicalLanguage,
  compareEngineVersions,
  BENCHMARK_DICTATION_SECONDS,
  languageIdentity,
  modelFile,
  type CatalogData,
} from "@handy-computer/models";
import { format } from "vite-plus/fmt";

// ASR architectures registered in transcribe.cpp v0.4.1's src/transcribe-arch.cpp.
const ASR_FAMILIES = new Set([
  "parakeet",
  "cohere_asr",
  "canary",
  "qwen3_asr",
  "moss",
  "voxtral",
  "voxtral_realtime",
  "canary_qwen",
  "whisper",
  "moonshine",
  "moonshine_streaming",
  "sensevoice",
  "funasr_nano",
  "gigaam",
  "granite_speech",
  "granite_speech_nar",
  "granite5_ctc",
  "medasr",
]);

// Preserve Handy's onboarding badges; curation alone also includes specialist models.
const RECOMMENDED = new Set([
  "parakeet-unified-en-0.6b",
  "nemotron-3.5-asr-streaming-0.6b",
  "canary-180m-flash",
  "cohere-transcribe-03-2026",
  "whisper-medium",
]);

// Handy labels these weights MIT; Moonshine lists them under its Community License at https://huggingface.co/moonshine-ai/moonshine-models.
const COMMUNITY_LICENSED_MOONSHINE = /^moonshine-(?:(?:base|tiny)-(?:ar|ja|ko|uk|vi|zh)|base-es)$/;

export function generateSpeechCatalog(
  data: CatalogData,
  sourceVersion: string,
  engineVersion: string,
) {
  if (data.schema !== 2) throw new Error("Unsupported speech catalog schema.");
  if (engineVersion !== "0.4.1")
    throw new Error("Review speech catalog loader support for this engine.");
  const ids = new Set<string>();
  const filenames = new Set<string>();
  const models = data.models.flatMap((model) => {
    if (
      model.role !== "asr" ||
      /(?:^|[^a-z0-9])nc(?:$|[^a-z0-9])/i.test(model.license) ||
      COMMUNITY_LICENSED_MOONSHINE.test(model.id) ||
      !ASR_FAMILIES.has(model.family) ||
      compareEngineVersions(model.minEngine ?? data.transcribeCpp, engineVersion) > 0
    )
      return [];

    const file = modelFile(model);
    // The store and native loader accept one root-level GGUF per model.
    if (!/^[^/\\:]+\.gguf$/.test(file.filename) || file.filename.startsWith(".")) return [];
    if (
      !/^\w[\w.-]*\/\w[\w.-]*$/.test(model.repository) ||
      !/^[a-f0-9]{40}$/.test(model.revision) ||
      !/^[a-f0-9]{64}$/.test(file.sha256) ||
      !Number.isSafeInteger(file.size) ||
      file.size <= 0 ||
      model.languages.length === 0
    )
      throw new Error(`Invalid speech catalog metadata: ${model.id}`);
    if (ids.has(model.repository) || filenames.has(file.filename)) {
      throw new Error(`Duplicate speech catalog model or filename: ${model.id}`);
    }
    ids.add(model.repository);
    filenames.add(file.filename);
    const languages = [...new Set(model.languages.map(canonicalLanguage))];
    const realtimeFactor = data.results[model.id]?.performance.accelerated;
    const accuracy = Object.fromEntries(
      languages.flatMap((language) => {
        const cell = data.results[model.id]?.accuracy[languageIdentity(language)];
        return cell
          ? [
              [
                language,
                { grade: accuracyGrade(cell.error).label, errorPercent: cell.error },
              ] as const,
            ]
          : [];
      }),
    );
    return [
      {
        id: model.repository,
        revision: model.revision,
        name: model.name,
        description: model.description || `${model.name} speech-to-text.`,
        filename: file.filename,
        size: file.size,
        sha256: file.sha256,
        license: model.license,
        // T3 selects base languages; the engine's prompt dictionary accepts their short aliases.
        languages,
        benchmark: {
          accuracy,
          secondsPer30s: realtimeFactor
            ? Number((BENCHMARK_DICTATION_SECONDS / realtimeFactor).toFixed(2))
            : null,
        },
        recommended: RECOMMENDED.has(model.id),
        supportsStreaming: model.capabilities.streaming,
        supportsLanguageDetection: model.capabilities.languageDetection,
        supportsTranslation: model.capabilities.translate,
      },
    ];
  });
  return { source: "@handy-computer/models", sourceVersion, engineVersion, models };
}

export async function renderSpeechCatalog(
  data: CatalogData,
  sourceVersion: string,
  engineVersion: string,
) {
  const result = await format(
    "catalog.json",
    JSON.stringify(generateSpeechCatalog(data, sourceVersion, engineVersion)),
  );
  if (result.errors.length > 0) throw new Error("Could not format speech catalog.");
  return result.code;
}