smoltalk 0.14.0 → 0.14.2

package/README.md

@@ -250,7 +250,7 @@ model ids aren't in the smoltalk registry.
 
 | `provider:` | What it is | Required config | Cost source |
 |-------------|------------|-----------------|-------------|
-| `"openrouter"` | OpenRouter.ai aggregator | `apiKey.openRouter` (or `OPENROUTER_API_KEY`) | `usage.cost` (auto-enabled by injecting `usage:{include:true}`) |
+| `"openrouter"` | OpenRouter.ai aggregator | `apiKey.openRouter` (or `OPENROUTER_API_KEY`) | `usage.cost` |
 | `"deepinfra"` | DeepInfra hosted models | `apiKey.deepInfra` (or `DEEPINFRA_API_KEY`) | `usage.estimated_cost` |
 | `"litellm"`   | Your own LiteLLM proxy   | `apiKey.liteLlm` + `baseUrl.liteLlm` (or `LITELLM_API_KEY` / `LITELLM_BASE_URL`) | `x-litellm-response-cost` header (non-stream only) |
 | `"openai-compat"` | Any OpenAI-shape backend (vLLM, TGI, LM Studio…) | `apiKey.openAiCompat` + `baseUrl.openAiCompat` (or `OPENAI_COMPAT_API_KEY` / `OPENAI_COMPAT_BASE_URL`) | Best-effort: reads `usage.cost`/`estimated_cost`/`cost_usd` if present |
@@ -561,6 +561,10 @@ 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`.
 
+`speak()` also supports **`mlx`**: a local MLX speech server at `baseUrl.mlx`,
+`MLX_BASE_URL`, or `http://127.0.0.1:8080/v1`. No API key, no retries, zero
+cost, and `"wav"` by default.
+
 ```ts
 // example: skip-typecheck
 // Groq STT (OpenAI-compatible; provider inferred from the model)
@@ -655,7 +659,11 @@ if (result.success) {
 `tts-1` and `tts-1-hd` are the only baked-in models in v1. `voice` is
 required. Options: `format` (OpenAI accepts `"mp3"` | `"opus"` | `"aac"` |
 `"flac"` | `"wav"` | `"pcm"`, default `"mp3"`; a custom provider may accept
-other strings) and `speed`. Limits are declared per model in the registry —
+other strings), `speed`, and `instructions`. `instructions` is free-text
+guidance on how the speech should sound (`"Alarmed and urgent."`). It is passed
+through as-is by the OpenAI-shaped providers (`openai`, `groq`, `openai-compat`,
+`mlx`); whether the model reads it is up to the model (`gpt-4o-mini-tts` does,
+`tts-1` does not). The `google` provider ignores it. Limits are declared per model in the registry —
 for `tts-1`/`tts-1-hd` that's a 4096-code-point input cap, a 0.25–4.0 speed
 range, and the format list above; exceeding any of them returns a `Failure`
 before the request is sent. The returned `audio` is a `Uint8Array` you own —

package/dist/clients/google.js

@@ -260,6 +260,9 @@ export class SmolGoogle extends BaseClient {
             });
         });
         const genConfig = {};
+        if (config.maxTokens !== undefined) {
+            genConfig.maxOutputTokens = config.maxTokens;
+        }
         if (systemParts.length > 0) {
             genConfig.systemInstruction = systemParts.join("\n");
         }

package/dist/clients/ollama.js

@@ -85,6 +85,9 @@ export class SmolOllama extends BaseClient {
         if (config.responseFormat) {
             request.format = responseFormatToJsonSchema(config.responseFormat);
         }
+        if (config.maxTokens !== undefined) {
+            request.options = { num_predict: config.maxTokens };
+        }
         Object.assign(request, sanitizeAttributes(config.rawAttributes));
         this.logger.debug("Sending request to Ollama:", JSON.stringify(redactAttachments(request), null, 2));
         this.statelogClient?.promptRequest(request);
@@ -151,6 +154,9 @@ export class SmolOllama extends BaseClient {
         if (config.responseFormat) {
             request.format = responseFormatToJsonSchema(config.responseFormat);
         }
+        if (config.maxTokens !== undefined) {
+            request.options = { num_predict: config.maxTokens };
+        }
         Object.assign(request, sanitizeAttributes(config.rawAttributes));
         this.logger.debug("Sending streaming request to Ollama:", JSON.stringify(redactAttachments(request), null, 2));
         this.statelogClient?.promptRequest(request);

package/dist/clients/openai.d.ts

@@ -32,11 +32,18 @@ export declare class SmolOpenAi extends BaseClient implements SmolClient {
     protected resolveCostUsd(_usage: any, _rawResponse?: Response): number | undefined;
     /**
      * Extra request body fields injected on every call. Subclasses override to
-     * add provider-specific request shapes (e.g. OpenRouter's `usage: { include: true }`
-     * or its `plugins: [{ id: "web" }]` for web search). Merged into the request
+     * add provider-specific request shapes (e.g. OpenRouter's
+     * `plugins: [{ id: "web" }]` for web search). Merged into the request
      * after the standard params so it can override them.
      */
     protected buildRequestExtras(_config: SmolConfig): Record<string, unknown>;
+    /**
+     * The request field carrying `config.maxTokens`. OpenAI deprecated
+     * `max_tokens` in favor of `max_completion_tokens`, and its reasoning models
+     * reject `max_tokens` outright. Compat servers override this to send
+     * `max_tokens`, which is the field they reliably accept.
+     */
+    protected maxTokensParam(config: SmolConfig): Record<string, number>;
     /**
      * Extract provider-specific hosted-tool results (e.g. OpenRouter web_search
      * annotations) from a completion. Subclasses override; default returns none.

package/dist/clients/openai.js

@@ -51,13 +51,25 @@ export class SmolOpenAi extends BaseClient {
     }
     /**
      * Extra request body fields injected on every call. Subclasses override to
-     * add provider-specific request shapes (e.g. OpenRouter's `usage: { include: true }`
-     * or its `plugins: [{ id: "web" }]` for web search). Merged into the request
+     * add provider-specific request shapes (e.g. OpenRouter's
+     * `plugins: [{ id: "web" }]` for web search). Merged into the request
      * after the standard params so it can override them.
      */
     buildRequestExtras(_config) {
         return {};
     }
+    /**
+     * The request field carrying `config.maxTokens`. OpenAI deprecated
+     * `max_tokens` in favor of `max_completion_tokens`, and its reasoning models
+     * reject `max_tokens` outright. Compat servers override this to send
+     * `max_tokens`, which is the field they reliably accept.
+     */
+    maxTokensParam(config) {
+        if (config.maxTokens === undefined) {
+            return {};
+        }
+        return { max_completion_tokens: config.maxTokens };
+    }
     /**
      * Extract provider-specific hosted-tool results (e.g. OpenRouter web_search
      * annotations) from a completion. Subclasses override; default returns none.
@@ -126,6 +138,7 @@ export class SmolOpenAi extends BaseClient {
             ...(config.reasoningEffort && {
                 reasoning_effort: config.reasoningEffort,
             }),
+            ...this.maxTokensParam(config),
             ...sanitizeAttributes(config.rawAttributes),
             ...this.buildRequestExtras(config),
         };

package/dist/clients/openaiCompat.d.ts

@@ -20,5 +20,6 @@ export declare class SmolOpenAiCompat extends SmolOpenAi {
         apiKey: string;
         baseURL: string;
     };
+    protected maxTokensParam(config: SmolConfig): Record<string, number>;
     protected resolveCostUsd(usage: any): number | undefined;
 }

package/dist/clients/openaiCompat.js

@@ -30,6 +30,14 @@ export class SmolOpenAiCompat extends SmolOpenAi {
         }
         return { apiKey, baseURL };
     }
+    // Compat servers (OpenRouter, DeepInfra, LiteLLM, vLLM, mlx_lm.server) all
+    // accept `max_tokens`; `max_completion_tokens` support is patchy.
+    maxTokensParam(config) {
+        if (config.maxTokens === undefined) {
+            return {};
+        }
+        return { max_tokens: config.maxTokens };
+    }
     resolveCostUsd(usage) {
         // Try the three common conventions across OpenAI-compatible providers.
         const c = usage?.cost ?? usage?.estimated_cost ?? usage?.cost_usd;

package/dist/clients/openrouter.d.ts

@@ -5,9 +5,8 @@ import type { SmolConfig, HostedToolResult } from "../types.js";
  *
  * - Baked base URL `https://openrouter.ai/api/v1` (override via config.baseUrl.openRouter).
  * - Key: config.apiKey.openRouter or env OPENROUTER_API_KEY.
- * - Cost: reads `usage.cost` (USD). OpenRouter only returns this when
- *   `usage: { include: true }` is set in the request body, which this client
- *   injects automatically via buildRequestExtras.
+ * - Cost: reads `usage.cost` (USD). OpenRouter includes this in every
+ *   response (in the final SSE chunk when streaming); no request flag needed.
  * - Hosted web_search: when config.hostedTools includes "web_search",
  *   injects `plugins: [{ id: "web", max_results: 5 }]` and parses
  *   message.annotations into a HostedToolResult.

package/dist/clients/openrouter.js

@@ -6,9 +6,8 @@ import { resolveApiKey, resolveBaseUrl } from "../util/provider.js";
  *
  * - Baked base URL `https://openrouter.ai/api/v1` (override via config.baseUrl.openRouter).
  * - Key: config.apiKey.openRouter or env OPENROUTER_API_KEY.
- * - Cost: reads `usage.cost` (USD). OpenRouter only returns this when
- *   `usage: { include: true }` is set in the request body, which this client
- *   injects automatically via buildRequestExtras.
+ * - Cost: reads `usage.cost` (USD). OpenRouter includes this in every
+ *   response (in the final SSE chunk when streaming); no request flag needed.
  * - Hosted web_search: when config.hostedTools includes "web_search",
  *   injects `plugins: [{ id: "web", max_results: 5 }]` and parses
  *   message.annotations into a HostedToolResult.
@@ -27,8 +26,7 @@ export class SmolOpenRouter extends SmolOpenAiCompat {
         return typeof usage?.cost === "number" ? usage.cost : undefined;
     }
     buildRequestExtras(config) {
-        // OpenRouter only returns usage.cost when this is set.
-        const extras = { usage: { include: true } };
+        const extras = {};
         if (config.hostedTools?.includes("web_search")) {
             extras.plugins = [{ id: "web", max_results: 5 }];
         }

package/dist/models.d.ts

@@ -176,6 +176,13 @@ export declare const textToSpeechModels: readonly [{
     readonly perCharacterCost: 0.00004;
     readonly maxInputChars: 200;
     readonly formats: readonly ["wav"];
+}, {
+    readonly type: "text-to-speech";
+    readonly modelName: "gemini-3.1-flash-tts-preview";
+    readonly provider: "google";
+    readonly inputTokenCost: 1;
+    readonly outputAudioTokenCost: 20;
+    readonly formats: readonly ["pcm", "wav"];
 }, {
     readonly type: "text-to-speech";
     readonly modelName: "gemini-2.5-flash-preview-tts";
@@ -688,7 +695,7 @@ export declare const textModels: readonly [{
         readonly inputTokenCost: 5;
         readonly cachedInputTokenCost: 0.5;
         readonly outputTokenCost: 22.5;
-        readonly thresholdTokens: 200000;
+        readonly thresholdTokens: 272000;
     };
     readonly reasoning: {
         readonly levels: readonly ["none", "low", "medium", "high", "xhigh"];
@@ -778,7 +785,7 @@ export declare const textModels: readonly [{
     readonly longContext: {
         readonly inputTokenCost: 60;
         readonly outputTokenCost: 270;
-        readonly thresholdTokens: 200000;
+        readonly thresholdTokens: 272000;
     };
     readonly reasoning: {
         readonly levels: readonly ["medium", "high", "xhigh"];
@@ -813,7 +820,7 @@ export declare const textModels: readonly [{
         readonly inputTokenCost: 10;
         readonly cachedInputTokenCost: 1;
         readonly outputTokenCost: 45;
-        readonly thresholdTokens: 200000;
+        readonly thresholdTokens: 272000;
     };
     readonly reasoning: {
         readonly levels: readonly ["none", "low", "medium", "high", "xhigh"];
@@ -845,7 +852,7 @@ export declare const textModels: readonly [{
     readonly longContext: {
         readonly inputTokenCost: 60;
         readonly outputTokenCost: 270;
-        readonly thresholdTokens: 200000;
+        readonly thresholdTokens: 272000;
     };
     readonly reasoning: {
         readonly levels: readonly ["none", "low", "medium", "high", "xhigh"];
@@ -866,6 +873,41 @@ export declare const textModels: readonly [{
     readonly structuredOutput: true;
     readonly temperatureSupported: false;
     readonly provider: "openai-responses";
+}, {
+    readonly type: "text";
+    readonly modelName: "gpt-6-astra";
+    readonly description: "GPT-6 Astra is OpenAI's most capable model, built for the hardest end-to-end work: complex reasoning, coding, computer use, research, and document creation. 1M context window. Standard pricing for ≤272K input tokens; prompts above that are billed at 2x input/cache and 1.5x output for the whole request. Knowledge cutoff: April 2026.";
+    readonly maxInputTokens: 1050000;
+    readonly maxOutputTokens: 128000;
+    readonly inputTokenCost: 10;
+    readonly cachedInputTokenCost: 1;
+    readonly outputTokenCost: 50;
+    readonly outputTokensPerSecond: 69;
+    readonly longContext: {
+        readonly inputTokenCost: 20;
+        readonly cachedInputTokenCost: 2;
+        readonly outputTokenCost: 75;
+        readonly thresholdTokens: 272000;
+    };
+    readonly reasoning: {
+        readonly levels: readonly ["low", "medium", "high", "xhigh", "max"];
+        readonly defaultLevel: "medium";
+        readonly canDisable: false;
+        readonly outputsThinking: false;
+        readonly outputsSignatures: false;
+    };
+    readonly modalities: {
+        readonly input: readonly ["text", "image", "pdf"];
+        readonly output: readonly ["text"];
+    };
+    readonly knowledge: "2026-04-30";
+    readonly releaseDate: "2026-09-04";
+    readonly lastUpdated: "2026-09-04";
+    readonly family: "gpt";
+    readonly openWeights: false;
+    readonly structuredOutput: true;
+    readonly temperatureSupported: false;
+    readonly provider: "openai";
 }, {
     readonly type: "text";
     readonly modelName: "gpt-5.6-sol";
@@ -875,12 +917,12 @@ export declare const textModels: readonly [{
     readonly inputTokenCost: 4;
     readonly cachedInputTokenCost: 0.4;
     readonly outputTokenCost: 20;
-    readonly outputTokensPerSecond: 71;
+    readonly outputTokensPerSecond: 77;
     readonly longContext: {
         readonly inputTokenCost: 8;
         readonly cachedInputTokenCost: 0.8;
         readonly outputTokenCost: 30;
-        readonly thresholdTokens: 200000;
+        readonly thresholdTokens: 272000;
     };
     readonly reasoning: {
         readonly levels: readonly ["none", "low", "medium", "high", "xhigh", "max"];
@@ -910,12 +952,12 @@ export declare const textModels: readonly [{
     readonly inputTokenCost: 2;
     readonly cachedInputTokenCost: 0.2;
     readonly outputTokenCost: 12;
-    readonly outputTokensPerSecond: 98;
+    readonly outputTokensPerSecond: 106;
     readonly longContext: {
         readonly inputTokenCost: 4;
         readonly cachedInputTokenCost: 0.4;
         readonly outputTokenCost: 18;
-        readonly thresholdTokens: 200000;
+        readonly thresholdTokens: 272000;
     };
     readonly reasoning: {
         readonly levels: readonly ["none", "low", "medium", "high", "xhigh", "max"];
@@ -945,12 +987,12 @@ export declare const textModels: readonly [{
     readonly inputTokenCost: 0.2;
     readonly cachedInputTokenCost: 0.02;
     readonly outputTokenCost: 1.2;
-    readonly outputTokensPerSecond: 116;
+    readonly outputTokensPerSecond: 165;
     readonly longContext: {
         readonly inputTokenCost: 0.4;
         readonly cachedInputTokenCost: 0.04;
         readonly outputTokenCost: 1.8;
-        readonly thresholdTokens: 200000;
+        readonly thresholdTokens: 272000;
     };
     readonly reasoning: {
         readonly levels: readonly ["none", "low", "medium", "high", "xhigh", "max"];
@@ -980,7 +1022,7 @@ export declare const textModels: readonly [{
     readonly inputTokenCost: 2;
     readonly cachedInputTokenCost: 0.2;
     readonly outputTokenCost: 12;
-    readonly outputTokensPerSecond: 133;
+    readonly outputTokensPerSecond: 124;
     readonly longContext: {
         readonly inputTokenCost: 4;
         readonly cachedInputTokenCost: 0.4;
@@ -1043,7 +1085,7 @@ export declare const textModels: readonly [{
     readonly inputTokenCost: 0.75;
     readonly cachedInputTokenCost: 0.075;
     readonly outputTokenCost: 3.75;
-    readonly outputTokensPerSecond: 312;
+    readonly outputTokensPerSecond: 329;
     readonly inputAudioTokenCost: 1.5;
     readonly reasoning: {
         readonly levels: readonly ["low", "medium", "high"];
@@ -1455,6 +1497,7 @@ export declare const textModels: readonly [{
     readonly cachedInputTokenCost: 0.25;
     readonly cacheCreationInputTokenCost: 12.5;
     readonly outputTokenCost: 50;
+    readonly outputTokensPerSecond: 69;
     readonly reasoning: {
         readonly thinkingStyle: "adaptive";
         readonly levels: readonly ["low", "medium", "high", "xhigh", "max"];
@@ -1484,6 +1527,7 @@ export declare const textModels: readonly [{
     readonly cachedInputTokenCost: 0.5;
     readonly cacheCreationInputTokenCost: 6.25;
     readonly outputTokenCost: 25;
+    readonly outputTokensPerSecond: 59;
     readonly reasoning: {
         readonly thinkingStyle: "adaptive";
         readonly levels: readonly ["low", "medium", "high", "xhigh", "max"];
@@ -1625,7 +1669,7 @@ export declare const textModels: readonly [{
     readonly cachedInputTokenCost: 0.2;
     readonly cacheCreationInputTokenCost: 2.5;
     readonly outputTokenCost: 10;
-    readonly outputTokensPerSecond: 71;
+    readonly outputTokensPerSecond: 81;
     readonly reasoning: {
         readonly thinkingStyle: "adaptive";
         readonly levels: readonly ["low", "medium", "high", "xhigh", "max"];

package/dist/models.js

@@ -92,6 +92,14 @@ export const textToSpeechModels = [
     },
     // 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-3.1-flash-tts-preview",
+        provider: "google",
+        inputTokenCost: 1.0, // $/1M text-input tokens, verified 2026-09-21
+        outputAudioTokenCost: 20.0, // $/1M audio-output tokens
+        formats: ["pcm", "wav"],
+    },
     {
         type: "text-to-speech",
         modelName: "gemini-2.5-flash-preview-tts",
@@ -626,7 +634,7 @@ export const textModels = [
             inputTokenCost: 5,
             cachedInputTokenCost: 0.5,
             outputTokenCost: 22.5,
-            thresholdTokens: 200000,
+            thresholdTokens: 272000,
         },
         reasoning: {
             levels: ["none", "low", "medium", "high", "xhigh"],
@@ -719,7 +727,7 @@ export const textModels = [
         longContext: {
             inputTokenCost: 60,
             outputTokenCost: 270,
-            thresholdTokens: 200000,
+            thresholdTokens: 272000,
         },
         reasoning: {
             levels: ["medium", "high", "xhigh"],
@@ -755,7 +763,7 @@ export const textModels = [
             inputTokenCost: 10,
             cachedInputTokenCost: 1,
             outputTokenCost: 45,
-            thresholdTokens: 200000,
+            thresholdTokens: 272000,
         },
         reasoning: {
             levels: ["none", "low", "medium", "high", "xhigh"],
@@ -788,7 +796,7 @@ export const textModels = [
         longContext: {
             inputTokenCost: 60,
             outputTokenCost: 270,
-            thresholdTokens: 200000,
+            thresholdTokens: 272000,
         },
         reasoning: {
             levels: ["none", "low", "medium", "high", "xhigh"],
@@ -810,6 +818,42 @@ export const textModels = [
         temperatureSupported: false,
         provider: "openai-responses",
     },
+    {
+        type: "text",
+        modelName: "gpt-6-astra",
+        description: "GPT-6 Astra is OpenAI's most capable model, built for the hardest end-to-end work: complex reasoning, coding, computer use, research, and document creation. 1M context window. Standard pricing for ≤272K input tokens; prompts above that are billed at 2x input/cache and 1.5x output for the whole request. Knowledge cutoff: April 2026.",
+        maxInputTokens: 1050000,
+        maxOutputTokens: 128000,
+        inputTokenCost: 10,
+        cachedInputTokenCost: 1,
+        outputTokenCost: 50,
+        outputTokensPerSecond: 69,
+        longContext: {
+            inputTokenCost: 20,
+            cachedInputTokenCost: 2,
+            outputTokenCost: 75,
+            thresholdTokens: 272000,
+        },
+        reasoning: {
+            levels: ["low", "medium", "high", "xhigh", "max"],
+            defaultLevel: "medium",
+            canDisable: false,
+            outputsThinking: false,
+            outputsSignatures: false,
+        },
+        modalities: {
+            input: ["text", "image", "pdf"],
+            output: ["text"],
+        },
+        knowledge: "2026-04-30",
+        releaseDate: "2026-09-04",
+        lastUpdated: "2026-09-04",
+        family: "gpt",
+        openWeights: false,
+        structuredOutput: true,
+        temperatureSupported: false,
+        provider: "openai",
+    },
     {
         type: "text",
         modelName: "gpt-5.6-sol",
@@ -819,12 +863,12 @@ export const textModels = [
         inputTokenCost: 4,
         cachedInputTokenCost: 0.4,
         outputTokenCost: 20,
-        outputTokensPerSecond: 71,
+        outputTokensPerSecond: 77,
         longContext: {
             inputTokenCost: 8,
             cachedInputTokenCost: 0.8,
             outputTokenCost: 30,
-            thresholdTokens: 200000,
+            thresholdTokens: 272000,
         },
         reasoning: {
             levels: ["none", "low", "medium", "high", "xhigh", "max"],
@@ -855,12 +899,12 @@ export const textModels = [
         inputTokenCost: 2,
         cachedInputTokenCost: 0.2,
         outputTokenCost: 12,
-        outputTokensPerSecond: 98,
+        outputTokensPerSecond: 106,
         longContext: {
             inputTokenCost: 4,
             cachedInputTokenCost: 0.4,
             outputTokenCost: 18,
-            thresholdTokens: 200000,
+            thresholdTokens: 272000,
         },
         reasoning: {
             levels: ["none", "low", "medium", "high", "xhigh", "max"],
@@ -891,12 +935,12 @@ export const textModels = [
         inputTokenCost: 0.2,
         cachedInputTokenCost: 0.02,
         outputTokenCost: 1.2,
-        outputTokensPerSecond: 116,
+        outputTokensPerSecond: 165,
         longContext: {
             inputTokenCost: 0.4,
             cachedInputTokenCost: 0.04,
             outputTokenCost: 1.8,
-            thresholdTokens: 200000,
+            thresholdTokens: 272000,
         },
         reasoning: {
             levels: ["none", "low", "medium", "high", "xhigh", "max"],
@@ -927,7 +971,7 @@ export const textModels = [
         inputTokenCost: 2,
         cachedInputTokenCost: 0.2,
         outputTokenCost: 12,
-        outputTokensPerSecond: 133,
+        outputTokensPerSecond: 124,
         longContext: {
             inputTokenCost: 4,
             cachedInputTokenCost: 0.4,
@@ -992,7 +1036,7 @@ export const textModels = [
         inputTokenCost: 0.75,
         cachedInputTokenCost: 0.075,
         outputTokenCost: 3.75,
-        outputTokensPerSecond: 312,
+        outputTokensPerSecond: 329,
         inputAudioTokenCost: 1.5,
         reasoning: {
             levels: ["low", "medium", "high"],
@@ -1424,6 +1468,7 @@ export const textModels = [
         cachedInputTokenCost: 0.25,
         cacheCreationInputTokenCost: 12.5,
         outputTokenCost: 50,
+        outputTokensPerSecond: 69,
         reasoning: {
             thinkingStyle: "adaptive",
             levels: ["low", "medium", "high", "xhigh", "max"],
@@ -1454,6 +1499,7 @@ export const textModels = [
         cachedInputTokenCost: 0.5,
         cacheCreationInputTokenCost: 6.25,
         outputTokenCost: 25,
+        outputTokensPerSecond: 59,
         reasoning: {
             thinkingStyle: "adaptive",
             levels: ["low", "medium", "high", "xhigh", "max"],
@@ -1600,7 +1646,7 @@ export const textModels = [
         cachedInputTokenCost: 0.2,
         cacheCreationInputTokenCost: 2.5,
         outputTokenCost: 10,
-        outputTokensPerSecond: 71,
+        outputTokensPerSecond: 81,
         reasoning: {
             thinkingStyle: "adaptive",
             levels: ["low", "medium", "high", "xhigh", "max"],
@@ -1939,7 +1985,7 @@ export const hostedTools = [
         category: "code_execution",
         description: "Run code in a sandboxed container.",
         providerToolId: "code_execution",
-        pricing: { unit: "per_hour", amount: 0.05, freeAllowance: "50 container-hours/day", note: "Free when used with web_search or web_fetch." },
+        pricing: { unit: "per_hour", amount: 0.05, freeAllowance: "1,550 container-hours/month", note: "Free when used with web_search or web_fetch. 5-minute minimum execution time per container." },
     },
     {
         name: "web_search",
@@ -2014,7 +2060,12 @@ export const hostedTools = [
         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.6-flash", "gemini-3.7-flash", "gemini-3.8-flash", "gemini-3.1-flash-lite", "gemini-3.5-flash-lite"],
-        pricing: { unit: "per_call", note: "Gemini 3 family only; see Google pricing." },
+        pricing: {
+            unit: "per_call",
+            amount: 0.014,
+            freeAllowance: "5,000 grounded prompts/month (Gemini 3)",
+            note: "$14 per 1,000 search queries on the Gemini 3 family.",
+        },
     },
     {
         name: "web_search",

package/dist/speech/baseSpeechClient.d.ts

@@ -11,6 +11,11 @@ export type SpeechClientConfig = {
     /** Base-URL map (for OpenAI-compatible providers); read via resolveBaseUrl. */
     baseUrl?: SmolConfig["baseUrl"];
     voice: string;
+    /** How the speech should sound, in plain words: "Alarmed and urgent."
+     *  Passed through as-is by the OpenAI-shaped providers (openai, groq,
+     *  openai-compat, mlx); whether the model reads it is up to the model
+     *  (OpenAI's tts-1 and tts-1-hd do not). The google provider ignores it. */
+    instructions?: string;
     modelData?: ModelDataBlob;
     /** Output format; provider-specific vocabulary (OpenAI: mp3/opus/aac/flac/wav/pcm). */
     format?: string;

package/dist/speech/mlx.d.ts

@@ -0,0 +1,23 @@
+import OpenAI from "openai";
+import { Result } from "../types/result.js";
+import type { SpeakFormat } from "../util/audioMime.js";
+import { OpenAISpeechClient } from "./openai.js";
+import type { SpeechResult } from "../speech.js";
+/**
+ * Speech from an MLX server on localhost, usually `agency local serve
+ * --speech <model>`. The same request the OpenAI client makes, with the
+ * things the chat and embedding mlx clients also fix: the base URL has a
+ * default, the key is a placeholder the server ignores, and the cost is
+ * zero. It also never retries. The server runs one generation at a time,
+ * so a retry would wait behind the request that just timed out and then
+ * generate the same text again.
+ */
+export declare class MlxSpeechClient extends OpenAISpeechClient {
+    protected makeClient(): OpenAI;
+    protected requiresKey(): boolean;
+    protected defaultFormat(): SpeakFormat;
+    /** Local speech is free. Set after the base class's cost pass, so model
+     *  data that prices this model cannot override it (matching the chat mlx
+     *  client, whose provider cost of 0 wins over registry pricing). */
+    speak(text: string): Promise<Result<SpeechResult>>;
+}

package/dist/speech/mlx.js

@@ -0,0 +1,49 @@
+import OpenAI from "openai";
+import { success } from "../types/result.js";
+import { resolveBaseUrl } from "../util/provider.js";
+import { OpenAISpeechClient } from "./openai.js";
+/** How long one request may take. Equal to the SDK default; stated here so
+ *  the ceiling is visible. A local model generating a long piece of text is
+ *  slow, and the caller keeps its requests short. */
+const MLX_SPEECH_TIMEOUT_MS = 600_000;
+/**
+ * Speech from an MLX server on localhost, usually `agency local serve
+ * --speech <model>`. The same request the OpenAI client makes, with the
+ * things the chat and embedding mlx clients also fix: the base URL has a
+ * default, the key is a placeholder the server ignores, and the cost is
+ * zero. It also never retries. The server runs one generation at a time,
+ * so a retry would wait behind the request that just timed out and then
+ * generate the same text again.
+ */
+export class MlxSpeechClient extends OpenAISpeechClient {
+    makeClient() {
+        // resolveBaseUrl always returns a value for "mlx" (it has a default).
+        const baseURL = resolveBaseUrl("mlx", { baseUrl: this.config.baseUrl });
+        // The OpenAI SDK refuses an empty key. The local server never reads it.
+        return new OpenAI({
+            apiKey: "mlx-local",
+            baseURL,
+            maxRetries: 0,
+            timeout: MLX_SPEECH_TIMEOUT_MS,
+        });
+    }
+    requiresKey() {
+        return false;
+    }
+    defaultFormat() {
+        return "wav";
+    }
+    /** Local speech is free. Set after the base class's cost pass, so model
+     *  data that prices this model cannot override it (matching the chat mlx
+     *  client, whose provider cost of 0 wins over registry pricing). */
+    async speak(text) {
+        const result = await super.speak(text);
+        if (!result.success) {
+            return result;
+        }
+        return success({
+            ...result.value,
+            cost: { inputCost: 0, outputCost: 0, totalCost: 0, currency: "USD" },
+        });
+    }
+}

package/dist/speech/openai.d.ts

@@ -10,5 +10,8 @@ export declare class OpenAISpeechClient extends BaseSpeechClient {
     protected defaultFormat(): SpeakFormat;
     /** Provider-specific diagnostic when no API key is resolved. Subclasses override. */
     protected noKeyMessage(): string;
+    /** Whether a request needs an API key at all. A local server ignores the
+     *  key, and its client says so by returning false. */
+    protected requiresKey(): boolean;
     protected _speak(text: string): Promise<Result<SpeechResult>>;
 }

package/dist/speech/openai.js

@@ -15,10 +15,15 @@ export class OpenAISpeechClient extends BaseSpeechClient {
     noKeyMessage() {
         return "No OpenAI API key provided. Set apiKey.openAi or OPENAI_API_KEY.";
     }
+    /** Whether a request needs an API key at all. A local server ignores the
+     *  key, and its client says so by returning false. */
+    requiresKey() {
+        return true;
+    }
     // No try/catch here: BaseSpeechClient.speak() is the single
     // redacting/logging exception boundary.
     async _speak(text) {
-        if (!this.config.apiKey) {
+        if (this.requiresKey() && !this.config.apiKey) {
             return failure(this.noKeyMessage());
         }
         // The shared contract carries format as a plain string; narrow to OpenAI's
@@ -40,6 +45,9 @@ export class OpenAISpeechClient extends BaseSpeechClient {
         if (this.config.speed !== undefined) {
             params.speed = this.config.speed;
         }
+        if (this.config.instructions !== undefined && this.config.instructions !== "") {
+            params.instructions = this.config.instructions;
+        }
         const res = await client.audio.speech.create(params, { signal: this.config.abortSignal });
         const audio = new Uint8Array(await res.arrayBuffer());
         const result = { audio, mimeType };

package/dist/speech.d.ts

@@ -7,6 +7,11 @@ import { BaseSpeechClient, SpeechClientConfig } from "./speech/baseSpeechClient.
 export type SpeakOptions = {
     model: string;
     voice: string;
+    /** How the speech should sound, in plain words: "Alarmed and urgent."
+     *  Passed through as-is by the OpenAI-shaped providers (openai, groq,
+     *  openai-compat, mlx); whether the model reads it is up to the model
+     *  (OpenAI's tts-1 and tts-1-hd do not). The google provider ignores it. */
+    instructions?: string;
     provider?: string;
     modelData?: ModelDataBlob;
     apiKey?: SmolConfig["apiKey"];

package/dist/speech.js

@@ -6,12 +6,14 @@ import { OpenAISpeechClient } from "./speech/openai.js";
 import { GroqSpeechClient } from "./speech/groq.js";
 import { GoogleSpeechClient } from "./speech/google.js";
 import { OpenAiCompatSpeechClient } from "./speech/openaiCompat.js";
+import { MlxSpeechClient } from "./speech/mlx.js";
 // Checked before the user registry so a registered "openai" can't hijack the built-in.
 const builtinClients = Object.create(null);
 builtinClients["openai"] = OpenAISpeechClient;
 builtinClients["groq"] = GroqSpeechClient;
 builtinClients["google"] = GoogleSpeechClient;
 builtinClients["openai-compat"] = OpenAiCompatSpeechClient;
+builtinClients["mlx"] = MlxSpeechClient;
 // Null-prototype so provider names like "toString"/"__proto__" can't collide
 // with Object.prototype or pollute the registry.
 const registered = Object.create(null);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smoltalk",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "description": "A common interface for LLM APIs",
   "homepage": "https://github.com/egonSchiele/smoltalk",
   "files": [