smoltalk 0.4.1 → 0.5.0

package/README.md

@@ -194,6 +194,145 @@ Detects when the model is stuck in a repetitive tool-call loop.
 | `intervention` | `string` | Action to take: `"remove-tool"`, `"remove-all-tools"`, `"throw-error"`, or `"halt-execution"`. |
 | `excludeTools` | `string[]` | Tool names to ignore when counting calls. |
 
+## Refreshing model data
+
+Smoltalk ships a baked-in model registry (pricing, context limits, capabilities).
+Because that data goes stale between releases, you can pull a fresh copy at
+runtime and layer it over the built-ins. **You decide where to store it** —
+smoltalk never writes to disk.
+
+```ts
+import { refreshModels, registerModelData } from "smoltalk";
+
+// Fetch the latest data (from a URL smoltalk controls by default).
+const result = await refreshModels();
+if (result.success) {
+  // Persist result.value however you like (file, KV store, etc.),
+  // then register it once at startup:
+  registerModelData(result.value);
+}
+```
+
+Precedence is **per-call `config.modelData` > `registerModelData` (global) >
+baked-in baseline**, merged field-by-field (a refreshed field wins; missing
+fields never erase built-in values). Per-call override:
+
+```ts
+import { textSync, type Message, type ModelDataBlob } from "smoltalk";
+
+declare const messages: Message[];
+declare const modelData: ModelDataBlob;
+
+await textSync({ model: "claude-opus-4-8", messages, modelData });
+```
+
+Override the source URL with the `SMOLTALK_MODEL_DATA_URL` env var or
+`refreshModels({ url })`. The URL may be remote (`https://`, e.g. your own
+self-hosted catalog) or local (`file://…/model-data.json`). The blob also carries
+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.
+
+## Hosted tools catalog
+
+Each cloud provider offers server-side "hosted" tools (web search, code
+execution, file search, image generation). Smoltalk ships a catalog of what's
+available and what it costs — query it with `getHostedTools()`:
+
+```ts
+import { getHostedTools, hostedToolPricingFor } from "smoltalk";
+
+// Hosted tools usable with a given model (respects provider + model allowlists):
+console.log(getHostedTools({ model: "claude-opus-4-8" }));
+
+// All web-search tools across providers:
+const search = getHostedTools({ category: "web_search" });
+
+// Effective pricing for a tool on a specific model (applies per-model overrides):
+const first = search[0];
+if (first) {
+  console.log(hostedToolPricingFor(first, "gemini-2.5-pro"));
+}
+```
+
+The catalog rides in the same refresh blob as model data, so `refreshModels()`
+keeps it current. Local models (Ollama) have none.
+
+### Using a hosted tool (web search)
+
+Enable a provider's hosted web search on a call with `hostedTools` (a list of
+capability names). It's separate from `tools` because hosted tools run
+server-side — you can't intercept or gate them like your own functions.
+
+```ts
+import { textSync, type Message } from "smoltalk";
+
+declare const messages: Message[];
+
+const result = await textSync({
+  model: "claude-opus-4-8",
+  messages,
+  hostedTools: ["web_search"],
+});
+
+// Normalized across providers, regardless of who ran the search:
+if (result.success) {
+  console.log(result.value.hostedToolResults);
+  // [{ tool: "web_search", provider: "anthropic", queries: [...], sources: [...],
+  //    citations: [...], callCount: 1, estimatedCost: 0.01 }]
+}
+```
+
+Supported on Anthropic, Google, and OpenAI **Responses-API** models. Note that
+smoltalk routes base GPT-5 / GPT-4o to Chat Completions, so on OpenAI hosted web
+search is available only on the `openai-responses` models (the `*-pro` variants,
+e.g. `gpt-5-pro`). Chat-only OpenAI models (`gpt-4o`, `gpt-5`) and local models
+return a clear error — use a search *function* (e.g. the Brave/Tavily-backed
+stdlib tools) as a regular `tool` instead.
+
+`estimatedCost` is an upper-bound estimate (providers report usage counts, not
+charges; free-tier allowances are ignored). Results are populated on `textSync`;
+streaming text is unaffected but the streamed result does not include them yet.
+On Google, web search can't be combined with structured output in one call.
+
+## Registering custom providers
+
+Smoltalk has three registration entry points — one per capability:
+
+```ts
+// example: skip-typecheck
+import {
+  success,                    // Result helper
+  registerProvider,           // text generation (a class extending BaseClient)
+  registerEmbeddingProvider,  // embeddings (a function)
+  registerImageProvider,      // images (a function)
+} from "smoltalk";
+
+// Text: a class extending BaseClient (implements _textSync / _textStream)
+registerProvider("my-llm", MyTextClient);
+
+// Embeddings: a function
+registerEmbeddingProvider("my-embed", async (inputs, config) => {
+  // read credentials from config (e.g. config.metadata), call your service
+  return success({ embeddings: [...], model: config.model });
+});
+
+// Images: a function
+registerImageProvider("my-image", async (input, config) => {
+  return success({ images: [...], model: config.model });
+});
+```
+
+Select a custom provider by passing `provider` in the call config
+(`embed(input, { provider: "my-embed", model })`,
+`image(input, { provider: "my-image", model })`). Built-in providers always take
+precedence; a registered name that collides with a built-in is ignored. Custom
+providers receive the full `config` and read their own credentials from it
+(e.g. `config.metadata`).
+
+Text is a class (it needs retries, tool-loop detection, streaming); embeddings
+and images are one-shot functions.
+
 ## Limitations
 Smoltalk has support for a limited number of providers right now, and is mostly focused on the stateless APIs for text completion, though I plan to add support for more providers as well as image and speech models later. Smoltalk is also a personal project, and there are alternatives backed by companies:
 

package/dist/classes/ToolCall.js

@@ -47,9 +47,10 @@ export class ToolCall {
     static fromJSON(json) {
         const result = ToolCallJSONSchema.safeParse(json);
         if (!result.success) {
-            console.error("Failed to parse ToolCall");
-            console.error(JSON.stringify(json, null, 2));
-            console.error(z.prettifyError(result.error));
+            const logger = getLogger();
+            logger.error("Failed to parse ToolCall:", z.prettifyError(result.error));
+            // Raw payload can contain tool-call arguments (often secrets) — only at debug level.
+            logger.debug("ToolCall payload that failed to parse:", JSON.stringify(json, null, 2));
             throw new Error("Failed to parse ToolCall");
         }
         return new ToolCall(result.data.id, result.data.name, result.data.arguments);

package/dist/classes/message/AssistantMessage.d.ts

@@ -37,6 +37,7 @@ export declare const AssistantMessageJSONSchema: z.ZodObject<{
         outputCost: z.ZodNumber;
         cachedInputCost: z.ZodOptional<z.ZodNumber>;
         cacheCreationInputCost: z.ZodOptional<z.ZodNumber>;
+        hostedToolsCost: z.ZodOptional<z.ZodNumber>;
         totalCost: z.ZodNumber;
         currency: z.ZodString;
     }, z.core.$strip>>;

package/dist/classes/message/AssistantMessage.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { BaseMessage } from "./BaseMessage.js";
 import { CostEstimateSchema, TextPartSchema, ThinkingBlockSchema, TokenUsageSchema, } from "../../types.js";
 import { ToolCall, ToolCallJSONSchema } from "../ToolCall.js";
+import { getLogger } from "../../util/logger.js";
 export const AssistantMessageJSONSchema = z.object({
     role: z.literal("assistant"),
     content: z.union([z.string(), z.array(TextPartSchema), z.null()]),
@@ -86,9 +87,10 @@ export class AssistantMessage extends BaseMessage {
     static fromJSON(json) {
         const result = AssistantMessageJSONSchema.safeParse(json);
         if (!result.success) {
-            console.error("Failed to parse AssistantMessage");
-            console.error(JSON.stringify(json, null, 2));
-            console.error(z.prettifyError(result.error));
+            const logger = getLogger();
+            logger.error("Failed to parse AssistantMessage:", z.prettifyError(result.error));
+            // Raw payload can contain assistant content / tool args — only at debug level.
+            logger.debug("AssistantMessage payload that failed to parse:", JSON.stringify(json, null, 2));
             throw new Error("Failed to parse AssistantMessage");
         }
         return new AssistantMessage(result.data.content, {

package/dist/classes/message/DeveloperMessage.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { BaseMessage } from "./BaseMessage.js";
 import { TextPartSchema } from "../../types.js";
+import { getLogger } from "../../util/logger.js";
 export const DeveloperMessageJSONSchema = z.object({
     role: z.literal("developer"),
     content: z.union([z.string(), z.array(TextPartSchema)]),
@@ -43,9 +44,10 @@ export class DeveloperMessage extends BaseMessage {
     static fromJSON(json) {
         const result = DeveloperMessageJSONSchema.safeParse(json);
         if (!result.success) {
-            console.error("Failed to parse DeveloperMessage");
-            console.error(JSON.stringify(json, null, 2));
-            console.error(z.prettifyError(result.error));
+            const logger = getLogger();
+            logger.error("Failed to parse DeveloperMessage:", z.prettifyError(result.error));
+            // Raw payload can contain developer-message content — only at debug level.
+            logger.debug("DeveloperMessage payload that failed to parse:", JSON.stringify(json, null, 2));
             throw new Error("Failed to parse DeveloperMessage");
         }
         return new DeveloperMessage(result.data.content, {

package/dist/classes/message/SystemMessage.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { BaseMessage } from "./BaseMessage.js";
 import { TextPartSchema } from "../../types.js";
+import { getLogger } from "../../util/logger.js";
 export const SystemMessageJSONSchema = z.object({
     role: z.literal("system"),
     content: z.union([z.string(), z.array(TextPartSchema)]),
@@ -43,9 +44,10 @@ export class SystemMessage extends BaseMessage {
     static fromJSON(json) {
         const result = SystemMessageJSONSchema.safeParse(json);
         if (!result.success) {
-            console.error("Failed to parse SystemMessage");
-            console.error(JSON.stringify(json, null, 2));
-            console.error(z.prettifyError(result.error));
+            const logger = getLogger();
+            logger.error("Failed to parse SystemMessage:", z.prettifyError(result.error));
+            // Raw payload can contain system prompt content — only at debug level.
+            logger.debug("SystemMessage payload that failed to parse:", JSON.stringify(json, null, 2));
             throw new Error("Failed to parse SystemMessage");
         }
         return new SystemMessage(result.data.content, {

package/dist/classes/message/ToolMessage.js

@@ -52,9 +52,10 @@ export class ToolMessage extends BaseMessage {
     static fromJSON(json) {
         const result = ToolMessageJSONSchema.safeParse(json);
         if (!result.success) {
-            console.error("Failed to parse ToolMessage");
-            console.error(JSON.stringify(json, null, 2));
-            console.error(z.prettifyError(result.error));
+            const logger = getLogger();
+            logger.error("Failed to parse ToolMessage:", z.prettifyError(result.error));
+            // Raw payload can contain tool results (file paths, secrets) — only at debug level.
+            logger.debug("ToolMessage payload that failed to parse:", JSON.stringify(json, null, 2));
             throw new Error("Failed to parse ToolMessage");
         }
         const TextPartArraySchema = z.array(TextPartSchema);

package/dist/classes/message/UserMessage.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { BaseMessage } from "./BaseMessage.js";
+import { getLogger } from "../../util/logger.js";
 export const UserMessageJSONSchema = z.object({
     role: z.literal("user"),
     content: z.string(),
@@ -42,9 +43,10 @@ export class UserMessage extends BaseMessage {
     static fromJSON(json) {
         const result = UserMessageJSONSchema.safeParse(json);
         if (!result.success) {
-            console.error("Failed to parse UserMessage");
-            console.error(JSON.stringify(json, null, 2));
-            console.error(z.prettifyError(result.error));
+            const logger = getLogger();
+            logger.error("Failed to parse UserMessage:", z.prettifyError(result.error));
+            // Raw payload can contain user prompts / PII — only at debug level.
+            logger.debug("UserMessage payload that failed to parse:", JSON.stringify(json, null, 2));
             throw new Error("Failed to parse UserMessage");
         }
         return new UserMessage(result.data.content, {

package/dist/client.js

@@ -12,7 +12,9 @@ import { SmolOpenAiResponses } from "./clients/openaiResponses.js";
 import { getModel, isTextModel } from "./models.js";
 import { SmolError } from "./smolError.js";
 import { resolveApiKey, resolveProvider } from "./util/provider.js";
-const registeredProviders = {};
+// Null-prototype so provider names like "toString"/"__proto__" can't collide
+// with Object.prototype or pollute the registry.
+const registeredProviders = Object.create(null);
 export function registerProvider(providerName, clientClass) {
     registeredProviders[providerName] = clientClass;
 }
@@ -25,11 +27,11 @@ export function unregisterProvider(providerName) {
 }
 export function getClient(config) {
     const modelName = config.model;
-    const provider = resolveProvider(modelName, config.provider);
+    const provider = resolveProvider(modelName, config.provider, config.modelData);
     // For getClient, validate that the model is a text model when no explicit
     // provider is given (since this factory only returns text-generation clients).
     if (!config.provider) {
-        const model = getModel(modelName);
+        const model = getModel(modelName, config.modelData);
         if (model && !isTextModel(model)) {
             throw new SmolError(`Only text models are supported currently. ${modelName} is a ${model?.type} model.`);
         }

package/dist/clients/anthropic.d.ts

@@ -1,6 +1,8 @@
-import { PromptResult, Result, SmolClient, SmolConfig, StreamChunk } from "../types.js";
+import { PromptResult, Result, SmolClient, SmolConfig, StreamChunk, HostedToolResult } from "../types.js";
 import { BaseClient } from "./baseClient.js";
 import { ModelName } from "../models.js";
+export declare function anthropicWebSearchEntries(hostedTools?: string[]): any[];
+export declare function parseAnthropicHostedTools(response: any, provider: string): HostedToolResult[];
 export type SmolAnthropicConfig = SmolConfig & {
     anthropicApiKey: string;
 };

package/dist/clients/anthropic.js

@@ -3,20 +3,65 @@ import { ToolCall } from "../classes/ToolCall.js";
 import { SystemMessage, DeveloperMessage } from "../classes/message/index.js";
 import { getLogger } from "../util/logger.js";
 import { success, } from "../types.js";
+import { WEB_SEARCH, webSearchResult, applyHostedToolCost } from "../util/hostedTools.js";
 import { zodToAnthropicTool } from "../util/tool.js";
-import { SmolContentPolicyError, SmolContextWindowExceededError, } from "../smolError.js";
+import { SmolContentPolicyError, SmolContextWindowExceededError, smolErrorForStatus, } from "../smolError.js";
+import { extractHttpErrorFields } from "../util/httpError.js";
 import { BaseClient } from "./baseClient.js";
 import { getModel, isTextModel } from "../models.js";
 import { Model } from "../model.js";
 const DEFAULT_MAX_TOKENS = 4096;
+export function anthropicWebSearchEntries(hostedTools) {
+    if (hostedTools && hostedTools.includes(WEB_SEARCH)) {
+        return [{ type: "web_search_20250305", name: "web_search" }];
+    }
+    return [];
+}
+export function parseAnthropicHostedTools(response, provider) {
+    const queries = [];
+    const sources = [];
+    const citations = [];
+    const raw = [];
+    for (const block of response.content || []) {
+        if (block.type === "server_tool_use" && block.name === "web_search") {
+            raw.push(block);
+            // input.query is always the search string; guard only against a malformed block.
+            if (block.input?.query) {
+                queries.push(block.input.query);
+            }
+        }
+        else if (block.type === "web_search_tool_result") {
+            raw.push(block);
+            // content items are web_search_result entries; an error variant has no url.
+            for (const r of block.content || []) {
+                if (r && typeof r.url === "string") {
+                    sources.push({ url: r.url, title: r.title });
+                }
+            }
+        }
+        else if (block.type === "text" && Array.isArray(block.citations)) {
+            for (const c of block.citations) {
+                if (c && typeof c.url === "string") {
+                    citations.push({ url: c.url, title: c.title });
+                }
+            }
+        }
+    }
+    const callCount = response.usage?.server_tool_use?.web_search_requests;
+    const used = queries.length > 0 || sources.length > 0 || (callCount ?? 0) > 0;
+    if (!used) {
+        return [];
+    }
+    return [webSearchResult(provider, { queries, sources, citations, callCount, raw })];
+}
 /**
  * Which thinking API a model speaks. New flagship Anthropic models (Opus 4.7+)
  * reject the legacy `{type: "enabled", budget_tokens}` form with a 400, so we
  * default unknown/unregistered models to "adaptive" (the forward-looking shape)
  * rather than the form that's being phased out.
  */
-function thinkingStyleFor(modelName) {
-    const model = getModel(modelName);
+function thinkingStyleFor(modelName, modelData) {
+    const model = getModel(modelName, modelData);
     if (model && isTextModel(model) && model.reasoning?.thinkingStyle) {
         return model.reasoning.thinkingStyle;
     }
@@ -106,7 +151,7 @@ export class SmolAnthropic extends BaseClient {
         super(config);
         this.client = new Anthropic({ apiKey: config.anthropicApiKey });
         this.logger = getLogger();
-        this.model = new Model(config.model);
+        this.model = new Model(config.model, undefined, config.modelData);
     }
     getModel() {
         return this.model.getModel();
@@ -161,11 +206,14 @@ export class SmolAnthropic extends BaseClient {
             }
             anthropicMessages.push(converted);
         }
-        const tools = config.tools && config.tools.length > 0
+        const functionTools = config.tools && config.tools.length > 0
             ? config.tools.map((tool) => zodToAnthropicTool(tool.name, tool.schema, {
                 description: tool.description,
             }))
-            : undefined;
+            : [];
+        const hostedEntries = anthropicWebSearchEntries(config.hostedTools);
+        const allTools = [...functionTools, ...hostedEntries];
+        const tools = allTools.length > 0 ? allTools : undefined;
         // Normalize the user's provider-agnostic thinking/effort config into the
         // shape this specific model accepts. Both `thinking.enabled` and
         // `reasoningEffort` are treated as a request to think.
@@ -189,7 +237,7 @@ export class SmolAnthropic extends BaseClient {
         if (!wantsThinking && !effort) {
             return { thinking: undefined, outputConfig: undefined };
         }
-        if (thinkingStyleFor(this.getModel()) === "adaptive") {
+        if (thinkingStyleFor(this.getModel(), this.config.modelData) === "adaptive") {
             // `output_config.effort` controls depth; the budget is irrelevant here.
             return {
                 thinking: { type: "adaptive" },
@@ -212,19 +260,21 @@ export class SmolAnthropic extends BaseClient {
     }
     rethrowAsSmolError(error) {
         if (error instanceof Anthropic.APIError) {
+            const http = { ...extractHttpErrorFields(error), cause: error };
             const msg = error.message.toLowerCase();
             if (msg.includes("prompt is too long") ||
                 msg.includes("context length") ||
                 msg.includes("context window") ||
                 msg.includes("too many tokens")) {
-                throw new SmolContextWindowExceededError(error.message);
+                throw new SmolContextWindowExceededError(error.message, http);
             }
             if (msg.includes("content policy") ||
                 msg.includes("usage policies") ||
                 msg.includes("content filtering") ||
                 msg.includes("violates our")) {
-                throw new SmolContentPolicyError(error.message);
+                throw new SmolContentPolicyError(error.message, http);
             }
+            throw smolErrorForStatus(error.message, http);
         }
         throw error;
     }
@@ -280,14 +330,22 @@ export class SmolAnthropic extends BaseClient {
             }
         }
         const { usage, cost } = this.calculateUsageAndCost(response.usage);
-        return success({
+        const parsed = parseAnthropicHostedTools(response, "anthropic");
+        const { results: hostedToolResults, cost: finalCost } = applyHostedToolCost(parsed, cost, this.getModel(), this.config.modelData);
+        const result = {
             output,
             toolCalls,
-            ...(thinkingBlocks.length > 0 && { thinkingBlocks }),
             usage,
-            cost,
+            cost: finalCost,
             model: this.getModel(),
-        });
+        };
+        if (thinkingBlocks.length > 0) {
+            result.thinkingBlocks = thinkingBlocks;
+        }
+        if (hostedToolResults.length > 0) {
+            result.hostedToolResults = hostedToolResults;
+        }
+        return success(result);
     }
     async *_textStream(config) {
         const { system, messages, tools, thinking, outputConfig } = this.buildRequest(config);

package/dist/clients/baseClient.js

@@ -3,7 +3,8 @@ import { getLogger } from "../util/logger.js";
 import { SmolStructuredOutputError } from "../smolError.js";
 import { getStatelogClient } from "../statelogClient.js";
 import { stripCodeFence } from "../util/util.js";
-import { success, } from "../types.js";
+import { success, failure, } from "../types.js";
+import { validateHostedTools } from "../util/hostedTools.js";
 import { z } from "zod";
 const DEFAULT_NUM_RETRIES = 2;
 export class BaseClient {
@@ -55,6 +56,10 @@ export class BaseClient {
         const messageLimitResult = this.checkMessageLimit(promptConfig);
         if (messageLimitResult)
             return messageLimitResult;
+        const hostedError = validateHostedTools(promptConfig.hostedTools, promptConfig.model, promptConfig.modelData);
+        if (hostedError) {
+            return failure(hostedError);
+        }
         const { continue: shouldContinue, newSmolConfig } = this.checkForToolLoops(promptConfig);
         if (!shouldContinue) {
             return {
@@ -264,6 +269,11 @@ export class BaseClient {
             };
             return;
         }
+        const hostedError = validateHostedTools(config.hostedTools, config.model, config.modelData);
+        if (hostedError) {
+            yield { type: "error", error: hostedError };
+            return;
+        }
         const { continue: shouldContinue, newSmolConfig } = this.checkForToolLoops(config);
         if (!shouldContinue) {
             yield {

package/dist/clients/google.d.ts

@@ -2,7 +2,10 @@ import { Content, GenerateContentConfig, GoogleGenAI } from "@google/genai";
 import { PromptResult, Result, SmolClient, SmolConfig, StreamChunk } from "../types.js";
 import { BaseClient } from "./baseClient.js";
 import { ModelName } from "../models.js";
+import { HostedToolResult } from "../types.js";
 export type SmolGoogleConfig = SmolConfig;
+export declare function googleWebSearchEntries(hostedTools?: string[]): any[];
+export declare function parseGoogleHostedTools(result: any, provider: string, model: string): HostedToolResult[];
 type GeneratedRequest = {
     contents: Content[];
     model: ModelName;
@@ -17,6 +20,7 @@ export declare class SmolGoogle extends BaseClient implements SmolClient {
     getModel(): ModelName;
     private calculateUsageAndCost;
     private buildRequest;
+    private rethrowAsSmolError;
     _textSync(config: SmolConfig): Promise<Result<PromptResult>>;
     __textSync(request: GeneratedRequest): Promise<Result<PromptResult>>;
     _textStream(config: SmolConfig): AsyncGenerator<StreamChunk>;