@jaypie/llm 1.2.5 → 1.2.7

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/operate/adapters/OpenAiAdapter.d.ts

@@ -12,7 +12,7 @@ import { BaseProviderAdapter } from "./ProviderAdapter.interface.js";
  */
 export declare class OpenAiAdapter extends BaseProviderAdapter {
     readonly name: "openai";
-    readonly defaultModel: "gpt-5.1";
+    readonly defaultModel: "gpt-5.2";
     buildRequest(request: OperateRequest): unknown;
     formatTools(toolkit: Toolkit, _outputSchema?: JsonObject): ProviderToolDefinition[];
     formatOutputSchema(schema: JsonObject | NaturalSchema | z.ZodType): JsonObject;

package/dist/cjs/tools/Toolkit.class.d.ts

@@ -17,7 +17,7 @@ export declare class Toolkit {
     call({ name, arguments: args }: {
         name: string;
         arguments: string;
-    }): Promise<any>;
+    }): Promise<import("@jaypie/types").AnyValue>;
     extend(tools: LlmTool[], options?: {
         warn?: boolean;
         replace?: boolean;

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/constants.d.ts

@@ -1,19 +1,28 @@
 export declare const PROVIDER: {
-    readonly OPENROUTER: {
+    readonly ANTHROPIC: {
+        readonly MAX_TOKENS: {
+            readonly DEFAULT: 4096;
+        };
         readonly MODEL: {
-            readonly DEFAULT: "z-ai/glm-4.7";
-            readonly SMALL: "z-ai/glm-4.7";
-            readonly LARGE: "z-ai/glm-4.7";
-            readonly TINY: "z-ai/glm-4.7";
+            readonly DEFAULT: "claude-sonnet-4-5";
+            readonly LARGE: "claude-opus-4-5";
+            readonly SMALL: "claude-sonnet-4-5";
+            readonly TINY: "claude-haiku-4-5";
+        };
+        readonly MODEL_MATCH_WORDS: readonly ["anthropic", "claude", "haiku", "opus", "sonnet"];
+        readonly NAME: "anthropic";
+        readonly PROMPT: {
+            readonly AI: "\n\nAssistant:";
+            readonly HUMAN: "\n\nHuman:";
         };
-        readonly MODEL_MATCH_WORDS: readonly ["openrouter"];
-        readonly NAME: "openrouter";
         readonly ROLE: {
             readonly ASSISTANT: "assistant";
             readonly SYSTEM: "system";
-            readonly TOOL: "tool";
             readonly USER: "user";
         };
+        readonly TOOLS: {
+            readonly SCHEMA_VERSION: "v2";
+        };
     };
     readonly GEMINI: {
         readonly MODEL: {
@@ -29,65 +38,56 @@ export declare const PROVIDER: {
             readonly USER: "user";
         };
     };
-    readonly ANTHROPIC: {
+    readonly OPENAI: {
         readonly MODEL: {
-            readonly DEFAULT: "claude-sonnet-4-5";
-            readonly LARGE: "claude-opus-4-5";
-            readonly SMALL: "claude-sonnet-4-5";
-            readonly TINY: "claude-haiku-4-5";
+            readonly DEFAULT: "gpt-5.2";
+            readonly LARGE: "gpt-5.2-pro";
+            readonly SMALL: "gpt-5-mini";
+            readonly TINY: "gpt-5-nano";
         };
-        readonly MODEL_MATCH_WORDS: readonly ["anthropic", "claude", "haiku", "opus", "sonnet"];
-        readonly NAME: "anthropic";
-        readonly PROMPT: {
-            readonly AI: "\n\nAssistant:";
-            readonly HUMAN: "\n\nHuman:";
+        readonly MODEL_MATCH_WORDS: readonly ["openai", "gpt", RegExp];
+        readonly NAME: "openai";
+    };
+    readonly OPENROUTER: {
+        readonly MODEL: {
+            readonly DEFAULT: "z-ai/glm-4.7";
+            readonly LARGE: "z-ai/glm-4.7";
+            readonly SMALL: "z-ai/glm-4.7";
+            readonly TINY: "z-ai/glm-4.7";
         };
+        readonly MODEL_MATCH_WORDS: readonly ["openrouter"];
+        readonly NAME: "openrouter";
         readonly ROLE: {
             readonly ASSISTANT: "assistant";
             readonly SYSTEM: "system";
+            readonly TOOL: "tool";
             readonly USER: "user";
         };
-        readonly MAX_TOKENS: {
-            readonly DEFAULT: 4096;
-        };
-        readonly TOOLS: {
-            readonly SCHEMA_VERSION: "v2";
-        };
-    };
-    readonly OPENAI: {
-        readonly MODEL: {
-            readonly DEFAULT: "gpt-5.1";
-            readonly LARGE: "gpt-5.1";
-            readonly SMALL: "gpt-5.1-mini";
-            readonly TINY: "gpt-5.1-nano";
-        };
-        readonly MODEL_MATCH_WORDS: readonly ["openai", "gpt", RegExp];
-        readonly NAME: "openai";
     };
 };
 export type LlmProviderName = typeof PROVIDER.ANTHROPIC.NAME | typeof PROVIDER.GEMINI.NAME | typeof PROVIDER.OPENAI.NAME | typeof PROVIDER.OPENROUTER.NAME;
 export declare const DEFAULT: {
     readonly MODEL: {
-        readonly BASE: "gpt-5.1";
-        readonly LARGE: "gpt-5.1";
-        readonly SMALL: "gpt-5.1-mini";
-        readonly TINY: "gpt-5.1-nano";
+        readonly BASE: "gpt-5.2";
+        readonly LARGE: "gpt-5.2-pro";
+        readonly SMALL: "gpt-5-mini";
+        readonly TINY: "gpt-5-nano";
     };
     readonly PROVIDER: {
         readonly MODEL: {
-            readonly DEFAULT: "gpt-5.1";
-            readonly LARGE: "gpt-5.1";
-            readonly SMALL: "gpt-5.1-mini";
-            readonly TINY: "gpt-5.1-nano";
+            readonly DEFAULT: "gpt-5.2";
+            readonly LARGE: "gpt-5.2-pro";
+            readonly SMALL: "gpt-5-mini";
+            readonly TINY: "gpt-5-nano";
         };
         readonly MODEL_MATCH_WORDS: readonly ["openai", "gpt", RegExp];
         readonly NAME: "openai";
     };
 };
 export declare const ALL: {
-    readonly BASE: readonly ["claude-sonnet-4-5", "gemini-3-pro-preview", "gpt-5.1"];
-    readonly COMBINED: readonly ["claude-sonnet-4-5", "claude-opus-4-5", "claude-sonnet-4-5", "claude-haiku-4-5", "gemini-3-pro-preview", "gemini-3-pro-preview", "gemini-3-flash-preview", "gemini-3-flash-preview", "gpt-5.1", "gpt-5.1", "gpt-5.1-mini", "gpt-5.1-nano"];
-    readonly LARGE: readonly ["claude-opus-4-5", "gemini-3-pro-preview", "gpt-5.1"];
-    readonly SMALL: readonly ["claude-sonnet-4-5", "gemini-3-flash-preview", "gpt-5.1-mini"];
-    readonly TINY: readonly ["claude-haiku-4-5", "gemini-3-flash-preview", "gpt-5.1-nano"];
+    readonly BASE: readonly ["claude-sonnet-4-5", "gemini-3-pro-preview", "gpt-5.2"];
+    readonly COMBINED: readonly ["claude-sonnet-4-5", "claude-opus-4-5", "claude-sonnet-4-5", "claude-haiku-4-5", "gemini-3-pro-preview", "gemini-3-pro-preview", "gemini-3-flash-preview", "gemini-3-flash-preview", "gpt-5.2", "gpt-5.2-pro", "gpt-5-mini", "gpt-5-nano"];
+    readonly LARGE: readonly ["claude-opus-4-5", "gemini-3-pro-preview", "gpt-5.2-pro"];
+    readonly SMALL: readonly ["claude-sonnet-4-5", "gemini-3-flash-preview", "gpt-5-mini"];
+    readonly TINY: readonly ["claude-haiku-4-5", "gemini-3-flash-preview", "gpt-5-nano"];
 };

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';
@@ -11,49 +11,43 @@ import { resolve } from 'path';
 import { getS3FileBuffer, getEnvSecret } from '@jaypie/aws';
 import { fetchWeatherApi } from 'openmeteo';
 
-const PROVIDER = {
-    OPENROUTER: {
-        // https://openrouter.ai/models
-        // OpenRouter provides access to hundreds of models from various providers
-        // The model format is: provider/model-name (e.g., "openai/gpt-4", "anthropic/claude-3-opus")
-        MODEL: {
-            // Default uses env var OPENROUTER_MODEL if set, otherwise a reasonable default
-            DEFAULT: "z-ai/glm-4.7",
-            SMALL: "z-ai/glm-4.7",
-            LARGE: "z-ai/glm-4.7",
-            TINY: "z-ai/glm-4.7",
-        },
-        MODEL_MATCH_WORDS: ["openrouter"],
-        NAME: "openrouter",
-        ROLE: {
-            ASSISTANT: "assistant",
-            SYSTEM: "system",
-            TOOL: "tool",
-            USER: "user",
-        },
+const FIRST_CLASS_PROVIDER = {
+    ANTHROPIC: {
+        DEFAULT: "claude-sonnet-4-5",
+        LARGE: "claude-opus-4-5",
+        SMALL: "claude-sonnet-4-5",
+        TINY: "claude-haiku-4-5",
     },
     GEMINI: {
-        // https://ai.google.dev/gemini-api/docs/models
-        MODEL: {
-            DEFAULT: "gemini-3-pro-preview",
-            LARGE: "gemini-3-pro-preview",
-            SMALL: "gemini-3-flash-preview",
-            TINY: "gemini-3-flash-preview",
-        },
-        MODEL_MATCH_WORDS: ["gemini", "google"],
-        NAME: "gemini",
-        ROLE: {
-            MODEL: "model",
-            USER: "user",
-        },
+        DEFAULT: "gemini-3-pro-preview",
+        LARGE: "gemini-3-pro-preview",
+        SMALL: "gemini-3-flash-preview",
+        TINY: "gemini-3-flash-preview",
+    },
+    OPENAI: {
+        DEFAULT: "gpt-5.2",
+        LARGE: "gpt-5.2-pro",
+        SMALL: "gpt-5-mini",
+        TINY: "gpt-5-nano",
+    },
+    OPENROUTER: {
+        DEFAULT: "z-ai/glm-4.7",
+        LARGE: "z-ai/glm-4.7",
+        SMALL: "z-ai/glm-4.7",
+        TINY: "z-ai/glm-4.7",
     },
+};
+const PROVIDER = {
     ANTHROPIC: {
         // https://docs.anthropic.com/en/docs/about-claude/models/overview
+        MAX_TOKENS: {
+            DEFAULT: 4096,
+        },
         MODEL: {
-            DEFAULT: "claude-sonnet-4-5",
-            LARGE: "claude-opus-4-5",
-            SMALL: "claude-sonnet-4-5",
-            TINY: "claude-haiku-4-5",
+            DEFAULT: FIRST_CLASS_PROVIDER.ANTHROPIC.DEFAULT,
+            LARGE: FIRST_CLASS_PROVIDER.ANTHROPIC.LARGE,
+            SMALL: FIRST_CLASS_PROVIDER.ANTHROPIC.SMALL,
+            TINY: FIRST_CLASS_PROVIDER.ANTHROPIC.TINY,
         },
         MODEL_MATCH_WORDS: [
             "anthropic",
@@ -72,24 +66,56 @@ const PROVIDER = {
             SYSTEM: "system",
             USER: "user",
         },
-        MAX_TOKENS: {
-            DEFAULT: 4096,
-        },
         TOOLS: {
             SCHEMA_VERSION: "v2",
         },
     },
+    GEMINI: {
+        // https://ai.google.dev/gemini-api/docs/models
+        MODEL: {
+            DEFAULT: FIRST_CLASS_PROVIDER.GEMINI.DEFAULT,
+            LARGE: FIRST_CLASS_PROVIDER.GEMINI.LARGE,
+            SMALL: FIRST_CLASS_PROVIDER.GEMINI.SMALL,
+            TINY: FIRST_CLASS_PROVIDER.GEMINI.TINY,
+        },
+        MODEL_MATCH_WORDS: ["gemini", "google"],
+        NAME: "gemini",
+        ROLE: {
+            MODEL: "model",
+            USER: "user",
+        },
+    },
     OPENAI: {
         // https://platform.openai.com/docs/models
         MODEL: {
-            DEFAULT: "gpt-5.1",
-            LARGE: "gpt-5.1",
-            SMALL: "gpt-5.1-mini",
-            TINY: "gpt-5.1-nano",
+            DEFAULT: FIRST_CLASS_PROVIDER.OPENAI.DEFAULT,
+            LARGE: FIRST_CLASS_PROVIDER.OPENAI.LARGE,
+            SMALL: FIRST_CLASS_PROVIDER.OPENAI.SMALL,
+            TINY: FIRST_CLASS_PROVIDER.OPENAI.TINY,
         },
         MODEL_MATCH_WORDS: ["openai", "gpt", /^o\d/],
         NAME: "openai",
     },
+    OPENROUTER: {
+        // https://openrouter.ai/models
+        // OpenRouter provides access to hundreds of models from various providers
+        // The model format is: provider/model-name (e.g., "openai/gpt-4", "anthropic/claude-3-opus")
+        MODEL: {
+            // Default uses env var OPENROUTER_MODEL if set, otherwise a reasonable default
+            DEFAULT: FIRST_CLASS_PROVIDER.OPENROUTER.DEFAULT,
+            LARGE: FIRST_CLASS_PROVIDER.OPENROUTER.LARGE,
+            SMALL: FIRST_CLASS_PROVIDER.OPENROUTER.SMALL,
+            TINY: FIRST_CLASS_PROVIDER.OPENROUTER.TINY,
+        },
+        MODEL_MATCH_WORDS: ["openrouter"],
+        NAME: "openrouter",
+        ROLE: {
+            ASSISTANT: "assistant",
+            SYSTEM: "system",
+            TOOL: "tool",
+            USER: "user",
+        },
+    },
 };
 // Last: Defaults
 const DEFAULT = {
@@ -5183,7 +5209,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 +5238,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 +5267,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 +5355,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 +5372,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 || {};