@blockrun/llm 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -51,7 +51,8 @@ __export(index_exports, {
   getPaymentLinks: () => getPaymentLinks,
   getWalletAddress: () => getWalletAddress,
   loadWallet: () => loadWallet,
-  saveWallet: () => saveWallet
+  saveWallet: () => saveWallet,
+  testnetClient: () => testnetClient
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -278,9 +279,14 @@ function validateResourceUrl(url, baseUrl) {
 
 // src/client.ts
 var DEFAULT_API_URL = "https://blockrun.ai/api";
+var TESTNET_API_URL = "https://testnet.blockrun.ai/api";
 var DEFAULT_MAX_TOKENS = 1024;
 var DEFAULT_TIMEOUT = 6e4;
+var SDK_VERSION = "0.3.0";
+var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 var LLMClient = class {
+  static DEFAULT_API_URL = DEFAULT_API_URL;
+  static TESTNET_API_URL = TESTNET_API_URL;
   account;
   privateKey;
   apiUrl;
@@ -333,7 +339,7 @@ var LLMClient = class {
       search: options?.search,
       searchParameters: options?.searchParameters
     });
-    return result.choices[0].message.content;
+    return result.choices[0].message.content || "";
   }
   /**
    * Full chat completion interface (OpenAI-compatible).
@@ -360,6 +366,12 @@ var LLMClient = class {
     } else if (options?.search === true) {
       body.search_parameters = { mode: "on" };
     }
+    if (options?.tools !== void 0) {
+      body.tools = options.tools;
+    }
+    if (options?.toolChoice !== void 0) {
+      body.tool_choice = options.toolChoice;
+    }
     return this.requestWithPayment("/v1/chat/completions", body);
   }
   /**
@@ -369,7 +381,7 @@ var LLMClient = class {
     const url = `${this.apiUrl}${endpoint}`;
     const response = await this.fetchWithTimeout(url, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
       body: JSON.stringify(body)
     });
     if (response.status === 402) {
@@ -432,6 +444,7 @@ var LLMClient = class {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
+        "User-Agent": USER_AGENT,
         "PAYMENT-SIGNATURE": paymentPayload
       },
       body: JSON.stringify(body)
@@ -560,7 +573,19 @@ var LLMClient = class {
   getWalletAddress() {
     return this.account.address;
   }
+  /**
+   * Check if client is configured for testnet.
+   */
+  isTestnet() {
+    return this.apiUrl.includes("testnet.blockrun.ai");
+  }
 };
+function testnetClient(options = {}) {
+  return new LLMClient({
+    ...options,
+    apiUrl: TESTNET_API_URL
+  });
+}
 var client_default = LLMClient;
 
 // src/image.ts
@@ -962,7 +987,9 @@ var ChatCompletions = class {
       {
         maxTokens: params.max_tokens,
         temperature: params.temperature,
-        topP: params.top_p
+        topP: params.top_p,
+        tools: params.tools,
+        toolChoice: params.tool_choice
       }
     );
     return this.transformResponse(response);
@@ -977,6 +1004,12 @@ var ChatCompletions = class {
       top_p: params.top_p,
       stream: true
     };
+    if (params.tools) {
+      body.tools = params.tools;
+    }
+    if (params.tool_choice) {
+      body.tool_choice = params.tool_choice;
+    }
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
@@ -1013,7 +1046,8 @@ var ChatCompletions = class {
         index: choice.index ?? index,
         message: {
           role: "assistant",
-          content: choice.message.content
+          content: choice.message.content,
+          tool_calls: choice.message.tool_calls
         },
         finish_reason: choice.finish_reason || "stop"
       })),
@@ -1070,5 +1104,6 @@ var OpenAI = class {
   getPaymentLinks,
   getWalletAddress,
   loadWallet,
-  saveWallet
+  saveWallet,
+  testnetClient
 });

package/dist/index.d.cts

@@ -1,14 +1,42 @@
 /**
  * Type definitions for BlockRun LLM SDK
  */
+interface FunctionDefinition {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+    strict?: boolean;
+}
+interface Tool {
+    type: "function";
+    function: FunctionDefinition;
+}
+interface FunctionCall {
+    name: string;
+    arguments: string;
+}
+interface ToolCall {
+    id: string;
+    type: "function";
+    function: FunctionCall;
+}
+type ToolChoice = "none" | "auto" | "required" | {
+    type: "function";
+    function: {
+        name: string;
+    };
+};
 interface ChatMessage {
-    role: "system" | "user" | "assistant";
-    content: string;
+    role: "system" | "user" | "assistant" | "tool";
+    content?: string | null;
+    name?: string;
+    tool_call_id?: string;
+    tool_calls?: ToolCall[];
 }
 interface ChatChoice {
     index: number;
     message: ChatMessage;
-    finish_reason?: string;
+    finish_reason?: "stop" | "length" | "content_filter" | "tool_calls";
 }
 interface ChatUsage {
     prompt_tokens: number;
@@ -146,6 +174,10 @@ interface ChatCompletionOptions {
     search?: boolean;
     /** Full xAI Live Search configuration (for Grok models) */
     searchParameters?: SearchParameters;
+    /** Tool definitions for function calling */
+    tools?: Tool[];
+    /** Tool selection strategy */
+    toolChoice?: ToolChoice;
 }
 declare class BlockrunError extends Error {
     constructor(message: string);
@@ -180,8 +212,28 @@ declare class APIError extends BlockrunError {
  *
  * Provides access to multiple LLM providers (OpenAI, Anthropic, Google, etc.)
  * with automatic x402 micropayments on Base chain.
+ *
+ * Networks:
+ * - Mainnet: https://blockrun.ai/api (Base, Chain ID 8453)
+ * - Testnet: https://testnet.blockrun.ai/api (Base Sepolia, Chain ID 84532)
+ *
+ * @example Testnet usage
+ * ```ts
+ * // Use testnet convenience function
+ * import { testnetClient } from '@blockrun/llm';
+ * const client = testnetClient({ privateKey: '0x...' });
+ * const response = await client.chat('openai/gpt-oss-20b', 'Hello!');
+ *
+ * // Or configure manually
+ * const client = new LLMClient({
+ *   privateKey: '0x...',
+ *   apiUrl: 'https://testnet.blockrun.ai/api'
+ * });
+ * ```
  */
 declare class LLMClient {
+    static readonly DEFAULT_API_URL = "https://blockrun.ai/api";
+    static readonly TESTNET_API_URL = "https://testnet.blockrun.ai/api";
     private account;
     private privateKey;
     private apiUrl;
@@ -266,7 +318,38 @@ declare class LLMClient {
      * Get the wallet address being used for payments.
      */
     getWalletAddress(): string;
+    /**
+     * Check if client is configured for testnet.
+     */
+    isTestnet(): boolean;
 }
+/**
+ * Create a testnet LLM client for development and testing.
+ *
+ * This is a convenience function that creates an LLMClient configured
+ * for the BlockRun testnet (Base Sepolia).
+ *
+ * @param options - Client options (privateKey required unless BASE_CHAIN_WALLET_KEY env var is set)
+ * @returns LLMClient configured for testnet
+ *
+ * @example
+ * ```ts
+ * import { testnetClient } from '@blockrun/llm';
+ *
+ * const client = testnetClient({ privateKey: '0x...' });
+ * const response = await client.chat('openai/gpt-oss-20b', 'Hello!');
+ * ```
+ *
+ * Testnet Setup:
+ * 1. Get testnet ETH from https://www.alchemy.com/faucets/base-sepolia
+ * 2. Get testnet USDC from https://faucet.circle.com/
+ * 3. Use your wallet with testnet funds
+ *
+ * Available Testnet Models:
+ * - openai/gpt-oss-20b
+ * - openai/gpt-oss-120b
+ */
+declare function testnetClient(options?: Omit<LLMClientOptions, 'apiUrl'>): LLMClient;
 
 /**
  * BlockRun Image Client - Generate images via x402 micropayments.
@@ -485,8 +568,11 @@ interface OpenAIClientOptions {
 interface OpenAIChatCompletionParams {
     model: string;
     messages: Array<{
-        role: "system" | "user" | "assistant";
-        content: string;
+        role: "system" | "user" | "assistant" | "tool";
+        content?: string | null;
+        name?: string;
+        tool_call_id?: string;
+        tool_calls?: ToolCall[];
     }>;
     max_tokens?: number;
     temperature?: number;
@@ -497,14 +583,17 @@ interface OpenAIChatCompletionParams {
     presence_penalty?: number;
     frequency_penalty?: number;
     user?: string;
+    tools?: Tool[];
+    tool_choice?: ToolChoice;
 }
 interface OpenAIChatCompletionChoice {
     index: number;
     message: {
         role: "assistant";
-        content: string;
+        content?: string | null;
+        tool_calls?: ToolCall[];
     };
-    finish_reason: string | null;
+    finish_reason: "stop" | "length" | "content_filter" | "tool_calls" | null;
 }
 interface OpenAIChatCompletionResponse {
     id: string;
@@ -584,4 +673,4 @@ declare class OpenAI {
     getWalletAddress(): string;
 }
 
-export { APIError, BASE_CHAIN_ID, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatUsage, 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, 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 };
+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 };

package/dist/index.d.ts

@@ -1,14 +1,42 @@
 /**
  * Type definitions for BlockRun LLM SDK
  */
+interface FunctionDefinition {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+    strict?: boolean;
+}
+interface Tool {
+    type: "function";
+    function: FunctionDefinition;
+}
+interface FunctionCall {
+    name: string;
+    arguments: string;
+}
+interface ToolCall {
+    id: string;
+    type: "function";
+    function: FunctionCall;
+}
+type ToolChoice = "none" | "auto" | "required" | {
+    type: "function";
+    function: {
+        name: string;
+    };
+};
 interface ChatMessage {
-    role: "system" | "user" | "assistant";
-    content: string;
+    role: "system" | "user" | "assistant" | "tool";
+    content?: string | null;
+    name?: string;
+    tool_call_id?: string;
+    tool_calls?: ToolCall[];
 }
 interface ChatChoice {
     index: number;
     message: ChatMessage;
-    finish_reason?: string;
+    finish_reason?: "stop" | "length" | "content_filter" | "tool_calls";
 }
 interface ChatUsage {
     prompt_tokens: number;
@@ -146,6 +174,10 @@ interface ChatCompletionOptions {
     search?: boolean;
     /** Full xAI Live Search configuration (for Grok models) */
     searchParameters?: SearchParameters;
+    /** Tool definitions for function calling */
+    tools?: Tool[];
+    /** Tool selection strategy */
+    toolChoice?: ToolChoice;
 }
 declare class BlockrunError extends Error {
     constructor(message: string);
@@ -180,8 +212,28 @@ declare class APIError extends BlockrunError {
  *
  * Provides access to multiple LLM providers (OpenAI, Anthropic, Google, etc.)
  * with automatic x402 micropayments on Base chain.
+ *
+ * Networks:
+ * - Mainnet: https://blockrun.ai/api (Base, Chain ID 8453)
+ * - Testnet: https://testnet.blockrun.ai/api (Base Sepolia, Chain ID 84532)
+ *
+ * @example Testnet usage
+ * ```ts
+ * // Use testnet convenience function
+ * import { testnetClient } from '@blockrun/llm';
+ * const client = testnetClient({ privateKey: '0x...' });
+ * const response = await client.chat('openai/gpt-oss-20b', 'Hello!');
+ *
+ * // Or configure manually
+ * const client = new LLMClient({
+ *   privateKey: '0x...',
+ *   apiUrl: 'https://testnet.blockrun.ai/api'
+ * });
+ * ```
  */
 declare class LLMClient {
+    static readonly DEFAULT_API_URL = "https://blockrun.ai/api";
+    static readonly TESTNET_API_URL = "https://testnet.blockrun.ai/api";
     private account;
     private privateKey;
     private apiUrl;
@@ -266,7 +318,38 @@ declare class LLMClient {
      * Get the wallet address being used for payments.
      */
     getWalletAddress(): string;
+    /**
+     * Check if client is configured for testnet.
+     */
+    isTestnet(): boolean;
 }
+/**
+ * Create a testnet LLM client for development and testing.
+ *
+ * This is a convenience function that creates an LLMClient configured
+ * for the BlockRun testnet (Base Sepolia).
+ *
+ * @param options - Client options (privateKey required unless BASE_CHAIN_WALLET_KEY env var is set)
+ * @returns LLMClient configured for testnet
+ *
+ * @example
+ * ```ts
+ * import { testnetClient } from '@blockrun/llm';
+ *
+ * const client = testnetClient({ privateKey: '0x...' });
+ * const response = await client.chat('openai/gpt-oss-20b', 'Hello!');
+ * ```
+ *
+ * Testnet Setup:
+ * 1. Get testnet ETH from https://www.alchemy.com/faucets/base-sepolia
+ * 2. Get testnet USDC from https://faucet.circle.com/
+ * 3. Use your wallet with testnet funds
+ *
+ * Available Testnet Models:
+ * - openai/gpt-oss-20b
+ * - openai/gpt-oss-120b
+ */
+declare function testnetClient(options?: Omit<LLMClientOptions, 'apiUrl'>): LLMClient;
 
 /**
  * BlockRun Image Client - Generate images via x402 micropayments.
@@ -485,8 +568,11 @@ interface OpenAIClientOptions {
 interface OpenAIChatCompletionParams {
     model: string;
     messages: Array<{
-        role: "system" | "user" | "assistant";
-        content: string;
+        role: "system" | "user" | "assistant" | "tool";
+        content?: string | null;
+        name?: string;
+        tool_call_id?: string;
+        tool_calls?: ToolCall[];
     }>;
     max_tokens?: number;
     temperature?: number;
@@ -497,14 +583,17 @@ interface OpenAIChatCompletionParams {
     presence_penalty?: number;
     frequency_penalty?: number;
     user?: string;
+    tools?: Tool[];
+    tool_choice?: ToolChoice;
 }
 interface OpenAIChatCompletionChoice {
     index: number;
     message: {
         role: "assistant";
-        content: string;
+        content?: string | null;
+        tool_calls?: ToolCall[];
     };
-    finish_reason: string | null;
+    finish_reason: "stop" | "length" | "content_filter" | "tool_calls" | null;
 }
 interface OpenAIChatCompletionResponse {
     id: string;
@@ -584,4 +673,4 @@ declare class OpenAI {
     getWalletAddress(): string;
 }
 
-export { APIError, BASE_CHAIN_ID, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatUsage, 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, 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 };
+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 };

package/dist/{index.esm-DGL5QIKD.js → index.esm-WP2DIBSK.js}

@@ -75,7 +75,7 @@ import {
   clusterApiUrl,
   sendAndConfirmRawTransaction,
   sendAndConfirmTransaction
-} from "./chunk-4LEERQOK.js";
+} from "./chunk-S7BEMV6T.js";
 import "./chunk-2ESYSVXG.js";
 export {
   Account,

package/dist/index.js

@@ -223,9 +223,14 @@ function validateResourceUrl(url, baseUrl) {
 
 // src/client.ts
 var DEFAULT_API_URL = "https://blockrun.ai/api";
+var TESTNET_API_URL = "https://testnet.blockrun.ai/api";
 var DEFAULT_MAX_TOKENS = 1024;
 var DEFAULT_TIMEOUT = 6e4;
+var SDK_VERSION = "0.3.0";
+var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 var LLMClient = class {
+  static DEFAULT_API_URL = DEFAULT_API_URL;
+  static TESTNET_API_URL = TESTNET_API_URL;
   account;
   privateKey;
   apiUrl;
@@ -278,7 +283,7 @@ var LLMClient = class {
       search: options?.search,
       searchParameters: options?.searchParameters
     });
-    return result.choices[0].message.content;
+    return result.choices[0].message.content || "";
   }
   /**
    * Full chat completion interface (OpenAI-compatible).
@@ -305,6 +310,12 @@ var LLMClient = class {
     } else if (options?.search === true) {
       body.search_parameters = { mode: "on" };
     }
+    if (options?.tools !== void 0) {
+      body.tools = options.tools;
+    }
+    if (options?.toolChoice !== void 0) {
+      body.tool_choice = options.toolChoice;
+    }
     return this.requestWithPayment("/v1/chat/completions", body);
   }
   /**
@@ -314,7 +325,7 @@ var LLMClient = class {
     const url = `${this.apiUrl}${endpoint}`;
     const response = await this.fetchWithTimeout(url, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
       body: JSON.stringify(body)
     });
     if (response.status === 402) {
@@ -377,6 +388,7 @@ var LLMClient = class {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
+        "User-Agent": USER_AGENT,
         "PAYMENT-SIGNATURE": paymentPayload
       },
       body: JSON.stringify(body)
@@ -505,7 +517,19 @@ var LLMClient = class {
   getWalletAddress() {
     return this.account.address;
   }
+  /**
+   * Check if client is configured for testnet.
+   */
+  isTestnet() {
+    return this.apiUrl.includes("testnet.blockrun.ai");
+  }
 };
+function testnetClient(options = {}) {
+  return new LLMClient({
+    ...options,
+    apiUrl: TESTNET_API_URL
+  });
+}
 var client_default = LLMClient;
 
 // src/image.ts
@@ -907,7 +931,9 @@ var ChatCompletions = class {
       {
         maxTokens: params.max_tokens,
         temperature: params.temperature,
-        topP: params.top_p
+        topP: params.top_p,
+        tools: params.tools,
+        toolChoice: params.tool_choice
       }
     );
     return this.transformResponse(response);
@@ -922,6 +948,12 @@ var ChatCompletions = class {
       top_p: params.top_p,
       stream: true
     };
+    if (params.tools) {
+      body.tools = params.tools;
+    }
+    if (params.tool_choice) {
+      body.tool_choice = params.tool_choice;
+    }
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
@@ -958,7 +990,8 @@ var ChatCompletions = class {
         index: choice.index ?? index,
         message: {
           role: "assistant",
-          content: choice.message.content
+          content: choice.message.content,
+          tool_calls: choice.message.tool_calls
         },
         finish_reason: choice.finish_reason || "stop"
       })),
@@ -1015,5 +1048,6 @@ export {
   getPaymentLinks,
   getWalletAddress,
   loadWallet,
-  saveWallet
+  saveWallet,
+  testnetClient
 };

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@blockrun/llm",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "BlockRun LLM Gateway SDK - Pay-per-request AI via x402 on Base",
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     }
   },
   "files": [