smoltalk 0.0.53 → 0.0.54

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. Hello world, this is functionality that other packages allow.
 
 ## Install
 
@@ -8,7 +8,7 @@ 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";

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;
@@ -676,7 +675,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";

package/dist/models.js

@@ -715,8 +715,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/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.54",
   "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"