@blockrun/llm 3.10.0 → 3.12.0

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;
@@ -77,6 +252,8 @@ interface ChatResponse {
         model?: string;
         settlementSkipped?: boolean;
     };
+    /** Present when a `blockrun/auto|eco|premium` alias selected the model locally. */
+    routing?: RoutingDecision;
 }
 interface Model {
     id: string;
@@ -313,24 +490,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 bundled Router Core V3 portfolio
+ * router. 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. The router's
+     * proxy-namespace `free/*` ids appear here as their `nvidia/*` gateway
+     * ids (or are dropped when the mapping is proxy-only).
      */
     fallbacks?: string[];
 }
@@ -340,6 +514,12 @@ interface SmartChatOptions extends ChatOptions {
     /** Maximum output tokens (used for cost estimation) */
     maxOutputTokens?: number;
 }
+interface SmartChatCompletionOptions extends ChatCompletionOptions {
+    /** Routing profile: eco (budget), auto (balanced), premium (best quality) */
+    routingProfile?: RoutingProfile;
+    /** Maximum output tokens used for route cost/capacity estimation. */
+    maxOutputTokens?: number;
+}
 interface SmartChatResponse {
     /** The AI response text */
     response: string;
@@ -348,6 +528,14 @@ interface SmartChatResponse {
     /** Routing decision metadata */
     routing: RoutingDecision;
 }
+interface SmartChatCompletionResponse {
+    /** Full OpenAI-compatible response, including tool calls. */
+    response: ChatResponse;
+    /** Model selected before any transient runtime fallback. */
+    model: string;
+    /** Local routing decision and ordered fallback candidates. */
+    routing: RoutingDecision;
+}
 interface SearchResult {
     query: string;
     summary: string;
@@ -1020,11 +1208,20 @@ declare class LLMClient {
      * console.log(response); // 'The capital of France is Paris.'
      */
     chat(model: string, prompt: string, options?: ChatOptions): Promise<string>;
+    private makeRoutingDecision;
+    /**
+     * Inspect a local routing decision without making or paying for a model call.
+     * The first invocation may fetch the public model catalog for current prices.
+     */
+    route(prompt: string, options?: SmartChatOptions): Promise<RoutingDecision>;
     /**
      * 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 BlockRun's product-neutral Router Core portfolio strategy: it
+     * classifies the task shape locally (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 +1231,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)
      * ```
      *
@@ -1048,21 +1246,14 @@ declare class LLMClient {
      * ```
      */
     smartChat(prompt: string, options?: SmartChatOptions): Promise<SmartChatResponse>;
+    /** Route a full Agent/tool conversation while preserving its complete response. */
+    smartChatCompletion(messages: ChatMessage[], options?: SmartChatCompletionOptions): Promise<SmartChatCompletionResponse>;
     /**
      * Get model pricing map (cached).
      * Fetches from API on first call, then returns cached result.
      */
     private getModelPricing;
-    /**
-     * Fetch model pricing from API.
-     *
-     * For flat-billed models (e.g. ZAI GLM-5 family at $0.001/call) the
-     * router still expects per-token rates, so we synthesise an equivalent
-     * per-token price assuming ~1500 total tokens per call. Without this,
-     * flat models would resolve to inputPrice=outputPrice=0 and the router
-     * would treat them as free, biasing routing decisions and reporting
-     * inflated savings %.
-     */
+    /** Fetch model pricing from the live catalog, preserving flat billing. */
     private fetchModelPricing;
     /**
      * Full chat completion interface (OpenAI-compatible).
@@ -2732,6 +2923,8 @@ declare class SolanaLLMClient {
     private sessionTotalUsd;
     private sessionCalls;
     private addressCache;
+    private modelPricingCache;
+    private modelPricingPromise;
     constructor(options?: SolanaLLMClientOptions);
     /** Get Solana wallet address (public key in base58). */
     getWalletAddress(): Promise<string>;
@@ -2739,6 +2932,13 @@ declare class SolanaLLMClient {
     chat(model: string, prompt: string, options?: ChatOptions): Promise<string>;
     /** Full chat completion (OpenAI-compatible). */
     chatCompletion(model: string, messages: ChatMessage[], options?: ChatCompletionOptions): Promise<ChatResponse>;
+    private getModelPricing;
+    /** Inspect a Solana route without making or paying for a model call. */
+    route(prompt: string, options?: SmartChatOptions): Promise<RoutingDecision>;
+    /** Smart one-line chat paid on Solana. */
+    smartChat(prompt: string, options?: SmartChatOptions): Promise<SmartChatResponse>;
+    /** Smart full message/tool completion paid on Solana. */
+    smartChatCompletion(messages: ChatMessage[], options?: SmartChatCompletionOptions): Promise<SmartChatCompletionResponse>;
     /** List available models. */
     listModels(): Promise<Model[]>;
     /**
@@ -3081,6 +3281,8 @@ interface OpenAIChatCompletionResponse {
         completion_tokens: number;
         total_tokens: number;
     };
+    /** BlockRun extension present when a `blockrun/*` Auto alias was used. */
+    routing?: RoutingDecision;
 }
 interface OpenAIChatCompletionChunk {
     id: string;
@@ -3238,4 +3440,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 SmartChatCompletionOptions, type SmartChatCompletionResponse, 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 };