smoltalk 0.9.0 → 0.10.1

package/dist/speech/openaiCompat.js

@@ -0,0 +1,22 @@
+import OpenAI from "openai";
+import { OpenAISpeechClient } from "./openai.js";
+import { resolveBaseUrl } from "../util/provider.js";
+/**
+ * Generic OpenAI-compatible speech (TTS) client. Point it at any provider
+ * exposing an OpenAI-shaped /audio/speech endpoint via
+ * `config.baseUrl.openAiCompat` (or OPENAI_COMPAT_BASE_URL) and
+ * `config.apiKey.openAiCompat` (or OPENAI_COMPAT_API_KEY). Mirrors the chat
+ * `SmolOpenAiCompat` client. Inherits OpenAI's `mp3` default format.
+ */
+export class OpenAiCompatSpeechClient extends OpenAISpeechClient {
+    makeClient() {
+        const baseURL = resolveBaseUrl("openai-compat", { baseUrl: this.config.baseUrl });
+        if (!baseURL) {
+            throw new Error("openai-compat: base URL required (config.baseUrl.openAiCompat or OPENAI_COMPAT_BASE_URL).");
+        }
+        return new OpenAI({ apiKey: this.config.apiKey, baseURL });
+    }
+    noKeyMessage() {
+        return "No API key provided. Set apiKey.openAiCompat or OPENAI_COMPAT_API_KEY.";
+    }
+}

package/dist/speech.d.ts

@@ -0,0 +1,45 @@
+import type { ModelDataBlob } from "./modelData.js";
+import type { SmolConfig } from "./types.js";
+import { Result } from "./types/result.js";
+import { CostEstimate } from "./types/costEstimate.js";
+import { TokenUsage } from "./types/tokenUsage.js";
+import { BaseSpeechClient, SpeechClientConfig } from "./speech/baseSpeechClient.js";
+export type SpeakOptions = {
+    model: string;
+    voice: string;
+    provider?: string;
+    modelData?: ModelDataBlob;
+    apiKey?: SmolConfig["apiKey"];
+    baseUrl?: SmolConfig["baseUrl"];
+    format?: string;
+    speed?: number;
+    metadata?: Record<string, unknown>;
+    /** Abort the in-flight provider request when this signal fires. */
+    abortSignal?: AbortSignal;
+};
+export type PcmAudioMetadata = {
+    sampleRateHz: number;
+    /** Sample representation, e.g. "s16le"; provider-specific. */
+    sampleFormat: string;
+    channels: number;
+};
+export type SpeechResult = {
+    audio: Uint8Array;
+    mimeType: string;
+    pcm?: PcmAudioMetadata;
+    usage?: TokenUsage;
+    cost?: CostEstimate;
+    raw?: unknown;
+};
+export type SpeechClientClass = new (config: SpeechClientConfig) => BaseSpeechClient;
+export declare function registerSpeechProvider(name: string, cls: SpeechClientClass): void;
+/** Test-only: clear all registered custom providers so registrations don't leak across tests. */
+export declare function _resetForTests(): void;
+/**
+ * Resolve provider + API key and instantiate the matching speech client for
+ * the declarative speak() operation. Never throws: a custom client class's
+ * constructor can throw, and this internal factory's catch redacts the
+ * resolved key so a constructor error cannot leak through the public wrapper.
+ */
+export declare function getSpeechClient(opts: SpeakOptions): Result<BaseSpeechClient>;
+export declare function speak(text: string, opts: SpeakOptions): Promise<Result<SpeechResult>>;

package/dist/speech.js

@@ -0,0 +1,63 @@
+import { success, failure } from "./types/result.js";
+import { redactSecret } from "./util/redact.js";
+import { getLogger } from "./util/logger.js";
+import { resolveProvider, resolveApiKey } from "./util/provider.js";
+import { OpenAISpeechClient } from "./speech/openai.js";
+import { GroqSpeechClient } from "./speech/groq.js";
+import { GoogleSpeechClient } from "./speech/google.js";
+import { OpenAiCompatSpeechClient } from "./speech/openaiCompat.js";
+// Checked before the user registry so a registered "openai" can't hijack the built-in.
+const builtinClients = Object.create(null);
+builtinClients["openai"] = OpenAISpeechClient;
+builtinClients["groq"] = GroqSpeechClient;
+builtinClients["google"] = GoogleSpeechClient;
+builtinClients["openai-compat"] = OpenAiCompatSpeechClient;
+// Null-prototype so provider names like "toString"/"__proto__" can't collide
+// with Object.prototype or pollute the registry.
+const registered = Object.create(null);
+export function registerSpeechProvider(name, cls) {
+    registered[name] = cls;
+}
+/** Test-only: clear all registered custom providers so registrations don't leak across tests. */
+export function _resetForTests() {
+    for (const key of Object.keys(registered)) {
+        delete registered[key];
+    }
+}
+/**
+ * Resolve provider + API key and instantiate the matching speech client for
+ * the declarative speak() operation. Never throws: a custom client class's
+ * constructor can throw, and this internal factory's catch redacts the
+ * resolved key so a constructor error cannot leak through the public wrapper.
+ */
+export function getSpeechClient(opts) {
+    let apiKeyForRedaction = "";
+    try {
+        const provider = resolveProvider(opts.model, opts.provider, opts.modelData);
+        const ClientClass = builtinClients[provider] ?? registered[provider];
+        if (ClientClass === undefined) {
+            return failure(`Provider "${provider}" has no speech API. Register one with registerSpeechProvider(name, ClientClass).`);
+        }
+        const apiKey = resolveApiKey(provider, opts) ?? "";
+        apiKeyForRedaction = apiKey;
+        const { apiKey: _callerKeys, ...clientOpts } = opts;
+        const config = { ...clientOpts, provider, apiKey };
+        return success(new ClientClass(config));
+    }
+    catch (err) {
+        let msg = "getSpeechClient() failed";
+        if (err instanceof Error) {
+            msg = err.message;
+        }
+        const redacted = redactSecret(msg, apiKeyForRedaction);
+        getLogger().error("getSpeechClient() failed:", redacted);
+        return failure(redacted);
+    }
+}
+export async function speak(text, opts) {
+    const client = getSpeechClient(opts);
+    if (!client.success) {
+        return client;
+    }
+    return client.value.speak(text);
+}

package/dist/transcription/baseTranscriptionClient.d.ts

@@ -0,0 +1,36 @@
+import type { ModelDataBlob } from "../modelData.js";
+import type { SmolConfig } from "../types.js";
+import { Result } from "../types/result.js";
+import { BlobRef } from "../util/blobRef.js";
+import type { TranscriptionResult } from "../transcription.js";
+export declare const DEFAULT_TRANSCRIBE_BYTES: number;
+export type TranscriptionClientConfig = {
+    model: string;
+    /** Resolved provider name. */
+    provider: string;
+    /** Resolved API key; empty string when none was found. */
+    apiKey: string;
+    /** Base-URL map (for OpenAI-compatible providers); read via resolveBaseUrl. */
+    baseUrl?: SmolConfig["baseUrl"];
+    modelData?: ModelDataBlob;
+    language?: string;
+    prompt?: string;
+    timestampGranularity?: "segment" | "word";
+    maxBytes?: number;
+    metadata?: Record<string, unknown>;
+    /** Abort the in-flight provider request when this signal fires. */
+    abortSignal?: AbortSignal;
+};
+/**
+ * Shared transcription behavior, mirroring BaseClient for text generation:
+ * the public transcribe() template method owns blob loading, model-data-driven
+ * validation, cost, and the single redacting/logging exception boundary.
+ * Subclasses implement only _transcribe(): SDK call + response mapping.
+ */
+export declare abstract class BaseTranscriptionClient {
+    protected config: TranscriptionClientConfig;
+    constructor(config: TranscriptionClientConfig);
+    transcribe(source: BlobRef): Promise<Result<TranscriptionResult>>;
+    /** Provider hook: SDK call + response mapping only; validation and cost live in the base. */
+    protected abstract _transcribe(data: Uint8Array, mimeType: string): Promise<Result<TranscriptionResult>>;
+}

package/dist/transcription/baseTranscriptionClient.js

@@ -0,0 +1,133 @@
+import { getModelForProvider, isSpeechToTextModel, modelSupportsInputModality, audioInputConstraints, } from "../models.js";
+import { Model, calculateTranscriptionCost } from "../model.js";
+import { success, failure } from "../types/result.js";
+import { loadBlob } from "../util/blobRef.js";
+import { audioFormatForMime, canonicalizeMime } from "../util/mime.js";
+import { redactSecret } from "../util/redact.js";
+import { getLogger } from "../util/logger.js";
+export const DEFAULT_TRANSCRIBE_BYTES = 25 * 1024 * 1024;
+/** Validate the declarative STT constraint block once before consuming it. */
+function transcriptionConstraintError(modelName, c) {
+    const modelMaxBytes = c.maxBytes;
+    if (modelMaxBytes !== undefined &&
+        (typeof modelMaxBytes !== "number" || !Number.isFinite(modelMaxBytes) || modelMaxBytes <= 0)) {
+        return `Model "${modelName}" has an invalid maxBytes value.`;
+    }
+    const supportedMimeTypes = c.supportedMimeTypes;
+    if (supportedMimeTypes !== undefined &&
+        (!Array.isArray(supportedMimeTypes) ||
+            !supportedMimeTypes.every((mime) => typeof mime === "string"))) {
+        return `Model "${modelName}" has invalid supportedMimeTypes.`;
+    }
+    return null;
+}
+// The caller's maxBytes is a safety limit; the model's maxBytes is the
+// provider's hard cap. Take the smaller of whichever are present so a caller
+// can tighten the limit but never bypass the provider cap.
+function resolveTranscriptionMaxBytes(callerMaxBytes, modelMaxBytes) {
+    if (callerMaxBytes !== undefined &&
+        (!Number.isFinite(callerMaxBytes) || callerMaxBytes <= 0)) {
+        return failure(`maxBytes must be a positive finite number (got ${callerMaxBytes}).`);
+    }
+    const limits = [];
+    if (callerMaxBytes !== undefined) {
+        limits.push(callerMaxBytes);
+    }
+    if (modelMaxBytes !== undefined) {
+        limits.push(modelMaxBytes);
+    }
+    if (limits.length === 0) {
+        return success(DEFAULT_TRANSCRIBE_BYTES);
+    }
+    return success(Math.min(...limits));
+}
+/**
+ * Shared transcription behavior, mirroring BaseClient for text generation:
+ * the public transcribe() template method owns blob loading, model-data-driven
+ * validation, cost, and the single redacting/logging exception boundary.
+ * Subclasses implement only _transcribe(): SDK call + response mapping.
+ */
+export class BaseTranscriptionClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async transcribe(source) {
+        // Already-aborted signal: stop before doing any paid work.
+        if (this.config.abortSignal?.aborted) {
+            return failure("Request was aborted");
+        }
+        try {
+            const model = getModelForProvider(this.config.provider, this.config.model, this.config.modelData);
+            // A model is a valid transcription target if it is a dedicated STT model,
+            // or a multimodal text model that accepts audio input (e.g. Gemini). An
+            // unknown model (undefined) flows through — the provider is authority.
+            const acceptsAudio = model === undefined ||
+                isSpeechToTextModel(model) ||
+                modelSupportsInputModality(this.config.model, "audio", this.config.modelData, this.config.provider) === true;
+            if (!acceptsAudio) {
+                return failure(`Model "${this.config.model}" cannot accept audio input (not a transcription model).`);
+            }
+            const constraints = model !== undefined ? audioInputConstraints(model) : {};
+            if (model !== undefined) {
+                const constraintError = transcriptionConstraintError(this.config.model, constraints);
+                if (constraintError !== null) {
+                    return failure(constraintError);
+                }
+            }
+            const effectiveLimit = resolveTranscriptionMaxBytes(this.config.maxBytes, constraints.maxBytes);
+            if (!effectiveLimit.success) {
+                return effectiveLimit;
+            }
+            let loaded;
+            try {
+                loaded = await loadBlob(source, { maxBytes: effectiveLimit.value });
+            }
+            catch (err) {
+                return failure(`Failed to load audio for transcription: ${err.message}`);
+            }
+            const mimeType = loaded.mimeType ?? "application/octet-stream";
+            if (constraints.supportedMimeTypes !== undefined) {
+                const audioFormat = audioFormatForMime(mimeType);
+                const normalizedMime = audioFormat?.mimeType ?? canonicalizeMime(mimeType);
+                if (!constraints.supportedMimeTypes.includes(normalizedMime)) {
+                    return failure(`Unsupported audio type "${mimeType}" for model "${this.config.model}". ` +
+                        `Supported: ${constraints.supportedMimeTypes.join(", ")}.`);
+                }
+            }
+            // Re-check after the async preflight (blob load / MIME validation): the
+            // signal may have fired during it, and we must not dispatch a request.
+            if (this.config.abortSignal?.aborted) {
+                return failure("Request was aborted");
+            }
+            const result = await this._transcribe(loaded.data, mimeType);
+            if (!result.success) {
+                return result;
+            }
+            let cost = calculateTranscriptionCost(model, result.value.durationSeconds);
+            if (cost === undefined && result.value.usage !== undefined) {
+                // Token-billed providers (Gemini) price through the shared cost engine.
+                cost =
+                    new Model(this.config.model, this.config.provider, this.config.modelData).calculateCost(result.value.usage) ?? undefined;
+            }
+            if (cost !== undefined) {
+                result.value.cost = cost;
+            }
+            return result;
+        }
+        catch (err) {
+            // Caller-initiated cancellation surfaces as a distinguishable failure
+            // (matching the chat path), not a redacted provider error.
+            if (this.config.abortSignal?.aborted) {
+                return failure("Request was aborted");
+            }
+            let msg = "transcribe() failed";
+            if (err instanceof Error) {
+                msg = err.message;
+            }
+            const redacted = redactSecret(msg, this.config.apiKey);
+            getLogger().error("transcribe() provider failed:", redacted);
+            return failure(redacted);
+        }
+    }
+}

package/dist/transcription/google.d.ts

@@ -0,0 +1,6 @@
+import { Result } from "../types/result.js";
+import { BaseTranscriptionClient } from "./baseTranscriptionClient.js";
+import type { TranscriptionResult } from "../transcription.js";
+export declare class GoogleTranscriptionClient extends BaseTranscriptionClient {
+    protected _transcribe(data: Uint8Array, mimeType: string): Promise<Result<TranscriptionResult>>;
+}

package/dist/transcription/google.js

@@ -0,0 +1,56 @@
+import { GoogleGenAI } from "@google/genai";
+import { success, failure } from "../types/result.js";
+import { BaseTranscriptionClient } from "./baseTranscriptionClient.js";
+import { normalizeGoogleAudioUsage } from "../util/googleAudioUsage.js";
+import { googleAudioWireMime } from "../util/audioMime.js";
+// Gemini's inline request cap is 20 MB for the *entire* request (audio bytes,
+// base64 expansion, prompt, and SDK envelope), not the raw file alone.
+const GOOGLE_INLINE_REQUEST_MAX_BYTES = 20_000_000;
+export class GoogleTranscriptionClient extends BaseTranscriptionClient {
+    // No try/catch: BaseTranscriptionClient.transcribe() is the exception boundary.
+    async _transcribe(data, mimeType) {
+        if (!this.config.apiKey) {
+            return failure("No Google API key provided. Set apiKey.google or GEMINI_API_KEY.");
+        }
+        if (this.config.timestampGranularity !== undefined) {
+            return failure("Gemini transcription does not support timestampGranularity.");
+        }
+        let instruction = "Transcribe the following audio verbatim. Output only the transcript text, with no commentary.";
+        if (this.config.language) {
+            instruction += ` The audio is in ${this.config.language}.`;
+        }
+        if (this.config.prompt) {
+            instruction += ` ${this.config.prompt}`;
+        }
+        const base64 = Buffer.from(data).toString("base64");
+        const request = {
+            model: this.config.model,
+            contents: [{
+                    role: "user",
+                    parts: [
+                        { inlineData: { mimeType: googleAudioWireMime(mimeType), data: base64 } },
+                        { text: instruction },
+                    ],
+                }],
+        };
+        if (Buffer.byteLength(JSON.stringify(request), "utf8") > GOOGLE_INLINE_REQUEST_MAX_BYTES) {
+            return failure("Audio and instructions exceed Gemini's 20 MB inline request limit; use a smaller source.");
+        }
+        const ai = new GoogleGenAI({ apiKey: this.config.apiKey });
+        // Signal is passed at call time (not part of `request`) so the encoded-size
+        // check above measures only the payload. Gemini's abortSignal is client-only:
+        // it tears down the request but does not stop server-side billing.
+        const res = await ai.models.generateContent({
+            ...request,
+            config: { abortSignal: this.config.abortSignal },
+        });
+        const usage = normalizeGoogleAudioUsage(res.usageMetadata, "input");
+        const result = {
+            text: res.text ?? "",
+            raw: res,
+        };
+        if (usage)
+            result.usage = usage;
+        return success(result);
+    }
+}

package/dist/transcription/groq.d.ts

@@ -0,0 +1,10 @@
+import OpenAI from "openai";
+import { OpenAITranscriptionClient } from "./openai.js";
+/**
+ * Groq exposes an OpenAI-compatible /audio/transcriptions endpoint (Whisper
+ * large-v3 / large-v3-turbo). Everything but the base URL is inherited.
+ */
+export declare class GroqTranscriptionClient extends OpenAITranscriptionClient {
+    protected makeClient(): OpenAI;
+    protected noKeyMessage(): string;
+}

package/dist/transcription/groq.js

@@ -0,0 +1,17 @@
+import OpenAI from "openai";
+import { OpenAITranscriptionClient } from "./openai.js";
+/**
+ * Groq exposes an OpenAI-compatible /audio/transcriptions endpoint (Whisper
+ * large-v3 / large-v3-turbo). Everything but the base URL is inherited.
+ */
+export class GroqTranscriptionClient extends OpenAITranscriptionClient {
+    makeClient() {
+        return new OpenAI({
+            apiKey: this.config.apiKey,
+            baseURL: "https://api.groq.com/openai/v1",
+        });
+    }
+    noKeyMessage() {
+        return "No Groq API key provided. Set apiKey.groq or GROQ_API_KEY.";
+    }
+}

package/dist/transcription/openai.d.ts

@@ -0,0 +1,11 @@
+import OpenAI from "openai";
+import { Result } from "../types/result.js";
+import { BaseTranscriptionClient } from "./baseTranscriptionClient.js";
+import type { TranscriptionResult } from "../transcription.js";
+export declare class OpenAITranscriptionClient extends BaseTranscriptionClient {
+    /** Build the OpenAI SDK client. Subclasses override to point at a compatible base URL. */
+    protected makeClient(): OpenAI;
+    /** Provider-specific diagnostic when no API key is resolved. Subclasses override. */
+    protected noKeyMessage(): string;
+    protected _transcribe(data: Uint8Array, mimeType: string): Promise<Result<TranscriptionResult>>;
+}

package/dist/transcription/openai.js

@@ -0,0 +1,67 @@
+import OpenAI, { toFile } from "openai";
+import { success, failure } from "../types/result.js";
+import { transcriptionAudioType } from "../util/audioMime.js";
+import { BaseTranscriptionClient } from "./baseTranscriptionClient.js";
+export class OpenAITranscriptionClient extends BaseTranscriptionClient {
+    /** Build the OpenAI SDK client. Subclasses override to point at a compatible base URL. */
+    makeClient() {
+        return new OpenAI({ apiKey: this.config.apiKey });
+    }
+    /** Provider-specific diagnostic when no API key is resolved. Subclasses override. */
+    noKeyMessage() {
+        return "No OpenAI API key provided. Set apiKey.openAi or OPENAI_API_KEY.";
+    }
+    // No try/catch here: BaseTranscriptionClient.transcribe() is the single
+    // redacting/logging exception boundary.
+    async _transcribe(data, mimeType) {
+        if (!this.config.apiKey) {
+            return failure(this.noKeyMessage());
+        }
+        // Filename is an OpenAI upload detail, not part of the provider-neutral
+        // operation contract. Derive the synthetic name from the normalized MIME.
+        const filename = transcriptionAudioType(mimeType)?.filename ?? "audio.bin";
+        const client = this.makeClient();
+        const file = await toFile(data, filename, { type: mimeType });
+        const granularities = [];
+        if (this.config.timestampGranularity) {
+            granularities.push(this.config.timestampGranularity);
+        }
+        const requestBody = {
+            file,
+            model: this.config.model,
+            response_format: "verbose_json",
+        };
+        if (this.config.language) {
+            requestBody.language = this.config.language;
+        }
+        if (this.config.prompt) {
+            requestBody.prompt = this.config.prompt;
+        }
+        if (granularities.length > 0) {
+            requestBody.timestamp_granularities = granularities;
+        }
+        const res = (await client.audio.transcriptions.create(requestBody, { signal: this.config.abortSignal }));
+        const result = { text: res.text, raw: res };
+        if (res.language) {
+            result.language = res.language;
+        }
+        if (typeof res.duration === "number") {
+            result.durationSeconds = res.duration;
+        }
+        if (Array.isArray(res.segments)) {
+            result.segments = res.segments.map((segment) => ({
+                start: segment.start,
+                end: segment.end,
+                text: segment.text,
+            }));
+        }
+        if (Array.isArray(res.words)) {
+            result.words = res.words.map((word) => ({
+                start: word.start,
+                end: word.end,
+                word: word.word,
+            }));
+        }
+        return success(result);
+    }
+}

package/dist/transcription/openaiCompat.d.ts

@@ -0,0 +1,13 @@
+import OpenAI from "openai";
+import { OpenAITranscriptionClient } from "./openai.js";
+/**
+ * Generic OpenAI-compatible transcription client. Point it at any provider
+ * exposing an OpenAI-shaped /audio/transcriptions endpoint via
+ * `config.baseUrl.openAiCompat` (or OPENAI_COMPAT_BASE_URL) and
+ * `config.apiKey.openAiCompat` (or OPENAI_COMPAT_API_KEY). Mirrors the chat
+ * `SmolOpenAiCompat` client.
+ */
+export declare class OpenAiCompatTranscriptionClient extends OpenAITranscriptionClient {
+    protected makeClient(): OpenAI;
+    protected noKeyMessage(): string;
+}

package/dist/transcription/openaiCompat.js

@@ -0,0 +1,22 @@
+import OpenAI from "openai";
+import { OpenAITranscriptionClient } from "./openai.js";
+import { resolveBaseUrl } from "../util/provider.js";
+/**
+ * Generic OpenAI-compatible transcription client. Point it at any provider
+ * exposing an OpenAI-shaped /audio/transcriptions endpoint via
+ * `config.baseUrl.openAiCompat` (or OPENAI_COMPAT_BASE_URL) and
+ * `config.apiKey.openAiCompat` (or OPENAI_COMPAT_API_KEY). Mirrors the chat
+ * `SmolOpenAiCompat` client.
+ */
+export class OpenAiCompatTranscriptionClient extends OpenAITranscriptionClient {
+    makeClient() {
+        const baseURL = resolveBaseUrl("openai-compat", { baseUrl: this.config.baseUrl });
+        if (!baseURL) {
+            throw new Error("openai-compat: base URL required (config.baseUrl.openAiCompat or OPENAI_COMPAT_BASE_URL).");
+        }
+        return new OpenAI({ apiKey: this.config.apiKey, baseURL });
+    }
+    noKeyMessage() {
+        return "No API key provided. Set apiKey.openAiCompat or OPENAI_COMPAT_API_KEY.";
+    }
+}

package/dist/transcription.d.ts

@@ -0,0 +1,54 @@
+import type { ModelDataBlob } from "./modelData.js";
+import type { SmolConfig } from "./types.js";
+import { Result } from "./types/result.js";
+import { TokenUsage } from "./types/tokenUsage.js";
+import { CostEstimate } from "./types/costEstimate.js";
+import { BlobRef } from "./util/blobRef.js";
+import { BaseTranscriptionClient, TranscriptionClientConfig } from "./transcription/baseTranscriptionClient.js";
+export { DEFAULT_TRANSCRIBE_BYTES } from "./transcription/baseTranscriptionClient.js";
+export type TranscribeOptions = {
+    model: string;
+    provider?: string;
+    modelData?: ModelDataBlob;
+    apiKey?: SmolConfig["apiKey"];
+    baseUrl?: SmolConfig["baseUrl"];
+    language?: string;
+    prompt?: string;
+    timestampGranularity?: "segment" | "word";
+    maxBytes?: number;
+    metadata?: Record<string, unknown>;
+    /** Abort the in-flight provider request when this signal fires. */
+    abortSignal?: AbortSignal;
+};
+export type TranscriptionSegment = {
+    start: number;
+    end: number;
+    text: string;
+};
+export type TranscriptionWord = {
+    start: number;
+    end: number;
+    word: string;
+};
+export type TranscriptionResult = {
+    text: string;
+    language?: string;
+    durationSeconds?: number;
+    segments?: TranscriptionSegment[];
+    words?: TranscriptionWord[];
+    usage?: TokenUsage;
+    cost?: CostEstimate;
+    raw?: unknown;
+};
+export type TranscriptionClientClass = new (config: TranscriptionClientConfig) => BaseTranscriptionClient;
+export declare function registerTranscriptionProvider(name: string, cls: TranscriptionClientClass): void;
+/** Test-only: clear all registered custom providers so registrations don't leak across tests. */
+export declare function _resetForTests(): void;
+/**
+ * Resolve provider + API key and instantiate the matching transcription client
+ * for the declarative transcribe() operation. Never throws: a custom client
+ * class's constructor can throw, and this internal factory's catch redacts the
+ * resolved key so a constructor error cannot leak through the public wrapper.
+ */
+export declare function getTranscriptionClient(opts: TranscribeOptions): Result<BaseTranscriptionClient>;
+export declare function transcribe(source: BlobRef, opts: TranscribeOptions): Promise<Result<TranscriptionResult>>;

package/dist/transcription.js

@@ -0,0 +1,64 @@
+import { success, failure } from "./types/result.js";
+import { redactSecret } from "./util/redact.js";
+import { getLogger } from "./util/logger.js";
+import { resolveProvider, resolveApiKey } from "./util/provider.js";
+import { OpenAITranscriptionClient } from "./transcription/openai.js";
+import { GroqTranscriptionClient } from "./transcription/groq.js";
+import { GoogleTranscriptionClient } from "./transcription/google.js";
+import { OpenAiCompatTranscriptionClient } from "./transcription/openaiCompat.js";
+export { DEFAULT_TRANSCRIBE_BYTES } from "./transcription/baseTranscriptionClient.js";
+// Checked before the user registry so a registered "openai" can't hijack the built-in.
+const builtinClients = Object.create(null);
+builtinClients["openai"] = OpenAITranscriptionClient;
+builtinClients["groq"] = GroqTranscriptionClient;
+builtinClients["google"] = GoogleTranscriptionClient;
+builtinClients["openai-compat"] = OpenAiCompatTranscriptionClient;
+// Null-prototype so provider names like "toString"/"__proto__" can't collide
+// with Object.prototype or pollute the registry.
+const registered = Object.create(null);
+export function registerTranscriptionProvider(name, cls) {
+    registered[name] = cls;
+}
+/** Test-only: clear all registered custom providers so registrations don't leak across tests. */
+export function _resetForTests() {
+    for (const key of Object.keys(registered)) {
+        delete registered[key];
+    }
+}
+/**
+ * Resolve provider + API key and instantiate the matching transcription client
+ * for the declarative transcribe() operation. Never throws: a custom client
+ * class's constructor can throw, and this internal factory's catch redacts the
+ * resolved key so a constructor error cannot leak through the public wrapper.
+ */
+export function getTranscriptionClient(opts) {
+    let apiKeyForRedaction = "";
+    try {
+        const provider = resolveProvider(opts.model, opts.provider, opts.modelData);
+        const ClientClass = builtinClients[provider] ?? registered[provider];
+        if (ClientClass === undefined) {
+            return failure(`Provider "${provider}" has no transcription API. Register one with registerTranscriptionProvider(name, ClientClass).`);
+        }
+        const apiKey = resolveApiKey(provider, opts) ?? "";
+        apiKeyForRedaction = apiKey;
+        const { apiKey: _callerKeys, ...clientOpts } = opts;
+        const config = { ...clientOpts, provider, apiKey };
+        return success(new ClientClass(config));
+    }
+    catch (err) {
+        let msg = "getTranscriptionClient() failed";
+        if (err instanceof Error) {
+            msg = err.message;
+        }
+        const redacted = redactSecret(msg, apiKeyForRedaction);
+        getLogger().error("getTranscriptionClient() failed:", redacted);
+        return failure(redacted);
+    }
+}
+export async function transcribe(source, opts) {
+    const client = getTranscriptionClient(opts);
+    if (!client.success) {
+        return client;
+    }
+    return client.value.transcribe(source);
+}

package/dist/types/tokenUsage.d.ts

@@ -4,6 +4,8 @@ export type TokenUsage = {
     outputTokens: number;
     cachedInputTokens?: number;
     cacheCreationInputTokens?: number;
+    inputAudioTokens?: number;
+    outputAudioTokens?: number;
     totalTokens?: number;
 };
 export declare const TokenUsageSchema: z.ZodObject<{
@@ -11,6 +13,8 @@ export declare const TokenUsageSchema: z.ZodObject<{
     outputTokens: z.ZodNumber;
     cachedInputTokens: z.ZodOptional<z.ZodNumber>;
     cacheCreationInputTokens: z.ZodOptional<z.ZodNumber>;
+    inputAudioTokens: z.ZodOptional<z.ZodNumber>;
+    outputAudioTokens: z.ZodOptional<z.ZodNumber>;
     totalTokens: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export declare function addTokenUsage(_a?: TokenUsage, _b?: TokenUsage): TokenUsage;