smoltalk 0.10.0 → 0.11.0

package/README.md

@@ -507,13 +507,79 @@ Text, transcription, and speech are classes: a base class owns the shared
 behavior (validation, cost, error handling) and the subclass implements only
 the provider call. Embeddings and images are one-shot functions.
 
+## Local models (llama-cpp)
+
+Install the optional plugin and name the provider — no wiring code:
+
+```bash
+npm i smoltalk-llama-cpp
+```
+
+```typescript
+import { textSync, userMessage } from "smoltalk";
+
+const result = await textSync({
+  provider: "llama-cpp",
+  model: "/path/to/llama-3.gguf",
+  messages: [userMessage("Hello!")],
+});
+```
+
+smoltalk lazily imports and registers the plugin on the first `llama-cpp`
+call; if the package is missing you get an install hint instead of a
+resolution stack trace. Hosts with unusual layouts (e.g. a globally-installed
+CLI with the plugin installed globally beside it) can hand smoltalk the
+plugin's entry path explicitly and skip Node resolution:
+
+```typescript
+import { loadLlamaCpp } from "smoltalk";
+
+const { resolveModel } = await loadLlamaCpp({
+  entryPath: "/path/to/smoltalk-llama-cpp/dist/index.js",
+});
+// resolveModel downloads hf: URIs (and absolutizes existing local paths):
+const modelPath = await resolveModel("hf:org/repo/model.gguf", "/models/cache");
+```
+
 ## 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 +595,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/client.d.ts

@@ -12,4 +12,10 @@ import { BaseClient } from "./clients/baseClient.js";
 import { SmolClientConfig } from "./types.js";
 export declare function registerProvider(providerName: string, clientClass: typeof BaseClient): void;
 export declare function unregisterProvider(providerName: string): boolean;
+/**
+ * True when `providerName` has been registered via registerProvider().
+ * Built-in providers (the switch cases in getClient) are not its concern —
+ * this only consults the custom registry.
+ */
+export declare function hasProvider(providerName: string): boolean;
 export declare function getClient(config: SmolClientConfig): BaseClient;

package/dist/client.js

@@ -33,6 +33,14 @@ export function unregisterProvider(providerName) {
     }
     return false;
 }
+/**
+ * True when `providerName` has been registered via registerProvider().
+ * Built-in providers (the switch cases in getClient) are not its concern —
+ * this only consults the custom registry.
+ */
+export function hasProvider(providerName) {
+    return providerName in registeredProviders;
+}
 export function getClient(config) {
     const modelName = config.model;
     const provider = resolveProvider(modelName, config.provider, config.modelData);
@@ -100,6 +108,10 @@ export function getClient(config) {
                 const ClientClass = registeredProviders[provider];
                 return new ClientClass(clientConfig);
             }
+            if (provider === "llama-cpp") {
+                throw new SmolError("The llama-cpp provider loads automatically when called through text()/textSync()/textStream(). " +
+                    "For direct getClient() use, await loadLlamaCpp() first (install smoltalk-llama-cpp if it is missing).");
+            }
             throw new SmolError(`Model provider ${provider} is not supported. To use a custom provider, register it first via registerProvider(name, ClientClass).`);
     }
 }

package/dist/clients/llamaCppLoader.d.ts

@@ -0,0 +1,42 @@
+import type { BaseClient } from "./baseClient.js";
+/**
+ * Minimal structural view of smoltalk-llama-cpp's module. Declared here (not
+ * imported from the plugin) so smoltalk compiles without the plugin installed
+ * and the workspace gains no build-order cycle.
+ */
+export type LlamaCppModule = {
+    LlamaCPP: typeof BaseClient;
+    resolveModel: (uriOrPath: string, cacheDir: string) => Promise<string>;
+};
+type ImportFn = (specifier: string) => Promise<Record<string, unknown>>;
+/**
+ * Test-only: swap the dynamic import (pass undefined to restore the real one)
+ * and clear the load cache. Deliberately NOT exported from the package index.
+ */
+export declare function _setImportForTests(fn?: ImportFn): void;
+/**
+ * Load and register the optional smoltalk-llama-cpp plugin, once per process.
+ *
+ * - Without options, imports the bare specifier "smoltalk-llama-cpp" using
+ *   Node resolution from smoltalk's location. The optional peer declaration
+ *   in package.json is what makes that resolvable under pnpm's strict layout.
+ * - `entryPath` is the escape hatch for hosts whose plugin install is not
+ *   resolvable from smoltalk (e.g. globally-installed CLIs): the file is
+ *   imported directly and Node resolution is skipped. Hosts own discovering
+ *   that path; smoltalk never probes global npm roots and reads no env vars.
+ * - Registers the module's LlamaCPP class under "llama-cpp" unless that name
+ *   is already registered. An existing registration is left untouched, but
+ *   the module is still imported, validated, and returned — an existing
+ *   registration wins the registry, never the return value. Registration is
+ *   re-ensured from the cached module on EVERY call, so a later
+ *   unregisterProvider("llama-cpp") is undone by the next load call without
+ *   a second import.
+ * - Concurrent first calls share one in-flight load. A failed load clears
+ *   the cache so a later call can retry (e.g. after installing the package).
+ *   A second call with a different entryPath after a successful load returns
+ *   the already-loaded module (first load wins).
+ */
+export declare function loadLlamaCpp(options?: {
+    entryPath?: string;
+}): Promise<LlamaCppModule>;
+export {};

package/dist/clients/llamaCppLoader.js

@@ -0,0 +1,109 @@
+import { pathToFileURL } from "url";
+import { hasProvider, registerProvider } from "../client.js";
+import { SmolError } from "../smolError.js";
+const realImport = (specifier) => import(specifier);
+let importFn = realImport;
+let cachedLoad;
+/**
+ * Test-only: swap the dynamic import (pass undefined to restore the real one)
+ * and clear the load cache. Deliberately NOT exported from the package index.
+ */
+export function _setImportForTests(fn) {
+    if (fn) {
+        importFn = fn;
+    }
+    else {
+        importFn = realImport;
+    }
+    cachedLoad = undefined;
+}
+/**
+ * Load and register the optional smoltalk-llama-cpp plugin, once per process.
+ *
+ * - Without options, imports the bare specifier "smoltalk-llama-cpp" using
+ *   Node resolution from smoltalk's location. The optional peer declaration
+ *   in package.json is what makes that resolvable under pnpm's strict layout.
+ * - `entryPath` is the escape hatch for hosts whose plugin install is not
+ *   resolvable from smoltalk (e.g. globally-installed CLIs): the file is
+ *   imported directly and Node resolution is skipped. Hosts own discovering
+ *   that path; smoltalk never probes global npm roots and reads no env vars.
+ * - Registers the module's LlamaCPP class under "llama-cpp" unless that name
+ *   is already registered. An existing registration is left untouched, but
+ *   the module is still imported, validated, and returned — an existing
+ *   registration wins the registry, never the return value. Registration is
+ *   re-ensured from the cached module on EVERY call, so a later
+ *   unregisterProvider("llama-cpp") is undone by the next load call without
+ *   a second import.
+ * - Concurrent first calls share one in-flight load. A failed load clears
+ *   the cache so a later call can retry (e.g. after installing the package).
+ *   A second call with a different entryPath after a successful load returns
+ *   the already-loaded module (first load wins).
+ */
+export function loadLlamaCpp(options) {
+    if (!cachedLoad) {
+        const load = doLoad(options?.entryPath);
+        cachedLoad = load;
+        load.catch(() => {
+            if (cachedLoad === load) {
+                cachedLoad = undefined;
+            }
+        });
+    }
+    // Registration happens on EVERY call, not only inside the first load: a
+    // consumer can unregisterProvider("llama-cpp") after a successful load,
+    // and the cached module must be re-registered on the next call or the
+    // provider stays missing for the life of the process.
+    return cachedLoad.then((plugin) => {
+        if (!hasProvider("llama-cpp")) {
+            registerProvider("llama-cpp", plugin.LlamaCPP);
+        }
+        return plugin;
+    });
+}
+async function doLoad(entryPath) {
+    let importSource;
+    if (entryPath) {
+        importSource = pathToFileURL(entryPath).href;
+    }
+    else {
+        importSource = "smoltalk-llama-cpp";
+    }
+    let mod;
+    try {
+        mod = await importFn(importSource);
+    }
+    catch (error) {
+        if (!entryPath && isPluginNotInstalledError(error)) {
+            throw new SmolError("The llama-cpp provider needs the optional smoltalk-llama-cpp package. " +
+                "Install it (npm i smoltalk-llama-cpp) and try again.", { cause: error });
+        }
+        throw new SmolError(`Failed to load smoltalk-llama-cpp from ${importSource}: ${errorMessage(error)}`, { cause: error });
+    }
+    if (typeof mod.LlamaCPP !== "function") {
+        throw new SmolError(`The module imported as ${importSource} does not export LlamaCPP — ` +
+            "it does not appear to be the smoltalk-llama-cpp package.");
+    }
+    if (typeof mod.resolveModel !== "function") {
+        throw new SmolError("Your installed smoltalk-llama-cpp is too old for this version of smoltalk. " +
+            "Upgrade it (npm i smoltalk-llama-cpp@latest; >=0.2.0 required).");
+    }
+    return mod;
+}
+/**
+ * True only when the smoltalk-llama-cpp specifier itself failed to resolve —
+ * not when the package exists but its own import chain broke (e.g. a
+ * node-llama-cpp binary problem), where an install hint would mislead.
+ */
+function isPluginNotInstalledError(error) {
+    const code = error?.code;
+    if (code !== "ERR_MODULE_NOT_FOUND") {
+        return false;
+    }
+    return errorMessage(error).includes("'smoltalk-llama-cpp'");
+}
+function errorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}

package/dist/functions.js

@@ -1,5 +1,6 @@
 import { BaseMessage, messageFromJSON, } from "./classes/message/index.js";
-import { getClient } from "./client.js";
+import { getClient, hasProvider } from "./client.js";
+import { loadLlamaCpp } from "./clients/llamaCppLoader.js";
 import { getLogger } from "./util/logger.js";
 function fixMessagesIfNecessary(messages) {
     if (messages && messages.length > 0) {
@@ -16,10 +17,16 @@ export function text(config) {
     return textSync(config);
 }
 export async function textSync(config) {
+    if (config.provider === "llama-cpp" && !hasProvider("llama-cpp")) {
+        await loadLlamaCpp();
+    }
     config.messages = fixMessagesIfNecessary(config.messages);
     return getClient(config).textSync(config);
 }
 export async function* textStream(config) {
+    if (config.provider === "llama-cpp" && !hasProvider("llama-cpp")) {
+        await loadLlamaCpp();
+    }
     config.messages = fixMessagesIfNecessary(config.messages);
     yield* getClient(config).textStream(config);
 }

package/dist/index.d.ts

@@ -8,6 +8,8 @@ export * from "./util/util.js";
 export * from "./util/tool.js";
 export * from "./classes/message/index.js";
 export * from "./functions.js";
+export { loadLlamaCpp } from "./clients/llamaCppLoader.js";
+export type { LlamaCppModule } from "./clients/llamaCppLoader.js";
 export * from "./classes/ToolCall.js";
 export * from "./embed.js";
 export * from "./image.js";

package/dist/index.js

@@ -8,6 +8,8 @@ export * from "./util/util.js";
 export * from "./util/tool.js";
 export * from "./classes/message/index.js";
 export * from "./functions.js";
+// Explicit (not `export *`) so the test-only `_setImportForTests` stays off the public surface.
+export { loadLlamaCpp } from "./clients/llamaCppLoader.js";
 export * from "./classes/ToolCall.js";
 export * from "./embed.js";
 export * from "./image.js";

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