@node-llm/core 0.5.0 → 0.7.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 (107) hide show
  1. package/README.md +83 -421
  2. package/dist/chat/Chat.d.ts +5 -0
  3. package/dist/chat/Chat.d.ts.map +1 -1
  4. package/dist/chat/Chat.js +31 -7
  5. package/dist/chat/ChatOptions.d.ts +3 -0
  6. package/dist/chat/ChatOptions.d.ts.map +1 -1
  7. package/dist/chat/ChatResponse.d.ts +5 -1
  8. package/dist/chat/ChatResponse.d.ts.map +1 -1
  9. package/dist/chat/ChatResponse.js +6 -1
  10. package/dist/chat/Stream.d.ts.map +1 -1
  11. package/dist/chat/Stream.js +7 -1
  12. package/dist/config.d.ts +29 -0
  13. package/dist/config.d.ts.map +1 -0
  14. package/dist/config.js +11 -0
  15. package/dist/index.d.ts +2 -0
  16. package/dist/index.d.ts.map +1 -1
  17. package/dist/index.js +1 -0
  18. package/dist/llm.d.ts +20 -10
  19. package/dist/llm.d.ts.map +1 -1
  20. package/dist/llm.js +52 -23
  21. package/dist/models/ModelRegistry.d.ts +39 -12
  22. package/dist/models/ModelRegistry.d.ts.map +1 -1
  23. package/dist/models/ModelRegistry.js +50 -40
  24. package/dist/models/models.d.ts +972 -0
  25. package/dist/models/models.d.ts.map +1 -0
  26. package/dist/models/models.js +7076 -0
  27. package/dist/models/types.d.ts +50 -0
  28. package/dist/models/types.d.ts.map +1 -0
  29. package/dist/models/types.js +1 -0
  30. package/dist/providers/Provider.d.ts +7 -0
  31. package/dist/providers/Provider.d.ts.map +1 -1
  32. package/dist/providers/anthropic/AnthropicProvider.d.ts +1 -0
  33. package/dist/providers/anthropic/AnthropicProvider.d.ts.map +1 -1
  34. package/dist/providers/anthropic/AnthropicProvider.js +2 -3
  35. package/dist/providers/anthropic/Capabilities.d.ts +1 -37
  36. package/dist/providers/anthropic/Capabilities.d.ts.map +1 -1
  37. package/dist/providers/anthropic/Capabilities.js +59 -130
  38. package/dist/providers/anthropic/Chat.d.ts.map +1 -1
  39. package/dist/providers/anthropic/Chat.js +6 -2
  40. package/dist/providers/anthropic/Models.d.ts +1 -0
  41. package/dist/providers/anthropic/Models.d.ts.map +1 -1
  42. package/dist/providers/anthropic/Models.js +36 -41
  43. package/dist/providers/anthropic/Streaming.d.ts.map +1 -1
  44. package/dist/providers/anthropic/Streaming.js +10 -1
  45. package/dist/providers/anthropic/index.d.ts.map +1 -1
  46. package/dist/providers/anthropic/index.js +3 -2
  47. package/dist/providers/deepseek/Capabilities.d.ts +14 -0
  48. package/dist/providers/deepseek/Capabilities.d.ts.map +1 -0
  49. package/dist/providers/deepseek/Capabilities.js +52 -0
  50. package/dist/providers/deepseek/Chat.d.ts +8 -0
  51. package/dist/providers/deepseek/Chat.d.ts.map +1 -0
  52. package/dist/providers/deepseek/Chat.js +89 -0
  53. package/dist/providers/deepseek/DeepSeekProvider.d.ts +28 -0
  54. package/dist/providers/deepseek/DeepSeekProvider.d.ts.map +1 -0
  55. package/dist/providers/deepseek/DeepSeekProvider.js +38 -0
  56. package/dist/providers/deepseek/Models.d.ts +8 -0
  57. package/dist/providers/deepseek/Models.d.ts.map +1 -0
  58. package/dist/providers/deepseek/Models.js +67 -0
  59. package/dist/providers/deepseek/Streaming.d.ts +8 -0
  60. package/dist/providers/deepseek/Streaming.d.ts.map +1 -0
  61. package/dist/providers/deepseek/Streaming.js +74 -0
  62. package/dist/providers/deepseek/index.d.ts +7 -0
  63. package/dist/providers/deepseek/index.d.ts.map +1 -0
  64. package/dist/providers/deepseek/index.js +22 -0
  65. package/dist/providers/gemini/Capabilities.d.ts +28 -7
  66. package/dist/providers/gemini/Capabilities.d.ts.map +1 -1
  67. package/dist/providers/gemini/Capabilities.js +32 -20
  68. package/dist/providers/gemini/Chat.d.ts.map +1 -1
  69. package/dist/providers/gemini/Chat.js +9 -11
  70. package/dist/providers/gemini/GeminiProvider.d.ts +1 -0
  71. package/dist/providers/gemini/GeminiProvider.d.ts.map +1 -1
  72. package/dist/providers/gemini/GeminiProvider.js +1 -0
  73. package/dist/providers/gemini/Models.d.ts +1 -0
  74. package/dist/providers/gemini/Models.d.ts.map +1 -1
  75. package/dist/providers/gemini/Models.js +46 -26
  76. package/dist/providers/gemini/index.d.ts.map +1 -1
  77. package/dist/providers/gemini/index.js +3 -2
  78. package/dist/providers/openai/Capabilities.d.ts +4 -11
  79. package/dist/providers/openai/Capabilities.d.ts.map +1 -1
  80. package/dist/providers/openai/Capabilities.js +124 -121
  81. package/dist/providers/openai/Chat.d.ts.map +1 -1
  82. package/dist/providers/openai/Chat.js +19 -17
  83. package/dist/providers/openai/Embedding.d.ts.map +1 -1
  84. package/dist/providers/openai/Embedding.js +2 -1
  85. package/dist/providers/openai/Image.d.ts.map +1 -1
  86. package/dist/providers/openai/Image.js +2 -1
  87. package/dist/providers/openai/ModelDefinitions.d.ts +1 -24
  88. package/dist/providers/openai/ModelDefinitions.d.ts.map +1 -1
  89. package/dist/providers/openai/ModelDefinitions.js +1 -211
  90. package/dist/providers/openai/Models.d.ts +1 -0
  91. package/dist/providers/openai/Models.d.ts.map +1 -1
  92. package/dist/providers/openai/Models.js +46 -22
  93. package/dist/providers/openai/Moderation.d.ts.map +1 -1
  94. package/dist/providers/openai/Moderation.js +2 -1
  95. package/dist/providers/openai/OpenAIProvider.d.ts +1 -0
  96. package/dist/providers/openai/OpenAIProvider.d.ts.map +1 -1
  97. package/dist/providers/openai/OpenAIProvider.js +1 -0
  98. package/dist/providers/openai/Streaming.d.ts.map +1 -1
  99. package/dist/providers/openai/Streaming.js +5 -1
  100. package/dist/providers/openai/Transcription.d.ts.map +1 -1
  101. package/dist/providers/openai/Transcription.js +3 -2
  102. package/dist/providers/openai/index.d.ts.map +1 -1
  103. package/dist/providers/openai/index.js +5 -3
  104. package/dist/providers/openai/utils.d.ts +20 -0
  105. package/dist/providers/openai/utils.d.ts.map +1 -0
  106. package/dist/providers/openai/utils.js +25 -0
  107. package/package.json +1 -1
package/README.md CHANGED
@@ -1,494 +1,156 @@
1
+ <p align="left">
2
+ <img src="../../docs/assets/images/logo.jpg" alt="node-llm logo" width="300" />
3
+ </p>
4
+
1
5
  # @node-llm/core
2
6
 
3
7
  [![npm version](https://img.shields.io/npm/v/@node-llm/core.svg)](https://www.npmjs.com/package/@node-llm/core)
4
8
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
9
  [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
6
10
 
7
- A provider-agnostic LLM core for Node.js, heavily inspired by the elegant design of [ruby-llm](https://github.com/crmne/ruby_llm).
8
-
9
- `node-llm` focuses on clean abstractions, minimal magic, and a streaming-first design. It provides a unified interface to interact with various LLM providers without being locked into their specific SDKs.
11
+ **One unified interface for OpenAI, Anthropic, Gemini, DeepSeek, and local models.**
10
12
 
11
- ---
13
+ **node-llm** abstracts away the chaos of vendor-specific SDKs. It gives you a clean, streaming-first API with built-in support for Vision, Tools, and Structured Outputs.
12
14
 
13
- ## 🚀 Features
15
+ <br/>
14
16
 
15
- - **Provider-Agnostic**: Switch between OpenAI (GPT-4o), Anthropic (Claude 3.5), and Gemini (2.0) with a single line of config.
16
- - **Streaming-First**: Native `AsyncIterator` support for real-time token delivery.
17
- - **Tool Calling**: Automatic execution loop for model-requested functions (OpenAI, Anthropic, Gemini).
18
- - **Structured Output**: Strict Zod-based JSON schema enforcement across all major providers.
19
- - **Multi-modal & Smart Files**: Built-in support for Vision (images), Audio, and Documents (PDFs for Claude).
20
- - **Fluent API**: Chainable methods like `.withTool()` and `.withSchema()` for dynamic registration.
21
- - **Resilient**: Configurable retry logic and detailed error handling for API outages.
22
- - **Type-Safe**: Written in TypeScript with full ESM support.
23
-
24
- ---
17
+ <p align="left">
18
+ <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openai.svg" height="28" />
19
+ <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openai-text.svg" height="22" />
20
+ &nbsp;&nbsp;&nbsp;&nbsp;
21
+ <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/anthropic-text.svg" height="18" />
22
+ &nbsp;&nbsp;&nbsp;&nbsp;
23
+ <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/gemini-color.svg" height="28" />
24
+ <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/gemini-text.svg" height="20" />
25
+ &nbsp;&nbsp;&nbsp;&nbsp;
26
+ <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/deepseek-color.svg" height="28" />
27
+ <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/deepseek-text.svg" height="20" />
28
+ </p>
25
29
 
26
- ## 📦 Installation
27
-
28
- ```bash
29
- npm install @node-llm/core
30
- # or
31
- pnpm add @node-llm/core
32
- ```
30
+ <br/>
33
31
 
34
32
  ---
35
33
 
36
- ## 🛠️ Quick Start
37
-
38
- ### 1. Configure the Provider
34
+ ## Quick Example
39
35
 
40
36
  ```ts
41
37
  import { LLM } from "@node-llm/core";
42
- import "dotenv/config";
43
-
44
- LLM.configure({
45
- provider: "openai", // or "anthropic", "gemini"
46
- retry: { attempts: 3, delayMs: 500 },
47
- defaultModerationModel: "text-moderation-latest",
48
- defaultTranscriptionModel: "whisper-1",
49
- defaultEmbeddingModel: "text-embedding-3-small"
50
- });
51
- ```
52
-
53
- ### 2. Basic Chat
54
-
55
- ```ts
56
- const chat = LLM.chat("gpt-4o-mini", {
57
- systemPrompt: "You are a helpful assistant."
58
- });
59
-
60
- const response = await chat.ask("What is Node.js?");
61
38
 
62
- // Use as a string directly
63
- console.log(response);
39
+ // 1. Configure once
40
+ LLM.configure({ provider: "openai" });
64
41
 
65
- // Or access metadata (RubyLLM style)
66
- console.log(response.content);
67
- console.log(`Model: ${response.model_id}`);
68
- console.log(`Tokens: ${response.input_tokens} in, ${response.output_tokens} out`);
69
- ```
70
-
71
- ### 3. Streaming Responses
72
-
73
- ```ts
74
- for await (const chunk of chat.stream("Write a poem")) {
42
+ // 2. Chat with streaming
43
+ const chat = LLM.chat("gpt-4o");
44
+ for await (const chunk of chat.stream("Explain Node.js")) {
75
45
  process.stdout.write(chunk.content);
76
46
  }
77
47
  ```
78
48
 
79
- ### 4. Image Generation (Paint)
80
-
81
- Generate images and interact with them using a rich API.
82
-
83
- ```ts
84
- const image = await LLM.paint("a sunset over mountains", {
85
- model: "dall-e-3"
86
- });
87
-
88
- // Use as a URL string
89
- console.log(`URL: ${image}`);
90
-
91
- // Or use rich methods
92
- await image.save("sunset.png");
93
- console.log(`Format: ${image.mimeType}`);
94
- ```
49
+ ---
95
50
 
96
- ### 5. Token Usage Tracking
51
+ ## 🔮 Capabilities
97
52
 
98
- Track tokens for individual turns or the entire conversation.
53
+ ### 💬 Unified Chat
54
+ Stop rewriting code for every provider. `node-llm` normalizes inputs and outputs.
99
55
 
100
56
  ```ts
101
- const response = await chat.ask("Hello!");
102
-
103
- console.log(response.input_tokens); // 10
104
- console.log(response.output_tokens); // 5
105
-
106
- // Access aggregated usage for the whole session
107
- console.log(chat.totalUsage.total_tokens);
57
+ const chat = LLM.chat(); // Defaults to GPT-4o
58
+ await chat.ask("Hello world");
108
59
  ```
109
60
 
110
- ### 6. Embeddings
111
-
112
- Generate vector representations of text for semantic search, clustering, and similarity comparisons.
61
+ ### 👁️ Smart Vision & Files
62
+ Pass images, PDFs, or audio files directly. We handle the base64 encoding and MIME types.
113
63
 
114
64
  ```ts
115
- // Single text embedding
116
- const embedding = await LLM.embed("Ruby is a programmer's best friend");
117
-
118
- console.log(embedding.vector); // Array of floats (e.g., 1536 dimensions)
119
- console.log(embedding.dimensions); // 1536
120
- console.log(embedding.model); // "text-embedding-3-small"
121
- console.log(embedding.input_tokens); // Token count
122
-
123
- // Batch embeddings
124
- const embeddings = await LLM.embed([
125
- "First text",
126
- "Second text",
127
- "Third text"
128
- ]);
129
-
130
- console.log(embeddings.vectors); // Array of vectors
131
- console.log(embeddings.vectors.length); // 3
132
-
133
- // Custom model and dimensions
134
- const customEmbedding = await LLM.embed("Semantic search text", {
135
- model: "text-embedding-3-large",
136
- dimensions: 256 // Reduce dimensions for faster processing
65
+ await chat.ask("Analyze this interface", {
66
+ files: ["./screenshot.png", "./specs.pdf"]
137
67
  });
138
68
  ```
139
69
 
140
- ### 7. Audio Transcription (Transcribe)
141
-
142
- Convert audio files to text using specialized models like Whisper.
143
-
144
- ```ts
145
- const text = await LLM.transcribe("meeting.mp3");
146
- console.log(text);
147
- ```
148
-
149
- ### 7. Content Moderation (Moderate)
150
-
151
- Check if text content violates safety policies.
152
-
153
- ```ts
154
- const result = await LLM.moderate("I want to help everyone!");
155
- if (result.flagged) {
156
- console.log(`❌ Flagged for: ${result.flaggedCategories.join(", ")}`);
157
- } else {
158
- console.log("✅ Content appears safe");
159
- }
160
- ```
161
-
162
- Learn how to implement [custom risk thresholds](../../examples/openai/12-risk-assessment.mjs) for more granular control.
163
-
164
- ### 8. Chat Event Handlers
165
-
166
- Hook into the chat lifecycle for logging, UI updates, or auditing.
167
-
168
- ```ts
169
- chat
170
- .onNewMessage(() => console.log("AI started typing..."))
171
- .onToolCall((tool) => console.log(`Calling ${tool.function.name}...`))
172
- .onToolResult((result) => console.log(`Tool returned: ${result}`))
173
- .onEndMessage((response) => console.log(`Done. Usage: ${response.total_tokens}`));
174
-
175
- await chat.ask("What's the weather?");
176
- ```
177
-
178
- ### 9. System Prompts (Instructions)
179
-
180
- Guide the AI's behavior, personality, or constraints.
181
-
182
- ```ts
183
- // Set initial instructions
184
- chat.withInstructions("You are a helpful assistant that explains simply.");
185
-
186
- // Update instructions mid-conversation (replace: true removes previous ones)
187
- chat.withInstructions("Now assume the persona of a pirate.", { replace: true });
188
-
189
- await chat.ask("Hello");
190
- // => "Ahoy matey!"
191
- ```
192
-
193
- ### 10. Temperature Control (Creativity)
194
-
195
- Adjust the randomness of the model's responses.
196
-
197
- ```ts
198
- // Factual (0.0 - 0.3)
199
- const factual = LLM.chat("gpt-4o").withTemperature(0.2);
200
-
201
- // Creative (0.7 - 1.0)
202
- const creative = LLM.chat("gpt-4o").withTemperature(0.9);
203
- ```
204
-
205
- ---
206
-
207
- ## 📚 Examples
208
-
209
- Check the [examples](../../examples) directory for focused scripts organized by provider:
210
-
211
- ### OpenAI Examples
212
-
213
- #### 💬 Chat
214
- | Example | Description |
215
- | :--- | :--- |
216
- | [Basic & Streaming](../../examples/openai/chat/basic.mjs) | Standard completions and real-time streaming |
217
- | [System Instructions](../../examples/openai/chat/instructions.mjs) | Tuning behavior with system prompts and temperature |
218
- | [Tool Calling](../../examples/openai/chat/tools.mjs) | Automatic execution of model-requested functions |
219
- | [Parallel Tool Calling](../../examples/openai/chat/parallel-tools.mjs) | Executing multiple tools in a single turn |
220
- | [Lifecycle Events](../../examples/openai/chat/events.mjs) | Hooks for specific chat events (onNewMessage, onToolCall) |
221
- | [Token Usage](../../examples/openai/chat/usage.mjs) | Tracking costs and token counts |
222
- | [Max Tokens](../../examples/openai/chat/max-tokens.mjs) | Limiting response length with `maxTokens` |
223
- | [Structured Output](../../examples/openai/chat/structured.mjs) | Zod-based JSON schema enforcement |
224
-
225
- #### 🖼️ Multimodal
226
- | Example | Description |
227
- | :--- | :--- |
228
- | [Vision Analysis](../../examples/openai/multimodal/vision.mjs) | Analyzing images via URLs |
229
- | [Multi-Image Analysis](../../examples/openai/multimodal/multi-image.mjs) | Comparing multiple images in one request |
230
- | [File Context](../../examples/openai/multimodal/files.mjs) | Reading and analyzing local project files |
231
- | [Audio Transcription](../../examples/openai/multimodal/transcribe.mjs) | Converting audio files to text (Whisper) |
232
-
233
- #### 🎨 Images
234
- | Example | Description |
235
- | :--- | :--- |
236
- | [Generate & Save](../../examples/openai/images/generate.mjs) | Creating images with DALL-E 3 and saving to disk |
237
-
238
- #### 🛡️ Safety
239
- | Example | Description |
240
- | :--- | :--- |
241
- | [Moderation](../../examples/openai/safety/moderation.mjs) | Content safety checks and risk assessment |
242
-
243
- #### 🧠 Discovery
244
- | Example | Description |
245
- | :--- | :--- |
246
- | [Models & Capabilities](../../examples/openai/discovery/models.mjs) | Listing models and inspecting their specs |
247
- | [Embeddings](../../examples/openai/embeddings/create.mjs) | Generating semantic vector embeddings |
248
-
249
- ### Gemini Examples
250
-
251
- #### 💬 Chat
252
- | Example | Description |
253
- | :--- | :--- |
254
- | [Basic & Streaming](../../examples/gemini/chat/basic.mjs) | Standard completions and real-time streaming |
255
- | [System Instructions](../../examples/gemini/chat/instructions.mjs) | Behavior tuning and creativity control |
256
- | [Tool Calling](../../examples/gemini/chat/tools.mjs) | Function calling with automatic execution |
257
- | [Lifecycle Events](../../examples/gemini/chat/events.mjs) | Event hooks for chat interactions |
258
- | [Token Usage](../../examples/gemini/chat/usage.mjs) | Tracking conversation costs |
259
- | [Structured Output](../../examples/gemini/chat/structured.mjs) | Native JSON schema support |
260
-
261
- #### 🖼️ Multimodal
262
- | Example | Description |
263
- | :--- | :--- |
264
- | [Vision Analysis](../../examples/gemini/multimodal/vision.mjs) | Understanding images |
265
- | [File Context](../../examples/gemini/multimodal/files.mjs) | Reading multiple local files |
266
- | [Audio Transcription](../../examples/gemini/multimodal/transcribe.mjs) | Native audio understanding |
267
-
268
- #### 🎨 Images
269
- | Example | Description |
270
- | :--- | :--- |
271
- | [Generate & Save](../../examples/gemini/images/generate.mjs) | Creating images with Imagen |
272
-
273
- #### 🧠 Discovery
274
- | Example | Description |
275
- | :--- | :--- |
276
- | [Models & Capabilities](../../examples/gemini/discovery/models.mjs) | Listing models and inspecting their specs |
277
- | [Embeddings](../../examples/gemini/embeddings/create.mjs) | Generating semantic vector embeddings |
278
-
279
- ### Anthropic Examples
280
-
281
- #### 💬 Chat
282
- | Example | Description |
283
- | :--- | :--- |
284
- | [Basic & Streaming](../../examples/anthropic/chat/basic.mjs) | Chatting with Claude 3.5 Models |
285
- | [Tool Calling](../../examples/anthropic/chat/tools.mjs) | Native tool use with automatic execution |
286
- | [Parallel Tools](../../examples/anthropic/chat/parallel-tools.mjs) | Handling multiple tool requests in one turn |
287
- | [Token Usage](../../examples/anthropic/chat/usage.mjs) | Tracking Claude-specific token metrics |
288
- | [Structured Output](../../examples/anthropic/chat/structured.mjs) | Prompt-based JSON schema enforcement |
289
-
290
- #### 🖼️ Multimodal
291
- | Example | Description |
292
- | :--- | :--- |
293
- | [Vision Analysis](../../examples/anthropic/multimodal/vision.mjs) | Analyzing images with Claude Vision |
294
- | [PDF Analysis](../../examples/anthropic/multimodal/pdf.mjs) | Native PDF document processing |
295
- | [File Context](../../examples/anthropic/multimodal/files.mjs) | Passing local file contents to Claude |
296
-
297
-
298
- To run an example:
299
- ```bash
300
- node examples/openai/01-basic-chat.mjs
301
- ```
302
-
303
- ---
304
-
305
- ## 🔌 Advanced Usage
306
-
307
- ### Tool Calling (Function Calling)
308
-
309
- Define your tools and let the library handle the execution loop automatically.
70
+ ### 🛠️ Auto-Executing Tools
71
+ Define tools once, and the library manages the execution loop for you.
310
72
 
311
73
  ```ts
312
- const weatherTool = {
74
+ const tools = [{
313
75
  type: 'function',
314
- function: {
315
- name: 'get_weather',
316
- parameters: {
317
- type: 'object',
318
- properties: { location: { type: 'string' } }
319
- }
320
- },
321
- handler: async ({ location }) => {
322
- return JSON.stringify({ location, temp: 22, unit: 'celsius' });
323
- }
324
- };
325
-
326
- // Use the fluent API to add tools on the fly
327
- const reply = await chat
328
- .withTool(weatherTool)
329
- .ask("What is the weather in London?");
330
- ```
331
-
332
- ### Structured Output (Schemas)
76
+ function: { name: 'get_weather', ... },
77
+ handler: async ({ loc }) => `Sunny in ${loc}`
78
+ }];
333
79
 
334
- Ensure the AI returns data exactly matching a specific structure. Supports strict schema validation using Zod.
80
+ await chat.withTools(tools).ask("Weather in Tokyo?");
81
+ ```
335
82
 
336
- **Using Zod (Recommended):**
83
+ ### Structured Output
84
+ Get type-safe JSON back using **Zod** schemas.
337
85
 
338
86
  ```ts
339
- import { LLM, z } from "@node-llm/core";
87
+ import { z } from "zod";
340
88
 
341
- const personSchema = z.object({
342
- name: z.string(),
343
- age: z.number(),
344
- hobbies: z.array(z.string())
345
- });
89
+ const Product = z.object({ name: z.string(), price: z.number() });
90
+ const res = await chat.withSchema(Product).ask("Generate a gadget");
346
91
 
347
- const response = await chat
348
- .withSchema(personSchema)
349
- .ask("Generate a person named Alice who likes hiking");
350
-
351
- // Type-safe access to parsed data
352
- const person = response.parsed;
353
- console.log(person.name); // "Alice"
92
+ console.log(res.parsed.name); // Type-safe access
354
93
  ```
355
94
 
356
- **Using Manual JSON Schema:**
357
-
95
+ ### 🎨 Image Generation
358
96
  ```ts
359
- const schema = {
360
- type: "object",
361
- properties: {
362
- name: { type: "string" },
363
- age: { type: "integer" }
364
- },
365
- required: ["name", "age"],
366
- additionalProperties: false // Required for strict mode in OpenAI
367
- };
368
-
369
- const response = await chat
370
- .withSchema(schema)
371
- .ask("Generate a person");
372
-
373
- console.log(response.parsed); // { name: "...", age: ... }
97
+ await LLM.paint("A cyberpunk city in rain");
374
98
  ```
375
99
 
376
- ### JSON Mode
377
-
378
- Guarantee valid JSON output without enforcing a strict schema.
379
-
100
+ ### 🎤 Audio Transcription
380
101
  ```ts
381
- chat.withRequestOptions({
382
- responseFormat: { type: "json_object" }
383
- });
384
-
385
- const response = await chat.ask("Generate a JSON object with a greeting");
386
- console.log(response.parsed); // { greeting: "..." }
102
+ await LLM.transcribe("meeting-recording.wav");
387
103
  ```
388
104
 
389
-
390
- ### Multi-modal & File Support
391
-
392
- Pass local paths or URLs directly. The library handles reading, MIME detection, and encoding for a wide variety of file types.
393
-
394
- **Supported File Types:**
395
- - **Images**: `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`
396
- - **Videos**: `.mp4`, `.mpeg`, `.mov`
397
- - **Audio**: `.wav`, `.mp3`
398
- - **Documents**: `.csv`, `.json`
399
- - **Code**: `.js`, `.mjs`, `.cjs`, `.ts`, `.py`, `.rb`, `.go`, `.java`, `.c`, `.cpp`, `.rs`, `.swift`, `.kt`
400
- - **Text**: `.txt`, `.md`, `.html`, `.css`, `.xml`, `.yml`, `.yaml`
105
+ ### 🧠 Deep Reasoning
106
+ Access the thought process of models like **DeepSeek R1** or **OpenAI o1/o3** using the `.reasoning` field.
401
107
 
402
108
  ```ts
403
- // Vision
404
- await chat.ask("What's in this image?", {
405
- files: ["./screenshot.png"]
406
- });
407
-
408
- // Audio
409
- await chat.ask("Transcribe this", {
410
- files: ["./meeting.mp3"]
411
- });
412
-
413
- // Code Analysis
414
- await chat.ask("Explain this code", {
415
- files: ["./app.ts"]
416
- });
109
+ const chat = LLM.chat("deepseek-reasoner");
110
+ const res = await chat.ask("Solve a complex puzzle");
417
111
 
418
- // Multiple files at once
419
- await chat.ask("Analyze these files", {
420
- files: ["diagram.png", "data.json", "notes.txt"]
421
- });
112
+ console.log(res.reasoning); // Output the model's inner thought process
113
+ console.log(res.content); // Output the final answer
422
114
  ```
423
115
 
424
- ### Custom HTTP Headers (Proxies/Observability)
425
-
426
- Inject custom headers into requests, useful for tools like Helicone or Portkey.
427
-
428
- ```ts
429
- chat.withRequestOptions({
430
- headers: {
431
- "Helicone-Auth": "Bearer my-key",
432
- "X-Custom-Trace": "123"
433
- }
434
- });
435
- ```
436
-
437
- ### Model Capabilities & Pricing
438
-
439
- Get up-to-date information about context windows, pricing, and capabilities directly from the Parsera API.
116
+ ---
440
117
 
441
- ```javascript
442
- // Refresh model information from the API
443
- await LLM.models.refresh();
118
+ ## 📋 Supported Providers
444
119
 
445
- // Use the data programmatically
446
- const model = LLM.models.find("gpt-4o-mini");
447
- console.log(model.context_window); // => 128000
448
- console.log(model.capabilities); // => ["function_calling", "structured_output", "streaming", "batch"]
449
- console.log(model.pricing.text_tokens.standard.input_per_million); // => 0.15
450
- ```
120
+ | Provider | Supported Features |
121
+ | :--- | :--- |
122
+ | <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openai.svg" height="18"> <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openai-text.svg" height="18"> | Chat, Streaming, Tools, Vision, Audio, Images, Transcription, **Reasoning** |
123
+ | <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/gemini-color.svg" height="18"> <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/gemini-text.svg" height="14"> | Chat, Streaming, Tools, Vision, Audio, Video, Embeddings |
124
+ | <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/anthropic-text.svg" height="12"> | Chat, Streaming, Tools, Vision, PDF Support, Structured Output |
125
+ | <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/deepseek-color.svg" height="18"> <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/deepseek-text.svg" height="14"> | Chat (V3), **Reasoning (R1)**, Tools, Streaming, Structured Output |
451
126
 
452
127
  ---
453
128
 
454
- ## 📋 Supported Providers
129
+ ## 🚀 Why use this over official SDKs?
455
130
 
456
- | Provider | Status | Notes |
131
+ | Feature | node-llm | Official SDKs |
457
132
  | :--- | :--- | :--- |
458
- | **OpenAI** | Supported | Chat, Streaming, Tools, Vision, Audio, Images, Transcription, Moderation |
459
- | **Gemini** | Supported | Chat, Streaming, Tools, Vision, Audio, Video, Embeddings, Transcription |
460
- | **Anthropic** | Supported | Chat, Streaming, Tools, Vision, PDF Support, Structured Output |
461
- | **Azure OpenAI** | 🏗️ Roadmap | Coming soon |
133
+ | **API Style** | Consistent across all providers | Different for everyone |
134
+ | **Streaming** | Standard `AsyncIterator` | Callbacks/Events/Streams mixed |
135
+ | **Tools** | Automatic Execution Loop | Manual parsing & recursion |
136
+ | **Files** | Path string or URL | Base64 buffers / distinct types |
137
+ | **Retries** | Built-in & Configurable | Varies by SDK |
462
138
 
463
139
  ---
464
140
 
465
- ## 🧠 Design Philosophy
141
+ ## 📚 Documentation & Installation
466
142
 
467
- - **Explicit over Implicit**: No hidden side effects.
468
- - **Minimal Dependencies**: Lightweight core with zero bloat.
469
- - **Developer Experience**: Inspired by Ruby's elegance, built for Node's performance.
470
- - **Production Ready**: Built-in retries and strict type checking.
471
-
472
- ---
143
+ ```bash
144
+ npm install @node-llm/core
145
+ ```
473
146
 
474
- `node-llm` features a comprehensive test suite including high-level integration tests and granular unit tests.
147
+ **[View Full Documentation ↗](https://node-llm.eshaiju.com/)**
475
148
 
476
- - **Unit Tests**: Test core logic and provider handlers in isolation without hitting any APIs.
477
- ```bash
478
- npm run test:unit
479
- ```
149
+ ---
480
150
 
481
- - **Integration Tests (VCR)**: Uses Polly.js to record and replay real LLM interactions.
482
- - **Replay Mode (Default)**: Runs against recorded cassettes. Fast and requires no API keys.
483
- ```bash
484
- npm run test:integration
485
- ```
486
- - **Record Mode**: Update cassettes by hitting real APIs (requires API keys).
487
- ```bash
488
- VCR_MODE=record npm run test:integration
489
- ```
151
+ ## 🫶 Credits
490
152
 
491
- *All recordings are automatically scrubbed of sensitive data (API keys, org IDs) before being saved to disk.*
153
+ Heavily inspired by the elegant design of [RubyLLM](https://rubyllm.com/).
492
154
 
493
155
  ---
494
156
 
@@ -74,6 +74,11 @@ export declare class Chat {
74
74
  headers?: Record<string, string>;
75
75
  responseFormat?: any;
76
76
  }): this;
77
+ /**
78
+ * Set provider-specific parameters.
79
+ * These will be merged into the final request payload.
80
+ */
81
+ withParams(params: Record<string, any>): this;
77
82
  /**
78
83
  * Enforce a specific schema for the output.
79
84
  * Can accept a Schema object or a Zod schema/JSON Schema directly.
@@ -1 +1 @@
1
- {"version":3,"file":"Chat.d.ts","sourceRoot":"","sources":["../../src/chat/Chat.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAI3D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,qBAAa,IAAI;IAKb,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,QAAQ,CAAW;gBAGR,QAAQ,EAAE,QAAQ,EAC3B,KAAK,EAAE,MAAM,EACJ,OAAO,GAAE,WAAgB;IAmB5C;;OAEG;IACH,IAAI,OAAO,IAAI,SAAS,OAAO,EAAE,CAEhC;IAED;;OAEG;IACH,IAAI,UAAU,IAAI,KAAK,CActB;IAED;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI;IAIzB;;;;;;;OAOG;IACH,SAAS,CAAC,KAAK,EAAE,CAAC,IAAI,GAAG,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IA2BvE;;;;OAIG;IACH,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAmB5E;;OAEG;IACH,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAI5E;;;OAGG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKnC;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAK9B;;;OAGG;IACH,kBAAkB,CAAC,OAAO,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,cAAc,CAAC,EAAE,GAAG,CAAA;KAAE,GAAG,IAAI;IAU7F;;;OAGG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI;IAkB9E,YAAY,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI;IAKvC,YAAY,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,IAAI,GAAG,IAAI;IAKlE,UAAU,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,GAAG,IAAI;IAKlD,YAAY,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,GAAG,IAAI;IAKlD;;OAEG;IACG,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,EAAE,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA8KrF;;OAEG;IACI,MAAM,CAAC,OAAO,EAAE,MAAM;CAI9B"}
1
+ {"version":3,"file":"Chat.d.ts","sourceRoot":"","sources":["../../src/chat/Chat.ts"],"names":[],"mappings":"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"}