@blockrun/llm 1.4.3 → 1.6.1

package/dist/index.d.ts

@@ -140,10 +140,48 @@ interface SearchParameters {
     toDate?: string;
     maxSearchResults?: number;
 }
+/** Usage info for Live Search sources */
+interface SearchUsage {
+    /** Number of search sources used in the response */
+    numSourcesUsed?: number;
+}
 interface Spending {
     totalUsd: number;
     calls: number;
 }
+/** Pre-request cost estimate for a chat call */
+interface CostEstimate {
+    /** Model ID used for the estimate */
+    model: string;
+    /** Estimated input token count */
+    estimatedInputTokens: number;
+    /** Estimated output token count */
+    estimatedOutputTokens: number;
+    /** Estimated cost in USD */
+    estimatedCostUsd: number;
+}
+/** Per-call spending report with running session totals */
+interface SpendingReport {
+    /** Model ID used */
+    model: string;
+    /** Input tokens consumed */
+    inputTokens: number;
+    /** Output tokens consumed */
+    outputTokens: number;
+    /** Cost of this call in USD */
+    costUsd: number;
+    /** Cumulative session spend in USD */
+    sessionTotalUsd: number;
+    /** Total number of calls in this session */
+    sessionCalls: number;
+}
+/** Chat response bundled with its spending report */
+interface ChatResponseWithCost {
+    /** The chat completion response */
+    response: ChatResponse;
+    /** Spending report for this call */
+    spendingReport: SpendingReport;
+}
 interface ResourceInfo {
     url: string;
     description?: string;
@@ -184,9 +222,9 @@ interface ChatOptions {
     temperature?: number;
     /** Nucleus sampling parameter */
     topP?: number;
-    /** Enable xAI Live Search (shortcut for searchParameters.mode = "on") */
+    /** Enable Live Search (shortcut for searchParameters.mode = "on") */
     search?: boolean;
-    /** Full xAI Live Search configuration (for Grok models) */
+    /** Full Live Search configuration (for search-enabled models) */
     searchParameters?: SearchParameters;
 }
 interface ChatCompletionOptions {
@@ -196,9 +234,9 @@ interface ChatCompletionOptions {
     temperature?: number;
     /** Nucleus sampling parameter */
     topP?: number;
-    /** Enable xAI Live Search (shortcut for searchParameters.mode = "on") */
+    /** Enable Live Search (shortcut for searchParameters.mode = "on") */
     search?: boolean;
-    /** Full xAI Live Search configuration (for Grok models) */
+    /** Full Live Search configuration (for search-enabled models) */
     searchParameters?: SearchParameters;
     /** Tool definitions for function calling */
     tools?: Tool[];
@@ -258,6 +296,68 @@ interface SearchOptions {
     /** End date filter (YYYY-MM-DD) */
     toDate?: string;
 }
+interface ExaSearchOptions {
+    /** Number of results to return (default: 10, max: 100) */
+    numResults?: number;
+    /** Restrict to a content category */
+    category?: "github" | "news" | "research paper" | "linkedin profile" | "personal site" | "tweet" | "financial report" | "pdf" | "company";
+    /** Only include pages published after this date (ISO 8601) */
+    startPublishedDate?: string;
+    /** Only include pages published before this date (ISO 8601) */
+    endPublishedDate?: string;
+    /** Only search within these domains */
+    includeDomains?: string[];
+    /** Exclude these domains from results */
+    excludeDomains?: string[];
+}
+interface ExaSearchItem {
+    id: string;
+    url: string;
+    title: string;
+    publishedDate?: string;
+    author?: string;
+    score?: number;
+}
+interface ExaSearchResponse {
+    requestId: string;
+    resolvedSearchType: string;
+    results: ExaSearchItem[];
+    searchTime: number;
+    costDollars: {
+        total: number;
+    };
+}
+interface ExaAnswerCitation {
+    id: string;
+    title: string;
+    url: string;
+    publishedDate?: string;
+    favicon?: string;
+}
+interface ExaAnswerResponse {
+    requestId: string;
+    answer: string;
+    citations: ExaAnswerCitation[];
+}
+interface ExaContentItem {
+    id: string;
+    url: string;
+    title: string;
+    text: string;
+    author?: string | null;
+}
+interface ExaContentsResponse {
+    results: ExaContentItem[];
+    costDollars: {
+        total: number;
+    };
+}
+interface ExaFindSimilarOptions {
+    /** Number of results to return (default: 10, max: 100) */
+    numResults?: number;
+    /** Exclude pages from the same domain as the reference URL */
+    excludeSourceDomain?: boolean;
+}
 interface XUser {
     id: string;
     userName: string;
@@ -406,7 +506,7 @@ declare class APIError extends BlockrunError {
  *   // Option 2: Pass private key directly
  *   const client = new LLMClient({ privateKey: '0x...' });
  *
- *   const response = await client.chat('openai/gpt-4o', 'Hello!');
+ *   const response = await client.chat('openai/gpt-5.2', 'Hello!');
  *   console.log(response);
  */
 
@@ -445,6 +545,8 @@ declare class LLMClient {
     private sessionCalls;
     private modelPricingCache;
     private modelPricingPromise;
+    private preAuthCache;
+    private static readonly PRE_AUTH_TTL_MS;
     /**
      * Initialize the BlockRun LLM client.
      *
@@ -454,13 +556,13 @@ declare class LLMClient {
     /**
      * Simple 1-line chat interface.
      *
-     * @param model - Model ID (e.g., 'openai/gpt-4o', 'anthropic/claude-sonnet-4')
+     * @param model - Model ID (e.g., 'openai/gpt-5.2', 'anthropic/claude-sonnet-4.6')
      * @param prompt - User message
      * @param options - Optional chat parameters
      * @returns Assistant's response text
      *
      * @example
-     * const response = await client.chat('gpt-4o', 'What is the capital of France?');
+     * const response = await client.chat('gpt-5.2', 'What is the capital of France?');
      * console.log(response); // 'The capital of France is Paris.'
      */
     chat(model: string, prompt: string, options?: ChatOptions): Promise<string>;
@@ -521,6 +623,21 @@ declare class LLMClient {
      * Handle 402 response: parse requirements, sign payment, retry.
      */
     private handlePaymentAndRetry;
+    /**
+     * Sign a payment header and return the PAYMENT-SIGNATURE value.
+     * Extracted to share logic between streaming and non-streaming flows.
+     */
+    private signPayment;
+    /**
+     * Streaming chat completion with automatic x402 payment.
+     *
+     * Uses a pre-auth cache so repeat calls to the same model skip the 402
+     * round-trip (~200ms savings). Falls back to the normal 402 flow on cache
+     * miss or if the pre-signed payment is rejected.
+     *
+     * @returns Raw fetch Response with a streaming SSE body.
+     */
+    chatCompletionStream(model: string, messages: ChatMessage[], options?: ChatCompletionOptions): Promise<Response>;
     /**
      * Make a request with automatic x402 payment handling, returning raw JSON.
      * Used for non-ChatResponse endpoints (X/Twitter, search, image edit, etc.).
@@ -584,6 +701,36 @@ declare class LLMClient {
      * @returns SearchResult with summary and citations
      */
     search(query: string, options?: SearchOptions): Promise<SearchResult>;
+    /**
+     * Neural web search via Exa. Returns semantically relevant URLs and metadata.
+     * Understands meaning, not just keywords. $0.01/call.
+     *
+     * @param query - Natural language search query
+     * @param options - Optional filters (numResults, category, date range, domains)
+     */
+    exaSearch(query: string, options?: ExaSearchOptions): Promise<ExaSearchResponse>;
+    /**
+     * Ask a question and get a cited, synthesized answer grounded in real web sources.
+     * No hallucinations — every claim is backed by a citation. $0.01/call.
+     *
+     * @param query - The question to answer
+     */
+    exaAnswer(query: string): Promise<ExaAnswerResponse>;
+    /**
+     * Fetch full Markdown text content from a list of URLs. $0.002 per URL.
+     * Returns clean text ready to feed into an LLM context window.
+     *
+     * @param urls - Array of URLs to fetch (up to 100)
+     */
+    exaContents(urls: string[]): Promise<ExaContentsResponse>;
+    /**
+     * Find pages semantically similar to a given URL. $0.01/call.
+     * Useful for discovering competitors, alternatives, and related resources.
+     *
+     * @param url - Reference URL
+     * @param options - Optional filters (numResults, excludeSourceDomain)
+     */
+    exaFindSimilar(url: string, options?: ExaFindSimilarOptions): Promise<ExaSearchResponse>;
     /**
      * Get USDC balance on Base network.
      *
@@ -1108,7 +1255,7 @@ declare const WALLET_DIR_PATH: string;
  *   // Or pass key directly
  *   const client = new SolanaLLMClient({ privateKey: 'your-bs58-key' });
  *
- *   const response = await client.chat('openai/gpt-4o', 'gm Solana');
+ *   const response = await client.chat('openai/gpt-5.2', 'gm Solana');
  */
 
 interface SolanaLLMClientOptions {
@@ -1166,6 +1313,44 @@ declare class SolanaLLMClient {
     xCompareAuthors(handle1: string, handle2: string): Promise<XCompareAuthorsResponse>;
     pm(path: string, params?: Record<string, string>): Promise<Record<string, unknown>>;
     pmQuery(path: string, query: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Generic Exa endpoint proxy (POST, Solana payment). Powered by Exa.
+     *
+     * @param path - Exa endpoint: "search" | "find-similar" | "contents" | "answer"
+     * @param body - Request body (see Exa API docs)
+     *
+     * @example
+     * const results = await client.exa("search", { query: "latest AI research", numResults: 5 });
+     */
+    exa(path: string, body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Neural and keyword web search via Exa (Solana payment, $0.01/request).
+     *
+     * @example
+     * const results = await client.exaSearch("latest AI papers", { numResults: 5 });
+     */
+    exaSearch(query: string, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Find pages semantically similar to a given URL via Exa (Solana payment, $0.01/request).
+     *
+     * @example
+     * const results = await client.exaFindSimilar("https://openai.com/research/gpt-4", { numResults: 5 });
+     */
+    exaFindSimilar(url: string, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Extract full text content from URLs via Exa (Solana payment, $0.002/URL).
+     *
+     * @example
+     * const data = await client.exaContents(["https://arxiv.org/abs/2303.08774"]);
+     */
+    exaContents(urls: string[], options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * AI-generated answer grounded in live web search via Exa (Solana payment, $0.01/request).
+     *
+     * @example
+     * const answer = await client.exaAnswer("What is the current state of AI safety research?");
+     */
+    exaAnswer(query: string, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
     /** Get session spending. */
     getSpending(): Spending;
     /** True if using sol.blockrun.ai. */
@@ -1228,6 +1413,11 @@ declare function getCachedByRequest(endpoint: string, body: Record<string, unkno
 declare function setCache(key: string, data: unknown, ttlMs: number): void;
 declare function saveToCache(endpoint: string, body: Record<string, unknown>, response: unknown, costUsd?: number): void;
 declare function clearCache(): number;
+declare function getCostLogSummary(): {
+    totalUsd: number;
+    calls: number;
+    byEndpoint: Record<string, number>;
+};
 
 /**
  * Agent wallet setup utilities.
@@ -1277,7 +1467,7 @@ declare function getCostSummary(): {
  *
  * // Rest of your code stays exactly the same!
  * const response = await client.chat.completions.create({
- *   model: 'gpt-4o',
+ *   model: 'gpt-5.2',
  *   messages: [{ role: 'user', content: 'Hello!' }]
  * });
  */
@@ -1384,7 +1574,7 @@ declare class Chat {
  * const client = new OpenAI({ walletKey: '0x...' });
  *
  * const response = await client.chat.completions.create({
- *   model: 'gpt-4o',
+ *   model: 'gpt-5.2',
  *   messages: [{ role: 'user', content: 'Hello!' }]
  * });
  *
@@ -1419,4 +1609,59 @@ declare class AnthropicClient {
     getWalletAddress(): string;
 }
 
-export { APIError, AnthropicClient, BASE_CHAIN_ID, type BlockRunAnthropicOptions, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatUsage, type CostEntry, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, 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, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type Spending, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XArticlesRisingResponse, type XAuthorAnalyticsResponse, type XCompareAuthorsResponse, type XFollower, type XFollowersResponse, type XFollowingsResponse, type XMentionsResponse, type XSearchResponse, type XSearchSource, type XTrendingResponse, type XTweet, type XTweetLookupResponse, type XTweetRepliesResponse, type XTweetThreadResponse, type XTweetsResponse, type XUser, type XUserInfoResponse, type XUserLookupResponse, type XVerifiedFollowersResponse, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getCached, getCachedByRequest, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, testnetClient };
+/**
+ * Input validation and security utilities for BlockRun LLM SDK.
+ *
+ * This module provides validation functions to ensure:
+ * - Private keys are properly formatted
+ * - API URLs use HTTPS
+ * - Server responses don't leak sensitive information
+ * - Resource URLs match expected domains
+ */
+
+/**
+ * Known LLM providers (for optional validation).
+ */
+declare const KNOWN_PROVIDERS: Set<string>;
+/**
+ * Validates that a model ID is a non-empty string.
+ *
+ * @param model - The model ID (e.g., "openai/gpt-5.2", "anthropic/claude-sonnet-4.5")
+ * @throws {Error} If the model is invalid
+ *
+ * @example
+ * validateModel("openai/gpt-5.2");
+ */
+declare function validateModel(model: string): void;
+/**
+ * Validates that max_tokens is an integer between 1 and 100,000.
+ *
+ * @param maxTokens - Maximum number of tokens to generate
+ * @throws {Error} If maxTokens is invalid
+ *
+ * @example
+ * validateMaxTokens(1000);
+ */
+declare function validateMaxTokens(maxTokens?: number): void;
+/**
+ * Validates that temperature is a number between 0 and 2.
+ *
+ * @param temperature - Sampling temperature (0-2)
+ * @throws {Error} If temperature is invalid
+ *
+ * @example
+ * validateTemperature(0.7);
+ */
+declare function validateTemperature(temperature?: number): void;
+/**
+ * Validates that top_p is a number between 0 and 1.
+ *
+ * @param topP - Top-p sampling parameter (0-1)
+ * @throws {Error} If topP is invalid
+ *
+ * @example
+ * validateTopP(0.9);
+ */
+declare function validateTopP(topP?: number): void;
+
+export { APIError, AnthropicClient, BASE_CHAIN_ID, type BlockRunAnthropicOptions, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, 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, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type Spending, type SpendingReport, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XArticlesRisingResponse, type XAuthorAnalyticsResponse, type XCompareAuthorsResponse, type XFollower, type XFollowersResponse, type XFollowingsResponse, type XMentionsResponse, type XSearchResponse, type XSearchSource, type XTrendingResponse, type XTweet, type XTweetLookupResponse, type XTweetRepliesResponse, type XTweetThreadResponse, type XTweetsResponse, type XUser, type XUserInfoResponse, type XUserLookupResponse, type XVerifiedFollowersResponse, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, testnetClient, validateMaxTokens, validateModel, validateTemperature, validateTopP };