@jaypie/llm 1.3.10 → 1.3.11

package/dist/esm/index.js

@@ -1,4 +1,4 @@
-import { ConfigurationError, BadGatewayError, TooManyRequestsError, NotImplementedError } from '@jaypie/errors';
+import { ConfigurationError, JaypieError, BadGatewayError, TooManyRequestsError, NotImplementedError } from '@jaypie/errors';
 import log$1, { log as log$2 } from '@jaypie/logger';
 import { z } from 'zod/v4';
 import { placeholders, JAYPIE, resolveValue, sleep } from '@jaypie/kit';
@@ -401,6 +401,36 @@ function determineModelProvider(input) {
     };
 }
 
+/**
+ * Normalizes a `model` option that may be a single model name or a
+ * preference-ordered array of model names.
+ *
+ * A `string[]` is interpreted as a fallback chain: index `0` is the primary
+ * model, indices `1..` become fallback entries with an auto-detected provider
+ * (reusing `determineModelProvider`, exactly as the constructor's first
+ * argument does).
+ *
+ * Returns the primary model plus the derived fallback chain. A bare string
+ * yields an empty chain and is unchanged.
+ */
+function resolveModelChain(model) {
+    if (!Array.isArray(model)) {
+        return { fallback: [], model };
+    }
+    if (model.length === 0) {
+        throw new ConfigurationError("model array must contain at least one model name");
+    }
+    const [primary, ...rest] = model;
+    const fallback = rest.map((name) => {
+        const determined = determineModelProvider(name);
+        if (!determined.provider) {
+            throw new ConfigurationError(`Unable to determine provider from model: ${name}`);
+        }
+        return { model: determined.model, provider: determined.provider };
+    });
+    return { fallback, model: primary };
+}
+
 //
 //
 // Abstract Base Adapter
@@ -1490,8 +1520,14 @@ var ErrorCategory;
 (function (ErrorCategory) {
     /** Error is transient and can be retried */
     ErrorCategory["Retryable"] = "retryable";
-    /** Error is due to rate limiting */
+    /** Error is due to short-term rate limiting (retry after a delay) */
     ErrorCategory["RateLimit"] = "rate_limit";
+    /**
+     * Provider quota is exhausted or the account cannot be billed
+     * (insufficient funds, daily quota, plan limit). Terminal and actionable —
+     * retrying within the request budget will not help.
+     */
+    ErrorCategory["Quota"] = "quota";
     /** Error cannot be recovered from */
     ErrorCategory["Unrecoverable"] = "unrecoverable";
     /** Error type is unknown */
@@ -1582,6 +1618,99 @@ function isTransientNetworkError(error) {
     return false;
 }
 
+//
+//
+// Constants
+//
+/**
+ * Transient structured-output compile failures. The provider caches the
+ * compiled grammar after a successful compile, so an immediate retry of the
+ * identical request typically succeeds (issue #422).
+ */
+const RETRYABLE_MESSAGE_PATTERNS = [
+    "grammar compilation timed out",
+    "grammar compilation timeout",
+];
+/** Billing / insufficient-funds signals — the account cannot be charged. */
+const BILLING_MESSAGE_PATTERNS = [
+    "insufficient_quota",
+    "insufficient funds",
+    "insufficient credit",
+    "credit balance",
+    "billing",
+    "payment required",
+    "plan and billing",
+];
+/** Exhausted usage quota (per-day / per-model limits). */
+const QUOTA_MESSAGE_PATTERNS = [
+    "quota exceeded",
+    "exceeded your current quota",
+    "resource_exhausted",
+    "quota_exceeded",
+];
+//
+//
+// Helpers
+//
+function extractMessage(error) {
+    if (error instanceof Error)
+        return error.message.toLowerCase();
+    if (typeof error === "string")
+        return error.toLowerCase();
+    if (error && typeof error === "object") {
+        const message = error.message;
+        if (typeof message === "string")
+            return message.toLowerCase();
+    }
+    return "";
+}
+//
+//
+// Main
+//
+/**
+ * Shared, provider-agnostic first pass over an error. Returns a
+ * {@link ClassifiedError} when the message unambiguously identifies a
+ * cross-provider condition (retryable structured-output timeout, exhausted
+ * quota, or a billing failure), or `undefined` to defer to the adapter's own
+ * status/name classification.
+ *
+ * Adapters call this before their existing logic so that, for example, a
+ * `429` carrying a daily-quota message is classified as {@link
+ * ErrorCategory.Quota} rather than {@link ErrorCategory.RateLimit}.
+ */
+function classifyProviderError(error) {
+    const message = extractMessage(error);
+    if (!message)
+        return undefined;
+    for (const pattern of RETRYABLE_MESSAGE_PATTERNS) {
+        if (message.includes(pattern)) {
+            return { category: ErrorCategory.Retryable, error, shouldRetry: true };
+        }
+    }
+    for (const pattern of BILLING_MESSAGE_PATTERNS) {
+        if (message.includes(pattern)) {
+            return {
+                category: ErrorCategory.Quota,
+                error,
+                reason: "billing",
+                shouldRetry: false,
+            };
+        }
+    }
+    for (const pattern of QUOTA_MESSAGE_PATTERNS) {
+        if (message.includes(pattern)) {
+            return {
+                category: ErrorCategory.Quota,
+                error,
+                reason: "quota",
+                shouldRetry: false,
+            };
+        }
+    }
+    return undefined;
+}
+
 //
 //
 // Constants
@@ -2355,6 +2484,11 @@ class AnthropicAdapter extends BaseProviderAdapter {
     // Error Classification
     //
     classifyError(error) {
+        // Shared first pass: retryable structured-output timeouts (#422),
+        // quota exhaustion, and billing failures classify the same across providers.
+        const shared = classifyProviderError(error);
+        if (shared)
+            return shared;
         const errorName = error?.constructor?.name;
         // Check for rate limit error
         if (errorName === "RateLimitError") {
@@ -2963,6 +3097,11 @@ class BedrockAdapter extends BaseProviderAdapter {
     // Error Classification
     //
     classifyError(error) {
+        // Shared first pass: retryable structured-output timeouts (#422),
+        // quota exhaustion, and billing failures classify the same across providers.
+        const shared = classifyProviderError(error);
+        if (shared)
+            return shared;
         const errorName = error?.constructor?.name;
         const errorMessage = error?.message ?? "";
         if (errorName === "ThrottlingException" ||
@@ -3632,6 +3771,11 @@ class GoogleAdapter extends BaseProviderAdapter {
     // Error Classification
     //
     classifyError(error) {
+        // Shared first pass: retryable structured-output timeouts (#422),
+        // quota exhaustion, and billing failures classify the same across providers.
+        const shared = classifyProviderError(error);
+        if (shared)
+            return shared;
         const geminiError = error;
         // Extract status code from error
         const statusCode = geminiError.status || geminiError.code;
@@ -4580,6 +4724,11 @@ class OpenAiAdapter extends BaseProviderAdapter {
     // Error Classification
     //
     classifyError(error) {
+        // Shared first pass: retryable structured-output timeouts (#422),
+        // quota exhaustion, and billing failures classify the same across providers.
+        const shared = classifyProviderError(error);
+        if (shared)
+            return shared;
         // Check for rate limit error
         if (error instanceof RateLimitError$1) {
             return {
@@ -5348,6 +5497,11 @@ class OpenRouterAdapter extends BaseProviderAdapter {
     // Error Classification
     //
     classifyError(error) {
+        // Shared first pass: retryable structured-output timeouts (#422),
+        // quota exhaustion, and billing failures classify the same across providers.
+        const shared = classifyProviderError(error);
+        if (shared)
+            return shared;
         // Check if error has a status code (HTTP error)
         const errorWithStatus = error;
         const statusCode = errorWithStatus.status || errorWithStatus.statusCode;
@@ -6712,6 +6866,122 @@ function createStaleRejectionGuard() {
     };
 }
 
+//
+//
+// Base
+//
+/**
+ * Normalized, provider-agnostic LLM error. Thrown by the operate/stream retry
+ * layer when a request cannot be completed, so consumers can `catch` a stable
+ * type regardless of which provider failed. Extends {@link JaypieError} so
+ * `isJaypieError()` and `.status` continue to work; the original provider error
+ * is preserved on `.cause`.
+ */
+class LlmError extends JaypieError {
+    constructor(message, category, { status = 502, title = "Bad Gateway", provider, model, retryAfterMs, cause, } = {}) {
+        super(message, { status, title }, { _type: "LlmError" });
+        this.name = "LlmError";
+        this.category = category;
+        this.provider = provider;
+        this.model = model;
+        this.retryAfterMs = retryAfterMs;
+        this.cause = cause;
+    }
+}
+//
+//
+// Subclasses
+//
+/**
+ * Short-term rate limiting (per-minute 429). Terminal within the request
+ * budget; `retryAfterMs` carries the provider's suggested wait when available.
+ */
+class LlmRateLimitError extends LlmError {
+    constructor(message, options = {}) {
+        super(message, ErrorCategory.RateLimit, {
+            status: 429,
+            title: "Too Many Requests",
+            ...options,
+        });
+        this.name = "LlmRateLimitError";
+    }
+}
+/**
+ * Provider quota is exhausted or the account cannot be billed. Terminal and
+ * actionable. `reason` distinguishes an exhausted usage quota from insufficient
+ * funds.
+ */
+class LlmQuotaError extends LlmError {
+    constructor(message, { reason = "quota", ...options } = {}) {
+        super(message, ErrorCategory.Quota, {
+            status: 402,
+            title: "Payment Required",
+            ...options,
+        });
+        this.name = "LlmQuotaError";
+        this.reason = reason;
+    }
+}
+/**
+ * The request cannot be recovered from (bad request, authentication,
+ * permission, not found). Terminal.
+ */
+class LlmUnrecoverableError extends LlmError {
+    constructor(message, options = {}) {
+        super(message, ErrorCategory.Unrecoverable, {
+            status: 502,
+            title: "Bad Gateway",
+            ...options,
+        });
+        this.name = "LlmUnrecoverableError";
+    }
+}
+/**
+ * A transient or unknown error survived the retry budget. Terminal only because
+ * retries were exhausted; the underlying condition may succeed later.
+ */
+class LlmTransientError extends LlmError {
+    constructor(message, options = {}) {
+        super(message, ErrorCategory.Retryable, {
+            status: 504,
+            title: "Gateway Timeout",
+            ...options,
+        });
+        this.name = "LlmTransientError";
+    }
+}
+
+/**
+ * Map a {@link ClassifiedError} to the matching {@link LlmError} subclass,
+ * preserving the original error as `cause`. Used by the retry layer to throw a
+ * stable, catchable type instead of a bare gateway error.
+ */
+function toLlmError(classified, context = {}) {
+    const original = classified.error;
+    const message = original instanceof Error ? original.message : String(original);
+    const options = {
+        cause: original,
+        model: context.model,
+        provider: context.provider,
+        retryAfterMs: classified.suggestedDelayMs,
+    };
+    switch (classified.category) {
+        case ErrorCategory.RateLimit:
+            return new LlmRateLimitError(message, options);
+        case ErrorCategory.Quota:
+            return new LlmQuotaError(message, {
+                ...options,
+                reason: classified.reason ?? "quota",
+            });
+        case ErrorCategory.Unrecoverable:
+            return new LlmUnrecoverableError(message, options);
+        case ErrorCategory.Retryable:
+        case ErrorCategory.Unknown:
+        default:
+            return new LlmTransientError(message, options);
+    }
+}
+
 //
 //
 // Main
@@ -6726,6 +6996,18 @@ class RetryExecutor {
         this.hookRunner = config.hookRunner ?? hookRunner;
         this.errorClassifier = config.errorClassifier;
     }
+    /**
+     * Build the typed, provider-agnostic error thrown when a request cannot be
+     * completed — classified (rate limit / quota / unrecoverable / transient)
+     * and carrying the provider, model, and original error as `cause`.
+     */
+    toTerminalError(error, context) {
+        const classified = this.errorClassifier.classify(error);
+        return toLlmError(classified, {
+            model: context.model,
+            provider: context.provider,
+        });
+    }
     /**
      * Execute an operation with retry logic.
      * Each attempt receives an AbortSignal. On failure, the signal is aborted
@@ -6769,8 +7051,7 @@ class RetryExecutor {
                             providerRequest: options.context.providerRequest,
                             error,
                         });
-                        const errorMessage = error instanceof Error ? error.message : String(error);
-                        throw new BadGatewayError(errorMessage);
+                        throw this.toTerminalError(error, options.context);
                     }
                     // Check if error is not retryable
                     if (!this.errorClassifier.isRetryable(error)) {
@@ -6782,8 +7063,7 @@ class RetryExecutor {
                             providerRequest: options.context.providerRequest,
                             error,
                         });
-                        const errorMessage = error instanceof Error ? error.message : String(error);
-                        throw new BadGatewayError(errorMessage);
+                        throw this.toTerminalError(error, options.context);
                     }
                     // Warn if this is an unknown error type
                     if (!this.errorClassifier.isKnownError(error)) {
@@ -6826,6 +7106,7 @@ const MAX_CONSECUTIVE_TOOL_ERRORS = 6;
  */
 function createErrorClassifier(adapter) {
     return {
+        classify: (error) => adapter.classifyError(error),
         isRetryable: (error) => adapter.isRetryableError(error),
         isKnownError: (error) => {
             const classified = adapter.classifyError(error);
@@ -7079,7 +7360,9 @@ class OperateLoop {
             const response = await retryExecutor.execute((signal) => this.adapter.executeRequest(this.client, providerRequest, signal), {
                 context: {
                     input: state.currentInput,
+                    model: options.model ?? this.adapter.defaultModel,
                     options,
+                    provider: this.adapter.name,
                     providerRequest,
                 },
                 hooks: hooksWithProgress,
@@ -7702,9 +7985,11 @@ class StreamLoop {
                         !this.adapter.isRetryableError(error)) {
                         log.error(`Stream request failed after ${this.retryPolicy.maxRetries} retries`);
                         log.var({ error });
-                        const errorMessage = error instanceof Error ? error.message : String(error);
                         llmSpan?.finish();
-                        throw new BadGatewayError(errorMessage);
+                        throw toLlmError(this.adapter.classifyError(error), {
+                            model: options.model ?? this.adapter.defaultModel,
+                            provider: this.adapter.name,
+                        });
                     }
                     const delay = this.retryPolicy.getDelayForAttempt(attempt);
                     log.warn(`Stream request failed. Retrying in ${delay}ms...`);
@@ -9175,7 +9460,14 @@ class XaiProvider {
 
 class Llm {
     constructor(providerName = DEFAULT.PROVIDER.NAME, options = {}) {
-        const { fallback, model } = options;
+        const { fallback: fallbackOption, model: modelOption } = options;
+        // A `model` array is sugar for a preference-ordered fallback chain:
+        // index 0 is primary, the rest become fallback entries (provider
+        // auto-detected). Any explicit `fallback` is appended after the chain.
+        const { fallback: modelFallback, model } = resolveModelChain(modelOption);
+        const fallback = modelFallback.length || fallbackOption
+            ? [...modelFallback, ...(fallbackOption ?? [])]
+            : undefined;
         let finalProvider = providerName;
         let finalModel = model;
         // Legacy: accept "gemini" but warn
@@ -9247,6 +9539,11 @@ class Llm {
         }
     }
     async send(message, options) {
+        if (options && Array.isArray(options.model)) {
+            // `send` has no fallback machinery; use the primary model only
+            const { model } = resolveModelChain(options.model);
+            return this._llm.send(message, { ...options, model });
+        }
         return this._llm.send(message, options);
     }
     /**
@@ -9279,8 +9576,21 @@ class Llm {
         if (!this._llm.operate) {
             throw new NotImplementedError(`Provider ${this._provider} does not support operate method`);
         }
-        const fallbackChain = this.resolveFallbackChain(options);
-        const optionsWithoutFallback = { ...options, fallback: false };
+        // A per-call `model` array becomes primary + a derived fallback chain
+        // prepended to any resolved chain.
+        const { fallback: modelFallback, model: perCallModel } = resolveModelChain(options.model);
+        const resolvedOptions = {
+            ...options,
+            model: perCallModel,
+        };
+        const fallbackChain = [
+            ...modelFallback,
+            ...this.resolveFallbackChain(resolvedOptions),
+        ];
+        const optionsWithoutFallback = {
+            ...resolvedOptions,
+            fallback: false,
+        };
         let lastError;
         let attempts = 0;
         // Try primary provider first
@@ -9329,33 +9639,45 @@ class Llm {
         if (!this._llm.stream) {
             throw new NotImplementedError(`Provider ${this._provider} does not support stream method`);
         }
-        yield* this._llm.stream(input, options);
+        // `stream` has no instance-level fallback machinery; an array model uses
+        // the primary and ignores the rest.
+        const { model } = resolveModelChain(options.model);
+        const streamOptions = { ...options, model };
+        yield* this._llm.stream(input, streamOptions);
     }
     static async send(message, options) {
         const { llm, apiKey, model, ...messageOptions } = options || {};
-        const instance = new Llm(llm, { apiKey, model });
+        // A `model` array derives a fallback chain; `send` has no fallback
+        // machinery, so the primary model is used and the chain is ignored.
+        const { model: primaryModel } = resolveModelChain(model);
+        const instance = new Llm(llm, { apiKey, model: primaryModel });
         return instance.send(message, messageOptions);
     }
     static async operate(input, options) {
         const { apiKey, fallback, llm, model, ...operateOptions } = options || {};
+        // A `model` array becomes primary + derived fallback chain
+        const { fallback: modelFallback, model: primaryModel } = resolveModelChain(model);
         let finalLlm = llm;
-        let finalModel = model;
-        if (!llm && model) {
-            const determined = determineModelProvider(model);
+        let finalModel = primaryModel;
+        if (!llm && primaryModel) {
+            const determined = determineModelProvider(primaryModel);
             if (determined.provider) {
                 finalLlm = determined.provider;
             }
         }
-        else if (llm && model) {
+        else if (llm && primaryModel) {
             // When both llm and model are provided, check if they conflict
-            const determined = determineModelProvider(model);
+            const determined = determineModelProvider(primaryModel);
             if (determined.provider && determined.provider !== llm) {
                 // Don't pass the conflicting model to the constructor
                 finalModel = undefined;
             }
         }
         // Resolve fallback for static method: pass to instance if array, pass to operate options if false
-        const instanceFallback = Array.isArray(fallback) ? fallback : undefined;
+        const explicitFallback = Array.isArray(fallback) ? fallback : [];
+        const instanceFallback = modelFallback.length || explicitFallback.length
+            ? [...modelFallback, ...explicitFallback]
+            : undefined;
         const operateFallback = fallback === false ? false : undefined;
         const instance = new Llm(finalLlm, {
             apiKey,
@@ -9369,23 +9691,29 @@ class Llm {
     }
     static stream(input, options) {
         const { llm, apiKey, model, ...streamOptions } = options || {};
+        // A `model` array becomes primary + derived fallback chain
+        const { fallback: modelFallback, model: primaryModel } = resolveModelChain(model);
         let finalLlm = llm;
-        let finalModel = model;
-        if (!llm && model) {
-            const determined = determineModelProvider(model);
+        let finalModel = primaryModel;
+        if (!llm && primaryModel) {
+            const determined = determineModelProvider(primaryModel);
             if (determined.provider) {
                 finalLlm = determined.provider;
             }
         }
-        else if (llm && model) {
+        else if (llm && primaryModel) {
             // When both llm and model are provided, check if they conflict
-            const determined = determineModelProvider(model);
+            const determined = determineModelProvider(primaryModel);
             if (determined.provider && determined.provider !== llm) {
                 // Don't pass the conflicting model to the constructor
                 finalModel = undefined;
             }
         }
-        const instance = new Llm(finalLlm, { apiKey, model: finalModel });
+        const instance = new Llm(finalLlm, {
+            apiKey,
+            fallback: modelFallback.length ? modelFallback : undefined,
+            model: finalModel,
+        });
         return instance.stream(input, streamOptions);
     }
 }
@@ -9683,5 +10011,5 @@ const toolkit = new JaypieToolkit(tools);
     [LlmMessageRole.Developer]: "user",
 });
 
-export { BedrockProvider, GoogleProvider as GeminiProvider, GoogleProvider, JaypieToolkit, constants as LLM, Llm, LlmMessageRole, LlmMessageType, LlmProgressEventType, LlmStreamChunkType, OpenRouterProvider, Toolkit, XaiProvider, extractReasoning, isLlmOperateInput, isLlmOperateInputContent, isLlmOperateInputFile, isLlmOperateInputImage, jsonSchemaToNaturalSchema, naturalSchemaToJsonSchema, toolkit, tools };
+export { BedrockProvider, ErrorCategory, GoogleProvider as GeminiProvider, GoogleProvider, JaypieToolkit, constants as LLM, Llm, LlmError, LlmMessageRole, LlmMessageType, LlmProgressEventType, LlmQuotaError, LlmRateLimitError, LlmStreamChunkType, LlmTransientError, LlmUnrecoverableError, OpenRouterProvider, Toolkit, XaiProvider, extractReasoning, isLlmOperateInput, isLlmOperateInputContent, isLlmOperateInputFile, isLlmOperateInputImage, jsonSchemaToNaturalSchema, naturalSchemaToJsonSchema, toolkit, tools };
 //# sourceMappingURL=index.js.map