smoltalk 0.10.0 → 0.10.1

package/README.md

@@ -509,11 +509,43 @@ the provider call. Embeddings and images are one-shot functions.
 
 ## Audio (STT/TTS)
 
-Three audio primitives, all OpenAI-only in v1. `transcribe()` (speech-to-text)
-and `speak()` (text-to-speech) are async and return `Result<T>` (never throw).
-`audioPart()` (attach audio to a chat message) is different: it's a
-synchronous plain-object constructor, not a `Result`-returning call — see
-"Audio in chat" below.
+Three audio primitives. `transcribe()` (speech-to-text) and `speak()`
+(text-to-speech) are async and return `Result<T>` (never throw). `audioPart()`
+(attach audio to a chat message) is different: it's a synchronous plain-object
+constructor, not a `Result`-returning call — see "Audio in chat" below.
+
+`transcribe()` and `speak()` support **OpenAI**, **Groq** (OpenAI-compatible
+endpoints), and **Google Gemini** (native multimodal). For any other provider
+that exposes OpenAI-shaped `/audio/*` endpoints, use the generic
+**`openai-compat`** provider with `baseUrl` (mirrors the chat client). Anthropic,
+OpenRouter, and Ollama have no audio endpoints and return a `Failure`.
+
+```ts
+// example: skip-typecheck
+// Groq STT (OpenAI-compatible; provider inferred from the model)
+await transcribe(src, { model: "whisper-large-v3" });
+
+// Gemini STT (native multimodal — a general Gemini model transcribes)
+await transcribe(src, { model: "gemini-2.5-flash", provider: "google" });
+
+// Groq TTS → WAV by default
+await speak("Hello", { model: "canopylabs/orpheus-v1-english", voice: "troy" });
+
+// Gemini TTS → raw PCM by default; format: "wav" wraps it in a WAV header.
+// Gemini has no numeric `speed` (rejected) and produces PCM/WAV only.
+await speak("Hello", {
+  model: "gemini-2.5-flash-preview-tts", voice: "Kore",
+  provider: "google", format: "wav",
+});
+
+// Any OpenAI-compatible /audio endpoint (vLLM, LiteLLM, a proxy, …)
+await transcribe(src, {
+  model: "whisper-1",
+  provider: "openai-compat",
+  apiKey: { openAiCompat: "..." },       // or OPENAI_COMPAT_API_KEY
+  baseUrl: { openAiCompat: "https://my-proxy/v1" }, // or OPENAI_COMPAT_BASE_URL
+});
+```
 
 ### Speech-to-text
 
@@ -529,7 +561,9 @@ if (result.success) {
 }
 ```
 
-`whisper-1` is the only baked-in model in v1. Options: `language`, `prompt`,
+Baked-in STT models: `whisper-1` (OpenAI) and `whisper-large-v3` /
+`whisper-large-v3-turbo` (Groq); Gemini transcribes with a general model such as
+`gemini-2.5-flash`. Options: `language`, `prompt`,
 `timestampGranularity` (`"segment"` | `"word"`), `maxBytes` (a safety limit —
 the effective cap is the smaller of your limit and the model's declared upload
 cap, 25 MB for `whisper-1`). The result carries `text` plus optional

package/dist/model.js

@@ -1,4 +1,4 @@
-import { getModel, getModelForProvider, isSpeechToTextModel, isTextModel, isTextToSpeechModel, ModelNameSchema, } from "./models.js";
+import { getModel, getModelForProvider, isSpeechToTextModel, isTextToSpeechModel, ModelNameSchema, } from "./models.js";
 import { SmolError } from "./smolError.js";
 import { round } from "./util/util.js";
 const TOKEN_COST_UNIT = 1_000_000;
@@ -32,7 +32,23 @@ export class Model {
         else {
             model = getModel(this.model, this.modelData);
         }
-        if (!model || !isTextModel(model)) {
+        if (!model) {
+            return null;
+        }
+        // This token engine prices text generation and token-billed audio models
+        // (e.g. Gemini TTS). Image and embeddings models have their own cost paths,
+        // so they are never priced here even if they carry text-token rates.
+        if (model.type === "image" || model.type === "embeddings") {
+            return null;
+        }
+        // BaseModel token-rate fields, read structurally across the model union.
+        const rates = model;
+        // Price only models that carry at least one token rate; those without
+        // (per-minute STT, per-char TTS) return null so their dedicated helpers apply.
+        if (rates.inputTokenCost === undefined &&
+            rates.outputTokenCost === undefined &&
+            rates.inputAudioTokenCost === undefined &&
+            rates.outputAudioTokenCost === undefined) {
             return null;
         }
         const cachedTokens = usage.cachedInputTokens ?? 0;
@@ -40,15 +56,15 @@ export class Model {
         // Disjoint buckets. If a discount price isn't defined for this model,
         // the tokens were still billed by the provider — charge them at the
         // full input rate so totalCost stays honest.
-        const cachedRate = model.cachedInputTokenCost ?? model.inputTokenCost ?? 0;
-        const cacheCreationRate = model.cacheCreationInputTokenCost ?? model.inputTokenCost ?? 0;
-        const inputCost = round((usage.inputTokens * (model.inputTokenCost || 0)) / TOKEN_COST_UNIT, 6);
-        const outputCost = round((usage.outputTokens * (model.outputTokenCost || 0)) / TOKEN_COST_UNIT, 6);
+        const cachedRate = rates.cachedInputTokenCost ?? rates.inputTokenCost ?? 0;
+        const cacheCreationRate = rates.cacheCreationInputTokenCost ?? rates.inputTokenCost ?? 0;
+        const inputCost = round((usage.inputTokens * (rates.inputTokenCost || 0)) / TOKEN_COST_UNIT, 6);
+        const outputCost = round((usage.outputTokens * (rates.outputTokenCost || 0)) / TOKEN_COST_UNIT, 6);
         const audioInTokens = usage.inputAudioTokens ?? 0;
         const audioOutTokens = usage.outputAudioTokens ?? 0;
         // Fall back to the text rate if no audio rate is defined so the total stays honest.
-        const audioInRate = model.inputAudioTokenCost ?? model.inputTokenCost ?? 0;
-        const audioOutRate = model.outputAudioTokenCost ?? model.outputTokenCost ?? 0;
+        const audioInRate = rates.inputAudioTokenCost ?? rates.inputTokenCost ?? 0;
+        const audioOutRate = rates.outputAudioTokenCost ?? rates.outputTokenCost ?? 0;
         const audioInCost = round((audioInTokens * audioInRate) / TOKEN_COST_UNIT, 6);
         const audioOutCost = round((audioOutTokens * audioOutRate) / TOKEN_COST_UNIT, 6);
         // Only expose cachedInputCost / cacheCreationInputCost when the model
@@ -59,7 +75,7 @@ export class Model {
         let foldedInputDollars = 0;
         if (cachedTokens > 0) {
             const dollars = (cachedTokens * cachedRate) / 1_000_000;
-            if (model.cachedInputTokenCost != null) {
+            if (rates.cachedInputTokenCost != null) {
                 cachedInputCost = round(dollars, 6);
             }
             else {
@@ -68,7 +84,7 @@ export class Model {
         }
         if (cacheCreationTokens > 0) {
             const dollars = (cacheCreationTokens * cacheCreationRate) / 1_000_000;
-            if (model.cacheCreationInputTokenCost != null) {
+            if (rates.cacheCreationInputTokenCost != null) {
                 cacheCreationInputCost = round(dollars, 6);
             }
             else {
@@ -115,7 +131,10 @@ export function calculateTranscriptionCost(model, durationSeconds) {
     if (model.perMinuteCost === undefined || durationSeconds === undefined || durationSeconds === null) {
         return undefined;
     }
-    const inputCost = round((durationSeconds / 60) * model.perMinuteCost, 6);
+    // Providers may bill a minimum duration regardless of actual length
+    // (e.g. Groq rounds up to 10s), so a shorter clip isn't understated.
+    const billedSeconds = Math.max(durationSeconds, model.minimumBillableSeconds ?? 0);
+    const inputCost = round((billedSeconds / 60) * model.perMinuteCost, 6);
     return { inputCost, outputCost: 0, totalCost: inputCost, currency: "USD" };
 }
 /** Per-code-point TTS pricing from a registry entry; same omission semantics. */

package/dist/models.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { type ModelDataBlob, type HostedTool, type HostedToolPrice } from "./modelData.js";
-export declare const providers: readonly ["ollama", "openai", "openai-responses", "anthropic", "google", "replicate", "modal", "openrouter", "deepinfra", "litellm", "openai-compat"];
+export declare const providers: readonly ["ollama", "openai", "openai-responses", "anthropic", "google", "replicate", "modal", "openrouter", "deepinfra", "litellm", "openai-compat", "groq"];
 export declare const ProviderSchema: z.ZodEnum<{
     openai: "openai";
     anthropic: "anthropic";
@@ -13,6 +13,7 @@ export declare const ProviderSchema: z.ZodEnum<{
     deepinfra: "deepinfra";
     litellm: "litellm";
     "openai-compat": "openai-compat";
+    groq: "groq";
 }>;
 export type Provider = z.infer<typeof ProviderSchema>;
 export type BaseModel = {
@@ -23,6 +24,8 @@ export type BaseModel = {
     cachedInputTokenCost?: number;
     cacheCreationInputTokenCost?: number;
     outputTokenCost?: number;
+    inputAudioTokenCost?: number;
+    outputAudioTokenCost?: number;
     disabled?: boolean;
     costUnit?: "tokens" | "characters" | "minutes";
     knowledge?: string;
@@ -34,6 +37,8 @@ export type BaseModel = {
 export type SpeechToTextModel = BaseModel & {
     type: "speech-to-text";
     perMinuteCost?: number;
+    /** Provider's minimum billable duration in seconds (e.g. Groq bills >= 10s). */
+    minimumBillableSeconds?: number;
     /** Canonical MIME types accepted after alias normalization through AUDIO_FORMATS. */
     supportedMimeTypes?: readonly string[];
     /** Provider upload cap in bytes. */
@@ -90,10 +95,11 @@ export type TextModel = BaseModel & {
         input: string[];
         output: string[];
     };
+    /** Audio-input constraints when this multimodal model is used for transcription. */
+    supportedMimeTypes?: readonly string[];
+    maxBytes?: number;
     structuredOutput?: boolean;
     temperatureSupported?: boolean;
-    inputAudioTokenCost?: number;
-    outputAudioTokenCost?: number;
     /** Pricing that applies above a context-size threshold (e.g. Gemini >200k). */
     longContext?: {
         thresholdTokens: number;
@@ -116,6 +122,22 @@ export declare const speechToTextModels: readonly [{
     readonly provider: "openai";
     readonly supportedMimeTypes: readonly ["audio/flac", "audio/mpeg", "audio/mp4", "audio/m4a", "audio/ogg", "audio/wav", "audio/webm"];
     readonly maxBytes: number;
+}, {
+    readonly type: "speech-to-text";
+    readonly modelName: "whisper-large-v3";
+    readonly provider: "groq";
+    readonly perMinuteCost: 0.00185;
+    readonly minimumBillableSeconds: 10;
+    readonly supportedMimeTypes: readonly ["audio/flac", "audio/mpeg", "audio/mp4", "audio/m4a", "audio/ogg", "audio/wav", "audio/webm"];
+    readonly maxBytes: number;
+}, {
+    readonly type: "speech-to-text";
+    readonly modelName: "whisper-large-v3-turbo";
+    readonly provider: "groq";
+    readonly perMinuteCost: 0.000667;
+    readonly minimumBillableSeconds: 10;
+    readonly supportedMimeTypes: readonly ["audio/flac", "audio/mpeg", "audio/mp4", "audio/m4a", "audio/ogg", "audio/wav", "audio/webm"];
+    readonly maxBytes: number;
 }];
 export declare const textToSpeechModels: readonly [{
     readonly type: "text-to-speech";
@@ -139,6 +161,34 @@ export declare const textToSpeechModels: readonly [{
         readonly max: 4;
     };
     readonly formats: readonly ["mp3", "opus", "aac", "flac", "wav", "pcm"];
+}, {
+    readonly type: "text-to-speech";
+    readonly modelName: "canopylabs/orpheus-v1-english";
+    readonly provider: "groq";
+    readonly perCharacterCost: 0.000022;
+    readonly maxInputChars: 200;
+    readonly formats: readonly ["wav"];
+}, {
+    readonly type: "text-to-speech";
+    readonly modelName: "canopylabs/orpheus-arabic-saudi";
+    readonly provider: "groq";
+    readonly perCharacterCost: 0.00004;
+    readonly maxInputChars: 200;
+    readonly formats: readonly ["wav"];
+}, {
+    readonly type: "text-to-speech";
+    readonly modelName: "gemini-2.5-flash-preview-tts";
+    readonly provider: "google";
+    readonly inputTokenCost: 0.5;
+    readonly outputAudioTokenCost: 10;
+    readonly formats: readonly ["pcm", "wav"];
+}, {
+    readonly type: "text-to-speech";
+    readonly modelName: "gemini-2.5-pro-preview-tts";
+    readonly provider: "google";
+    readonly inputTokenCost: 1;
+    readonly outputAudioTokenCost: 20;
+    readonly formats: readonly ["pcm", "wav"];
 }];
 export declare const textModels: readonly [{
     readonly type: "text";
@@ -1203,6 +1253,8 @@ export declare const textModels: readonly [{
         readonly input: readonly ["text", "image", "audio", "video", "pdf"];
         readonly output: readonly ["text"];
     };
+    readonly supportedMimeTypes: readonly ["audio/wav", "audio/mpeg", "audio/aac", "audio/ogg", "audio/flac", "audio/aiff"];
+    readonly maxBytes: 14000000;
     readonly knowledge: "2025-01";
     readonly releaseDate: "2025-06-17";
     readonly lastUpdated: "2025-06-17";
@@ -1771,5 +1823,11 @@ export declare function isImageModel(model: ModelType): model is ImageModel;
 export declare function isTextModel(model: ModelType): model is TextModel;
 export declare function isSpeechToTextModel(model: ModelType): model is SpeechToTextModel;
 export declare function isTextToSpeechModel(model: ModelType): model is TextToSpeechModel;
+/** Audio-input constraints, readable off either a dedicated STT model or a
+ *  multimodal text model. Empty for any other model type. */
+export declare function audioInputConstraints(model: ModelType): {
+    maxBytes?: number;
+    supportedMimeTypes?: readonly string[];
+};
 export declare function isEmbeddingsModel(model: ModelType): model is EmbeddingsModel;
 export declare const ModelNameSchema: z.ZodString;

package/dist/models.js

@@ -12,6 +12,7 @@ export const providers = [
     "deepinfra",
     "litellm",
     "openai-compat",
+    "groq",
 ];
 export const ProviderSchema = z.enum(providers);
 export const speechToTextModels = [
@@ -26,6 +27,32 @@ export const speechToTextModels = [
         ],
         maxBytes: 25 * 1024 * 1024,
     },
+    {
+        type: "speech-to-text",
+        modelName: "whisper-large-v3",
+        provider: "groq",
+        perMinuteCost: 0.00185, // $0.111/hr, verified 2026-08-09
+        minimumBillableSeconds: 10, // Groq bills a 10s minimum per request
+        supportedMimeTypes: [
+            "audio/flac", "audio/mpeg", "audio/mp4", "audio/m4a", "audio/ogg",
+            "audio/wav", "audio/webm",
+        ],
+        // Conservative free-tier / direct-attachment cap; Groq's developer tier
+        // allows 100 MB, but a single baked-in record cannot vary by account tier.
+        maxBytes: 25 * 1024 * 1024,
+    },
+    {
+        type: "speech-to-text",
+        modelName: "whisper-large-v3-turbo",
+        provider: "groq",
+        perMinuteCost: 0.000667, // $0.04/hr, verified 2026-08-09
+        minimumBillableSeconds: 10, // Groq bills a 10s minimum per request
+        supportedMimeTypes: [
+            "audio/flac", "audio/mpeg", "audio/mp4", "audio/m4a", "audio/ogg",
+            "audio/wav", "audio/webm",
+        ],
+        maxBytes: 25 * 1024 * 1024,
+    },
 ];
 export const textToSpeechModels = [
     {
@@ -46,6 +73,40 @@ export const textToSpeechModels = [
         speedRange: { min: 0.25, max: 4 },
         formats: ["mp3", "opus", "aac", "flac", "wav", "pcm"],
     },
+    {
+        type: "text-to-speech",
+        modelName: "canopylabs/orpheus-v1-english",
+        provider: "groq",
+        perCharacterCost: 0.000022, // $22 / 1M chars, verified 2026-08-09
+        maxInputChars: 200,
+        formats: ["wav"],
+    },
+    {
+        type: "text-to-speech",
+        modelName: "canopylabs/orpheus-arabic-saudi",
+        provider: "groq",
+        perCharacterCost: 0.00004, // $40 / 1M chars, verified 2026-08-09
+        maxInputChars: 200,
+        formats: ["wav"],
+    },
+    // Gemini TTS is token-billed (text input + audio output). No maxInputChars:
+    // Gemini documents a 32k-token context, and characters are not a sound proxy.
+    {
+        type: "text-to-speech",
+        modelName: "gemini-2.5-flash-preview-tts",
+        provider: "google",
+        inputTokenCost: 0.5, // $/1M text-input tokens, verified 2026-08-09
+        outputAudioTokenCost: 10.0, // $/1M audio-output tokens
+        formats: ["pcm", "wav"],
+    },
+    {
+        type: "text-to-speech",
+        modelName: "gemini-2.5-pro-preview-tts",
+        provider: "google",
+        inputTokenCost: 1.0, // $/1M text-input tokens, verified 2026-08-09
+        outputAudioTokenCost: 20.0, // $/1M audio-output tokens
+        formats: ["pcm", "wav"],
+    },
 ];
 export const textModels = [
     {
@@ -1148,6 +1209,11 @@ export const textModels = [
             input: ["text", "image", "audio", "video", "pdf"],
             output: ["text"],
         },
+        // Audio-input (transcription) constraints. maxBytes is a conservative raw cap
+        // leaving room for base64 expansion + instructions under Gemini's 20 MB total
+        // inline request limit; the client also checks the encoded request size.
+        supportedMimeTypes: ["audio/wav", "audio/mpeg", "audio/aac", "audio/ogg", "audio/flac", "audio/aiff"],
+        maxBytes: 14_000_000,
         knowledge: "2025-01",
         releaseDate: "2025-06-17",
         lastUpdated: "2025-06-17",
@@ -1975,6 +2041,14 @@ export function isSpeechToTextModel(model) {
 export function isTextToSpeechModel(model) {
     return model.type === "text-to-speech";
 }
+/** Audio-input constraints, readable off either a dedicated STT model or a
+ *  multimodal text model. Empty for any other model type. */
+export function audioInputConstraints(model) {
+    if (model.type === "speech-to-text" || model.type === "text") {
+        return { maxBytes: model.maxBytes, supportedMimeTypes: model.supportedMimeTypes };
+    }
+    return {};
+}
 export function isEmbeddingsModel(model) {
     return model.type === "embeddings";
 }

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