@node-llm/core 1.5.4 → 1.6.1

package/dist/config.js

@@ -12,30 +12,85 @@ export class Configuration {
     _openrouterApiKey;
     _openrouterApiBase;
     _debug;
-    get openaiApiKey() { return this._openaiApiKey ?? process.env.OPENAI_API_KEY?.trim(); }
-    set openaiApiKey(v) { this._openaiApiKey = v; }
-    get openaiApiBase() { return this._openaiApiBase ?? process.env.OPENAI_API_BASE?.trim(); }
-    set openaiApiBase(v) { this._openaiApiBase = v; }
-    get anthropicApiKey() { return this._anthropicApiKey ?? process.env.ANTHROPIC_API_KEY?.trim(); }
-    set anthropicApiKey(v) { this._anthropicApiKey = v; }
-    get anthropicApiBase() { return this._anthropicApiBase ?? process.env.ANTHROPIC_API_BASE?.trim(); }
-    set anthropicApiBase(v) { this._anthropicApiBase = v; }
-    get geminiApiKey() { return this._geminiApiKey ?? process.env.GEMINI_API_KEY?.trim(); }
-    set geminiApiKey(v) { this._geminiApiKey = v; }
-    get geminiApiBase() { return this._geminiApiBase ?? process.env.GEMINI_API_BASE?.trim(); }
-    set geminiApiBase(v) { this._geminiApiBase = v; }
-    get deepseekApiKey() { return this._deepseekApiKey ?? process.env.DEEPSEEK_API_KEY?.trim(); }
-    set deepseekApiKey(v) { this._deepseekApiKey = v; }
-    get deepseekApiBase() { return this._deepseekApiBase ?? process.env.DEEPSEEK_API_BASE?.trim(); }
-    set deepseekApiBase(v) { this._deepseekApiBase = v; }
-    get ollamaApiBase() { return this._ollamaApiBase ?? process.env.OLLAMA_API_BASE?.trim() ?? DEFAULT_OLLAMA_BASE_URL; }
-    set ollamaApiBase(v) { this._ollamaApiBase = v; }
-    get openrouterApiKey() { return this._openrouterApiKey ?? process.env.OPENROUTER_API_KEY?.trim(); }
-    set openrouterApiKey(v) { this._openrouterApiKey = v; }
-    get openrouterApiBase() { return this._openrouterApiBase ?? process.env.OPENROUTER_API_BASE?.trim(); }
-    set openrouterApiBase(v) { this._openrouterApiBase = v; }
-    get debug() { return this._debug ?? process.env.NODELLM_DEBUG === "true"; }
-    set debug(v) { this._debug = v; }
+    _provider;
+    get openaiApiKey() {
+        return this._openaiApiKey ?? process.env.OPENAI_API_KEY?.trim();
+    }
+    set openaiApiKey(v) {
+        this._openaiApiKey = v;
+    }
+    get openaiApiBase() {
+        return this._openaiApiBase ?? process.env.OPENAI_API_BASE?.trim();
+    }
+    set openaiApiBase(v) {
+        this._openaiApiBase = v;
+    }
+    get anthropicApiKey() {
+        return this._anthropicApiKey ?? process.env.ANTHROPIC_API_KEY?.trim();
+    }
+    set anthropicApiKey(v) {
+        this._anthropicApiKey = v;
+    }
+    get anthropicApiBase() {
+        return this._anthropicApiBase ?? process.env.ANTHROPIC_API_BASE?.trim();
+    }
+    set anthropicApiBase(v) {
+        this._anthropicApiBase = v;
+    }
+    get geminiApiKey() {
+        return this._geminiApiKey ?? process.env.GEMINI_API_KEY?.trim();
+    }
+    set geminiApiKey(v) {
+        this._geminiApiKey = v;
+    }
+    get geminiApiBase() {
+        return this._geminiApiBase ?? process.env.GEMINI_API_BASE?.trim();
+    }
+    set geminiApiBase(v) {
+        this._geminiApiBase = v;
+    }
+    get deepseekApiKey() {
+        return this._deepseekApiKey ?? process.env.DEEPSEEK_API_KEY?.trim();
+    }
+    set deepseekApiKey(v) {
+        this._deepseekApiKey = v;
+    }
+    get deepseekApiBase() {
+        return this._deepseekApiBase ?? process.env.DEEPSEEK_API_BASE?.trim();
+    }
+    set deepseekApiBase(v) {
+        this._deepseekApiBase = v;
+    }
+    get ollamaApiBase() {
+        return this._ollamaApiBase ?? process.env.OLLAMA_API_BASE?.trim() ?? DEFAULT_OLLAMA_BASE_URL;
+    }
+    set ollamaApiBase(v) {
+        this._ollamaApiBase = v;
+    }
+    get openrouterApiKey() {
+        return this._openrouterApiKey ?? process.env.OPENROUTER_API_KEY?.trim();
+    }
+    set openrouterApiKey(v) {
+        this._openrouterApiKey = v;
+    }
+    get openrouterApiBase() {
+        return this._openrouterApiBase ?? process.env.OPENROUTER_API_BASE?.trim();
+    }
+    set openrouterApiBase(v) {
+        this._openrouterApiBase = v;
+    }
+    get debug() {
+        return this._debug ?? process.env.NODELLM_DEBUG === "true";
+    }
+    set debug(v) {
+        this._debug = v;
+    }
+    get provider() {
+        return this._provider ?? process.env.NODELLM_PROVIDER?.trim();
+    }
+    set provider(v) {
+        this._provider = v;
+    }
     maxToolCalls = DEFAULT_MAX_TOOL_CALLS;
     maxRetries = DEFAULT_MAX_RETRIES;
     requestTimeout = DEFAULT_REQUEST_TIMEOUT;
@@ -57,7 +112,7 @@ export class Configuration {
             const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
             if (descriptor && descriptor.get) {
                 // Trigger the getter to snapshot the live value (including env fallbacks)
-                plain[name] = this[name];
+                plain[name] = Reflect.get(this, name);
             }
         }
         return plain;

package/dist/constants.js

@@ -14,5 +14,5 @@ export const DEFAULT_MODELS = {
     TRANSCRIPTION: "whisper-1",
     MODERATION: "omni-moderation-latest",
     EMBEDDING: "text-embedding-3-small",
-    IMAGE: "dall-e-3",
+    IMAGE: "dall-e-3"
 };

package/dist/errors/index.d.ts

@@ -1,3 +1,17 @@
+/**
+ * NodeLLM Error Hierarchy
+ *
+ * **Stability Contract**: These error types and their semantics are part of the
+ * public API and will not change without a major version bump.
+ *
+ * - Error names are stable
+ * - Error codes are stable
+ * - Error semantics (when they're thrown) are stable
+ * - New errors may be added (non-breaking)
+ * - Existing error meanings will not change
+ *
+ * @see ARCHITECTURE.md for error contract details
+ */
 /**
  * Base class for all NodeLLM errors
  */
@@ -10,40 +24,40 @@ export declare class LLMError extends Error {
  */
 export declare class APIError extends LLMError {
     readonly status: number;
-    readonly body: any;
+    readonly body: unknown;
     readonly provider?: string | undefined;
     readonly model?: string | undefined;
-    constructor(message: string, status: number, body: any, provider?: string | undefined, model?: string | undefined);
+    constructor(message: string, status: number, body: unknown, provider?: string | undefined, model?: string | undefined);
 }
 /**
  * 400 - Invalid request parameters
  */
 export declare class BadRequestError extends APIError {
-    constructor(message: string, body: any, provider?: string, model?: string);
+    constructor(message: string, body: unknown, provider?: string, model?: string);
 }
 /**
  * 401/403 - API key or permission issues
  */
 export declare class AuthenticationError extends APIError {
-    constructor(message: string, status: number, body: any, provider?: string);
+    constructor(message: string, status: number, body: unknown, provider?: string);
 }
 /**
  * 429 - Rate limit exceeded
  */
 export declare class RateLimitError extends APIError {
-    constructor(message: string, body: any, provider?: string, model?: string);
+    constructor(message: string, body: unknown, provider?: string, model?: string);
 }
 /**
  * 500+ - Provider server error
  */
 export declare class ServerError extends APIError {
-    constructor(message: string, status: number, body: any, provider?: string, model?: string);
+    constructor(message: string, status: number, body: unknown, provider?: string, model?: string);
 }
 /**
  * 502/503/529 - Service overloaded/unavailable
  */
 export declare class ServiceUnavailableError extends ServerError {
-    constructor(message: string, status: number, body: any, provider?: string, model?: string);
+    constructor(message: string, status: number, body: unknown, provider?: string, model?: string);
 }
 /**
  * Misconfiguration (e.g. missing API key)

package/dist/errors/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;aACY,IAAI,CAAC,EAAE,MAAM;gBAA9C,OAAO,EAAE,MAAM,EAAkB,IAAI,CAAC,EAAE,MAAM,YAAA;CAK3D;AAED;;GAEG;AACH,qBAAa,QAAS,SAAQ,QAAQ;aAGlB,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,GAAG;aACT,QAAQ,CAAC,EAAE,MAAM;aACjB,KAAK,CAAC,EAAE,MAAM;gBAJ9B,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,GAAG,EACT,QAAQ,CAAC,EAAE,MAAM,YAAA,EACjB,KAAK,CAAC,EAAE,MAAM,YAAA;CAIjC;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;CAI1E;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,QAAQ;gBACnC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,CAAC,EAAE,MAAM;CAI1E;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,QAAQ;gBAC9B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;CAI1E;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,QAAQ;gBAC3B,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;CAI1F;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,WAAW;gBAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;CAI1F;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;gBAClC,OAAO,EAAE,MAAM;CAG5B;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,OAAO,EAAE,MAAM;CAG5B;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,OAAO,EAAE,MAAM;CAG5B;AAED;;GAEG;AACH,qBAAa,0BAA2B,SAAQ,QAAQ;;CAIvD;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,QAAQ;aAEjC,QAAQ,EAAE,MAAM;aAChB,OAAO,EAAE,MAAM;gBADf,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM;CAIlC;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,QAAQ;aAE9B,KAAK,EAAE,MAAM;aACb,UAAU,EAAE,MAAM;gBADlB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM;CAIrC;AACD;;GAEG;AACH,qBAAa,SAAU,SAAQ,QAAQ;aAGnB,QAAQ,CAAC,EAAE,MAAM;aACjB,KAAK,EAAE,OAAO;gBAF9B,OAAO,EAAE,MAAM,EACC,QAAQ,CAAC,EAAE,MAAM,YAAA,EACjB,KAAK,GAAE,OAAe;CAKzC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;aAGf,IAAI,CAAC,EAAE,MAAM;gBAD7B,OAAO,EAAE,MAAM,EACC,IAAI,CAAC,EAAE,MAAM,YAAA;CAMhC;AAED;;GAEG;AACH,qBAAa,QAAS,SAAQ,QAAQ;aAGlB,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,OAAO;aACb,QAAQ,CAAC,EAAE,MAAM;aACjB,KAAK,CAAC,EAAE,MAAM;gBAJ9B,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,QAAQ,CAAC,EAAE,MAAM,YAAA,EACjB,KAAK,CAAC,EAAE,MAAM,YAAA;CAIjC;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;CAI9E;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,QAAQ;gBACnC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM;CAI9E;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,QAAQ;gBAC9B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;CAI9E;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,QAAQ;gBAC3B,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;CAI9F;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,WAAW;gBAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;CAI9F;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;gBAClC,OAAO,EAAE,MAAM;CAG5B;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,OAAO,EAAE,MAAM;CAG5B;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,OAAO,EAAE,MAAM;CAG5B;AAED;;GAEG;AACH,qBAAa,0BAA2B,SAAQ,QAAQ;;CAIvD;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,QAAQ;aAEjC,QAAQ,EAAE,MAAM;aAChB,OAAO,EAAE,MAAM;gBADf,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM;CAIlC;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,QAAQ;aAE9B,KAAK,EAAE,MAAM;aACb,UAAU,EAAE,MAAM;gBADlB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM;CAIrC;AACD;;GAEG;AACH,qBAAa,SAAU,SAAQ,QAAQ;aAGnB,QAAQ,CAAC,EAAE,MAAM;aACjB,KAAK,EAAE,OAAO;gBAF9B,OAAO,EAAE,MAAM,EACC,QAAQ,CAAC,EAAE,MAAM,YAAA,EACjB,KAAK,GAAE,OAAe;CAKzC"}

package/dist/errors/index.js

@@ -1,3 +1,17 @@
+/**
+ * NodeLLM Error Hierarchy
+ *
+ * **Stability Contract**: These error types and their semantics are part of the
+ * public API and will not change without a major version bump.
+ *
+ * - Error names are stable
+ * - Error codes are stable
+ * - Error semantics (when they're thrown) are stable
+ * - New errors may be added (non-breaking)
+ * - Existing error meanings will not change
+ *
+ * @see ARCHITECTURE.md for error contract details
+ */
 /**
  * Base class for all NodeLLM errors
  */

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export * from "./chat/Chat.js";
 export * from "./chat/ChatStream.js";
 export * from "./streaming/Stream.js";
 export { z } from "zod";
-export { NodeLLM, Transcription, Moderation, Embedding } from "./llm.js";
+export { NodeLLM, LegacyNodeLLM, createLLM, NodeLLMCore, Transcription, Moderation, Embedding, ModelRegistry, PricingRegistry } from "./llm.js";
 export { config } from "./config.js";
 export type { NodeLLMConfig } from "./config.js";
 export { providerRegistry } from "./providers/registry.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AAEtC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACzE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,cAAc,EACf,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AAEtC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,OAAO,EACP,aAAa,EACb,SAAS,EACT,WAAW,EACX,aAAa,EACb,UAAU,EACV,SAAS,EACT,aAAa,EACb,eAAe,EAChB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,cAAc,EACf,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -7,7 +7,7 @@ export * from "./chat/Chat.js";
 export * from "./chat/ChatStream.js";
 export * from "./streaming/Stream.js";
 export { z } from "zod";
-export { NodeLLM, Transcription, Moderation, Embedding } from "./llm.js";
+export { NodeLLM, LegacyNodeLLM, createLLM, NodeLLMCore, Transcription, Moderation, Embedding, ModelRegistry, PricingRegistry } from "./llm.js";
 export { config } from "./config.js";
 export { providerRegistry } from "./providers/registry.js";
 export { Schema } from "./schema/Schema.js";

package/dist/llm.d.ts

@@ -3,6 +3,7 @@ import { ChatOptions } from "./chat/ChatOptions.js";
 import { Provider, ModelInfo } from "./providers/Provider.js";
 import { GeneratedImage } from "./image/GeneratedImage.js";
 import { ModelRegistry } from "./models/ModelRegistry.js";
+import { PricingRegistry } from "./models/PricingRegistry.js";
 import { Transcription } from "./transcription/Transcription.js";
 import { Moderation } from "./moderation/Moderation.js";
 import { Embedding } from "./embedding/Embedding.js";
@@ -18,57 +19,35 @@ type LLMConfig = {
     defaultTranscriptionModel?: string;
     defaultModerationModel?: string;
     defaultEmbeddingModel?: string;
-} & Partial<NodeLLMConfig>;
+} & Omit<Partial<NodeLLMConfig>, "provider">;
 export declare class NodeLLMCore {
-    readonly models: typeof ModelRegistry;
     readonly config: NodeLLMConfig;
-    private provider?;
-    private defaultChatModelId?;
-    private defaultTranscriptionModelId?;
-    private defaultModerationModelId?;
-    private defaultEmbeddingModelId?;
-    private retry;
-    /**
-     * Create a new LLM instance. Defaults to the global config.
-     */
-    constructor(customConfig?: NodeLLMConfig);
+    readonly provider?: Provider | undefined;
+    readonly retry: Required<RetryOptions>;
+    private readonly defaults;
+    readonly models: typeof ModelRegistry;
+    readonly pricing: typeof PricingRegistry;
+    constructor(config: NodeLLMConfig, provider?: Provider | undefined, retry?: Required<RetryOptions>, defaults?: {
+        chat?: string;
+        transcription?: string;
+        moderation?: string;
+        embedding?: string;
+    });
+    get defaultChatModel(): string | undefined;
+    get defaultTranscriptionModel(): string | undefined;
+    get defaultModerationModel(): string | undefined;
+    get defaultEmbeddingModel(): string | undefined;
     /**
      * Returns a scoped LLM instance configured for a specific provider.
-     * This respects the current global configuration but avoids side effects
-     * on the main NodeLLM singleton.
-     *
-     * @param providerName - The provider to use (e.g., "openai", "anthropic")
-     * @param scopedConfig - Optional configuration overrides for this scoped instance
-     *
-     * @example
-     * ```ts
-     * const openai = NodeLLM.withProvider("openai");
-     * const anthropic = NodeLLM.withProvider("anthropic");
-     *
-     * // These can now run in parallel without race conditions
-     * await Promise.all([
-     *   openai.chat("gpt-4o").ask(prompt),
-     *   anthropic.chat("claude-3-5-sonnet").ask(prompt),
-     * ]);
-     * ```
-     *
-     * @example With scoped credentials
-     * ```ts
-     * const customAnthropic = NodeLLM.withProvider("anthropic", {
-     *   anthropicApiKey: "sk-ant-custom-key"
-     * });
-     * ```
+     * This returns a NEW immutable instance.
      */
     withProvider(providerName: string, scopedConfig?: Partial<NodeLLMConfig>): NodeLLMCore;
     /**
      * Register a custom LLM provider.
-     * This allows you to extend NodeLLM with your own logic at runtime.
-     *
-     * @param name - Unique identifier for the provider
-     * @param factory - A function that returns a Provider instance
+     * Note: This modifies the global provider registry.
      */
     registerProvider(name: string, factory: () => Provider): void;
-    configure(configOrCallback: LLMConfig | ((config: NodeLLMConfig) => void)): void;
+    getRetryConfig(): Required<RetryOptions>;
     private ensureProviderSupport;
     chat(model?: string, options?: ChatOptions): Chat;
     listModels(): Promise<ModelInfo[]>;
@@ -88,10 +67,6 @@ export declare class NodeLLMCore {
         assumeModelExists?: boolean;
         requestTimeout?: number;
     }): Promise<Transcription>;
-    get defaultTranscriptionModel(): string | undefined;
-    get defaultModerationModel(): string | undefined;
-    get defaultEmbeddingModel(): string | undefined;
-    getRetryConfig(): Required<RetryOptions>;
     moderate(input: string | string[], options?: {
         model?: string;
         assumeModelExists?: boolean;
@@ -104,6 +79,29 @@ export declare class NodeLLMCore {
         requestTimeout?: number;
     }): Promise<Embedding>;
 }
-export { Transcription, Moderation, Embedding };
+export { Transcription, Moderation, Embedding, ModelRegistry, PricingRegistry };
+/**
+ * Creates a new immutable LLM instance.
+ */
+export declare function createLLM(options?: LLMConfig): NodeLLMCore;
+/**
+ * The global, immutable NodeLLM instance.
+ *
+ * DESIGN: Lazy Initialization
+ * To support 'import "dotenv/config"' patterns in ESM, this instance
+ * does NOT snapshot the environment until its first property access.
+ * Once accessed, it is frozen and becomes a stable, immutable contract.
+ *
+ * @see ARCHITECTURE.md for full contract details
+ */
 export declare const NodeLLM: NodeLLMCore;
+/**
+ * LEGACY BOOTSTRAPPER (DEPRECATED)
+ *
+ * Provided to ease migration from the mutable singleton pattern.
+ * configure() will warn and no-op, as the global instance is now immutable.
+ */
+export declare const LegacyNodeLLM: {
+    configure(_options: LLMConfig | ((config: NodeLLMConfig) => void)): void;
+};
 //# sourceMappingURL=llm.d.ts.map

package/dist/llm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../src/llm.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../src/llm.ts"],"names":[],"mappings":"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"}