smoltalk 0.4.2 → 0.5.0

package/dist/types/costEstimate.d.ts

@@ -4,6 +4,7 @@ export type CostEstimate = {
     outputCost: number;
     cachedInputCost?: number;
     cacheCreationInputCost?: number;
+    hostedToolsCost?: number;
     totalCost: number;
     currency: string;
 };
@@ -12,6 +13,7 @@ export declare const CostEstimateSchema: 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/types/costEstimate.js

@@ -4,6 +4,7 @@ export const CostEstimateSchema = z.object({
     outputCost: z.number(),
     cachedInputCost: z.number().optional(),
     cacheCreationInputCost: z.number().optional(),
+    hostedToolsCost: z.number().optional(),
     totalCost: z.number(),
     currency: z.string(),
 });

package/dist/types.d.ts

@@ -5,6 +5,7 @@ import { Message } from "./classes/message/index.js";
 import { ToolCall } from "./classes/ToolCall.js";
 import { Model } from "./model.js";
 import { ModelName } from "./models.js";
+import type { ModelDataBlob } from "./modelData.js";
 import { Result } from "./types/result.js";
 import { TokenUsage } from "./types/tokenUsage.js";
 import { CostEstimate } from "./types/costEstimate.js";
@@ -44,6 +45,8 @@ export type SmolConfig = {
     }>;
     /** Arbitrary metadata passed to custom model providers. */
     metadata?: Record<string, any>;
+    /** Refreshed model/hosted-tool data (from refreshModels) to layer over the baked-in registry for this call. */
+    modelData?: ModelDataBlob;
     /** The conversation messages to send to the model. */
     messages: Message[];
     /** Tools (functions) the model can call. */
@@ -52,6 +55,10 @@ export type SmolConfig = {
         description?: string;
         schema: ZodType;
     }[];
+    /** Provider hosted tools (server-side) to enable for this call, by capability
+     *  name (catalog category), e.g. ["web_search"]. Distinct from `tools`
+     *  (client functions) — hosted tools run server-side and can't be intercepted. */
+    hostedTools?: string[];
     /** Maximum number of tokens the model can generate in its response. */
     maxTokens?: number;
     /** Sampling temperature (0-2). (OpenAI only) */
@@ -96,6 +103,27 @@ export type ToolLoopDetection = {
     intervention?: "remove-tool" | "remove-all-tools" | "throw-error" | "halt-execution";
     excludeTools?: string[];
 };
+export type WebSearchSource = {
+    url: string;
+    title?: string;
+    snippet?: string;
+};
+export type WebSearchCitation = {
+    url: string;
+    title?: string;
+    startIndex?: number;
+    endIndex?: number;
+};
+export type HostedToolResult = {
+    tool: string;
+    provider: string;
+    queries?: string[];
+    sources?: WebSearchSource[];
+    citations?: WebSearchCitation[];
+    callCount?: number;
+    estimatedCost?: number;
+    raw?: unknown;
+};
 export type PromptResult = {
     output: string | null;
     toolCalls: ToolCall[];
@@ -103,8 +131,9 @@ export type PromptResult = {
     usage?: TokenUsage;
     cost?: CostEstimate;
     model?: ModelName;
+    hostedToolResults?: HostedToolResult[];
 };
-export declare function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, model, }: Partial<PromptResult>): PromptResult;
+export declare function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, model, hostedToolResults, }: Partial<PromptResult>): PromptResult;
 export type StreamChunk = {
     type: "text";
     text: string;

package/dist/types.js

@@ -2,7 +2,7 @@ export * from "./types/result.js";
 import z from "zod";
 export * from "./types/costEstimate.js";
 export * from "./types/tokenUsage.js";
-export function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, model, }) {
+export function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, model, hostedToolResults, }) {
     return {
         output: output || null,
         toolCalls: toolCalls || [],
@@ -10,6 +10,7 @@ export function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, m
         usage,
         cost,
         model,
+        hostedToolResults,
     };
 }
 export const TextPartSchema = z.object({

package/dist/util/hostedTools.d.ts

@@ -0,0 +1,19 @@
+import type { ModelDataBlob } from "../modelData.js";
+import type { CostEstimate } from "../types/costEstimate.js";
+import type { HostedToolResult, WebSearchSource, WebSearchCitation } from "../types.js";
+export declare const WEB_SEARCH = "web_search";
+export declare const IMPLEMENTED_HOSTED_TOOLS: Set<string>;
+export declare function validateHostedTools(requested: string[] | undefined, model: string, modelData?: ModelDataBlob): string | null;
+export declare function estimateHostedToolCost(result: HostedToolResult, model: string, modelData?: ModelDataBlob): number | undefined;
+export declare function foldHostedToolCost(cost: CostEstimate | undefined, results: HostedToolResult[]): CostEstimate | undefined;
+export declare function webSearchResult(provider: string, parts: {
+    queries?: string[];
+    sources?: WebSearchSource[];
+    citations?: WebSearchCitation[];
+    callCount?: number;
+    raw?: unknown;
+}): HostedToolResult;
+export declare function applyHostedToolCost(results: HostedToolResult[], cost: CostEstimate | undefined, model: string, modelData?: ModelDataBlob): {
+    results: HostedToolResult[];
+    cost: CostEstimate | undefined;
+};

package/dist/util/hostedTools.js

@@ -0,0 +1,104 @@
+import { getHostedTools, hostedToolPricingFor } from "../models.js";
+import { getModel } from "../models.js";
+import { round } from "./util.js";
+export const WEB_SEARCH = "web_search";
+// Capabilities whose runtime translation/parsing smoltalk actually implements.
+export const IMPLEMENTED_HOSTED_TOOLS = new Set([WEB_SEARCH]);
+// Returns an error message if any requested capability is unusable for this
+// model, else null. Capabilities are matched against the catalog `category`.
+export function validateHostedTools(requested, model, modelData) {
+    if (!requested || requested.length === 0) {
+        return null;
+    }
+    const allCategories = new Set(getHostedTools({ includeDisabled: true, modelData }).map((t) => t.category));
+    const availableCategories = new Set(getHostedTools({ model, modelData }).map((t) => t.category));
+    for (const name of requested) {
+        if (!IMPLEMENTED_HOSTED_TOOLS.has(name)) {
+            if (allCategories.has(name)) {
+                return `Hosted tool "${name}" is in the catalog but not yet supported by smoltalk at runtime.`;
+            }
+            return `Unknown hosted tool "${name}".`;
+        }
+        if (!availableCategories.has(name)) {
+            const provider = getModel(model, modelData)?.provider ?? "unknown";
+            return `${name} is a hosted capability; ${model} (${provider}) doesn't offer it — pass a search function as a tool instead.`;
+        }
+    }
+    return null;
+}
+// callCount x catalog price for the capability on this model. Only per_call
+// pricing yields a number (web search); undefined otherwise.
+export function estimateHostedToolCost(result, model, modelData) {
+    if (!result.callCount) {
+        return undefined;
+    }
+    const tools = getHostedTools({ model, includeDisabled: true, modelData });
+    const tool = tools.find((t) => t.category === result.tool && t.provider === result.provider);
+    if (!tool) {
+        return undefined;
+    }
+    const price = hostedToolPricingFor(tool, model);
+    if (!price || price.unit !== "per_call" || price.amount === undefined) {
+        return undefined;
+    }
+    return round(result.callCount * price.amount, 6);
+}
+// Fold per-result estimatedCost into a CostEstimate (hostedToolsCost + totalCost).
+export function foldHostedToolCost(cost, results) {
+    let hosted = 0;
+    for (const r of results) {
+        if (r.estimatedCost) {
+            hosted += r.estimatedCost;
+        }
+    }
+    if (hosted === 0) {
+        return cost;
+    }
+    const hostedRounded = round(hosted, 6);
+    if (!cost) {
+        return {
+            inputCost: 0,
+            outputCost: 0,
+            hostedToolsCost: hostedRounded,
+            totalCost: hostedRounded,
+            currency: "USD",
+        };
+    }
+    return {
+        ...cost,
+        hostedToolsCost: round((cost.hostedToolsCost || 0) + hosted, 6),
+        totalCost: round(cost.totalCost + hosted, 6),
+    };
+}
+// Build a normalized web-search result, omitting empty fields. One place for the
+// "assemble result" shape so each parser doesn't repeat it.
+export function webSearchResult(provider, parts) {
+    const result = { tool: WEB_SEARCH, provider };
+    if (parts.queries && parts.queries.length > 0) {
+        result.queries = parts.queries;
+    }
+    if (parts.sources && parts.sources.length > 0) {
+        result.sources = parts.sources;
+    }
+    if (parts.citations && parts.citations.length > 0) {
+        result.citations = parts.citations;
+    }
+    if (parts.callCount) {
+        result.callCount = parts.callCount;
+    }
+    if (parts.raw !== undefined) {
+        result.raw = parts.raw;
+    }
+    return result;
+}
+// Estimate per-result cost and fold the total into the CostEstimate. One call
+// for every client, so the estimate+fold sequence lives in exactly one place.
+export function applyHostedToolCost(results, cost, model, modelData) {
+    for (const r of results) {
+        const est = estimateHostedToolCost(r, model, modelData);
+        if (est !== undefined) {
+            r.estimatedCost = est;
+        }
+    }
+    return { results, cost: foldHostedToolCost(cost, results) };
+}

package/dist/util/provider.d.ts

@@ -1,9 +1,10 @@
+import type { ModelDataBlob } from "../modelData.js";
 /**
  * Resolve the provider for a given model name.
  * If an explicit provider is given, returns it directly.
  * Otherwise looks up the model in the registry.
  */
-export declare function resolveProvider(modelName: string, explicitProvider?: string): string;
+export declare function resolveProvider(modelName: string, explicitProvider?: string, modelData?: ModelDataBlob): string;
 type ApiKeyConfig = {
     openAiApiKey?: string;
     googleApiKey?: string;

package/dist/util/provider.js

@@ -5,10 +5,10 @@ import { SmolError } from "../smolError.js";
  * If an explicit provider is given, returns it directly.
  * Otherwise looks up the model in the registry.
  */
-export function resolveProvider(modelName, explicitProvider) {
+export function resolveProvider(modelName, explicitProvider, modelData) {
     if (explicitProvider)
         return explicitProvider;
-    const model = getModel(modelName);
+    const model = getModel(modelName, modelData);
     if (model === undefined) {
         throw new SmolError(`Model ${modelName} is not recognized. Please specify a known model, or explicitly set the provider option in the config.`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smoltalk",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "A common interface for LLM APIs",
   "homepage": "https://github.com/egonSchiele/smoltalk",
   "files": [
@@ -35,6 +35,9 @@
     "openai": "^6.15.0",
     "zod": "^4.3.6"
   },
+  "devDependencies": {
+    "tsx": "^4.19.2"
+  },
   "scripts": {
     "test": "vitest --exclude=**/*.live.test.ts",
     "test:live": "vitest run lib/clients/*.live.test.ts lib/embed/*.live.test.ts lib/image/*.live.test.ts",
@@ -42,6 +45,8 @@
     "build": "rm -rf dist && tsc",
     "start": "cd dist && node index.js",
     "doc": "typedoc --disableSources --out docs lib && prettier docs/ --write",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "seed-data": "tsx scripts/seed-model-data.ts",
+    "refresh-data": "tsx scripts/refresh-from-modelsdev.ts"
   }
 }