@blockrun/llm 0.3.0 → 1.0.0

package/README.md

@@ -59,12 +59,10 @@ For Solana, set `BLOCKRUN_SOLANA_KEY` environment variable with your base58-enco
 | Model | Input Price | Output Price |
 |-------|-------------|--------------|
 | `openai/gpt-5.2` | $1.75/M | $14.00/M |
-| `openai/gpt-5.1` | $1.25/M | $10.00/M |
-| `openai/gpt-5` | $1.25/M | $10.00/M |
 | `openai/gpt-5-mini` | $0.25/M | $2.00/M |
 | `openai/gpt-5-nano` | $0.05/M | $0.40/M |
 | `openai/gpt-5.2-pro` | $21.00/M | $168.00/M |
-| `openai/gpt-5-pro` | $15.00/M | $120.00/M |
+| `openai/gpt-5.2-codex` | $1.75/M | $14.00/M |
 
 ### OpenAI GPT-4 Family
 | Model | Input Price | Output Price |
@@ -87,7 +85,10 @@ For Solana, set `BLOCKRUN_SOLANA_KEY` environment variable with your base58-enco
 ### Anthropic Claude
 | Model | Input Price | Output Price |
 |-------|-------------|--------------|
+| `anthropic/claude-opus-4.6` | $5.00/M | $25.00/M |
+| `anthropic/claude-opus-4.5` | $5.00/M | $25.00/M |
 | `anthropic/claude-opus-4` | $15.00/M | $75.00/M |
+| `anthropic/claude-sonnet-4.6` | $3.00/M | $15.00/M |
 | `anthropic/claude-sonnet-4` | $3.00/M | $15.00/M |
 | `anthropic/claude-haiku-4.5` | $1.00/M | $5.00/M |
 
@@ -96,7 +97,7 @@ For Solana, set `BLOCKRUN_SOLANA_KEY` environment variable with your base58-enco
 |-------|-------------|--------------|
 | `google/gemini-3-pro-preview` | $2.00/M | $12.00/M |
 | `google/gemini-2.5-pro` | $1.25/M | $10.00/M |
-| `google/gemini-2.5-flash` | $0.15/M | $0.60/M |
+| `google/gemini-2.5-flash` | $0.30/M | $2.50/M |
 
 ### DeepSeek
 | Model | Input Price | Output Price |
@@ -105,17 +106,29 @@ For Solana, set `BLOCKRUN_SOLANA_KEY` environment variable with your base58-enco
 | `deepseek/deepseek-reasoner` | $0.28/M | $0.42/M |
 
 ### xAI Grok
-| Model | Input Price | Output Price |
-|-------|-------------|--------------|
-| `xai/grok-3` | $3.00/M | $15.00/M |
-| `xai/grok-3-fast` | $5.00/M | $25.00/M |
-| `xai/grok-3-mini` | $0.30/M | $0.50/M |
+| Model | Input Price | Output Price | Context | Notes |
+|-------|-------------|--------------|---------|-------|
+| `xai/grok-3` | $3.00/M | $15.00/M | 131K | Flagship |
+| `xai/grok-3-mini` | $0.30/M | $0.50/M | 131K | Fast & affordable |
+| `xai/grok-4-1-fast-reasoning` | $0.20/M | $0.50/M | **2M** | Latest, chain-of-thought |
+| `xai/grok-4-1-fast-non-reasoning` | $0.20/M | $0.50/M | **2M** | Latest, direct response |
+| `xai/grok-4-fast-reasoning` | $0.20/M | $0.50/M | **2M** | Step-by-step reasoning |
+| `xai/grok-4-fast-non-reasoning` | $0.20/M | $0.50/M | **2M** | Quick responses |
+| `xai/grok-code-fast-1` | $0.20/M | $1.50/M | 256K | Code generation |
+| `xai/grok-4-0709` | $0.20/M | $1.50/M | 256K | Premium quality |
+| `xai/grok-2-vision` | $2.00/M | $10.00/M | 32K | Vision capabilities |
 
 ### Moonshot Kimi
 | Model | Input Price | Output Price |
 |-------|-------------|--------------|
 | `moonshot/kimi-k2.5` | $0.60/M | $3.00/M |
 
+### NVIDIA (Free & Hosted)
+| Model | Input Price | Output Price | Notes |
+|-------|-------------|--------------|-------|
+| `nvidia/gpt-oss-120b` | **FREE** | **FREE** | OpenAI open-weight 120B (Apache 2.0) |
+| `nvidia/kimi-k2.5` | $0.60/M | $3.00/M | Moonshot 1T MoE with vision |
+
 ### E2E Verified Models
 
 All models below have been tested end-to-end via the TypeScript SDK (Feb 2026):
@@ -123,10 +136,12 @@ All models below have been tested end-to-end via the TypeScript SDK (Feb 2026):
 | Provider | Model | Status |
 |----------|-------|--------|
 | OpenAI | `openai/gpt-4o-mini` | Passed |
+| OpenAI | `openai/gpt-5.2-codex` | Passed |
+| Anthropic | `anthropic/claude-opus-4.6` | Passed |
 | Anthropic | `anthropic/claude-sonnet-4` | Passed |
 | Google | `google/gemini-2.5-flash` | Passed |
 | DeepSeek | `deepseek/deepseek-chat` | Passed |
-| xAI | `xai/grok-3-fast` | Passed |
+| xAI | `xai/grok-3` | Passed |
 | Moonshot | `moonshot/kimi-k2.5` | Passed |
 
 ### Image Generation
@@ -206,6 +221,47 @@ const response2 = await client.chat('anthropic/claude-sonnet-4', 'Write a haiku'
 });
 ```
 
+### Smart Routing (ClawRouter)
+
+Save up to 78% on inference costs with intelligent model routing. ClawRouter uses a 14-dimension rule-based scoring algorithm to select the cheapest model that can handle your request (<1ms, 100% local).
+
+```typescript
+import { LLMClient } from '@blockrun/llm';
+
+const client = new LLMClient();
+
+// Auto-route to cheapest capable model
+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 78%'
+
+// Routing profiles
+const free = await client.smartChat('Hello!', { routingProfile: 'free' });     // Zero cost
+const eco = await client.smartChat('Explain AI', { routingProfile: 'eco' });   // Budget optimized
+const auto = await client.smartChat('Code review', { routingProfile: 'auto' }); // Balanced (default)
+const premium = await client.smartChat('Write a legal brief', { routingProfile: 'premium' }); // Best quality
+```
+
+**Routing Profiles:**
+
+| Profile | Description | Best For |
+|---------|-------------|----------|
+| `free` | NVIDIA free models only | Testing, simple queries |
+| `eco` | Budget-optimized | Cost-sensitive workloads |
+| `auto` | Intelligent routing (default) | General use |
+| `premium` | Best quality models | Critical tasks |
+
+**Tiers:**
+
+| Tier | Example Tasks | Typical Models |
+|------|---------------|----------------|
+| SIMPLE | Greetings, math, lookups | Gemini Flash, GPT-4o-mini |
+| MEDIUM | Explanations, summaries | GPT-4o, Claude Sonnet |
+| COMPLEX | Analysis, code generation | GPT-5.2, Claude Opus |
+| REASONING | Multi-step logic, planning | o3, DeepSeek Reasoner |
+
 ### Full Chat Completion
 
 ```typescript
@@ -389,6 +445,12 @@ import {
   type ChatResponse,
   type ChatOptions,
   type Model,
+  // Smart routing types
+  type SmartChatOptions,
+  type SmartChatResponse,
+  type RoutingDecision,
+  type RoutingProfile,
+  type RoutingTier,
   APIError,
   PaymentError,
 } from '@blockrun/llm';
@@ -397,9 +459,9 @@ import {
 ## Links
 
 - [Website](https://blockrun.ai)
-- [Documentation](https://docs.blockrun.ai)
-- [GitHub](https://github.com/blockrun/blockrun-llm-ts)
-- [Discord](https://discord.gg/blockrun)
+- [Documentation](https://github.com/BlockRunAI/awesome-blockrun/tree/main/docs)
+- [GitHub](https://github.com/blockrunai/blockrun-llm-ts)
+- [Telegram](https://t.me/+mroQv4-4hGgzOGUx)
 
 ## License
 

package/dist/index.cjs

@@ -83,6 +83,9 @@ var APIError = class extends BlockrunError {
   }
 };
 
+// src/client.ts
+var import_clawrouter = require("@blockrun/clawrouter");
+
 // src/x402.ts
 var import_accounts = require("viem/accounts");
 var BASE_CHAIN_ID = 8453;
@@ -293,6 +296,8 @@ var LLMClient = class {
   timeout;
   sessionTotalUsd = 0;
   sessionCalls = 0;
+  modelPricingCache = null;
+  modelPricingPromise = null;
   /**
    * Initialize the BlockRun LLM client.
    *
@@ -341,6 +346,91 @@ var LLMClient = class {
     });
     return result.choices[0].message.content || "";
   }
+  /**
+   * 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.
+   *
+   * @param prompt - User message
+   * @param options - Optional chat and routing parameters
+   * @returns SmartChatResponse with response text, selected model, and routing metadata
+   *
+   * @example Simple usage (auto profile)
+   * ```ts
+   * 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.savings); // 0.78 (78% savings)
+   * ```
+   *
+   * @example With routing profile
+   * ```ts
+   * // Free tier only (zero cost)
+   * const result = await client.smartChat('Hello!', { routingProfile: 'free' });
+   *
+   * // Eco mode (budget optimized)
+   * const result = await client.smartChat('Explain quantum computing', { routingProfile: 'eco' });
+   *
+   * // Premium mode (best quality)
+   * const result = await client.smartChat('Write a business plan', { routingProfile: 'premium' });
+   * ```
+   */
+  async smartChat(prompt, options) {
+    const modelPricing = await this.getModelPricing();
+    const maxOutputTokens = options?.maxOutputTokens || options?.maxTokens || 1024;
+    const decision = (0, import_clawrouter.route)(prompt, options?.system, maxOutputTokens, {
+      config: import_clawrouter.DEFAULT_ROUTING_CONFIG,
+      modelPricing,
+      routingProfile: options?.routingProfile
+    });
+    const response = await this.chat(decision.model, prompt, {
+      system: options?.system,
+      maxTokens: options?.maxTokens,
+      temperature: options?.temperature,
+      topP: options?.topP,
+      search: options?.search,
+      searchParameters: options?.searchParameters
+    });
+    return {
+      response,
+      model: decision.model,
+      routing: decision
+    };
+  }
+  /**
+   * Get model pricing map (cached).
+   * Fetches from API on first call, then returns cached result.
+   */
+  async getModelPricing() {
+    if (this.modelPricingCache) {
+      return this.modelPricingCache;
+    }
+    if (this.modelPricingPromise) {
+      return this.modelPricingPromise;
+    }
+    this.modelPricingPromise = this.fetchModelPricing();
+    try {
+      this.modelPricingCache = await this.modelPricingPromise;
+      return this.modelPricingCache;
+    } finally {
+      this.modelPricingPromise = null;
+    }
+  }
+  /**
+   * Fetch model pricing from API.
+   */
+  async fetchModelPricing() {
+    const models = await this.listModels();
+    const pricing = /* @__PURE__ */ new Map();
+    for (const model of models) {
+      pricing.set(model.id, {
+        inputPrice: model.inputPrice,
+        outputPrice: model.outputPrice
+      });
+    }
+    return pricing;
+  }
   /**
    * Full chat completion interface (OpenAI-compatible).
    *

package/dist/index.d.cts

@@ -179,6 +179,32 @@ interface ChatCompletionOptions {
     /** Tool selection strategy */
     toolChoice?: ToolChoice;
 }
+type RoutingProfile = "free" | "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;
+}
+interface SmartChatOptions extends ChatOptions {
+    /** Routing profile: free (zero cost), eco (budget), auto (balanced), premium (best quality) */
+    routingProfile?: RoutingProfile;
+    /** Maximum output tokens (used for cost estimation) */
+    maxOutputTokens?: number;
+}
+interface SmartChatResponse {
+    /** The AI response text */
+    response: string;
+    /** Which model was selected by smart routing */
+    model: string;
+    /** Routing decision metadata */
+    routing: RoutingDecision;
+}
 declare class BlockrunError extends Error {
     constructor(message: string);
 }
@@ -240,6 +266,8 @@ declare class LLMClient {
     private timeout;
     private sessionTotalUsd;
     private sessionCalls;
+    private modelPricingCache;
+    private modelPricingPromise;
     /**
      * Initialize the BlockRun LLM client.
      *
@@ -259,6 +287,46 @@ declare class LLMClient {
      * console.log(response); // 'The capital of France is Paris.'
      */
     chat(model: string, prompt: string, options?: ChatOptions): Promise<string>;
+    /**
+     * 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.
+     *
+     * @param prompt - User message
+     * @param options - Optional chat and routing parameters
+     * @returns SmartChatResponse with response text, selected model, and routing metadata
+     *
+     * @example Simple usage (auto profile)
+     * ```ts
+     * 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.savings); // 0.78 (78% savings)
+     * ```
+     *
+     * @example With routing profile
+     * ```ts
+     * // Free tier only (zero cost)
+     * const result = await client.smartChat('Hello!', { routingProfile: 'free' });
+     *
+     * // Eco mode (budget optimized)
+     * const result = await client.smartChat('Explain quantum computing', { routingProfile: 'eco' });
+     *
+     * // Premium mode (best quality)
+     * const result = await client.smartChat('Write a business plan', { routingProfile: 'premium' });
+     * ```
+     */
+    smartChat(prompt: string, options?: SmartChatOptions): Promise<SmartChatResponse>;
+    /**
+     * Get model pricing map (cached).
+     * Fetches from API on first call, then returns cached result.
+     */
+    private getModelPricing;
+    /**
+     * Fetch model pricing from API.
+     */
+    private fetchModelPricing;
     /**
      * Full chat completion interface (OpenAI-compatible).
      *
@@ -673,4 +741,4 @@ declare class OpenAI {
     getWalletAddress(): string;
 }
 
-export { APIError, BASE_CHAIN_ID, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatUsage, type FunctionCall, type FunctionDefinition, ImageClient, type ImageClientOptions, type ImageData, type ImageGenerateOptions, type ImageModel, type ImageResponse, LLMClient, type LLMClientOptions, type Model, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PaymentError, type PaymentLinks, type RssSearchSource, type SearchParameters, type SearchSource, type Spending, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, createWallet, LLMClient as default, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getEip681Uri, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadWallet, saveWallet, testnetClient };
+export { APIError, BASE_CHAIN_ID, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatUsage, type FunctionCall, type FunctionDefinition, ImageClient, type ImageClientOptions, type ImageData, type ImageGenerateOptions, type ImageModel, type ImageResponse, LLMClient, type LLMClientOptions, type Model, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PaymentError, type PaymentLinks, type RoutingDecision, type RoutingProfile, type RoutingTier, type RssSearchSource, type SearchParameters, type SearchSource, type SmartChatOptions, type SmartChatResponse, type Spending, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, createWallet, LLMClient as default, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getEip681Uri, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadWallet, saveWallet, testnetClient };

package/dist/index.d.ts

@@ -179,6 +179,32 @@ interface ChatCompletionOptions {
     /** Tool selection strategy */
     toolChoice?: ToolChoice;
 }
+type RoutingProfile = "free" | "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;
+}
+interface SmartChatOptions extends ChatOptions {
+    /** Routing profile: free (zero cost), eco (budget), auto (balanced), premium (best quality) */
+    routingProfile?: RoutingProfile;
+    /** Maximum output tokens (used for cost estimation) */
+    maxOutputTokens?: number;
+}
+interface SmartChatResponse {
+    /** The AI response text */
+    response: string;
+    /** Which model was selected by smart routing */
+    model: string;
+    /** Routing decision metadata */
+    routing: RoutingDecision;
+}
 declare class BlockrunError extends Error {
     constructor(message: string);
 }
@@ -240,6 +266,8 @@ declare class LLMClient {
     private timeout;
     private sessionTotalUsd;
     private sessionCalls;
+    private modelPricingCache;
+    private modelPricingPromise;
     /**
      * Initialize the BlockRun LLM client.
      *
@@ -259,6 +287,46 @@ declare class LLMClient {
      * console.log(response); // 'The capital of France is Paris.'
      */
     chat(model: string, prompt: string, options?: ChatOptions): Promise<string>;
+    /**
+     * 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.
+     *
+     * @param prompt - User message
+     * @param options - Optional chat and routing parameters
+     * @returns SmartChatResponse with response text, selected model, and routing metadata
+     *
+     * @example Simple usage (auto profile)
+     * ```ts
+     * 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.savings); // 0.78 (78% savings)
+     * ```
+     *
+     * @example With routing profile
+     * ```ts
+     * // Free tier only (zero cost)
+     * const result = await client.smartChat('Hello!', { routingProfile: 'free' });
+     *
+     * // Eco mode (budget optimized)
+     * const result = await client.smartChat('Explain quantum computing', { routingProfile: 'eco' });
+     *
+     * // Premium mode (best quality)
+     * const result = await client.smartChat('Write a business plan', { routingProfile: 'premium' });
+     * ```
+     */
+    smartChat(prompt: string, options?: SmartChatOptions): Promise<SmartChatResponse>;
+    /**
+     * Get model pricing map (cached).
+     * Fetches from API on first call, then returns cached result.
+     */
+    private getModelPricing;
+    /**
+     * Fetch model pricing from API.
+     */
+    private fetchModelPricing;
     /**
      * Full chat completion interface (OpenAI-compatible).
      *
@@ -673,4 +741,4 @@ declare class OpenAI {
     getWalletAddress(): string;
 }
 
-export { APIError, BASE_CHAIN_ID, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatUsage, type FunctionCall, type FunctionDefinition, ImageClient, type ImageClientOptions, type ImageData, type ImageGenerateOptions, type ImageModel, type ImageResponse, LLMClient, type LLMClientOptions, type Model, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PaymentError, type PaymentLinks, type RssSearchSource, type SearchParameters, type SearchSource, type Spending, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, createWallet, LLMClient as default, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getEip681Uri, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadWallet, saveWallet, testnetClient };
+export { APIError, BASE_CHAIN_ID, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatUsage, type FunctionCall, type FunctionDefinition, ImageClient, type ImageClientOptions, type ImageData, type ImageGenerateOptions, type ImageModel, type ImageResponse, LLMClient, type LLMClientOptions, type Model, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PaymentError, type PaymentLinks, type RoutingDecision, type RoutingProfile, type RoutingTier, type RssSearchSource, type SearchParameters, type SearchSource, type SmartChatOptions, type SmartChatResponse, type Spending, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, createWallet, LLMClient as default, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getEip681Uri, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadWallet, saveWallet, testnetClient };

package/dist/index.js

@@ -27,6 +27,9 @@ var APIError = class extends BlockrunError {
   }
 };
 
+// src/client.ts
+import { route, DEFAULT_ROUTING_CONFIG } from "@blockrun/clawrouter";
+
 // src/x402.ts
 import { signTypedData } from "viem/accounts";
 var BASE_CHAIN_ID = 8453;
@@ -237,6 +240,8 @@ var LLMClient = class {
   timeout;
   sessionTotalUsd = 0;
   sessionCalls = 0;
+  modelPricingCache = null;
+  modelPricingPromise = null;
   /**
    * Initialize the BlockRun LLM client.
    *
@@ -285,6 +290,91 @@ var LLMClient = class {
     });
     return result.choices[0].message.content || "";
   }
+  /**
+   * 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.
+   *
+   * @param prompt - User message
+   * @param options - Optional chat and routing parameters
+   * @returns SmartChatResponse with response text, selected model, and routing metadata
+   *
+   * @example Simple usage (auto profile)
+   * ```ts
+   * 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.savings); // 0.78 (78% savings)
+   * ```
+   *
+   * @example With routing profile
+   * ```ts
+   * // Free tier only (zero cost)
+   * const result = await client.smartChat('Hello!', { routingProfile: 'free' });
+   *
+   * // Eco mode (budget optimized)
+   * const result = await client.smartChat('Explain quantum computing', { routingProfile: 'eco' });
+   *
+   * // Premium mode (best quality)
+   * const result = await client.smartChat('Write a business plan', { routingProfile: 'premium' });
+   * ```
+   */
+  async smartChat(prompt, options) {
+    const modelPricing = await this.getModelPricing();
+    const maxOutputTokens = options?.maxOutputTokens || options?.maxTokens || 1024;
+    const decision = route(prompt, options?.system, maxOutputTokens, {
+      config: DEFAULT_ROUTING_CONFIG,
+      modelPricing,
+      routingProfile: options?.routingProfile
+    });
+    const response = await this.chat(decision.model, prompt, {
+      system: options?.system,
+      maxTokens: options?.maxTokens,
+      temperature: options?.temperature,
+      topP: options?.topP,
+      search: options?.search,
+      searchParameters: options?.searchParameters
+    });
+    return {
+      response,
+      model: decision.model,
+      routing: decision
+    };
+  }
+  /**
+   * Get model pricing map (cached).
+   * Fetches from API on first call, then returns cached result.
+   */
+  async getModelPricing() {
+    if (this.modelPricingCache) {
+      return this.modelPricingCache;
+    }
+    if (this.modelPricingPromise) {
+      return this.modelPricingPromise;
+    }
+    this.modelPricingPromise = this.fetchModelPricing();
+    try {
+      this.modelPricingCache = await this.modelPricingPromise;
+      return this.modelPricingCache;
+    } finally {
+      this.modelPricingPromise = null;
+    }
+  }
+  /**
+   * Fetch model pricing from API.
+   */
+  async fetchModelPricing() {
+    const models = await this.listModels();
+    const pricing = /* @__PURE__ */ new Map();
+    for (const model of models) {
+      pricing.set(model.id, {
+        inputPrice: model.inputPrice,
+        outputPrice: model.outputPrice
+      });
+    }
+    return pricing;
+  }
   /**
    * Full chat completion interface (OpenAI-compatible).
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/llm",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "type": "module",
   "description": "BlockRun LLM Gateway SDK - Pay-per-request AI via x402 on Base",
   "main": "dist/index.cjs",
@@ -48,6 +48,7 @@
     "url": "https://github.com/BlockRunAI/blockrun-llm-ts/issues"
   },
   "dependencies": {
+    "@blockrun/clawrouter": "^0.9.3",
     "viem": "^2.21.0"
   },
   "optionalDependencies": {