smoltalk 0.12.1 → 0.13.0

package/README.md

@@ -197,8 +197,8 @@ Two provider notes:
 | `model` | `ModelName` | **Required.** The model to use (e.g. `"gpt-4o"`, `"gemini-2.0-flash-lite"`). |
 | `messages` | `Message[]` | **Required.** The conversation messages to send. |
 | `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()`. |
+| `baseUrl` | `{ ollama?, openRouter?, deepInfra?, liteLlm?, openAiCompat?, mlx? }` | Custom base URLs. `ollama` defaults to `$OLLAMA_HOST` then `http://localhost:11434`; `openRouter`/`deepInfra` defaults are baked in; `mlx` defaults to `$MLX_BASE_URL` then `http://127.0.0.1:8080/v1`; `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"`, `"mlx"`, 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. |
@@ -254,6 +254,7 @@ model ids aren't in the smoltalk registry.
 | `"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 |
+| `"mlx"` | An MLX server on localhost (`mlx_lm.server`, or `agency local serve`) | none — `baseUrl.mlx` or `MLX_BASE_URL` (default `http://127.0.0.1:8080/v1`); no API key | Always `0` |
 
 ```ts
 import { textSync, userMessage } from "smoltalk";
@@ -275,6 +276,7 @@ const r = await textSync({
 | `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 |
+| `mlx`           | ✅   | ❌         | ❌               | ❌ |
 
 Smoltalk surfaces a clear `failure(...)` from `embed()`/`image()` for the
 unsupported combinations rather than silently dropping the call.

package/dist/client.d.ts

@@ -8,6 +8,7 @@ export * from "./clients/openaiCompat.js";
 export * from "./clients/openrouter.js";
 export * from "./clients/deepinfra.js";
 export * from "./clients/litellm.js";
+export * from "./clients/mlx.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

@@ -8,6 +8,7 @@ export * from "./clients/openaiCompat.js";
 export * from "./clients/openrouter.js";
 export * from "./clients/deepinfra.js";
 export * from "./clients/litellm.js";
+export * from "./clients/mlx.js";
 import { SmolAnthropic } from "./clients/anthropic.js";
 import { SmolGoogle } from "./clients/google.js";
 import { SmolOllama } from "./clients/ollama.js";
@@ -17,6 +18,7 @@ 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 { SmolMlx } from "./clients/mlx.js";
 import { getModel, isTextModel } from "./models.js";
 import { SmolError } from "./smolError.js";
 import { resolveApiKey, resolveProvider } from "./util/provider.js";
@@ -103,6 +105,8 @@ export function getClient(config) {
             return new SmolLiteLlm(clientConfig);
         case "openai-compat":
             return new SmolOpenAiCompat(clientConfig);
+        case "mlx":
+            return new SmolMlx(clientConfig);
         default:
             if (provider in registeredProviders) {
                 const ClientClass = registeredProviders[provider];

package/dist/clients/mlx.d.ts

@@ -0,0 +1,15 @@
+import { SmolOpenAiCompat } from "./openaiCompat.js";
+import type { SmolConfig } from "../types.js";
+/**
+ * Client for an MLX server on localhost, usually started with `mlx_lm.server`
+ * (or `agency local serve`). The server speaks the OpenAI chat format, so this
+ * is the openai-compat client with three things fixed: the base URL has a
+ * default, no API key is needed, and the cost is always zero.
+ */
+export declare class SmolMlx extends SmolOpenAiCompat {
+    protected resolveClientOptions(config: SmolConfig): {
+        apiKey: string;
+        baseURL: string;
+    };
+    protected resolveCostUsd(): number;
+}

package/dist/clients/mlx.js

@@ -0,0 +1,19 @@
+import { SmolOpenAiCompat } from "./openaiCompat.js";
+import { resolveBaseUrl } from "../util/provider.js";
+/**
+ * Client for an MLX server on localhost, usually started with `mlx_lm.server`
+ * (or `agency local serve`). The server speaks the OpenAI chat format, so this
+ * is the openai-compat client with three things fixed: the base URL has a
+ * default, no API key is needed, and the cost is always zero.
+ */
+export class SmolMlx extends SmolOpenAiCompat {
+    resolveClientOptions(config) {
+        // resolveBaseUrl always returns a value for "mlx" (it has a default).
+        const baseURL = resolveBaseUrl("mlx", config);
+        // The OpenAI SDK refuses an empty key. The local server never reads it.
+        return { apiKey: "mlx-local", baseURL };
+    }
+    resolveCostUsd() {
+        return 0;
+    }
+}

package/dist/clients/openai.js

@@ -179,7 +179,11 @@ export class SmolOpenAi extends BaseClient {
             throw new SmolContentPolicyError("Content blocked by OpenAI content filter");
         }
         const message = completion.choices[0].message;
-        const output = message.content;
+        // mlx_lm.server omits `content` entirely on a tool-call reply, where OpenAI
+        // sends an explicit null. Coerce the missing case to null so `output`
+        // honors its declared `string | null` type (a no-op for real OpenAI, whose
+        // content is already string | null).
+        const output = message.content ?? null;
         const _toolCalls = message.tool_calls;
         const toolCalls = [];
         if (_toolCalls) {

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from "./client.js";
 export * from "./types.js";
 export * from "./models.js";
 export * from "./modelData.js";
+export * from "./modelRefresh.js";
 export * from "./model.js";
 export * from "./smolError.js";
 export * from "./util/util.js";

package/dist/index.js

@@ -2,6 +2,7 @@ export * from "./client.js";
 export * from "./types.js";
 export * from "./models.js";
 export * from "./modelData.js";
+export * from "./modelRefresh.js";
 export * from "./model.js";
 export * from "./smolError.js";
 export * from "./util/util.js";

package/dist/modelData.d.ts

@@ -30,11 +30,3 @@ export declare function parseModelDataBlob(raw: string): Result<ModelDataBlob>;
 export declare function deepMergeEntry<T>(base: T, overlay: T): T;
 export declare function mergeModelData(base: ModelType[], overlay: ModelType[]): ModelType[];
 export declare function mergeHostedTools(base: HostedTool[], overlay: HostedTool[]): HostedTool[];
-export declare const DEFAULT_MODEL_DATA_URL = "https://raw.githubusercontent.com/egonSchiele/smoltalk/main/packages/smoltalk/data/model-data.json";
-export type Fetcher = (url: string, signal?: AbortSignal) => Promise<string>;
-export type RefreshOptions = {
-    url?: string;
-    fetcher?: Fetcher;
-    signal?: AbortSignal;
-};
-export declare function refreshModels(opts?: RefreshOptions): Promise<Result<ModelDataBlob>>;

package/dist/modelData.js

@@ -1,6 +1,4 @@
 import z from "zod";
-import { readFile } from "node:fs/promises";
-import { fileURLToPath } from "node:url";
 import { success, failure } from "./types/result.js";
 export const SUPPORTED_SCHEMA_VERSION = 1;
 const EnvelopeSchema = z.object({
@@ -154,69 +152,3 @@ export function mergeModelData(base, overlay) {
 export function mergeHostedTools(base, overlay) {
     return mergeByKey(base, overlay, (t) => `${t.provider}:${t.name}`);
 }
-export const DEFAULT_MODEL_DATA_URL = "https://raw.githubusercontent.com/egonSchiele/smoltalk/main/packages/smoltalk/data/model-data.json";
-const MAX_BYTES = 10_000_000;
-const TIMEOUT_MS = 15_000;
-function enforceSizeCap(text) {
-    if (Buffer.byteLength(text, "utf8") > MAX_BYTES) {
-        throw new Error(`Model data exceeds the ${MAX_BYTES}-byte cap`);
-    }
-    return text;
-}
-// The default fetcher supports remote https:// URLs and local file:// URLs.
-// file:// lets users point at a self-hosted on-disk catalog (and powers the
-// integration test). Any other scheme is rejected.
-async function defaultFetcher(url, signal) {
-    if (url.startsWith("file://")) {
-        const path = fileURLToPath(url);
-        const text = await readFile(path, "utf8");
-        return enforceSizeCap(text);
-    }
-    if (url.startsWith("https://")) {
-        const res = await fetch(url, { signal });
-        if (!res.ok) {
-            throw new Error(`HTTP ${res.status} ${res.statusText}`);
-        }
-        return enforceSizeCap(await res.text());
-    }
-    throw new Error(`Unsupported model-data URL scheme (expected https:// or file://): ${url}`);
-}
-export async function refreshModels(opts = {}) {
-    let url = DEFAULT_MODEL_DATA_URL;
-    if (process.env.SMOLTALK_MODEL_DATA_URL) {
-        url = process.env.SMOLTALK_MODEL_DATA_URL;
-    }
-    if (opts.url) {
-        url = opts.url;
-    }
-    let fetcher = defaultFetcher;
-    if (opts.fetcher) {
-        fetcher = opts.fetcher;
-    }
-    // Always drive the fetcher off our own controller so the timeout can abort
-    // it. Forward an externally-supplied signal into the same controller so both
-    // the timeout and the caller can cancel.
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
-    if (opts.signal) {
-        if (opts.signal.aborted) {
-            controller.abort();
-        }
-        else {
-            opts.signal.addEventListener("abort", () => controller.abort(), {
-                once: true,
-            });
-        }
-    }
-    let raw;
-    try {
-        raw = await fetcher(url, controller.signal);
-    }
-    catch (err) {
-        return failure(`Could not fetch model data from ${url}: ${String(err)}`);
-    }
-    finally {
-        clearTimeout(timer);
-    }
-    return parseModelDataBlob(raw);
-}

package/dist/modelRefresh.d.ts

@@ -0,0 +1,10 @@
+import { type ModelDataBlob } from "./modelData.js";
+import { Result } from "./types/result.js";
+export declare const DEFAULT_MODEL_DATA_URL = "https://raw.githubusercontent.com/egonSchiele/smoltalk/main/packages/smoltalk/data/model-data.json";
+export type Fetcher = (url: string, signal?: AbortSignal) => Promise<string>;
+export type RefreshOptions = {
+    url?: string;
+    fetcher?: Fetcher;
+    signal?: AbortSignal;
+};
+export declare function refreshModels(opts?: RefreshOptions): Promise<Result<ModelDataBlob>>;

package/dist/modelRefresh.js

@@ -0,0 +1,78 @@
+/**
+ * Fetching refreshed model data from a remote or on-disk catalog.
+ *
+ * Split out of modelData.ts so that module — and therefore models.ts, and
+ * therefore the model registry — carries no Node dependency. Everything here
+ * needs a Node runtime (node:fs, Buffer, process.env); everything in
+ * modelData.ts is pure and bundles for the browser.
+ */
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { parseModelDataBlob } from "./modelData.js";
+import { failure } from "./types/result.js";
+export const DEFAULT_MODEL_DATA_URL = "https://raw.githubusercontent.com/egonSchiele/smoltalk/main/packages/smoltalk/data/model-data.json";
+const MAX_BYTES = 10_000_000;
+const TIMEOUT_MS = 15_000;
+function enforceSizeCap(text) {
+    if (Buffer.byteLength(text, "utf8") > MAX_BYTES) {
+        throw new Error(`Model data exceeds the ${MAX_BYTES}-byte cap`);
+    }
+    return text;
+}
+// The default fetcher supports remote https:// URLs and local file:// URLs.
+// file:// lets users point at a self-hosted on-disk catalog (and powers the
+// integration test). Any other scheme is rejected.
+async function defaultFetcher(url, signal) {
+    if (url.startsWith("file://")) {
+        const path = fileURLToPath(url);
+        const text = await readFile(path, "utf8");
+        return enforceSizeCap(text);
+    }
+    if (url.startsWith("https://")) {
+        const res = await fetch(url, { signal });
+        if (!res.ok) {
+            throw new Error(`HTTP ${res.status} ${res.statusText}`);
+        }
+        return enforceSizeCap(await res.text());
+    }
+    throw new Error(`Unsupported model-data URL scheme (expected https:// or file://): ${url}`);
+}
+export async function refreshModels(opts = {}) {
+    let url = DEFAULT_MODEL_DATA_URL;
+    if (process.env.SMOLTALK_MODEL_DATA_URL) {
+        url = process.env.SMOLTALK_MODEL_DATA_URL;
+    }
+    if (opts.url) {
+        url = opts.url;
+    }
+    let fetcher = defaultFetcher;
+    if (opts.fetcher) {
+        fetcher = opts.fetcher;
+    }
+    // Always drive the fetcher off our own controller so the timeout can abort
+    // it. Forward an externally-supplied signal into the same controller so both
+    // the timeout and the caller can cancel.
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    if (opts.signal) {
+        if (opts.signal.aborted) {
+            controller.abort();
+        }
+        else {
+            opts.signal.addEventListener("abort", () => controller.abort(), {
+                once: true,
+            });
+        }
+    }
+    let raw;
+    try {
+        raw = await fetcher(url, controller.signal);
+    }
+    catch (err) {
+        return failure(`Could not fetch model data from ${url}: ${String(err)}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    return parseModelDataBlob(raw);
+}

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", "openrouter", "deepinfra", "litellm", "openai-compat", "groq"];
+export declare const providers: readonly ["ollama", "openai", "openai-responses", "anthropic", "google", "replicate", "modal", "openrouter", "deepinfra", "litellm", "openai-compat", "groq", "mlx"];
 export declare const ProviderSchema: z.ZodEnum<{
     openai: "openai";
     anthropic: "anthropic";
@@ -14,6 +14,7 @@ export declare const ProviderSchema: z.ZodEnum<{
     litellm: "litellm";
     "openai-compat": "openai-compat";
     groq: "groq";
+    mlx: "mlx";
 }>;
 export type Provider = z.infer<typeof ProviderSchema>;
 export type BaseModel = {

package/dist/models.js

@@ -13,6 +13,7 @@ export const providers = [
     "litellm",
     "openai-compat",
     "groq",
+    "mlx",
 ];
 export const ProviderSchema = z.enum(providers);
 export const speechToTextModels = [

package/dist/types.d.ts

@@ -44,6 +44,8 @@ export type SmolConfig = {
         deepInfra?: string;
         liteLlm?: string;
         openAiCompat?: string;
+        /** The MLX server started by `mlx_lm.server` (or `agency local serve`). Defaults to http://127.0.0.1:8080/v1 (or $MLX_BASE_URL). */
+        mlx?: string;
     };
     /** Log level for internal debug logging. */
     logLevel?: LogLevel;

package/dist/util/provider.d.ts

@@ -29,6 +29,7 @@ type NestedKeyConfig = {
         deepInfra?: string;
         liteLlm?: string;
         openAiCompat?: string;
+        mlx?: string;
     };
 };
 /**

package/dist/util/provider.js

@@ -64,6 +64,8 @@ export function resolveBaseUrl(provider, config) {
             return b?.liteLlm || process.env.LITELLM_BASE_URL;
         case "openai-compat":
             return b?.openAiCompat || process.env.OPENAI_COMPAT_BASE_URL;
+        case "mlx":
+            return b?.mlx || process.env.MLX_BASE_URL || "http://127.0.0.1:8080/v1";
         default:
             return undefined;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smoltalk",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "A common interface for LLM APIs",
   "homepage": "https://github.com/egonSchiele/smoltalk",
   "files": [
@@ -12,6 +12,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.js"
     },
+    "./models": {
+      "types": "./dist/models.d.ts",
+      "import": "./dist/models.js",
+      "require": "./dist/models.js"
+    },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "import": "./dist/testing/index.js",