@jaypie/llm 1.2.5 → 1.2.6

package/dist/cjs/index.d.ts

@@ -1,6 +1,6 @@
 export { default as Llm } from "./Llm.js";
 export * as LLM from "./constants.js";
-export type { LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProvider, } from "./types/LlmProvider.interface.js";
+export type { LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProvider, } from "./types/LlmProvider.interface.js";
 export { LlmMessageRole, LlmMessageType, } from "./types/LlmProvider.interface.js";
 export { isLlmOperateInput, isLlmOperateInputContent, isLlmOperateInputFile, isLlmOperateInputImage, } from "./types/LlmOperateInput.guards.js";
 export type { LlmTool } from "./types/LlmTool.interface.js";

package/dist/cjs/types/LlmProvider.interface.d.ts

@@ -144,6 +144,18 @@ interface LlmItemReference {
 }
 export type LlmHistoryItem = LlmInputMessage | LlmItemReference | LlmOutputItem | LlmToolResult;
 export type LlmHistory = LlmHistoryItem[];
+/**
+ * Configuration for a fallback provider.
+ * Used when the primary provider fails with an unrecoverable error.
+ */
+export interface LlmFallbackConfig {
+    /** Provider name (e.g., "openai", "anthropic", "gemini") */
+    provider: string;
+    /** Model to use with this provider (optional, uses provider default if not specified) */
+    model?: string;
+    /** API key for this provider (optional, uses environment variable if not specified) */
+    apiKey?: string;
+}
 export interface LlmMessageOptions {
     data?: NaturalMap;
     model?: string;
@@ -157,6 +169,8 @@ export interface LlmMessageOptions {
 export interface LlmOperateOptions {
     data?: NaturalMap;
     explain?: boolean;
+    /** Chain of fallback providers to try if primary fails. Set to false to disable instance-level fallback. */
+    fallback?: LlmFallbackConfig[] | false;
     format?: JsonObject | NaturalSchema | z.ZodType;
     history?: LlmHistory;
     hooks?: {
@@ -215,6 +229,8 @@ export interface LlmOperateOptions {
 }
 export interface LlmOptions {
     apiKey?: string;
+    /** Chain of fallback providers to try if primary fails */
+    fallback?: LlmFallbackConfig[];
     model?: string;
 }
 export interface LlmUsageItem {
@@ -229,9 +245,14 @@ export type LlmUsage = LlmUsageItem[];
 export interface LlmOperateResponse {
     content?: string | JsonObject;
     error?: LlmError;
+    /** Number of providers attempted (1 = primary only, >1 = fallback(s) used) */
+    fallbackAttempts?: number;
+    /** Whether a fallback provider was used instead of the primary */
+    fallbackUsed?: boolean;
     history: LlmHistory;
     model?: string;
     output: LlmOutput;
+    /** Which provider actually handled the request */
     provider?: string;
     reasoning: string[];
     responses: JsonReturn[];

package/dist/esm/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/esm/index.d.ts

@@ -1,6 +1,6 @@
 export { default as Llm } from "./Llm.js";
 export * as LLM from "./constants.js";
-export type { LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProvider, } from "./types/LlmProvider.interface.js";
+export type { LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProvider, } from "./types/LlmProvider.interface.js";
 export { LlmMessageRole, LlmMessageType, } from "./types/LlmProvider.interface.js";
 export { isLlmOperateInput, isLlmOperateInputContent, isLlmOperateInputFile, isLlmOperateInputImage, } from "./types/LlmOperateInput.guards.js";
 export type { LlmTool } from "./types/LlmTool.interface.js";

package/dist/esm/index.js

@@ -1,7 +1,7 @@
 import { ConfigurationError, BadGatewayError, TooManyRequestsError, NotImplementedError } from '@jaypie/errors';
+import log$3, { log as log$2 } from '@jaypie/logger';
 import { z } from 'zod/v4';
 import { placeholders, JAYPIE, resolveValue, sleep } from '@jaypie/kit';
-import { log as log$2 } from '@jaypie/logger';
 import RandomLib from 'random';
 import { RateLimitError, APIConnectionError, APIConnectionTimeoutError, InternalServerError, APIUserAbortError, AuthenticationError, BadRequestError, ConflictError, NotFoundError, PermissionDeniedError, UnprocessableEntityError, OpenAI } from 'openai';
 import { zodResponseFormat } from 'openai/helpers/zod';
@@ -5183,7 +5183,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) {
@@ -5212,6 +5212,7 @@ class Llm {
                 finalModel = undefined;
             }
         }
+        this._fallbackConfig = fallback;
         this._provider = finalProvider;
         this._options = { ...options, model: finalModel };
         this._llm = this.createProvider(finalProvider, this._options);
@@ -5240,11 +5241,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 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$3.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$3.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) {
@@ -5258,7 +5329,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) {
@@ -5275,8 +5346,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 || {};