@juspay/neurolink 12.48.1 → 12.49.0

package/dist/cli/factories/commandFactory.d.ts

@@ -300,6 +300,11 @@ export declare class CLICommandFactory {
             type: "string";
             description: string;
         };
+        sttDiarize: {
+            type: "boolean";
+            default: boolean;
+            description: string;
+        };
         inputAudio: {
             type: "string";
             description: string;
@@ -1223,6 +1228,11 @@ export declare const commonOptions: {
         type: "string";
         description: string;
     };
+    sttDiarize: {
+        type: "boolean";
+        default: boolean;
+        description: string;
+    };
     inputAudio: {
         type: "string";
         description: string;

package/dist/cli/factories/commandFactory.js

@@ -435,6 +435,11 @@ export class CLICommandFactory {
             type: "string",
             description: "Audio language code for STT (e.g., en-US)",
         },
+        sttDiarize: {
+            type: "boolean",
+            default: false,
+            description: "Label speakers in the transcript (providers that diarize: deepgram, google-stt, elevenlabs-stt, a diarizing OpenAI-compatible endpoint)",
+        },
         inputAudio: {
             type: "string",
             description: "Path to audio file for STT transcription",
@@ -818,6 +823,7 @@ export class CLICommandFactory {
             // --input-audio without --stt get an actionable error from yargs
             // instead of silently skipping STT.
             .implies("sttProvider", "stt")
+            .implies("sttDiarize", "stt")
             .implies("inputAudio", "stt"));
     }
     // Helper method to process CLI images with smart auto-detection
@@ -980,6 +986,7 @@ export class CLICommandFactory {
             stt: argv.stt,
             sttProvider: argv.sttProvider,
             sttLanguage: argv.sttLanguage,
+            sttDiarize: argv.sttDiarize,
             inputAudio: argv.inputAudio,
             // Video generation options (Veo 3.1)
             outputMode: argv.outputMode,
@@ -2850,6 +2857,9 @@ export class CLICommandFactory {
                         enabled: true,
                         provider: enhancedOptions.sttProvider,
                         language: enhancedOptions.sttLanguage,
+                        ...(enhancedOptions.sttDiarize
+                            ? { speakerDiarization: true }
+                            : {}),
                         ...(inputAudioBuffer && { audio: inputAudioBuffer }),
                         ...(inputAudioFormat && { format: inputAudioFormat }),
                     }
@@ -3117,6 +3127,9 @@ export class CLICommandFactory {
                         enabled: true,
                         provider: enhancedOptions.sttProvider,
                         language: enhancedOptions.sttLanguage,
+                        ...(enhancedOptions.sttDiarize
+                            ? { speakerDiarization: true }
+                            : {}),
                         ...(streamSttAudio && { audio: streamSttAudio }),
                         ...(streamSttFormat && { format: streamSttFormat }),
                     };

package/dist/cli/parser.js

@@ -31,6 +31,7 @@ import { proxyExposeCommand } from "./commands/proxyExpose.js";
 import { proxyReplayCommand } from "./commands/proxyReplay.js";
 import { EvaluateCommandFactory } from "./commands/evaluate.js";
 import { DecideCommandFactory } from "./commands/decide.js";
+import { TranscribeCommandFactory } from "./commands/transcribe.js";
 import { TaskCommandFactory } from "./commands/task.js";
 import { AutoresearchCommandFactory } from "./commands/autoresearch.js";
 import { voiceServerCommand } from "./commands/voiceServer.js";
@@ -172,6 +173,8 @@ export function initializeCliParser() {
         .command(CLICommandFactory.createStreamCommand())
         // Decide Command - typed, calibrated judgements (no free text)
         .command(DecideCommandFactory.createDecideCommand())
+        // Transcribe Command - audio in, text out (the transcribe inference type)
+        .command(TranscribeCommandFactory.createTranscribeCommand())
         // Batch Processing Command - Using CLICommandFactory
         .command(CLICommandFactory.createBatchCommand())
         // Provider Command Group - Using CLICommandFactory

package/dist/cli/utils/serverUtils.d.ts

@@ -2,6 +2,22 @@
  * Server Utilities for NeuroLink CLI
  * Shared utility functions for server management commands (serve.ts and server.ts)
  */
+import type { MiddlewareDefinition } from "../../types/index.js";
+export declare const DEFAULT_SERVER_PORT = 3000;
+/** Comma-separated API keys; when set, every route except health needs one. */
+export declare const SERVER_API_KEY_ENV = "NEUROLINK_SERVER_API_KEY";
+/**
+ * Resolve the listen port: --port, then the config file, then the PORT
+ * environment variable (what container platforms set), then 3000.
+ */
+export declare function resolveServerPort(cliPort?: number, filePort?: number): number;
+export declare function readServerApiKeys(): string[];
+/**
+ * Require one of `apiKeys` as `Authorization: Bearer <key>` or `X-API-Key`.
+ * Health probes stay open so orchestrators can reach them, and the dev
+ * playground header cannot bypass a key the operator configured.
+ */
+export declare function createServerApiKeyMiddleware(apiKeys: string[], basePath: string): MiddlewareDefinition;
 /**
  * Get the base directory for NeuroLink state files
  * @returns Path to ~/.neurolink directory
@@ -29,6 +45,18 @@ export declare function ensureStateDir(): void;
  * @returns true if the process is running, false otherwise
  */
 export declare function isProcessRunning(pid: number): boolean;
+/**
+ * Whether a saved server state belongs to a different, still-running process.
+ * A state naming our own PID is stale: a restarted container is PID 1 again
+ * and would otherwise refuse to start, believing it is already running.
+ */
+export declare function isOtherServerRunning(pid: number): boolean;
+/**
+ * Remove this process's state file however it exits. A graceful stop can end
+ * the process before its signal handler gets to clean up (once the listener
+ * closes, the event loop may drain), so this runs from the "exit" event.
+ */
+export declare function clearStateOnExit(clearState: () => void): void;
 /**
  * Format a duration in milliseconds to a human-readable uptime string
  * @param ms - Duration in milliseconds

package/dist/cli/utils/serverUtils.js

@@ -2,9 +2,64 @@
  * Server Utilities for NeuroLink CLI
  * Shared utility functions for server management commands (serve.ts and server.ts)
  */
+import { timingSafeEqual } from "crypto";
 import fs from "fs";
 import os from "os";
 import path from "path";
+import { ConfigurationError } from "../../server/errors.js";
+import { createAuthMiddleware } from "../../server/middleware/auth.js";
+// ============================================
+// Listen Address & Access Control
+// ============================================
+export const DEFAULT_SERVER_PORT = 3000;
+/** Comma-separated API keys; when set, every route except health needs one. */
+export const SERVER_API_KEY_ENV = "NEUROLINK_SERVER_API_KEY";
+/**
+ * Resolve the listen port: --port, then the config file, then the PORT
+ * environment variable (what container platforms set), then 3000.
+ */
+export function resolveServerPort(cliPort, filePort) {
+    const envPort = process.env.PORT?.trim();
+    const port = cliPort ?? filePort ?? (envPort ? Number(envPort) : DEFAULT_SERVER_PORT);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new ConfigurationError(`Invalid port "${cliPort ?? filePort ?? envPort}": expected an integer between 0 and 65535`);
+    }
+    return port;
+}
+export function readServerApiKeys() {
+    return (process.env[SERVER_API_KEY_ENV] ?? "")
+        .split(",")
+        .map((key) => key.trim())
+        .filter((key) => key.length > 0);
+}
+/**
+ * Constant-time for equal lengths; a length mismatch returns early, which
+ * reveals only the key's length, never its content.
+ */
+const matchesKey = (key, token) => key.length === token.length && timingSafeEqual(key, token);
+/**
+ * Require one of `apiKeys` as `Authorization: Bearer <key>` or `X-API-Key`.
+ * Health probes stay open so orchestrators can reach them, and the dev
+ * playground header cannot bypass a key the operator configured.
+ */
+export function createServerApiKeyMiddleware(apiKeys, basePath) {
+    const keys = apiKeys.map((key) => Buffer.from(key, "utf8"));
+    return createAuthMiddleware({
+        type: "custom",
+        extractToken: (ctx) => {
+            const bearer = /^Bearer\s+(.+)$/i.exec(ctx.headers["authorization"] ?? "");
+            return bearer?.[1] ?? ctx.headers["x-api-key"] ?? null;
+        },
+        validate: async (token) => {
+            const candidate = Buffer.from(token, "utf8");
+            return keys.some((key) => matchesKey(key, candidate))
+                ? { id: "api-key" }
+                : null;
+        },
+        skipPaths: [`${basePath.replace(/\/+$/, "")}/health`],
+        skipDevPlayground: false,
+    });
+}
 // ============================================
 // State Directory Management
 // ============================================
@@ -56,6 +111,22 @@ export function isProcessRunning(pid) {
         return code === "EPERM";
     }
 }
+/**
+ * Whether a saved server state belongs to a different, still-running process.
+ * A state naming our own PID is stale: a restarted container is PID 1 again
+ * and would otherwise refuse to start, believing it is already running.
+ */
+export function isOtherServerRunning(pid) {
+    return pid !== process.pid && isProcessRunning(pid);
+}
+/**
+ * Remove this process's state file however it exits. A graceful stop can end
+ * the process before its signal handler gets to clean up (once the listener
+ * closes, the event loop may drain), so this runs from the "exit" event.
+ */
+export function clearStateOnExit(clearState) {
+    process.once("exit", clearState);
+}
 // ============================================
 // Time Formatting
 // ============================================

package/dist/factories/mediaHandlerCatalog.js

@@ -1,3 +1,4 @@
+import { STT_PROVIDER_DESCRIPTORS } from "./sttDescriptors.js";
 /**
  * Static catalog of every shipped media-handler provider, across all six
  * ecosystems (TTS, STT, Realtime, Video, Avatar, Music). Pure data — no
@@ -20,15 +21,16 @@ export const MEDIA_HANDLER_CATALOG = [
     { kind: "tts", name: "sixtydb" },
     { kind: "tts", name: "cartesia" },
     // --- STT ---
-    { kind: "stt", name: "whisper", aliases: ["openai-stt"] },
-    { kind: "stt", name: "deepgram" },
-    { kind: "stt", name: "google-stt" },
-    { kind: "stt", name: "azure-stt" },
-    // "elevenlabs" is reused across kinds on purpose — TTS primary, STT alias —
-    // the same way "vertex" is a TTS alias and the Video primary. Each kind has
-    // its own registry, so `stt: { provider: "elevenlabs" }` and
-    // `tts: { provider: "elevenlabs" }` resolve to different handlers.
-    { kind: "stt", name: "elevenlabs-stt", aliases: ["scribe", "elevenlabs"] },
+    // Derived from STT_PROVIDER_DESCRIPTORS (names, aliases and precedence
+    // order) so the catalog and the descriptors cannot drift. "elevenlabs" is
+    // reused across kinds on purpose — TTS primary, STT alias — the same way
+    // "vertex" is a TTS alias and the Video primary; each kind has its own
+    // registry.
+    ...STT_PROVIDER_DESCRIPTORS.map((descriptor) => ({
+        kind: "stt",
+        name: descriptor.name,
+        ...(descriptor.aliases ? { aliases: descriptor.aliases } : {}),
+    })),
     // --- Realtime ---
     { kind: "realtime", name: "openai-realtime" },
     { kind: "realtime", name: "gemini-live" },

package/dist/factories/sttDescriptors.d.ts

@@ -0,0 +1,63 @@
+import type { STTCredentials, STTEndpointConfig, STTProviderDescriptor } from "../types/index.js";
+/**
+ * Every shipped speech-to-text provider — the single source of truth for its
+ * name, aliases, credentials slice, env vars and capabilities. Pure data, like
+ * `PROVIDER_DESCRIPTORS` for text providers; the handler classes are wired to
+ * these names in `voice/index.ts`, and `MEDIA_HANDLER_CATALOG`'s STT rows are
+ * derived from this list so the two cannot drift.
+ *
+ * **Order is precedence.** `resolveDefaultSTTProvider()` returns the first
+ * entry that is configured, so reordering changes which engine every
+ * `transcribe()` / `generate({ stt })` without an explicit provider uses.
+ * `whistle` is last on purpose: it runs on this machine and needs no key, so
+ * it is what a caller gets when nothing else is configured.
+ */
+export declare const STT_PROVIDER_DESCRIPTORS: readonly STTProviderDescriptor[];
+/** The provider used when nothing else is configured. */
+export declare const DEFAULT_LOCAL_STT_PROVIDER = "whistle";
+/**
+ * Canonical descriptor name for a provider name or alias (case-insensitive),
+ * or `undefined` when it is not a shipped STT provider — a caller may still
+ * have registered a handler of its own under that name.
+ */
+export declare function resolveSTTProviderName(name: string | undefined): string | undefined;
+/** The descriptor for a provider name or alias, if it is a shipped one. */
+export declare function getSTTProviderDescriptor(name: string): STTProviderDescriptor | undefined;
+/**
+ * Whether a provider can run with these credentials and the environment. The
+ * local engine needs no configuration and always counts. Unknown names are
+ * not configured.
+ */
+export declare function isSTTProviderConfigured(name: string, credentials?: STTCredentials): boolean;
+/** Configured providers, in precedence order (the local engine last). */
+export declare function listConfiguredSTTProviders(credentials?: STTCredentials): string[];
+/**
+ * Named OpenAI-compatible endpoints: `credentials.stt.endpoints` over the
+ * `NEUROLINK_STT_ENDPOINTS` JSON object. Keys are lowercased; one that
+ * collides with a shipped provider name or alias is dropped with a warning,
+ * as is an entry without a `baseURL`. Malformed JSON is reported once and
+ * ignored.
+ */
+export declare function resolveSTTEndpoints(credentials?: STTCredentials): Record<string, STTEndpointConfig>;
+/**
+ * The per-call endpoints alone (`credentials.stt.endpoints`), validated
+ * exactly as the env map is: names lower-cased, a name that collides with a
+ * shipped provider or alias dropped, an entry without a `baseURL` dropped.
+ * Every per-call lookup goes through this so a request can neither replace a
+ * shipped handler nor build an endpoint the env form would have refused.
+ */
+export declare function resolveCallSTTEndpoints(credentials?: STTCredentials): Record<string, STTEndpointConfig>;
+/**
+ * The provider a transcription without an explicit one goes to:
+ * `NEUROLINK_STT_PROVIDER` when it names a known provider or alias, else the
+ * first configured provider in descriptor order, else the built-in local
+ * engine. Never throws, never returns an empty string.
+ */
+export declare function resolveDefaultSTTProvider(credentials?: STTCredentials): string;
+/**
+ * The variables that would configure each hosted STT provider, one clause per
+ * provider in precedence order, e.g. "OPENAI_STT_API_KEY or OPENAI_API_KEY for
+ * whisper, or DEEPGRAM_API_KEY for deepgram". Derived from the descriptors so
+ * a new provider appears in every "nothing is configured" message.
+ */
+export declare function describeSTTProviderKeys(): string;

package/dist/factories/sttDescriptors.js

@@ -0,0 +1,286 @@
+import { logger } from "../utils/logger.js";
+/**
+ * Every shipped speech-to-text provider — the single source of truth for its
+ * name, aliases, credentials slice, env vars and capabilities. Pure data, like
+ * `PROVIDER_DESCRIPTORS` for text providers; the handler classes are wired to
+ * these names in `voice/index.ts`, and `MEDIA_HANDLER_CATALOG`'s STT rows are
+ * derived from this list so the two cannot drift.
+ *
+ * **Order is precedence.** `resolveDefaultSTTProvider()` returns the first
+ * entry that is configured, so reordering changes which engine every
+ * `transcribe()` / `generate({ stt })` without an explicit provider uses.
+ * `whistle` is last on purpose: it runs on this machine and needs no key, so
+ * it is what a caller gets when nothing else is configured.
+ */
+export const STT_PROVIDER_DESCRIPTORS = [
+    {
+        name: "whisper",
+        aliases: ["openai-stt", "openai-compatible"],
+        label: "OpenAI-compatible /audio/transcriptions",
+        credentialsKey: "whisper",
+        envVars: ["OPENAI_STT_API_KEY", "OPENAI_API_KEY"],
+        baseUrlEnv: "OPENAI_STT_BASE_URL",
+        defaultModel: "whisper-1",
+        capabilities: {
+            streaming: "chunked",
+            // OpenAI's own endpoint does not diarize; compatible servers may, and
+            // the handler only sends the switch to those.
+            diarization: true,
+            languageDetect: true,
+            prompt: true,
+            wordTimestamps: true,
+            local: false,
+        },
+    },
+    {
+        name: "deepgram",
+        label: "Deepgram",
+        credentialsKey: "deepgram",
+        envVars: ["DEEPGRAM_API_KEY"],
+        baseUrlEnv: "DEEPGRAM_BASE_URL",
+        defaultModel: "nova-2",
+        capabilities: {
+            streaming: "native",
+            diarization: true,
+            languageDetect: true,
+            prompt: false,
+            wordTimestamps: true,
+            local: false,
+        },
+    },
+    {
+        name: "elevenlabs-stt",
+        // "elevenlabs" is reused across kinds on purpose — TTS primary, STT
+        // alias. Each kind has its own registry, so `stt: { provider:
+        // "elevenlabs" }` and `tts: { provider: "elevenlabs" }` resolve to
+        // different handlers.
+        aliases: ["scribe", "elevenlabs"],
+        label: "ElevenLabs Scribe",
+        credentialsKey: "elevenlabs",
+        envVars: ["ELEVENLABS_API_KEY"],
+        baseUrlEnv: "ELEVENLABS_STT_BASE_URL",
+        defaultModel: "scribe_v2",
+        capabilities: {
+            streaming: "chunked",
+            diarization: true,
+            languageDetect: true,
+            prompt: false,
+            wordTimestamps: true,
+            local: false,
+        },
+    },
+    {
+        name: "google-stt",
+        label: "Google Cloud Speech-to-Text",
+        credentialsKey: "google",
+        // GoogleSTT accepts the AI Studio key aliases and a service-account file.
+        envVars: [
+            "GOOGLE_API_KEY",
+            "GOOGLE_AI_API_KEY",
+            "GEMINI_API_KEY",
+            "GOOGLE_APPLICATION_CREDENTIALS",
+        ],
+        defaultModel: "latest_long",
+        capabilities: {
+            streaming: "chunked",
+            diarization: true,
+            languageDetect: false,
+            prompt: false,
+            wordTimestamps: true,
+            local: false,
+        },
+    },
+    {
+        name: "azure-stt",
+        label: "Azure Speech",
+        credentialsKey: "azure",
+        envVars: ["AZURE_SPEECH_KEY"],
+        capabilities: {
+            streaming: "chunked",
+            diarization: false,
+            languageDetect: false,
+            prompt: false,
+            wordTimestamps: true,
+            local: false,
+        },
+    },
+    {
+        name: "whistle",
+        aliases: ["cactus-whistle", "local"],
+        label: "Whistle (built-in, local)",
+        credentialsKey: "whistle",
+        envVars: [],
+        capabilities: {
+            streaming: "chunked",
+            diarization: false,
+            languageDetect: true,
+            prompt: false,
+            wordTimestamps: true,
+            local: true,
+            languages: ["en", "de", "fr", "es", "it", "nl", "pl"],
+        },
+    },
+];
+/** The provider used when nothing else is configured. */
+export const DEFAULT_LOCAL_STT_PROVIDER = "whistle";
+const STT_DESCRIPTORS_BY_NAME = new Map(STT_PROVIDER_DESCRIPTORS.map((d) => [d.name, d]));
+/** Lower-cased name or alias → canonical descriptor name. */
+const STT_ALIAS_INDEX = new Map(STT_PROVIDER_DESCRIPTORS.flatMap((d) => [
+    [d.name.toLowerCase(), d.name],
+    ...(d.aliases ?? []).map((alias) => [alias.toLowerCase(), d.name]),
+]));
+/**
+ * Canonical descriptor name for a provider name or alias (case-insensitive),
+ * or `undefined` when it is not a shipped STT provider — a caller may still
+ * have registered a handler of its own under that name.
+ */
+export function resolveSTTProviderName(name) {
+    if (!name) {
+        return undefined;
+    }
+    return STT_ALIAS_INDEX.get(name.trim().toLowerCase());
+}
+/** The descriptor for a provider name or alias, if it is a shipped one. */
+export function getSTTProviderDescriptor(name) {
+    const canonical = resolveSTTProviderName(name);
+    return canonical ? STT_DESCRIPTORS_BY_NAME.get(canonical) : undefined;
+}
+function hasValue(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/**
+ * Whether a credentials slice configures its provider: a key, a service
+ * account file, or — for the OpenAI-compatible handler, whose self-hosted
+ * servers often need no key — a base URL.
+ */
+function sliceConfigures(descriptor, credentials) {
+    const slice = credentials?.[descriptor.credentialsKey];
+    if (!slice) {
+        return false;
+    }
+    if (hasValue(slice.apiKey) || hasValue(slice.credentialsPath)) {
+        return true;
+    }
+    return descriptor.credentialsKey === "whisper" && hasValue(slice.baseURL);
+}
+/**
+ * Whether a provider can run with these credentials and the environment. The
+ * local engine needs no configuration and always counts. Unknown names are
+ * not configured.
+ */
+export function isSTTProviderConfigured(name, credentials) {
+    const descriptor = getSTTProviderDescriptor(name);
+    if (!descriptor) {
+        return false;
+    }
+    if (descriptor.capabilities.local) {
+        return true;
+    }
+    if (sliceConfigures(descriptor, credentials)) {
+        return true;
+    }
+    return descriptor.envVars.some((envVar) => hasValue(process.env[envVar]));
+}
+/** Configured providers, in precedence order (the local engine last). */
+export function listConfiguredSTTProviders(credentials) {
+    return [
+        ...STT_PROVIDER_DESCRIPTORS.filter((d) => isSTTProviderConfigured(d.name, credentials)).map((d) => d.name),
+        ...Object.keys(resolveSTTEndpoints(credentials)),
+    ];
+}
+/**
+ * Named OpenAI-compatible endpoints: `credentials.stt.endpoints` over the
+ * `NEUROLINK_STT_ENDPOINTS` JSON object. Keys are lowercased; one that
+ * collides with a shipped provider name or alias is dropped with a warning,
+ * as is an entry without a `baseURL`. Malformed JSON is reported once and
+ * ignored.
+ */
+export function resolveSTTEndpoints(credentials) {
+    const out = {};
+    const raw = process.env.NEUROLINK_STT_ENDPOINTS?.trim();
+    if (raw) {
+        try {
+            Object.assign(out, validateSTTEndpoints("NEUROLINK_STT_ENDPOINTS", JSON.parse(raw)));
+        }
+        catch (error) {
+            logger.warn(`[STT] NEUROLINK_STT_ENDPOINTS is not valid JSON; ignoring it (${error instanceof Error ? error.message : String(error)})`);
+        }
+    }
+    Object.assign(out, resolveCallSTTEndpoints(credentials));
+    return out;
+}
+/**
+ * The per-call endpoints alone (`credentials.stt.endpoints`), validated
+ * exactly as the env map is: names lower-cased, a name that collides with a
+ * shipped provider or alias dropped, an entry without a `baseURL` dropped.
+ * Every per-call lookup goes through this so a request can neither replace a
+ * shipped handler nor build an endpoint the env form would have refused.
+ */
+export function resolveCallSTTEndpoints(credentials) {
+    return validateSTTEndpoints("credentials.stt.endpoints", credentials?.endpoints);
+}
+function validateSTTEndpoints(source, entries) {
+    const out = {};
+    if (typeof entries !== "object" || entries === null) {
+        return out;
+    }
+    for (const [rawName, cfg] of Object.entries(entries)) {
+        const name = rawName.trim().toLowerCase();
+        if (!name) {
+            continue;
+        }
+        if (STT_ALIAS_INDEX.has(name)) {
+            logger.warn(`[STT] ${source}: endpoint "${rawName}" collides with a shipped provider name; ignoring it`);
+            continue;
+        }
+        const baseURL = typeof cfg === "object" && cfg !== null && "baseURL" in cfg
+            ? cfg.baseURL
+            : undefined;
+        if (typeof baseURL !== "string" || !baseURL.trim()) {
+            logger.warn(`[STT] ${source}: endpoint "${rawName}" has no baseURL; ignoring it`);
+            continue;
+        }
+        const c = cfg;
+        out[name] = {
+            baseURL: baseURL.trim(),
+            ...(typeof c.apiKey === "string" ? { apiKey: c.apiKey } : {}),
+            ...(typeof c.model === "string" ? { model: c.model } : {}),
+            ...(typeof c.timeoutMs === "number" ? { timeoutMs: c.timeoutMs } : {}),
+        };
+    }
+    return out;
+}
+/**
+ * The provider a transcription without an explicit one goes to:
+ * `NEUROLINK_STT_PROVIDER` when it names a known provider or alias, else the
+ * first configured provider in descriptor order, else the built-in local
+ * engine. Never throws, never returns an empty string.
+ */
+export function resolveDefaultSTTProvider(credentials) {
+    const fromEnv = process.env.NEUROLINK_STT_PROVIDER?.trim();
+    if (fromEnv) {
+        const canonical = resolveSTTProviderName(fromEnv);
+        if (canonical) {
+            return canonical;
+        }
+        const endpoint = fromEnv.toLowerCase();
+        if (endpoint in resolveSTTEndpoints(credentials)) {
+            return endpoint;
+        }
+        logger.warn(`[STT] NEUROLINK_STT_PROVIDER="${fromEnv}" is not a known STT provider; ` +
+            `ignoring it. Known: ${STT_PROVIDER_DESCRIPTORS.map((d) => d.name).join(", ")}`);
+    }
+    const configured = STT_PROVIDER_DESCRIPTORS.find((d) => !d.capabilities.local && isSTTProviderConfigured(d.name, credentials));
+    return configured?.name ?? DEFAULT_LOCAL_STT_PROVIDER;
+}
+/**
+ * The variables that would configure each hosted STT provider, one clause per
+ * provider in precedence order, e.g. "OPENAI_STT_API_KEY or OPENAI_API_KEY for
+ * whisper, or DEEPGRAM_API_KEY for deepgram". Derived from the descriptors so
+ * a new provider appears in every "nothing is configured" message.
+ */
+export function describeSTTProviderKeys() {
+    return STT_PROVIDER_DESCRIPTORS.filter((d) => d.envVars.length > 0)
+        .map((d) => `${d.envVars.join(" or ")} for ${d.name}`)
+        .join(", or ");
+}

package/dist/index.d.ts

@@ -70,7 +70,10 @@ export { AVATAR_ERROR_CODES, AvatarError } from "./utils/avatarProcessor.js";
 export { MusicProcessor } from "./utils/musicProcessor.js";
 export { MUSIC_ERROR_CODES, MusicError } from "./utils/musicProcessor.js";
 export { STTProcessor } from "./utils/sttProcessor.js";
-export { AzureTTS, AzureTTSHandler, CartesiaTTS, CartesiaTTSHandler, ElevenLabsTTS, ElevenLabsTTSHandler, FishAudioTTS, FishAudioTTSHandler, SixtyDBTTS, SixtyDBTTSHandler, GoogleTTSHandler, OpenAITTS, OpenAITTSHandler, AzureSTT, AzureSTTHandler, DeepgramSTT, DeepgramSTTHandler, ElevenLabsSTT, ElevenLabsSTTHandler, GoogleSTT, GoogleSTTHandler, OpenAISTT, OpenAISTTHandler, WhisperSTT, WhisperSTTHandler, BaseRealtimeHandler, GeminiLive, GeminiLiveHandler, OpenAIRealtime, OpenAIRealtimeHandler, RealtimeProcessor, RealtimeError, STTError, VoiceError, registerDefaultRealtimeHandlers, registerDefaultSTTHandlers, registerDefaultTTSHandlers, } from "./voice/index.js";
+export { describeSTTProviderKeys, isSTTProviderConfigured, resolveDefaultSTTProvider, STT_PROVIDER_DESCRIPTORS, } from "./factories/sttDescriptors.js";
+export { buildSpeakerTurns, listSpeakers } from "./utils/speakerTurns.js";
+export { correctTranscript } from "./voice/correction/index.js";
+export { AzureTTS, AzureTTSHandler, CartesiaTTS, CartesiaTTSHandler, ElevenLabsTTS, ElevenLabsTTSHandler, FishAudioTTS, FishAudioTTSHandler, SixtyDBTTS, SixtyDBTTSHandler, GoogleTTSHandler, OpenAITTS, OpenAITTSHandler, AzureSTT, AzureSTTHandler, DeepgramSTT, DeepgramSTTHandler, ElevenLabsSTT, ElevenLabsSTTHandler, GoogleSTT, GoogleSTTHandler, OpenAISTT, OpenAISTTHandler, WhisperSTT, WhisperSTTHandler, WhistleSTT, WhistleSTTHandler, BaseRealtimeHandler, GeminiLive, GeminiLiveHandler, OpenAIRealtime, OpenAIRealtimeHandler, RealtimeProcessor, RealtimeError, STTError, VoiceError, registerDefaultRealtimeHandlers, registerDefaultSTTHandlers, registerDefaultTTSHandlers, } from "./voice/index.js";
 export { BeatovenMusic, BeatovenMusicHandler, ElevenLabsMusic, ElevenLabsMusicHandler, LyriaMusic, LyriaMusicHandler, registerDefaultMusicHandlers, ReplicateMusic, ReplicateMusicHandler, } from "./music/index.js";
 export { DIDAvatar, DIDAvatarHandler, HeyGenAvatar, HeyGenAvatarHandler, registerDefaultAvatarHandlers, ReplicateAvatar, ReplicateAvatarHandler, } from "./avatar/index.js";
 export { isVertexVideoConfigured, KlingVideoHandler, registerDefaultVideoHandlers, ReplicateVideoHandler, RunwayVideoHandler, VertexVideoHandler, } from "./adapters/video/index.js";

package/dist/index.js

@@ -120,6 +120,12 @@ export { MusicProcessor } from "./utils/musicProcessor.js";
 export { MUSIC_ERROR_CODES, MusicError } from "./utils/musicProcessor.js";
 // STT / Realtime processors (registries for speech-to-text + live voice)
 export { STTProcessor } from "./utils/sttProcessor.js";
+// The `transcribe` inference type: STT provider descriptors (precedence
+// order = default-provider order), provider-neutral speaker turns, and the
+// transcript correction layer `neurolink.transcribe()` runs.
+export { describeSTTProviderKeys, isSTTProviderConfigured, resolveDefaultSTTProvider, STT_PROVIDER_DESCRIPTORS, } from "./factories/sttDescriptors.js";
+export { buildSpeakerTurns, listSpeakers } from "./utils/speakerTurns.js";
+export { correctTranscript } from "./voice/correction/index.js";
 // STT_ERROR_CODES is surfaced via the types barrel (export * from "./types/index.js")
 // STTError is re-exported below from the voice/index.js barrel
 // ============================================================================
@@ -134,7 +140,7 @@ export {
 // TTS
 AzureTTS, AzureTTSHandler, CartesiaTTS, CartesiaTTSHandler, ElevenLabsTTS, ElevenLabsTTSHandler, FishAudioTTS, FishAudioTTSHandler, SixtyDBTTS, SixtyDBTTSHandler, GoogleTTSHandler, OpenAITTS, OpenAITTSHandler, 
 // STT
-AzureSTT, AzureSTTHandler, DeepgramSTT, DeepgramSTTHandler, ElevenLabsSTT, ElevenLabsSTTHandler, GoogleSTT, GoogleSTTHandler, OpenAISTT, OpenAISTTHandler, WhisperSTT, WhisperSTTHandler, 
+AzureSTT, AzureSTTHandler, DeepgramSTT, DeepgramSTTHandler, ElevenLabsSTT, ElevenLabsSTTHandler, GoogleSTT, GoogleSTTHandler, OpenAISTT, OpenAISTTHandler, WhisperSTT, WhisperSTTHandler, WhistleSTT, WhistleSTTHandler, 
 // Realtime
 BaseRealtimeHandler, GeminiLive, GeminiLiveHandler, OpenAIRealtime, OpenAIRealtimeHandler, RealtimeProcessor, 
 // Voice error classes (RealtimeError + STTError + VoiceError)