@blockrun/llm 3.9.0 → 3.11.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;
@@ -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[];
 }
@@ -947,6 +1119,16 @@ interface PollOptions {
 declare class BlockrunError extends Error {
     constructor(message: string);
 }
+/**
+ * Thrown by a helper whose upstream endpoint no longer exists.
+ *
+ * Kept as a throwing method rather than deleted so upgrading does not break
+ * imports or property access — the failure is explicit and immediate instead of
+ * a round trip that returns 410/404.
+ */
+declare class RetiredEndpointError extends BlockrunError {
+    constructor(message: string);
+}
 declare class PaymentError extends BlockrunError {
     constructor(message: string);
 }
@@ -1013,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
@@ -1024,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)
      * ```
      *
@@ -1284,25 +1470,43 @@ declare class LLMClient {
      * });
      */
     pmQuery(path: string, query: Record<string, unknown>): Promise<Record<string, unknown>>;
-    /** List canonical cross-venue markets (Predexon v2). Tier 1 ($0.001/call).
-     * Filter with venue, status, category, league, event_id, pagination_key. */
-    pmMarkets(params?: Record<string, string>): Promise<Record<string, unknown>>;
-    /** List venue-native executable listings flattened across canonical markets
-     * (Predexon v2). Tier 1 ($0.001/call). */
-    pmListings(params?: Record<string, string>): Promise<Record<string, unknown>>;
-    /** Resolve a canonical Predexon outcome ID to its market context and venue
-     * listings. Tier 1 ($0.001/call). */
-    pmOutcome(predexonId: string): Promise<Record<string, unknown>>;
+    /** RETIRED — `/v1/pm/markets` no longer exists.
+     *
+     * Predexon sunset market matching on 2026-07-20 and the whole canonical layer
+     * went with it, so this path returns 410 upstream. Use
+     * `pm("markets/search", { q })` for cross-venue lookups.
+     *
+     * Kept as a throwing stub rather than deleted so upgrading does not break
+     * property access; it throws before any network I/O.
+     *
+     * @throws {RetiredEndpointError} always. */
+    pmMarkets(_params?: Record<string, string>): Promise<Record<string, unknown>>;
+    /** RETIRED — `/v1/pm/markets/listings` no longer exists (410, sunset
+     * 2026-07-20 with market matching). Use `pm("markets/search", { q })`.
+     *
+     * @throws {RetiredEndpointError} always. */
+    pmListings(_params?: Record<string, string>): Promise<Record<string, unknown>>;
+    /** RETIRED — `/v1/pm/outcomes/{predexonId}` no longer exists (410, sunset
+     * 2026-07-20 with market matching). Use `pm("markets/search", { q })`.
+     *
+     * @throws {RetiredEndpointError} always. */
+    pmOutcome(_predexonId: string): Promise<Record<string, unknown>>;
     /** Polymarket markets with cursor-based keyset pagination (use pagination_key).
      * Tier 1 ($0.001/call). */
     pmPolymarketMarketsKeyset(params?: Record<string, string>): Promise<Record<string, unknown>>;
     /** Polymarket events with cursor-based keyset pagination (use pagination_key).
      * Tier 1 ($0.001/call). */
     pmPolymarketEventsKeyset(params?: Record<string, string>): Promise<Record<string, unknown>>;
-    /** List available sports categories. Tier 1 ($0.001/call). */
+    /** List available sports categories. Tier 1 ($0.001/call).
+     *
+     * NOTE: upstream returns 500 for every `sports/*` path as of 2026-08-04.
+     * The route still resolves, so this works again the moment Predexon restores
+     * it, but do not build on it yet. */
     pmSportsCategories(): Promise<Record<string, unknown>>;
     /** List sports markets grouped by game. Filter with league, sport_type,
-     * status, venue. Tier 1 ($0.001/call). */
+     * status, venue. Tier 1 ($0.001/call).
+     *
+     * NOTE: upstream returns 500 for every `sports/*` path as of 2026-08-04. */
     pmSportsMarkets(params?: Record<string, string>): Promise<Record<string, unknown>>;
     /** Fetch identity + profile metadata for one wallet (ENS, Twitter, portfolio,
      * etc.). Tier 2 ($0.005/call). */
@@ -3210,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, 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 };