smoltalk 0.9.0 → 0.10.1

package/dist/models.js

@@ -12,25 +12,101 @@ export const providers = [
     "deepinfra",
     "litellm",
     "openai-compat",
+    "groq",
 ];
 export const ProviderSchema = z.enum(providers);
 export const speechToTextModels = [
     {
         type: "speech-to-text",
-        modelName: "whisper-web",
+        modelName: "whisper-1",
         perMinuteCost: 0.006,
         provider: "openai",
+        supportedMimeTypes: [
+            "audio/flac", "audio/mpeg", "audio/mp4", "audio/m4a", "audio/ogg",
+            "audio/wav", "audio/webm",
+        ],
+        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 = [
+    {
+        type: "text-to-speech",
+        modelName: "tts-1",
+        perCharacterCost: 0.000015,
+        provider: "openai",
+        maxInputChars: 4096,
+        speedRange: { min: 0.25, max: 4 },
+        formats: ["mp3", "opus", "aac", "flac", "wav", "pcm"],
+    },
+    {
+        type: "text-to-speech",
+        modelName: "tts-1-hd",
+        perCharacterCost: 0.00003,
+        provider: "openai",
+        maxInputChars: 4096,
+        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"],
     },
-    // not a speech to text model?
-    /* {
-      type: "speech-to-text",
-      modelName: "gpt-4o-audio-preview",
-      description:
-        "This is a preview release of the GPT-4o Audio models. These models accept audio inputs and outputs, and can be used in the Chat Completions REST API. Learn more. The knowledge cutoff for GPT-4o Audio models is October, 2023.",
-      inputTokenCost: 2.5,
-      outputTokenCost: 10,
-      provider: "openai",
-    }, */
 ];
 export const textModels = [
     {
@@ -771,16 +847,16 @@ export const textModels = [
     {
         type: "text",
         modelName: "gpt-5.6-terra",
-        description: "GPT-5.6 Terra balances capability and cost — competitive with GPT-5.5 at roughly half the price. 1M context window. Standard pricing for ≤272K tokens, 2x input/1.5x output for >272K. Knowledge cutoff: February 2026.",
+        description: "GPT-5.6 Terra balances capability and cost. 1M context window. Standard pricing for ≤272K tokens, 2x input/1.5x output for >272K. Reflects the July 30, 2026 price cut. Knowledge cutoff: February 2026.",
         maxInputTokens: 1050000,
         maxOutputTokens: 128000,
-        inputTokenCost: 2.5,
-        cachedInputTokenCost: 0.25,
-        outputTokenCost: 15,
+        inputTokenCost: 2,
+        cachedInputTokenCost: 0.2,
+        outputTokenCost: 12,
         longContext: {
-            inputTokenCost: 5,
-            cachedInputTokenCost: 0.5,
-            outputTokenCost: 22.5,
+            inputTokenCost: 4,
+            cachedInputTokenCost: 0.4,
+            outputTokenCost: 18,
             thresholdTokens: 200000,
         },
         reasoning: {
@@ -806,16 +882,16 @@ export const textModels = [
     {
         type: "text",
         modelName: "gpt-5.6-luna",
-        description: "GPT-5.6 Luna is the fast, most affordable member of the GPT-5.6 family. 1M context window. Standard pricing for ≤272K tokens, 2x input/1.5x output for >272K. Knowledge cutoff: February 2026.",
+        description: "GPT-5.6 Luna is the fast, most affordable member of the GPT-5.6 family. 1M context window. Standard pricing for ≤272K tokens, 2x input/1.5x output for >272K. Reflects the July 30, 2026 price cut (input/output down ~80%). Knowledge cutoff: February 2026.",
         maxInputTokens: 1050000,
         maxOutputTokens: 128000,
-        inputTokenCost: 1,
-        cachedInputTokenCost: 0.1,
-        outputTokenCost: 6,
+        inputTokenCost: 0.2,
+        cachedInputTokenCost: 0.02,
+        outputTokenCost: 1.2,
         longContext: {
-            inputTokenCost: 2,
-            cachedInputTokenCost: 0.2,
-            outputTokenCost: 9,
+            inputTokenCost: 0.4,
+            cachedInputTokenCost: 0.04,
+            outputTokenCost: 1.8,
             thresholdTokens: 200000,
         },
         reasoning: {
@@ -903,10 +979,40 @@ export const textModels = [
         disabled: true,
         provider: "google",
     },
+    {
+        type: "text",
+        modelName: "gemini-3.6-flash",
+        description: "Latest Gemini 3.6 Flash model (GA July 21, 2026). Supersedes Gemini 3.5 Flash with better token efficiency and agentic planning at a lower output price ($7.50 vs $9.00/1M). 1M context window, 64K output. Context caching: $0.15/1M read.",
+        maxInputTokens: 1048576,
+        maxOutputTokens: 65536,
+        inputTokenCost: 1.5,
+        cachedInputTokenCost: 0.15,
+        outputTokenCost: 7.5,
+        inputAudioTokenCost: 1.5,
+        reasoning: {
+            levels: ["minimal", "low", "medium", "high"],
+            defaultLevel: "high",
+            canDisable: false,
+            outputsThinking: true,
+            outputsSignatures: true,
+        },
+        modalities: {
+            input: ["text", "image", "video", "audio", "pdf"],
+            output: ["text"],
+        },
+        knowledge: "2026-03",
+        releaseDate: "2026-07-21",
+        lastUpdated: "2026-07-21",
+        family: "gemini-flash",
+        openWeights: false,
+        structuredOutput: true,
+        temperatureSupported: true,
+        provider: "google",
+    },
     {
         type: "text",
         modelName: "gemini-3.5-flash",
-        description: "Latest Gemini 3.5 Flash model (GA May 2026). Outperforms Gemini 3.1 Pro on coding and agentic suites at 4x the speed. 1M context window, 64K output. Context caching: $0.15/1M read.",
+        description: "Gemini 3.5 Flash (GA May 2026). Superseded by gemini-3.6-flash. Outperforms Gemini 3.1 Pro on coding and agentic suites at 4x the speed. 1M context window, 64K output. Context caching: $0.15/1M read.",
         maxInputTokens: 1048576,
         maxOutputTokens: 65536,
         inputTokenCost: 1.5,
@@ -964,10 +1070,40 @@ export const textModels = [
         temperatureSupported: true,
         provider: "google",
     },
+    {
+        type: "text",
+        modelName: "gemini-3.5-flash-lite",
+        description: "Most cost-effective Gemini model (GA July 21, 2026). Supersedes gemini-3.1-flash-lite. Built for high-volume, low-reasoning work (search, document processing, translation). Thinking support, 1M context window, 64K output.",
+        maxInputTokens: 1048576,
+        maxOutputTokens: 65536,
+        inputTokenCost: 0.3,
+        cachedInputTokenCost: 0.03,
+        outputTokenCost: 2.5,
+        inputAudioTokenCost: 0.5,
+        reasoning: {
+            levels: ["minimal", "low", "medium", "high"],
+            defaultLevel: "minimal",
+            canDisable: false,
+            outputsThinking: true,
+            outputsSignatures: true,
+        },
+        modalities: {
+            input: ["text", "image", "video", "audio", "pdf"],
+            output: ["text"],
+        },
+        knowledge: "2025-01",
+        releaseDate: "2026-07-21",
+        lastUpdated: "2026-07-21",
+        family: "gemini-flash-lite",
+        openWeights: false,
+        structuredOutput: true,
+        temperatureSupported: true,
+        provider: "google",
+    },
     {
         type: "text",
         modelName: "gemini-3.1-flash-lite",
-        description: "Most cost-effective Gemini 3.1 model (GA). Thinking support, 1M context window, 64K output. 2.5x faster TTFA and 45% faster output than 2.5 Flash.",
+        description: "Cost-effective Gemini 3.1 model (GA). Superseded by gemini-3.5-flash-lite. Thinking support, 1M context window, 64K output. 2.5x faster TTFA and 45% faster output than 2.5 Flash.",
         maxInputTokens: 1048576,
         maxOutputTokens: 65536,
         inputTokenCost: 0.25,
@@ -1073,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",
@@ -1549,6 +1690,19 @@ export const textModels = [
         temperatureSupported: false,
         provider: "openai-responses",
     },
+    {
+        type: "text",
+        modelName: "gpt-audio-1.5",
+        description: "OpenAI GA audio chat model (Chat Completions). Text+audio in, text+audio out.",
+        provider: "openai",
+        modalities: { input: ["text", "audio"], output: ["text", "audio"] },
+        inputTokenCost: 2.5,
+        outputTokenCost: 10,
+        inputAudioTokenCost: 32,
+        outputAudioTokenCost: 64,
+        maxInputTokens: 128000,
+        maxOutputTokens: 16384,
+    },
 ];
 export const imageModels = [
     {
@@ -1730,7 +1884,7 @@ export const hostedTools = [
         category: "maps_grounding",
         description: "Grounding with Google Maps (Gemini 3 only).",
         providerToolId: "google_maps",
-        models: ["gemini-3-pro-preview", "gemini-3.1-pro-preview", "gemini-3-flash-preview", "gemini-3.5-flash", "gemini-3.1-flash-lite"],
+        models: ["gemini-3-pro-preview", "gemini-3.1-pro-preview", "gemini-3-flash-preview", "gemini-3.5-flash", "gemini-3.6-flash", "gemini-3.1-flash-lite", "gemini-3.5-flash-lite"],
         pricing: { unit: "per_call", note: "Gemini 3 family only; see Google pricing." },
     },
     {
@@ -1765,6 +1919,7 @@ function baselineModels() {
         ...textModels,
         ...imageModels,
         ...speechToTextModels,
+        ...textToSpeechModels,
         ...registeredTextModels,
         ...embeddingsModels,
     ];
@@ -1790,13 +1945,28 @@ export function getAllModels(requestData) {
 export function getModel(modelName, requestData) {
     return getAllModels(requestData).find((model) => model.modelName === modelName);
 }
+/**
+ * Like `getModel`, but also matches on `provider`. Use this whenever a
+ * modelName may collide across providers (the merge key everywhere else in
+ * this module is `provider:modelName`) — plain `getModel` returns whichever
+ * matching entry comes first and can silently pick the wrong provider.
+ */
+export function getModelForProvider(provider, modelName, requestData) {
+    return getAllModels(requestData).find((model) => model.modelName === modelName && model.provider === provider);
+}
 /**
  * Whether a model is known to accept the given input modality ("image", "pdf", …).
  * Returns undefined when the model is unknown or carries no `modalities` data —
  * callers should treat undefined as "don't gate".
  */
-export function modelSupportsInputModality(modelName, modality, requestData) {
-    const model = getModel(modelName, requestData);
+export function modelSupportsInputModality(modelName, modality, requestData, provider) {
+    let model;
+    if (provider !== undefined) {
+        model = getModelForProvider(provider, modelName, requestData);
+    }
+    else {
+        model = getModel(modelName, requestData);
+    }
     if (!model || model.type !== "text") {
         return undefined;
     }
@@ -1868,6 +2038,17 @@ export function isTextModel(model) {
 export function isSpeechToTextModel(model) {
     return model.type === "speech-to-text";
 }
+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

@@ -0,0 +1,36 @@
+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 = {
+    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"];
+    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
+ * speak() template method owns model-data-driven validation (char cap, speed
+ * range, format list), cost, and the single redacting/logging exception
+ * boundary. Subclasses implement only _speak(): SDK call + response mapping.
+ * A model with no registry entry skips validation — the provider is then the
+ * authority, matching how cost is silently omitted for unknown models.
+ */
+export declare abstract class BaseSpeechClient {
+    protected config: SpeechClientConfig;
+    constructor(config: SpeechClientConfig);
+    speak(text: string): Promise<Result<SpeechResult>>;
+    /** Provider hook: SDK call + response mapping only; validation and cost live in the base. */
+    protected abstract _speak(text: string): Promise<Result<SpeechResult>>;
+}

package/dist/speech/baseSpeechClient.js

@@ -0,0 +1,117 @@
+import { getModelForProvider, isTextToSpeechModel, } from "../models.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";
+/** Validate the declarative TTS constraint block once before consuming it. */
+function speechConstraintError(model) {
+    const maxInputChars = model.maxInputChars;
+    if (maxInputChars !== undefined &&
+        (typeof maxInputChars !== "number" ||
+            !Number.isInteger(maxInputChars) ||
+            maxInputChars <= 0)) {
+        return `Model "${model.modelName}" has an invalid maxInputChars value.`;
+    }
+    const speedRange = model.speedRange;
+    if (speedRange !== undefined) {
+        if (typeof speedRange !== "object" || speedRange === null) {
+            return `Model "${model.modelName}" has an invalid speedRange.`;
+        }
+        const min = speedRange.min;
+        const max = speedRange.max;
+        if (typeof min !== "number" ||
+            typeof max !== "number" ||
+            !Number.isFinite(min) ||
+            !Number.isFinite(max) ||
+            min > max) {
+            return `Model "${model.modelName}" has an invalid speedRange.`;
+        }
+    }
+    const formats = model.formats;
+    if (formats !== undefined &&
+        (!Array.isArray(formats) ||
+            !formats.every((format) => typeof format === "string"))) {
+        return `Model "${model.modelName}" has invalid formats.`;
+    }
+    return null;
+}
+/**
+ * Shared TTS behavior, mirroring BaseClient for text generation: the public
+ * speak() template method owns model-data-driven validation (char cap, speed
+ * range, format list), cost, and the single redacting/logging exception
+ * boundary. Subclasses implement only _speak(): SDK call + response mapping.
+ * A model with no registry entry skips validation — the provider is then the
+ * authority, matching how cost is silently omitted for unknown models.
+ */
+export class BaseSpeechClient {
+    config;
+    constructor(config) {
+        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)) {
+                return failure(`Model "${this.config.model}" is not a text-to-speech model.`);
+            }
+            if (model !== undefined) {
+                const constraintError = speechConstraintError(model);
+                if (constraintError !== null) {
+                    return failure(constraintError);
+                }
+                if (model.maxInputChars !== undefined && [...text].length > model.maxInputChars) {
+                    return failure(`Input exceeds the ${model.maxInputChars}-character limit for model "${this.config.model}".`);
+                }
+                if (this.config.speed !== undefined && model.speedRange !== undefined) {
+                    const { min, max } = model.speedRange;
+                    if (!Number.isFinite(this.config.speed) || this.config.speed < min || this.config.speed > max) {
+                        return failure(`speed must be a finite number in [${min}, ${max}].`);
+                    }
+                }
+                if (this.config.format !== undefined &&
+                    model.formats !== undefined &&
+                    !model.formats.includes(this.config.format)) {
+                    return failure(`Format "${this.config.format}" is not supported by model "${this.config.model}". ` +
+                        `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;
+            }
+            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;
+            }
+            const redacted = redactSecret(msg, this.config.apiKey);
+            getLogger().error("speak() provider failed:", redacted);
+            return failure(redacted);
+        }
+    }
+}

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

@@ -0,0 +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

@@ -0,0 +1,51 @@
+import OpenAI from "openai";
+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(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 ?? 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 = this.makeClient();
+        const params = {
+            model: this.config.model,
+            voice: this.config.voice,
+            input: text,
+            response_format: format,
+        };
+        if (this.config.speed !== undefined) {
+            params.speed = this.config.speed;
+        }
+        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") {
+            result.pcm = { sampleRateHz: 24000, sampleFormat: "s16le", channels: 1 };
+        }
+        return success(result);
+    }
+}

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