@jaypie/llm 1.3.9 → 1.3.11

package/dist/cjs/util/effort.d.ts

@@ -0,0 +1,42 @@
+import { type LlmEffort } from "../constants.js";
+/**
+ * Result of translating the provider-neutral {@link LlmEffort} scale to a
+ * provider's native reasoning control.
+ */
+export interface LlmEffortMapping<T extends string | number = string> {
+    /**
+     * True when the requested neutral level had no distinct native rung and was
+     * collapsed or clamped onto a neighbor (e.g. `highest` -> Grok `high`, or
+     * `highest` -> OpenAI `high` on a model predating `xhigh`). Adapters log
+     * these at debug so a papered-over request stays on the record.
+     */
+    papered: boolean;
+    /** Native effort value for the target provider. */
+    value: T;
+}
+/**
+ * Per-provider translation of the provider-neutral {@link LlmEffort} scale.
+ *
+ * The neutral enum (lowest → low → medium → high → highest) is a relative
+ * five-point scale. Each table below maps it onto the target provider's native
+ * effort control, keeping `medium`/`high` semantically aligned across providers
+ * and using each provider's extra bottom (`minimal`) or top (`xhigh`/`max`)
+ * rung where one exists. Providers with fewer levels collapse the ends and mark
+ * the result `papered`. A single `effort` value is therefore safe to reuse
+ * across providers and fallback chains.
+ */
+/** Consistent debug message for a papered-over effort level. */
+export declare function paperedEffortMessage({ model, provider, requested, value, }: {
+    model: string;
+    provider: string;
+    requested: LlmEffort;
+    value: string | number;
+}): string;
+export declare function toOpenAiEffort(effort: LlmEffort, { model }: {
+    model: string;
+}): LlmEffortMapping;
+export declare function toXaiEffort(effort: LlmEffort): LlmEffortMapping;
+export declare function toAnthropicEffort(effort: LlmEffort): LlmEffortMapping;
+export declare function toGeminiThinkingLevel(effort: LlmEffort): LlmEffortMapping;
+export declare function toGeminiThinkingBudget(effort: LlmEffort): LlmEffortMapping<number>;
+export declare function toOpenRouterEffort(effort: LlmEffort): LlmEffortMapping;

package/dist/cjs/util/resolveModelChain.d.ts

@@ -0,0 +1,17 @@
+import { LlmFallbackConfig } from "../types/LlmProvider.interface.js";
+/**
+ * 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.
+ */
+export declare function resolveModelChain(model?: string | string[]): {
+    model?: string;
+    fallback: LlmFallbackConfig[];
+};

package/dist/esm/Llm.d.ts

@@ -1,15 +1,19 @@
 import { JsonObject } from "@jaypie/types";
 import { LlmProviderName } from "./constants.js";
-import { LlmFallbackConfig, LlmHistory, LlmInputMessage, LlmMessageOptions, LlmOperateInput, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProvider } from "./types/LlmProvider.interface.js";
+import { LlmFallbackConfig, LlmHistory, LlmInputMessage, LlmMessageOptions, LlmModelOption, LlmOperateInput, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProvider } from "./types/LlmProvider.interface.js";
 import { LlmStreamChunk } from "./types/LlmStreamChunk.interface.js";
 declare class Llm implements LlmProvider {
     private _fallbackConfig?;
     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.
@@ -20,23 +24,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>;
 }
 export default Llm;

package/dist/esm/constants.d.ts

@@ -1,3 +1,20 @@
+/**
+ * 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.
+ */
+export declare const EFFORT: {
+    readonly LOWEST: "lowest";
+    readonly LOW: "low";
+    readonly MEDIUM: "medium";
+    readonly HIGH: "high";
+    readonly HIGHEST: "highest";
+};
+export type LlmEffort = (typeof EFFORT)[keyof typeof EFFORT];
 export declare const MODEL: {
     FABLE: string;
     OPUS: string;
@@ -7,13 +24,26 @@ export 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;
+    };
 };
 export 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";
@@ -25,16 +55,18 @@ export 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:";
@@ -51,6 +83,8 @@ export 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";
@@ -65,6 +99,8 @@ export 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";
@@ -79,16 +115,20 @@ export 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";
@@ -107,6 +147,8 @@ export 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";
@@ -119,6 +161,7 @@ export declare const PROVIDER: {
 };
 export 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;
 export 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";
@@ -126,19 +169,25 @@ export 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).
+ */
 export declare const ALL: {
     readonly BASE: readonly ["claude-sonnet-4-6", "gemini-3.1-pro-preview", "gpt-5.4", "grok-latest"];
-    readonly COMBINED: readonly ("claude-sonnet-4-6" | "claude-opus-4-8" | "claude-haiku-4-5" | "gemini-3.1-pro-preview" | "gemini-3.5-flash" | "gemini-3.1-flash-lite" | "gpt-5.4" | "gpt-5.5" | "gpt-5.4-mini" | "gpt-5.4-nano" | "grok-latest" | "grok-4-1-fast-reasoning" | "grok-4-1-fast-non-reasoning")[];
+    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")[];
     readonly LARGE: readonly ["claude-opus-4-8", "gemini-3.1-pro-preview", "gpt-5.5", "grok-latest"];
     readonly SMALL: readonly ["claude-sonnet-4-6", "gemini-3.5-flash", "gpt-5.4-mini", "grok-4-1-fast-reasoning"];
     readonly TINY: readonly ["claude-haiku-4-5", "gemini-3.1-flash-lite", "gpt-5.4-nano", "grok-4-1-fast-non-reasoning"];

package/dist/esm/errors/LlmError.d.ts

@@ -0,0 +1,62 @@
+import { JaypieError } from "@jaypie/errors";
+import { ErrorCategory } from "../operate/types.js";
+export 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`.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export declare class LlmTransientError extends LlmError {
+    constructor(message: string, options?: LlmErrorOptions);
+}

package/dist/esm/errors/toLlmError.d.ts

@@ -0,0 +1,11 @@
+import { ClassifiedError } from "../operate/types.js";
+import { LlmError } from "./LlmError.js";
+/**
+ * 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.
+ */
+export declare function toLlmError(classified: ClassifiedError, context?: {
+    provider?: string;
+    model?: string;
+}): LlmError;