@jaypie/llm 1.3.9 → 1.3.11

package/dist/esm/operate/adapters/AnthropicAdapter.d.ts

@@ -16,7 +16,8 @@ import { BaseProviderAdapter } from "./ProviderAdapter.interface.js";
  */
 type AnthropicRequestParams = Anthropic.MessageCreateParams & {
     output_config?: {
-        format: {
+        effort?: string;
+        format?: {
             type: "json_schema";
             schema: JsonObject;
         };
@@ -29,7 +30,7 @@ type AnthropicRequestParams = Anthropic.MessageCreateParams & {
  */
 export declare class AnthropicAdapter extends BaseProviderAdapter {
     readonly name: "anthropic";
-    readonly defaultModel: "claude-sonnet-4-6";
+    readonly defaultModel: string;
     private runtimeNoTemperatureModels;
     private runtimeNoStructuredOutputModels;
     rememberModelRejectsTemperature(model: string): void;

package/dist/esm/operate/adapters/BedrockAdapter.d.ts

@@ -49,7 +49,7 @@ type AnnotatedBedrockResponse = ConverseCommandOutput & {
 };
 export declare class BedrockAdapter extends BaseProviderAdapter {
     readonly name: "bedrock";
-    readonly defaultModel: "amazon.nova-lite-v1:0";
+    readonly defaultModel: "amazon.nova-pro-v1:0";
     private _modelsFallbackToStructuredOutputTool;
     private _modelsWithoutTemperature;
     private rememberModelRejectsOutputConfig;

package/dist/esm/operate/adapters/GoogleAdapter.d.ts

@@ -13,7 +13,7 @@ import { GeminiPart, GeminiRawResponse, GeminiRequest } from "../../providers/go
  */
 export declare class GoogleAdapter extends BaseProviderAdapter {
     readonly name: "google";
-    readonly defaultModel: "gemini-3.1-pro-preview";
+    readonly defaultModel: string;
     private runtimeNoStructuredOutputComboModels;
     rememberModelRejectsStructuredOutputCombo(model: string): void;
     clearRuntimeNoStructuredOutputComboModels(): void;

package/dist/esm/operate/adapters/OpenAiAdapter.d.ts

@@ -1,5 +1,7 @@
 import { JsonObject, NaturalSchema } from "@jaypie/types";
 import { z } from "zod/v4";
+import { type LlmEffort } from "../../constants.js";
+import { type LlmEffortMapping } from "../../util/effort.js";
 import { Toolkit } from "../../tools/Toolkit.class.js";
 import { LlmHistory, LlmOperateOptions, LlmToolResult, LlmUsageItem } from "../../types/LlmProvider.interface.js";
 import { LlmStreamChunk } from "../../types/LlmStreamChunk.interface.js";
@@ -12,11 +14,15 @@ import { BaseProviderAdapter } from "./ProviderAdapter.interface.js";
  */
 export declare class OpenAiAdapter extends BaseProviderAdapter {
     readonly name: "openai";
-    readonly defaultModel: "gpt-5.4";
+    readonly defaultModel: string;
     private runtimeNoTemperatureModels;
     rememberModelRejectsTemperature(model: string): void;
     clearRuntimeNoTemperatureModels(): void;
     private supportsTemperature;
+    /** Whether `reasoning.effort` may be sent for this model. Overridden by xAI. */
+    protected supportsReasoningEffort(model: string): boolean;
+    /** Translate a normalized effort to this provider's `reasoning.effort` value. */
+    protected mapReasoningEffort(effort: LlmEffort, model: string): LlmEffortMapping;
     buildRequest(request: OperateRequest): unknown;
     formatTools(toolkit: Toolkit, _outputSchema?: JsonObject): ProviderToolDefinition[];
     formatOutputSchema(schema: JsonObject | NaturalSchema | z.ZodType): JsonObject;

package/dist/esm/operate/adapters/OpenRouterAdapter.d.ts

@@ -79,6 +79,10 @@ interface OpenRouterRequest {
     tools?: OpenRouterTool[];
     tool_choice?: "auto" | "none" | "required";
     response_format?: OpenRouterResponseFormat;
+    reasoning?: {
+        effort?: string;
+        max_tokens?: number;
+    };
     user?: string;
 }
 /**
@@ -111,7 +115,7 @@ type OpenRouterContentPart = {
  */
 export declare class OpenRouterAdapter extends BaseProviderAdapter {
     readonly name: "openrouter";
-    readonly defaultModel: "anthropic/claude-sonnet-4-6";
+    readonly defaultModel: string;
     private runtimeNoStructuredOutputModels;
     rememberModelRejectsStructuredOutput(model: string): void;
     clearRuntimeNoStructuredOutputModels(): void;

package/dist/esm/operate/adapters/XaiAdapter.d.ts

@@ -1,3 +1,5 @@
+import { type LlmEffort } from "../../constants.js";
+import { type LlmEffortMapping } from "../../util/effort.js";
 import { ClassifiedError } from "../types.js";
 import { OpenAiAdapter } from "./OpenAiAdapter.js";
 /**
@@ -8,7 +10,15 @@ import { OpenAiAdapter } from "./OpenAiAdapter.js";
  */
 export declare class XaiAdapter extends OpenAiAdapter {
     readonly name: "xai";
-    readonly defaultModel: "grok-latest";
+    readonly defaultModel: string;
+    /**
+     * Grok gates reasoning effort by model, not by the OpenAI `gpt-*`/`o*`
+     * patterns. Only explicit `*-reasoning` models accept `reasoning_effort`;
+     * bare grok-4 reasons implicitly and rejects it, so we stay conservative and
+     * only opt in models whose name advertises reasoning.
+     */
+    protected supportsReasoningEffort(model: string): boolean;
+    protected mapReasoningEffort(effort: LlmEffort): LlmEffortMapping;
     classifyError(error: unknown): ClassifiedError;
 }
 export declare const xaiAdapter: XaiAdapter;

package/dist/esm/operate/retry/RetryExecutor.d.ts

@@ -1,13 +1,20 @@
 import { HookRunner, LlmHooks } from "../hooks/HookRunner.js";
 import { RetryPolicy } from "./RetryPolicy.js";
+import { ClassifiedError } from "../types.js";
 export interface RetryContext {
     input: unknown;
     options?: unknown;
     providerRequest: unknown;
+    /** Provider name, carried onto the thrown LlmError */
+    provider?: string;
+    /** Model in use, carried onto the thrown LlmError */
+    model?: string;
 }
 export interface ErrorClassifier {
     isRetryable(error: unknown): boolean;
     isKnownError(error: unknown): boolean;
+    /** Full classification, used to throw a typed LlmError on terminal failure */
+    classify(error: unknown): ClassifiedError;
 }
 export interface RetryExecutorConfig {
     errorClassifier: ErrorClassifier;
@@ -27,6 +34,12 @@ export declare class RetryExecutor {
     private readonly hookRunner;
     private readonly errorClassifier;
     constructor(config: RetryExecutorConfig);
+    /**
+     * 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`.
+     */
+    private toTerminalError;
     /**
      * Execute an operation with retry logic.
      * Each attempt receives an AbortSignal. On failure, the signal is aborted

package/dist/esm/operate/types.d.ts

@@ -1,4 +1,5 @@
 import { JsonObject } from "@jaypie/types";
+import { type LlmEffort } from "../constants.js";
 import { LlmHistory, LlmMessageType, LlmOperateOptions, LlmUsageItem } from "../types/LlmProvider.interface.js";
 import { Toolkit } from "../tools/Toolkit.class.js";
 /**
@@ -68,6 +69,8 @@ export interface OperateRequest {
     tools?: ProviderToolDefinition[];
     /** Structured output format */
     format?: JsonObject;
+    /** Normalized reasoning effort; adapters translate to provider-native control */
+    effort?: LlmEffort;
     /** Provider-specific options */
     providerOptions?: JsonObject;
     /** Whether the request will execute over a streaming transport */
@@ -94,8 +97,14 @@ export interface ProviderToolDefinition {
 export declare enum ErrorCategory {
     /** Error is transient and can be retried */
     Retryable = "retryable",
-    /** Error is due to rate limiting */
+    /** 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 */
@@ -113,6 +122,11 @@ export interface ClassifiedError {
     shouldRetry: boolean;
     /** Suggested delay before retry (if applicable) */
     suggestedDelayMs?: number;
+    /**
+     * For {@link ErrorCategory.Quota}, distinguishes an exhausted usage quota
+     * from an account that cannot be billed (insufficient funds).
+     */
+    reason?: "quota" | "billing";
 }
 import type { ResponseBuilder } from "./response/ResponseBuilder.js";
 /**

package/dist/esm/providers/google/types.d.ts

@@ -73,6 +73,11 @@ export interface GeminiGenerateContentConfig {
     responseMimeType?: string;
     responseJsonSchema?: JsonObject;
     responseSchema?: JsonObject;
+    thinkingConfig?: {
+        thinkingLevel?: string;
+        thinkingBudget?: number;
+        includeThoughts?: boolean;
+    };
     temperature?: number;
     topP?: number;
     topK?: number;

package/dist/esm/types/LlmProvider.interface.d.ts

@@ -1,5 +1,6 @@
 import { AnyValue, JsonObject, JsonReturn, NaturalMap, NaturalSchema } from "@jaypie/types";
 import { z } from "zod/v4";
+import { type LlmEffort } from "../constants.js";
 import { LlmTool } from "./LlmTool.interface.js";
 import { LlmStreamChunk } from "./LlmStreamChunk.interface.js";
 import { Toolkit } from "../tools/Toolkit.class.js";
@@ -213,6 +214,14 @@ export interface LlmProgressEvent {
 export type LlmProgressCallback = (event: LlmProgressEvent) => unknown | Promise<unknown>;
 export 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;
@@ -286,6 +295,15 @@ export 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.
+ */
+export type LlmModelOption = string | string[];
 export interface LlmOptions {
     apiKey?: string;
     /** Chain of fallback providers to try if primary fails */

package/dist/esm/util/classifyProviderError.d.ts

@@ -0,0 +1,13 @@
+import { ClassifiedError } from "../operate/types.js";
+/**
+ * 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}.
+ */
+export declare function classifyProviderError(error: unknown): ClassifiedError | undefined;

package/dist/esm/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/esm/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/llm",
-  "version": "1.3.9",
+  "version": "1.3.11",
   "description": "Large language model utilities",
   "repository": {
     "type": "git",