@jaypie/llm 1.2.5 → 1.2.6

package/dist/cjs/Llm.d.ts

@@ -1,14 +1,25 @@
 import { JsonObject } from "@jaypie/types";
 import { LlmProviderName } from "./constants.js";
-import { LlmHistory, LlmInputMessage, LlmMessageOptions, LlmOperateInput, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProvider } from "./types/LlmProvider.interface.js";
+import { LlmFallbackConfig, LlmHistory, LlmInputMessage, LlmMessageOptions, LlmOperateInput, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProvider } from "./types/LlmProvider.interface.js";
 import { LlmStreamChunk } from "./types/LlmStreamChunk.interface.js";
 declare class Llm implements LlmProvider {
-    private _provider;
+    private _fallbackConfig?;
     private _llm;
     private _options;
+    private _provider;
     constructor(providerName?: LlmProviderName | string, options?: LlmOptions);
     private createProvider;
     send(message: string, options?: LlmMessageOptions): Promise<string | JsonObject>;
+    /**
+     * Resolves the fallback chain from instance config and per-call options.
+     * Per-call options take precedence over instance config.
+     * Returns empty array if fallback is disabled.
+     */
+    private resolveFallbackChain;
+    /**
+     * Creates a fallback Llm instance lazily when needed.
+     */
+    private createFallbackInstance;
     operate(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: LlmOperateOptions): Promise<LlmOperateResponse>;
     stream(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: LlmOperateOptions): AsyncIterable<LlmStreamChunk>;
     static send(message: string, options?: LlmMessageOptions & {
@@ -17,8 +28,9 @@ declare class Llm implements LlmProvider {
         model?: string;
     }): Promise<string | JsonObject>;
     static operate(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: LlmOperateOptions & {
-        llm?: LlmProviderName;
         apiKey?: string;
+        fallback?: LlmFallbackConfig[] | false;
+        llm?: LlmProviderName;
         model?: string;
     }): Promise<LlmOperateResponse>;
     static stream(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: LlmOperateOptions & {

package/dist/cjs/index.cjs

@@ -1,9 +1,9 @@
 'use strict';
 
 var errors = require('@jaypie/errors');
+var log$2 = require('@jaypie/logger');
 var v4 = require('zod/v4');
 var kit = require('@jaypie/kit');
-var logger = require('@jaypie/logger');
 var RandomLib = require('random');
 var openai = require('openai');
 var zod = require('openai/helpers/zod');
@@ -481,7 +481,7 @@ function formatOperateInput(input, options) {
     return [input];
 }
 
-const getLogger$4 = () => logger.log.lib({ lib: kit.JAYPIE.LIB.LLM });
+const getLogger$4 = () => log$2.log.lib({ lib: kit.JAYPIE.LIB.LLM });
 const log$1 = getLogger$4();
 
 // Turn policy constants
@@ -2368,16 +2368,16 @@ function convertContentToOpenRouter(content) {
         }
         // Image content - warn and discard
         if (item.type === exports.LlmMessageType.InputImage) {
-            logger.log.warn("OpenRouter does not support image uploads; image discarded");
+            log$2.log.warn("OpenRouter does not support image uploads; image discarded");
             continue;
         }
         // File/Document content - warn and discard
         if (item.type === exports.LlmMessageType.InputFile) {
-            logger.log.warn({ filename: item.filename }, "OpenRouter does not support file uploads; file discarded");
+            log$2.log.warn({ filename: item.filename }, "OpenRouter does not support file uploads; file discarded");
             continue;
         }
         // Unknown type - warn and skip
-        logger.log.warn({ item }, "Unknown content type for OpenRouter; discarded");
+        log$2.log.warn({ item }, "Unknown content type for OpenRouter; discarded");
     }
     // If no text parts remain, return empty string to avoid empty array
     if (parts.length === 0) {
@@ -2893,7 +2893,7 @@ class OpenRouterAdapter extends BaseProviderAdapter {
 const openRouterAdapter = new OpenRouterAdapter();
 
 const DEFAULT_TOOL_TYPE = "function";
-const log = logger.log.lib({ lib: kit.JAYPIE.LIB.LLM });
+const log = log$2.log.lib({ lib: kit.JAYPIE.LIB.LLM });
 function logToolMessage(message, context) {
     log.trace.var({ [context.name]: message });
 }
@@ -4495,7 +4495,7 @@ async function loadSdk$2() {
     }
 }
 // Logger
-const getLogger$3 = () => logger.log.lib({ lib: kit.JAYPIE.LIB.LLM });
+const getLogger$3 = () => log$2.log.lib({ lib: kit.JAYPIE.LIB.LLM });
 // Client initialization
 async function initializeClient$3({ apiKey, } = {}) {
     const logger = getLogger$3();
@@ -4534,7 +4534,7 @@ function prepareMessages$3(message, { data, placeholders } = {}) {
 }
 // Basic text completion
 async function createTextCompletion$1(client, messages, model, systemMessage) {
-    logger.log.trace("Using text output (unstructured)");
+    log$2.log.trace("Using text output (unstructured)");
     const params = {
         model,
         messages,
@@ -4543,17 +4543,17 @@ async function createTextCompletion$1(client, messages, model, systemMessage) {
     // Add system instruction if provided
     if (systemMessage) {
         params.system = systemMessage;
-        logger.log.trace(`System message: ${systemMessage.length} characters`);
+        log$2.log.trace(`System message: ${systemMessage.length} characters`);
     }
     const response = await client.messages.create(params);
     const firstContent = response.content[0];
     const text = firstContent && "text" in firstContent ? firstContent.text : "";
-    logger.log.trace(`Assistant reply: ${text.length} characters`);
+    log$2.log.trace(`Assistant reply: ${text.length} characters`);
     return text;
 }
 // Structured output completion
 async function createStructuredCompletion$1(client, messages, model, responseSchema, systemMessage) {
-    logger.log.trace("Using structured output");
+    log$2.log.trace("Using structured output");
     // Get the JSON schema for the response
     const schema = responseSchema instanceof v4.z.ZodType
         ? responseSchema
@@ -4586,7 +4586,7 @@ async function createStructuredCompletion$1(client, messages, model, responseSch
                 if (!schema.parse(result)) {
                     throw new Error(`JSON response from Anthropic does not match schema: ${responseText}`);
                 }
-                logger.log.trace("Received structured response", { result });
+                log$2.log.trace("Received structured response", { result });
                 return result;
             }
             catch {
@@ -4597,7 +4597,7 @@ async function createStructuredCompletion$1(client, messages, model, responseSch
         throw new Error("Failed to parse structured response from Anthropic");
     }
     catch (error) {
-        logger.log.error("Error creating structured completion", { error });
+        log$2.log.error("Error creating structured completion", { error });
         throw error;
     }
 }
@@ -4711,7 +4711,7 @@ async function loadSdk$1() {
     }
 }
 // Logger
-const getLogger$2 = () => logger.log.lib({ lib: kit.JAYPIE.LIB.LLM });
+const getLogger$2 = () => log$2.log.lib({ lib: kit.JAYPIE.LIB.LLM });
 // Client initialization
 async function initializeClient$2({ apiKey, } = {}) {
     const logger = getLogger$2();
@@ -4851,7 +4851,7 @@ class GeminiProvider {
 }
 
 // Logger
-const getLogger$1 = () => logger.log.lib({ lib: kit.JAYPIE.LIB.LLM });
+const getLogger$1 = () => log$2.log.lib({ lib: kit.JAYPIE.LIB.LLM });
 // Client initialization
 async function initializeClient$1({ apiKey, } = {}) {
     const logger = getLogger$1();
@@ -5035,7 +5035,7 @@ async function loadSdk() {
     }
 }
 // Logger
-const getLogger = () => logger.log.lib({ lib: kit.JAYPIE.LIB.LLM });
+const getLogger = () => log$2.log.lib({ lib: kit.JAYPIE.LIB.LLM });
 // Client initialization
 async function initializeClient({ apiKey, } = {}) {
     const logger = getLogger();
@@ -5185,7 +5185,7 @@ class OpenRouterProvider {
 
 class Llm {
     constructor(providerName = DEFAULT.PROVIDER.NAME, options = {}) {
-        const { model } = options;
+        const { fallback, model } = options;
         let finalProvider = providerName;
         let finalModel = model;
         if (model) {
@@ -5214,6 +5214,7 @@ class Llm {
                 finalModel = undefined;
             }
         }
+        this._fallbackConfig = fallback;
         this._provider = finalProvider;
         this._options = { ...options, model: finalModel };
         this._llm = this.createProvider(finalProvider, this._options);
@@ -5242,11 +5243,81 @@ class Llm {
     async send(message, options) {
         return this._llm.send(message, options);
     }
+    /**
+     * Resolves the fallback chain from instance config and per-call options.
+     * Per-call options take precedence over instance config.
+     * Returns empty array if fallback is disabled.
+     */
+    resolveFallbackChain(options) {
+        // Per-call `fallback: false` disables fallback entirely
+        if (options.fallback === false) {
+            return [];
+        }
+        // Per-call fallback array overrides instance config
+        if (Array.isArray(options.fallback)) {
+            return options.fallback;
+        }
+        // Use instance config if available
+        return this._fallbackConfig || [];
+    }
+    /**
+     * Creates a fallback Llm instance lazily when needed.
+     */
+    createFallbackInstance(config) {
+        return new Llm(config.provider, {
+            apiKey: config.apiKey,
+            model: config.model,
+        });
+    }
     async operate(input, options = {}) {
         if (!this._llm.operate) {
             throw new errors.NotImplementedError(`Provider ${this._provider} does not support operate method`);
         }
-        return this._llm.operate(input, options);
+        const fallbackChain = this.resolveFallbackChain(options);
+        const optionsWithoutFallback = { ...options, fallback: false };
+        let lastError;
+        let attempts = 0;
+        // Try primary provider first
+        attempts++;
+        try {
+            const response = await this._llm.operate(input, optionsWithoutFallback);
+            return {
+                ...response,
+                fallbackAttempts: attempts,
+                fallbackUsed: false,
+                provider: response.provider || this._provider,
+            };
+        }
+        catch (error) {
+            lastError = error;
+            log$2.warn(`Provider ${this._provider} failed`, {
+                error: lastError.message,
+                fallbacksRemaining: fallbackChain.length,
+            });
+        }
+        // Try fallback providers
+        for (const fallbackConfig of fallbackChain) {
+            attempts++;
+            try {
+                const fallbackInstance = this.createFallbackInstance(fallbackConfig);
+                const response = await fallbackInstance.operate(input, optionsWithoutFallback);
+                return {
+                    ...response,
+                    fallbackAttempts: attempts,
+                    fallbackUsed: true,
+                    provider: response.provider || fallbackConfig.provider,
+                };
+            }
+            catch (error) {
+                lastError = error;
+                log$2.warn(`Fallback provider ${fallbackConfig.provider} failed`, {
+                    error: lastError.message,
+                    fallbacksRemaining: fallbackChain.length - attempts + 1,
+                });
+            }
+        }
+        // All providers failed, throw the last error
+        throw lastError;
     }
     async *stream(input, options = {}) {
         if (!this._llm.stream) {
@@ -5260,7 +5331,7 @@ class Llm {
         return instance.send(message, messageOptions);
     }
     static async operate(input, options) {
-        const { llm, apiKey, model, ...operateOptions } = options || {};
+        const { apiKey, fallback, llm, model, ...operateOptions } = options || {};
         let finalLlm = llm;
         let finalModel = model;
         if (!llm && model) {
@@ -5277,8 +5348,18 @@ class Llm {
                 finalModel = undefined;
             }
         }
-        const instance = new Llm(finalLlm, { apiKey, model: finalModel });
-        return instance.operate(input, operateOptions);
+        // Resolve fallback for static method: pass to instance if array, pass to operate options if false
+        const instanceFallback = Array.isArray(fallback) ? fallback : undefined;
+        const operateFallback = fallback === false ? false : undefined;
+        const instance = new Llm(finalLlm, {
+            apiKey,
+            fallback: instanceFallback,
+            model: finalModel,
+        });
+        return instance.operate(input, {
+            ...operateOptions,
+            ...(operateFallback !== undefined && { fallback: operateFallback }),
+        });
     }
     static stream(input, options) {
         const { llm, apiKey, model, ...streamOptions } = options || {};