@jaypie/llm 1.2.5 → 1.2.7

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/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/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');
@@ -13,49 +13,43 @@ var path = require('path');
 var aws = require('@jaypie/aws');
 var openmeteo = require('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",
@@ -74,24 +68,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 = {
@@ -481,7 +507,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 +2394,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 +2919,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 +4521,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 +4560,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 +4569,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 +4612,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 +4623,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 +4737,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 +4877,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 +5061,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 +5211,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 +5240,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 +5269,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 +5357,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 +5374,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 || {};