@juspay/neurolink 13.6.5 → 13.8.0

package/dist/voice/correction/rewrite.js

@@ -18,9 +18,103 @@
  * @module voice/correction/rewrite
  */
 import { TimeoutError, withTimeout } from "../../utils/async/withTimeout.js";
+import { describeOutputTag, hasIndicScript, isIndicLanguage, normalizeLanguageCode, } from "../languages.js";
+import { analyzeCodeMix } from "../codeMix.js";
 import { dictionaryBlock } from "./dictionary.js";
-/** Default per-call rewrite timeout; on expiry the input text is kept. */
-export const DEFAULT_REWRITE_TIMEOUT_MS = 12000;
+/**
+ * The rewrite's provider/model/timeout settings, whatever shape `rewrite`
+ * took: `false` and `"auto"` carry none, an object carries its own.
+ */
+export function rewriteSettings(rewrite) {
+    return rewrite && typeof rewrite === "object" ? rewrite : undefined;
+}
+/**
+ * Whether the rewrite is wanted for a text, under the "auto" rule: it runs
+ * when there is something for it to do and is skipped otherwise, which is
+ * what makes an already clean English sentence cost nothing. `"always"`
+ * (object form with `mode: "always"`) runs it every time; `false` never.
+ */
+export function rewriteWanted(text, options, signals = {}) {
+    const rewrite = options?.rewrite;
+    if (rewrite === false) {
+        return { wanted: false, reason: "rewrite off" };
+    }
+    if (typeof rewrite === "object" && rewrite.mode === "always") {
+        return { wanted: true, reason: "always" };
+    }
+    const trimmed = text.trim();
+    if (!trimmed) {
+        return { wanted: false, reason: "empty" };
+    }
+    if (signals.hasSecondOpinion) {
+        return { wanted: true, reason: "second opinion to reconcile" };
+    }
+    if (options?.cleanup === "clean") {
+        return { wanted: true, reason: "clean verbatim" };
+    }
+    if ((signals.termsApplied ?? 0) > 0) {
+        return { wanted: true, reason: "dictionary term applied" };
+    }
+    const transliterate = resolveTransliterate(options, signals.language);
+    if (transliterate === "latin" && needsRomanising(trimmed, signals.language)) {
+        return { wanted: true, reason: "romanise" };
+    }
+    if (options?.punctuate !== false) {
+        const words = trimmed.split(/\s+/u).length;
+        if (words >= 4 && !TERMINAL_PUNCTUATION.test(trimmed)) {
+            return { wanted: true, reason: "punctuate" };
+        }
+    }
+    return { wanted: false, reason: "nothing to change" };
+}
+/** Any letter outside the Latin blocks (Indic, Arabic, CJK, Cyrillic …). */
+const NON_LATIN_LETTER = /(?!\p{Script=Latin})\p{L}/u;
+/** Arabic-script letters, which are Indian-language text only for Urdu, Sindhi and Kashmiri. */
+const ARABIC_LETTER = /\p{Script=Arabic}/u;
+/**
+ * The script setting in effect. Unset, Indian languages (and speech whose
+ * language is unknown, as before) are written in Latin letters; any other
+ * known language keeps its own script.
+ */
+export function resolveTransliterate(options, language) {
+    if (options?.transliterate) {
+        return options.transliterate;
+    }
+    const code = normalizeLanguageCode(language);
+    return code && code !== "en" && !isIndicLanguage(code) ? "native" : "latin";
+}
+/**
+ * Whether `text` holds script the Latin setting converts: Indic letters, or
+ * Arabic letters when the language is Urdu, Sindhi or Kashmiri, or any
+ * non-Latin letters when the caller explicitly asked for Latin output in a
+ * language outside India.
+ */
+function needsRomanising(text, language) {
+    if (hasIndicScript(text)) {
+        return true;
+    }
+    const code = normalizeLanguageCode(language);
+    if (ARABIC_LETTER.test(text) &&
+        (code === "ur" || code === "sd" || code === "ks")) {
+        return true;
+    }
+    return (code !== undefined &&
+        code !== "en" &&
+        !isIndicLanguage(code) &&
+        NON_LATIN_LETTER.test(text));
+}
+/**
+ * Whether the Indian-language prompt applies: Indian languages, English
+ * (code-mixed speech is often reported as English) and speech whose language
+ * is unknown. Any other known language gets the general prompt.
+ */
+function indicPrompt(language) {
+    const code = normalizeLanguageCode(language);
+    return code === undefined || code === "en" || isIndicLanguage(code);
+}
+/** Ends with a sentence mark, the danda, or a closing quote/bracket after one. */
+const TERMINAL_PUNCTUATION = /[.!?\u0964\u0965\u2026][\s"'\u201D\u2019)\]]*$/u;
+const DEFAULT_REWRITE_TIMEOUT_MS = 12000;
 /** Default per-batch timeout for `rewriteLines`: a batch carries up to 25 lines. */
 export const DEFAULT_REWRITE_LINES_TIMEOUT_MS = 60000;
 /** Default share of words a rewrite may drop before it is discarded. */
@@ -68,9 +162,13 @@ function scriptRule(transliterate) {
  * transcripts: numbered lines in, the same numbered lines out.
  */
 export function buildRewriteSystemPrompt(options) {
+    if (!indicPrompt(options?.language)) {
+        return buildGeneralRewriteSystemPrompt(options ?? {});
+    }
     const transliterate = options?.transliterate ?? "latin";
     const punctuate = options?.punctuate ?? true;
     const lines = options?.lines ?? false;
+    const clean = options?.cleanup === "clean";
     const table = dictionaryBlock(options?.dictionary);
     const rules = [
         scriptRule(transliterate),
@@ -82,18 +180,36 @@ export function buildRewriteSystemPrompt(options) {
         rules.push('- Use the dictionary: a word or phrase that sounds like a term or one of its "also heard as" forms, ' +
             "and means that term here, is written as the term exactly.");
     }
-    if (lines) {
-        rules.push("- Also fix near-homophones that make no sense in context when the intended word is obvious.");
-    }
+    // Indic engines mis-hear short words into near-homophones that read as
+    // real words (कल "tomorrow" → खाल "skin"); only context reveals them.
+    rules.push("- Fix near-homophones that make no sense in context when the intended word is obvious " +
+        '(खाल heard where कल, "tomorrow", is meant); never change a word that makes sense as heard.');
+    const fillers = clean ? "remove fillers" : "keep fillers";
     rules.push(punctuate
-        ? "- Add natural punctuation and capitalization; write numbers as digits; keep fillers."
-        : "- Do not add or change punctuation or capitalization; keep fillers.");
-    rules.push(lines
-        ? "- Keep every word: never summarize, add, drop, reorder or merge. Keep any speaker label at the " +
-            "start of a line unchanged. A line that needs no change is returned verbatim."
-        : "- Keep every word: never summarize, add, drop or reorder. With two transcripts, take " +
-            "Indian-language words from the one that has them in an Indian language and English words " +
-            "from the one that spells them in English; elsewhere prefer Transcript 1.");
+        ? `- Add natural punctuation and capitalization; write numbers as digits; ${fillers}.`
+        : `- Do not add or change punctuation or capitalization; ${fillers}.`);
+    if (clean) {
+        rules.push("- Clean verbatim: drop fillers (um, uh, hmm, a 'like' or 'you know' that carries no meaning), " +
+            'stutters and immediate word repeats ("they they they" → "they", "no, no, no" → "no"), ' +
+            "and false starts that the speaker restarted. Never drop a word that carries meaning, never " +
+            "summarize, add or reorder.");
+    }
+    else {
+        rules.push(lines
+            ? "- Keep every word: never summarize, add, drop, reorder or merge. Keep any speaker label at the " +
+                "start of a line unchanged. A line that needs no change is returned verbatim."
+            : "- Keep every word: never summarize, add, drop or reorder. With two transcripts, take " +
+                "Indian-language words from the one that has them in an Indian language and English words " +
+                "from the one that spells them in English; elsewhere prefer Transcript 1. When a word " +
+                "alignment is given, decide word by word: a pair that is the same English word (मीटिंग ≈ meeting) " +
+                "is that English word; where the English transcript has an English-sounding guess at an " +
+                "Indian-language word (भेज देना | page dinner), keep the Indian-language word. Sounding alike " +
+                "is not enough: when the English word makes no sense in the sentence, the speaker said the " +
+                'Indian-language word (खाल ≈ Call before "meeting hai" is kal, tomorrow).');
+    }
+    if (clean && lines) {
+        rules.push("- Never merge or reorder lines. Keep any speaker label at the start of a line unchanged.");
+    }
     const head = [
         "You are a post-editor for speech-recognition (ASR) transcripts. The speaker talks English, " +
             "an Indian language (Hindi, Bengali, Marathi, Gujarati, Punjabi, Odia, Assamese, Urdu, Tamil, " +
@@ -111,6 +227,56 @@ export function buildRewriteSystemPrompt(options) {
     ].join("\n");
     return table ? `${head}\n\n${table}` : head;
 }
+/**
+ * The rewrite prompt for a known language outside India: fix what the engine
+ * got wrong, keep the language and its script (unless Latin letters were
+ * asked for), never translate.
+ */
+function buildGeneralRewriteSystemPrompt(options) {
+    const code = normalizeLanguageCode(options.language) ?? "und";
+    const name = describeOutputTag(code);
+    const punctuate = options.punctuate ?? true;
+    const lines = options.lines ?? false;
+    const clean = options.cleanup === "clean";
+    const table = dictionaryBlock(options.dictionary);
+    const rules = [
+        options.transliterate === "latin"
+            ? `- Write ${name} in Latin letters using its standard romanization; keep the words in ${name}.`
+            : `- Keep the text in ${name} and in its own writing system; never transliterate it.`,
+        `- NEVER translate. A ${name} word stays ${name} and an English word stays English.`,
+        "- Fix words the recognizer mis-heard when the intended word is obvious from context; " +
+            "English words get their correct English spelling.",
+    ];
+    if (table) {
+        rules.push('- Use the dictionary: a word or phrase that sounds like a term or one of its "also heard as" forms, ' +
+            "and means that term here, is written as the term exactly.");
+    }
+    const fillers = clean ? "remove fillers" : "keep fillers";
+    rules.push(punctuate
+        ? `- Add natural punctuation and capitalization in ${name}'s own conventions; write numbers as digits; ${fillers}.`
+        : `- Do not add or change punctuation or capitalization; ${fillers}.`);
+    rules.push(clean
+        ? "- Clean verbatim: drop fillers, stutters, immediate repeats and restarted false starts. " +
+            "Never drop a word that carries meaning, never summarize, add or reorder."
+        : lines
+            ? "- Keep every word: never summarize, add, drop, reorder or merge. Keep any speaker label at the " +
+                "start of a line unchanged. A line that needs no change is returned verbatim."
+            : "- Keep every word: never summarize, add, drop or reorder. With two transcripts, take each word " +
+                "from the one that wrote it correctly; elsewhere prefer Transcript 1.");
+    const head = [
+        `You are a post-editor for speech-recognition (ASR) transcripts. The speaker talks ${name}, ` +
+            "possibly mixed with English.",
+        lines
+            ? "Input: a numbered list of transcript lines."
+            : "Input: an ASR transcript, and possibly a second transcript of the same audio from another engine.",
+        "Write the speaker's words exactly as they said them:",
+        ...rules,
+        lines
+            ? "Output: the same numbered lines, one per input line, nothing else."
+            : "Output only the corrected text, nothing else.",
+    ].join("\n");
+    return table ? `${head}\n\n${table}` : head;
+}
 /**
  * User message for the rewrite. With a second opinion the two transcripts are
  * labelled; `literal` lists aliases the guard decided were meant literally, so
@@ -118,14 +284,75 @@ export function buildRewriteSystemPrompt(options) {
  */
 export function buildRewriteUserPrompt(primary, secondOpinion, extras) {
     const second = secondOpinion?.trim();
+    const previous = (extras?.previous ?? [])
+        .map((line) => line.trim())
+        .filter(Boolean);
+    const context = previous.length
+        ? "Earlier in this conversation (context only: do not correct, translate or repeat these):\n" +
+            previous.map((line) => `- ${line}`).join("\n") +
+            "\n\n"
+        : "";
     const body = second
         ? `Transcript 1 (${extras?.labels?.primary ?? "primary engine"}): ${primary}\n` +
             `Transcript 2 (${extras?.labels?.secondary ?? "second engine"}): ${second}`
         : `Transcript: ${primary}`;
+    const aligned = alignmentBlock(extras?.pairs);
     const literal = [...new Set(extras?.literal ?? [])].filter(Boolean);
+    if (aligned) {
+        return literal.length
+            ? `${context}${body}\n${aligned}\nMeant literally here, not dictionary terms: ${literal.map((w) => `"${w}"`).join(", ")}`
+            : `${context}${body}\n${aligned}`;
+    }
     return literal.length
-        ? `${body}\nMeant literally here, not dictionary terms: ${literal.map((w) => `"${w}"`).join(", ")}`
-        : body;
+        ? `${context}${body}\nMeant literally here, not dictionary terms: ${literal.map((w) => `"${w}"`).join(", ")}`
+        : `${context}${body}`;
+}
+/** Most aligned positions shown to the model. */
+const MAX_ALIGNED_PAIRS = 120;
+/** Largest word grid (primary × second opinion) aligned for reconciliation: ~500 × 500. */
+const MAX_ALIGN_CELLS = 250_000;
+/**
+ * The word alignment of two transcripts as a prompt block: same-sounding
+ * words side by side ("मीटिंग ≈ meeting"), and runs where only one engine
+ * heard something, so the rewrite decides word by word which reading holds
+ * the speaker's word in which language.
+ */
+export function alignmentBlock(pairs) {
+    if (!pairs?.length) {
+        return undefined;
+    }
+    const cells = pairs
+        .slice(0, MAX_ALIGNED_PAIRS)
+        .map((p) => p.alike
+        ? `${p.indic} ≈ ${p.latin}`
+        : `${p.indic ?? "∅"} | ${p.latin ?? "∅"}`);
+    return ("Word alignment of the two transcripts, in order (≈ sounds alike, | heard differently, ∅ nothing there):\n" +
+        cells.join("; "));
+}
+/**
+ * Word pairs for a reconciliation: the Indic-script transcript aligned
+ * against the Latin-script one, whichever order they came in; `undefined`
+ * when both are in the same script (nothing to line up across scripts).
+ */
+export function reconcilePairs(primary, secondOpinion) {
+    if (!secondOpinion?.trim()) {
+        return undefined;
+    }
+    const indicFirst = hasIndicScript(primary) && !hasIndicScript(secondOpinion);
+    const indicSecond = hasIndicScript(secondOpinion) && !hasIndicScript(primary);
+    if (!indicFirst && !indicSecond) {
+        return undefined;
+    }
+    // The alignment is quadratic; a whole long transcript is reconciled
+    // without pairs rather than stalling the event loop.
+    const cells = primary.split(/\s+/u).length * secondOpinion.split(/\s+/u).length;
+    if (cells > MAX_ALIGN_CELLS) {
+        return undefined;
+    }
+    const mix = indicFirst
+        ? analyzeCodeMix(primary, secondOpinion)
+        : analyzeCodeMix(secondOpinion, primary);
+    return { pairs: mix.pairs, englishShare: mix.englishShare };
 }
 /** A label the model may echo in front of its answer ("Transcript 1 (…):"). */
 const ECHOED_LABEL_RE = /^(?:corrected\s+)?transcript(?:\s*\d+)?(?:\s*\([^)]*\))?\s*:\s*/iu;
@@ -152,10 +379,14 @@ function dropRatio(before, after) {
     }
     return Math.max(0, (inWords - countWords(after)) / inWords);
 }
-function resolveDropRatio(value) {
+/** Share of words a clean-verbatim rewrite may remove when the caller set no `maxDropRatio`. */
+const CLEAN_MAX_DROP_RATIO = 0.5;
+function resolveDropRatio(value, cleanup) {
     return typeof value === "number" && Number.isFinite(value)
         ? Math.min(1, Math.max(0, value))
-        : DEFAULT_MAX_DROP_RATIO;
+        : cleanup === "clean"
+            ? CLEAN_MAX_DROP_RATIO
+            : DEFAULT_MAX_DROP_RATIO;
 }
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
@@ -168,7 +399,7 @@ function errorMessage(error) {
 export async function rewriteTranscript(input, rewrite) {
     const started = Date.now();
     const { primary, secondOpinion, options } = input;
-    const settings = options?.rewrite === false ? undefined : options?.rewrite;
+    const settings = rewriteSettings(options?.rewrite);
     const timeoutMs = settings?.timeoutMs && settings.timeoutMs > 0
         ? settings.timeoutMs
         : DEFAULT_REWRITE_TIMEOUT_MS;
@@ -195,13 +426,17 @@ export async function rewriteTranscript(input, rewrite) {
     try {
         content = await withTimeout(rewrite({
             system: buildRewriteSystemPrompt({
-                transliterate: options?.transliterate,
+                transliterate: resolveTransliterate(options, input.language),
                 punctuate: options?.punctuate,
+                cleanup: options?.cleanup,
                 dictionary: input.dictionary,
+                language: input.language,
             }),
             user: buildRewriteUserPrompt(primary, secondOpinion, {
                 labels: input.labels,
                 literal: input.literal,
+                previous: input.previous,
+                ...(input.pairs ? { pairs: input.pairs } : {}),
             }),
             provider: settings?.provider,
             model: settings?.model,
@@ -222,11 +457,46 @@ export async function rewriteTranscript(input, rewrite) {
         return keep("empty");
     }
     const ratio = dropRatio(primary, text);
-    if (ratio > resolveDropRatio(options?.maxDropRatio)) {
+    if (ratio > resolveDropRatio(options?.maxDropRatio, options?.cleanup)) {
         return keep("dropped", { dropRatio: ratio });
     }
+    if (addedWords(primary, secondOpinion, text, input.previous)) {
+        return keep("added");
+    }
     return { text, status: "ok", ms: Date.now() - started };
 }
+/**
+ * Whether a rewrite says more than was spoken: noticeably more words than
+ * the longer of the two readings it was given (a model that joins both
+ * readings one after the other instead of choosing between them), or a run
+ * of six words copied from an earlier utterance that the input does not
+ * contain (a model that repeats its context).
+ */
+function addedWords(primary, secondOpinion, output, previous) {
+    const given = Math.max(countWords(primary), countWords(secondOpinion ?? ""));
+    const out = countWords(output);
+    if (out > given * 1.3 + 3) {
+        return true;
+    }
+    const norm = (t) => t
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\s]/gu, " ")
+        .split(/\s+/u)
+        .filter(Boolean);
+    const inputText = ` ${[...norm(primary), ...norm(secondOpinion ?? "")].join(" ")} `;
+    const outWords = norm(output);
+    for (const line of previous ?? []) {
+        const prev = norm(line);
+        for (let i = 0; i + 6 <= prev.length; i++) {
+            const run = prev.slice(i, i + 6).join(" ");
+            if (` ${outWords.join(" ")} `.includes(` ${run} `) &&
+                !inputText.includes(` ${run} `)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
 /** Run `task` over `items` with at most `limit` in flight; results keep input order. */
 async function mapLimited(items, limit, task) {
     const results = new Array(items.length);
@@ -252,18 +522,18 @@ const NUMBERED_LINE_RE = /^\s*(\d+)[.)]\s?(.*)$/gmu;
 export async function rewriteLines(lines, rewrite, options) {
     const started = Date.now();
     const out = [...lines];
-    const settings = options?.correction?.rewrite === false
-        ? undefined
-        : options?.correction?.rewrite;
+    const settings = rewriteSettings(options?.correction?.rewrite);
     const timeoutMs = settings?.timeoutMs && settings.timeoutMs > 0
         ? settings.timeoutMs
         : DEFAULT_REWRITE_LINES_TIMEOUT_MS;
-    const maxDrop = resolveDropRatio(options?.correction?.maxDropRatio);
+    const maxDrop = resolveDropRatio(options?.correction?.maxDropRatio, options?.correction?.cleanup);
     const system = buildRewriteSystemPrompt({
-        transliterate: options?.correction?.transliterate,
+        transliterate: resolveTransliterate(options?.correction, options?.language),
         punctuate: options?.correction?.punctuate,
+        cleanup: options?.correction?.cleanup,
         dictionary: options?.dictionary,
         lines: true,
+        language: options?.language,
     });
     const indices = lines
         .map((line, index) => (line.trim() ? index : -1))

package/dist/voice/eval/sttEvalLangfuse.d.ts

@@ -0,0 +1,14 @@
+import type { ServerSTTEvalBatchRequest, ServerSTTEvalLangfuseConfig, ServerSTTEvalReport } from "../../types/index.js";
+/** The export configuration from the environment, or `undefined` when it is not set up. */
+export declare function sttEvalLangfuseConfigFromEnv(env?: NodeJS.ProcessEnv): ServerSTTEvalLangfuseConfig | undefined;
+export declare class STTEvalLangfuseExporter {
+    private readonly _config;
+    private _tail;
+    constructor(config: ServerSTTEvalLangfuseConfig);
+    /** Queues one batch (and the call's comparison after it) for export. Never throws. */
+    export(batch: ServerSTTEvalBatchRequest, report: ServerSTTEvalReport | undefined): Promise<void>;
+    /** Resolves once every export queued so far has been attempted. */
+    flush(): Promise<void>;
+    private _eventsFor;
+    private _send;
+}

package/dist/voice/eval/sttEvalLangfuse.js

@@ -0,0 +1,182 @@
+/**
+ * Langfuse export for the STT evaluation collector.
+ *
+ * Configured only by the server's environment, never by a request or a route
+ * option: where evaluation data goes is the operator's decision.
+ *
+ *   NEUROLINK_STT_EVAL_LANGFUSE_PUBLIC_KEY / _SECRET_KEY   both required
+ *   NEUROLINK_STT_EVAL_LANGFUSE_BASE_URL                   default https://cloud.langfuse.com
+ *   NEUROLINK_STT_EVAL_LANGFUSE_ENVIRONMENT                optional
+ *
+ * These are separate from NeuroLink's own `LANGFUSE_*` keys so evaluations
+ * land in a project of their own. Each call is one trace (`stt-eval`), each
+ * segment one event under it, and the disagreement figures are scores on the
+ * trace. Ids are derived from the call and segment ids, so a resent batch
+ * updates what it sent before instead of duplicating it. An export never
+ * fails or delays the batch that caused it: it runs in the background, in
+ * order, and a failure is logged.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { logger } from "../../utils/logger.js";
+const DEFAULT_BASE_URL = "https://cloud.langfuse.com";
+const REQUEST_TIMEOUT_MS = 15_000;
+/** Events per ingestion request, well under Langfuse's request-size limit. */
+const EVENTS_PER_REQUEST = 500;
+/** The export configuration from the environment, or `undefined` when it is not set up. */
+export function sttEvalLangfuseConfigFromEnv(env = process.env) {
+    const publicKey = env.NEUROLINK_STT_EVAL_LANGFUSE_PUBLIC_KEY?.trim();
+    const secretKey = env.NEUROLINK_STT_EVAL_LANGFUSE_SECRET_KEY?.trim();
+    if (!publicKey || !secretKey) {
+        return undefined;
+    }
+    const environment = env.NEUROLINK_STT_EVAL_LANGFUSE_ENVIRONMENT?.trim();
+    return {
+        publicKey,
+        secretKey,
+        baseUrl: (env.NEUROLINK_STT_EVAL_LANGFUSE_BASE_URL?.trim() || DEFAULT_BASE_URL).replace(/\/+$/u, ""),
+        ...(environment ? { environment } : {}),
+    };
+}
+export class STTEvalLangfuseExporter {
+    _config;
+    _tail = Promise.resolve();
+    constructor(config) {
+        this._config = config;
+    }
+    /** Queues one batch (and the call's comparison after it) for export. Never throws. */
+    export(batch, report) {
+        const events = this._eventsFor(batch, report);
+        this._tail = this._tail.then(() => this._send(batch.call_id, events));
+        return this._tail;
+    }
+    /** Resolves once every export queued so far has been attempted. */
+    flush() {
+        return this._tail;
+    }
+    _eventsFor(batch, report) {
+        const now = new Date().toISOString();
+        const traceId = idFor("trace", batch.call_id);
+        const env = this._config.environment
+            ? { environment: this._config.environment }
+            : {};
+        const event = (type, body) => ({
+            id: randomUUID(),
+            timestamp: now,
+            type,
+            body: { ...body, ...env },
+        });
+        const events = [
+            event("trace-create", {
+                id: traceId,
+                name: "stt-eval",
+                sessionId: batch.call_id,
+                tags: ["stt-eval", batch.models.primary, batch.models.shadow],
+                metadata: {
+                    call_id: batch.call_id,
+                    room: batch.room ?? null,
+                    models: batch.models,
+                    final: report?.final ?? batch.final === true,
+                    batches: report?.batches,
+                    segments: report?.segments,
+                    speakers: report?.speakers,
+                },
+            }),
+        ];
+        for (const segment of batch.segments) {
+            const start = segment.start_time ?? segment.received_at;
+            events.push(event("event-create", {
+                id: idFor("segment", `${batch.call_id}\u0000${segment.id}`),
+                traceId,
+                name: `${segment.source}:${segment.participant_name || segment.participant_identity}`,
+                startTime: isoFromSeconds(start),
+                output: segment.text,
+                metadata: {
+                    segment_id: segment.id,
+                    source: segment.source,
+                    model: segment.model,
+                    participant_identity: segment.participant_identity,
+                    participant_name: segment.participant_name ?? null,
+                    language: segment.language ?? null,
+                    start_time: segment.start_time ?? null,
+                    end_time: segment.end_time ?? null,
+                    received_at: segment.received_at,
+                },
+            }));
+        }
+        if (report) {
+            const score = (key, name, value, extra = {}) => {
+                if (value === null) {
+                    return;
+                }
+                events.push(event("score-create", {
+                    id: idFor("score", `${batch.call_id}\u0000${key}`),
+                    traceId,
+                    name,
+                    value,
+                    dataType: "NUMERIC",
+                    ...extra,
+                }));
+            };
+            score("overall", "stt_disagreement", report.overall.disagreement);
+            score("overall-phonetic", "stt_phonetic_disagreement", report.overall.phonetic_disagreement);
+            for (const speaker of report.speakers_compared) {
+                const who = {
+                    comment: speaker.participant_name,
+                    metadata: {
+                        participant_identity: speaker.participant_identity,
+                        primary: speaker.primary,
+                        shadow: speaker.shadow,
+                        method: speaker.method,
+                    },
+                };
+                score(`speaker\u0000${speaker.participant_identity}`, "stt_speaker_disagreement", speaker.disagreement, who);
+                score(`speaker-phonetic\u0000${speaker.participant_identity}`, "stt_speaker_phonetic_disagreement", speaker.phonetic_disagreement, who);
+            }
+        }
+        return events;
+    }
+    async _send(callId, events) {
+        const auth = Buffer.from(`${this._config.publicKey}:${this._config.secretKey}`).toString("base64");
+        for (let i = 0; i < events.length; i += EVENTS_PER_REQUEST) {
+            try {
+                const response = await fetch(`${this._config.baseUrl}/api/public/ingestion`, {
+                    method: "POST",
+                    headers: {
+                        authorization: `Basic ${auth}`,
+                        "content-type": "application/json",
+                    },
+                    body: JSON.stringify({
+                        batch: events.slice(i, i + EVENTS_PER_REQUEST),
+                    }),
+                    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                });
+                // 207 carries per-event results; anything in `errors` was refused.
+                const result = (await response.json().catch(() => ({})));
+                const refused = Array.isArray(result.errors) ? result.errors.length : 0;
+                if (!response.ok || refused > 0) {
+                    logger.warn("[stt-eval] Langfuse export incomplete", {
+                        callId,
+                        status: response.status,
+                        refused,
+                    });
+                }
+            }
+            catch (error) {
+                logger.warn("[stt-eval] Langfuse export failed", {
+                    callId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
+}
+/** A stable 32-hex id, so a resend upserts the same Langfuse object. */
+function idFor(kind, key) {
+    return createHash("sha256")
+        .update(`${kind}\u0000${key}`)
+        .digest("hex")
+        .slice(0, 32);
+}
+function isoFromSeconds(seconds) {
+    return new Date(seconds * 1000).toISOString();
+}

package/dist/voice/eval/sttEvalStore.d.ts

@@ -0,0 +1,27 @@
+import type { ServerSTTEvalBatchRequest, ServerSTTEvalBatchResponse, ServerSTTEvalCallSummary, ServerSTTEvalOptions, ServerSTTEvalReport } from "../../types/index.js";
+export declare class STTEvalStore {
+    private readonly _dir;
+    private readonly _maxCalls;
+    private readonly _maxSegments;
+    private readonly _calls;
+    /** Per call: the tail of its accept queue, so batches apply and append in arrival order. */
+    private readonly _queues;
+    private _ready;
+    private readonly _langfuse;
+    constructor(options?: ServerSTTEvalOptions);
+    accept(batch: ServerSTTEvalBatchRequest): Promise<ServerSTTEvalBatchResponse>;
+    list(): Promise<ServerSTTEvalCallSummary[]>;
+    report(callId: string, includeSegments?: boolean): Promise<ServerSTTEvalReport | undefined>;
+    private _reportOf;
+    /** Runs `task` after every earlier task for the same call has settled. */
+    private _serial;
+    private _create;
+    private _apply;
+    private _callFor;
+    private _evict;
+    private _fileFor;
+    /** Replays the directory once; every caller awaits the same load. */
+    private _load;
+    private _loadDir;
+    private _replay;
+}