smoltalk 0.9.0 → 0.10.0

package/dist/models.d.ts

@@ -34,6 +34,23 @@ export type BaseModel = {
 export type SpeechToTextModel = BaseModel & {
     type: "speech-to-text";
     perMinuteCost?: number;
+    /** Canonical MIME types accepted after alias normalization through AUDIO_FORMATS. */
+    supportedMimeTypes?: readonly string[];
+    /** Provider upload cap in bytes. */
+    maxBytes?: number;
+};
+export type TextToSpeechModel = BaseModel & {
+    type: "text-to-speech";
+    perCharacterCost?: number;
+    /** Input cap in Unicode code points. */
+    maxInputChars?: number;
+    /** Accepted values for the speed option. */
+    speedRange?: {
+        min: number;
+        max: number;
+    };
+    /** Output formats the provider can render for this model. */
+    formats?: readonly string[];
 };
 export type ImageModel = BaseModel & {
     type: "image";
@@ -91,12 +108,37 @@ export type EmbeddingsModel = {
     provider: string;
     tokenCost?: number;
 };
-export type ModelType = SpeechToTextModel | TextModel | EmbeddingsModel | ImageModel;
+export type ModelType = SpeechToTextModel | TextToSpeechModel | TextModel | EmbeddingsModel | ImageModel;
 export declare const speechToTextModels: readonly [{
     readonly type: "speech-to-text";
-    readonly modelName: "whisper-web";
+    readonly modelName: "whisper-1";
     readonly perMinuteCost: 0.006;
     readonly provider: "openai";
+    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";
+    readonly modelName: "tts-1";
+    readonly perCharacterCost: 0.000015;
+    readonly provider: "openai";
+    readonly maxInputChars: 4096;
+    readonly speedRange: {
+        readonly min: 0.25;
+        readonly max: 4;
+    };
+    readonly formats: readonly ["mp3", "opus", "aac", "flac", "wav", "pcm"];
+}, {
+    readonly type: "text-to-speech";
+    readonly modelName: "tts-1-hd";
+    readonly perCharacterCost: 0.00003;
+    readonly provider: "openai";
+    readonly maxInputChars: 4096;
+    readonly speedRange: {
+        readonly min: 0.25;
+        readonly max: 4;
+    };
+    readonly formats: readonly ["mp3", "opus", "aac", "flac", "wav", "pcm"];
 }];
 export declare const textModels: readonly [{
     readonly type: "text";
@@ -810,16 +852,16 @@ export declare const textModels: readonly [{
 }, {
     readonly type: "text";
     readonly modelName: "gpt-5.6-terra";
-    readonly 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.";
+    readonly 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.";
     readonly maxInputTokens: 1050000;
     readonly maxOutputTokens: 128000;
-    readonly inputTokenCost: 2.5;
-    readonly cachedInputTokenCost: 0.25;
-    readonly outputTokenCost: 15;
+    readonly inputTokenCost: 2;
+    readonly cachedInputTokenCost: 0.2;
+    readonly outputTokenCost: 12;
     readonly longContext: {
-        readonly inputTokenCost: 5;
-        readonly cachedInputTokenCost: 0.5;
-        readonly outputTokenCost: 22.5;
+        readonly inputTokenCost: 4;
+        readonly cachedInputTokenCost: 0.4;
+        readonly outputTokenCost: 18;
         readonly thresholdTokens: 200000;
     };
     readonly reasoning: {
@@ -844,16 +886,16 @@ export declare const textModels: readonly [{
 }, {
     readonly type: "text";
     readonly modelName: "gpt-5.6-luna";
-    readonly 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.";
+    readonly 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.";
     readonly maxInputTokens: 1050000;
     readonly maxOutputTokens: 128000;
-    readonly inputTokenCost: 1;
-    readonly cachedInputTokenCost: 0.1;
-    readonly outputTokenCost: 6;
+    readonly inputTokenCost: 0.2;
+    readonly cachedInputTokenCost: 0.02;
+    readonly outputTokenCost: 1.2;
     readonly longContext: {
-        readonly inputTokenCost: 2;
-        readonly cachedInputTokenCost: 0.2;
-        readonly outputTokenCost: 9;
+        readonly inputTokenCost: 0.4;
+        readonly cachedInputTokenCost: 0.04;
+        readonly outputTokenCost: 1.8;
         readonly thresholdTokens: 200000;
     };
     readonly reasoning: {
@@ -938,10 +980,39 @@ export declare const textModels: readonly [{
     readonly temperatureSupported: true;
     readonly disabled: true;
     readonly provider: "google";
+}, {
+    readonly type: "text";
+    readonly modelName: "gemini-3.6-flash";
+    readonly 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.";
+    readonly maxInputTokens: 1048576;
+    readonly maxOutputTokens: 65536;
+    readonly inputTokenCost: 1.5;
+    readonly cachedInputTokenCost: 0.15;
+    readonly outputTokenCost: 7.5;
+    readonly inputAudioTokenCost: 1.5;
+    readonly reasoning: {
+        readonly levels: readonly ["minimal", "low", "medium", "high"];
+        readonly defaultLevel: "high";
+        readonly canDisable: false;
+        readonly outputsThinking: true;
+        readonly outputsSignatures: true;
+    };
+    readonly modalities: {
+        readonly input: readonly ["text", "image", "video", "audio", "pdf"];
+        readonly output: readonly ["text"];
+    };
+    readonly knowledge: "2026-03";
+    readonly releaseDate: "2026-07-21";
+    readonly lastUpdated: "2026-07-21";
+    readonly family: "gemini-flash";
+    readonly openWeights: false;
+    readonly structuredOutput: true;
+    readonly temperatureSupported: true;
+    readonly provider: "google";
 }, {
     readonly type: "text";
     readonly modelName: "gemini-3.5-flash";
-    readonly 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.";
+    readonly 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.";
     readonly maxInputTokens: 1048576;
     readonly maxOutputTokens: 65536;
     readonly inputTokenCost: 1.5;
@@ -997,10 +1068,39 @@ export declare const textModels: readonly [{
     readonly structuredOutput: true;
     readonly temperatureSupported: true;
     readonly provider: "google";
+}, {
+    readonly type: "text";
+    readonly modelName: "gemini-3.5-flash-lite";
+    readonly 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.";
+    readonly maxInputTokens: 1048576;
+    readonly maxOutputTokens: 65536;
+    readonly inputTokenCost: 0.3;
+    readonly cachedInputTokenCost: 0.03;
+    readonly outputTokenCost: 2.5;
+    readonly inputAudioTokenCost: 0.5;
+    readonly reasoning: {
+        readonly levels: readonly ["minimal", "low", "medium", "high"];
+        readonly defaultLevel: "minimal";
+        readonly canDisable: false;
+        readonly outputsThinking: true;
+        readonly outputsSignatures: true;
+    };
+    readonly modalities: {
+        readonly input: readonly ["text", "image", "video", "audio", "pdf"];
+        readonly output: readonly ["text"];
+    };
+    readonly knowledge: "2025-01";
+    readonly releaseDate: "2026-07-21";
+    readonly lastUpdated: "2026-07-21";
+    readonly family: "gemini-flash-lite";
+    readonly openWeights: false;
+    readonly structuredOutput: true;
+    readonly temperatureSupported: true;
+    readonly provider: "google";
 }, {
     readonly type: "text";
     readonly modelName: "gemini-3.1-flash-lite";
-    readonly 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.";
+    readonly 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.";
     readonly maxInputTokens: 1048576;
     readonly maxOutputTokens: 65536;
     readonly inputTokenCost: 0.25;
@@ -1558,6 +1658,21 @@ export declare const textModels: readonly [{
     readonly structuredOutput: true;
     readonly temperatureSupported: false;
     readonly provider: "openai-responses";
+}, {
+    readonly type: "text";
+    readonly modelName: "gpt-audio-1.5";
+    readonly description: "OpenAI GA audio chat model (Chat Completions). Text+audio in, text+audio out.";
+    readonly provider: "openai";
+    readonly modalities: {
+        readonly input: readonly ["text", "audio"];
+        readonly output: readonly ["text", "audio"];
+    };
+    readonly inputTokenCost: 2.5;
+    readonly outputTokenCost: 10;
+    readonly inputAudioTokenCost: 32;
+    readonly outputAudioTokenCost: 64;
+    readonly maxInputTokens: 128000;
+    readonly maxOutputTokens: 16384;
 }];
 export declare const imageModels: readonly [{
     readonly type: "image";
@@ -1610,6 +1725,7 @@ export declare const embeddingsModels: EmbeddingsModel[];
 export type TextModelName = (typeof textModels)[number]["modelName"];
 export type ImageModelName = (typeof imageModels)[number]["modelName"];
 export type SpeechToTextModelName = (typeof speechToTextModels)[number]["modelName"];
+export type TextToSpeechModelName = (typeof textToSpeechModels)[number]["modelName"];
 export type EmbeddingsModelName = (typeof embeddingsModels)[number]["modelName"];
 export type ModelName = string;
 export declare const hostedTools: HostedTool[];
@@ -1630,12 +1746,19 @@ export declare function getRegisteredModelData(): ModelDataBlob | null;
  */
 export declare function getAllModels(requestData?: ModelDataBlob): ModelType[];
 export declare function getModel(modelName: ModelName, requestData?: ModelDataBlob): ModelType | undefined;
+/**
+ * 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 declare function getModelForProvider(provider: string, modelName: ModelName, requestData?: ModelDataBlob): ModelType | undefined;
 /**
  * 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 declare function modelSupportsInputModality(modelName: ModelName, modality: string, requestData?: ModelDataBlob): boolean | undefined;
+export declare function modelSupportsInputModality(modelName: ModelName, modality: string, requestData?: ModelDataBlob, provider?: string): boolean | undefined;
 export declare function getHostedTools(opts?: {
     provider?: string;
     model?: string;
@@ -1647,5 +1770,6 @@ export declare function hostedToolPricingFor(tool: HostedTool, model?: string):
 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;
 export declare function isEmbeddingsModel(model: ModelType): model is EmbeddingsModel;
 export declare const ModelNameSchema: z.ZodString;

package/dist/models.js

@@ -17,20 +17,35 @@ 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,
+    },
+];
+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"],
     },
-    // 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 +786,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 +821,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 +918,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 +1009,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,
@@ -1549,6 +1624,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 +1818,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 +1853,7 @@ function baselineModels() {
         ...textModels,
         ...imageModels,
         ...speechToTextModels,
+        ...textToSpeechModels,
         ...registeredTextModels,
         ...embeddingsModels,
     ];
@@ -1790,13 +1879,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 +1972,9 @@ export function isTextModel(model) {
 export function isSpeechToTextModel(model) {
     return model.type === "speech-to-text";
 }
+export function isTextToSpeechModel(model) {
+    return model.type === "text-to-speech";
+}
 export function isEmbeddingsModel(model) {
     return model.type === "embeddings";
 }

package/dist/speech/baseSpeechClient.d.ts

@@ -0,0 +1,31 @@
+import type { ModelDataBlob } from "../modelData.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;
+    voice: string;
+    modelData?: ModelDataBlob;
+    /** Output format; provider-specific vocabulary (OpenAI: mp3/opus/aac/flac/wav/pcm). */
+    format?: string;
+    speed?: number;
+    metadata?: Record<string, unknown>;
+};
+/**
+ * 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,98 @@
+import { getModelForProvider, isTextToSpeechModel, } from "../models.js";
+import { 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) {
+        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(", ")}.`);
+                }
+            }
+            const result = await this._speak(text);
+            if (!result.success) {
+                return result;
+            }
+            const cost = calculateSpeechCost(model, [...text].length);
+            if (cost !== undefined) {
+                result.value.cost = cost;
+            }
+            return result;
+        }
+        catch (err) {
+            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/openai.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 OpenAISpeechClient extends BaseSpeechClient {
+    protected _speak(text: string): Promise<Result<SpeechResult>>;
+}