@juspay/neurolink 13.7.0 → 13.8.1

package/dist/voice/languages.js

@@ -0,0 +1,290 @@
+/**
+ * Language codes and writing systems for the transcribe pipeline.
+ *
+ * Engines report languages in different shapes ("hi", "hin", "Hindi",
+ * "en-US"); routing, correction and output rendering need one: a lower-case
+ * ISO 639 code. Output targets are BCP-47 tags whose script subtag says how
+ * the text is written (`hi-Latn` is Hindi in Latin letters), and the guards
+ * on a rendering check the text against that script.
+ *
+ * @module voice/languages
+ */
+/** Indian languages: the ones the rewrite writes in Latin letters by default. */
+const INDIC_LANGUAGES = new Set([
+    "as",
+    "bn",
+    "brx",
+    "doi",
+    "gu",
+    "hi",
+    "kn",
+    "kok",
+    "ks",
+    "mai",
+    "ml",
+    "mni",
+    "mr",
+    "ne",
+    "or",
+    "pa",
+    "sa",
+    "sat",
+    "sd",
+    "ta",
+    "te",
+    "ur",
+]);
+/** English names (and ISO 639-2/3 codes) engines report instead of a 639-1 code. */
+const LANGUAGE_ALIASES = {
+    english: "en",
+    eng: "en",
+    hindi: "hi",
+    hin: "hi",
+    bengali: "bn",
+    bangla: "bn",
+    ben: "bn",
+    marathi: "mr",
+    mar: "mr",
+    gujarati: "gu",
+    guj: "gu",
+    punjabi: "pa",
+    panjabi: "pa",
+    pan: "pa",
+    odia: "or",
+    oriya: "or",
+    ori: "or",
+    assamese: "as",
+    asm: "as",
+    urdu: "ur",
+    urd: "ur",
+    tamil: "ta",
+    tam: "ta",
+    telugu: "te",
+    tel: "te",
+    kannada: "kn",
+    kan: "kn",
+    malayalam: "ml",
+    mal: "ml",
+    nepali: "ne",
+    nep: "ne",
+    sanskrit: "sa",
+    san: "sa",
+    sindhi: "sd",
+    kashmiri: "ks",
+    konkani: "kok",
+    maithili: "mai",
+    spanish: "es",
+    spa: "es",
+    french: "fr",
+    fra: "fr",
+    german: "de",
+    deu: "de",
+    italian: "it",
+    portuguese: "pt",
+    russian: "ru",
+    japanese: "ja",
+    jpn: "ja",
+    korean: "ko",
+    kor: "ko",
+    chinese: "zh",
+    mandarin: "zh",
+    cantonese: "yue",
+    zho: "zh",
+    arabic: "ar",
+    ara: "ar",
+    persian: "fa",
+    turkish: "tr",
+    dutch: "nl",
+    indonesian: "id",
+    vietnamese: "vi",
+    thai: "th",
+};
+/**
+ * The language part of whatever an engine reported, as a lower-case ISO 639
+ * code: "en-US" → "en", "Hindi" → "hi", "auto-ta" → "ta". `undefined` for
+ * nothing, "auto" and "und".
+ */
+export function normalizeLanguageCode(value) {
+    const trimmed = value?.trim().toLowerCase();
+    if (!trimmed || trimmed === "auto" || trimmed === "und") {
+        return undefined;
+    }
+    const bare = trimmed.replace(/^auto[-_]/u, "");
+    // Own keys only: "constructor" must not resolve to Object.prototype's.
+    if (Object.hasOwn(LANGUAGE_ALIASES, bare)) {
+        return LANGUAGE_ALIASES[bare];
+    }
+    const primary = bare.split(/[-_]/u)[0];
+    if (Object.hasOwn(LANGUAGE_ALIASES, primary)) {
+        return LANGUAGE_ALIASES[primary];
+    }
+    return /^[a-z]{2,3}$/u.test(primary) ? primary : undefined;
+}
+export function isIndicLanguage(language) {
+    const code = normalizeLanguageCode(language);
+    return code !== undefined && INDIC_LANGUAGES.has(code);
+}
+/** Letter ranges per script; `Jpan` counts kana and kanji, `Hani` kanji/hanzi only. */
+const SCRIPT_RANGES = [
+    ["Latn", /\p{Script=Latin}/u],
+    ["Deva", /\p{Script=Devanagari}/u],
+    ["Beng", /\p{Script=Bengali}/u],
+    ["Guru", /\p{Script=Gurmukhi}/u],
+    ["Gujr", /\p{Script=Gujarati}/u],
+    ["Orya", /\p{Script=Oriya}/u],
+    ["Taml", /\p{Script=Tamil}/u],
+    ["Telu", /\p{Script=Telugu}/u],
+    ["Knda", /\p{Script=Kannada}/u],
+    ["Mlym", /\p{Script=Malayalam}/u],
+    ["Sinh", /\p{Script=Sinhala}/u],
+    ["Arab", /\p{Script=Arabic}/u],
+    ["Cyrl", /\p{Script=Cyrillic}/u],
+    ["Grek", /\p{Script=Greek}/u],
+    ["Hebr", /\p{Script=Hebrew}/u],
+    ["Thai", /\p{Script=Thai}/u],
+    ["Hang", /\p{Script=Hangul}/u],
+    ["Jpan", /[\p{Script=Hiragana}\p{Script=Katakana}]/u],
+    ["Hani", /\p{Script=Han}/u],
+    ["Geor", /\p{Script=Georgian}/u],
+    ["Armn", /\p{Script=Armenian}/u],
+    ["Ethi", /\p{Script=Ethiopic}/u],
+];
+/** The script a language is written in when no script subtag says otherwise. */
+const DEFAULT_SCRIPT = {
+    hi: "Deva",
+    mr: "Deva",
+    ne: "Deva",
+    sa: "Deva",
+    mai: "Deva",
+    kok: "Deva",
+    doi: "Deva",
+    brx: "Deva",
+    bn: "Beng",
+    as: "Beng",
+    mni: "Beng",
+    pa: "Guru",
+    gu: "Gujr",
+    or: "Orya",
+    ta: "Taml",
+    te: "Telu",
+    kn: "Knda",
+    ml: "Mlym",
+    si: "Sinh",
+    ur: "Arab",
+    ar: "Arab",
+    fa: "Arab",
+    ps: "Arab",
+    sd: "Arab",
+    ks: "Arab",
+    ru: "Cyrl",
+    uk: "Cyrl",
+    bg: "Cyrl",
+    sr: "Cyrl",
+    mk: "Cyrl",
+    be: "Cyrl",
+    kk: "Cyrl",
+    el: "Grek",
+    he: "Hebr",
+    yi: "Hebr",
+    th: "Thai",
+    ko: "Hang",
+    ja: "Jpan",
+    zh: "Hani",
+    yue: "Hani",
+    ka: "Geor",
+    hy: "Armn",
+    am: "Ethi",
+};
+/** Letters of each script in `text`; scripts with none are absent. */
+export function scriptCounts(text) {
+    const counts = new Map();
+    for (const ch of text) {
+        for (const [script, re] of SCRIPT_RANGES) {
+            if (re.test(ch)) {
+                counts.set(script, (counts.get(script) ?? 0) + 1);
+                break;
+            }
+        }
+    }
+    return counts;
+}
+/** The script most letters of `text` are in, `undefined` for text without letters. */
+export function dominantScript(text) {
+    let best;
+    let bestCount = 0;
+    for (const [script, count] of scriptCounts(text)) {
+        if (count > bestCount) {
+            best = script;
+            bestCount = count;
+        }
+    }
+    return best;
+}
+const INDIC_SCRIPT = /[\p{Script=Devanagari}\p{Script=Bengali}\p{Script=Gurmukhi}\p{Script=Gujarati}\p{Script=Oriya}\p{Script=Tamil}\p{Script=Telugu}\p{Script=Kannada}\p{Script=Malayalam}\p{Script=Sinhala}]/u;
+/** Whether `text` holds letters of an Indic script (Devanagari through Sinhala). */
+export function hasIndicScript(text) {
+    return INDIC_SCRIPT.test(text);
+}
+/**
+ * A BCP-47 output tag: language, optional script, optional region
+ * (`es`, `fr-CA`, `hi-Latn`, `zh-Hant`). `undefined` for anything else.
+ */
+export function parseOutputTag(tag) {
+    const match = /^([a-z]{2,3})(?:-([A-Za-z]{4}))?(?:-([A-Za-z]{2}|\d{3}))?$/iu.exec(tag.trim());
+    if (!match) {
+        return undefined;
+    }
+    const language = match[1].toLowerCase();
+    const subtag = match[2]
+        ? `${match[2][0].toUpperCase()}${match[2].slice(1).toLowerCase()}`
+        : undefined;
+    // Traditional and Simplified Chinese are both Han for the guard.
+    const script = subtag === "Hant" || subtag === "Hans"
+        ? "Hani"
+        : (SCRIPT_RANGES.find(([s]) => s === subtag)?.[0] ??
+            (subtag ? undefined : (DEFAULT_SCRIPT[language] ?? "Latn")));
+    if (!script) {
+        return undefined;
+    }
+    return {
+        tag: tag.trim(),
+        language,
+        script,
+        explicitScript: subtag !== undefined,
+    };
+}
+/** Share of `text`'s letters written in `script` (Japanese accepts kanji as well as kana). */
+export function scriptShare(text, script) {
+    const counts = scriptCounts(text);
+    let total = 0;
+    for (const count of counts.values()) {
+        total += count;
+    }
+    if (total === 0) {
+        return 1;
+    }
+    const own = (counts.get(script) ?? 0) +
+        (script === "Jpan" ? (counts.get("Hani") ?? 0) : 0);
+    return own / total;
+}
+/** "es" → "Spanish", "hi-Latn" → "Hindi (Latin script)"; the tag itself when the runtime cannot name it. */
+export function describeOutputTag(tag) {
+    const parsed = parseOutputTag(tag);
+    if (!parsed) {
+        return tag;
+    }
+    const name = displayName("language", parsed.language);
+    if (!parsed.explicitScript) {
+        return name;
+    }
+    return `${name} (${displayName("script", parsed.script)} script)`;
+}
+/** The English name of a language or script code; the code itself when the runtime has no name for it. */
+function displayName(type, code) {
+    try {
+        return new Intl.DisplayNames(["en"], { type }).of(code) ?? code;
+    }
+    catch {
+        return code;
+    }
+}

package/dist/voice/modelAssets.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared plumbing for the model files NeuroLink ships or fetches on first
+ * use (Whistle's runtime and model, the Silero VAD model): where the
+ * package's own `models/` directory is, whether a file on disk is the pinned
+ * one, and a verified atomic download. Each model keeps its own manifest and
+ * directory rules; this module only ever looks at one file at a time.
+ *
+ * @module voice/modelAssets
+ */
+import type { LocalModelAsset } from "../types/index.js";
+/** Per-file download deadline; generous because Whistle's model is 17 MB. */
+export declare const MODEL_DOWNLOAD_TIMEOUT_MS: number;
+/**
+ * The package's own `models` directory, found by walking up from this module
+ * to the directory holding NeuroLink's `package.json`. Works from the source
+ * tree, from `dist/` and from the single-file bundles, since all of them sit
+ * below the package root; `null` when nothing above looks like the package.
+ */
+export declare function packageModelsDir(): string | null;
+/** Whether the file at `path` is `asset`: size first (cheap), then the SHA-256. */
+export declare function checkModelFile(path: string, asset: LocalModelAsset): Promise<"ok" | "missing" | "corrupt">;
+export declare function hashModelFile(path: string): Promise<string>;
+/**
+ * Fetches `asset` into `dir`, verifying the SHA-256 before anything is
+ * written and writing atomically (temp file + rename), so an interrupted
+ * download never leaves a file that looks complete. `label` prefixes the log.
+ */
+export declare function downloadModelAsset(asset: LocalModelAsset, dir: string, label: string): Promise<void>;

package/dist/voice/modelAssets.js

@@ -0,0 +1,113 @@
+/**
+ * Shared plumbing for the model files NeuroLink ships or fetches on first
+ * use (Whistle's runtime and model, the Silero VAD model): where the
+ * package's own `models/` directory is, whether a file on disk is the pinned
+ * one, and a verified atomic download. Each model keeps its own manifest and
+ * directory rules; this module only ever looks at one file at a time.
+ *
+ * @module voice/modelAssets
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { createReadStream, existsSync, readFileSync } from "node:fs";
+import { rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { logger } from "../utils/logger.js";
+/** Per-file download deadline; generous because Whistle's model is 17 MB. */
+export const MODEL_DOWNLOAD_TIMEOUT_MS = 10 * 60_000;
+let modelsDir;
+/**
+ * The package's own `models` directory, found by walking up from this module
+ * to the directory holding NeuroLink's `package.json`. Works from the source
+ * tree, from `dist/` and from the single-file bundles, since all of them sit
+ * below the package root; `null` when nothing above looks like the package.
+ */
+export function packageModelsDir() {
+    if (modelsDir !== undefined) {
+        return modelsDir;
+    }
+    modelsDir = null;
+    let dir;
+    try {
+        dir = dirname(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return modelsDir;
+    }
+    for (let depth = 0; depth < 8; depth += 1) {
+        const manifest = join(dir, "package.json");
+        if (existsSync(manifest)) {
+            try {
+                const parsed = JSON.parse(readFileSync(manifest, "utf8"));
+                if (parsed.name === "@juspay/neurolink") {
+                    modelsDir = join(dir, "models");
+                    return modelsDir;
+                }
+            }
+            catch {
+                // Not a manifest we can read; keep walking up.
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    return modelsDir;
+}
+/** Whether the file at `path` is `asset`: size first (cheap), then the SHA-256. */
+export async function checkModelFile(path, asset) {
+    try {
+        const info = await stat(path);
+        if (!info.isFile()) {
+            return "missing";
+        }
+        if (info.size !== asset.bytes) {
+            return "corrupt";
+        }
+    }
+    catch {
+        return "missing";
+    }
+    return (await hashModelFile(path)) === asset.sha256 ? "ok" : "corrupt";
+}
+export function hashModelFile(path) {
+    return new Promise((resolvePromise, reject) => {
+        const hash = createHash("sha256");
+        createReadStream(path)
+            .on("data", (chunk) => hash.update(chunk))
+            .on("error", reject)
+            .on("end", () => resolvePromise(hash.digest("hex")));
+    });
+}
+/**
+ * Fetches `asset` into `dir`, verifying the SHA-256 before anything is
+ * written and writing atomically (temp file + rename), so an interrupted
+ * download never leaves a file that looks complete. `label` prefixes the log.
+ */
+export async function downloadModelAsset(asset, dir, label) {
+    const response = await fetch(asset.url, {
+        signal: AbortSignal.timeout(MODEL_DOWNLOAD_TIMEOUT_MS),
+        redirect: "follow",
+    });
+    if (!response.ok) {
+        throw new Error(`${asset.name}: HTTP ${response.status}`);
+    }
+    const body = Buffer.from(await response.arrayBuffer());
+    const digest = createHash("sha256").update(body).digest("hex");
+    if (digest !== asset.sha256) {
+        throw new Error(`${asset.name}: SHA-256 mismatch (expected ${asset.sha256}, got ${digest})`);
+    }
+    const target = join(dir, asset.name);
+    const temp = join(dir, `.${asset.name}.${process.pid}.${randomBytes(4).toString("hex")}.part`);
+    try {
+        await writeFile(temp, body);
+        await rename(temp, target);
+    }
+    catch (error) {
+        await rm(temp, { force: true }).catch(() => undefined);
+        throw error;
+    }
+    logger.debug(`[${label}] ${asset.name} verified and saved to ${target}`);
+}

package/dist/voice/output/render.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Output languages: the transcript rendered in other languages and scripts.
+ *
+ * One structured model call renders every requested target for a batch of
+ * lines (an utterance, or up to 20 segments of a recording), from the
+ * native-script engine text plus its corrected form, with earlier lines and
+ * their renderings as context. Targets that are the transcript's own
+ * language and script need no call at all.
+ *
+ * A rendering is never allowed to cost the transcript anything: it runs
+ * after the text is settled, fails open, and reports what happened in its
+ * `status`. The guards refuse an answer that is empty, in the wrong script
+ * for its tag, or the source handed back untranslated; a refused target gets
+ * one retry on its own.
+ *
+ * @module voice/output/render
+ */
+import type { STTCorrectionDeps, STTOutputOptions, STTOutputRenderInput, STTOutputRendering } from "../../types/index.js";
+/** Distinct targets accepted per request. */
+export declare const MAX_OUTPUT_LANGUAGES = 8;
+/** The tag that means "the transcript as it is". */
+export declare const SOURCE_OUTPUT = "source";
+/**
+ * The output languages in effect right now: read from a live source when
+ * one was given, trimmed, de-duplicated (case-insensitively) and capped.
+ */
+export declare function outputLanguagesOf(output: STTOutputOptions | undefined): string[];
+/**
+ * Render one transcript (one or more lines) into every requested language.
+ * Returns one entry per requested tag, keyed by the tag as given. Never throws.
+ */
+export declare function renderOutputs(input: STTOutputRenderInput, deps: Pick<STTCorrectionDeps, "render">): Promise<Record<string, STTOutputRendering>>;