smoltalk 0.0.53 → 0.0.55

package/README.md

@@ -1,6 +1,6 @@
 # Smoltalk
 
-Smoltalk is a package that exposes a common interface across different LLM providers. It exists because I think it's important to have an npm package that allows users to try out different kinds of LLMs, and prevents vendor lock-in. Using a different LLM should be as simple as switching out a model name.
+Smoltalk exposes a common API to different LLM providers. There are other packages that do this, but Smoltalk allows you to build strategies on top of it. Here is a simple example.
 
 ## Install
 
@@ -8,26 +8,83 @@ Smoltalk is a package that exposes a common interface across different LLM provi
 pnpm install smoltalk
 ```
 
-## Quickstart
+## Hello world example
 
 ```typescript
-import { getClient } from "smoltalk";
-
-const client = getClient({
-  openAiApiKey: process.env.OPENAI_API_KEY || "",
-  googleApiKey: process.env.GEMINI_API_KEY || "",
-  logLevel: "debug",
-  model: "gemini-2.0-flash-lite",
-});
+import { text, userMessage } from "smoltalk";
 
 async function main() {
-  const resp = await client.prompt("Hello, how are you?");
-  console.log(resp);
+  const messages = [userMessage("Write me a 10 word story.")];
+  const response = await text({
+    messages,
+    model: "gpt-5.4",
+  });
+  console.log(response);
 }
 
 main();
 ```
 
+This is functionality that other packages allow.
+<details>
+  <summary>Response</summary>
+
+```
+{
+  success: true,
+  value: {
+    output: 'Clock stopped; everyone smiled as tomorrow finally arrived before yesterday.',
+    toolCalls: [],
+    usage: {
+      inputTokens: 14,
+      outputTokens: 15,
+      cachedInputTokens: 0,
+      totalTokens: 29
+    },
+    cost: {
+      inputCost: 0.000035,
+      outputCost: 0.000225,
+      cachedInputCost: undefined,
+      totalCost: 0.00026,
+      currency: 'USD'
+    },
+    model: 'gpt-5.4'
+  }
+}
+```
+</details>
+
+What if you wanted to have fallbacks in case the OpenAI API was down? Just change the `model` field:
+
+```ts
+  const response = await text({
+    messages,
+    model: fallback("gpt-5.4", "gemini-2.5-flash-lite"),
+    // or multiple fallbacks:
+    // model: fallback("gpt-5.4", ["gemini-2.5-flash-lite", "gemini-3-flash-preview"]),
+  });
+```
+
+Or what if you wanted to try a couple of models and take the first response?
+
+```ts
+  const response = await text({
+    messages,
+    model: race("gpt-5.4", "gemini-2.5-flash-lite", "o4-mini"),
+  });
+```
+
+Or combine them:
+
+```ts
+  const response = await text({
+    messages,
+    model: race(fallback("gpt-5.4", "gemini-2.5-flash-lite"), "o4-mini"),
+  });
+```
+
+You get the idea.
+
 ## Longer tutorial
 To use Smoltak, you first create a client:
 
@@ -157,20 +214,15 @@ 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 consecutive calls. |
 
-## Prior art
+## 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:
+
 - Langchain
-OpenRouter
+- OpenRouter
 - Vercel AI
 
-These are all good options, but they are quite heavy, and I wanted a lighter option. That said, you may be better off with one of the above alternatives:
-- They are backed by a business and are more likely to be responsive.
-- They support way more functionality and providers. Smoltalk currently supports just a subset of functionality for OpenAI and Google.
-
-## Functionality
-Smoltalk pretty much lets you generate text using an OpenAI or Google model, with support for function calling and structured output, and that's it. I will add functionality and providers sporadically when I have time and need.
-
 ## Contributing
-This repo could use some help! Any of the following contributions would be helpful:
+Contributions are welcome. Any of the following contributions would be helpful:
 - Adding support for API parameters or endpoints
 - Adding support for different providers
-- Updating the list of models
+- Updating the list of models

package/dist/client.js

@@ -26,29 +26,38 @@ export function getClient(config) {
         }
         provider = model.provider;
     }
-    const clientConfig = { ...config, model: modelName };
+    const resolvedKeys = {
+        openAiApiKey: config.openAiApiKey || process.env.OPENAI_API_KEY,
+        googleApiKey: config.googleApiKey || process.env.GEMINI_API_KEY,
+        anthropicApiKey: config.anthropicApiKey || process.env.ANTHROPIC_API_KEY,
+    };
+    const clientConfig = {
+        ...config,
+        ...resolvedKeys,
+        model: modelName,
+    };
     switch (provider) {
         case "anthropic":
-            if (!config.anthropicApiKey) {
-                throw new SmolError("No Anthropic API key provided. Please provide an Anthropic API key in the config using anthropicApiKey.");
+            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.");
             }
             return new SmolAnthropic({
                 ...clientConfig,
-                anthropicApiKey: config.anthropicApiKey,
+                anthropicApiKey: resolvedKeys.anthropicApiKey,
             });
         case "openai":
-            if (!config.openAiApiKey) {
-                throw new SmolError("No OpenAI API key provided. Please provide an OpenAI API key in the config using openAiApiKey.");
+            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.");
             }
             return new SmolOpenAi(clientConfig);
         case "openai-responses":
-            if (!config.openAiApiKey) {
-                throw new SmolError("No OpenAI API key provided. Please provide an OpenAI API key in the config using openAiApiKey.");
+            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.");
             }
             return new SmolOpenAiResponses(clientConfig);
         case "google":
-            if (!config.googleApiKey) {
-                throw new SmolError("No Google API key provided. Please provide a Google API key in the config using googleApiKey.");
+            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.");
             }
             return new SmolGoogle(clientConfig);
         case "ollama":

package/dist/model.js

@@ -1,4 +1,4 @@
-import { getModel, isTextModel, textModels, } from "./models.js";
+import { getModel, isTextModel, textModels, registeredTextModels, } from "./models.js";
 import { SmolError } from "./smolError.js";
 import { ModelConfigSchema, ModelNameAndProviderSchema, ModelNameSchema, } from "./strategies/types.js";
 import { round } from "./util.js";
@@ -41,7 +41,7 @@ export class Model {
         }
         return undefined;
     }
-    resolveModel(models = textModels) {
+    resolveModel(models = [...registeredTextModels, ...textModels]) {
         if (ModelNameSchema.safeParse(this.model).success) {
             return this.model;
         }
@@ -120,6 +120,8 @@ export class Model {
                 return (m.inputTokenCost ?? 0) + (m.outputTokenCost ?? 0);
             case "large-context":
                 return m.maxInputTokens;
+            default:
+                throw new SmolError(`Unknown optimization: ${optimization}`);
         }
     }
     isLowerBetter(optimization) {

package/dist/models.d.ts

@@ -13,7 +13,7 @@ export declare const ProviderSchema: z.ZodEnum<{
 export type Provider = z.infer<typeof ProviderSchema>;
 export type BaseModel = {
     modelName: string;
-    provider: Provider;
+    provider: string;
     description?: string;
     inputTokenCost?: number;
     cachedInputTokenCost?: number;
@@ -32,7 +32,6 @@ export type ImageModel = BaseModel & {
 };
 export type TextModel = BaseModel & {
     type: "text";
-    modelName: string;
     maxInputTokens: number;
     maxOutputTokens: number;
     outputTokensPerSecond?: number;
@@ -68,7 +67,7 @@ export declare const speechToTextModels: readonly [{
 export declare const textModels: readonly [{
     readonly type: "text";
     readonly modelName: "gpt-4o-mini";
-    readonly description: "GPT-4o mini (“o” for “omni”) is a fast, affordable small model for focused tasks. It accepts both text and image inputs, and produces text outputs (including Structured Outputs). It is ideal for fine-tuning, and model outputs from a larger model like GPT-4o can be distilled to GPT-4o-mini to produce similar results at lower cost and latency. The knowledge cutoff for GPT-4o-mini models is October, 2023.";
+    readonly description: "GPT-4o mini ('o' for 'omni') is a fast, affordable small model for focused tasks. It accepts both text and image inputs, and produces text outputs (including Structured Outputs). It is ideal for fine-tuning, and model outputs from a larger model like GPT-4o can be distilled to GPT-4o-mini to produce similar results at lower cost and latency. Knowledge cutoff: July 2025.";
     readonly maxInputTokens: 128000;
     readonly maxOutputTokens: 16384;
     readonly inputTokenCost: 0.15;
@@ -79,7 +78,7 @@ export declare const textModels: readonly [{
 }, {
     readonly type: "text";
     readonly modelName: "gpt-4o";
-    readonly description: "GPT-4o (“o” for “omni”) is our versatile, high-intelligence flagship model. It accepts both text and image inputs, and produces text outputs (including Structured Outputs). The knowledge cutoff for GPT-4o-mini models is October, 2023.";
+    readonly description: "GPT-4o ('o' for 'omni') is our versatile, high-intelligence flagship model. It accepts both text and image inputs, and produces text outputs (including Structured Outputs). Knowledge cutoff: April 2024.";
     readonly maxInputTokens: 128000;
     readonly maxOutputTokens: 16384;
     readonly inputTokenCost: 2.5;
@@ -90,7 +89,7 @@ export declare const textModels: readonly [{
 }, {
     readonly type: "text";
     readonly modelName: "o3";
-    readonly description: "o3 is a reasoning model that sets a new standard for math, science, coding, visual reasoning tasks, and technical writing. Part of the o-series of reasoning models. The knowledge cutoff for o3 models is October, 2023.";
+    readonly description: "o3 is a reasoning model that sets a new standard for math, science, coding, visual reasoning tasks, and technical writing. Part of the o-series of reasoning models. Knowledge cutoff: June 2024.";
     readonly maxInputTokens: 200000;
     readonly maxOutputTokens: 100000;
     readonly inputTokenCost: 2;
@@ -108,8 +107,8 @@ export declare const textModels: readonly [{
 }, {
     readonly type: "text";
     readonly modelName: "o3-mini";
-    readonly description: "o3-mini is our most recent small reasoning model, providing high intelligence at the same cost and latency targets of o1-mini. o3-mini also supports key developer features, like Structured Outputs, function calling, Batch API, and more. Like other models in the o-series, it is designed to excel at science, math, and coding tasks.The knowledge cutoff for o3-mini models is October, 2023.";
-    readonly maxInputTokens: 200000;
+    readonly description: "o3-mini is our most recent small reasoning model, providing high intelligence at the same cost and latency targets of o1-mini. o3-mini also supports key developer features, like Structured Outputs, function calling, Batch API, and more. Like other models in the o-series, it is designed to excel at science, math, and coding tasks. Knowledge cutoff: June 2024.";
+    readonly maxInputTokens: 500000;
     readonly maxOutputTokens: 100000;
     readonly inputTokenCost: 1.1;
     readonly cachedInputTokenCost: 0.55;
@@ -129,9 +128,9 @@ export declare const textModels: readonly [{
     readonly description: "Latest small o-series model optimized for fast, effective reasoning with exceptional performance in coding and visual tasks. Knowledge cutoff: June 2024.";
     readonly maxInputTokens: 200000;
     readonly maxOutputTokens: 100000;
-    readonly inputTokenCost: 1.1;
-    readonly cachedInputTokenCost: 0.275;
-    readonly outputTokenCost: 4.4;
+    readonly inputTokenCost: 0.6;
+    readonly cachedInputTokenCost: 0.3;
+    readonly outputTokenCost: 2.4;
     readonly outputTokensPerSecond: 135;
     readonly reasoning: {
         readonly levels: readonly ["low", "medium", "high"];
@@ -325,6 +324,20 @@ export declare const textModels: readonly [{
         readonly outputsSignatures: false;
     };
     readonly provider: "openai";
+}, {
+    readonly type: "text";
+    readonly modelName: "gpt-5.2-pro";
+    readonly description: "GPT-5.2 Pro uses more compute for complex reasoning tasks. 400K context window. Knowledge cutoff: August 2025.";
+    readonly maxInputTokens: 400000;
+    readonly maxOutputTokens: 128000;
+    readonly inputTokenCost: 21;
+    readonly outputTokenCost: 168;
+    readonly reasoning: {
+        readonly canDisable: false;
+        readonly outputsThinking: false;
+        readonly outputsSignatures: false;
+    };
+    readonly provider: "openai";
 }, {
     readonly type: "text";
     readonly modelName: "gpt-5.4";
@@ -676,7 +689,11 @@ export type ImageModelName = (typeof imageModels)[number]["modelName"];
 export type SpeechToTextModelName = (typeof speechToTextModels)[number]["modelName"];
 export type EmbeddingsModelName = (typeof embeddingsModels)[number]["modelName"];
 export type ModelName = TextModelName | ImageModelName | SpeechToTextModelName;
-export declare function getModel(modelName: ModelName): {
+export declare const registeredTextModels: TextModel[];
+export declare function registerTextModel(model: Omit<TextModel, "type"> & {
+    type?: "text";
+}): void;
+export declare function getModel(modelName: ModelName): TextModel | {
     readonly type: "speech-to-text";
     readonly modelName: "whisper-local";
     readonly provider: "local";
@@ -688,7 +705,7 @@ export declare function getModel(modelName: ModelName): {
 } | {
     readonly type: "text";
     readonly modelName: "gpt-4o-mini";
-    readonly description: "GPT-4o mini (“o” for “omni”) is a fast, affordable small model for focused tasks. It accepts both text and image inputs, and produces text outputs (including Structured Outputs). It is ideal for fine-tuning, and model outputs from a larger model like GPT-4o can be distilled to GPT-4o-mini to produce similar results at lower cost and latency. The knowledge cutoff for GPT-4o-mini models is October, 2023.";
+    readonly description: "GPT-4o mini ('o' for 'omni') is a fast, affordable small model for focused tasks. It accepts both text and image inputs, and produces text outputs (including Structured Outputs). It is ideal for fine-tuning, and model outputs from a larger model like GPT-4o can be distilled to GPT-4o-mini to produce similar results at lower cost and latency. Knowledge cutoff: July 2025.";
     readonly maxInputTokens: 128000;
     readonly maxOutputTokens: 16384;
     readonly inputTokenCost: 0.15;
@@ -699,7 +716,7 @@ export declare function getModel(modelName: ModelName): {
 } | {
     readonly type: "text";
     readonly modelName: "gpt-4o";
-    readonly description: "GPT-4o (“o” for “omni”) is our versatile, high-intelligence flagship model. It accepts both text and image inputs, and produces text outputs (including Structured Outputs). The knowledge cutoff for GPT-4o-mini models is October, 2023.";
+    readonly description: "GPT-4o ('o' for 'omni') is our versatile, high-intelligence flagship model. It accepts both text and image inputs, and produces text outputs (including Structured Outputs). Knowledge cutoff: April 2024.";
     readonly maxInputTokens: 128000;
     readonly maxOutputTokens: 16384;
     readonly inputTokenCost: 2.5;
@@ -710,7 +727,7 @@ export declare function getModel(modelName: ModelName): {
 } | {
     readonly type: "text";
     readonly modelName: "o3";
-    readonly description: "o3 is a reasoning model that sets a new standard for math, science, coding, visual reasoning tasks, and technical writing. Part of the o-series of reasoning models. The knowledge cutoff for o3 models is October, 2023.";
+    readonly description: "o3 is a reasoning model that sets a new standard for math, science, coding, visual reasoning tasks, and technical writing. Part of the o-series of reasoning models. Knowledge cutoff: June 2024.";
     readonly maxInputTokens: 200000;
     readonly maxOutputTokens: 100000;
     readonly inputTokenCost: 2;
@@ -728,8 +745,8 @@ export declare function getModel(modelName: ModelName): {
 } | {
     readonly type: "text";
     readonly modelName: "o3-mini";
-    readonly description: "o3-mini is our most recent small reasoning model, providing high intelligence at the same cost and latency targets of o1-mini. o3-mini also supports key developer features, like Structured Outputs, function calling, Batch API, and more. Like other models in the o-series, it is designed to excel at science, math, and coding tasks.The knowledge cutoff for o3-mini models is October, 2023.";
-    readonly maxInputTokens: 200000;
+    readonly description: "o3-mini is our most recent small reasoning model, providing high intelligence at the same cost and latency targets of o1-mini. o3-mini also supports key developer features, like Structured Outputs, function calling, Batch API, and more. Like other models in the o-series, it is designed to excel at science, math, and coding tasks. Knowledge cutoff: June 2024.";
+    readonly maxInputTokens: 500000;
     readonly maxOutputTokens: 100000;
     readonly inputTokenCost: 1.1;
     readonly cachedInputTokenCost: 0.55;
@@ -749,9 +766,9 @@ export declare function getModel(modelName: ModelName): {
     readonly description: "Latest small o-series model optimized for fast, effective reasoning with exceptional performance in coding and visual tasks. Knowledge cutoff: June 2024.";
     readonly maxInputTokens: 200000;
     readonly maxOutputTokens: 100000;
-    readonly inputTokenCost: 1.1;
-    readonly cachedInputTokenCost: 0.275;
-    readonly outputTokenCost: 4.4;
+    readonly inputTokenCost: 0.6;
+    readonly cachedInputTokenCost: 0.3;
+    readonly outputTokenCost: 2.4;
     readonly outputTokensPerSecond: 135;
     readonly reasoning: {
         readonly levels: readonly ["low", "medium", "high"];
@@ -945,6 +962,20 @@ export declare function getModel(modelName: ModelName): {
         readonly outputsSignatures: false;
     };
     readonly provider: "openai";
+} | {
+    readonly type: "text";
+    readonly modelName: "gpt-5.2-pro";
+    readonly description: "GPT-5.2 Pro uses more compute for complex reasoning tasks. 400K context window. Knowledge cutoff: August 2025.";
+    readonly maxInputTokens: 400000;
+    readonly maxOutputTokens: 128000;
+    readonly inputTokenCost: 21;
+    readonly outputTokenCost: 168;
+    readonly reasoning: {
+        readonly canDisable: false;
+        readonly outputsThinking: false;
+        readonly outputsSignatures: false;
+    };
+    readonly provider: "openai";
 } | {
     readonly type: "text";
     readonly modelName: "gpt-5.4";

package/dist/models.js

@@ -33,7 +33,7 @@ export const textModels = [
     {
         type: "text",
         modelName: "gpt-4o-mini",
-        description: "GPT-4o mini (“o” for “omni”) is a fast, affordable small model for focused tasks. It accepts both text and image inputs, and produces text outputs (including Structured Outputs). It is ideal for fine-tuning, and model outputs from a larger model like GPT-4o can be distilled to GPT-4o-mini to produce similar results at lower cost and latency. The knowledge cutoff for GPT-4o-mini models is October, 2023.",
+        description: "GPT-4o mini ('o' for 'omni') is a fast, affordable small model for focused tasks. It accepts both text and image inputs, and produces text outputs (including Structured Outputs). It is ideal for fine-tuning, and model outputs from a larger model like GPT-4o can be distilled to GPT-4o-mini to produce similar results at lower cost and latency. Knowledge cutoff: July 2025.",
         maxInputTokens: 128000,
         maxOutputTokens: 16384,
         inputTokenCost: 0.15,
@@ -45,7 +45,7 @@ export const textModels = [
     {
         type: "text",
         modelName: "gpt-4o",
-        description: "GPT-4o (“o” for “omni”) is our versatile, high-intelligence flagship model. It accepts both text and image inputs, and produces text outputs (including Structured Outputs). The knowledge cutoff for GPT-4o-mini models is October, 2023.",
+        description: "GPT-4o ('o' for 'omni') is our versatile, high-intelligence flagship model. It accepts both text and image inputs, and produces text outputs (including Structured Outputs). Knowledge cutoff: April 2024.",
         maxInputTokens: 128000,
         maxOutputTokens: 16384,
         inputTokenCost: 2.5,
@@ -57,7 +57,7 @@ export const textModels = [
     {
         type: "text",
         modelName: "o3",
-        description: "o3 is a reasoning model that sets a new standard for math, science, coding, visual reasoning tasks, and technical writing. Part of the o-series of reasoning models. The knowledge cutoff for o3 models is October, 2023.",
+        description: "o3 is a reasoning model that sets a new standard for math, science, coding, visual reasoning tasks, and technical writing. Part of the o-series of reasoning models. Knowledge cutoff: June 2024.",
         maxInputTokens: 200000,
         maxOutputTokens: 100000,
         inputTokenCost: 2,
@@ -76,8 +76,8 @@ export const textModels = [
     {
         type: "text",
         modelName: "o3-mini",
-        description: "o3-mini is our most recent small reasoning model, providing high intelligence at the same cost and latency targets of o1-mini. o3-mini also supports key developer features, like Structured Outputs, function calling, Batch API, and more. Like other models in the o-series, it is designed to excel at science, math, and coding tasks.The knowledge cutoff for o3-mini models is October, 2023.",
-        maxInputTokens: 200000,
+        description: "o3-mini is our most recent small reasoning model, providing high intelligence at the same cost and latency targets of o1-mini. o3-mini also supports key developer features, like Structured Outputs, function calling, Batch API, and more. Like other models in the o-series, it is designed to excel at science, math, and coding tasks. Knowledge cutoff: June 2024.",
+        maxInputTokens: 500000,
         maxOutputTokens: 100000,
         inputTokenCost: 1.1,
         cachedInputTokenCost: 0.55,
@@ -98,9 +98,9 @@ export const textModels = [
         description: "Latest small o-series model optimized for fast, effective reasoning with exceptional performance in coding and visual tasks. Knowledge cutoff: June 2024.",
         maxInputTokens: 200000,
         maxOutputTokens: 100000,
-        inputTokenCost: 1.1,
-        cachedInputTokenCost: 0.275,
-        outputTokenCost: 4.4,
+        inputTokenCost: 0.6,
+        cachedInputTokenCost: 0.3,
+        outputTokenCost: 2.4,
         outputTokensPerSecond: 135,
         reasoning: {
             levels: ["low", "medium", "high"],
@@ -308,6 +308,21 @@ export const textModels = [
         },
         provider: "openai",
     },
+    {
+        type: "text",
+        modelName: "gpt-5.2-pro",
+        description: "GPT-5.2 Pro uses more compute for complex reasoning tasks. 400K context window. Knowledge cutoff: August 2025.",
+        maxInputTokens: 400000,
+        maxOutputTokens: 128000,
+        inputTokenCost: 21,
+        outputTokenCost: 168,
+        reasoning: {
+            canDisable: false,
+            outputsThinking: false,
+            outputsSignatures: false,
+        },
+        provider: "openai",
+    },
     {
         type: "text",
         modelName: "gpt-5.4",
@@ -715,8 +730,17 @@ export const imageModels = [
 export const embeddingsModels = [
     { type: "embeddings", modelName: "text-embedding-3-small", tokenCost: 0.02 },
 ];
+export const registeredTextModels = [];
+export function registerTextModel(model) {
+    registeredTextModels.push({ ...model, type: "text" });
+}
 export function getModel(modelName) {
-    const allModels = [...textModels, ...imageModels, ...speechToTextModels];
+    const allModels = [
+        ...textModels,
+        ...imageModels,
+        ...speechToTextModels,
+        ...registeredTextModels,
+    ];
     return allModels.find((model) => model.modelName === modelName);
 }
 export function isImageModel(model) {

package/dist/strategies/index.d.ts

@@ -7,5 +7,5 @@ export * from "./raceStrategy.js";
 export * from "./types.js";
 export declare function race(...strategies: ModelParam[]): Strategy;
 export declare function id(model: ModelLike): Strategy;
-export declare function fallback(primaryStrategy: ModelParam, config: FallbackStrategyConfig): Strategy;
+export declare function fallback(primaryStrategy: ModelParam, config: FallbackStrategyConfig | string | string[]): Strategy;
 export declare function fromJSON(json: StrategyJSON): Strategy;

package/dist/strategies/index.js

@@ -14,7 +14,17 @@ export function id(model) {
     return new IDStrategy(model);
 }
 export function fallback(primaryStrategy, config) {
-    return new FallbackStrategy(primaryStrategy, config);
+    let resolvedConfig;
+    if (typeof config === "string") {
+        resolvedConfig = { error: [config] };
+    }
+    else if (Array.isArray(config)) {
+        resolvedConfig = { error: config };
+    }
+    else {
+        resolvedConfig = config;
+    }
+    return new FallbackStrategy(primaryStrategy, resolvedConfig);
 }
 export function fromJSON(json) {
     if (IDStrategyJSONSchema.safeParse(json).success) {

package/dist/types.d.ts

@@ -4,7 +4,7 @@ import z, { ZodType } from "zod";
 import { Message } from "./classes/message/index.js";
 import { ToolCall } from "./classes/ToolCall.js";
 import { Model } from "./model.js";
-import { ModelName, Provider } from "./models.js";
+import { ModelName } from "./models.js";
 import { ModelConfig, ModelNameAndProvider, Strategy, StrategyJSON } from "./strategies/types.js";
 import { Result } from "./types/result.js";
 export type ThinkingBlock = {
@@ -72,8 +72,95 @@ export type SmolConfig = {
     anthropicApiKey?: string;
     ollamaApiKey?: string;
     ollamaHost?: string;
+    /**
+    The given model determines both
+    - what client is used
+    - what strategy is executed.
+  
+    ## 1. Specifying a model directly
+    The simplest case is to specify the name of a model from lib/models.ts.
+    Example:
+  
+    ```
+      model: "claude-sonnet-4-6"
+    ```
+  
+    ## 2. Specifying a model config (letting Smoltalk pick the model)
+    You can instead also choose to let Smoltalk pick the model that it thinks
+    will be best for certain parameters. For example:
+    ```
+      model: {
+        // find the fastest model
+        optimizeFor: ["speed"],
+  
+        // from either Anthropic or Google, whichever is faster
+        providers: ["anthropic", "google"],
+        limit: {
+          // 1 mil input tokens + 1 mil output tokens together
+          // should cost less than $10 for the models being considered
+          cost: 10,
+        },
+      }
+    ```
+  
+    This can be a good option because as better models come out,
+    you won't need to update your code. You can just update Smoltalk
+    and it will pick the best model automatically.
+  
+    ## 3. Specifying a strategy
+    Finally, you can instead specify a strategy to execute. For example:
+  
+    ```
+      model: {
+        type: "race",
+        params: {
+          strategies: ["gemini-2.5-flash-lite", "gemini-2.5-pro"],
+        },
+      }
+    ```
+  
+    In this case, Smoltalk will run your request over using both LLMs simultaneously,
+    and take the response that finishes first.
+  
+    You can also choose to specify fallbacks in case the first model
+    returns an error for some reason. This can be a good way to try something
+    with a fast model and then use a slower but more powerful model if the first one fails.
+  
+    ```
+      model: {
+        type: "fallback",
+        params: {
+          primaryStrategy: "gemini-2.5-flash-lite",
+          config: {
+            error: ["gemini-2.5-pro"],
+          },
+        },
+      }
+    ```
+  
+    You can of course combine strategies together to create more complex behavior:
+  
+    ```
+      const geminiLiteWithFallback = {
+        type: "fallback",
+        params: {
+          primaryStrategy: "gemini-2.5-flash-lite",
+          config: {
+            error: ["gemini-2.5-pro"],
+          },
+        },
+      };
+  
+      model: {
+        type: "race",
+        params: {
+          strategies: ["gemini-2.5-pro", geminiLiteWithFallback],
+        },
+      }
+    ```
+      */
     model: ModelParam;
-    provider?: Provider;
+    provider?: string;
     logLevel?: LogLevel;
     statelog?: Partial<{
         host: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smoltalk",
-  "version": "0.0.53",
+  "version": "0.0.55",
   "description": "A common interface for LLM APIs",
   "homepage": "https://github.com/egonSchiele/smoltalk",
   "scripts": {
@@ -33,7 +33,6 @@
   "devDependencies": {
     "@types/node": "^25.0.3",
     "prettier": "^3.7.4",
-    "termcolors": "github:egonSchiele/termcolors",
     "typedoc": "^0.28.15",
     "typescript": "^5.9.3",
     "vitest": "^4.0.16"