@blockrun/llm 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,295 @@
+/**
+ * Type definitions for BlockRun LLM SDK
+ */
+interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+interface ChatChoice {
+    index: number;
+    message: ChatMessage;
+    finish_reason?: string;
+}
+interface ChatUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+interface ChatResponse {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: ChatChoice[];
+    usage?: ChatUsage;
+}
+interface Model {
+    id: string;
+    name: string;
+    provider: string;
+    description: string;
+    inputPrice: number;
+    outputPrice: number;
+    contextWindow: number;
+    maxOutput: number;
+    available: boolean;
+}
+interface LLMClientOptions {
+    /** EVM wallet private key (hex string starting with 0x). Optional if BASE_CHAIN_WALLET_KEY env var is set. */
+    privateKey?: `0x${string}` | string;
+    /** API endpoint URL (default: https://blockrun.ai/api) */
+    apiUrl?: string;
+    /** Request timeout in milliseconds (default: 60000) */
+    timeout?: number;
+}
+interface ChatOptions {
+    /** System prompt */
+    system?: string;
+    /** Max tokens to generate */
+    maxTokens?: number;
+    /** Sampling temperature */
+    temperature?: number;
+    /** Nucleus sampling parameter */
+    topP?: number;
+}
+interface ChatCompletionOptions {
+    /** Max tokens to generate */
+    maxTokens?: number;
+    /** Sampling temperature */
+    temperature?: number;
+    /** Nucleus sampling parameter */
+    topP?: number;
+}
+declare class BlockrunError extends Error {
+    constructor(message: string);
+}
+declare class PaymentError extends BlockrunError {
+    constructor(message: string);
+}
+declare class APIError extends BlockrunError {
+    statusCode: number;
+    response?: unknown;
+    constructor(message: string, statusCode: number, response?: unknown);
+}
+
+/**
+ * BlockRun LLM Client - Main SDK entry point.
+ *
+ * Usage:
+ *   import { LLMClient } from '@blockrun/llm';
+ *
+ *   // Option 1: Use BASE_CHAIN_WALLET_KEY env var
+ *   const client = new LLMClient();
+ *
+ *   // Option 2: Pass private key directly
+ *   const client = new LLMClient({ privateKey: '0x...' });
+ *
+ *   const response = await client.chat('openai/gpt-4o', 'Hello!');
+ *   console.log(response);
+ */
+
+/**
+ * BlockRun LLM Gateway Client.
+ *
+ * Provides access to multiple LLM providers (OpenAI, Anthropic, Google, etc.)
+ * with automatic x402 micropayments on Base chain.
+ */
+declare class LLMClient {
+    private account;
+    private privateKey;
+    private apiUrl;
+    private timeout;
+    /**
+     * Initialize the BlockRun LLM client.
+     *
+     * @param options - Client configuration options (optional if BASE_CHAIN_WALLET_KEY env var is set)
+     */
+    constructor(options?: LLMClientOptions);
+    /**
+     * Simple 1-line chat interface.
+     *
+     * @param model - Model ID (e.g., 'openai/gpt-4o', 'anthropic/claude-sonnet-4')
+     * @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?');
+     * console.log(response); // 'The capital of France is Paris.'
+     */
+    chat(model: string, prompt: string, options?: ChatOptions): Promise<string>;
+    /**
+     * Full chat completion interface (OpenAI-compatible).
+     *
+     * @param model - Model ID
+     * @param messages - Array of messages with role and content
+     * @param options - Optional completion parameters
+     * @returns ChatResponse object with choices and usage
+     */
+    chatCompletion(model: string, messages: ChatMessage[], options?: ChatCompletionOptions): Promise<ChatResponse>;
+    /**
+     * Make a request with automatic x402 payment handling.
+     */
+    private requestWithPayment;
+    /**
+     * Handle 402 response: parse requirements, sign payment, retry.
+     */
+    private handlePaymentAndRetry;
+    /**
+     * Fetch with timeout.
+     */
+    private fetchWithTimeout;
+    /**
+     * List available models with pricing.
+     */
+    listModels(): Promise<Model[]>;
+    /**
+     * Get the wallet address being used for payments.
+     */
+    getWalletAddress(): string;
+}
+
+/**
+ * x402 Payment Protocol v2 Implementation for BlockRun.
+ *
+ * This module handles creating signed payment payloads for the x402 v2 protocol.
+ * The private key is used ONLY for local signing and NEVER leaves the client.
+ */
+
+declare const BASE_CHAIN_ID = 8453;
+declare const USDC_BASE: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+
+/**
+ * OpenAI-compatible API wrapper for BlockRun LLM SDK.
+ *
+ * Drop-in replacement for OpenAI SDK - just change the import and use walletKey instead of apiKey.
+ *
+ * @example
+ * // Before (OpenAI)
+ * import OpenAI from 'openai';
+ * const client = new OpenAI({ apiKey: 'sk-...' });
+ *
+ * // After (BlockRun)
+ * import { OpenAI } from '@blockrun/llm';
+ * const client = new OpenAI({ walletKey: '0x...' });
+ *
+ * // Rest of your code stays exactly the same!
+ * const response = await client.chat.completions.create({
+ *   model: 'gpt-4o',
+ *   messages: [{ role: 'user', content: 'Hello!' }]
+ * });
+ */
+
+interface OpenAIClientOptions {
+    /** EVM wallet private key (replaces apiKey) */
+    walletKey?: `0x${string}` | string;
+    /** Alternative: use privateKey like LLMClient */
+    privateKey?: `0x${string}` | string;
+    /** API endpoint URL (default: https://blockrun.ai/api) */
+    baseURL?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+interface OpenAIChatCompletionParams {
+    model: string;
+    messages: Array<{
+        role: "system" | "user" | "assistant";
+        content: string;
+    }>;
+    max_tokens?: number;
+    temperature?: number;
+    top_p?: number;
+    stream?: boolean;
+    n?: number;
+    stop?: string | string[];
+    presence_penalty?: number;
+    frequency_penalty?: number;
+    user?: string;
+}
+interface OpenAIChatCompletionChoice {
+    index: number;
+    message: {
+        role: "assistant";
+        content: string;
+    };
+    finish_reason: string | null;
+}
+interface OpenAIChatCompletionResponse {
+    id: string;
+    object: "chat.completion";
+    created: number;
+    model: string;
+    choices: OpenAIChatCompletionChoice[];
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+interface OpenAIChatCompletionChunk {
+    id: string;
+    object: "chat.completion.chunk";
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        delta: {
+            role?: "assistant";
+            content?: string;
+        };
+        finish_reason: string | null;
+    }>;
+}
+/**
+ * Chat completions API (OpenAI-compatible)
+ */
+declare class ChatCompletions {
+    private client;
+    private apiUrl;
+    private timeout;
+    constructor(client: LLMClient, apiUrl: string, timeout: number);
+    /**
+     * Create a chat completion (OpenAI-compatible).
+     */
+    create(params: OpenAIChatCompletionParams): Promise<OpenAIChatCompletionResponse>;
+    create(params: OpenAIChatCompletionParams & {
+        stream: true;
+    }): Promise<AsyncIterable<OpenAIChatCompletionChunk>>;
+    private createStream;
+    private transformResponse;
+}
+/**
+ * Chat API namespace
+ */
+declare class Chat {
+    completions: ChatCompletions;
+    constructor(client: LLMClient, apiUrl: string, timeout: number);
+}
+/**
+ * OpenAI-compatible client for BlockRun.
+ *
+ * Drop-in replacement for the OpenAI SDK.
+ *
+ * @example
+ * import { OpenAI } from '@blockrun/llm';
+ *
+ * const client = new OpenAI({ walletKey: '0x...' });
+ *
+ * const response = await client.chat.completions.create({
+ *   model: 'gpt-4o',
+ *   messages: [{ role: 'user', content: 'Hello!' }]
+ * });
+ *
+ * console.log(response.choices[0].message.content);
+ */
+declare class OpenAI {
+    chat: Chat;
+    private client;
+    constructor(options?: OpenAIClientOptions);
+    /**
+     * Get the wallet address being used for payments.
+     */
+    getWalletAddress(): string;
+}
+
+export { APIError, BASE_CHAIN_ID, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatUsage, LLMClient, type LLMClientOptions, type Model, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PaymentError, USDC_BASE, LLMClient as default };

package/dist/index.d.ts

@@ -0,0 +1,295 @@
+/**
+ * Type definitions for BlockRun LLM SDK
+ */
+interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+interface ChatChoice {
+    index: number;
+    message: ChatMessage;
+    finish_reason?: string;
+}
+interface ChatUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+interface ChatResponse {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: ChatChoice[];
+    usage?: ChatUsage;
+}
+interface Model {
+    id: string;
+    name: string;
+    provider: string;
+    description: string;
+    inputPrice: number;
+    outputPrice: number;
+    contextWindow: number;
+    maxOutput: number;
+    available: boolean;
+}
+interface LLMClientOptions {
+    /** EVM wallet private key (hex string starting with 0x). Optional if BASE_CHAIN_WALLET_KEY env var is set. */
+    privateKey?: `0x${string}` | string;
+    /** API endpoint URL (default: https://blockrun.ai/api) */
+    apiUrl?: string;
+    /** Request timeout in milliseconds (default: 60000) */
+    timeout?: number;
+}
+interface ChatOptions {
+    /** System prompt */
+    system?: string;
+    /** Max tokens to generate */
+    maxTokens?: number;
+    /** Sampling temperature */
+    temperature?: number;
+    /** Nucleus sampling parameter */
+    topP?: number;
+}
+interface ChatCompletionOptions {
+    /** Max tokens to generate */
+    maxTokens?: number;
+    /** Sampling temperature */
+    temperature?: number;
+    /** Nucleus sampling parameter */
+    topP?: number;
+}
+declare class BlockrunError extends Error {
+    constructor(message: string);
+}
+declare class PaymentError extends BlockrunError {
+    constructor(message: string);
+}
+declare class APIError extends BlockrunError {
+    statusCode: number;
+    response?: unknown;
+    constructor(message: string, statusCode: number, response?: unknown);
+}
+
+/**
+ * BlockRun LLM Client - Main SDK entry point.
+ *
+ * Usage:
+ *   import { LLMClient } from '@blockrun/llm';
+ *
+ *   // Option 1: Use BASE_CHAIN_WALLET_KEY env var
+ *   const client = new LLMClient();
+ *
+ *   // Option 2: Pass private key directly
+ *   const client = new LLMClient({ privateKey: '0x...' });
+ *
+ *   const response = await client.chat('openai/gpt-4o', 'Hello!');
+ *   console.log(response);
+ */
+
+/**
+ * BlockRun LLM Gateway Client.
+ *
+ * Provides access to multiple LLM providers (OpenAI, Anthropic, Google, etc.)
+ * with automatic x402 micropayments on Base chain.
+ */
+declare class LLMClient {
+    private account;
+    private privateKey;
+    private apiUrl;
+    private timeout;
+    /**
+     * Initialize the BlockRun LLM client.
+     *
+     * @param options - Client configuration options (optional if BASE_CHAIN_WALLET_KEY env var is set)
+     */
+    constructor(options?: LLMClientOptions);
+    /**
+     * Simple 1-line chat interface.
+     *
+     * @param model - Model ID (e.g., 'openai/gpt-4o', 'anthropic/claude-sonnet-4')
+     * @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?');
+     * console.log(response); // 'The capital of France is Paris.'
+     */
+    chat(model: string, prompt: string, options?: ChatOptions): Promise<string>;
+    /**
+     * Full chat completion interface (OpenAI-compatible).
+     *
+     * @param model - Model ID
+     * @param messages - Array of messages with role and content
+     * @param options - Optional completion parameters
+     * @returns ChatResponse object with choices and usage
+     */
+    chatCompletion(model: string, messages: ChatMessage[], options?: ChatCompletionOptions): Promise<ChatResponse>;
+    /**
+     * Make a request with automatic x402 payment handling.
+     */
+    private requestWithPayment;
+    /**
+     * Handle 402 response: parse requirements, sign payment, retry.
+     */
+    private handlePaymentAndRetry;
+    /**
+     * Fetch with timeout.
+     */
+    private fetchWithTimeout;
+    /**
+     * List available models with pricing.
+     */
+    listModels(): Promise<Model[]>;
+    /**
+     * Get the wallet address being used for payments.
+     */
+    getWalletAddress(): string;
+}
+
+/**
+ * x402 Payment Protocol v2 Implementation for BlockRun.
+ *
+ * This module handles creating signed payment payloads for the x402 v2 protocol.
+ * The private key is used ONLY for local signing and NEVER leaves the client.
+ */
+
+declare const BASE_CHAIN_ID = 8453;
+declare const USDC_BASE: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+
+/**
+ * OpenAI-compatible API wrapper for BlockRun LLM SDK.
+ *
+ * Drop-in replacement for OpenAI SDK - just change the import and use walletKey instead of apiKey.
+ *
+ * @example
+ * // Before (OpenAI)
+ * import OpenAI from 'openai';
+ * const client = new OpenAI({ apiKey: 'sk-...' });
+ *
+ * // After (BlockRun)
+ * import { OpenAI } from '@blockrun/llm';
+ * const client = new OpenAI({ walletKey: '0x...' });
+ *
+ * // Rest of your code stays exactly the same!
+ * const response = await client.chat.completions.create({
+ *   model: 'gpt-4o',
+ *   messages: [{ role: 'user', content: 'Hello!' }]
+ * });
+ */
+
+interface OpenAIClientOptions {
+    /** EVM wallet private key (replaces apiKey) */
+    walletKey?: `0x${string}` | string;
+    /** Alternative: use privateKey like LLMClient */
+    privateKey?: `0x${string}` | string;
+    /** API endpoint URL (default: https://blockrun.ai/api) */
+    baseURL?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+interface OpenAIChatCompletionParams {
+    model: string;
+    messages: Array<{
+        role: "system" | "user" | "assistant";
+        content: string;
+    }>;
+    max_tokens?: number;
+    temperature?: number;
+    top_p?: number;
+    stream?: boolean;
+    n?: number;
+    stop?: string | string[];
+    presence_penalty?: number;
+    frequency_penalty?: number;
+    user?: string;
+}
+interface OpenAIChatCompletionChoice {
+    index: number;
+    message: {
+        role: "assistant";
+        content: string;
+    };
+    finish_reason: string | null;
+}
+interface OpenAIChatCompletionResponse {
+    id: string;
+    object: "chat.completion";
+    created: number;
+    model: string;
+    choices: OpenAIChatCompletionChoice[];
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+interface OpenAIChatCompletionChunk {
+    id: string;
+    object: "chat.completion.chunk";
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        delta: {
+            role?: "assistant";
+            content?: string;
+        };
+        finish_reason: string | null;
+    }>;
+}
+/**
+ * Chat completions API (OpenAI-compatible)
+ */
+declare class ChatCompletions {
+    private client;
+    private apiUrl;
+    private timeout;
+    constructor(client: LLMClient, apiUrl: string, timeout: number);
+    /**
+     * Create a chat completion (OpenAI-compatible).
+     */
+    create(params: OpenAIChatCompletionParams): Promise<OpenAIChatCompletionResponse>;
+    create(params: OpenAIChatCompletionParams & {
+        stream: true;
+    }): Promise<AsyncIterable<OpenAIChatCompletionChunk>>;
+    private createStream;
+    private transformResponse;
+}
+/**
+ * Chat API namespace
+ */
+declare class Chat {
+    completions: ChatCompletions;
+    constructor(client: LLMClient, apiUrl: string, timeout: number);
+}
+/**
+ * OpenAI-compatible client for BlockRun.
+ *
+ * Drop-in replacement for the OpenAI SDK.
+ *
+ * @example
+ * import { OpenAI } from '@blockrun/llm';
+ *
+ * const client = new OpenAI({ walletKey: '0x...' });
+ *
+ * const response = await client.chat.completions.create({
+ *   model: 'gpt-4o',
+ *   messages: [{ role: 'user', content: 'Hello!' }]
+ * });
+ *
+ * console.log(response.choices[0].message.content);
+ */
+declare class OpenAI {
+    chat: Chat;
+    private client;
+    constructor(options?: OpenAIClientOptions);
+    /**
+     * Get the wallet address being used for payments.
+     */
+    getWalletAddress(): string;
+}
+
+export { APIError, BASE_CHAIN_ID, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatUsage, LLMClient, type LLMClientOptions, type Model, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PaymentError, USDC_BASE, LLMClient as default };