@blockrun/llm 0.3.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.md +123 -24
  2. package/dist/{chunk-S7BEMV6T.js → chunk-KRDGCX7W.js} +25914 -25839
  3. package/dist/{esm-EBZAIN5N.js → esm-PTFDM6PE.js} +159 -6
  4. package/dist/index.cjs +36985 -37
  5. package/dist/index.d.cts +179 -1
  6. package/dist/index.d.ts +179 -1
  7. package/dist/{index.esm-WP2DIBSK.js → index.esm-SXKIFLA7.js} +3 -2
  8. package/dist/index.js +421 -1
  9. package/package.json +71 -70
  10. package/dist/chunk-2ESYSVXG.js +0 -48
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @blockrun/llm
2
2
 
3
- Pay-per-request access to GPT-4o, Claude 4, Gemini 2.5, and more via x402 micropayments on Base and Solana.
3
+ Pay-per-request access to GPT-4o, Claude 4, Gemini 3.1, and more via x402 micropayments on Base and Solana.
4
4
 
5
5
  **Networks:**
6
6
  - **Base Mainnet:** Chain ID 8453 - Production with real USDC
@@ -35,13 +35,44 @@ That's it. The SDK handles x402 payment automatically.
35
35
  ## Quick Start (Solana)
36
36
 
37
37
  ```typescript
38
- import { LLMClient } from '@blockrun/llm';
38
+ import { SolanaLLMClient } from '@blockrun/llm';
39
39
 
40
- const client = new LLMClient({ network: 'solana' }); // Uses BLOCKRUN_SOLANA_KEY
41
- const response = await client.chat('openai/gpt-4o', 'Hello!');
40
+ // SOLANA_WALLET_KEY env var (bs58-encoded Solana secret key)
41
+ const client = new SolanaLLMClient();
42
+ const response = await client.chat('openai/gpt-4o', 'gm Solana');
43
+ console.log(response);
42
44
  ```
43
45
 
44
- For Solana, set `BLOCKRUN_SOLANA_KEY` environment variable with your base58-encoded Solana secret key.
46
+ Set `SOLANA_WALLET_KEY` to your bs58-encoded Solana secret key. Payments are automatic via x402 — your key never leaves your machine.
47
+
48
+ ## Solana Support
49
+
50
+ Pay for AI calls with Solana USDC via [sol.blockrun.ai](https://sol.blockrun.ai):
51
+
52
+ ```typescript
53
+ import { SolanaLLMClient } from '@blockrun/llm';
54
+
55
+ // SOLANA_WALLET_KEY env var (bs58-encoded Solana secret key)
56
+ const client = new SolanaLLMClient();
57
+
58
+ // Or pass key directly
59
+ const client2 = new SolanaLLMClient({ privateKey: 'your-bs58-solana-key' });
60
+
61
+ // Same API as LLMClient
62
+ const response = await client.chat('openai/gpt-4o', 'gm Solana');
63
+ console.log(response);
64
+
65
+ // Live Search with Grok (Solana payment)
66
+ const tweet = await client.chat('xai/grok-3-mini', 'What is trending on X?', { search: true });
67
+ ```
68
+
69
+ **Setup:**
70
+ 1. Export your Solana wallet key: `export SOLANA_WALLET_KEY="your-bs58-key"`
71
+ 2. Fund with USDC on Solana mainnet
72
+ 3. That's it — payments are automatic via x402
73
+
74
+ **Supported endpoint:** `https://sol.blockrun.ai/api`
75
+ **Payment:** Solana USDC (SPL, mainnet)
45
76
 
46
77
  ## How It Works
47
78
 
@@ -59,12 +90,10 @@ For Solana, set `BLOCKRUN_SOLANA_KEY` environment variable with your base58-enco
59
90
  | Model | Input Price | Output Price |
60
91
  |-------|-------------|--------------|
61
92
  | `openai/gpt-5.2` | $1.75/M | $14.00/M |
62
- | `openai/gpt-5.1` | $1.25/M | $10.00/M |
63
- | `openai/gpt-5` | $1.25/M | $10.00/M |
64
93
  | `openai/gpt-5-mini` | $0.25/M | $2.00/M |
65
94
  | `openai/gpt-5-nano` | $0.05/M | $0.40/M |
66
95
  | `openai/gpt-5.2-pro` | $21.00/M | $168.00/M |
67
- | `openai/gpt-5-pro` | $15.00/M | $120.00/M |
96
+ | `openai/gpt-5.2-codex` | $1.75/M | $14.00/M |
68
97
 
69
98
  ### OpenAI GPT-4 Family
70
99
  | Model | Input Price | Output Price |
@@ -87,16 +116,21 @@ For Solana, set `BLOCKRUN_SOLANA_KEY` environment variable with your base58-enco
87
116
  ### Anthropic Claude
88
117
  | Model | Input Price | Output Price |
89
118
  |-------|-------------|--------------|
119
+ | `anthropic/claude-opus-4.6` | $5.00/M | $25.00/M |
120
+ | `anthropic/claude-opus-4.5` | $5.00/M | $25.00/M |
90
121
  | `anthropic/claude-opus-4` | $15.00/M | $75.00/M |
122
+ | `anthropic/claude-sonnet-4.6` | $3.00/M | $15.00/M |
91
123
  | `anthropic/claude-sonnet-4` | $3.00/M | $15.00/M |
92
124
  | `anthropic/claude-haiku-4.5` | $1.00/M | $5.00/M |
93
125
 
94
126
  ### Google Gemini
95
127
  | Model | Input Price | Output Price |
96
128
  |-------|-------------|--------------|
97
- | `google/gemini-3-pro-preview` | $2.00/M | $12.00/M |
129
+ | `google/gemini-3.1-pro` | $2.00/M | $12.00/M |
130
+ | `google/gemini-3-flash-preview` | $0.50/M | $3.00/M |
98
131
  | `google/gemini-2.5-pro` | $1.25/M | $10.00/M |
99
- | `google/gemini-2.5-flash` | $0.15/M | $0.60/M |
132
+ | `google/gemini-2.5-flash` | $0.30/M | $2.50/M |
133
+ | `google/gemini-2.5-flash-lite` | $0.10/M | $0.40/M |
100
134
 
101
135
  ### DeepSeek
102
136
  | Model | Input Price | Output Price |
@@ -105,17 +139,34 @@ For Solana, set `BLOCKRUN_SOLANA_KEY` environment variable with your base58-enco
105
139
  | `deepseek/deepseek-reasoner` | $0.28/M | $0.42/M |
106
140
 
107
141
  ### xAI Grok
108
- | Model | Input Price | Output Price |
109
- |-------|-------------|--------------|
110
- | `xai/grok-3` | $3.00/M | $15.00/M |
111
- | `xai/grok-3-fast` | $5.00/M | $25.00/M |
112
- | `xai/grok-3-mini` | $0.30/M | $0.50/M |
142
+ | Model | Input Price | Output Price | Context | Notes |
143
+ |-------|-------------|--------------|---------|-------|
144
+ | `xai/grok-3` | $3.00/M | $15.00/M | 131K | Flagship |
145
+ | `xai/grok-3-mini` | $0.30/M | $0.50/M | 131K | Fast & affordable |
146
+ | `xai/grok-4-1-fast-reasoning` | $0.20/M | $0.50/M | **2M** | Latest, chain-of-thought |
147
+ | `xai/grok-4-1-fast-non-reasoning` | $0.20/M | $0.50/M | **2M** | Latest, direct response |
148
+ | `xai/grok-4-fast-reasoning` | $0.20/M | $0.50/M | **2M** | Step-by-step reasoning |
149
+ | `xai/grok-4-fast-non-reasoning` | $0.20/M | $0.50/M | **2M** | Quick responses |
150
+ | `xai/grok-code-fast-1` | $0.20/M | $1.50/M | 256K | Code generation |
151
+ | `xai/grok-4-0709` | $0.20/M | $1.50/M | 256K | Premium quality |
152
+ | `xai/grok-2-vision` | $2.00/M | $10.00/M | 32K | Vision capabilities |
113
153
 
114
154
  ### Moonshot Kimi
115
155
  | Model | Input Price | Output Price |
116
156
  |-------|-------------|--------------|
117
157
  | `moonshot/kimi-k2.5` | $0.60/M | $3.00/M |
118
158
 
159
+ ### MiniMax
160
+ | Model | Input Price | Output Price |
161
+ |-------|-------------|--------------|
162
+ | `minimax/minimax-m2.5` | $0.30/M | $1.20/M |
163
+
164
+ ### NVIDIA (Free & Hosted)
165
+ | Model | Input Price | Output Price | Notes |
166
+ |-------|-------------|--------------|-------|
167
+ | `nvidia/gpt-oss-120b` | **FREE** | **FREE** | OpenAI open-weight 120B (Apache 2.0) |
168
+ | `nvidia/kimi-k2.5` | $0.60/M | $3.00/M | Moonshot 1T MoE with vision |
169
+
119
170
  ### E2E Verified Models
120
171
 
121
172
  All models below have been tested end-to-end via the TypeScript SDK (Feb 2026):
@@ -123,10 +174,12 @@ All models below have been tested end-to-end via the TypeScript SDK (Feb 2026):
123
174
  | Provider | Model | Status |
124
175
  |----------|-------|--------|
125
176
  | OpenAI | `openai/gpt-4o-mini` | Passed |
177
+ | OpenAI | `openai/gpt-5.2-codex` | Passed |
178
+ | Anthropic | `anthropic/claude-opus-4.6` | Passed |
126
179
  | Anthropic | `anthropic/claude-sonnet-4` | Passed |
127
180
  | Google | `google/gemini-2.5-flash` | Passed |
128
181
  | DeepSeek | `deepseek/deepseek-chat` | Passed |
129
- | xAI | `xai/grok-3-fast` | Passed |
182
+ | xAI | `xai/grok-3` | Passed |
130
183
  | Moonshot | `moonshot/kimi-k2.5` | Passed |
131
184
 
132
185
  ### Image Generation
@@ -206,6 +259,47 @@ const response2 = await client.chat('anthropic/claude-sonnet-4', 'Write a haiku'
206
259
  });
207
260
  ```
208
261
 
262
+ ### Smart Routing (ClawRouter)
263
+
264
+ 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).
265
+
266
+ ```typescript
267
+ import { LLMClient } from '@blockrun/llm';
268
+
269
+ const client = new LLMClient();
270
+
271
+ // Auto-route to cheapest capable model
272
+ const result = await client.smartChat('What is 2+2?');
273
+ console.log(result.response); // '4'
274
+ console.log(result.model); // 'google/gemini-2.5-flash'
275
+ console.log(result.routing.tier); // 'SIMPLE'
276
+ console.log(`Saved ${(result.routing.savings * 100).toFixed(0)}%`); // 'Saved 78%'
277
+
278
+ // Routing profiles
279
+ const free = await client.smartChat('Hello!', { routingProfile: 'free' }); // Zero cost
280
+ const eco = await client.smartChat('Explain AI', { routingProfile: 'eco' }); // Budget optimized
281
+ const auto = await client.smartChat('Code review', { routingProfile: 'auto' }); // Balanced (default)
282
+ const premium = await client.smartChat('Write a legal brief', { routingProfile: 'premium' }); // Best quality
283
+ ```
284
+
285
+ **Routing Profiles:**
286
+
287
+ | Profile | Description | Best For |
288
+ |---------|-------------|----------|
289
+ | `free` | NVIDIA free models only | Testing, simple queries |
290
+ | `eco` | Budget-optimized | Cost-sensitive workloads |
291
+ | `auto` | Intelligent routing (default) | General use |
292
+ | `premium` | Best quality models | Critical tasks |
293
+
294
+ **Tiers:**
295
+
296
+ | Tier | Example Tasks | Typical Models |
297
+ |------|---------------|----------------|
298
+ | SIMPLE | Greetings, math, lookups | Gemini Flash, GPT-4o-mini |
299
+ | MEDIUM | Explanations, summaries | GPT-4o, Claude Sonnet |
300
+ | COMPLEX | Analysis, code generation | GPT-5.2, Claude Opus |
301
+ | REASONING | Multi-step logic, planning | o3, DeepSeek Reasoner |
302
+
209
303
  ### Full Chat Completion
210
304
 
211
305
  ```typescript
@@ -267,9 +361,8 @@ const client = new LLMClient({
267
361
 
268
362
  | Variable | Description |
269
363
  |----------|-------------|
270
- | `BASE_CHAIN_WALLET_KEY` | Your Base chain wallet private key (for Base) |
271
- | `BLOCKRUN_SOLANA_KEY` | Your Solana wallet secret key - base58 (for Solana) |
272
- | `BLOCKRUN_NETWORK` | Default network: `base` or `solana` (optional, default: base) |
364
+ | `BASE_CHAIN_WALLET_KEY` | Your Base chain wallet private key (for Base / `LLMClient`) |
365
+ | `SOLANA_WALLET_KEY` | Your Solana wallet secret key - bs58 encoded (for `SolanaLLMClient`) |
273
366
  | `BLOCKRUN_API_URL` | API endpoint (optional, default: https://blockrun.ai/api) |
274
367
 
275
368
  ## Error Handling
@@ -331,11 +424,11 @@ BASE_CHAIN_WALLET_KEY=0x...
331
424
  ### Solana
332
425
  1. Create a Solana wallet (Phantom, Backpack, Solflare, etc.)
333
426
  2. Get USDC on Solana for API payments
334
- 3. Export your secret key and set as `BLOCKRUN_SOLANA_KEY`
427
+ 3. Export your secret key and set as `SOLANA_WALLET_KEY`
335
428
 
336
429
  ```bash
337
430
  # .env
338
- BLOCKRUN_SOLANA_KEY=...your_base58_secret_key
431
+ SOLANA_WALLET_KEY=...your_bs58_secret_key
339
432
  ```
340
433
 
341
434
  Note: Solana transactions are gasless for the user - the CDP facilitator pays for transaction fees.
@@ -389,6 +482,12 @@ import {
389
482
  type ChatResponse,
390
483
  type ChatOptions,
391
484
  type Model,
485
+ // Smart routing types
486
+ type SmartChatOptions,
487
+ type SmartChatResponse,
488
+ type RoutingDecision,
489
+ type RoutingProfile,
490
+ type RoutingTier,
392
491
  APIError,
393
492
  PaymentError,
394
493
  } from '@blockrun/llm';
@@ -397,9 +496,9 @@ import {
397
496
  ## Links
398
497
 
399
498
  - [Website](https://blockrun.ai)
400
- - [Documentation](https://docs.blockrun.ai)
401
- - [GitHub](https://github.com/blockrun/blockrun-llm-ts)
402
- - [Discord](https://discord.gg/blockrun)
499
+ - [Documentation](https://github.com/BlockRunAI/awesome-blockrun/tree/main/docs)
500
+ - [GitHub](https://github.com/blockrunai/blockrun-llm-ts)
501
+ - [Telegram](https://t.me/+mroQv4-4hGgzOGUx)
403
502
 
404
503
  ## License
405
504