smoltalk 0.10.0 → 0.11.0

package/dist/speech/baseSpeechClient.d.ts

@@ -1,4 +1,5 @@
 import type { ModelDataBlob } from "../modelData.js";
+import type { SmolConfig } from "../types.js";
 import { Result } from "../types/result.js";
 import type { SpeechResult } from "../speech.js";
 export type SpeechClientConfig = {
@@ -7,12 +8,16 @@ export type SpeechClientConfig = {
     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"];
     voice: string;
     modelData?: ModelDataBlob;
     /** Output format; provider-specific vocabulary (OpenAI: mp3/opus/aac/flac/wav/pcm). */
     format?: string;
     speed?: number;
     metadata?: Record<string, unknown>;
+    /** Abort the in-flight provider request when this signal fires. */
+    abortSignal?: AbortSignal;
 };
 /**
  * Shared TTS behavior, mirroring BaseClient for text generation: the public

package/dist/speech/baseSpeechClient.js

@@ -1,5 +1,5 @@
 import { getModelForProvider, isTextToSpeechModel, } from "../models.js";
-import { calculateSpeechCost } from "../model.js";
+import { Model, calculateSpeechCost } from "../model.js";
 import { failure } from "../types/result.js";
 import { redactSecret } from "../util/redact.js";
 import { getLogger } from "../util/logger.js";
@@ -49,6 +49,10 @@ export class BaseSpeechClient {
         this.config = config;
     }
     async speak(text) {
+        // 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);
             if (model !== undefined && !isTextToSpeechModel(model)) {
@@ -75,17 +79,32 @@ export class BaseSpeechClient {
                         `Supported: ${model.formats.join(", ")}.`);
                 }
             }
+            // Re-check after preflight validation: the signal may have fired during
+            // it, and we must not dispatch a request once cancelled.
+            if (this.config.abortSignal?.aborted) {
+                return failure("Request was aborted");
+            }
             const result = await this._speak(text);
             if (!result.success) {
                 return result;
             }
-            const cost = calculateSpeechCost(model, [...text].length);
+            let cost = calculateSpeechCost(model, [...text].length);
+            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 = "speak() failed";
             if (err instanceof Error) {
                 msg = err.message;

package/dist/speech/google.d.ts

@@ -0,0 +1,6 @@
+import { Result } from "../types/result.js";
+import { BaseSpeechClient } from "./baseSpeechClient.js";
+import type { SpeechResult } from "../speech.js";
+export declare class GoogleSpeechClient extends BaseSpeechClient {
+    protected _speak(text: string): Promise<Result<SpeechResult>>;
+}

package/dist/speech/google.js

@@ -0,0 +1,54 @@
+import { GoogleGenAI } from "@google/genai";
+import { success, failure } from "../types/result.js";
+import { pcmToWav } from "../util/audioMime.js";
+import { normalizeGoogleAudioUsage } from "../util/googleAudioUsage.js";
+import { BaseSpeechClient } from "./baseSpeechClient.js";
+const GEMINI_PCM = { sampleRateHz: 24000, sampleFormat: "s16le", channels: 1 };
+export class GoogleSpeechClient extends BaseSpeechClient {
+    // No try/catch: BaseSpeechClient.speak() is the exception boundary.
+    async _speak(text) {
+        if (!this.config.apiKey) {
+            return failure("No Google API key provided. Set apiKey.google or GEMINI_API_KEY.");
+        }
+        // Gemini controls pacing via prompt style, not a numeric speed parameter.
+        if (this.config.speed !== undefined) {
+            return failure("Gemini TTS does not support the 'speed' option; control pacing via the prompt text.");
+        }
+        const format = this.config.format ?? "pcm";
+        if (format !== "pcm" && format !== "wav") {
+            return failure(`Gemini TTS only produces raw PCM. Supported formats: pcm (default), wav. Got "${format}".`);
+        }
+        const ai = new GoogleGenAI({ apiKey: this.config.apiKey });
+        const res = await ai.models.generateContent({
+            model: this.config.model,
+            contents: [{ role: "user", parts: [{ text }] }],
+            config: {
+                responseModalities: ["AUDIO"],
+                speechConfig: {
+                    voiceConfig: { prebuiltVoiceConfig: { voiceName: this.config.voice } },
+                },
+                // Client-only cancellation: tears down the request, but Gemini still
+                // bills server-side work.
+                abortSignal: this.config.abortSignal,
+            },
+        });
+        const dataB64 = res.candidates?.[0]?.content?.parts?.find((part) => part.inlineData?.data !== undefined)?.inlineData?.data;
+        if (!dataB64) {
+            return failure("Gemini returned no audio data.");
+        }
+        const pcm = new Uint8Array(Buffer.from(dataB64, "base64"));
+        let audio = pcm;
+        let mimeType = "application/octet-stream";
+        if (format === "wav") {
+            audio = pcmToWav(pcm, { sampleRateHz: 24000, channels: 1, bitsPerSample: 16 });
+            mimeType = "audio/wav";
+        }
+        const usage = normalizeGoogleAudioUsage(res.usageMetadata, "output");
+        const result = { audio, mimeType, raw: res };
+        if (format === "pcm")
+            result.pcm = GEMINI_PCM;
+        if (usage)
+            result.usage = usage;
+        return success(result);
+    }
+}

package/dist/speech/groq.d.ts

@@ -0,0 +1,11 @@
+import OpenAI from "openai";
+import { OpenAISpeechClient } from "./openai.js";
+import type { SpeakFormat } from "../util/audioMime.js";
+/**
+ * Groq exposes OpenAI-compatible Orpheus TTS and supports WAV only.
+ */
+export declare class GroqSpeechClient extends OpenAISpeechClient {
+    protected makeClient(): OpenAI;
+    protected defaultFormat(): SpeakFormat;
+    protected noKeyMessage(): string;
+}

package/dist/speech/groq.js

@@ -0,0 +1,19 @@
+import OpenAI from "openai";
+import { OpenAISpeechClient } from "./openai.js";
+/**
+ * Groq exposes OpenAI-compatible Orpheus TTS and supports WAV only.
+ */
+export class GroqSpeechClient extends OpenAISpeechClient {
+    makeClient() {
+        return new OpenAI({
+            apiKey: this.config.apiKey,
+            baseURL: "https://api.groq.com/openai/v1",
+        });
+    }
+    defaultFormat() {
+        return "wav";
+    }
+    noKeyMessage() {
+        return "No Groq API key provided. Set apiKey.groq or GROQ_API_KEY.";
+    }
+}

package/dist/speech/openai.d.ts

@@ -1,6 +1,14 @@
+import OpenAI from "openai";
 import { Result } from "../types/result.js";
+import { type SpeakFormat } from "../util/audioMime.js";
 import { BaseSpeechClient } from "./baseSpeechClient.js";
 import type { SpeechResult } from "../speech.js";
 export declare class OpenAISpeechClient extends BaseSpeechClient {
+    /** Build the OpenAI SDK client. Subclasses override to point at a compatible base URL. */
+    protected makeClient(): OpenAI;
+    /** Provider default used when the declarative call omits format. */
+    protected defaultFormat(): SpeakFormat;
+    /** Provider-specific diagnostic when no API key is resolved. Subclasses override. */
+    protected noKeyMessage(): string;
     protected _speak(text: string): Promise<Result<SpeechResult>>;
 }

package/dist/speech/openai.js

@@ -3,22 +3,34 @@ import { success, failure } from "../types/result.js";
 import { SPEECH_FORMAT_TO_MIME, isSpeakFormat, } from "../util/audioMime.js";
 import { BaseSpeechClient } from "./baseSpeechClient.js";
 export class OpenAISpeechClient extends BaseSpeechClient {
+    /** Build the OpenAI SDK client. Subclasses override to point at a compatible base URL. */
+    makeClient() {
+        return new OpenAI({ apiKey: this.config.apiKey });
+    }
+    /** Provider default used when the declarative call omits format. */
+    defaultFormat() {
+        return "mp3";
+    }
+    /** 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: BaseSpeechClient.speak() is the single
     // redacting/logging exception boundary.
     async _speak(text) {
         if (!this.config.apiKey) {
-            return failure("No OpenAI API key provided. Set apiKey.openAi or OPENAI_API_KEY.");
+            return failure(this.noKeyMessage());
         }
         // The shared contract carries format as a plain string; narrow to OpenAI's
         // closed union at runtime before indexing the MIME table.
-        const requestedFormat = this.config.format ?? "mp3";
+        const requestedFormat = this.config.format ?? this.defaultFormat();
         if (!isSpeakFormat(requestedFormat)) {
             return failure(`Format "${requestedFormat}" is not a supported OpenAI speech format. ` +
                 `Supported: ${Object.keys(SPEECH_FORMAT_TO_MIME).join(", ")}.`);
         }
         const format = requestedFormat;
         const mimeType = SPEECH_FORMAT_TO_MIME[format];
-        const client = new OpenAI({ apiKey: this.config.apiKey });
+        const client = this.makeClient();
         const params = {
             model: this.config.model,
             voice: this.config.voice,
@@ -28,7 +40,7 @@ export class OpenAISpeechClient extends BaseSpeechClient {
         if (this.config.speed !== undefined) {
             params.speed = this.config.speed;
         }
-        const res = await client.audio.speech.create(params);
+        const res = await client.audio.speech.create(params, { signal: this.config.abortSignal });
         const audio = new Uint8Array(await res.arrayBuffer());
         const result = { audio, mimeType };
         if (format === "pcm") {

package/dist/speech/openaiCompat.d.ts

@@ -0,0 +1,13 @@
+import OpenAI from "openai";
+import { OpenAISpeechClient } from "./openai.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 declare class OpenAiCompatSpeechClient extends OpenAISpeechClient {
+    protected makeClient(): OpenAI;
+    protected noKeyMessage(): string;
+}

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

@@ -2,6 +2,7 @@ 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;
@@ -9,9 +10,12 @@ export type SpeakOptions = {
     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;
@@ -23,6 +27,7 @@ export type SpeechResult = {
     audio: Uint8Array;
     mimeType: string;
     pcm?: PcmAudioMetadata;
+    usage?: TokenUsage;
     cost?: CostEstimate;
     raw?: unknown;
 };

package/dist/speech.js

@@ -3,9 +3,15 @@ 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);

package/dist/transcription/baseTranscriptionClient.d.ts

@@ -1,4 +1,5 @@
 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";
@@ -9,12 +10,16 @@ export type TranscriptionClientConfig = {
     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:

package/dist/transcription/baseTranscriptionClient.js

@@ -1,5 +1,5 @@
-import { getModelForProvider, isSpeechToTextModel, } from "../models.js";
-import { calculateTranscriptionCost } from "../model.js";
+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";
@@ -7,24 +7,24 @@ 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(model) {
-    const modelMaxBytes = model.maxBytes;
+function transcriptionConstraintError(modelName, c) {
+    const modelMaxBytes = c.maxBytes;
     if (modelMaxBytes !== undefined &&
         (typeof modelMaxBytes !== "number" || !Number.isFinite(modelMaxBytes) || modelMaxBytes <= 0)) {
-        return `Model "${model.modelName}" has an invalid maxBytes value.`;
+        return `Model "${modelName}" has an invalid maxBytes value.`;
     }
-    const supportedMimeTypes = model.supportedMimeTypes;
+    const supportedMimeTypes = c.supportedMimeTypes;
     if (supportedMimeTypes !== undefined &&
         (!Array.isArray(supportedMimeTypes) ||
             !supportedMimeTypes.every((mime) => typeof mime === "string"))) {
-        return `Model "${model.modelName}" has invalid supportedMimeTypes.`;
+        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, model) {
+function resolveTranscriptionMaxBytes(callerMaxBytes, modelMaxBytes) {
     if (callerMaxBytes !== undefined &&
         (!Number.isFinite(callerMaxBytes) || callerMaxBytes <= 0)) {
         return failure(`maxBytes must be a positive finite number (got ${callerMaxBytes}).`);
@@ -33,8 +33,8 @@ function resolveTranscriptionMaxBytes(callerMaxBytes, model) {
     if (callerMaxBytes !== undefined) {
         limits.push(callerMaxBytes);
     }
-    if (model?.maxBytes !== undefined) {
-        limits.push(model.maxBytes);
+    if (modelMaxBytes !== undefined) {
+        limits.push(modelMaxBytes);
     }
     if (limits.length === 0) {
         return success(DEFAULT_TRANSCRIBE_BYTES);
@@ -53,18 +53,29 @@ export class BaseTranscriptionClient {
         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);
-            if (model !== undefined && !isSpeechToTextModel(model)) {
-                return failure(`Model "${this.config.model}" is not a speech-to-text model.`);
+            // 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(model);
+                const constraintError = transcriptionConstraintError(this.config.model, constraints);
                 if (constraintError !== null) {
                     return failure(constraintError);
                 }
             }
-            const effectiveLimit = resolveTranscriptionMaxBytes(this.config.maxBytes, model);
+            const effectiveLimit = resolveTranscriptionMaxBytes(this.config.maxBytes, constraints.maxBytes);
             if (!effectiveLimit.success) {
                 return effectiveLimit;
             }
@@ -76,25 +87,40 @@ export class BaseTranscriptionClient {
                 return failure(`Failed to load audio for transcription: ${err.message}`);
             }
             const mimeType = loaded.mimeType ?? "application/octet-stream";
-            if (model !== undefined && model.supportedMimeTypes !== undefined) {
+            if (constraints.supportedMimeTypes !== undefined) {
                 const audioFormat = audioFormatForMime(mimeType);
                 const normalizedMime = audioFormat?.mimeType ?? canonicalizeMime(mimeType);
-                if (!model.supportedMimeTypes.includes(normalizedMime)) {
+                if (!constraints.supportedMimeTypes.includes(normalizedMime)) {
                     return failure(`Unsupported audio type "${mimeType}" for model "${this.config.model}". ` +
-                        `Supported: ${model.supportedMimeTypes.join(", ")}.`);
+                        `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;
             }
-            const cost = calculateTranscriptionCost(model, result.value.durationSeconds);
+            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;

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

@@ -1,6 +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

@@ -3,16 +3,24 @@ 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("No OpenAI API key provided. Set apiKey.openAi or OPENAI_API_KEY.");
+            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 = new OpenAI({ apiKey: this.config.apiKey });
+        const client = this.makeClient();
         const file = await toFile(data, filename, { type: mimeType });
         const granularities = [];
         if (this.config.timestampGranularity) {
@@ -32,7 +40,7 @@ export class OpenAITranscriptionClient extends BaseTranscriptionClient {
         if (granularities.length > 0) {
             requestBody.timestamp_granularities = granularities;
         }
-        const res = (await client.audio.transcriptions.create(requestBody));
+        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;

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;
+}