@jaypie/llm 1.3.9 → 1.3.11

package/dist/esm/index.d.ts

@@ -1,7 +1,25 @@
 import * as _jaypie_types from '@jaypie/types';
 import { JsonObject, AnyValue, NaturalMap, NaturalSchema, JsonReturn } from '@jaypie/types';
 import { z } from 'zod/v4';
+import { JaypieError } from '@jaypie/errors';
 
+/**
+ * Provider-neutral reasoning-effort levels — a five-point relative scale that
+ * deliberately borrows no provider's vocabulary. Each adapter translates these
+ * to its provider's native control (OpenAI `reasoning.effort`, Anthropic
+ * `output_config.effort`, Gemini `thinkingLevel`/`thinkingBudget`, Grok
+ * `reasoning_effort`, OpenRouter `reasoning.effort`), spreading the scale across
+ * the provider's available range. Omitting `effort` leaves the provider default
+ * untouched, so it is safe to set across a fallback chain.
+ */
+declare const EFFORT: {
+    readonly LOWEST: "lowest";
+    readonly LOW: "low";
+    readonly MEDIUM: "medium";
+    readonly HIGH: "high";
+    readonly HIGHEST: "highest";
+};
+type LlmEffort = (typeof EFFORT)[keyof typeof EFFORT];
 declare const MODEL: {
     FABLE: string;
     OPUS: string;
@@ -11,13 +29,26 @@ declare const MODEL: {
     GEMINI_FLASH: string;
     GEMINI_FLASH_LITE: string;
     GEMINI_PRO: string;
+    SOL: string;
+    TERRA: string;
+    LUNA: string;
+    /** @deprecated use MODEL.SOL (gpt-5.6-sol) */
     GPT: string;
+    /** @deprecated use MODEL.TERRA (gpt-5.6-terra) */
     GPT_MINI: string;
+    /** @deprecated use MODEL.LUNA (gpt-5.6-luna) */
     GPT_NANO: string;
     GROK: string;
+    OPENROUTER: {
+        GLM: string;
+        LUNA: string;
+        SONNET: string;
+    };
 };
 declare const PROVIDER: {
     readonly BEDROCK: {
+        readonly DEFAULT: "amazon.nova-pro-v1:0";
+        /** @deprecated Size tiers are retired in 2.0. Use PROVIDER.BEDROCK.DEFAULT. */
         readonly MODEL: {
             readonly DEFAULT: "amazon.nova-lite-v1:0";
             readonly LARGE: "amazon.nova-pro-v1:0";
@@ -29,16 +60,18 @@ declare const PROVIDER: {
         readonly REGION: "AWS_REGION";
     };
     readonly ANTHROPIC: {
+        readonly DEFAULT: string;
         readonly MAX_TOKENS: {
             readonly DEFAULT: 16384;
         };
+        /** @deprecated Size tiers are retired in 2.0. Use PROVIDER.ANTHROPIC.DEFAULT, or pick a specific model from MODEL.*. */
         readonly MODEL: {
             readonly DEFAULT: "claude-sonnet-4-6";
             readonly LARGE: "claude-opus-4-8";
             readonly SMALL: "claude-sonnet-4-6";
             readonly TINY: "claude-haiku-4-5";
         };
-        readonly MODEL_MATCH_WORDS: readonly ["anthropic", "claude", "haiku", "opus", "sonnet"];
+        readonly MODEL_MATCH_WORDS: readonly ["anthropic", "claude", "fable", "haiku", "mythos", "opus", "sonnet"];
         readonly NAME: "anthropic";
         readonly PROMPT: {
             readonly AI: "\n\nAssistant:";
@@ -55,6 +88,8 @@ declare const PROVIDER: {
     };
     /** @deprecated Use PROVIDER.GOOGLE — "Google" is the provider; Gemini is the model family */
     readonly GEMINI: {
+        readonly DEFAULT: string;
+        /** @deprecated Size tiers are retired in 2.0. Use PROVIDER.GOOGLE.DEFAULT, or pick a specific model from MODEL.*. */
         readonly MODEL: {
             readonly DEFAULT: "gemini-3.1-pro-preview";
             readonly LARGE: "gemini-3.1-pro-preview";
@@ -69,6 +104,8 @@ declare const PROVIDER: {
         };
     };
     readonly GOOGLE: {
+        readonly DEFAULT: string;
+        /** @deprecated Size tiers are retired in 2.0. Use PROVIDER.GOOGLE.DEFAULT, or pick a specific model from MODEL.*. */
         readonly MODEL: {
             readonly DEFAULT: "gemini-3.1-pro-preview";
             readonly LARGE: "gemini-3.1-pro-preview";
@@ -83,16 +120,20 @@ declare const PROVIDER: {
         };
     };
     readonly OPENAI: {
+        readonly DEFAULT: string;
+        /** @deprecated Size tiers are retired in 2.0. Use PROVIDER.OPENAI.DEFAULT, or pick a specific model from MODEL.*. */
         readonly MODEL: {
             readonly DEFAULT: "gpt-5.4";
             readonly LARGE: "gpt-5.5";
             readonly SMALL: "gpt-5.4-mini";
             readonly TINY: "gpt-5.4-nano";
         };
-        readonly MODEL_MATCH_WORDS: readonly ["openai", "gpt", RegExp];
+        readonly MODEL_MATCH_WORDS: readonly ["gpt", "luna", "openai", "sol", "terra", RegExp];
         readonly NAME: "openai";
     };
     readonly OPENROUTER: {
+        readonly DEFAULT: string;
+        /** @deprecated Size tiers are retired in 2.0. Use PROVIDER.OPENROUTER.DEFAULT, or pick a specific route from MODEL.OPENROUTER.*. */
         readonly MODEL: {
             readonly DEFAULT: "anthropic/claude-sonnet-4-6";
             readonly LARGE: "anthropic/claude-opus-4-8";
@@ -111,6 +152,8 @@ declare const PROVIDER: {
     readonly XAI: {
         readonly API_KEY: "XAI_API_KEY";
         readonly BASE_URL: "https://api.x.ai/v1";
+        readonly DEFAULT: string;
+        /** @deprecated Size tiers are retired in 2.0. Use PROVIDER.XAI.DEFAULT, or pick a specific model from MODEL.*. */
         readonly MODEL: {
             readonly DEFAULT: "grok-latest";
             readonly LARGE: "grok-latest";
@@ -123,6 +166,7 @@ declare const PROVIDER: {
 };
 type LlmProviderName = typeof PROVIDER.ANTHROPIC.NAME | typeof PROVIDER.BEDROCK.NAME | typeof PROVIDER.GOOGLE.NAME | typeof PROVIDER.OPENAI.NAME | typeof PROVIDER.OPENROUTER.NAME | typeof PROVIDER.XAI.NAME;
 declare const DEFAULT: {
+    /** @deprecated Size tiers are retired in 2.0. Use DEFAULT.PROVIDER.DEFAULT, or pick a specific model from MODEL.*. */
     readonly MODEL: {
         readonly BASE: "gpt-5.4";
         readonly LARGE: "gpt-5.5";
@@ -130,16 +174,22 @@ declare const DEFAULT: {
         readonly TINY: "gpt-5.4-nano";
     };
     readonly PROVIDER: {
+        readonly DEFAULT: string;
+        /** @deprecated Size tiers are retired in 2.0. Use PROVIDER.OPENAI.DEFAULT, or pick a specific model from MODEL.*. */
         readonly MODEL: {
             readonly DEFAULT: "gpt-5.4";
             readonly LARGE: "gpt-5.5";
             readonly SMALL: "gpt-5.4-mini";
             readonly TINY: "gpt-5.4-nano";
         };
-        readonly MODEL_MATCH_WORDS: readonly ["openai", "gpt", RegExp];
+        readonly MODEL_MATCH_WORDS: readonly ["gpt", "luna", "openai", "sol", "terra", RegExp];
         readonly NAME: "openai";
     };
 };
+/**
+ * @deprecated Size-tier catalogs are retired in 2.0. Pick specific models from
+ * MODEL.* (grouped by provider via MODEL_MATCH_WORDS / determineModelProvider).
+ */
 declare const ALL: {
     readonly BASE: readonly ["claude-sonnet-4-6", "gemini-3.1-pro-preview", "gpt-5.4", "grok-latest"];
     readonly COMBINED: readonly ("claude-opus-4-8" | "claude-haiku-4-5" | "gemini-3.5-flash" | "gemini-3.1-flash-lite" | "gemini-3.1-pro-preview" | "gpt-5.5" | "gpt-5.4-mini" | "gpt-5.4-nano" | "grok-latest" | "claude-sonnet-4-6" | "gpt-5.4" | "grok-4-1-fast-reasoning" | "grok-4-1-fast-non-reasoning")[];
@@ -150,12 +200,14 @@ declare const ALL: {
 
 declare const constants_ALL: typeof ALL;
 declare const constants_DEFAULT: typeof DEFAULT;
+declare const constants_EFFORT: typeof EFFORT;
+type constants_LlmEffort = LlmEffort;
 type constants_LlmProviderName = LlmProviderName;
 declare const constants_MODEL: typeof MODEL;
 declare const constants_PROVIDER: typeof PROVIDER;
 declare namespace constants {
-  export { constants_ALL as ALL, constants_DEFAULT as DEFAULT, constants_MODEL as MODEL, constants_PROVIDER as PROVIDER };
-  export type { constants_LlmProviderName as LlmProviderName };
+  export { constants_ALL as ALL, constants_DEFAULT as DEFAULT, constants_EFFORT as EFFORT, constants_MODEL as MODEL, constants_PROVIDER as PROVIDER };
+  export type { constants_LlmEffort as LlmEffort, constants_LlmProviderName as LlmProviderName };
 }
 
 interface LlmTool {
@@ -273,7 +325,7 @@ declare enum LlmResponseStatus {
     Incomplete = "incomplete",
     InProgress = "in_progress"
 }
-interface LlmError {
+interface LlmError$1 {
     detail?: string;
     status: number | string;
     title: string;
@@ -461,6 +513,14 @@ interface LlmProgressEvent {
 type LlmProgressCallback = (event: LlmProgressEvent) => unknown | Promise<unknown>;
 interface LlmOperateOptions {
     data?: NaturalMap;
+    /**
+     * Provider-neutral reasoning effort (lowest | low | medium | high | highest).
+     * Each provider translates it to its native control, spreading the scale
+     * across the provider's range; omitting it leaves the provider default
+     * untouched, so it is safe across a fallback chain. Providers without
+     * reasoning control ignore it.
+     */
+    effort?: LlmEffort;
     explain?: boolean;
     /** Chain of fallback providers to try if primary fails. Set to false to disable instance-level fallback. */
     fallback?: LlmFallbackConfig[] | false;
@@ -534,6 +594,15 @@ interface LlmOperateOptions {
     turns?: boolean | number;
     user?: string;
 }
+/**
+ * A single model name, or a preference-ordered array of model names.
+ * An array is interpreted as a fallback chain: index 0 is primary, later
+ * entries are tried in order when earlier ones fail (provider auto-detected
+ * per entry). Accepted by the `Llm` constructor and static/instance
+ * `operate`/`send`/`stream` methods; normalized to a scalar model plus a
+ * derived fallback chain before reaching providers.
+ */
+type LlmModelOption = string | string[];
 interface LlmOptions {
     apiKey?: string;
     /** Chain of fallback providers to try if primary fails */
@@ -551,7 +620,7 @@ interface LlmUsageItem {
 type LlmUsage = LlmUsageItem[];
 interface LlmOperateResponse {
     content?: string | JsonObject;
-    error?: LlmError;
+    error?: LlmError$1;
     /** Number of providers attempted (1 = primary only, >1 = fallback(s) used) */
     fallbackAttempts?: number;
     /** Whether a fallback provider was used instead of the primary */
@@ -577,9 +646,13 @@ declare class Llm implements LlmProvider {
     private _llm;
     private _options;
     private _provider;
-    constructor(providerName?: LlmProviderName | string, options?: LlmOptions);
+    constructor(providerName?: LlmProviderName | string, options?: Omit<LlmOptions, "model"> & {
+        model?: LlmModelOption;
+    });
     private createProvider;
-    send(message: string, options?: LlmMessageOptions): Promise<string | JsonObject>;
+    send(message: string, options?: Omit<LlmMessageOptions, "model"> & {
+        model?: LlmModelOption;
+    }): Promise<string | JsonObject>;
     /**
      * Resolves the fallback chain from instance config and per-call options.
      * Per-call options take precedence over instance config.
@@ -590,23 +663,27 @@ declare class Llm implements LlmProvider {
      * 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 & {
+    operate(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: Omit<LlmOperateOptions, "model"> & {
+        model?: LlmModelOption;
+    }): Promise<LlmOperateResponse>;
+    stream(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: Omit<LlmOperateOptions, "model"> & {
+        model?: LlmModelOption;
+    }): AsyncIterable<LlmStreamChunk>;
+    static send(message: string, options?: Omit<LlmMessageOptions, "model"> & {
         llm?: LlmProviderName;
         apiKey?: string;
-        model?: string;
+        model?: string | string[];
     }): Promise<string | JsonObject>;
-    static operate(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: LlmOperateOptions & {
+    static operate(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: Omit<LlmOperateOptions, "model"> & {
         apiKey?: string;
         fallback?: LlmFallbackConfig[] | false;
         llm?: LlmProviderName;
-        model?: string;
+        model?: string | string[];
     }): Promise<LlmOperateResponse>;
-    static stream(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: LlmOperateOptions & {
+    static stream(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: Omit<LlmOperateOptions, "model"> & {
         llm?: LlmProviderName;
         apiKey?: string;
-        model?: string;
+        model?: string | string[];
     }): AsyncIterable<LlmStreamChunk>;
 }
 
@@ -637,6 +714,87 @@ declare class JaypieToolkit extends Toolkit {
 }
 declare const toolkit: JaypieToolkit;
 
+/**
+ * Categories of errors for retry logic
+ */
+declare enum ErrorCategory {
+    /** Error is transient and can be retried */
+    Retryable = "retryable",
+    /** Error is due to short-term rate limiting (retry after a delay) */
+    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.
+     */
+    Quota = "quota",
+    /** Error cannot be recovered from */
+    Unrecoverable = "unrecoverable",
+    /** Error type is unknown */
+    Unknown = "unknown"
+}
+
+interface LlmErrorOptions {
+    /** Provider name that produced the error (e.g. "anthropic", "google") */
+    provider?: string;
+    /** Model in use when the error occurred */
+    model?: string;
+    /** Milliseconds to wait before retrying, when the provider suggests one */
+    retryAfterMs?: number;
+    /** The original provider error, preserved for inspection */
+    cause?: unknown;
+}
+/**
+ * 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`.
+ */
+declare class LlmError extends JaypieError {
+    readonly category: ErrorCategory;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly retryAfterMs?: number;
+    readonly cause?: unknown;
+    constructor(message: string, category: ErrorCategory, { status, title, provider, model, retryAfterMs, cause, }?: LlmErrorOptions & {
+        status?: number;
+        title?: string;
+    });
+}
+/**
+ * Short-term rate limiting (per-minute 429). Terminal within the request
+ * budget; `retryAfterMs` carries the provider's suggested wait when available.
+ */
+declare class LlmRateLimitError extends LlmError {
+    constructor(message: string, options?: LlmErrorOptions);
+}
+/**
+ * Provider quota is exhausted or the account cannot be billed. Terminal and
+ * actionable. `reason` distinguishes an exhausted usage quota from insufficient
+ * funds.
+ */
+declare class LlmQuotaError extends LlmError {
+    readonly reason: "quota" | "billing";
+    constructor(message: string, { reason, ...options }?: LlmErrorOptions & {
+        reason?: "quota" | "billing";
+    });
+}
+/**
+ * The request cannot be recovered from (bad request, authentication,
+ * permission, not found). Terminal.
+ */
+declare class LlmUnrecoverableError extends LlmError {
+    constructor(message: string, options?: LlmErrorOptions);
+}
+/**
+ * A transient or unknown error survived the retry budget. Terminal only because
+ * retries were exhausted; the underlying condition may succeed later.
+ */
+declare class LlmTransientError extends LlmError {
+    constructor(message: string, options?: LlmErrorOptions);
+}
+
 /**
  * Extracts reasoning text from LLM history items.
  *
@@ -739,5 +897,5 @@ declare class XaiProvider implements LlmProvider {
     stream(input: string | LlmHistory | LlmInputMessage, options?: LlmOperateOptions): AsyncIterable<LlmStreamChunk>;
 }
 
-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 type { LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProgressCallback, LlmProgressEvent, LlmProgressToolCall, LlmProvider, LlmStreamChunk, LlmStreamChunkDone, LlmStreamChunkError, LlmStreamChunkText, LlmStreamChunkToolCall, LlmStreamChunkToolResult, LlmTool };
+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 };
+export type { LlmEffort, LlmErrorOptions, LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmModelOption, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProgressCallback, LlmProgressEvent, LlmProgressToolCall, LlmProvider, LlmStreamChunk, LlmStreamChunkDone, LlmStreamChunkError, LlmStreamChunkText, LlmStreamChunkToolCall, LlmStreamChunkToolResult, LlmTool };