smoltalk 0.16.0 → 0.17.0

package/README.md

@@ -838,6 +838,43 @@ unsupported provider, a model without audio input, or audio that isn't
 `mp3`/`wav` surfaces as a `Failure` from that call, not from `audioPart()`
 itself. Audio is inlined as base64, not uploaded via the Files API.
 
+## In the browser
+
+smoltalk bundles for the browser. A bundler run for the browser (Vite,
+webpack with `target: "web"`, esbuild with `--platform=browser`) picks the
+browser side of smoltalk's `#platform` and `#ollama` imports on its own;
+there is no separate entry point and no flag. With esbuild, mark Node
+builtins external, because `@anthropic-ai/sdk` lazily imports `node:fs` on
+the path it takes when no API key is passed (Vite does this for you):
+
+```sh
+esbuild app.ts --bundle --platform=browser --format=esm --external:node:*
+```
+
+Differences from Node:
+
+- There are no environment variables. `env` reads as unset, nothing
+  throws, and a client built without a key fails with the SDK's own
+  missing-key error. Pass keys in `apiKey`.
+- A `{ kind: "path" }` attachment throws: "readFileBytes is not available
+  in a browser build of smoltalk."
+- `refreshModels` accepts `https:` URLs only; a `file:` URL fails the
+  same way, from `readTextFromFileUrl`.
+- `loadLlamaCpp` fails: it loads a native module. Without `entryPath` the
+  error is the loader's "Failed to load smoltalk-llama-cpp", wrapping the
+  browser's refusal to resolve the bare specifier; with `entryPath` it is
+  `pathToFileUrl`'s. Local inference in a browser is the `smoltalk-webllm`
+  plugin.
+
+The `openai` and `@anthropic-ai/sdk` clients are constructed with
+`dangerouslyAllowBrowser: true`. That flag exists because a key sent to a
+browser is visible to anyone who can open the page. For a production app,
+keep the key on a server. The built-in OpenAI, Anthropic, and Google
+clients take no base URL, so the browser side reaches such a server as an
+OpenAI-compatible endpoint: `provider: "openai-compat"` with
+`baseUrl.openAiCompat` set to the proxy, and the proxy holding the real
+key.
+
 ## 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:
 

package/dist/clients/anthropic.js

@@ -1,3 +1,4 @@
+import { env } from "#platform";
 import Anthropic from "@anthropic-ai/sdk";
 import { ToolCall } from "../classes/ToolCall.js";
 import { SystemMessage, DeveloperMessage } from "../classes/message/index.js";
@@ -219,11 +220,11 @@ export class SmolAnthropic extends BaseClient {
     model;
     constructor(config) {
         super(config);
-        const apiKey = config.apiKey?.anthropic || process.env.ANTHROPIC_API_KEY;
+        const apiKey = config.apiKey?.anthropic || env("ANTHROPIC_API_KEY");
         if (!apiKey) {
             throw new Error("Anthropic API key is required for SmolAnthropic client.");
         }
-        this.client = new Anthropic({ apiKey });
+        this.client = new Anthropic({ dangerouslyAllowBrowser: true, apiKey });
         this.logger = getLogger();
         this.model = new Model(config.model, config.provider, config.modelData);
     }

package/dist/clients/google.js

@@ -1,3 +1,4 @@
+import { env } from "#platform";
 import { GoogleGenAI } from "@google/genai";
 import { ToolCall } from "../classes/ToolCall.js";
 import { getLogger } from "../util/logger.js";
@@ -203,7 +204,7 @@ export class SmolGoogle extends BaseClient {
     model;
     constructor(config) {
         super(config);
-        const apiKey = config.apiKey?.google || process.env.GEMINI_API_KEY;
+        const apiKey = config.apiKey?.google || env("GEMINI_API_KEY");
         if (!apiKey) {
             throw new Error("Google API key is required for SmolGoogle client.");
         }

package/dist/clients/llamaCppLoader.js

@@ -1,4 +1,4 @@
-import { pathToFileURL } from "url";
+import { pathToFileUrl } from "#platform";
 import { hasProvider, registerProvider } from "../client.js";
 import { SmolError } from "../smolError.js";
 const realImport = (specifier) => import(specifier);
@@ -63,7 +63,7 @@ export function loadLlamaCpp(options) {
 async function doLoad(entryPath) {
     let importSource;
     if (entryPath) {
-        importSource = pathToFileURL(entryPath).href;
+        importSource = pathToFileUrl(entryPath);
     }
     else {
         importSource = "smoltalk-llama-cpp";

package/dist/clients/ollama.d.ts

@@ -1,4 +1,4 @@
-import { Ollama } from "ollama";
+import { Ollama } from "#ollama";
 import { PromptResult, Result, SmolClient, SmolConfig, StreamChunk } from "../types.js";
 import { BaseClient } from "./baseClient.js";
 import { ModelName } from "../models.js";

package/dist/clients/ollama.js

@@ -1,4 +1,4 @@
-import { Ollama } from "ollama";
+import { Ollama } from "#ollama";
 import { ToolCall } from "../classes/ToolCall.js";
 import { getLogger } from "../util/logger.js";
 import { redactAttachments } from "../util/redact.js";

package/dist/clients/openai.d.ts

@@ -14,7 +14,8 @@ export declare class SmolOpenAi extends BaseClient implements SmolClient {
     protected attachmentCapabilities(): ClientAttachmentCapabilities;
     /**
      * Build the `new OpenAI({...})` options. Subclasses override to inject a
-     * different baseURL or to pull the key from a different config field.
+     * different baseURL or to pull the key from a different config field. The
+     * constructor adds `dangerouslyAllowBrowser` itself.
      *
      * Default behavior: read OPENAI_API_KEY (or config.apiKey.openAi). Throws
      * if the key is missing — subclasses with required keys do their own check.

package/dist/clients/openai.js

@@ -1,3 +1,4 @@
+import { env } from "#platform";
 import OpenAI from "openai";
 import { success, } from "../types.js";
 import { ToolCall } from "../classes/ToolCall.js";
@@ -19,7 +20,7 @@ export class SmolOpenAi extends BaseClient {
     constructor(config) {
         super(config);
         const options = this.resolveClientOptions(config);
-        this.client = new OpenAI(options);
+        this.client = new OpenAI({ ...options, dangerouslyAllowBrowser: true });
         this.logger = getLogger();
         this.model = new Model(config.model, config.provider, config.modelData);
     }
@@ -29,13 +30,14 @@ export class SmolOpenAi extends BaseClient {
     }
     /**
      * Build the `new OpenAI({...})` options. Subclasses override to inject a
-     * different baseURL or to pull the key from a different config field.
+     * different baseURL or to pull the key from a different config field. The
+     * constructor adds `dangerouslyAllowBrowser` itself.
      *
      * 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;
+        const apiKey = config.apiKey?.openAi || env("OPENAI_API_KEY");
         if (!apiKey) {
             throw new Error("OpenAI API key is required for SmolOpenAi client.");
         }

package/dist/clients/openaiResponses.js

@@ -1,3 +1,4 @@
+import { env } from "#platform";
 import OpenAI from "openai";
 import { success, } from "../types.js";
 import { ToolCall } from "../classes/ToolCall.js";
@@ -57,11 +58,11 @@ export class SmolOpenAiResponses extends BaseClient {
     model;
     constructor(config) {
         super(config);
-        const apiKey = config.apiKey?.openAi || process.env.OPENAI_API_KEY;
+        const apiKey = config.apiKey?.openAi || env("OPENAI_API_KEY");
         if (!apiKey) {
             throw new Error("OpenAI API key is required for SmolOpenAiResponses client.");
         }
-        this.client = new OpenAI({ apiKey });
+        this.client = new OpenAI({ dangerouslyAllowBrowser: true, apiKey });
         this.logger = getLogger();
         this.model = new Model(config.model, config.provider, config.modelData);
     }

package/dist/clients/resolveAttachments.js

@@ -1,3 +1,4 @@
+import { bytesToBase64 } from "../util/base64.js";
 import { UserMessage } from "../classes/message/index.js";
 import { normalizeBlob } from "../util/blobRef.js";
 import { fileFamily } from "../util/attachments.js";
@@ -45,7 +46,7 @@ async function toBase64Source(source, allowed, maxBytes) {
         allowedMimePrefixes: allowed,
         maxBytes,
     });
-    return { kind: "base64", base64: Buffer.from(data).toString("base64"), mimeType };
+    return { kind: "base64", base64: bytesToBase64(data), mimeType };
 }
 /** Error message when a providerFile ref targets the wrong provider family, else null. */
 function providerFileError(fileProvider, targetProvider) {

package/dist/embed/openai.js

@@ -1,3 +1,4 @@
+import { base64ToBytes } from "../util/base64.js";
 import OpenAI from "openai";
 import { success, failure } from "../types/result.js";
 import { getModel, isEmbeddingsModel } from "../models.js";
@@ -10,7 +11,7 @@ import { round } from "../util/util.js";
  */
 function toFloats(embedding) {
     if (typeof embedding === "string") {
-        const bytes = Buffer.from(embedding, "base64");
+        const bytes = base64ToBytes(embedding);
         const view = new Float32Array(bytes.buffer, bytes.byteOffset, Math.floor(bytes.byteLength / 4));
         return Array.from(view);
     }
@@ -24,7 +25,7 @@ function toFloats(embedding) {
  */
 export async function openaiEmbed(inputs, config, apiKey, baseURL, options) {
     try {
-        const client = new OpenAI({ apiKey, ...(baseURL ? { baseURL } : {}) });
+        const client = new OpenAI({ dangerouslyAllowBrowser: true, apiKey, ...(baseURL ? { baseURL } : {}) });
         const body = {
             model: config.model,
             input: inputs,

package/dist/files/anthropic.js

@@ -7,13 +7,13 @@ export function anthropicFileRef(uploaded, mimeType) {
 class AnthropicFileProvider extends BaseFileProvider {
     label = "Anthropic";
     async doUpload(data, mimeType, ctx) {
-        const client = new Anthropic({ apiKey: ctx.apiKey });
+        const client = new Anthropic({ dangerouslyAllowBrowser: true, apiKey: ctx.apiKey });
         const file = await toFile(data, ctx.filename ?? "upload", { type: mimeType });
         const uploaded = await client.beta.files.upload({ file, betas: [FILES_BETA] });
         return anthropicFileRef(uploaded, mimeType);
     }
     async doDelete(ref, ctx) {
-        const client = new Anthropic({ apiKey: ctx.apiKey });
+        const client = new Anthropic({ dangerouslyAllowBrowser: true, apiKey: ctx.apiKey });
         await client.beta.files.delete(ref.id, { betas: [FILES_BETA] });
     }
 }

package/dist/files/openai.js

@@ -8,7 +8,7 @@ export function openaiFileRef(created, mimeType) {
 class OpenAIFileProvider extends BaseFileProvider {
     label = "OpenAI";
     async doUpload(data, mimeType, ctx) {
-        const client = new OpenAI({ apiKey: ctx.apiKey });
+        const client = new OpenAI({ dangerouslyAllowBrowser: true, apiKey: ctx.apiKey });
         const file = await toFile(data, ctx.filename ?? "upload", { type: mimeType });
         // S5: the mapper below is trivial and won't throw post-create, so no orphan
         // is left here; a provider whose mapper does real work should best-effort delete.
@@ -16,7 +16,7 @@ class OpenAIFileProvider extends BaseFileProvider {
         return openaiFileRef(created, mimeType);
     }
     async doDelete(ref, ctx) {
-        const client = new OpenAI({ apiKey: ctx.apiKey });
+        const client = new OpenAI({ dangerouslyAllowBrowser: true, apiKey: ctx.apiKey });
         await client.files.delete(ref.id);
     }
 }

package/dist/image/google.js

@@ -1,3 +1,4 @@
+import { base64ToBytes, bytesToBase64 } from "../util/base64.js";
 import { GoogleGenAI } from "@google/genai";
 import { success, failure } from "../types/result.js";
 import { getModel, isImageModel } from "../models.js";
@@ -14,7 +15,7 @@ export async function googleImage(input, config, apiKey) {
                 parts.push({
                     inlineData: {
                         mimeType: img.mimeType,
-                        data: Buffer.from(img.data).toString("base64"),
+                        data: bytesToBase64(img.data),
                     },
                 });
             }
@@ -32,7 +33,7 @@ export async function googleImage(input, config, apiKey) {
             for (const part of candidate.content?.parts ?? []) {
                 if (part.inlineData?.data && part.inlineData?.mimeType) {
                     images.push({
-                        data: new Uint8Array(Buffer.from(part.inlineData.data, "base64")),
+                        data: base64ToBytes(part.inlineData.data),
                         mimeType: part.inlineData.mimeType,
                     });
                 }

package/dist/image/openai.js

@@ -1,3 +1,4 @@
+import { base64ToBytes } from "../util/base64.js";
 import OpenAI from "openai";
 import { toFile } from "openai/uploads";
 import { success, failure } from "../types/result.js";
@@ -11,14 +12,14 @@ export async function openaiImage(input, config, apiKey) {
         if (normalized.mask && !hasImages) {
             return failure("A mask was provided without any input images. Masks are only valid for image edits — pass at least one entry in `images` alongside the mask.");
         }
-        const client = new OpenAI({ apiKey });
+        const client = new OpenAI({ dangerouslyAllowBrowser: true, apiKey });
         const baseParams = buildBaseParams(config, normalized.prompt);
         const response = hasImages
             ? await callEdit(client, baseParams, normalized)
             : await client.images.generate(baseParams);
         const mimeType = mimeFromFormat(config.outputFormat) ?? "image/png";
         const images = (response.data ?? []).map((d) => ({
-            data: new Uint8Array(Buffer.from(d.b64_json, "base64")),
+            data: base64ToBytes(d.b64_json),
             mimeType,
             revisedPrompt: d.revised_prompt,
         }));

package/dist/image/openaiCompat.js

@@ -1,3 +1,4 @@
+import { base64ToBytes } from "../util/base64.js";
 import OpenAI from "openai";
 import { success, failure } from "../types/result.js";
 import { omitUndefined } from "../util/util.js";
@@ -17,7 +18,7 @@ export async function openaiCompatImage(input, config, apiKey, baseURL) {
         if (normalized.mask) {
             return failure("openai-compat: image masks are not supported on this generic adapter.");
         }
-        const client = new OpenAI({ apiKey, baseURL });
+        const client = new OpenAI({ dangerouslyAllowBrowser: true, apiKey, baseURL });
         const params = omitUndefined({
             model: config.model,
             prompt: normalized.prompt,
@@ -31,7 +32,7 @@ export async function openaiCompatImage(input, config, apiKey, baseURL) {
         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")),
+            data: base64ToBytes(d.b64_json),
             mimeType,
             revisedPrompt: d.revised_prompt,
         }));

package/dist/modelRefresh.js

@@ -2,19 +2,19 @@
  * 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.
+ * therefore the model registry — stays pure. This file reaches the platform
+ * through #platform: a `file:` URL works on Node and throws in a browser,
+ * and `https:` works on both.
  */
-import { readFile } from "node:fs/promises";
-import { fileURLToPath } from "node:url";
+import { env, readTextFromFileUrl } from "#platform";
+import { utf8ByteLength } from "./util/base64.js";
 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) {
+    if (utf8ByteLength(text) > MAX_BYTES) {
         throw new Error(`Model data exceeds the ${MAX_BYTES}-byte cap`);
     }
     return text;
@@ -24,9 +24,7 @@ function enforceSizeCap(text) {
 // 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);
+        return enforceSizeCap(await readTextFromFileUrl(url));
     }
     if (url.startsWith("https://")) {
         const res = await fetch(url, { signal });
@@ -39,8 +37,9 @@ async function defaultFetcher(url, signal) {
 }
 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;
+    const fromEnv = env("SMOLTALK_MODEL_DATA_URL");
+    if (fromEnv) {
+        url = fromEnv;
     }
     if (opts.url) {
         url = opts.url;

package/dist/platform.browser.d.ts

@@ -0,0 +1,5 @@
+import type { Platform } from "./platform.js";
+export declare const readFileBytes: Platform["readFileBytes"];
+export declare const readTextFromFileUrl: Platform["readTextFromFileUrl"];
+export declare const pathToFileUrl: Platform["pathToFileUrl"];
+export declare const env: Platform["env"];

package/dist/platform.browser.js

@@ -0,0 +1,13 @@
+function unavailable(fn) {
+    return new Error(`${fn} is not available in a browser build of smoltalk.`);
+}
+export const readFileBytes = async () => {
+    throw unavailable("readFileBytes");
+};
+export const readTextFromFileUrl = async () => {
+    throw unavailable("readTextFromFileUrl");
+};
+export const pathToFileUrl = () => {
+    throw unavailable("pathToFileUrl");
+};
+export const env = () => undefined;

package/dist/platform.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The functions smoltalk takes from the platform it runs on. Two files
+ * implement them, `platform.node.ts` and `platform.browser.ts`, and the
+ * `#platform` entry in package.json's `imports` picks one: Node resolves
+ * it to the Node file, and a bundler run with its browser condition
+ * (esbuild `--platform=browser`, Vite, webpack `target: "web"`) picks the
+ * browser file. Shared code imports `#platform` and never `node:*`.
+ *
+ * The browser file throws from every file function and answers `undefined`
+ * for every environment variable, so a browser caller passes API keys in
+ * and cannot use path attachments, `file:` model data, or the llama.cpp
+ * loader's `entryPath`. Pure string work such as a path's extension is not
+ * on the platform; see `lib/util/fileExtension.ts`.
+ */
+export type Platform = {
+    /** The bytes of the file at `path`. With `maxBytes`, refuses a larger
+     *  file before reading it, with a {@link FileTooLargeError}. */
+    readFileBytes(path: string, maxBytes?: number): Promise<Uint8Array>;
+    /** The text of the file a `file:` URL names, as UTF-8. */
+    readTextFromFileUrl(url: string): Promise<string>;
+    /** The `file:` URL for a file system path. */
+    pathToFileUrl(path: string): string;
+    /** The environment variable `name`, or `undefined` when unset or when
+     *  the platform has no environment. */
+    env(name: string): string | undefined;
+};
+/** Thrown by `readFileBytes` when the file is larger than `maxBytes`. */
+export declare class FileTooLargeError extends Error {
+    readonly path: string;
+    readonly size: number;
+    readonly maxBytes: number;
+    constructor(path: string, size: number, maxBytes: number);
+}

package/dist/platform.js

@@ -0,0 +1,13 @@
+/** Thrown by `readFileBytes` when the file is larger than `maxBytes`. */
+export class FileTooLargeError extends Error {
+    path;
+    size;
+    maxBytes;
+    constructor(path, size, maxBytes) {
+        super(`File ${path} is ${size} bytes, over the limit of ${maxBytes} bytes.`);
+        this.path = path;
+        this.size = size;
+        this.maxBytes = maxBytes;
+        this.name = "FileTooLargeError";
+    }
+}

package/dist/platform.node.d.ts

@@ -0,0 +1,5 @@
+import { type Platform } from "./platform.js";
+export declare const readFileBytes: Platform["readFileBytes"];
+export declare const readTextFromFileUrl: Platform["readTextFromFileUrl"];
+export declare const pathToFileUrl: Platform["pathToFileUrl"];
+export declare const env: Platform["env"];

package/dist/platform.node.js

@@ -0,0 +1,17 @@
+// The Node side of #platform. See platform.ts.
+import { readFile, stat } from "node:fs/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { FileTooLargeError } from "./platform.js";
+export const readFileBytes = async (path, maxBytes) => {
+    if (maxBytes !== undefined) {
+        const info = await stat(path);
+        if (info.size > maxBytes) {
+            throw new FileTooLargeError(path, info.size, maxBytes);
+        }
+    }
+    const buf = await readFile(path);
+    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+};
+export const readTextFromFileUrl = (url) => readFile(fileURLToPath(url), "utf8");
+export const pathToFileUrl = (path) => pathToFileURL(path).href;
+export const env = (name) => process.env[name];

package/dist/speech/google.js

@@ -1,3 +1,4 @@
+import { base64ToBytes } from "../util/base64.js";
 import { GoogleGenAI } from "@google/genai";
 import { success, failure } from "../types/result.js";
 import { pcmToWav } from "../util/audioMime.js";
@@ -36,7 +37,7 @@ export class GoogleSpeechClient extends BaseSpeechClient {
         if (!dataB64) {
             return failure("Gemini returned no audio data.");
         }
-        const pcm = new Uint8Array(Buffer.from(dataB64, "base64"));
+        const pcm = base64ToBytes(dataB64);
         let audio = pcm;
         let mimeType = "application/octet-stream";
         if (format === "wav") {

package/dist/speech/groq.js

@@ -6,6 +6,7 @@ import { OpenAISpeechClient } from "./openai.js";
 export class GroqSpeechClient extends OpenAISpeechClient {
     makeClient() {
         return new OpenAI({
+            dangerouslyAllowBrowser: true,
             apiKey: this.config.apiKey,
             baseURL: "https://api.groq.com/openai/v1",
         });

package/dist/speech/mlx.js

@@ -21,6 +21,7 @@ export class MlxSpeechClient extends OpenAISpeechClient {
         const baseURL = resolveBaseUrl("mlx", { baseUrl: this.config.baseUrl });
         // The OpenAI SDK refuses an empty key. The local server never reads it.
         return new OpenAI({
+            dangerouslyAllowBrowser: true,
             apiKey: "mlx-local",
             baseURL,
             maxRetries: 0,

package/dist/speech/openai.js

@@ -5,7 +5,7 @@ import { BaseSpeechClient } from "./baseSpeechClient.js";
 export class OpenAISpeechClient extends BaseSpeechClient {
     /** Build the OpenAI SDK client. Subclasses override to point at a compatible base URL. */
     makeClient() {
-        return new OpenAI({ apiKey: this.config.apiKey });
+        return new OpenAI({ dangerouslyAllowBrowser: true, apiKey: this.config.apiKey });
     }
     /** Provider default used when the declarative call omits format. */
     defaultFormat() {

package/dist/speech/openaiCompat.js

@@ -14,7 +14,7 @@ export class OpenAiCompatSpeechClient extends OpenAISpeechClient {
         if (!baseURL) {
             throw new Error("openai-compat: base URL required (config.baseUrl.openAiCompat or OPENAI_COMPAT_BASE_URL).");
         }
-        return new OpenAI({ apiKey: this.config.apiKey, baseURL });
+        return new OpenAI({ dangerouslyAllowBrowser: true, apiKey: this.config.apiKey, baseURL });
     }
     noKeyMessage() {
         return "No API key provided. Set apiKey.openAiCompat or OPENAI_COMPAT_API_KEY.";

package/dist/statelogClient.js

@@ -1,3 +1,4 @@
+import { env } from "#platform";
 import { nanoid } from "nanoid";
 import { failure, mergeResults, success } from "./types/result.js";
 import { redactAttachments } from "./util/redact.js";
@@ -311,7 +312,7 @@ export function getStatelogClient(config) {
     const statelogConfig = {
         host: config.host,
         traceId: config.traceId || nanoid(),
-        apiKey: process.env.STATELOG_SMOLTALK_API_KEY || "",
+        apiKey: env("STATELOG_SMOLTALK_API_KEY") || "",
         projectId: config.projectId,
         debugMode: config.debugMode || false,
     };

package/dist/transcription/google.js

@@ -1,3 +1,4 @@
+import { bytesToBase64, utf8ByteLength } from "../util/base64.js";
 import { GoogleGenAI } from "@google/genai";
 import { success, failure } from "../types/result.js";
 import { BaseTranscriptionClient } from "./baseTranscriptionClient.js";
@@ -22,7 +23,7 @@ export class GoogleTranscriptionClient extends BaseTranscriptionClient {
         if (this.config.prompt) {
             instruction += ` ${this.config.prompt}`;
         }
-        const base64 = Buffer.from(data).toString("base64");
+        const base64 = bytesToBase64(data);
         const request = {
             model: this.config.model,
             contents: [{
@@ -33,7 +34,7 @@ export class GoogleTranscriptionClient extends BaseTranscriptionClient {
                     ],
                 }],
         };
-        if (Buffer.byteLength(JSON.stringify(request), "utf8") > GOOGLE_INLINE_REQUEST_MAX_BYTES) {
+        if (utf8ByteLength(JSON.stringify(request)) > GOOGLE_INLINE_REQUEST_MAX_BYTES) {
             return failure("Audio and instructions exceed Gemini's 20 MB inline request limit; use a smaller source.");
         }
         const ai = new GoogleGenAI({ apiKey: this.config.apiKey });

package/dist/transcription/groq.js

@@ -7,6 +7,7 @@ import { OpenAITranscriptionClient } from "./openai.js";
 export class GroqTranscriptionClient extends OpenAITranscriptionClient {
     makeClient() {
         return new OpenAI({
+            dangerouslyAllowBrowser: true,
             apiKey: this.config.apiKey,
             baseURL: "https://api.groq.com/openai/v1",
         });

package/dist/transcription/openai.js

@@ -5,7 +5,7 @@ import { BaseTranscriptionClient } from "./baseTranscriptionClient.js";
 export class OpenAITranscriptionClient extends BaseTranscriptionClient {
     /** Build the OpenAI SDK client. Subclasses override to point at a compatible base URL. */
     makeClient() {
-        return new OpenAI({ apiKey: this.config.apiKey });
+        return new OpenAI({ dangerouslyAllowBrowser: true, apiKey: this.config.apiKey });
     }
     /** Provider-specific diagnostic when no API key is resolved. Subclasses override. */
     noKeyMessage() {

package/dist/transcription/openaiCompat.js

@@ -14,7 +14,7 @@ export class OpenAiCompatTranscriptionClient extends OpenAITranscriptionClient {
         if (!baseURL) {
             throw new Error("openai-compat: base URL required (config.baseUrl.openAiCompat or OPENAI_COMPAT_BASE_URL).");
         }
-        return new OpenAI({ apiKey: this.config.apiKey, baseURL });
+        return new OpenAI({ dangerouslyAllowBrowser: true, apiKey: this.config.apiKey, baseURL });
     }
     noKeyMessage() {
         return "No API key provided. Set apiKey.openAiCompat or OPENAI_COMPAT_API_KEY.";

package/dist/util/attachments.js

@@ -1,3 +1,4 @@
+import { bytesToBase64 } from "./base64.js";
 /** Filename sent to providers that require one when a file part omits its own. */
 export const DEFAULT_ATTACHMENT_FILENAME = "attachment.pdf";
 /** A file part's filename, falling back to the shared default when unset. */
@@ -17,7 +18,7 @@ export function refToBase64(ref) {
         return { base64: ref.base64, mimeType: ref.mimeType };
     }
     if (ref.kind === "bytes") {
-        return { base64: Buffer.from(ref.data).toString("base64"), mimeType: ref.mimeType };
+        return { base64: bytesToBase64(ref.data), mimeType: ref.mimeType };
     }
     throw new Error(`Attachment ref must be resolved to base64 or bytes before serialization ` +
         `(got kind="${ref.kind}"). This is a smoltalk bug.`);

package/dist/util/base64.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Bytes to and from base64, and two other byte helpers, written without
+ * `Buffer` so they run in a browser. `Uint8Array.fromBase64` and
+ * `toBase64` are used where the runtime has them, and `atob`/`btoa` with a
+ * loop elsewhere.
+ */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/**
+ * Decodes standard base64 and base64url (`-` and `_` for `+` and `/`),
+ * with or without padding. Any other character throws. `Buffer`, which
+ * this replaced, skipped characters it did not know.
+ */
+export declare function base64ToBytes(text: string): Uint8Array;
+/** One array holding every chunk in order. */
+export declare function concatBytes(chunks: Uint8Array[], total?: number): Uint8Array;
+/** The number of bytes `text` takes as UTF-8. */
+export declare function utf8ByteLength(text: string): number;

package/dist/util/base64.js

@@ -0,0 +1,59 @@
+/**
+ * Bytes to and from base64, and two other byte helpers, written without
+ * `Buffer` so they run in a browser. `Uint8Array.fromBase64` and
+ * `toBase64` are used where the runtime has them, and `atob`/`btoa` with a
+ * loop elsewhere.
+ */
+export function bytesToBase64(bytes) {
+    const native = bytes.toBase64;
+    if (typeof native === "function") {
+        return native.call(bytes);
+    }
+    let binary = "";
+    const chunk = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunk) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+    }
+    return btoa(binary);
+}
+/**
+ * Decodes standard base64 and base64url (`-` and `_` for `+` and `/`),
+ * with or without padding. Any other character throws. `Buffer`, which
+ * this replaced, skipped characters it did not know.
+ */
+export function base64ToBytes(text) {
+    if (text.includes("-") || text.includes("_")) {
+        text = text.replace(/-/g, "+").replace(/_/g, "/");
+    }
+    const native = Uint8Array.fromBase64;
+    if (typeof native === "function") {
+        return native.call(Uint8Array, text);
+    }
+    const binary = atob(text);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        out[i] = binary.charCodeAt(i);
+    }
+    return out;
+}
+/** One array holding every chunk in order. */
+export function concatBytes(chunks, total) {
+    let length = total;
+    if (length === undefined) {
+        length = 0;
+        for (const chunk of chunks) {
+            length += chunk.byteLength;
+        }
+    }
+    const out = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+/** The number of bytes `text` takes as UTF-8. */
+export function utf8ByteLength(text) {
+    return new TextEncoder().encode(text).byteLength;
+}

package/dist/util/blobRef.js

@@ -1,5 +1,7 @@
-import { readFile, stat } from "node:fs/promises";
-import { extname } from "node:path";
+import { readFileBytes } from "#platform";
+import { FileTooLargeError } from "../platform.js";
+import { base64ToBytes, concatBytes } from "./base64.js";
+import { fileExtension } from "./fileExtension.js";
 import { EXT_TO_MIME } from "./mime.js";
 /** Default timeout for fetching attachment URLs during normalization (60 seconds). */
 export const DEFAULT_FETCH_TIMEOUT_MS = 60_000;
@@ -62,7 +64,7 @@ async function readBodyWithLimit(res, maxBytes) {
         chunks.push(value);
     }
     // Pass the known total so concat doesn't re-scan the chunk list for its length.
-    return new Uint8Array(Buffer.concat(chunks, total));
+    return concatBytes(chunks, total);
 }
 async function loadRef(ref, allowed, maxBytes) {
     switch (ref.kind) {
@@ -70,26 +72,30 @@ async function loadRef(ref, allowed, maxBytes) {
             return { data: ref.data, mimeType: ref.mimeType };
         case "base64":
             return {
-                data: new Uint8Array(Buffer.from(ref.base64, "base64")),
+                data: base64ToBytes(ref.base64),
                 mimeType: ref.mimeType,
             };
         case "path": {
-            // S1: bound memory — reject on stat before reading the whole file.
-            if (maxBytes !== undefined) {
-                const info = await stat(ref.path);
-                if (info.size > maxBytes) {
-                    throw tooLargeError(maxBytes, info.size);
+            // S1: bound memory — readFileBytes rejects on the file's size before
+            // reading it. In a browser it throws: there is no file system.
+            let buf;
+            try {
+                buf = await readFileBytes(ref.path, maxBytes);
+            }
+            catch (err) {
+                if (err instanceof FileTooLargeError) {
+                    throw tooLargeError(err.maxBytes, err.size);
                 }
+                throw err;
             }
-            const buf = await readFile(ref.path);
-            const ext = extname(ref.path).toLowerCase();
+            const ext = fileExtension(ref.path);
             const inferred = EXT_TO_MIME[ext];
             const mimeType = ref.mimeType ?? inferred;
             if (allowed !== null && (!mimeType || !isAllowedMime(mimeType, allowed))) {
                 throw new Error(`Could not determine an allowed MIME type for path "${ref.path}". ` +
                     `Allowed: ${allowed.join(", ")}. Pass an explicit mimeType on the BlobRef.`);
             }
-            return { data: new Uint8Array(buf), mimeType };
+            return { data: buf, mimeType };
         }
         case "url": {
             // S2: only http(s) — reject file:/ftp:/gopher:/data: etc.

package/dist/util/fileExtension.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The extension of a path including its dot, lower-cased, or "" when there
+ * is none. Follows Node's `path.extname`: only the last segment counts, a
+ * leading dot (`.bashrc`) is not an extension, and a trailing dot gives ".", and ".." gives "".
+ * String work only, so it is the same on every platform.
+ */
+export declare function fileExtension(path: string): string;

package/dist/util/fileExtension.js

@@ -0,0 +1,15 @@
+/**
+ * The extension of a path including its dot, lower-cased, or "" when there
+ * is none. Follows Node's `path.extname`: only the last segment counts, a
+ * leading dot (`.bashrc`) is not an extension, and a trailing dot gives ".", and ".." gives "".
+ * String work only, so it is the same on every platform.
+ */
+export function fileExtension(path) {
+    const slash = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+    const base = path.slice(slash + 1);
+    const dot = base.lastIndexOf(".");
+    if (dot <= 0 || base === "..") {
+        return "";
+    }
+    return base.slice(dot).toLowerCase();
+}

package/dist/util/provider.d.ts

@@ -36,6 +36,7 @@ type NestedKeyConfig = {
 };
 /**
  * Resolve the API key for a provider, checking config then env vars.
+ * In a browser `env` answers nothing, so the caller passes the key.
  */
 export declare function resolveApiKey(provider: string, config: NestedKeyConfig): string | undefined;
 /**

package/dist/util/provider.js

@@ -1,3 +1,4 @@
+import { env } from "#platform";
 import { getModel } from "../models.js";
 import { SmolError } from "../smolError.js";
 /**
@@ -16,31 +17,32 @@ export function resolveProvider(modelName, explicitProvider, modelData) {
 }
 /**
  * Resolve the API key for a provider, checking config then env vars.
+ * In a browser `env` answers nothing, so the caller passes the key.
  */
 export function resolveApiKey(provider, config) {
     const k = config.apiKey;
     switch (provider) {
         case "openai":
         case "openai-responses":
-            return k?.openAi || process.env.OPENAI_API_KEY;
+            return k?.openAi || env("OPENAI_API_KEY");
         case "google":
-            return k?.google || process.env.GEMINI_API_KEY;
+            return k?.google || env("GEMINI_API_KEY");
         case "anthropic":
-            return k?.anthropic || process.env.ANTHROPIC_API_KEY;
+            return k?.anthropic || env("ANTHROPIC_API_KEY");
         case "ollama":
             return k?.ollama;
         case "openrouter":
-            return k?.openRouter || process.env.OPENROUTER_API_KEY;
+            return k?.openRouter || env("OPENROUTER_API_KEY");
         case "deepinfra":
-            return k?.deepInfra || process.env.DEEPINFRA_API_KEY;
+            return k?.deepInfra || env("DEEPINFRA_API_KEY");
         case "litellm":
-            return k?.liteLlm || process.env.LITELLM_API_KEY;
+            return k?.liteLlm || env("LITELLM_API_KEY");
         case "openai-compat":
-            return k?.openAiCompat || process.env.OPENAI_COMPAT_API_KEY;
+            return k?.openAiCompat || env("OPENAI_COMPAT_API_KEY");
         case "groq":
-            return k?.groq || process.env.GROQ_API_KEY;
+            return k?.groq || env("GROQ_API_KEY");
         case "typesafe":
-            return k?.typesafe || process.env.TYPESAFE_API_KEY;
+            return k?.typesafe || env("TYPESAFE_API_KEY");
         default:
             return config.apiKey?.[provider];
     }
@@ -57,20 +59,20 @@ export function resolveBaseUrl(provider, config) {
     const b = config.baseUrl;
     switch (provider) {
         case "ollama":
-            return b?.ollama || process.env.OLLAMA_HOST;
+            return b?.ollama || 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;
+            return b?.liteLlm || env("LITELLM_BASE_URL");
         case "openai-compat":
-            return b?.openAiCompat || process.env.OPENAI_COMPAT_BASE_URL;
+            return b?.openAiCompat || env("OPENAI_COMPAT_BASE_URL");
         case "mlx":
-            return b?.mlx || process.env.MLX_BASE_URL || "http://127.0.0.1:8080/v1";
+            return b?.mlx || env("MLX_BASE_URL") || "http://127.0.0.1:8080/v1";
         case "typesafe":
             // A Laya server (`laya-serve`) speaks the same protocol; point this at it.
-            return b?.typesafe || process.env.TYPESAFE_BASE_URL || "https://api.typesafe.ai";
+            return b?.typesafe || env("TYPESAFE_BASE_URL") || "https://api.typesafe.ai";
         default:
             return undefined;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smoltalk",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "A common interface for LLM APIs",
   "homepage": "https://github.com/egonSchiele/smoltalk",
   "files": [
@@ -23,6 +23,16 @@
       "require": "./dist/testing/index.js"
     }
   },
+  "imports": {
+    "#platform": {
+      "browser": "./dist/platform.browser.js",
+      "default": "./dist/platform.node.js"
+    },
+    "#ollama": {
+      "browser": "ollama/browser",
+      "default": "ollama"
+    }
+  },
   "type": "module",
   "types": "./dist/index.d.ts",
   "keywords": [
@@ -41,6 +51,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "esbuild": "^0.28.2",
     "tsx": "^4.19.2"
   },
   "peerDependencies": {
@@ -60,6 +71,7 @@
     "doc": "typedoc --disableSources --out docs lib && prettier docs/ --write",
     "typecheck": "tsc --noEmit",
     "seed-data": "tsx scripts/seed-model-data.ts",
-    "refresh-data": "tsx scripts/refresh-from-modelsdev.ts"
+    "refresh-data": "tsx scripts/refresh-from-modelsdev.ts",
+    "check:browser": "node scripts/check-browser-bundle.mjs"
   }
 }