smoltalk 0.14.0 → 0.14.1

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/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.1",
   "description": "A common interface for LLM APIs",
   "homepage": "https://github.com/egonSchiele/smoltalk",
   "files": [