@steve31415/baselib 3.27.0 → 3.28.0

package/dist/llm/complete.d.ts

@@ -1,4 +1,11 @@
-import type { LLMRequest, LLMResponse } from './types.js';
+import type { LLMRequest, LLMResponse, Effort } from './types.js';
+import type { ModelEntry } from './models.js';
+/**
+ * The effort level to send a model: none when the model has no effort
+ * control, otherwise the requested level clamped to the nearest one the
+ * model accepts (e.g. `minimal` → `low` on models without a `minimal`).
+ */
+export declare function resolveEffort(entry: ModelEntry, effort: Effort | undefined): Effort | undefined;
 /**
  * Call an LLM with automatic failover to alternative providers.
  *

package/dist/llm/complete.js

@@ -1,9 +1,25 @@
-import { LLMError } from './types.js';
+import { LLMError, EFFORT_LEVELS } from './types.js';
 import { MODEL_REGISTRY, THINKING_HEADROOM_WARN_TOKENS } from './models.js';
 import { providers } from './providers/index.js';
 const DEFAULT_MAX_TOKENS = 2048;
 const DEFAULT_TEMPERATURE = 0.3;
 const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_THINKING_LEVELS = ['low', 'medium', 'high'];
+/**
+ * The effort level to send a model: none when the model has no effort
+ * control, otherwise the requested level clamped to the nearest one the
+ * model accepts (e.g. `minimal` → `low` on models without a `minimal`).
+ */
+export function resolveEffort(entry, effort) {
+    if (!entry.supportsEffort || effort === undefined)
+        return undefined;
+    const levels = entry.thinkingLevels ?? DEFAULT_THINKING_LEVELS;
+    if (levels.includes(effort))
+        return effort;
+    const rank = (level) => EFFORT_LEVELS.indexOf(level);
+    const wanted = rank(effort);
+    return [...levels].sort((a, b) => Math.abs(rank(a) - wanted) - Math.abs(rank(b) - wanted))[0];
+}
 /**
  * Call an LLM with automatic failover to alternative providers.
  *
@@ -42,6 +58,16 @@ export async function llmComplete(request) {
             ...(request.callSite ? { callSite: request.callSite } : {}),
         });
     }
+    // Google is retiring the Gemini thinking budget in favor of levels (see
+    // LLMRequest.thinkingBudget). Flag every caller still passing one so the
+    // migration to `effort` is visible in the logs, not discovered by a 400.
+    if (request.thinkingBudget !== undefined) {
+        request.logger?.warn('llm.thinking_budget_deprecated', {
+            model: request.model,
+            thinkingBudget: request.thinkingBudget,
+            ...(request.callSite ? { callSite: request.callSite } : {}),
+        });
+    }
     // Build the ordered list of models to try: primary + fallbacks
     const modelsToTry = [request.model, ...entry.fallbacks];
     const failedAttempts = [];
@@ -67,7 +93,7 @@ export async function llmComplete(request) {
                 supportsTemperature: modelEntry.supportsTemperature ?? true,
                 supportsThinkingBudgetZero: modelEntry.supportsThinkingBudgetZero ?? true,
                 supportsForcedToolChoice: modelEntry.supportsForcedToolChoice ?? true,
-                effort: modelEntry.supportsEffort ? request.effort : undefined,
+                effort: resolveEffort(modelEntry, request.effort),
                 jsonSchema: request.jsonSchema,
                 apiKey,
                 logger: request.logger,

package/dist/llm/index.d.ts

@@ -1,4 +1,4 @@
 export { llmComplete } from './complete.js';
 export { MODEL_REGISTRY } from './models.js';
 export type { ModelEntry } from './models.js';
-export { LLMError, type LLMRequest, type LLMResponse, type FailedAttempt, type FinishCategory, type ProviderName, type ApiKeys, type JsonSchema, } from './types.js';
+export { LLMError, EFFORT_LEVELS, type Effort, type LLMRequest, type LLMResponse, type FailedAttempt, type FinishCategory, type ProviderName, type ApiKeys, type JsonSchema, } from './types.js';

package/dist/llm/index.js

@@ -7,4 +7,4 @@
 // Public API
 export { llmComplete } from './complete.js';
 export { MODEL_REGISTRY } from './models.js';
-export { LLMError, } from './types.js';
+export { LLMError, EFFORT_LEVELS, } from './types.js';

package/dist/llm/models.d.ts

@@ -1,4 +1,4 @@
-import type { ProviderName } from './types.js';
+import type { ProviderName, Effort } from './types.js';
 export interface ModelEntry {
     /** Provider that serves this model. */
     provider: ProviderName;
@@ -22,12 +22,22 @@ export interface ModelEntry {
      */
     supportsThinkingBudgetZero?: boolean;
     /**
-     * Whether this model accepts Anthropic's `output_config.effort` parameter
-     * (verified on Sonnet 5 / Sonnet 4.6 2026-08-10; documented GA on Opus
-     * 4.6+/5). Defaults to `false`; the effort option is dropped for models
-     * without it.
+     * Whether this model accepts a reasoning-effort level: Anthropic's
+     * `output_config.effort` (verified on Sonnet 5 / Sonnet 4.6 2026-08-10;
+     * documented GA on Opus 4.6+/5) or Gemini's `thinkingConfig.thinkingLevel`
+     * (every Gemini 3.x model; verified live 2026-10-06). Defaults to `false`;
+     * the effort option is dropped for models without it.
      */
     supportsEffort?: boolean;
+    /**
+     * The effort levels this model accepts, for `supportsEffort` models whose
+     * set differs from the default `low | medium | high`. A requested level
+     * outside the set is clamped to the nearest one in it (`minimal` → `low`).
+     * Gemini 3.5 Flash-Lite, 3.6 Flash and 3 Flash preview also take `minimal`
+     * ("no hidden reasoning"); 3.1 Pro preview does not (Google's per-model
+     * table, 2026-10-06).
+     */
+    thinkingLevels?: readonly Effort[];
     /**
      * Whether this model performs hidden reasoning when the request omits any
      * thinking configuration (which this library always does). Defaults to

package/dist/llm/models.js

@@ -11,7 +11,12 @@ export const THINKING_HEADROOM_WARN_TOKENS = 4096;
 export const MODEL_REGISTRY = {
     // 2026-08 suite refresh: current models are claude-sonnet-5 / claude-opus-5
     // (Anthropic; claude-opus-5-5 succeeded claude-opus-5 on 2026-09-22), the gpt-5.6 sol/terra/luna family (OpenAI), and the Gemini
-    // 3.5/3.6 GA line plus gemini-3.1-pro-preview (Google). Older names stay
+    // 3.5/3.6 GA line plus gemini-3.1-pro-preview (Google). Google's 2026-10
+    // deprecation notice: `temperature`/`topP`/`topK` have had no effect since
+    // 3.6 Flash and, like `thinkingBudget`, will 400 on models after 3.8 Flash
+    // — hence `supportsTemperature: false` from 3.6 Flash on and `effort`
+    // (thinking level) as the reasoning control on every Gemini 3.x entry.
+    // Older names stay
     // registered so existing callers keep working, but no fallback chain routes
     // through a retiring model: gemini-2.5-pro and gemini-2.5-flash shut down
     // 2026-10-16, and the gpt-4o snapshots retire from 2026-10 onward.
@@ -30,6 +35,8 @@ export const MODEL_REGISTRY = {
         // so no `thinksByDefault` headroom warning.
         // Rejects thinkingBudget 0 (400, verified 2026-08-09).
         supportsThinkingBudgetZero: false,
+        supportsEffort: true,
+        thinkingLevels: ['minimal', 'low', 'medium', 'high'],
     },
     'gemini-3.6-flash': {
         provider: 'gemini',
@@ -40,6 +47,11 @@ export const MODEL_REGISTRY = {
         thinksByDefault: true,
         // Rejects thinkingBudget 0 (400, verified 2026-08-09).
         supportsThinkingBudgetZero: false,
+        supportsEffort: true,
+        thinkingLevels: ['minimal', 'low', 'medium', 'high'],
+        // Sampling parameters are fixed at their defaults from this model on
+        // (Google, 2026-10); still accepted today, so omitting changes nothing.
+        supportsTemperature: false,
     },
     'gpt-5.6-luna': {
         provider: 'openai',
@@ -63,11 +75,14 @@ export const MODEL_REGISTRY = {
         provider: 'gemini',
         apiModelId: 'gemini-3.1-flash-lite',
         fallbacks: ['claude-sonnet-4-6'],
+        supportsEffort: true,
     },
     'gemini-3-flash-preview': {
         provider: 'gemini',
         apiModelId: 'gemini-3-flash-preview',
         fallbacks: ['claude-haiku-4-5', 'gpt-5.6-luna'],
+        supportsEffort: true,
+        thinkingLevels: ['minimal', 'low', 'medium', 'high'],
     },
     'gpt-4o-mini': {
         provider: 'openai',
@@ -181,6 +196,8 @@ export const MODEL_REGISTRY = {
         thinksByDefault: true,
         // Rejects thinkingBudget 0 (400, verified 2026-08-09).
         supportsThinkingBudgetZero: false,
+        // Levels low|medium|high only (no `minimal`) — the default set.
+        supportsEffort: true,
     },
     // Retiring 2026-10-16 — migrate callers to gemini-3.1-pro-preview.
     'gemini-2.5-pro': {

package/dist/llm/providers/gemini.js

@@ -53,13 +53,18 @@ export const geminiProvider = {
             generationConfig.responseSchema = stripUnsupportedSchemaFields(request.jsonSchema.schema);
         }
         // Gemini thinking models reason before answering; the reasoning tokens
-        // count against maxOutputTokens. Capping the thinking budget reserves
-        // headroom for the visible response so a long reasoning pass can't
-        // truncate it. Models with a thinking floor (registry
+        // count against maxOutputTokens. `effort` (pre-gated and clamped in
+        // complete.ts) is the current control, sent as a thinking level — not a
+        // token cap, so callers size maxOutputTokens for it. The deprecated
+        // thinkingBudget is still forwarded when no level is set (the API rejects
+        // both together). Models with a thinking floor (registry
         // `supportsThinkingBudgetZero: false`) reject an explicit 0 budget with a
         // 400 — for those a 0 means "as little thinking as possible", which their
         // default already is, so the config is omitted entirely.
-        if (request.thinkingBudget !== undefined
+        if (request.effort) {
+            generationConfig.thinkingConfig = { thinkingLevel: request.effort };
+        }
+        else if (request.thinkingBudget !== undefined
             && (request.thinkingBudget !== 0 || request.supportsThinkingBudgetZero)) {
             generationConfig.thinkingConfig = { thinkingBudget: request.thinkingBudget };
         }

package/dist/llm/types.d.ts

@@ -35,21 +35,25 @@ export interface LLMRequest {
     /** Timeout per provider attempt, including response body download, in ms. Default: 60000. */
     timeoutMs?: number;
     /**
-     * Cap on reasoning/thinking tokens for models that support hidden reasoning
-     * (currently Gemini 2.5 family). Reasoning tokens are charged against the
-     * same budget as output tokens, so when thinking is unbounded it can starve
-     * the visible response and cause mid-string truncation. Setting this
-     * reserves headroom for the response. Ignored by providers that don't
-     * expose a thinking budget.
+     * @deprecated Use `effort`. Gemini's token cap on hidden reasoning. Gemini
+     * 3.x already remaps a budget to a thinking *level* (so it is no longer a
+     * cap), and Google has announced that models after 3.8 Flash reject it
+     * outright (400). Still forwarded to Gemini when `effort` is absent, with
+     * WARN `llm.thinking_budget_deprecated` per call; ignored by Anthropic and
+     * OpenAI, and ignored by Gemini when `effort` is also set.
      */
     thinkingBudget?: number;
     /**
-     * Output-effort level for models that support Anthropic's `output_config.
-     * effort` (registry `supportsEffort`). Lower effort trades thoroughness for
-     * latency/cost. Currently honored on Anthropic models only; when a call
-     * fails over to another provider the fallback runs at its own defaults.
+     * Reasoning-effort level for models that expose one (registry
+     * `supportsEffort`): Anthropic `output_config.effort`, Gemini
+     * `thinkingConfig.thinkingLevel`. Lower effort trades thoroughness for
+     * latency and cost. A level the target model lacks is clamped to its
+     * nearest supported level (registry `thinkingLevels`; `minimal` → `low` on
+     * Anthropic). Dropped for models without the control, so a failed-over
+     * call runs at the fallback's defaults. Levels are not token caps: size
+     * `maxTokens` for the reasoning the level will do.
      */
-    effort?: 'low' | 'medium' | 'high';
+    effort?: Effort;
     /**
      * Optional short identifier for the calling feature (e.g. 'video_classify',
      * 'message_prioritize', 'log_summary'). Included in llm.request and
@@ -80,6 +84,14 @@ export interface LLMRequest {
  * provider-specific vocabulary local to the adapter that owns it.
  */
 export type FinishCategory = 'complete' | 'truncated' | 'declined' | 'other';
+/**
+ * Reasoning-effort levels, ordered from least to most. Each provider adapter
+ * maps a level to its native control (Anthropic `output_config.effort`,
+ * Gemini `thinkingConfig.thinkingLevel`); `minimal` exists only on some
+ * Gemini models and means "no hidden reasoning".
+ */
+export declare const EFFORT_LEVELS: readonly ["minimal", "low", "medium", "high"];
+export type Effort = (typeof EFFORT_LEVELS)[number];
 /** Successful response from llmComplete(). */
 export interface LLMResponse {
     /** The text output (or JSON stringified if jsonSchema was used). */
@@ -188,8 +200,11 @@ export interface ProviderCallRequest {
     logger?: Logger;
     timeoutMs: number;
     thinkingBudget?: number;
-    /** Effort level, pre-gated by the registry's `supportsEffort` (absent when unsupported). */
-    effort?: 'low' | 'medium' | 'high';
+    /**
+     * Effort level, pre-gated by the registry's `supportsEffort` (absent when
+     * unsupported) and clamped to the model's `thinkingLevels`.
+     */
+    effort?: Effort;
     callSite?: string;
     cacheSystemPrompt?: boolean;
 }

package/dist/llm/types.js

@@ -1,3 +1,10 @@
+/**
+ * Reasoning-effort levels, ordered from least to most. Each provider adapter
+ * maps a level to its native control (Anthropic `output_config.effort`,
+ * Gemini `thinkingConfig.thinkingLevel`); `minimal` exists only on some
+ * Gemini models and means "no hidden reasoning".
+ */
+export const EFFORT_LEVELS = ['minimal', 'low', 'medium', 'high'];
 /** Error thrown when an LLM provider call fails. Its message may contain private input; do not log verbatim. */
 export class LLMError extends Error {
     provider;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.27.0",
+  "version": "3.28.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",