smoltalk 0.8.3 → 0.9.0

package/README.md

@@ -8,15 +8,6 @@ Smoltalk exposes a common API to different LLM providers, with built-in cost tra
 pnpm install smoltalk
 ```
 
-> **Upgrading to 0.6.x?** The flat API-key/host fields on `SmolConfig` have
-> been removed in favor of nested `apiKey` and `baseUrl` maps. Migration:
-> ```diff
-> -{ openAiApiKey: "sk-...",   googleApiKey: "...", ollamaHost: "http://..." }
-> +{ apiKey: { openAi: "sk-...", google: "..." }, baseUrl: { ollama: "http://..." } }
-> ```
-> Env-var fallbacks are unchanged (`OPENAI_API_KEY`, `GEMINI_API_KEY`,
-> `ANTHROPIC_API_KEY`, `OLLAMA_HOST`).
-
 ## Hello world example
 
 ```typescript
@@ -335,6 +326,80 @@ a `hostedTools` catalog (`getHostedTools()`); the published file is kept current
 by a daily CI job that translates [models.dev](https://models.dev) into
 smoltalk's shape.
 
+## Custom models & pricing
+
+If you use a model that isn't in smoltalk's baked-in catalog (a self-hosted
+model, a brand-new release, an OpenAI-compatible endpoint), smoltalk has no
+pricing for it and the `cost` field is simply omitted from the result — nothing
+errors, you just get `usage` without `cost`. Teach it the price and cost
+tracking starts working.
+
+**One model — `registerTextModel` (recommended).** Register once at startup:
+
+```ts
+import { registerTextModel, textSync, userMessage } from "smoltalk";
+
+registerTextModel({
+  modelName: "my-model",
+  provider: "openai-compat", // must match the provider you call with (see below)
+  inputTokenCost: 0.5, // USD per 1M input tokens
+  outputTokenCost: 1.5, // USD per 1M output tokens
+  cachedInputTokenCost: 0.05, // optional
+  cacheCreationInputTokenCost: 0.625, // optional
+  maxInputTokens: 128000, // required by the type, even if you only want pricing
+  maxOutputTokens: 8192,
+});
+
+const messages = [userMessage("hello")];
+const res = await textSync({
+  model: "my-model",
+  provider: "openai-compat",
+  baseUrl: { openAiCompat: "https://my-endpoint/v1" },
+  messages,
+});
+// res.value.cost is now populated from the rates above.
+```
+
+**Per-call only — `config.modelData`.** When you can't register globally (e.g.
+per-tenant rates), pass a minimal blob for a single call. It layers over the
+baseline exactly like a refresh blob:
+
+```ts
+import { textSync, userMessage, type ModelDataBlob } from "smoltalk";
+
+const modelData: ModelDataBlob = {
+  schemaVersion: 1,
+  generatedAt: new Date().toISOString(),
+  hostedTools: [],
+  models: [
+    {
+      type: "text",
+      modelName: "my-model",
+      provider: "openai-compat",
+      maxInputTokens: 128000,
+      maxOutputTokens: 8192,
+      inputTokenCost: 0.5,
+      outputTokenCost: 1.5,
+    },
+  ],
+};
+
+const messages = [userMessage("hello")];
+await textSync({ model: "my-model", provider: "openai-compat", messages, modelData });
+```
+
+**The provider must match.** The registry is keyed by `provider:modelName`, so
+the `provider` you register (or put in the blob) has to equal the `provider` you
+pass at call time. Registering `my-model` under `"openai-compat"` but calling it
+with `provider: "openrouter"` looks up a different key, finds no price, and
+silently drops the `cost` field. When in doubt, register under the same provider
+string you call with.
+
+Overriding an entry that *is* in the catalog works the same way — merges are
+field-by-field (see "Refreshing model data" above), so registering just
+`inputTokenCost` / `outputTokenCost` for a known model updates only those fields
+and leaves its limits and capabilities intact.
+
 ## Hosted tools catalog
 
 Each cloud provider offers server-side "hosted" tools (web search, code

package/dist/classes/ToolCall.js

@@ -79,17 +79,25 @@ export class ToolCall {
         };
     }
     toGoogle() {
-        return {
-            functionCall: {
-                name: this.name,
-                args: this.arguments,
-            },
-            // Gemini 3 requires the original thought signature echoed back on the
-            // function-call part; omitting it fails validation during tool use.
-            ...(this._thoughtSignature !== undefined && {
-                thoughtSignature: this._thoughtSignature,
-            }),
+        const functionCall = {
+            name: this.name,
+            args: this.arguments,
         };
+        // Echo the id when we have one: the Gemini API pairs a functionResponse
+        // back to its functionCall by id when present. Omit it when empty — current
+        // Gemini 3 preview models issue no ids, and an empty id is not a valid key.
+        if (this._id !== "") {
+            functionCall.id = this._id;
+        }
+        const result = {
+            functionCall,
+        };
+        // Gemini 3 requires the original thought signature echoed back on the
+        // function-call part; omitting it fails validation during tool use.
+        if (this._thoughtSignature !== undefined) {
+            result.thoughtSignature = this._thoughtSignature;
+        }
+        return result;
     }
     toOpenAIResponseInputItem() {
         return {

package/dist/classes/message/ToolMessage.js

@@ -91,18 +91,21 @@ export class ToolMessage extends BaseMessage {
         };
     }
     toGoogleMessage() {
+        const functionResponse = {
+            name: this.name,
+            response: {
+                result: this.content,
+            },
+        };
+        // Echo the id so Gemini can pair this response to its call by id — the
+        // documented matching mechanism. Only when non-empty: current Gemini 3
+        // preview models issue no ids, and an empty id is not a valid key.
+        if (this.tool_call_id !== "") {
+            functionResponse.id = this.tool_call_id;
+        }
         return {
             role: "user",
-            parts: [
-                {
-                    functionResponse: {
-                        name: this.name,
-                        response: {
-                            result: this.content,
-                        },
-                    },
-                },
-            ],
+            parts: [{ functionResponse }],
         };
     }
     toOllamaMessage() {

package/dist/clients/google.d.ts

@@ -3,6 +3,7 @@ import { PromptResult, Result, SmolClient, SmolConfig, StreamChunk } from "../ty
 import { BaseClient } from "./baseClient.js";
 import { ModelName } from "../models.js";
 import { HostedToolResult } from "../types.js";
+import type { Message } from "../classes/message/index.js";
 export type SmolGoogleConfig = SmolConfig;
 export declare function googleWebSearchEntries(hostedTools?: string[]): any[];
 /**
@@ -20,6 +21,7 @@ export declare function googleWebSearchEntries(hostedTools?: string[]): any[];
  * See egonSchiele/agency-lang#495.
  */
 export declare function geminiSupportsToolCirculation(model: string): boolean;
+export declare function reorderToolResultsForGemini(messages: Message[]): Message[];
 export declare function parseGoogleHostedTools(result: any, provider: string, model: string): HostedToolResult[];
 type GeneratedRequest = {
     contents: Content[];

package/dist/clients/google.js

@@ -39,6 +39,118 @@ export function geminiSupportsToolCirculation(model) {
         return true;
     return parseInt(m[1], 10) >= 3;
 }
+// Reorder each round's tool results to match the order of the calls that
+// produced them. Two documented Gemini behaviors make this necessary:
+//   - A function call carries an optional `id`, and a response is paired back to
+//     its call by echoing that id.
+//     https://ai.google.dev/gemini-api/docs/function-calling
+//   - Parts must be returned in the order received (responses in call order:
+//     FC1,FC2 -> FR1,FR2), and the thought signature rides ONLY the first
+//     function call of a parallel batch; omitting it 400s on Gemini 3. So part
+//     order is load-bearing independent of ids.
+//     https://ai.google.dev/gemini-api/docs/generate-content/thought-signatures
+// Current Gemini 3 preview models are observed to emit no function-call ids, so
+// on them pairing is purely positional. A caller whose results arrive in
+// completion order (rather than call order) would otherwise feed tool A's answer
+// to tool B and break thought-signature validation.
+//
+// For every assistant message that carries toolCalls, the run of ToolMessages
+// immediately following it is reordered. The run ends at the first non-tool
+// message: any results the caller interleaved AFTER a non-tool message are left
+// where they are — moving messages across an interloper is repair, not reorder.
+//   1. By id, when both the call and a response have non-empty ids (order-free,
+//      takes global priority so an id match is never stolen by a name match).
+//   2. By name + occurrence otherwise: the k-th response named X answers the
+//      k-th call named X.
+// NEVER drop a message: a response matching no call (or any surplus) is kept at
+// the end of the run in its original relative order. A reorder that lost a
+// message would turn a mispairing bug into a missing-result bug, which is worse.
+export function reorderToolResultsForGemini(messages) {
+    const out = [];
+    let i = 0;
+    while (i < messages.length) {
+        const msg = messages[i];
+        out.push(msg);
+        const toolCalls = msg.role === "assistant" ? msg.toolCalls : undefined;
+        if (!toolCalls || toolCalls.length === 0) {
+            i += 1;
+            continue;
+        }
+        // Collect the contiguous run of tool results that answers this round.
+        let j = i + 1;
+        const run = [];
+        while (j < messages.length && messages[j].role === "tool") {
+            run.push(messages[j]);
+            j += 1;
+        }
+        if (run.length === 0) {
+            i += 1;
+            continue;
+        }
+        out.push(...orderRunToMatchCalls(toolCalls, run));
+        i = j;
+    }
+    return out;
+}
+function orderRunToMatchCalls(toolCalls, run) {
+    const used = new Array(run.length).fill(false);
+    // assignment[callIndex] = index into `run`, or -1 if that call has no result.
+    const assignment = new Array(toolCalls.length).fill(-1);
+    function runId(k) {
+        const m = run[k];
+        if (m.role === "tool") {
+            return m.tool_call_id;
+        }
+        return "";
+    }
+    function runName(k) {
+        const m = run[k];
+        if (m.role === "tool") {
+            return m.name;
+        }
+        return "";
+    }
+    // Pass 1: id pairing (both sides non-empty), global priority.
+    toolCalls.forEach((call, ci) => {
+        if (call.id === "")
+            return;
+        const ri = run.findIndex((_r, k) => !used[k] && runId(k) !== "" && runId(k) === call.id);
+        if (ri !== -1) {
+            assignment[ci] = ri;
+            used[ri] = true;
+        }
+    });
+    // Pass 2: name + occurrence, for calls still unmatched. findIndex takes the
+    // first unused same-name response, so the k-th call named X pairs with the
+    // k-th response named X.
+    //
+    // Garbage-in caveat: if a call and its only same-name response carry DIFFERENT
+    // non-empty ids (one side lost or mangled its id), pass 1 misses and pass 2
+    // pairs them by name — emitting functionCall.id != functionResponse.id in that
+    // slot, which an id-pairing model would see as a contradiction. The input was
+    // already inconsistent; we pair positionally rather than drop the result. Not
+    // a reorder bug.
+    toolCalls.forEach((call, ci) => {
+        if (assignment[ci] !== -1)
+            return;
+        const ri = run.findIndex((_r, k) => !used[k] && runName(k) === call.name);
+        if (ri !== -1) {
+            assignment[ci] = ri;
+            used[ri] = true;
+        }
+    });
+    const ordered = [];
+    for (const ri of assignment) {
+        if (ri !== -1)
+            ordered.push(run[ri]);
+    }
+    // Never drop: append any unmatched/surplus responses in original order.
+    for (let k = 0; k < run.length; k++) {
+        if (!used[k])
+            ordered.push(run[k]);
+    }
+    return ordered;
+}
 export function parseGoogleHostedTools(result, provider, model) {
     const queries = [];
     const sources = [];
@@ -136,7 +248,12 @@ export class SmolGoogle extends BaseClient {
             }
             return true;
         });
-        const messages = contentMessages.map((msg) => msg.toGoogleMessage());
+        // Normalize tool-result ordering before conversion: Gemini pairs each
+        // functionResponse to its functionCall (by id on 3.5+, strictly by position
+        // on the Gemini 3 family), so results must leave in call order regardless of
+        // the order the caller supplied them. See reorderToolResultsForGemini.
+        const orderedMessages = reorderToolResultsForGemini(contentMessages);
+        const messages = orderedMessages.map((msg) => msg.toGoogleMessage());
         const tools = (config.tools || []).map((tool) => {
             return zodToGoogleTool(tool.name, tool.schema, {
                 description: tool.description,
@@ -341,7 +458,12 @@ export class SmolGoogle extends BaseClient {
                         const functionCall = part.functionCall;
                         // Gemini 3 rides the thought signature on the same part as the
                         // function call; capture it so it can be echoed back during tool use.
-                        toolCalls.push(new ToolCall("", functionCall.name, functionCall.args, {
+                        toolCalls.push(
+                        // Keep functionCall.id so id-based pairing can round-trip. Do NOT
+                        // fall back to the name (as the streaming path does for its Map
+                        // key): two parallel calls to the same tool would share a fake id
+                        // and re-create the pairing bug at the id layer.
+                        new ToolCall(functionCall.id || "", functionCall.name, functionCall.args, {
                             thoughtSignature: part.thoughtSignature,
                         }));
                     }

package/dist/models.d.ts

@@ -1228,6 +1228,35 @@ export declare const textModels: readonly [{
     readonly costUnit: "characters";
     readonly disabled: true;
     readonly provider: "google";
+}, {
+    readonly type: "text";
+    readonly modelName: "claude-fable-5";
+    readonly description: "Anthropic's most capable widely released model, for the most demanding reasoning and long-horizon agentic work. Thinking is always on (cannot be disabled); the raw chain of thought is never returned. Requires 30-day data retention (not available under zero data retention). 1M context window, 128K max output.";
+    readonly maxInputTokens: 1000000;
+    readonly maxOutputTokens: 128000;
+    readonly inputTokenCost: 10;
+    readonly cachedInputTokenCost: 1;
+    readonly cacheCreationInputTokenCost: 12.5;
+    readonly outputTokenCost: 50;
+    readonly reasoning: {
+        readonly thinkingStyle: "adaptive";
+        readonly levels: readonly ["low", "medium", "high", "xhigh", "max"];
+        readonly defaultLevel: "high";
+        readonly canDisable: false;
+        readonly outputsThinking: true;
+        readonly outputsSignatures: true;
+    };
+    readonly modalities: {
+        readonly input: readonly ["text", "image", "pdf"];
+        readonly output: readonly ["text"];
+    };
+    readonly knowledge: "2026-01";
+    readonly releaseDate: "2026-06-09";
+    readonly lastUpdated: "2026-06-09";
+    readonly family: "claude-fable";
+    readonly openWeights: false;
+    readonly temperatureSupported: false;
+    readonly provider: "anthropic";
 }, {
     readonly type: "text";
     readonly modelName: "claude-opus-4-8";
@@ -1310,6 +1339,35 @@ export declare const textModels: readonly [{
     readonly openWeights: false;
     readonly temperatureSupported: true;
     readonly provider: "anthropic";
+}, {
+    readonly type: "text";
+    readonly modelName: "claude-sonnet-5";
+    readonly description: "The best combination of speed and intelligence in the Sonnet tier, with near-Opus quality on coding and agentic work. Adaptive thinking on by default; supports the full low/medium/high/xhigh/max effort range. New tokenizer (~30% more tokens for the same text vs Sonnet 4.6). Standard pricing $3/$15; introductory $2/$10 per MTok through 2026-08-31. 1M context window, 128K max output.";
+    readonly maxInputTokens: 1000000;
+    readonly maxOutputTokens: 128000;
+    readonly inputTokenCost: 3;
+    readonly cachedInputTokenCost: 0.3;
+    readonly cacheCreationInputTokenCost: 3.75;
+    readonly outputTokenCost: 15;
+    readonly reasoning: {
+        readonly thinkingStyle: "adaptive";
+        readonly levels: readonly ["low", "medium", "high", "xhigh", "max"];
+        readonly defaultLevel: "high";
+        readonly canDisable: true;
+        readonly outputsThinking: true;
+        readonly outputsSignatures: true;
+    };
+    readonly modalities: {
+        readonly input: readonly ["text", "image", "pdf"];
+        readonly output: readonly ["text"];
+    };
+    readonly knowledge: "2026-01";
+    readonly releaseDate: "2026-06-30";
+    readonly lastUpdated: "2026-06-30";
+    readonly family: "claude-sonnet";
+    readonly openWeights: false;
+    readonly temperatureSupported: false;
+    readonly provider: "anthropic";
 }, {
     readonly type: "text";
     readonly modelName: "claude-sonnet-4-6";

package/dist/models.js

@@ -1206,6 +1206,36 @@ export const textModels = [
         disabled: true,
         provider: "google",
     },
+    {
+        type: "text",
+        modelName: "claude-fable-5",
+        description: "Anthropic's most capable widely released model, for the most demanding reasoning and long-horizon agentic work. Thinking is always on (cannot be disabled); the raw chain of thought is never returned. Requires 30-day data retention (not available under zero data retention). 1M context window, 128K max output.",
+        maxInputTokens: 1000000,
+        maxOutputTokens: 128000,
+        inputTokenCost: 10,
+        cachedInputTokenCost: 1,
+        cacheCreationInputTokenCost: 12.5,
+        outputTokenCost: 50,
+        reasoning: {
+            thinkingStyle: "adaptive",
+            levels: ["low", "medium", "high", "xhigh", "max"],
+            defaultLevel: "high",
+            canDisable: false,
+            outputsThinking: true,
+            outputsSignatures: true,
+        },
+        modalities: {
+            input: ["text", "image", "pdf"],
+            output: ["text"],
+        },
+        knowledge: "2026-01",
+        releaseDate: "2026-06-09",
+        lastUpdated: "2026-06-09",
+        family: "claude-fable",
+        openWeights: false,
+        temperatureSupported: false,
+        provider: "anthropic",
+    },
     {
         type: "text",
         modelName: "claude-opus-4-8",
@@ -1291,6 +1321,36 @@ export const textModels = [
         temperatureSupported: true,
         provider: "anthropic",
     },
+    {
+        type: "text",
+        modelName: "claude-sonnet-5",
+        description: "The best combination of speed and intelligence in the Sonnet tier, with near-Opus quality on coding and agentic work. Adaptive thinking on by default; supports the full low/medium/high/xhigh/max effort range. New tokenizer (~30% more tokens for the same text vs Sonnet 4.6). Standard pricing $3/$15; introductory $2/$10 per MTok through 2026-08-31. 1M context window, 128K max output.",
+        maxInputTokens: 1000000,
+        maxOutputTokens: 128000,
+        inputTokenCost: 3,
+        cachedInputTokenCost: 0.3,
+        cacheCreationInputTokenCost: 3.75,
+        outputTokenCost: 15,
+        reasoning: {
+            thinkingStyle: "adaptive",
+            levels: ["low", "medium", "high", "xhigh", "max"],
+            defaultLevel: "high",
+            canDisable: true,
+            outputsThinking: true,
+            outputsSignatures: true,
+        },
+        modalities: {
+            input: ["text", "image", "pdf"],
+            output: ["text"],
+        },
+        knowledge: "2026-01",
+        releaseDate: "2026-06-30",
+        lastUpdated: "2026-06-30",
+        family: "claude-sonnet",
+        openWeights: false,
+        temperatureSupported: false,
+        provider: "anthropic",
+    },
     {
         type: "text",
         modelName: "claude-sonnet-4-6",

package/package.json

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