@node-llm/core 1.5.2 → 1.6.0

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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"}

package/dist/llm.js

@@ -1,12 +1,14 @@
 import { Chat } from "./chat/Chat.js";
-import { providerRegistry, ensureOpenAIRegistered, registerAnthropicProvider, registerGeminiProvider, registerDeepSeekProvider, registerOllamaProvider, registerOpenRouterProvider, } from "./providers/registry.js";
+import { providerRegistry, ensureOpenAIRegistered, registerAnthropicProvider, registerGeminiProvider, registerDeepSeekProvider, registerOllamaProvider, registerOpenRouterProvider } from "./providers/registry.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";
 import { ProviderNotConfiguredError, UnsupportedFeatureError, ModelCapabilityError } from "./errors/index.js";
 import { resolveModelAlias } from "./model_aliases.js";
+import { logger } from "./utils/logger.js";
 import { config, Configuration } from "./config.js";
 // Provider registration map
 const PROVIDER_REGISTRARS = {
@@ -15,125 +17,63 @@ const PROVIDER_REGISTRARS = {
     anthropic: registerAnthropicProvider,
     deepseek: registerDeepSeekProvider,
     ollama: registerOllamaProvider,
-    openrouter: registerOpenRouterProvider,
+    openrouter: registerOpenRouterProvider
 };
 export class NodeLLMCore {
-    models = ModelRegistry;
     config;
     provider;
-    defaultChatModelId;
-    defaultTranscriptionModelId;
-    defaultModerationModelId;
-    defaultEmbeddingModelId;
-    retry = {
-        attempts: 1,
-        delayMs: 0,
-    };
-    /**
-     * Create a new LLM instance. Defaults to the global config.
-     */
-    constructor(customConfig) {
-        if (customConfig instanceof Configuration) {
-            this.config = customConfig;
-        }
-        else if (customConfig) {
-            this.config = new Configuration();
-            Object.assign(this.config, customConfig);
-        }
-        else {
-            this.config = config;
-        }
-        if (this.config.maxRetries !== undefined) {
-            this.retry.attempts = this.config.maxRetries + 1;
-        }
+    retry;
+    defaults;
+    models = ModelRegistry;
+    pricing = PricingRegistry;
+    constructor(config, provider, retry = { attempts: 1, delayMs: 0 }, defaults = {}) {
+        this.config = config;
+        this.provider = provider;
+        this.retry = retry;
+        this.defaults = defaults;
+        Object.freeze(this.config);
+        Object.freeze(this.retry);
+        Object.freeze(this.defaults);
+    }
+    get defaultChatModel() {
+        return this.defaults.chat;
+    }
+    get defaultTranscriptionModel() {
+        return this.defaults.transcription;
+    }
+    get defaultModerationModel() {
+        return this.defaults.moderation;
+    }
+    get defaultEmbeddingModel() {
+        return this.defaults.embedding;
     }
     /**
      * 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, scopedConfig) {
-        const baseConfig = (this.config instanceof Configuration) ? this.config.toPlainObject() : this.config;
-        const scoped = new NodeLLMCore({ ...baseConfig, ...scopedConfig });
-        scoped.configure({ provider: providerName });
-        return scoped;
+        const baseConfig = this.config instanceof Configuration ? this.config.toPlainObject() : this.config;
+        // We leverage createLLM to handle the resolution of the new provider string
+        return createLLM({
+            ...baseConfig,
+            ...scopedConfig,
+            provider: providerName,
+            // Preserve defaults unless overridden (conceptually, though createLLM takes specific keys)
+            defaultChatModel: this.defaults.chat,
+            defaultTranscriptionModel: this.defaults.transcription,
+            defaultModerationModel: this.defaults.moderation,
+            defaultEmbeddingModel: this.defaults.embedding
+        });
     }
     /**
      * 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, factory) {
         providerRegistry.register(name, factory);
     }
-    configure(configOrCallback) {
-        // Callback style: for setting API keys
-        if (typeof configOrCallback === "function") {
-            configOrCallback(this.config);
-            return;
-        }
-        // Object style: for setting provider and other options
-        const options = configOrCallback;
-        // Extract known control keys
-        const { provider, retry, defaultChatModel, defaultTranscriptionModel, defaultModerationModel, defaultEmbeddingModel, ...apiConfig } = options;
-        // Merge API keys into global config
-        Object.assign(this.config, apiConfig);
-        if (apiConfig.maxRetries !== undefined) {
-            this.retry.attempts = apiConfig.maxRetries + 1;
-        }
-        if (defaultChatModel) {
-            this.defaultChatModelId = defaultChatModel;
-        }
-        if (defaultTranscriptionModel) {
-            this.defaultTranscriptionModelId = defaultTranscriptionModel;
-        }
-        if (defaultModerationModel) {
-            this.defaultModerationModelId = defaultModerationModel;
-        }
-        if (defaultEmbeddingModel) {
-            this.defaultEmbeddingModelId = defaultEmbeddingModel;
-        }
-        if (retry) {
-            this.retry = {
-                attempts: retry.attempts ?? 1,
-                delayMs: retry.delayMs ?? 0,
-            };
-        }
-        if (typeof provider === "string") {
-            // Use the provider registrars map
-            const registrar = PROVIDER_REGISTRARS[provider];
-            if (registrar) {
-                registrar();
-            }
-            this.provider = providerRegistry.resolve(provider);
-        }
-        else if (provider) {
-            this.provider = provider;
-        }
+    getRetryConfig() {
+        return this.retry;
     }
     ensureProviderSupport(method) {
         if (!this.provider) {
@@ -148,7 +88,7 @@ export class NodeLLMCore {
         if (!this.provider) {
             throw new ProviderNotConfiguredError();
         }
-        const rawModel = model || this.defaultChatModelId || this.provider.defaultModel("chat");
+        const rawModel = model || this.defaults.chat || this.provider.defaultModel("chat");
         const resolvedModel = resolveModelAlias(rawModel, this.provider.id);
         return new Chat(this.provider, resolvedModel, options, this.retry);
     }
@@ -161,59 +101,50 @@ export class NodeLLMCore {
     }
     async paint(prompt, options) {
         const provider = this.ensureProviderSupport("paint");
-        // Default to resolving aliases
         const rawModel = options?.model;
         const model = resolveModelAlias(rawModel || "", provider.id);
         if (options?.assumeModelExists) {
-            console.warn(`[NodeLLM] Skipping validation for model ${model}`);
+            logger.warn(`Skipping validation for model ${model}`);
         }
-        else if (model && provider.capabilities && !provider.capabilities.supportsImageGeneration(model)) {
+        else if (model &&
+            provider.capabilities &&
+            !provider.capabilities.supportsImageGeneration(model)) {
             throw new ModelCapabilityError(model, "image generation");
         }
         const response = await provider.paint({
             prompt,
             ...options,
             model,
-            requestTimeout: options?.requestTimeout ?? this.config.requestTimeout,
+            requestTimeout: options?.requestTimeout ?? this.config.requestTimeout
         });
         return new GeneratedImage(response);
     }
     async transcribe(file, options) {
         const provider = this.ensureProviderSupport("transcribe");
-        const rawModel = options?.model || this.defaultTranscriptionModelId || "";
+        const rawModel = options?.model || this.defaults.transcription || "";
         const model = resolveModelAlias(rawModel, provider.id);
         if (options?.assumeModelExists) {
-            console.warn(`[NodeLLM] Skipping validation for model ${model}`);
+            logger.warn(`Skipping validation for model ${model}`);
         }
-        else if (model && provider.capabilities && !provider.capabilities.supportsTranscription(model)) {
+        else if (model &&
+            provider.capabilities &&
+            !provider.capabilities.supportsTranscription(model)) {
             throw new ModelCapabilityError(model, "transcription");
         }
         const response = await provider.transcribe({
             file,
             ...options,
             model,
-            requestTimeout: options?.requestTimeout ?? this.config.requestTimeout,
+            requestTimeout: options?.requestTimeout ?? this.config.requestTimeout
         });
         return new Transcription(response);
     }
-    get defaultTranscriptionModel() {
-        return this.defaultTranscriptionModelId;
-    }
-    get defaultModerationModel() {
-        return this.defaultModerationModelId;
-    }
-    get defaultEmbeddingModel() {
-        return this.defaultEmbeddingModelId;
-    }
-    getRetryConfig() {
-        return this.retry;
-    }
     async moderate(input, options) {
         const provider = this.ensureProviderSupport("moderate");
-        const rawModel = options?.model || this.defaultModerationModelId || "";
+        const rawModel = options?.model || this.defaults.moderation || "";
         const model = resolveModelAlias(rawModel, provider.id);
         if (options?.assumeModelExists) {
-            console.warn(`[NodeLLM] Skipping validation for model ${model}`);
+            logger.warn(`Skipping validation for model ${model}`);
         }
         else if (model && provider.capabilities && !provider.capabilities.supportsModeration(model)) {
             throw new ModelCapabilityError(model, "moderation");
@@ -222,29 +153,170 @@ export class NodeLLMCore {
             input,
             ...options,
             model,
-            requestTimeout: options?.requestTimeout ?? this.config.requestTimeout,
+            requestTimeout: options?.requestTimeout ?? this.config.requestTimeout
         });
         return new Moderation(response);
     }
     async embed(input, options) {
         const provider = this.ensureProviderSupport("embed");
-        const rawModel = options?.model || this.defaultEmbeddingModelId || "";
+        const rawModel = options?.model || this.defaults.embedding || "";
         const model = resolveModelAlias(rawModel, provider.id);
         const request = {
             input,
             model,
             dimensions: options?.dimensions,
-            requestTimeout: options?.requestTimeout ?? this.config.requestTimeout,
+            requestTimeout: options?.requestTimeout ?? this.config.requestTimeout
         };
         if (options?.assumeModelExists) {
-            console.warn(`[NodeLLM] Skipping validation for model ${request.model}`);
+            logger.warn(`Skipping validation for model ${request.model}`);
         }
-        else if (request.model && provider.capabilities && !provider.capabilities.supportsEmbeddings(request.model)) {
+        else if (request.model &&
+            provider.capabilities &&
+            !provider.capabilities.supportsEmbeddings(request.model)) {
             throw new ModelCapabilityError(request.model, "embeddings");
         }
         const response = await provider.embed(request);
         return new Embedding(response);
     }
 }
-export { Transcription, Moderation, Embedding };
-export const NodeLLM = new NodeLLMCore();
+export { Transcription, Moderation, Embedding, ModelRegistry, PricingRegistry };
+/**
+ * Creates a new immutable LLM instance.
+ */
+export function createLLM(options = {}) {
+    // 1. Resolve Configuration
+    // We must ensure we are working with a SNAPSHOT of the configuration,
+    // not a live reference to the global mutable Configuration instance.
+    let configSnapshot;
+    if (options instanceof Configuration) {
+        configSnapshot = options.toPlainObject();
+    }
+    else {
+        // If it's a plain object, we merge it into a fresh Configuration to handle
+        // defaults and environment variable fallbacks correctly, then snapshot it.
+        const tempConfig = new Configuration();
+        Object.assign(tempConfig, options);
+        configSnapshot = tempConfig.toPlainObject();
+    }
+    // Use the snapshot for the rest of the logic
+    const baseConfig = configSnapshot;
+    // 2. Resolve Retry
+    let retry = { attempts: 1, delayMs: 0 };
+    if (baseConfig.maxRetries !== undefined) {
+        retry.attempts = baseConfig.maxRetries + 1;
+    }
+    if (options.retry) {
+        retry = {
+            attempts: options.retry.attempts ?? retry.attempts,
+            delayMs: options.retry.delayMs ?? retry.delayMs
+        };
+    }
+    // 3. Resolve Provider
+    let providerInstance;
+    if (typeof options.provider === "string") {
+        const registrar = PROVIDER_REGISTRARS[options.provider];
+        if (registrar)
+            registrar();
+        providerInstance = providerRegistry.resolve(options.provider, baseConfig);
+    }
+    else if (options.provider) {
+        providerInstance = options.provider;
+    }
+    // 4. Resolve Defaults
+    const defaults = {
+        chat: options.defaultChatModel,
+        transcription: options.defaultTranscriptionModel,
+        moderation: options.defaultModerationModel,
+        embedding: options.defaultEmbeddingModel
+    };
+    return new NodeLLMCore(baseConfig, providerInstance, retry, defaults);
+}
+/**
+ * DEFAULT IMMUTABLE INSTANCE
+ *
+ * NodeLLM is a default immutable instance created at startup.
+ *
+ * **Architectural Contract**:
+ * - Configuration is captured from environment variables at module load time
+ * - The instance is frozen and cannot be mutated
+ * - Runtime provider switching is achieved via `withProvider()`, not mutation
+ * - Model names do NOT imply provider selection (provider must be explicit)
+ *
+ * **Usage Patterns**:
+ *
+ * 1. Using the default instance (if env vars are set):
+ * ```typescript
+ * import { NodeLLM } from '@node-llm/core';
+ * const chat = NodeLLM.chat("gpt-4");
+ * ```
+ *
+ * 2. Runtime provider switching (recommended):
+ * ```typescript
+ * const llm = NodeLLM.withProvider("openai", {
+ *   openaiApiKey: process.env.OPENAI_API_KEY
+ * });
+ * const chat = llm.chat("gpt-4");
+ * ```
+ *
+ * 3. Creating custom instances:
+ * ```typescript
+ * import { createLLM } from '@node-llm/core';
+ * const llm = createLLM({ provider: "anthropic", anthropicApiKey: "..." });
+ * ```
+ *
+ * @see ARCHITECTURE.md for full contract details
+ */
+let _defaultInstance;
+/**
+ * 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 const NodeLLM = new Proxy({}, {
+    get: (target, prop) => {
+        if (!_defaultInstance) {
+            _defaultInstance = createLLM(config);
+            Object.freeze(_defaultInstance);
+        }
+        const val = Reflect.get(_defaultInstance, prop);
+        // Only bind if it's a function AND it exists on the prototype (is a method)
+        // This avoids binding properties like 'models' which is a Class.
+        if (typeof val === "function" && prop in NodeLLMCore.prototype) {
+            return val.bind(_defaultInstance);
+        }
+        return val;
+    },
+    getPrototypeOf: () => NodeLLMCore.prototype,
+    getOwnPropertyDescriptor: (target, prop) => {
+        if (!_defaultInstance) {
+            _defaultInstance = createLLM(config);
+            Object.freeze(_defaultInstance);
+        }
+        return Object.getOwnPropertyDescriptor(_defaultInstance, prop);
+    },
+    ownKeys: () => {
+        if (!_defaultInstance) {
+            _defaultInstance = createLLM(config);
+            Object.freeze(_defaultInstance);
+        }
+        return Reflect.ownKeys(_defaultInstance);
+    }
+});
+/**
+ * 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 const LegacyNodeLLM = {
+    configure(_options) {
+        console.warn("NodeLLM.configure() is deprecated and currently a NO-OP. " +
+            "The global NodeLLM instance is now immutable. " +
+            "Use createLLM() for instance-based LLMs or NodeLLM.withProvider() for runtime switching.");
+    }
+};

package/dist/model_aliases.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model_aliases.d.ts","sourceRoot":"","sources":["../src/model_aliases.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,GAAG,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;AAEvI,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,MAAM,CAiBhF"}
+{"version":3,"file":"model_aliases.d.ts","sourceRoot":"","sources":["../src/model_aliases.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,WAAW,GACX,QAAQ,GACR,UAAU,GACV,YAAY,GACZ,SAAS,GACT,UAAU,GACV,SAAS,GACT,MAAM,CAAC;AAEX,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,MAAM,CAiBhF"}

package/dist/models/ModelRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ModelRegistry.d.ts","sourceRoot":"","sources":["../../src/models/ModelRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGnC,qBAAa,aAAa;IACtB,OAAO,CAAC,MAAM,CAAC,MAAM,CAA6C;IAElE,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAMlE;;OAEG;IACH,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,GAAG,KAAK,EAAE,GAAG,IAAI;IAa1C;;OAEG;IACH,MAAM,CAAC,GAAG,IAAI,KAAK,EAAE;IAIrB;;OAEG;IACH,MAAM,CAAC,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAKhF;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAK/E;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAK9E;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;sBAA3I,MAAM;uBAAiB,MAAM;sBAAgB,MAAM;wBAAkB,MAAM;2BAAqB,MAAM;;;;;sBAAtG,MAAM;uBAAiB,MAAM;sBAAgB,MAAM;wBAAkB,MAAM;2BAAqB,MAAM;;CA+BrJ"}
+{"version":3,"file":"ModelRegistry.d.ts","sourceRoot":"","sources":["../../src/models/ModelRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAInC,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,MAAM,CAA6C;IAElE,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAIlE;;OAEG;IACH,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,GAAG,KAAK,EAAE,GAAG,IAAI;IAe1C;;OAEG;IACH,MAAM,CAAC,GAAG,IAAI,KAAK,EAAE;IAIrB;;OAEG;IACH,MAAM,CAAC,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAKhF;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAK/E;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAK9E;;OAEG;IACH,MAAM,CAAC,aAAa,CAClB,KAAK,EAAE;QACL,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,EACD,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM;sBAPA,MAAM;uBACL,MAAM;sBACP,MAAM;wBACJ,MAAM;2BACH,MAAM;;;;;sBAJX,MAAM;uBACL,MAAM;sBACP,MAAM;wBACJ,MAAM;2BACH,MAAM;;CAyC9B"}

package/dist/models/ModelRegistry.js

@@ -1,16 +1,17 @@
 import { modelsData } from "./models.js";
+import { PricingRegistry } from "./PricingRegistry.js";
 export class ModelRegistry {
     static models = modelsData;
     static find(modelId, provider) {
-        return this.models.find(m => (m.id === modelId || m.family === modelId) && (!provider || m.provider === provider));
+        return this.models.find((m) => m.id.toLowerCase() === modelId.toLowerCase() && (!provider || m.provider === provider));
     }
     /**
      * Add or update models in the registry.
      */
     static save(models) {
         const toAdd = Array.isArray(models) ? models : [models];
-        toAdd.forEach(newModel => {
-            const index = this.models.findIndex(m => m.id === newModel.id && m.provider === newModel.provider);
+        toAdd.forEach((newModel) => {
+            const index = this.models.findIndex((m) => m.id === newModel.id && m.provider === newModel.provider);
             if (index >= 0) {
                 this.models[index] = newModel;
             }
@@ -50,21 +51,22 @@ export class ModelRegistry {
      * Calculate cost for usage.
      */
     static calculateCost(usage, modelId, provider) {
-        const model = this.find(modelId, provider);
-        if (!model || !model.pricing?.text_tokens?.standard) {
+        const pricing = PricingRegistry.getPricing(modelId, provider);
+        if (!pricing || !pricing.text_tokens?.standard) {
             return usage;
         }
-        const prices = model.pricing.text_tokens.standard;
+        const prices = pricing.text_tokens.standard;
         const inputPrice = prices.input_per_million || 0;
         const outputPrice = prices.output_per_million || 0;
-        const reasoningPrice = prices.reasoning_output_per_million || outputPrice;
-        const cachedPrice = prices.cached_input_per_million ?? (inputPrice / 2);
+        // Fallback for reasoning: if not specified, default to 2.5x standard output price for specific reasoning models
+        // or just standard output price for others.
+        const reasoningPrice = prices.reasoning_output_per_million ?? (modelId.includes("reasoner") || modelId.includes("3-7") ? outputPrice * 2.5 : outputPrice);
+        const cachedPrice = prices.cached_input_per_million ?? inputPrice / 2;
         const inputCost = ((usage.input_tokens - (usage.cached_tokens || 0)) / 1_000_000) * inputPrice +
             ((usage.cached_tokens || 0) / 1_000_000) * cachedPrice;
         const outputTokens = usage.output_tokens - (usage.reasoning_tokens || 0);
         const reasoningTokens = usage.reasoning_tokens || 0;
-        const outputCost = (outputTokens / 1_000_000) * outputPrice +
-            (reasoningTokens / 1_000_000) * reasoningPrice;
+        const outputCost = (outputTokens / 1_000_000) * outputPrice + (reasoningTokens / 1_000_000) * reasoningPrice;
         const totalCost = inputCost + outputCost;
         return {
             ...usage,

package/dist/models/PricingRegistry.d.ts

@@ -0,0 +1,31 @@
+import { ModelPricing } from "./types.js";
+/**
+ * Registry for LLM pricing information.
+ * Priority: Runtime Overrides > Library Default Patterns > ModelRegistry (models.ts)
+ */
+export declare class PricingRegistry {
+    private static pricingOverrides;
+    private static lastUpdated;
+    private static DEFAULT_PATTERNS;
+    /**
+     * Get pricing for a model.
+     */
+    static getPricing(modelId: string, provider: string): ModelPricing | undefined;
+    /**
+     * Register or override pricing at runtime.
+     */
+    static register(provider: string, modelId: string, pricing: ModelPricing): void;
+    /**
+     * Fetch updates from a remote URL.
+     */
+    static fetchUpdates(url: string): Promise<boolean>;
+    /**
+     * Get the timestamp of the last update.
+     */
+    static getLastUpdated(): Date | null;
+    /**
+     * Reset overrides.
+     */
+    static reset(): void;
+}
+//# sourceMappingURL=PricingRegistry.d.ts.map

package/dist/models/PricingRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PricingRegistry.d.ts","sourceRoot":"","sources":["../../src/models/PricingRegistry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAmC;IAClE,OAAO,CAAC,MAAM,CAAC,WAAW,CAA2B;IAGrD,OAAO,CAAC,MAAM,CAAC,gBAAgB,CA4B7B;IAEF;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAmB9E;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY;IAIxE;;OAEG;WACU,YAAY,CAAC,GAAG,EAAE,MAAM;IAmBrC;;OAEG;IACH,MAAM,CAAC,cAAc,IAAI,IAAI,GAAG,IAAI;IAIpC;;OAEG;IACH,MAAM,CAAC,KAAK;CAIb"}

package/dist/models/PricingRegistry.js

@@ -0,0 +1,101 @@
+import { ModelRegistry } from "./ModelRegistry.js";
+/**
+ * Registry for LLM pricing information.
+ * Priority: Runtime Overrides > Library Default Patterns > ModelRegistry (models.ts)
+ */
+export class PricingRegistry {
+    static pricingOverrides = new Map();
+    static lastUpdated = new Date();
+    // Library-level fallbacks for common model families
+    static DEFAULT_PATTERNS = [
+        {
+            provider: "anthropic",
+            pattern: /claude-3-7/,
+            pricing: {
+                text_tokens: {
+                    standard: { input_per_million: 3.0, output_per_million: 15.0, reasoning_output_per_million: 37.5 },
+                    batch: { input_per_million: 1.5, output_per_million: 7.5, reasoning_output_per_million: 18.75 }
+                }
+            }
+        },
+        {
+            provider: "anthropic",
+            pattern: /claude-3/,
+            pricing: {
+                text_tokens: {
+                    standard: { input_per_million: 3.0, output_per_million: 15.0 },
+                    batch: { input_per_million: 1.5, output_per_million: 7.5 }
+                }
+            }
+        },
+        {
+            provider: "openai",
+            pattern: /gpt-3/,
+            pricing: {
+                text_tokens: { standard: { input_per_million: 0.5, output_per_million: 1.5 } }
+            }
+        }
+    ];
+    /**
+     * Get pricing for a model.
+     */
+    static getPricing(modelId, provider) {
+        // 1. Check custom overrides (Runtime/Remote)
+        const key = `${provider}/${modelId}`;
+        if (this.pricingOverrides.has(key)) {
+            return this.pricingOverrides.get(key);
+        }
+        // 2. Check library default patterns (Core Overrides)
+        for (const entry of this.DEFAULT_PATTERNS) {
+            if (entry.provider === provider && entry.pattern.test(modelId)) {
+                return entry.pricing;
+            }
+        }
+        // 3. Fallback to registry lookup (models.ts)
+        const model = ModelRegistry.find(modelId, provider);
+        return model?.pricing;
+    }
+    /**
+     * Register or override pricing at runtime.
+     */
+    static register(provider, modelId, pricing) {
+        this.pricingOverrides.set(`${provider}/${modelId}`, pricing);
+    }
+    /**
+     * Fetch updates from a remote URL.
+     */
+    static async fetchUpdates(url) {
+        try {
+            const response = await fetch(url);
+            if (!response.ok)
+                throw new Error(response.statusText);
+            const data = await response.json();
+            if (data.models) {
+                for (const [key, pricing] of Object.entries(data.models)) {
+                    const [provider, modelId] = key.split("/");
+                    if (provider && modelId)
+                        this.register(provider, modelId, pricing);
+                }
+            }
+            this.lastUpdated = new Date();
+            return true;
+        }
+        catch (error) {
+            console.error("[NodeLLM] Error fetching pricing updates:", error);
+            return false;
+        }
+    }
+    /**
+     * Get the timestamp of the last update.
+     */
+    static getLastUpdated() {
+        return this.lastUpdated;
+    }
+    /**
+     * Reset overrides.
+     */
+    static reset() {
+        this.pricingOverrides.clear();
+        this.lastUpdated = new Date();
+    }
+}