smoltalk 0.5.1 → 0.6.0

package/README.md

@@ -8,6 +8,15 @@ 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
@@ -68,8 +77,10 @@ const messages = [
 const resp = await text({
   messages,
   model: "gemini-2.0-flash-lite",
-  openAiApiKey: process.env.OPENAI_API_KEY || "",
-  googleApiKey: process.env.GEMINI_API_KEY || "",
+  apiKey: {
+    openAi: process.env.OPENAI_API_KEY || "",
+    google: process.env.GEMINI_API_KEY || "",
+  },
   logLevel: "debug",
 });
 ```
@@ -80,8 +91,10 @@ If you want to construct a client once and reuse it across many calls, use `getC
 import { getClient, userMessage } from "smoltalk";
 
 const client = getClient({
-  openAiApiKey: process.env.OPENAI_API_KEY || "",
-  googleApiKey: process.env.GEMINI_API_KEY || "",
+  apiKey: {
+    openAi: process.env.OPENAI_API_KEY || "",
+    google: process.env.GEMINI_API_KEY || "",
+  },
   model: "gemini-2.0-flash-lite",
 });
 
@@ -147,12 +160,9 @@ A couple of design decisions to note:
 |--------|------|-------------|
 | `model` | `ModelName` | **Required.** The model to use (e.g. `"gpt-4o"`, `"gemini-2.0-flash-lite"`). |
 | `messages` | `Message[]` | **Required.** The conversation messages to send. |
-| `openAiApiKey` | `string` | OpenAI API key. |
-| `googleApiKey` | `string` | Google Gemini API key. |
-| `anthropicApiKey` | `string` | Anthropic API key. |
-| `ollamaApiKey` | `string` | Ollama API key (only needed for cloud Ollama). |
-| `ollamaHost` | `string` | Ollama host URL (for self-hosted or cloud Ollama). |
-| `provider` | `Provider` | Override provider detection. One of `"openai"`, `"openai-responses"`, `"google"`, `"ollama"`, `"anthropic"`, or any provider registered via `registerProvider()`. |
+| `apiKey` | `{ openAi?, google?, anthropic?, ollama?, openRouter?, deepInfra?, liteLlm?, openAiCompat? }` | API keys, nested by provider. Each falls back to its conventional env var (`OPENAI_API_KEY`, `GEMINI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, `DEEPINFRA_API_KEY`, `LITELLM_API_KEY`, `OPENAI_COMPAT_API_KEY`). Ollama has no env-var fallback for the key. |
+| `baseUrl` | `{ ollama?, openRouter?, deepInfra?, liteLlm?, openAiCompat? }` | Custom base URLs. `ollama` defaults to `$OLLAMA_HOST` then `http://localhost:11434`; `openRouter`/`deepInfra` defaults are baked in; `liteLlm`/`openAiCompat` require an explicit URL (or `LITELLM_BASE_URL` / `OPENAI_COMPAT_BASE_URL` env). |
+| `provider` | `Provider` | Override provider detection. One of `"openai"`, `"openai-responses"`, `"google"`, `"ollama"`, `"anthropic"`, `"openrouter"`, `"deepinfra"`, `"litellm"`, `"openai-compat"`, or any provider registered via `registerProvider()`. |
 | `logLevel` | `LogLevel` | Logging verbosity: `"debug"`, `"info"`, `"warn"`, `"error"`. |
 | `tools` | `{ name, description?, schema }[]` | Tool definitions. `schema` is a Zod object schema. |
 | `responseFormat` | `ZodType` | Zod schema for structured output. The response is parsed and validated against this schema. |
@@ -194,6 +204,53 @@ 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. |
 
+## Hosted OpenAI-compatible providers
+
+Smoltalk ships four built-in providers for hosted open-source models that all
+speak the OpenAI chat-completions shape. Use these when you want to run a
+Llama, GLM, Qwen, etc. via someone else's hosted infrastructure without
+adding a new dependency. You must pass `provider:` explicitly because these
+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}`) |
+| `"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 |
+
+```ts
+import { textSync, userMessage } from "smoltalk";
+
+const r = await textSync({
+  model: "z-ai/glm-5.2",
+  provider: "openrouter",
+  apiKey: { openRouter: process.env.OPENROUTER_API_KEY! },
+  messages: [userMessage("hi")],
+});
+// r.value.cost.totalCost is a real OpenRouter-reported USD cost.
+```
+
+**Capability matrix:**
+
+|                 | chat | embeddings | image generation | `web_search` hosted tool |
+|-----------------|------|------------|------------------|--------------------------|
+| `openrouter`    | ✅   | ❌         | ❌               | ✅ (via `:online` / web plugin) |
+| `deepinfra`     | ✅   | ✅         | ❌ (uses per-model endpoints, not OpenAI shape) | ❌ |
+| `litellm`       | ✅   | ✅         | ✅ (if the upstream model supports it) | ✅ (if upstream supports it) |
+| `openai-compat` | ✅   | ✅         | ✅ (backend-dependent) | depends on backend |
+
+Smoltalk surfaces a clear `failure(...)` from `embed()`/`image()` for the
+unsupported combinations rather than silently dropping the call.
+
+**Running a local LiteLLM proxy:**
+
+```bash
+pip install 'litellm[proxy]'
+litellm --model openai/gpt-4o
+# In your code: baseUrl: { liteLlm: "http://localhost:4000" }
+```
+
 ## Refreshing model data
 
 Smoltalk ships a baked-in model registry (pricing, context limits, capabilities).

package/dist/client.d.ts

@@ -4,6 +4,10 @@ export * from "./clients/openai.js";
 export * from "./clients/openaiResponses.js";
 export * from "./clients/baseClient.js";
 export * from "./clients/ollama.js";
+export * from "./clients/openaiCompat.js";
+export * from "./clients/openrouter.js";
+export * from "./clients/deepinfra.js";
+export * from "./clients/litellm.js";
 import { BaseClient } from "./clients/baseClient.js";
 import { SmolClientConfig } from "./types.js";
 export declare function registerProvider(providerName: string, clientClass: typeof BaseClient): void;

package/dist/client.js

@@ -4,11 +4,19 @@ export * from "./clients/openai.js";
 export * from "./clients/openaiResponses.js";
 export * from "./clients/baseClient.js";
 export * from "./clients/ollama.js";
+export * from "./clients/openaiCompat.js";
+export * from "./clients/openrouter.js";
+export * from "./clients/deepinfra.js";
+export * from "./clients/litellm.js";
 import { SmolAnthropic } from "./clients/anthropic.js";
 import { SmolGoogle } from "./clients/google.js";
 import { SmolOllama } from "./clients/ollama.js";
 import { SmolOpenAi } from "./clients/openai.js";
 import { SmolOpenAiResponses } from "./clients/openaiResponses.js";
+import { SmolOpenAiCompat } from "./clients/openaiCompat.js";
+import { SmolOpenRouter } from "./clients/openrouter.js";
+import { SmolDeepInfra } from "./clients/deepinfra.js";
+import { SmolLiteLlm } from "./clients/litellm.js";
 import { getModel, isTextModel } from "./models.js";
 import { SmolError } from "./smolError.js";
 import { resolveApiKey, resolveProvider } from "./util/provider.js";
@@ -36,43 +44,56 @@ export function getClient(config) {
             throw new SmolError(`Only text models are supported currently. ${modelName} is a ${model?.type} model.`);
         }
     }
+    // Resolve API keys from config or env vars and inject them back into the
+    // nested apiKey map. The client constructors also read env vars directly,
+    // but this lets getClient surface a clear error before construction.
     const resolvedKeys = {
-        openAiApiKey: resolveApiKey("openai", config),
-        googleApiKey: resolveApiKey("google", config),
-        anthropicApiKey: resolveApiKey("anthropic", config),
+        openAi: resolveApiKey("openai", config),
+        google: resolveApiKey("google", config),
+        anthropic: resolveApiKey("anthropic", config),
+        ollama: resolveApiKey("ollama", config),
+        openRouter: resolveApiKey("openrouter", config),
+        deepInfra: resolveApiKey("deepinfra", config),
+        liteLlm: resolveApiKey("litellm", config),
+        openAiCompat: resolveApiKey("openai-compat", config),
     };
     const clientConfig = {
         messages: [],
         ...config,
-        ...resolvedKeys,
+        apiKey: { ...resolvedKeys, ...config.apiKey },
         model: modelName,
     };
     switch (provider) {
         case "anthropic":
-            if (!resolvedKeys.anthropicApiKey) {
-                throw new SmolError("No Anthropic API key provided. Please provide an Anthropic API key in the config using anthropicApiKey, or set the ANTHROPIC_API_KEY environment variable.");
+            if (!resolvedKeys.anthropic) {
+                throw new SmolError("No Anthropic API key provided. Please provide an Anthropic API key in the config using apiKey.anthropic, or set the ANTHROPIC_API_KEY environment variable.");
             }
-            return new SmolAnthropic({
-                ...clientConfig,
-                anthropicApiKey: resolvedKeys.anthropicApiKey,
-            });
+            return new SmolAnthropic(clientConfig);
         case "openai":
-            if (!resolvedKeys.openAiApiKey) {
-                throw new SmolError("No OpenAI API key provided. Please provide an OpenAI API key in the config using openAiApiKey, or set the OPENAI_API_KEY environment variable.");
+            if (!resolvedKeys.openAi) {
+                throw new SmolError("No OpenAI API key provided. Please provide an OpenAI API key in the config using apiKey.openAi, or set the OPENAI_API_KEY environment variable.");
             }
             return new SmolOpenAi(clientConfig);
         case "openai-responses":
-            if (!resolvedKeys.openAiApiKey) {
-                throw new SmolError("No OpenAI API key provided. Please provide an OpenAI API key in the config using openAiApiKey, or set the OPENAI_API_KEY environment variable.");
+            if (!resolvedKeys.openAi) {
+                throw new SmolError("No OpenAI API key provided. Please provide an OpenAI API key in the config using apiKey.openAi, or set the OPENAI_API_KEY environment variable.");
             }
             return new SmolOpenAiResponses(clientConfig);
         case "google":
-            if (!resolvedKeys.googleApiKey) {
-                throw new SmolError("No Google API key provided. Please provide a Google API key in the config using googleApiKey, or set the GEMINI_API_KEY environment variable.");
+            if (!resolvedKeys.google) {
+                throw new SmolError("No Google API key provided. Please provide a Google API key in the config using apiKey.google, or set the GEMINI_API_KEY environment variable.");
             }
             return new SmolGoogle(clientConfig);
         case "ollama":
             return new SmolOllama(clientConfig);
+        case "openrouter":
+            return new SmolOpenRouter(clientConfig);
+        case "deepinfra":
+            return new SmolDeepInfra(clientConfig);
+        case "litellm":
+            return new SmolLiteLlm(clientConfig);
+        case "openai-compat":
+            return new SmolOpenAiCompat(clientConfig);
         default:
             if (provider in registeredProviders) {
                 const ClientClass = registeredProviders[provider];

package/dist/clients/anthropic.d.ts

@@ -3,9 +3,7 @@ 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;
-};
+export type SmolAnthropicConfig = SmolConfig;
 export declare class SmolAnthropic extends BaseClient implements SmolClient {
     private client;
     private logger;

package/dist/clients/anthropic.js

@@ -149,7 +149,11 @@ export class SmolAnthropic extends BaseClient {
     model;
     constructor(config) {
         super(config);
-        this.client = new Anthropic({ apiKey: config.anthropicApiKey });
+        const apiKey = config.apiKey?.anthropic || process.env.ANTHROPIC_API_KEY;
+        if (!apiKey) {
+            throw new Error("Anthropic API key is required for SmolAnthropic client.");
+        }
+        this.client = new Anthropic({ apiKey });
         this.logger = getLogger();
         this.model = new Model(config.model, undefined, config.modelData);
     }

package/dist/clients/deepinfra.d.ts

@@ -0,0 +1,17 @@
+import { SmolOpenAiCompat } from "./openaiCompat.js";
+import type { SmolConfig } from "../types.js";
+/**
+ * DeepInfra client (https://deepinfra.com). OpenAI-compatible chat completions
+ * at the `/v1/openai` base URL.
+ *
+ * - Baked base URL `https://api.deepinfra.com/v1/openai` (override via config.baseUrl.deepInfra).
+ * - Key: config.apiKey.deepInfra or env DEEPINFRA_API_KEY.
+ * - Cost: reads `usage.estimated_cost` (USD).
+ */
+export declare class SmolDeepInfra extends SmolOpenAiCompat {
+    protected resolveClientOptions(config: SmolConfig): {
+        apiKey: string;
+        baseURL: string;
+    };
+    protected resolveCostUsd(usage: any): number | undefined;
+}

package/dist/clients/deepinfra.js

@@ -0,0 +1,27 @@
+import { SmolOpenAiCompat } from "./openaiCompat.js";
+import { resolveApiKey, resolveBaseUrl } from "../util/provider.js";
+/**
+ * DeepInfra client (https://deepinfra.com). OpenAI-compatible chat completions
+ * at the `/v1/openai` base URL.
+ *
+ * - Baked base URL `https://api.deepinfra.com/v1/openai` (override via config.baseUrl.deepInfra).
+ * - Key: config.apiKey.deepInfra or env DEEPINFRA_API_KEY.
+ * - Cost: reads `usage.estimated_cost` (USD).
+ */
+export class SmolDeepInfra extends SmolOpenAiCompat {
+    resolveClientOptions(config) {
+        const apiKey = resolveApiKey("deepinfra", config);
+        // resolveBaseUrl bakes in the deepinfra default, so this is always defined.
+        const baseURL = resolveBaseUrl("deepinfra", config);
+        if (!apiKey) {
+            throw new Error("deepinfra: API key required (config.apiKey.deepInfra or DEEPINFRA_API_KEY).");
+        }
+        return { apiKey, baseURL };
+    }
+    resolveCostUsd(usage) {
+        // DeepInfra returns usage.estimated_cost (USD) on chat completions.
+        return typeof usage?.estimated_cost === "number"
+            ? usage.estimated_cost
+            : undefined;
+    }
+}

package/dist/clients/google.js

@@ -68,10 +68,11 @@ export class SmolGoogle extends BaseClient {
     model;
     constructor(config) {
         super(config);
-        if (!config.googleApiKey) {
+        const apiKey = config.apiKey?.google || process.env.GEMINI_API_KEY;
+        if (!apiKey) {
             throw new Error("Google API key is required for SmolGoogle client.");
         }
-        this.client = new GoogleGenAI({ apiKey: config.googleApiKey });
+        this.client = new GoogleGenAI({ apiKey });
         this.logger = getLogger();
         this.model = new Model(config.model, undefined, config.modelData);
     }

package/dist/clients/litellm.d.ts

@@ -0,0 +1,19 @@
+import { SmolOpenAiCompat } from "./openaiCompat.js";
+import type { SmolConfig } from "../types.js";
+/**
+ * LiteLLM proxy client (https://docs.litellm.ai/docs/simple_proxy). OpenAI-
+ * compatible chat completions through a user-run LiteLLM proxy.
+ *
+ * - Base URL is REQUIRED from config.baseUrl.liteLlm or env LITELLM_BASE_URL.
+ * - Key: config.apiKey.liteLlm or env LITELLM_API_KEY.
+ * - Cost: reads the `x-litellm-response-cost` header (USD). Only available
+ *   for non-streaming responses; streaming requests fall back to the
+ *   smoltalk model registry.
+ */
+export declare class SmolLiteLlm extends SmolOpenAiCompat {
+    protected resolveClientOptions(config: SmolConfig): {
+        apiKey: string;
+        baseURL: string;
+    };
+    protected resolveCostUsd(_usage: any, rawResponse?: Response): number | undefined;
+}

package/dist/clients/litellm.js

@@ -0,0 +1,32 @@
+import { SmolOpenAiCompat } from "./openaiCompat.js";
+import { resolveApiKey, resolveBaseUrl } from "../util/provider.js";
+/**
+ * LiteLLM proxy client (https://docs.litellm.ai/docs/simple_proxy). OpenAI-
+ * compatible chat completions through a user-run LiteLLM proxy.
+ *
+ * - Base URL is REQUIRED from config.baseUrl.liteLlm or env LITELLM_BASE_URL.
+ * - Key: config.apiKey.liteLlm or env LITELLM_API_KEY.
+ * - Cost: reads the `x-litellm-response-cost` header (USD). Only available
+ *   for non-streaming responses; streaming requests fall back to the
+ *   smoltalk model registry.
+ */
+export class SmolLiteLlm extends SmolOpenAiCompat {
+    resolveClientOptions(config) {
+        const apiKey = resolveApiKey("litellm", config);
+        const baseURL = resolveBaseUrl("litellm", config);
+        if (!apiKey) {
+            throw new Error("litellm: API key required (config.apiKey.liteLlm or LITELLM_API_KEY).");
+        }
+        if (!baseURL) {
+            throw new Error("litellm: base URL required (config.baseUrl.liteLlm or LITELLM_BASE_URL).");
+        }
+        return { apiKey, baseURL };
+    }
+    resolveCostUsd(_usage, rawResponse) {
+        const header = rawResponse?.headers?.get?.("x-litellm-response-cost");
+        if (!header)
+            return undefined;
+        const n = Number(header);
+        return Number.isFinite(n) ? n : undefined;
+    }
+}

package/dist/clients/ollama.js

@@ -4,6 +4,7 @@ import { getLogger } from "../util/logger.js";
 import { success, } from "../types.js";
 import { zodToGoogleTool } from "../util/tool.js";
 import { sanitizeAttributes } from "../util/util.js";
+import { resolveBaseUrl } from "../util/provider.js";
 import { BaseClient } from "./baseClient.js";
 import { SmolContextWindowExceededError, smolErrorForStatus, } from "../smolError.js";
 import { extractHttpErrorFields } from "../util/httpError.js";
@@ -17,14 +18,15 @@ export class SmolOllama extends BaseClient {
         super(config);
         this.logger = getLogger();
         this.model = new Model(config.model, undefined, config.modelData);
-        if (config.ollamaApiKey) {
+        const apiKey = config.apiKey?.ollama;
+        if (apiKey) {
             this.client = new Ollama({
                 host: "https://cloud.ollama.com",
-                headers: { Authorization: "Bearer " + config.ollamaApiKey },
+                headers: { Authorization: "Bearer " + apiKey },
             });
         }
         else {
-            const host = config.ollamaHost || DEFAULT_OLLAMA_HOST;
+            const host = resolveBaseUrl("ollama", config) || DEFAULT_OLLAMA_HOST;
             this.client = new Ollama({ host });
         }
     }

package/dist/clients/openai.d.ts

@@ -1,16 +1,52 @@
 import OpenAI from "openai";
-import { PromptResult, Result, SmolClient, SmolConfig, StreamChunk } from "../types.js";
+import { PromptResult, Result, SmolClient, SmolConfig, StreamChunk, HostedToolResult } from "../types.js";
+import { EgonLog } from "../util/logger.js";
 import { BaseClient } from "./baseClient.js";
 import { ModelName } from "../models.js";
+import { Model } from "../model.js";
+import { CostEstimate, TokenUsage } from "../types.js";
 export type SmolOpenAiConfig = SmolConfig;
 export declare class SmolOpenAi extends BaseClient implements SmolClient {
-    private client;
-    private logger;
-    private model;
+    protected client: OpenAI;
+    protected logger: EgonLog;
+    protected model: Model;
     constructor(config: SmolOpenAiConfig);
+    /**
+     * Build the `new OpenAI({...})` options. Subclasses override to inject a
+     * different baseURL or to pull the key from a different config field.
+     *
+     * Default behavior: read OPENAI_API_KEY (or config.apiKey.openAi). Throws
+     * if the key is missing — subclasses with required keys do their own check.
+     */
+    protected resolveClientOptions(config: SmolConfig): {
+        apiKey?: string;
+        baseURL?: string;
+    };
+    /**
+     * Inspect the provider-returned usage (and optionally the raw HTTP response)
+     * for a USD cost figure. Returns `undefined` if the provider didn't surface
+     * one, in which case `calculateUsageAndCost` falls back to the smoltalk
+     * model registry. Subclasses (OpenRouter, DeepInfra, LiteLLM) override this.
+     */
+    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
+     * after the standard params so it can override them.
+     */
+    protected buildRequestExtras(_config: SmolConfig): Record<string, unknown>;
+    /**
+     * Extract provider-specific hosted-tool results (e.g. OpenRouter web_search
+     * annotations) from a completion. Subclasses override; default returns none.
+     */
+    protected parseHostedToolResults(_completion: any, _config: SmolConfig): HostedToolResult[];
     getClient(): OpenAI;
     getModel(): ModelName;
-    private calculateUsageAndCost;
+    protected calculateUsageAndCost(usageData: any, rawResponse?: Response): {
+        usage?: TokenUsage;
+        cost?: CostEstimate;
+    };
     private buildRequest;
     private rethrowAsSmolError;
     _textSync(config: SmolConfig): Promise<Result<PromptResult>>;

package/dist/clients/openai.js

@@ -14,20 +14,57 @@ export class SmolOpenAi extends BaseClient {
     model;
     constructor(config) {
         super(config);
-        if (!config.openAiApiKey) {
-            throw new Error("OpenAI API key is required for SmolOpenAi client.");
-        }
-        this.client = new OpenAI({ apiKey: config.openAiApiKey });
+        const options = this.resolveClientOptions(config);
+        this.client = new OpenAI(options);
         this.logger = getLogger();
         this.model = new Model(config.model, undefined, config.modelData);
     }
+    /**
+     * Build the `new OpenAI({...})` options. Subclasses override to inject a
+     * different baseURL or to pull the key from a different config field.
+     *
+     * Default behavior: read OPENAI_API_KEY (or config.apiKey.openAi). Throws
+     * if the key is missing — subclasses with required keys do their own check.
+     */
+    resolveClientOptions(config) {
+        const apiKey = config.apiKey?.openAi || process.env.OPENAI_API_KEY;
+        if (!apiKey) {
+            throw new Error("OpenAI API key is required for SmolOpenAi client.");
+        }
+        return { apiKey };
+    }
+    /**
+     * Inspect the provider-returned usage (and optionally the raw HTTP response)
+     * for a USD cost figure. Returns `undefined` if the provider didn't surface
+     * one, in which case `calculateUsageAndCost` falls back to the smoltalk
+     * model registry. Subclasses (OpenRouter, DeepInfra, LiteLLM) override this.
+     */
+    resolveCostUsd(_usage, _rawResponse) {
+        return 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
+     * after the standard params so it can override them.
+     */
+    buildRequestExtras(_config) {
+        return {};
+    }
+    /**
+     * Extract provider-specific hosted-tool results (e.g. OpenRouter web_search
+     * annotations) from a completion. Subclasses override; default returns none.
+     */
+    parseHostedToolResults(_completion, _config) {
+        return [];
+    }
     getClient() {
         return this.client;
     }
     getModel() {
         return this.model.getModel();
     }
-    calculateUsageAndCost(usageData) {
+    calculateUsageAndCost(usageData, rawResponse) {
         let usage;
         let cost;
         if (usageData) {
@@ -40,9 +77,23 @@ export class SmolOpenAi extends BaseClient {
             if (cached > 0) {
                 usage.cachedInputTokens = cached;
             }
-            const calculatedCost = this.model.calculateCost(usage);
-            if (calculatedCost) {
-                cost = calculatedCost;
+            // Prefer provider-supplied cost when available (e.g. OpenRouter
+            // usage.cost, DeepInfra usage.estimated_cost, LiteLLM header).
+            // Fall back to the smoltalk model-registry calculation.
+            const providerCost = this.resolveCostUsd(usageData, rawResponse);
+            if (typeof providerCost === "number") {
+                cost = {
+                    inputCost: 0,
+                    outputCost: 0,
+                    totalCost: providerCost,
+                    currency: "USD",
+                };
+            }
+            else {
+                const calculatedCost = this.model.calculateCost(usage);
+                if (calculatedCost) {
+                    cost = calculatedCost;
+                }
             }
         }
         return { usage, cost };
@@ -61,6 +112,7 @@ export class SmolOpenAi extends BaseClient {
                 reasoning_effort: config.reasoningEffort,
             }),
             ...sanitizeAttributes(config.rawAttributes),
+            ...this.buildRequestExtras(config),
         };
         if (config.responseFormat) {
             request.response_format = {
@@ -92,11 +144,16 @@ export class SmolOpenAi extends BaseClient {
         this.statelogClient?.promptRequest(request);
         const signal = this.getAbortSignal(config);
         let completion;
+        let rawResponse;
         try {
-            completion = await this.client.chat.completions.create({
+            const result = await this.client.chat.completions
+                .create({
                 ...request,
                 stream: false,
-            }, { ...(signal && { signal }) });
+            }, { ...(signal && { signal }) })
+                .withResponse();
+            completion = result.data;
+            rawResponse = result.response;
         }
         catch (error) {
             this.rethrowAsSmolError(error);
@@ -123,14 +180,17 @@ export class SmolOpenAi extends BaseClient {
                 }
             }
         }
-        // Extract usage and calculate cost
-        const { usage, cost } = this.calculateUsageAndCost(completion.usage);
+        // Extract usage and calculate cost. rawResponse lets subclasses read
+        // response headers (e.g. LiteLLM's x-litellm-response-cost).
+        const { usage, cost } = this.calculateUsageAndCost(completion.usage, rawResponse);
+        const hostedToolResults = this.parseHostedToolResults(completion, config);
         return success({
             output,
             toolCalls,
             usage,
             cost,
             model: this.getModel(),
+            ...(hostedToolResults.length > 0 ? { hostedToolResults } : {}),
         });
     }
     async *_textStream(config) {
@@ -156,6 +216,9 @@ export class SmolOpenAi extends BaseClient {
         for await (const chunk of completion) {
             // Extract usage from the final chunk
             if (chunk.usage) {
+                // Header-based cost (LiteLLM) is unsupported while streaming.
+                // Body-based cost (OpenRouter/DeepInfra) still works because it
+                // comes through chunk.usage.
                 const usageAndCost = this.calculateUsageAndCost(chunk.usage);
                 usage = usageAndCost.usage;
                 cost = usageAndCost.cost;

package/dist/clients/openaiCompat.d.ts

@@ -0,0 +1,22 @@
+import { SmolOpenAi } from "./openai.js";
+import type { SmolConfig } from "../types.js";
+/**
+ * Generic OpenAI-compatible client. Use when pointing smoltalk at any
+ * arbitrary OpenAI-shaped endpoint (vLLM, TGI, LM Studio, OpenLLM, etc.).
+ *
+ * Both `config.apiKey.openAiCompat` and `config.baseUrl.openAiCompat` are
+ * required (or their env-var fallbacks: `OPENAI_COMPAT_API_KEY`,
+ * `OPENAI_COMPAT_BASE_URL`).
+ *
+ * Cost: opportunistically reads `usage.cost`, `usage.estimated_cost`, or
+ * `usage.cost_usd` if the backend includes one of them. Otherwise falls back
+ * to the smoltalk model registry (which won't have these custom models, so
+ * cost stays undefined — that's expected for arbitrary backends).
+ */
+export declare class SmolOpenAiCompat extends SmolOpenAi {
+    protected resolveClientOptions(config: SmolConfig): {
+        apiKey: string;
+        baseURL: string;
+    };
+    protected resolveCostUsd(usage: any): number | undefined;
+}

package/dist/clients/openaiCompat.js

@@ -0,0 +1,33 @@
+import { SmolOpenAi } from "./openai.js";
+import { resolveApiKey, resolveBaseUrl } from "../util/provider.js";
+/**
+ * Generic OpenAI-compatible client. Use when pointing smoltalk at any
+ * arbitrary OpenAI-shaped endpoint (vLLM, TGI, LM Studio, OpenLLM, etc.).
+ *
+ * Both `config.apiKey.openAiCompat` and `config.baseUrl.openAiCompat` are
+ * required (or their env-var fallbacks: `OPENAI_COMPAT_API_KEY`,
+ * `OPENAI_COMPAT_BASE_URL`).
+ *
+ * Cost: opportunistically reads `usage.cost`, `usage.estimated_cost`, or
+ * `usage.cost_usd` if the backend includes one of them. Otherwise falls back
+ * to the smoltalk model registry (which won't have these custom models, so
+ * cost stays undefined — that's expected for arbitrary backends).
+ */
+export class SmolOpenAiCompat extends SmolOpenAi {
+    resolveClientOptions(config) {
+        const apiKey = resolveApiKey("openai-compat", config);
+        const baseURL = resolveBaseUrl("openai-compat", config);
+        if (!apiKey) {
+            throw new Error("openai-compat: API key required (config.apiKey.openAiCompat or OPENAI_COMPAT_API_KEY).");
+        }
+        if (!baseURL) {
+            throw new Error("openai-compat: base URL required (config.baseUrl.openAiCompat or OPENAI_COMPAT_BASE_URL).");
+        }
+        return { apiKey, baseURL };
+    }
+    resolveCostUsd(usage) {
+        // Try the three common conventions across OpenAI-compatible providers.
+        const c = usage?.cost ?? usage?.estimated_cost ?? usage?.cost_usd;
+        return typeof c === "number" ? c : undefined;
+    }
+}

package/dist/clients/openaiResponses.js

@@ -53,10 +53,11 @@ export class SmolOpenAiResponses extends BaseClient {
     model;
     constructor(config) {
         super(config);
-        if (!config.openAiApiKey) {
+        const apiKey = config.apiKey?.openAi || process.env.OPENAI_API_KEY;
+        if (!apiKey) {
             throw new Error("OpenAI API key is required for SmolOpenAiResponses client.");
         }
-        this.client = new OpenAI({ apiKey: config.openAiApiKey });
+        this.client = new OpenAI({ apiKey });
         this.logger = getLogger();
         this.model = new Model(config.model, undefined, config.modelData);
     }

package/dist/clients/openrouter.d.ts

@@ -0,0 +1,23 @@
+import { SmolOpenAiCompat } from "./openaiCompat.js";
+import type { SmolConfig, HostedToolResult } from "../types.js";
+/**
+ * OpenRouter client (https://openrouter.ai). OpenAI-compatible chat completions.
+ *
+ * - 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.
+ * - Hosted web_search: when config.hostedTools includes "web_search",
+ *   injects `plugins: [{ id: "web", max_results: 5 }]` and parses
+ *   message.annotations into a HostedToolResult.
+ */
+export declare class SmolOpenRouter extends SmolOpenAiCompat {
+    protected resolveClientOptions(config: SmolConfig): {
+        apiKey: string;
+        baseURL: string;
+    };
+    protected resolveCostUsd(usage: any): number | undefined;
+    protected buildRequestExtras(config: SmolConfig): Record<string, unknown>;
+    protected parseHostedToolResults(completion: any, config: SmolConfig): HostedToolResult[];
+}

package/dist/clients/openrouter.js

@@ -0,0 +1,76 @@
+import { SmolOpenAiCompat } from "./openaiCompat.js";
+import { webSearchResult } from "../util/hostedTools.js";
+import { resolveApiKey, resolveBaseUrl } from "../util/provider.js";
+/**
+ * OpenRouter client (https://openrouter.ai). OpenAI-compatible chat completions.
+ *
+ * - 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.
+ * - Hosted web_search: when config.hostedTools includes "web_search",
+ *   injects `plugins: [{ id: "web", max_results: 5 }]` and parses
+ *   message.annotations into a HostedToolResult.
+ */
+export class SmolOpenRouter extends SmolOpenAiCompat {
+    resolveClientOptions(config) {
+        const apiKey = resolveApiKey("openrouter", config);
+        // resolveBaseUrl bakes in the openrouter default, so this is always defined.
+        const baseURL = resolveBaseUrl("openrouter", config);
+        if (!apiKey) {
+            throw new Error("openrouter: API key required (config.apiKey.openRouter or OPENROUTER_API_KEY).");
+        }
+        return { apiKey, baseURL };
+    }
+    resolveCostUsd(usage) {
+        return typeof usage?.cost === "number" ? usage.cost : undefined;
+    }
+    buildRequestExtras(config) {
+        // OpenRouter only returns usage.cost when this is set.
+        const extras = { usage: { include: true } };
+        if (config.hostedTools?.includes("web_search")) {
+            extras.plugins = [{ id: "web", max_results: 5 }];
+        }
+        return extras;
+    }
+    parseHostedToolResults(completion, config) {
+        if (!config.hostedTools?.includes("web_search"))
+            return [];
+        const annotations = completion?.choices?.[0]?.message?.annotations;
+        if (!Array.isArray(annotations) || annotations.length === 0)
+            return [];
+        const sources = [];
+        const citations = [];
+        for (const a of annotations) {
+            if (a?.type !== "url_citation" || !a.url_citation?.url)
+                continue;
+            const uc = a.url_citation;
+            const source = {
+                url: uc.url,
+            };
+            if (uc.title)
+                source.title = uc.title;
+            if (uc.content)
+                source.snippet = uc.content;
+            sources.push(source);
+            const citation = { url: uc.url };
+            if (uc.title)
+                citation.title = uc.title;
+            if (typeof uc.start_index === "number")
+                citation.startIndex = uc.start_index;
+            if (typeof uc.end_index === "number")
+                citation.endIndex = uc.end_index;
+            citations.push(citation);
+        }
+        if (sources.length === 0)
+            return [];
+        return [
+            webSearchResult("openrouter", {
+                sources,
+                citations,
+                callCount: 1,
+            }),
+        ];
+    }
+}

package/dist/embed/openai.d.ts

@@ -1,3 +1,9 @@
 import { EmbedConfig, EmbedResult } from "../embed.js";
 import { Result } from "../types/result.js";
-export declare function openaiEmbed(inputs: string[], config: EmbedConfig, apiKey: string): Promise<Result<EmbedResult>>;
+/**
+ * OpenAI-compatible embedding call. Used by openai directly and by other
+ * OpenAI-shape backends (deepinfra, litellm, openai-compat) which pass a
+ * custom `baseURL`. Cost comes from the smoltalk model registry; provider-
+ * returned cost fields aren't standardized on this endpoint.
+ */
+export declare function openaiEmbed(inputs: string[], config: EmbedConfig, apiKey: string, baseURL?: string): Promise<Result<EmbedResult>>;

package/dist/embed/openai.js

@@ -2,9 +2,15 @@ import OpenAI from "openai";
 import { success, failure } from "../types/result.js";
 import { getModel, isEmbeddingsModel } from "../models.js";
 import { round } from "../util/util.js";
-export async function openaiEmbed(inputs, config, apiKey) {
+/**
+ * OpenAI-compatible embedding call. Used by openai directly and by other
+ * OpenAI-shape backends (deepinfra, litellm, openai-compat) which pass a
+ * custom `baseURL`. Cost comes from the smoltalk model registry; provider-
+ * returned cost fields aren't standardized on this endpoint.
+ */
+export async function openaiEmbed(inputs, config, apiKey, baseURL) {
     try {
-        const client = new OpenAI({ apiKey });
+        const client = new OpenAI({ apiKey, ...(baseURL ? { baseURL } : {}) });
         const response = await client.embeddings.create({
             model: config.model,
             input: inputs,

package/dist/embed.d.ts

@@ -6,10 +6,24 @@ export type EmbedConfig = {
     model: string;
     provider?: string;
     dimensions?: number;
-    openAiApiKey?: string;
-    googleApiKey?: string;
-    ollamaApiKey?: string;
-    ollamaHost?: string;
+    /** API keys, nested by provider. Falls back to env vars
+     *  (OPENAI_API_KEY / GEMINI_API_KEY / DEEPINFRA_API_KEY /
+     *  LITELLM_API_KEY / OPENAI_COMPAT_API_KEY). */
+    apiKey?: {
+        openAi?: string;
+        google?: string;
+        ollama?: string;
+        deepInfra?: string;
+        liteLlm?: string;
+        openAiCompat?: string;
+    };
+    /** Custom base URLs, nested by provider. */
+    baseUrl?: {
+        ollama?: string;
+        deepInfra?: string;
+        liteLlm?: string;
+        openAiCompat?: string;
+    };
     metadata?: Record<string, unknown>;
     modelData?: ModelDataBlob;
 };

package/dist/embed.js

@@ -1,5 +1,5 @@
 import { failure } from "./types/result.js";
-import { resolveProvider, resolveApiKey } from "./util/provider.js";
+import { resolveProvider, resolveApiKey, resolveBaseUrl } from "./util/provider.js";
 import { openaiEmbed } from "./embed/openai.js";
 import { googleEmbed } from "./embed/google.js";
 import { ollamaEmbed } from "./embed/ollama.js";
@@ -23,18 +23,46 @@ export async function embed(input, config) {
         case "openai":
         case "openai-responses": {
             if (!apiKey) {
-                return failure("No OpenAI API key provided. Set openAiApiKey in config or the OPENAI_API_KEY environment variable.");
+                return failure("No OpenAI API key provided. Set config.apiKey.openAi or the OPENAI_API_KEY environment variable.");
             }
             return openaiEmbed(inputs, config, apiKey);
         }
         case "google": {
             if (!apiKey) {
-                return failure("No Google API key provided. Set googleApiKey in config or the GEMINI_API_KEY environment variable.");
+                return failure("No Google API key provided. Set config.apiKey.google or the GEMINI_API_KEY environment variable.");
             }
             return googleEmbed(inputs, config, apiKey);
         }
         case "ollama":
-            return ollamaEmbed(inputs, config, apiKey, config.ollamaHost);
+            return ollamaEmbed(inputs, config, apiKey, resolveBaseUrl("ollama", config));
+        case "openrouter":
+            return failure("openrouter does not expose an embeddings endpoint; use deepinfra, openai-compat, or litellm instead.");
+        case "deepinfra": {
+            if (!apiKey) {
+                return failure("No DeepInfra API key provided. Set config.apiKey.deepInfra or the DEEPINFRA_API_KEY environment variable.");
+            }
+            return openaiEmbed(inputs, config, apiKey, resolveBaseUrl("deepinfra", config));
+        }
+        case "litellm": {
+            if (!apiKey) {
+                return failure("No LiteLLM API key provided. Set config.apiKey.liteLlm or the LITELLM_API_KEY environment variable.");
+            }
+            const baseURL = resolveBaseUrl("litellm", config);
+            if (!baseURL) {
+                return failure("No LiteLLM base URL provided. Set config.baseUrl.liteLlm or the LITELLM_BASE_URL environment variable.");
+            }
+            return openaiEmbed(inputs, config, apiKey, baseURL);
+        }
+        case "openai-compat": {
+            if (!apiKey) {
+                return failure("No openai-compat API key provided. Set config.apiKey.openAiCompat or the OPENAI_COMPAT_API_KEY environment variable.");
+            }
+            const baseURL = resolveBaseUrl("openai-compat", config);
+            if (!baseURL) {
+                return failure("No openai-compat base URL provided. Set config.baseUrl.openAiCompat or the OPENAI_COMPAT_BASE_URL environment variable.");
+            }
+            return openaiEmbed(inputs, config, apiKey, baseURL);
+        }
         default: {
             const custom = registeredEmbedProviders[provider];
             if (custom) {

package/dist/image/openaiCompat.d.ts

@@ -0,0 +1,9 @@
+import { ImageInput, ImageConfig, ImageGenResult } from "../image.js";
+import { Result } from "../types/result.js";
+/**
+ * Generic OpenAI-compatible image generation. Used by litellm/openai-compat —
+ * any backend that speaks the OpenAI `/images/generations` shape. Image edits
+ * are not supported here (the multipart upload shape varies between backends);
+ * pass a plain prompt only.
+ */
+export declare function openaiCompatImage(input: ImageInput, config: ImageConfig, apiKey: string, baseURL: string): Promise<Result<ImageGenResult>>;

package/dist/image/openaiCompat.js

@@ -0,0 +1,60 @@
+import OpenAI from "openai";
+import { success, failure } from "../types/result.js";
+import { omitUndefined } from "../util/util.js";
+/**
+ * Generic OpenAI-compatible image generation. Used by litellm/openai-compat —
+ * any backend that speaks the OpenAI `/images/generations` shape. Image edits
+ * are not supported here (the multipart upload shape varies between backends);
+ * pass a plain prompt only.
+ */
+export async function openaiCompatImage(input, config, apiKey, baseURL) {
+    try {
+        const normalized = typeof input === "string" ? { prompt: input } : input;
+        const hasImages = !!(normalized.images && normalized.images.length > 0);
+        if (hasImages) {
+            return failure("openai-compat: image edits (passing `images`) are not supported on this generic adapter. Use the `openai` provider for OpenAI image edits.");
+        }
+        if (normalized.mask) {
+            return failure("openai-compat: image masks are not supported on this generic adapter.");
+        }
+        const client = new OpenAI({ apiKey, baseURL });
+        const params = omitUndefined({
+            model: config.model,
+            prompt: normalized.prompt,
+            n: config.n,
+            size: config.size,
+            quality: config.quality,
+            output_format: config.outputFormat,
+            background: config.background,
+            ...(config.metadata ?? {}),
+        });
+        const response = await client.images.generate(params);
+        const mimeType = mimeFromFormat(config.outputFormat) ?? "image/png";
+        const images = (response.data ?? []).map((d) => ({
+            data: new Uint8Array(Buffer.from(d.b64_json, "base64")),
+            mimeType,
+            revisedPrompt: d.revised_prompt,
+        }));
+        return success({
+            images,
+            model: config.model,
+        });
+    }
+    catch (err) {
+        return failure(err instanceof Error
+            ? err.message
+            : "OpenAI-compatible image request failed");
+    }
+}
+function mimeFromFormat(format) {
+    switch (format) {
+        case "png":
+            return "image/png";
+        case "jpeg":
+            return "image/jpeg";
+        case "webp":
+            return "image/webp";
+        default:
+            return undefined;
+    }
+}

package/dist/image.d.ts

@@ -17,8 +17,19 @@ export type ImageConfig = {
     quality?: "low" | "medium" | "high" | "auto";
     outputFormat?: "png" | "jpeg" | "webp";
     background?: "transparent" | "opaque" | "auto";
-    openAiApiKey?: string;
-    googleApiKey?: string;
+    /** API keys, nested by provider. Falls back to env vars
+     *  (OPENAI_API_KEY / GEMINI_API_KEY / LITELLM_API_KEY / OPENAI_COMPAT_API_KEY). */
+    apiKey?: {
+        openAi?: string;
+        google?: string;
+        liteLlm?: string;
+        openAiCompat?: string;
+    };
+    /** Custom base URLs, nested by provider. */
+    baseUrl?: {
+        liteLlm?: string;
+        openAiCompat?: string;
+    };
     metadata?: Record<string, unknown>;
     modelData?: ModelDataBlob;
 };

package/dist/image.js

@@ -1,7 +1,8 @@
 import { failure } from "./types/result.js";
-import { resolveProvider, resolveApiKey } from "./util/provider.js";
+import { resolveProvider, resolveApiKey, resolveBaseUrl } from "./util/provider.js";
 import { openaiImage } from "./image/openai.js";
 import { googleImage } from "./image/google.js";
+import { openaiCompatImage } from "./image/openaiCompat.js";
 // Null-prototype so provider names like "toString"/"__proto__" can't collide
 // with Object.prototype or pollute the registry.
 const registeredImageProviders = Object.create(null);
@@ -27,16 +28,40 @@ export async function image(input, config) {
         case "openai":
         case "openai-responses": {
             if (!apiKey) {
-                return failure("No OpenAI API key provided. Set openAiApiKey in config or the OPENAI_API_KEY environment variable.");
+                return failure("No OpenAI API key provided. Set config.apiKey.openAi or the OPENAI_API_KEY environment variable.");
             }
             return openaiImage(input, config, apiKey);
         }
         case "google": {
             if (!apiKey) {
-                return failure("No Google API key provided. Set googleApiKey in config or the GEMINI_API_KEY environment variable.");
+                return failure("No Google API key provided. Set config.apiKey.google or the GEMINI_API_KEY environment variable.");
             }
             return googleImage(input, config, apiKey);
         }
+        case "openrouter":
+            return failure("openrouter does not expose an OpenAI-compatible images endpoint; use openai-compat or litellm instead.");
+        case "deepinfra":
+            return failure("deepinfra exposes per-model image endpoints rather than the OpenAI `/images/generations` shape; use openai-compat with a specific backend or litellm instead.");
+        case "litellm": {
+            if (!apiKey) {
+                return failure("No LiteLLM API key provided. Set config.apiKey.liteLlm or the LITELLM_API_KEY environment variable.");
+            }
+            const baseURL = resolveBaseUrl("litellm", config);
+            if (!baseURL) {
+                return failure("No LiteLLM base URL provided. Set config.baseUrl.liteLlm or the LITELLM_BASE_URL environment variable.");
+            }
+            return openaiCompatImage(input, config, apiKey, baseURL);
+        }
+        case "openai-compat": {
+            if (!apiKey) {
+                return failure("No openai-compat API key provided. Set config.apiKey.openAiCompat or the OPENAI_COMPAT_API_KEY environment variable.");
+            }
+            const baseURL = resolveBaseUrl("openai-compat", config);
+            if (!baseURL) {
+                return failure("No openai-compat base URL provided. Set config.baseUrl.openAiCompat or the OPENAI_COMPAT_BASE_URL environment variable.");
+            }
+            return openaiCompatImage(input, config, apiKey, baseURL);
+        }
         default: {
             const custom = registeredImageProviders[provider];
             if (custom) {

package/dist/models.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { type ModelDataBlob, type HostedTool, type HostedToolPrice } from "./modelData.js";
-export declare const providers: readonly ["ollama", "openai", "openai-responses", "anthropic", "google", "replicate", "modal"];
+export declare const providers: readonly ["ollama", "openai", "openai-responses", "anthropic", "google", "replicate", "modal", "openrouter", "deepinfra", "litellm", "openai-compat"];
 export declare const ProviderSchema: z.ZodEnum<{
     ollama: "ollama";
     openai: "openai";
@@ -9,6 +9,10 @@ export declare const ProviderSchema: z.ZodEnum<{
     google: "google";
     replicate: "replicate";
     modal: "modal";
+    openrouter: "openrouter";
+    deepinfra: "deepinfra";
+    litellm: "litellm";
+    "openai-compat": "openai-compat";
 }>;
 export type Provider = z.infer<typeof ProviderSchema>;
 export type BaseModel = {

package/dist/models.js

@@ -8,6 +8,10 @@ export const providers = [
     "google",
     "replicate",
     "modal",
+    "openrouter",
+    "deepinfra",
+    "litellm",
+    "openai-compat",
 ];
 export const ProviderSchema = z.enum(providers);
 export const speechToTextModels = [
@@ -1557,6 +1561,18 @@ export const hostedTools = [
         models: ["gemini-3-pro-preview", "gemini-3.1-pro-preview", "gemini-3-flash-preview", "gemini-3.5-flash", "gemini-3.1-flash-lite"],
         pricing: { unit: "per_call", note: "Gemini 3 family only; see Google pricing." },
     },
+    {
+        name: "web_search",
+        provider: "openrouter",
+        category: "web_search",
+        description: "Web search via OpenRouter's web plugin (Exa-backed). Adds citations as annotations.",
+        providerToolId: "web",
+        pricing: {
+            unit: "per_call",
+            amount: 0.02,
+            note: "$4 per 1,000 results returned by the web plugin × default 5 results/call = $0.02/call. Plus token cost for inserted context. If you override max_results, scale this accordingly.",
+        },
+    },
 ];
 export const registeredTextModels = [];
 export function registerTextModel(model) {
@@ -1658,4 +1674,4 @@ export function isEmbeddingsModel(model) {
 }
 export const ModelNameSchema = z
     .string()
-    .regex(/^[a-zA-Z0-9._:-]+$/, "Model name must only contain letters, numbers, dots, underscores, hyphens, and colons");
+    .regex(/^[a-zA-Z0-9._:@/-]+$/, "Model name must only contain letters, numbers, dots, underscores, hyphens, colons, slashes, and @");

package/dist/types.d.ts

@@ -16,16 +16,28 @@ export type SmolConfig = {
     model: ModelName;
     /** Override the provider for the given model (e.g., use a custom endpoint for an OpenAI-compatible model). */
     provider?: string;
-    /** API key for OpenAI. Required when using OpenAI models. */
-    openAiApiKey?: string;
-    /** API key for Google Gemini. Required when using Google models. */
-    googleApiKey?: string;
-    /** API key for Anthropic. Required when using Anthropic/Claude models. */
-    anthropicApiKey?: string;
-    /** API key for Ollama. Only needed when connecting to a cloud-hosted Ollama instance. */
-    ollamaApiKey?: string;
-    /** Base URL for the Ollama server. Defaults to localhost if not set. (Ollama only) */
-    ollamaHost?: string;
+    /** API keys, nested by provider. Each key falls back to its conventional env var
+     *  if unset (e.g. apiKey.openAi → OPENAI_API_KEY). */
+    apiKey?: {
+        openAi?: string;
+        google?: string;
+        anthropic?: string;
+        ollama?: string;
+        openRouter?: string;
+        deepInfra?: string;
+        liteLlm?: string;
+        openAiCompat?: string;
+    };
+    /** Custom base URLs, nested by provider. Defaults are baked in where applicable
+     *  (e.g. openrouter, deepinfra); litellm and openai-compat require an explicit URL. */
+    baseUrl?: {
+        /** Host URL for the Ollama server. Defaults to http://localhost:11434 (or $OLLAMA_HOST). */
+        ollama?: string;
+        openRouter?: string;
+        deepInfra?: string;
+        liteLlm?: string;
+        openAiCompat?: string;
+    };
     /** Log level for internal debug logging. */
     logLevel?: LogLevel;
     /** Configuration for Statelog observability/tracing integration. */

package/dist/util/provider.d.ts

@@ -5,14 +5,40 @@ import type { ModelDataBlob } from "../modelData.js";
  * Otherwise looks up the model in the registry.
  */
 export declare function resolveProvider(modelName: string, explicitProvider?: string, modelData?: ModelDataBlob): string;
-type ApiKeyConfig = {
-    openAiApiKey?: string;
-    googleApiKey?: string;
-    anthropicApiKey?: string;
-    ollamaApiKey?: string;
+/**
+ * Minimal shape needed to read API keys / base URLs. Kept local to avoid
+ * importing SmolConfig (which would create a circular import).
+ */
+type NestedKeyConfig = {
+    apiKey?: {
+        openAi?: string;
+        google?: string;
+        anthropic?: string;
+        ollama?: string;
+        openRouter?: string;
+        deepInfra?: string;
+        liteLlm?: string;
+        openAiCompat?: string;
+    };
+    baseUrl?: {
+        ollama?: string;
+        openRouter?: string;
+        deepInfra?: string;
+        liteLlm?: string;
+        openAiCompat?: string;
+    };
 };
 /**
  * Resolve the API key for a provider, checking config then env vars.
  */
-export declare function resolveApiKey(provider: string, config: ApiKeyConfig): string | undefined;
+export declare function resolveApiKey(provider: string, config: NestedKeyConfig): string | undefined;
+/**
+ * Resolve the base URL for a provider, checking config then env vars then a
+ * baked-in default. Returns `undefined` when a provider requires the caller to
+ * supply one (litellm, openai-compat) and nothing was given.
+ *
+ * Centralized here so we don't duplicate the env-fallback table across
+ * embed.ts, image.ts, and each client constructor.
+ */
+export declare function resolveBaseUrl(provider: string, config: NestedKeyConfig): string | undefined;
 export {};

package/dist/util/provider.js

@@ -18,16 +18,50 @@ export function resolveProvider(modelName, explicitProvider, modelData) {
  * Resolve the API key for a provider, checking config then env vars.
  */
 export function resolveApiKey(provider, config) {
+    const k = config.apiKey;
     switch (provider) {
         case "openai":
         case "openai-responses":
-            return config.openAiApiKey || process.env.OPENAI_API_KEY;
+            return k?.openAi || process.env.OPENAI_API_KEY;
         case "google":
-            return config.googleApiKey || process.env.GEMINI_API_KEY;
+            return k?.google || process.env.GEMINI_API_KEY;
         case "anthropic":
-            return config.anthropicApiKey || process.env.ANTHROPIC_API_KEY;
+            return k?.anthropic || process.env.ANTHROPIC_API_KEY;
         case "ollama":
-            return config.ollamaApiKey;
+            return k?.ollama;
+        case "openrouter":
+            return k?.openRouter || process.env.OPENROUTER_API_KEY;
+        case "deepinfra":
+            return k?.deepInfra || process.env.DEEPINFRA_API_KEY;
+        case "litellm":
+            return k?.liteLlm || process.env.LITELLM_API_KEY;
+        case "openai-compat":
+            return k?.openAiCompat || process.env.OPENAI_COMPAT_API_KEY;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Resolve the base URL for a provider, checking config then env vars then a
+ * baked-in default. Returns `undefined` when a provider requires the caller to
+ * supply one (litellm, openai-compat) and nothing was given.
+ *
+ * Centralized here so we don't duplicate the env-fallback table across
+ * embed.ts, image.ts, and each client constructor.
+ */
+export function resolveBaseUrl(provider, config) {
+    const b = config.baseUrl;
+    switch (provider) {
+        case "ollama":
+            return b?.ollama || process.env.OLLAMA_HOST;
+        case "openrouter":
+            return b?.openRouter || "https://openrouter.ai/api/v1";
+        case "deepinfra":
+            return b?.deepInfra || "https://api.deepinfra.com/v1/openai";
+        case "litellm":
+            return b?.liteLlm || process.env.LITELLM_BASE_URL;
+        case "openai-compat":
+            return b?.openAiCompat || process.env.OPENAI_COMPAT_BASE_URL;
         default:
             return undefined;
     }

package/package.json

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