smoltalk 0.10.1 → 0.11.0

package/README.md

@@ -507,6 +507,40 @@ Text, transcription, and speech are classes: a base class owns the shared
 behavior (validation, cost, error handling) and the subclass implements only
 the provider call. Embeddings and images are one-shot functions.
 
+## Local models (llama-cpp)
+
+Install the optional plugin and name the provider — no wiring code:
+
+```bash
+npm i smoltalk-llama-cpp
+```
+
+```typescript
+import { textSync, userMessage } from "smoltalk";
+
+const result = await textSync({
+  provider: "llama-cpp",
+  model: "/path/to/llama-3.gguf",
+  messages: [userMessage("Hello!")],
+});
+```
+
+smoltalk lazily imports and registers the plugin on the first `llama-cpp`
+call; if the package is missing you get an install hint instead of a
+resolution stack trace. Hosts with unusual layouts (e.g. a globally-installed
+CLI with the plugin installed globally beside it) can hand smoltalk the
+plugin's entry path explicitly and skip Node resolution:
+
+```typescript
+import { loadLlamaCpp } from "smoltalk";
+
+const { resolveModel } = await loadLlamaCpp({
+  entryPath: "/path/to/smoltalk-llama-cpp/dist/index.js",
+});
+// resolveModel downloads hf: URIs (and absolutizes existing local paths):
+const modelPath = await resolveModel("hf:org/repo/model.gguf", "/models/cache");
+```
+
 ## Audio (STT/TTS)
 
 Three audio primitives. `transcribe()` (speech-to-text) and `speak()`

package/dist/client.d.ts

@@ -12,4 +12,10 @@ import { BaseClient } from "./clients/baseClient.js";
 import { SmolClientConfig } from "./types.js";
 export declare function registerProvider(providerName: string, clientClass: typeof BaseClient): void;
 export declare function unregisterProvider(providerName: string): boolean;
+/**
+ * True when `providerName` has been registered via registerProvider().
+ * Built-in providers (the switch cases in getClient) are not its concern —
+ * this only consults the custom registry.
+ */
+export declare function hasProvider(providerName: string): boolean;
 export declare function getClient(config: SmolClientConfig): BaseClient;

package/dist/client.js

@@ -33,6 +33,14 @@ export function unregisterProvider(providerName) {
     }
     return false;
 }
+/**
+ * True when `providerName` has been registered via registerProvider().
+ * Built-in providers (the switch cases in getClient) are not its concern —
+ * this only consults the custom registry.
+ */
+export function hasProvider(providerName) {
+    return providerName in registeredProviders;
+}
 export function getClient(config) {
     const modelName = config.model;
     const provider = resolveProvider(modelName, config.provider, config.modelData);
@@ -100,6 +108,10 @@ export function getClient(config) {
                 const ClientClass = registeredProviders[provider];
                 return new ClientClass(clientConfig);
             }
+            if (provider === "llama-cpp") {
+                throw new SmolError("The llama-cpp provider loads automatically when called through text()/textSync()/textStream(). " +
+                    "For direct getClient() use, await loadLlamaCpp() first (install smoltalk-llama-cpp if it is missing).");
+            }
             throw new SmolError(`Model provider ${provider} is not supported. To use a custom provider, register it first via registerProvider(name, ClientClass).`);
     }
 }

package/dist/clients/llamaCppLoader.d.ts

@@ -0,0 +1,42 @@
+import type { BaseClient } from "./baseClient.js";
+/**
+ * Minimal structural view of smoltalk-llama-cpp's module. Declared here (not
+ * imported from the plugin) so smoltalk compiles without the plugin installed
+ * and the workspace gains no build-order cycle.
+ */
+export type LlamaCppModule = {
+    LlamaCPP: typeof BaseClient;
+    resolveModel: (uriOrPath: string, cacheDir: string) => Promise<string>;
+};
+type ImportFn = (specifier: string) => Promise<Record<string, unknown>>;
+/**
+ * Test-only: swap the dynamic import (pass undefined to restore the real one)
+ * and clear the load cache. Deliberately NOT exported from the package index.
+ */
+export declare function _setImportForTests(fn?: ImportFn): void;
+/**
+ * Load and register the optional smoltalk-llama-cpp plugin, once per process.
+ *
+ * - Without options, imports the bare specifier "smoltalk-llama-cpp" using
+ *   Node resolution from smoltalk's location. The optional peer declaration
+ *   in package.json is what makes that resolvable under pnpm's strict layout.
+ * - `entryPath` is the escape hatch for hosts whose plugin install is not
+ *   resolvable from smoltalk (e.g. globally-installed CLIs): the file is
+ *   imported directly and Node resolution is skipped. Hosts own discovering
+ *   that path; smoltalk never probes global npm roots and reads no env vars.
+ * - Registers the module's LlamaCPP class under "llama-cpp" unless that name
+ *   is already registered. An existing registration is left untouched, but
+ *   the module is still imported, validated, and returned — an existing
+ *   registration wins the registry, never the return value. Registration is
+ *   re-ensured from the cached module on EVERY call, so a later
+ *   unregisterProvider("llama-cpp") is undone by the next load call without
+ *   a second import.
+ * - Concurrent first calls share one in-flight load. A failed load clears
+ *   the cache so a later call can retry (e.g. after installing the package).
+ *   A second call with a different entryPath after a successful load returns
+ *   the already-loaded module (first load wins).
+ */
+export declare function loadLlamaCpp(options?: {
+    entryPath?: string;
+}): Promise<LlamaCppModule>;
+export {};

package/dist/clients/llamaCppLoader.js

@@ -0,0 +1,109 @@
+import { pathToFileURL } from "url";
+import { hasProvider, registerProvider } from "../client.js";
+import { SmolError } from "../smolError.js";
+const realImport = (specifier) => import(specifier);
+let importFn = realImport;
+let cachedLoad;
+/**
+ * Test-only: swap the dynamic import (pass undefined to restore the real one)
+ * and clear the load cache. Deliberately NOT exported from the package index.
+ */
+export function _setImportForTests(fn) {
+    if (fn) {
+        importFn = fn;
+    }
+    else {
+        importFn = realImport;
+    }
+    cachedLoad = undefined;
+}
+/**
+ * Load and register the optional smoltalk-llama-cpp plugin, once per process.
+ *
+ * - Without options, imports the bare specifier "smoltalk-llama-cpp" using
+ *   Node resolution from smoltalk's location. The optional peer declaration
+ *   in package.json is what makes that resolvable under pnpm's strict layout.
+ * - `entryPath` is the escape hatch for hosts whose plugin install is not
+ *   resolvable from smoltalk (e.g. globally-installed CLIs): the file is
+ *   imported directly and Node resolution is skipped. Hosts own discovering
+ *   that path; smoltalk never probes global npm roots and reads no env vars.
+ * - Registers the module's LlamaCPP class under "llama-cpp" unless that name
+ *   is already registered. An existing registration is left untouched, but
+ *   the module is still imported, validated, and returned — an existing
+ *   registration wins the registry, never the return value. Registration is
+ *   re-ensured from the cached module on EVERY call, so a later
+ *   unregisterProvider("llama-cpp") is undone by the next load call without
+ *   a second import.
+ * - Concurrent first calls share one in-flight load. A failed load clears
+ *   the cache so a later call can retry (e.g. after installing the package).
+ *   A second call with a different entryPath after a successful load returns
+ *   the already-loaded module (first load wins).
+ */
+export function loadLlamaCpp(options) {
+    if (!cachedLoad) {
+        const load = doLoad(options?.entryPath);
+        cachedLoad = load;
+        load.catch(() => {
+            if (cachedLoad === load) {
+                cachedLoad = undefined;
+            }
+        });
+    }
+    // Registration happens on EVERY call, not only inside the first load: a
+    // consumer can unregisterProvider("llama-cpp") after a successful load,
+    // and the cached module must be re-registered on the next call or the
+    // provider stays missing for the life of the process.
+    return cachedLoad.then((plugin) => {
+        if (!hasProvider("llama-cpp")) {
+            registerProvider("llama-cpp", plugin.LlamaCPP);
+        }
+        return plugin;
+    });
+}
+async function doLoad(entryPath) {
+    let importSource;
+    if (entryPath) {
+        importSource = pathToFileURL(entryPath).href;
+    }
+    else {
+        importSource = "smoltalk-llama-cpp";
+    }
+    let mod;
+    try {
+        mod = await importFn(importSource);
+    }
+    catch (error) {
+        if (!entryPath && isPluginNotInstalledError(error)) {
+            throw new SmolError("The llama-cpp provider needs the optional smoltalk-llama-cpp package. " +
+                "Install it (npm i smoltalk-llama-cpp) and try again.", { cause: error });
+        }
+        throw new SmolError(`Failed to load smoltalk-llama-cpp from ${importSource}: ${errorMessage(error)}`, { cause: error });
+    }
+    if (typeof mod.LlamaCPP !== "function") {
+        throw new SmolError(`The module imported as ${importSource} does not export LlamaCPP — ` +
+            "it does not appear to be the smoltalk-llama-cpp package.");
+    }
+    if (typeof mod.resolveModel !== "function") {
+        throw new SmolError("Your installed smoltalk-llama-cpp is too old for this version of smoltalk. " +
+            "Upgrade it (npm i smoltalk-llama-cpp@latest; >=0.2.0 required).");
+    }
+    return mod;
+}
+/**
+ * True only when the smoltalk-llama-cpp specifier itself failed to resolve —
+ * not when the package exists but its own import chain broke (e.g. a
+ * node-llama-cpp binary problem), where an install hint would mislead.
+ */
+function isPluginNotInstalledError(error) {
+    const code = error?.code;
+    if (code !== "ERR_MODULE_NOT_FOUND") {
+        return false;
+    }
+    return errorMessage(error).includes("'smoltalk-llama-cpp'");
+}
+function errorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}

package/dist/functions.js

@@ -1,5 +1,6 @@
 import { BaseMessage, messageFromJSON, } from "./classes/message/index.js";
-import { getClient } from "./client.js";
+import { getClient, hasProvider } from "./client.js";
+import { loadLlamaCpp } from "./clients/llamaCppLoader.js";
 import { getLogger } from "./util/logger.js";
 function fixMessagesIfNecessary(messages) {
     if (messages && messages.length > 0) {
@@ -16,10 +17,16 @@ export function text(config) {
     return textSync(config);
 }
 export async function textSync(config) {
+    if (config.provider === "llama-cpp" && !hasProvider("llama-cpp")) {
+        await loadLlamaCpp();
+    }
     config.messages = fixMessagesIfNecessary(config.messages);
     return getClient(config).textSync(config);
 }
 export async function* textStream(config) {
+    if (config.provider === "llama-cpp" && !hasProvider("llama-cpp")) {
+        await loadLlamaCpp();
+    }
     config.messages = fixMessagesIfNecessary(config.messages);
     yield* getClient(config).textStream(config);
 }

package/dist/index.d.ts

@@ -8,6 +8,8 @@ export * from "./util/util.js";
 export * from "./util/tool.js";
 export * from "./classes/message/index.js";
 export * from "./functions.js";
+export { loadLlamaCpp } from "./clients/llamaCppLoader.js";
+export type { LlamaCppModule } from "./clients/llamaCppLoader.js";
 export * from "./classes/ToolCall.js";
 export * from "./embed.js";
 export * from "./image.js";

package/dist/index.js

@@ -8,6 +8,8 @@ export * from "./util/util.js";
 export * from "./util/tool.js";
 export * from "./classes/message/index.js";
 export * from "./functions.js";
+// Explicit (not `export *`) so the test-only `_setImportForTests` stays off the public surface.
+export { loadLlamaCpp } from "./clients/llamaCppLoader.js";
 export * from "./classes/ToolCall.js";
 export * from "./embed.js";
 export * from "./image.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smoltalk",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "A common interface for LLM APIs",
   "homepage": "https://github.com/egonSchiele/smoltalk",
   "files": [
@@ -38,6 +38,14 @@
   "devDependencies": {
     "tsx": "^4.19.2"
   },
+  "peerDependencies": {
+    "smoltalk-llama-cpp": ">=0.2.0 <1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "smoltalk-llama-cpp": {
+      "optional": true
+    }
+  },
   "scripts": {
     "test": "vitest --exclude=**/*.live.test.ts",
     "test:live": "vitest run lib/clients/*.live.test.ts lib/embed/*.live.test.ts lib/image/*.live.test.ts",