@blockrun/llm 3.10.0 → 3.11.0

package/README.md

@@ -236,7 +236,24 @@ Every paid request is a real on-chain USDC transfer — look up your wallet addr
 
 ## Smart Routing (ClawRouter)
 
-Let the SDK automatically pick the cheapest capable model for each request:
+Let the SDK automatically pick the cheapest capable model for each request — **<!-- br:savings.autoVsBaselinePct -->88<!-- /br:savings.autoVsBaselinePct -->% cheaper than pinning Claude Opus 5** for the same traffic on `auto`, **<!-- br:savings.ecoVsBaselinePct -->98<!-- /br:savings.ecoVsBaselinePct -->%** on `eco`.
+
+Not an "up to" figure. The baseline, the workload mix and the token ratio are
+published in [`savings-mix.json`](https://github.com/BlockRunAI/blockrun/blob/main/src/brand/savings-mix.json),
+priced against the live catalog, so anyone can recompute the claim and get the
+same answer.
+
+Smart routing is powered by [ClawRouter](https://github.com/BlockRunAI/ClawRouter) —
+the open-source, agent-first LLM router: wallet signatures instead of API keys,
+USDC micropayments instead of credit cards, and <1ms fully-local routing with
+zero external calls. In this SDK it is an **optional peer dependency** —
+install it alongside the SDK:
+
+```bash
+npm install @blockrun/clawrouter
+```
+
+Only `smartChat()` needs it: every other API works without it, and the package is loaded lazily, so a missing or broken router can never break `import '@blockrun/llm'`. Calling `smartChat()` without it throws an error naming the package instead of a cryptic module-load failure.
 
 ```typescript
 import { LLMClient } from '@blockrun/llm';
@@ -247,23 +264,28 @@ const client = new LLMClient();
 const result = await client.smartChat('What is 2+2?');
 console.log(result.response);     // '4'
 console.log(result.model);        // 'moonshot/kimi-k2.5' (cheap, fast)
-console.log(`Saved ${(result.routing.savings * 100).toFixed(0)}%`); // 'Saved 87%'
+console.log(`Saved ${(result.routing.savings * 100).toFixed(0)}%`); // 'Saved 88%'
 
 // Complex reasoning task -> routes to reasoning model
 const complex = await client.smartChat('Prove the Riemann hypothesis step by step');
 console.log(complex.model);  // 'xai/grok-4-1-fast-reasoning'
 
+// Inspect how the request was classified and ranked (Router v3.4 portfolio).
+console.log(complex.routing.method);     // 'portfolio'
+console.log(complex.routing.taskType);   // 'reasoning'
+console.log(complex.routing.candidates); // ranked, capability-eligible models
+
 // Inspect the fallback chain SmartChat will walk on transient errors.
 console.log(complex.routing.fallbacks);  // ['anthropic/claude-opus-4.7', ...]
 ```
 
 ### Automatic Fallback on Transient Errors
 
-`smartChat()` populates a tier-specific fallback chain and `chat()` /
-`chatCompletion()` walk it automatically when the primary model returns a
-transient error — timeouts, network failures, or 5xx responses (502/503/504/
-522/524). 4xx errors and `PaymentError` propagate immediately so wallet /
-auth issues surface fast.
+`smartChat()` populates a fallback chain from the portfolio ranking and
+`chat()` / `chatCompletion()` walk it automatically when the primary model
+returns a transient error — timeouts, network failures, 429 rate limits, or
+5xx responses (502/503/504/522/524). Other 4xx errors and `PaymentError`
+propagate immediately so wallet / auth issues surface fast.
 
 ```typescript
 // Manually pass a fallback chain to chat() / chatCompletion()
@@ -276,12 +298,12 @@ const reply = await client.chat('nvidia/deepseek-v4-flash', 'hello', {
 
 ### Routing Profiles
 
-| Profile | Description | Best For |
-|---------|-------------|----------|
-| `free` | NVIDIA free tier — smart-routes across <!-- br:models.free -->6<!-- /br:models.free --> models (DeepSeek V4 Flash, Nemotron Nano Omni, Qwen3, Llama 4, Mistral, plus 2 hidden gpt-oss) | Zero-cost testing, dev, prod |
-| `eco` | Cheapest models per tier (DeepSeek, xAI) | Cost-sensitive production |
-| `auto` | Best balance of cost/quality (default) | General use |
-| `premium` | Top-tier models (OpenAI, Anthropic) | Quality-critical tasks |
+| Profile | Strategy | Savings vs Opus 5 | Best For |
+|---------|----------|-------------------|----------|
+| `free` | NVIDIA free tier — smart-routes across <!-- br:models.free -->6<!-- /br:models.free --> models (DeepSeek V4 Flash, Nemotron Nano Omni, Qwen3, Llama 4, Mistral, plus 2 hidden gpt-oss) | **100%** | Zero-cost testing, dev, prod |
+| `eco` | Cheapest capable model per tier | **<!-- br:savings.ecoVsBaselinePct -->98<!-- /br:savings.ecoVsBaselinePct -->%** | Cost-sensitive production |
+| `auto` | Best balance of cost/quality (default) | **<!-- br:savings.autoVsBaselinePct -->88<!-- /br:savings.autoVsBaselinePct -->%** | General use |
+| `premium` | Top-tier models (OpenAI, Anthropic) | 0% | Quality-critical tasks |
 
 ```typescript
 // Use premium models for complex tasks
@@ -294,23 +316,78 @@ console.log(result.model);  // 'anthropic/claude-opus-4.7'
 
 ### How ClawRouter Works
 
-ClawRouter uses a 14-dimension rule-based classifier to analyze each request:
-
-- **Token count** - Short vs long prompts
-- **Code presence** - Programming keywords
-- **Reasoning markers** - "prove", "step by step", etc.
-- **Technical terms** - Architecture, optimization, etc.
-- **Creative markers** - Story, poem, brainstorm, etc.
-- **Agentic patterns** - Multi-step, tool use indicators
-
-The classifier runs in <1ms, 100% locally, and routes to one of four tiers:
-
-| Tier | Example Tasks | Auto Profile Model |
-|------|---------------|-------------------|
-| SIMPLE | "What is 2+2?", definitions | moonshot/kimi-k2.5 |
-| MEDIUM | Code snippets, explanations | xai/grok-code-fast-1 |
-| COMPLEX | Architecture, long documents | google/gemini-3.1-pro |
-| REASONING | Proofs, multi-step reasoning | xai/grok-4-1-fast-reasoning |
+Since ClawRouter v0.12.242, Auto uses the deterministic **Router v3.4 portfolio
+strategy**: it classifies the task shape locally across
+<!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions --> dimensions
+(token count, code presence, reasoning markers, technical/creative terms,
+agentic patterns, …), enforces tool / vision / structured-output / context
+constraints as **hard filters**, then ranks an ordered candidate portfolio.
+The winner becomes `routing.model`; the rest surface as `routing.candidates`
+and feed SmartChat's transient-error fallback chain. Routing stays 100% local
+and deterministic — <1ms, no extra model call, no network hop.
+
+Classification still maps to one of four tiers (`routing.tier`). Each
+tier × profile has a designated primary (what the rules strategy —
+`routing.method: 'rules'`, the rollback lever — routes to directly, and what
+anchors the portfolio's candidate pool):
+
+| Tier | Example Tasks | ECO | AUTO | PREMIUM |
+|------|---------------|-----|------|---------|
+| SIMPLE | "What is 2+2?", definitions | free/gpt-oss-120b † (**FREE**) | gemini-2.5-flash ($0.30/$2.50) | kimi-k2.7 † ($0.95/$4.00) |
+| MEDIUM | Code snippets, explanations | gemini-3.1-flash-lite ($0.25/$1.50) | kimi-k2.7 ($0.95/$4.00) | gpt-5.3-codex ($1.75/$14.00) |
+| COMPLEX | Architecture, long documents | gemini-3.1-flash-lite ($0.25/$1.50) | gemini-3.1-pro ($2/$12) | claude-fable-5 ($10/$50) |
+| REASONING | Proofs, multi-step reasoning | grok-4-1-fast-reasoning † ($0.20/$0.50) | grok-4-1-fast-reasoning † ($0.20/$0.50) | claude-sonnet-4.6 ($3/$15) |
+
+† Withheld from `/v1/models` — the router still calls it by direct ID, but you
+will not find it on the public pricing page. The published savings claim is
+priced on visible models only.
+
+This table mirrors ClawRouter's tier configs at the version this SDK pins;
+the [ClawRouter README](https://github.com/BlockRunAI/ClawRouter#how-it-works)
+is the live source of truth as models and prices move.
+
+### Routing Metadata Reference
+
+Every `smartChat()` result carries the full decision on `result.routing`
+(type `RoutingDecision`) — enough to log, audit, or replay why a model was
+picked:
+
+| Field | Description |
+|-------|-------------|
+| `model` | Selected model id (same as `result.model`) |
+| `method` | `'portfolio'` (the Auto default), `'rules'` (rollback strategy), or `'llm'` |
+| `tier` | Task tier: `'SIMPLE'`, `'MEDIUM'`, `'COMPLEX'`, or `'REASONING'` |
+| `taskType` | Portfolio task classification: `'chat'`, `'extraction'`, `'code_edit'`, `'code_agent'`, `'tool_agent'`, `'debug'`, `'reasoning'`, `'reasoning_math'`, `'long_context'`, `'vision'`, … |
+| `candidates` | Ordered, capability-eligible models ranked by the portfolio router; the first entry is `model` |
+| `candidateScores` | Per-candidate score breakdown (`quality` / `cost` / `speed` / `reliability`), ordered with `candidates` |
+| `fallbacks` | The chain `chat()` walks on transient errors (timeout / network / 429 / 5xx) — `candidates` minus the primary, with ClawRouter's proxy-namespace `free/*` ids mapped to their `nvidia/*` gateway ids (SDK-computed) |
+| `savings` | 0–1 fraction saved vs the premium baseline |
+| `costEstimate` / `baselineCost` | Estimated cost of the pick vs that baseline, in USD |
+| `confidence` | Sigmoid-calibrated classifier confidence, 0–1 |
+| `routerVersion` | `'v3-portfolio'` or `'v2-rules'` |
+| `profile` | Routing profile applied: `'auto'`, `'eco'`, `'premium'`, or `'agentic'` |
+| `reasoning` | Human-readable explanation of the decision |
+| `tierConfigs` | The tier → primary/fallback map the decision was made against |
+
+### TypeScript Types
+
+`RoutingDecision`, `RoutingProfile`, `RoutingTier`, `RoutingTaskType`, and
+`RoutingTierConfig` are exported from `@blockrun/llm`. They are derived from
+[`@blockrun/router-core`](https://github.com/BlockRunAI/router-core) — the
+routing engine ClawRouter bundles — pinned to the exact commit ClawRouter's
+published build inlines, and shipped **inlined in this SDK's declaration
+files**. You do not need to install `@blockrun/clawrouter` (or router-core,
+which is not on npm) for your project to typecheck against these types; the
+runtime package is only needed to actually call `smartChat()`.
+
+### Going Deeper
+
+- [ClawRouter](https://github.com/BlockRunAI/ClawRouter) — the router itself: OpenClaw plugin, standalone proxy for Cursor / continue.dev / any OpenAI-compatible client, Telegram integration
+- [Routing profiles in depth](https://github.com/BlockRunAI/ClawRouter/blob/main/docs/routing-profiles.md) — ECO / AUTO / PREMIUM details
+- [How the routing engine works](https://github.com/BlockRunAI/ClawRouter/blob/main/docs/smart-llm-router-14-dimension-classifier.md) — the classifier, dimension by dimension
+- [Router benchmark](https://github.com/BlockRunAI/ClawRouter/blob/main/docs/llm-router-benchmark-46-models-sub-1ms-routing.md) — sub-1ms routing across the catalog
+- [ClawRouter vs OpenRouter](https://github.com/BlockRunAI/ClawRouter/blob/main/docs/clawrouter-vs-openrouter-llm-routing-comparison.md) — head-to-head comparison
+- [`@blockrun/router-core`](https://github.com/BlockRunAI/router-core) — the deterministic routing engine both share
 
 ## Available Models
 
@@ -873,7 +950,7 @@ const response2 = await client.chat('anthropic/claude-sonnet-4', 'Write a haiku'
 
 ### Smart Routing (ClawRouter)
 
-Save up to <!-- br:savings.autoVsBaselinePct -->87<!-- /br:savings.autoVsBaselinePct -->% on inference costs with intelligent model routing. ClawRouter uses a <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions -->-dimension rule-based scoring algorithm to select the cheapest model that can handle your request (<1ms, 100% local).
+Save up to <!-- br:savings.autoVsBaselinePct -->88<!-- /br:savings.autoVsBaselinePct -->% on inference costs with intelligent model routing. ClawRouter's deterministic portfolio router (v3.4, default since ClawRouter v0.12.242) classifies each request across <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions --> dimensions, applies hard capability filters, and ranks the cheapest capable models (<1ms, 100% local). Requires the optional peer dependency: `npm install @blockrun/clawrouter`.
 
 ```typescript
 import { LLMClient } from '@blockrun/llm';
@@ -885,7 +962,7 @@ const result = await client.smartChat('What is 2+2?');
 console.log(result.response);     // '4'
 console.log(result.model);        // 'google/gemini-2.5-flash'
 console.log(result.routing.tier); // 'SIMPLE'
-console.log(`Saved ${(result.routing.savings * 100).toFixed(0)}%`); // 'Saved 87%'
+console.log(`Saved ${(result.routing.savings * 100).toFixed(0)}%`); // 'Saved 88%'
 
 // Routing profiles
 const free = await client.smartChat('Hello!', { routingProfile: 'free' });     // Zero cost
@@ -1442,7 +1519,7 @@ The `AnthropicClient` wraps the official `@anthropic-ai/sdk` with a custom fetch
 When you make an API call, the SDK automatically handles x402 payment. It signs a USDC transaction locally using your wallet private key (which never leaves your machine), and includes the payment proof in the request header. Settlement is non-custodial and instant on Base or Solana.
 
 ### What is smart routing / ClawRouter?
-ClawRouter is a built-in smart routing engine that analyzes your request across <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions --> dimensions and automatically picks the cheapest model capable of handling it. Routing happens locally in under 1ms. It can save up to <!-- br:savings.autoVsBaselinePct -->87<!-- /br:savings.autoVsBaselinePct -->% on LLM costs compared to using premium models for every request.
+ClawRouter is the SDK's smart routing engine, shipped as the optional `@blockrun/clawrouter` peer dependency (`npm install @blockrun/clawrouter` — only `smartChat()` needs it). It analyzes your request across <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions --> dimensions and automatically picks the cheapest model capable of handling it. Routing happens locally in under 1ms. It can save up to <!-- br:savings.autoVsBaselinePct -->88<!-- /br:savings.autoVsBaselinePct -->% on LLM costs compared to using premium models for every request.
 
 ### Does it support streaming?
 Yes — as of v1.6.1. Use `client.chatCompletionStream()` for native streaming or `stream: true` in the OpenAI-compatible client. Payment is handled automatically: the SDK signs USDC payment before streaming begins, and caches payment requirements per model so subsequent calls skip the 402 round-trip (~200ms faster).

package/dist/index.cjs

@@ -608,14 +608,14 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.10.0";
+var SDK_VERSION = "3.11.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
 function isTransientError(err) {
   if (err instanceof PaymentError) return false;
   if (err instanceof APIError) {
-    return [502, 503, 504, 522, 524].includes(err.statusCode);
+    return [429, 502, 503, 504, 522, 524].includes(err.statusCode);
   }
   if (err instanceof Error) {
     if (err.name === "AbortError") return true;
@@ -742,8 +742,11 @@ var LLMClient = class _LLMClient {
   /**
    * Smart chat with automatic model routing.
    *
-   * Uses ClawRouter's 14-dimension rule-based scoring algorithm (<1ms, 100% local)
-   * to select the cheapest model that can handle your request.
+   * Uses ClawRouter's deterministic portfolio router (Router v3.4, the Auto
+   * default since v0.12.242): it classifies the task shape locally (<1ms, no
+   * extra model call), enforces capability constraints as hard filters, and
+   * ranks an ordered candidate portfolio — the cheapest model that can handle
+   * the request wins, and the rest become the transient-error fallback chain.
    *
    * @param prompt - User message
    * @param options - Optional chat and routing parameters
@@ -753,7 +756,8 @@ var LLMClient = class _LLMClient {
    * ```ts
    * const result = await client.smartChat('What is 2+2?');
    * console.log(result.response); // '4'
-   * console.log(result.model); // 'google/gemini-2.5-flash-lite'
+   * console.log(result.model); // 'google/gemini-3.5-flash'
+   * console.log(result.routing.method); // 'portfolio'
    * console.log(result.routing.savings); // 0.78 (78% savings)
    * ```
    *
@@ -785,11 +789,15 @@ var LLMClient = class _LLMClient {
       routingProfile: options?.routingProfile
     });
     const tierConfigs = decision.tierConfigs ?? DEFAULT_ROUTING_CONFIG.tiers;
-    const fullChain = getFallbackChain(decision.tier, tierConfigs);
-    const fallbacks = fullChain.filter(
-      (id) => id !== decision.model && modelPricing.has(id)
-    );
-    const response = await this.chat(decision.model, prompt, {
+    const ranked = decision.candidates?.length ? decision.candidates : [decision.model, ...getFallbackChain(decision.tier, tierConfigs)];
+    const callable = [];
+    for (const id of ranked) {
+      const resolved = !id.startsWith("free/") ? id : modelPricing.has(`nvidia/${id.slice(5)}`) ? `nvidia/${id.slice(5)}` : null;
+      if (resolved && !callable.includes(resolved)) callable.push(resolved);
+    }
+    const primary = callable[0] ?? decision.model;
+    const fallbacks = callable.slice(1);
+    const response = await this.chat(primary, prompt, {
       system: options?.system,
       maxTokens: options?.maxTokens,
       temperature: options?.temperature,
@@ -802,8 +810,8 @@ var LLMClient = class _LLMClient {
     });
     return {
       response,
-      model: decision.model,
-      routing: { ...decision, fallbacks }
+      model: primary,
+      routing: { ...decision, model: primary, fallbacks }
     };
   }
   /**

package/dist/index.d.cts

@@ -1,8 +1,183 @@
 import * as _anthropic_ai_sdk from '@anthropic-ai/sdk';
 
+/**
+ * Smart Router Types
+ *
+ * Four classification tiers — REASONING is distinct from COMPLEX because
+ * reasoning tasks need different models (o3, gemini-pro) than general
+ * complex tasks (gpt-4o, sonnet-4).
+ *
+ * Scoring uses weighted float dimensions with sigmoid confidence calibration.
+ */
+type Tier = "SIMPLE" | "MEDIUM" | "COMPLEX" | "REASONING";
+type RoutingDecision$1 = {
+    model: string;
+    tier: Tier;
+    confidence: number;
+    method: "rules" | "llm" | "portfolio";
+    reasoning: string;
+    costEstimate: number;
+    baselineCost: number;
+    savings: number;
+    agenticScore?: number;
+    /** Which tier configs were used (auto/eco/premium/agentic) — avoids re-derivation in the host */
+    tierConfigs?: Record<Tier, TierConfig>;
+    /** Which routing profile was applied */
+    profile?: "auto" | "eco" | "premium" | "agentic";
+    /** Ordered, capability-eligible candidates. The first entry is `model`. */
+    candidates?: string[];
+    /** Explainable request classification used by the portfolio router. */
+    taskType?: TaskType;
+    /** Router implementation that made the selection. */
+    routerVersion?: "v2-rules" | "v3-portfolio";
+    /** Explainable local portfolio score breakdown, ordered with `candidates`. */
+    candidateScores?: Array<{
+        model: string;
+        score: number;
+        quality: number;
+        cost: number;
+        speed: number;
+        reliability: number;
+    }>;
+};
+type TaskType = "chat" | "extraction" | "code_edit" | "code_agent" | "tool_agent" | "tool_agent_parallel" | "debug" | "reasoning" | "reasoning_mcq" | "reasoning_math" | "long_context" | "vision";
+type TierConfig = {
+    primary: string;
+    fallback: string[];
+};
+type ScoringConfig = {
+    tokenCountThresholds: {
+        simple: number;
+        complex: number;
+    };
+    codeKeywords: string[];
+    reasoningKeywords: string[];
+    simpleKeywords: string[];
+    technicalKeywords: string[];
+    creativeKeywords: string[];
+    imperativeVerbs: string[];
+    constraintIndicators: string[];
+    outputFormatKeywords: string[];
+    referenceKeywords: string[];
+    negationKeywords: string[];
+    domainSpecificKeywords: string[];
+    agenticTaskKeywords: string[];
+    dimensionWeights: Record<string, number>;
+    tierBoundaries: {
+        simpleMedium: number;
+        mediumComplex: number;
+        complexReasoning: number;
+    };
+    confidenceSteepness: number;
+    confidenceThreshold: number;
+};
+type ClassifierConfig = {
+    llmModel: string;
+    llmMaxTokens: number;
+    llmTemperature: number;
+    promptTruncationChars: number;
+    cacheTtlMs: number;
+};
+type OverridesConfig = {
+    maxTokensForceComplex: number;
+    structuredOutputMinTier: Tier;
+    ambiguousDefaultTier: Tier;
+    /**
+     * When enabled, prefer models optimized for agentic workflows.
+     * Agentic models continue autonomously with multi-step tasks
+     * instead of stopping and waiting for user input.
+     */
+    agenticMode?: boolean;
+};
+/**
+ * Time-windowed promotion that temporarily overrides tier routing.
+ * Active promotions are auto-applied; expired ones are ignored at runtime.
+ */
+type Promotion = {
+    /** Human-readable label (e.g. "GLM-5 Launch Promo") */
+    name: string;
+    /** ISO date string, promotion starts (inclusive). e.g. "2026-04-01" */
+    startDate: string;
+    /** ISO date string, promotion ends (exclusive). e.g. "2026-04-15" */
+    endDate: string;
+    /** Partial tier overrides — merged into the active tier configs (primary/fallback) */
+    tierOverrides: Partial<Record<Tier, Partial<TierConfig>>>;
+    /** Which profiles this applies to. Default: all profiles. */
+    profiles?: Array<"auto" | "eco" | "premium" | "agentic">;
+};
+type RoutingConfig = {
+    version: string;
+    /** Enables a one-line rollback to the established V2 rules selector. */
+    strategy?: "rules" | "portfolio";
+    /**
+     * Locally recompute a comparison strategy without changing the model that
+     * actually serves the request. The host emits only decision metadata via
+     * `onShadowRouted`; it never persists prompt content or makes a second call.
+     */
+    shadow?: {
+        strategy: "rules" | "portfolio";
+        sampleRate?: number;
+    };
+    /** Calibratable local portfolio scoring weights; values are relative, not probabilities. */
+    portfolio?: {
+        auto: {
+            quality: number;
+            capability: number;
+            cost: number;
+            speed: number;
+            reliability: number;
+            legacy: number;
+        };
+        eco: {
+            quality: number;
+            capability: number;
+            cost: number;
+            speed: number;
+            reliability: number;
+            legacy: number;
+        };
+        premium: {
+            quality: number;
+            capability: number;
+            cost: number;
+            speed: number;
+            reliability: number;
+            legacy: number;
+        };
+        highStakesBoost: {
+            quality: number;
+            reliability: number;
+        };
+        latencySensitiveSpeedBoost: number;
+        /** A candidate materially below the best task affinity cannot win on cost alone. */
+        affinityFloorGap: {
+            auto: number;
+            eco: number;
+            premium: number;
+        };
+    };
+    classifier: ClassifierConfig;
+    scoring: ScoringConfig;
+    tiers: Record<Tier, TierConfig>;
+    /**
+     * Tier configs for agentic mode — models that excel at multi-step tasks.
+     * Set to `null` to disable agentic tier selection entirely (forces all
+     * requests through `tiers`, even when tools are present in the request).
+     */
+    agenticTiers?: Record<Tier, TierConfig> | null;
+    /** Tier configs for eco profile — ultra cost-optimized (blockrun/eco). `null` falls back to `tiers`. */
+    ecoTiers?: Record<Tier, TierConfig> | null;
+    /** Tier configs for premium profile — best quality (blockrun/premium). `null` falls back to `tiers`. */
+    premiumTiers?: Record<Tier, TierConfig> | null;
+    /** Time-windowed promotions that temporarily override tier routing */
+    promotions?: Promotion[];
+    overrides: OverridesConfig;
+};
+
 /**
  * Type definitions for BlockRun LLM SDK
  */
+
 interface FunctionDefinition {
     name: string;
     description?: string;
@@ -313,24 +488,21 @@ interface ChatCompletionOptions {
     fallbackModels?: string[];
 }
 type RoutingProfile = "eco" | "auto" | "premium";
-type RoutingTier = "SIMPLE" | "MEDIUM" | "COMPLEX" | "REASONING";
-interface RoutingDecision {
-    model: string;
-    tier: RoutingTier;
-    confidence: number;
-    method: "rules" | "llm";
-    reasoning: string;
-    costEstimate: number;
-    baselineCost: number;
-    savings: number;
-    /** Routing profile applied by clawrouter (may include "agentic" on gateway responses). */
-    profile?: RoutingProfile | "agentic";
-    /** Score used when agentic routing is active. */
-    agenticScore?: number;
+type RoutingTier = Tier;
+/**
+ * Request classification produced by the portfolio router (ClawRouter
+ * v0.12.242+, Router v3.4). Present on decisions with `method: "portfolio"`.
+ */
+type RoutingTaskType = TaskType;
+/** Primary model + ordered fallbacks for one routing tier. */
+type RoutingTierConfig = RoutingConfig["tiers"][Tier];
+interface RoutingDecision extends RoutingDecision$1 {
     /**
-     * Remaining tier models with known pricing, in fallback order. `chat()`
-     * walks this list when the primary model hits a transient error
-     * (timeout, network, 5xx). Excludes the primary itself.
+     * Remaining gateway-callable models, in the router's ranked order.
+     * `chat()` walks this list when the primary model hits a transient error
+     * (timeout, network, 429, 5xx). Excludes the primary itself. ClawRouter's
+     * proxy-namespace `free/*` ids appear here as their `nvidia/*` gateway
+     * ids (or are dropped when the mapping is proxy-only).
      */
     fallbacks?: string[];
 }
@@ -1023,8 +1195,11 @@ declare class LLMClient {
     /**
      * Smart chat with automatic model routing.
      *
-     * Uses ClawRouter's 14-dimension rule-based scoring algorithm (<1ms, 100% local)
-     * to select the cheapest model that can handle your request.
+     * Uses ClawRouter's deterministic portfolio router (Router v3.4, the Auto
+     * default since v0.12.242): it classifies the task shape locally (<1ms, no
+     * extra model call), enforces capability constraints as hard filters, and
+     * ranks an ordered candidate portfolio — the cheapest model that can handle
+     * the request wins, and the rest become the transient-error fallback chain.
      *
      * @param prompt - User message
      * @param options - Optional chat and routing parameters
@@ -1034,7 +1209,8 @@ declare class LLMClient {
      * ```ts
      * const result = await client.smartChat('What is 2+2?');
      * console.log(result.response); // '4'
-     * console.log(result.model); // 'google/gemini-2.5-flash-lite'
+     * console.log(result.model); // 'google/gemini-3.5-flash'
+     * console.log(result.routing.method); // 'portfolio'
      * console.log(result.routing.savings); // 0.78 (78% savings)
      * ```
      *
@@ -3238,4 +3414,4 @@ declare function validateTemperature(temperature?: number): void;
  */
 declare function validateTopP(topP?: number): void;
 
-export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, NETWORK_ALIASES, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, RPC_PRICE_USD, type ResponseFormat, RetiredEndpointError, type RoutingDecision, type RoutingProfile, type RoutingTier, type RpcBatchRequest, RpcClient, type RpcClientOptions, type RpcError, type RpcNetwork, type RpcResponse, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SUPPORTED_NETWORKS, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type SoundEffectOptions, type SpeechAudio, SpeechClient, type SpeechClientOptions, type SpeechGenerateOptions, type SpeechModel, type SpeechResponse, type SpeechVoice, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoiceInfo, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, importSolanaWallet, importWallet, listDiscoveredSolanaWallets, listDiscoveredWallets, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, validateMaxTokens, validateModel, validateTemperature, validateTopP };
+export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, NETWORK_ALIASES, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, RPC_PRICE_USD, type ResponseFormat, RetiredEndpointError, type RoutingDecision, type RoutingProfile, type RoutingTaskType, type RoutingTier, type RoutingTierConfig, type RpcBatchRequest, RpcClient, type RpcClientOptions, type RpcError, type RpcNetwork, type RpcResponse, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SUPPORTED_NETWORKS, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type SoundEffectOptions, type SpeechAudio, SpeechClient, type SpeechClientOptions, type SpeechGenerateOptions, type SpeechModel, type SpeechResponse, type SpeechVoice, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoiceInfo, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, importSolanaWallet, importWallet, listDiscoveredSolanaWallets, listDiscoveredWallets, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, validateMaxTokens, validateModel, validateTemperature, validateTopP };

package/dist/index.d.ts

@@ -1,8 +1,183 @@
 import * as _anthropic_ai_sdk from '@anthropic-ai/sdk';
 
+/**
+ * Smart Router Types
+ *
+ * Four classification tiers — REASONING is distinct from COMPLEX because
+ * reasoning tasks need different models (o3, gemini-pro) than general
+ * complex tasks (gpt-4o, sonnet-4).
+ *
+ * Scoring uses weighted float dimensions with sigmoid confidence calibration.
+ */
+type Tier = "SIMPLE" | "MEDIUM" | "COMPLEX" | "REASONING";
+type RoutingDecision$1 = {
+    model: string;
+    tier: Tier;
+    confidence: number;
+    method: "rules" | "llm" | "portfolio";
+    reasoning: string;
+    costEstimate: number;
+    baselineCost: number;
+    savings: number;
+    agenticScore?: number;
+    /** Which tier configs were used (auto/eco/premium/agentic) — avoids re-derivation in the host */
+    tierConfigs?: Record<Tier, TierConfig>;
+    /** Which routing profile was applied */
+    profile?: "auto" | "eco" | "premium" | "agentic";
+    /** Ordered, capability-eligible candidates. The first entry is `model`. */
+    candidates?: string[];
+    /** Explainable request classification used by the portfolio router. */
+    taskType?: TaskType;
+    /** Router implementation that made the selection. */
+    routerVersion?: "v2-rules" | "v3-portfolio";
+    /** Explainable local portfolio score breakdown, ordered with `candidates`. */
+    candidateScores?: Array<{
+        model: string;
+        score: number;
+        quality: number;
+        cost: number;
+        speed: number;
+        reliability: number;
+    }>;
+};
+type TaskType = "chat" | "extraction" | "code_edit" | "code_agent" | "tool_agent" | "tool_agent_parallel" | "debug" | "reasoning" | "reasoning_mcq" | "reasoning_math" | "long_context" | "vision";
+type TierConfig = {
+    primary: string;
+    fallback: string[];
+};
+type ScoringConfig = {
+    tokenCountThresholds: {
+        simple: number;
+        complex: number;
+    };
+    codeKeywords: string[];
+    reasoningKeywords: string[];
+    simpleKeywords: string[];
+    technicalKeywords: string[];
+    creativeKeywords: string[];
+    imperativeVerbs: string[];
+    constraintIndicators: string[];
+    outputFormatKeywords: string[];
+    referenceKeywords: string[];
+    negationKeywords: string[];
+    domainSpecificKeywords: string[];
+    agenticTaskKeywords: string[];
+    dimensionWeights: Record<string, number>;
+    tierBoundaries: {
+        simpleMedium: number;
+        mediumComplex: number;
+        complexReasoning: number;
+    };
+    confidenceSteepness: number;
+    confidenceThreshold: number;
+};
+type ClassifierConfig = {
+    llmModel: string;
+    llmMaxTokens: number;
+    llmTemperature: number;
+    promptTruncationChars: number;
+    cacheTtlMs: number;
+};
+type OverridesConfig = {
+    maxTokensForceComplex: number;
+    structuredOutputMinTier: Tier;
+    ambiguousDefaultTier: Tier;
+    /**
+     * When enabled, prefer models optimized for agentic workflows.
+     * Agentic models continue autonomously with multi-step tasks
+     * instead of stopping and waiting for user input.
+     */
+    agenticMode?: boolean;
+};
+/**
+ * Time-windowed promotion that temporarily overrides tier routing.
+ * Active promotions are auto-applied; expired ones are ignored at runtime.
+ */
+type Promotion = {
+    /** Human-readable label (e.g. "GLM-5 Launch Promo") */
+    name: string;
+    /** ISO date string, promotion starts (inclusive). e.g. "2026-04-01" */
+    startDate: string;
+    /** ISO date string, promotion ends (exclusive). e.g. "2026-04-15" */
+    endDate: string;
+    /** Partial tier overrides — merged into the active tier configs (primary/fallback) */
+    tierOverrides: Partial<Record<Tier, Partial<TierConfig>>>;
+    /** Which profiles this applies to. Default: all profiles. */
+    profiles?: Array<"auto" | "eco" | "premium" | "agentic">;
+};
+type RoutingConfig = {
+    version: string;
+    /** Enables a one-line rollback to the established V2 rules selector. */
+    strategy?: "rules" | "portfolio";
+    /**
+     * Locally recompute a comparison strategy without changing the model that
+     * actually serves the request. The host emits only decision metadata via
+     * `onShadowRouted`; it never persists prompt content or makes a second call.
+     */
+    shadow?: {
+        strategy: "rules" | "portfolio";
+        sampleRate?: number;
+    };
+    /** Calibratable local portfolio scoring weights; values are relative, not probabilities. */
+    portfolio?: {
+        auto: {
+            quality: number;
+            capability: number;
+            cost: number;
+            speed: number;
+            reliability: number;
+            legacy: number;
+        };
+        eco: {
+            quality: number;
+            capability: number;
+            cost: number;
+            speed: number;
+            reliability: number;
+            legacy: number;
+        };
+        premium: {
+            quality: number;
+            capability: number;
+            cost: number;
+            speed: number;
+            reliability: number;
+            legacy: number;
+        };
+        highStakesBoost: {
+            quality: number;
+            reliability: number;
+        };
+        latencySensitiveSpeedBoost: number;
+        /** A candidate materially below the best task affinity cannot win on cost alone. */
+        affinityFloorGap: {
+            auto: number;
+            eco: number;
+            premium: number;
+        };
+    };
+    classifier: ClassifierConfig;
+    scoring: ScoringConfig;
+    tiers: Record<Tier, TierConfig>;
+    /**
+     * Tier configs for agentic mode — models that excel at multi-step tasks.
+     * Set to `null` to disable agentic tier selection entirely (forces all
+     * requests through `tiers`, even when tools are present in the request).
+     */
+    agenticTiers?: Record<Tier, TierConfig> | null;
+    /** Tier configs for eco profile — ultra cost-optimized (blockrun/eco). `null` falls back to `tiers`. */
+    ecoTiers?: Record<Tier, TierConfig> | null;
+    /** Tier configs for premium profile — best quality (blockrun/premium). `null` falls back to `tiers`. */
+    premiumTiers?: Record<Tier, TierConfig> | null;
+    /** Time-windowed promotions that temporarily override tier routing */
+    promotions?: Promotion[];
+    overrides: OverridesConfig;
+};
+
 /**
  * Type definitions for BlockRun LLM SDK
  */
+
 interface FunctionDefinition {
     name: string;
     description?: string;
@@ -313,24 +488,21 @@ interface ChatCompletionOptions {
     fallbackModels?: string[];
 }
 type RoutingProfile = "eco" | "auto" | "premium";
-type RoutingTier = "SIMPLE" | "MEDIUM" | "COMPLEX" | "REASONING";
-interface RoutingDecision {
-    model: string;
-    tier: RoutingTier;
-    confidence: number;
-    method: "rules" | "llm";
-    reasoning: string;
-    costEstimate: number;
-    baselineCost: number;
-    savings: number;
-    /** Routing profile applied by clawrouter (may include "agentic" on gateway responses). */
-    profile?: RoutingProfile | "agentic";
-    /** Score used when agentic routing is active. */
-    agenticScore?: number;
+type RoutingTier = Tier;
+/**
+ * Request classification produced by the portfolio router (ClawRouter
+ * v0.12.242+, Router v3.4). Present on decisions with `method: "portfolio"`.
+ */
+type RoutingTaskType = TaskType;
+/** Primary model + ordered fallbacks for one routing tier. */
+type RoutingTierConfig = RoutingConfig["tiers"][Tier];
+interface RoutingDecision extends RoutingDecision$1 {
     /**
-     * Remaining tier models with known pricing, in fallback order. `chat()`
-     * walks this list when the primary model hits a transient error
-     * (timeout, network, 5xx). Excludes the primary itself.
+     * Remaining gateway-callable models, in the router's ranked order.
+     * `chat()` walks this list when the primary model hits a transient error
+     * (timeout, network, 429, 5xx). Excludes the primary itself. ClawRouter's
+     * proxy-namespace `free/*` ids appear here as their `nvidia/*` gateway
+     * ids (or are dropped when the mapping is proxy-only).
      */
     fallbacks?: string[];
 }
@@ -1023,8 +1195,11 @@ declare class LLMClient {
     /**
      * Smart chat with automatic model routing.
      *
-     * Uses ClawRouter's 14-dimension rule-based scoring algorithm (<1ms, 100% local)
-     * to select the cheapest model that can handle your request.
+     * Uses ClawRouter's deterministic portfolio router (Router v3.4, the Auto
+     * default since v0.12.242): it classifies the task shape locally (<1ms, no
+     * extra model call), enforces capability constraints as hard filters, and
+     * ranks an ordered candidate portfolio — the cheapest model that can handle
+     * the request wins, and the rest become the transient-error fallback chain.
      *
      * @param prompt - User message
      * @param options - Optional chat and routing parameters
@@ -1034,7 +1209,8 @@ declare class LLMClient {
      * ```ts
      * const result = await client.smartChat('What is 2+2?');
      * console.log(result.response); // '4'
-     * console.log(result.model); // 'google/gemini-2.5-flash-lite'
+     * console.log(result.model); // 'google/gemini-3.5-flash'
+     * console.log(result.routing.method); // 'portfolio'
      * console.log(result.routing.savings); // 0.78 (78% savings)
      * ```
      *
@@ -3238,4 +3414,4 @@ declare function validateTemperature(temperature?: number): void;
  */
 declare function validateTopP(topP?: number): void;
 
-export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, NETWORK_ALIASES, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, RPC_PRICE_USD, type ResponseFormat, RetiredEndpointError, type RoutingDecision, type RoutingProfile, type RoutingTier, type RpcBatchRequest, RpcClient, type RpcClientOptions, type RpcError, type RpcNetwork, type RpcResponse, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SUPPORTED_NETWORKS, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type SoundEffectOptions, type SpeechAudio, SpeechClient, type SpeechClientOptions, type SpeechGenerateOptions, type SpeechModel, type SpeechResponse, type SpeechVoice, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoiceInfo, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, importSolanaWallet, importWallet, listDiscoveredSolanaWallets, listDiscoveredWallets, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, validateMaxTokens, validateModel, validateTemperature, validateTopP };
+export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, NETWORK_ALIASES, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, RPC_PRICE_USD, type ResponseFormat, RetiredEndpointError, type RoutingDecision, type RoutingProfile, type RoutingTaskType, type RoutingTier, type RoutingTierConfig, type RpcBatchRequest, RpcClient, type RpcClientOptions, type RpcError, type RpcNetwork, type RpcResponse, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SUPPORTED_NETWORKS, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type SoundEffectOptions, type SpeechAudio, SpeechClient, type SpeechClientOptions, type SpeechGenerateOptions, type SpeechModel, type SpeechResponse, type SpeechVoice, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoiceInfo, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, importSolanaWallet, importWallet, listDiscoveredSolanaWallets, listDiscoveredWallets, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, validateMaxTokens, validateModel, validateTemperature, validateTopP };

package/dist/index.js

@@ -494,14 +494,14 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.10.0";
+var SDK_VERSION = "3.11.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
 function isTransientError(err) {
   if (err instanceof PaymentError) return false;
   if (err instanceof APIError) {
-    return [502, 503, 504, 522, 524].includes(err.statusCode);
+    return [429, 502, 503, 504, 522, 524].includes(err.statusCode);
   }
   if (err instanceof Error) {
     if (err.name === "AbortError") return true;
@@ -628,8 +628,11 @@ var LLMClient = class _LLMClient {
   /**
    * Smart chat with automatic model routing.
    *
-   * Uses ClawRouter's 14-dimension rule-based scoring algorithm (<1ms, 100% local)
-   * to select the cheapest model that can handle your request.
+   * Uses ClawRouter's deterministic portfolio router (Router v3.4, the Auto
+   * default since v0.12.242): it classifies the task shape locally (<1ms, no
+   * extra model call), enforces capability constraints as hard filters, and
+   * ranks an ordered candidate portfolio — the cheapest model that can handle
+   * the request wins, and the rest become the transient-error fallback chain.
    *
    * @param prompt - User message
    * @param options - Optional chat and routing parameters
@@ -639,7 +642,8 @@ var LLMClient = class _LLMClient {
    * ```ts
    * const result = await client.smartChat('What is 2+2?');
    * console.log(result.response); // '4'
-   * console.log(result.model); // 'google/gemini-2.5-flash-lite'
+   * console.log(result.model); // 'google/gemini-3.5-flash'
+   * console.log(result.routing.method); // 'portfolio'
    * console.log(result.routing.savings); // 0.78 (78% savings)
    * ```
    *
@@ -671,11 +675,15 @@ var LLMClient = class _LLMClient {
       routingProfile: options?.routingProfile
     });
     const tierConfigs = decision.tierConfigs ?? DEFAULT_ROUTING_CONFIG.tiers;
-    const fullChain = getFallbackChain(decision.tier, tierConfigs);
-    const fallbacks = fullChain.filter(
-      (id) => id !== decision.model && modelPricing.has(id)
-    );
-    const response = await this.chat(decision.model, prompt, {
+    const ranked = decision.candidates?.length ? decision.candidates : [decision.model, ...getFallbackChain(decision.tier, tierConfigs)];
+    const callable = [];
+    for (const id of ranked) {
+      const resolved = !id.startsWith("free/") ? id : modelPricing.has(`nvidia/${id.slice(5)}`) ? `nvidia/${id.slice(5)}` : null;
+      if (resolved && !callable.includes(resolved)) callable.push(resolved);
+    }
+    const primary = callable[0] ?? decision.model;
+    const fallbacks = callable.slice(1);
+    const response = await this.chat(primary, prompt, {
       system: options?.system,
       maxTokens: options?.maxTokens,
       temperature: options?.temperature,
@@ -688,8 +696,8 @@ var LLMClient = class _LLMClient {
     });
     return {
       response,
-      model: decision.model,
-      routing: { ...decision, fallbacks }
+      model: primary,
+      routing: { ...decision, model: primary, fallbacks }
     };
   }
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/llm",
-  "version": "3.10.0",
+  "version": "3.11.0",
   "type": "module",
   "description": "BlockRun SDK - Pay-per-request AI (LLM, Image, Video, Music, Voice) via x402 on Base and Solana",
   "main": "dist/index.cjs",
@@ -18,8 +18,8 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts --clean --external @blockrun/clawrouter --external @anthropic-ai/sdk --external @solana/web3.js --external @solana/spl-token --external bs58",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch --external @blockrun/clawrouter --external @anthropic-ai/sdk --external @solana/web3.js --external @solana/spl-token --external bs58",
+    "build": "tsup",
+    "dev": "tsup --watch",
     "test": "vitest",
     "lint": "eslint src/",
     "typecheck": "tsc --noEmit"
@@ -55,6 +55,8 @@
     "@anthropic-ai/sdk": "^0.39.0"
   },
   "devDependencies": {
+    "@blockrun/clawrouter": "^0.12.244",
+    "@blockrun/router-core": "https://codeload.github.com/BlockRunAI/router-core/tar.gz/6a790ebec60161825bbc8c4093fd221006b4e5fb",
     "@eslint/js": "^9.39.4",
     "@types/node": "^20.19.41",
     "eslint": "^9.39.4",
@@ -75,7 +77,7 @@
   },
   "packageManager": "pnpm@9.15.4",
   "peerDependencies": {
-    "@blockrun/clawrouter": "^0.12.222",
+    "@blockrun/clawrouter": "^0.12.242",
     "@solana/spl-token": "^0.4.14",
     "@solana/web3.js": "^1.98.4"
   },