@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.
- package/README.md +83 -421
- package/dist/chat/Chat.d.ts +5 -0
- package/dist/chat/Chat.d.ts.map +1 -1
- package/dist/chat/Chat.js +31 -7
- package/dist/chat/ChatOptions.d.ts +3 -0
- package/dist/chat/ChatOptions.d.ts.map +1 -1
- package/dist/chat/ChatResponse.d.ts +5 -1
- package/dist/chat/ChatResponse.d.ts.map +1 -1
- package/dist/chat/ChatResponse.js +6 -1
- package/dist/chat/Stream.d.ts.map +1 -1
- package/dist/chat/Stream.js +7 -1
- package/dist/config.d.ts +29 -0
- package/dist/config.d.ts.map +1 -0
- package/dist/config.js +11 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/llm.d.ts +20 -10
- package/dist/llm.d.ts.map +1 -1
- package/dist/llm.js +52 -23
- package/dist/models/ModelRegistry.d.ts +39 -12
- package/dist/models/ModelRegistry.d.ts.map +1 -1
- package/dist/models/ModelRegistry.js +50 -40
- package/dist/models/models.d.ts +972 -0
- package/dist/models/models.d.ts.map +1 -0
- package/dist/models/models.js +7076 -0
- package/dist/models/types.d.ts +50 -0
- package/dist/models/types.d.ts.map +1 -0
- package/dist/models/types.js +1 -0
- package/dist/providers/Provider.d.ts +7 -0
- package/dist/providers/Provider.d.ts.map +1 -1
- package/dist/providers/anthropic/AnthropicProvider.d.ts +1 -0
- package/dist/providers/anthropic/AnthropicProvider.d.ts.map +1 -1
- package/dist/providers/anthropic/AnthropicProvider.js +2 -3
- package/dist/providers/anthropic/Capabilities.d.ts +1 -37
- package/dist/providers/anthropic/Capabilities.d.ts.map +1 -1
- package/dist/providers/anthropic/Capabilities.js +59 -130
- package/dist/providers/anthropic/Chat.d.ts.map +1 -1
- package/dist/providers/anthropic/Chat.js +6 -2
- package/dist/providers/anthropic/Models.d.ts +1 -0
- package/dist/providers/anthropic/Models.d.ts.map +1 -1
- package/dist/providers/anthropic/Models.js +36 -41
- package/dist/providers/anthropic/Streaming.d.ts.map +1 -1
- package/dist/providers/anthropic/Streaming.js +10 -1
- package/dist/providers/anthropic/index.d.ts.map +1 -1
- package/dist/providers/anthropic/index.js +3 -2
- package/dist/providers/deepseek/Capabilities.d.ts +14 -0
- package/dist/providers/deepseek/Capabilities.d.ts.map +1 -0
- package/dist/providers/deepseek/Capabilities.js +52 -0
- package/dist/providers/deepseek/Chat.d.ts +8 -0
- package/dist/providers/deepseek/Chat.d.ts.map +1 -0
- package/dist/providers/deepseek/Chat.js +89 -0
- package/dist/providers/deepseek/DeepSeekProvider.d.ts +28 -0
- package/dist/providers/deepseek/DeepSeekProvider.d.ts.map +1 -0
- package/dist/providers/deepseek/DeepSeekProvider.js +38 -0
- package/dist/providers/deepseek/Models.d.ts +8 -0
- package/dist/providers/deepseek/Models.d.ts.map +1 -0
- package/dist/providers/deepseek/Models.js +67 -0
- package/dist/providers/deepseek/Streaming.d.ts +8 -0
- package/dist/providers/deepseek/Streaming.d.ts.map +1 -0
- package/dist/providers/deepseek/Streaming.js +74 -0
- package/dist/providers/deepseek/index.d.ts +7 -0
- package/dist/providers/deepseek/index.d.ts.map +1 -0
- package/dist/providers/deepseek/index.js +22 -0
- package/dist/providers/gemini/Capabilities.d.ts +28 -7
- package/dist/providers/gemini/Capabilities.d.ts.map +1 -1
- package/dist/providers/gemini/Capabilities.js +32 -20
- package/dist/providers/gemini/Chat.d.ts.map +1 -1
- package/dist/providers/gemini/Chat.js +9 -11
- package/dist/providers/gemini/GeminiProvider.d.ts +1 -0
- package/dist/providers/gemini/GeminiProvider.d.ts.map +1 -1
- package/dist/providers/gemini/GeminiProvider.js +1 -0
- package/dist/providers/gemini/Models.d.ts +1 -0
- package/dist/providers/gemini/Models.d.ts.map +1 -1
- package/dist/providers/gemini/Models.js +46 -26
- package/dist/providers/gemini/index.d.ts.map +1 -1
- package/dist/providers/gemini/index.js +3 -2
- package/dist/providers/openai/Capabilities.d.ts +4 -11
- package/dist/providers/openai/Capabilities.d.ts.map +1 -1
- package/dist/providers/openai/Capabilities.js +124 -121
- package/dist/providers/openai/Chat.d.ts.map +1 -1
- package/dist/providers/openai/Chat.js +19 -17
- package/dist/providers/openai/Embedding.d.ts.map +1 -1
- package/dist/providers/openai/Embedding.js +2 -1
- package/dist/providers/openai/Image.d.ts.map +1 -1
- package/dist/providers/openai/Image.js +2 -1
- package/dist/providers/openai/ModelDefinitions.d.ts +1 -24
- package/dist/providers/openai/ModelDefinitions.d.ts.map +1 -1
- package/dist/providers/openai/ModelDefinitions.js +1 -211
- package/dist/providers/openai/Models.d.ts +1 -0
- package/dist/providers/openai/Models.d.ts.map +1 -1
- package/dist/providers/openai/Models.js +46 -22
- package/dist/providers/openai/Moderation.d.ts.map +1 -1
- package/dist/providers/openai/Moderation.js +2 -1
- package/dist/providers/openai/OpenAIProvider.d.ts +1 -0
- package/dist/providers/openai/OpenAIProvider.d.ts.map +1 -1
- package/dist/providers/openai/OpenAIProvider.js +1 -0
- package/dist/providers/openai/Streaming.d.ts.map +1 -1
- package/dist/providers/openai/Streaming.js +5 -1
- package/dist/providers/openai/Transcription.d.ts.map +1 -1
- package/dist/providers/openai/Transcription.js +3 -2
- package/dist/providers/openai/index.d.ts.map +1 -1
- package/dist/providers/openai/index.js +5 -3
- package/dist/providers/openai/utils.d.ts +20 -0
- package/dist/providers/openai/utils.d.ts.map +1 -0
- package/dist/providers/openai/utils.js +25 -0
- 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
|
[](https://www.npmjs.com/package/@node-llm/core)
|
|
4
8
|
[](https://opensource.org/licenses/MIT)
|
|
5
9
|
[](https://www.typescriptlang.org/)
|
|
6
10
|
|
|
7
|
-
|
|
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
|
-
|
|
15
|
+
<br/>
|
|
14
16
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
-
|
|
22
|
-
|
|
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
|
+
|
|
21
|
+
<img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/anthropic-text.svg" height="18" />
|
|
22
|
+
|
|
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
|
+
|
|
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
|
-
|
|
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
|
-
##
|
|
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
|
-
//
|
|
63
|
-
|
|
39
|
+
// 1. Configure once
|
|
40
|
+
LLM.configure({ provider: "openai" });
|
|
64
41
|
|
|
65
|
-
//
|
|
66
|
-
|
|
67
|
-
|
|
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
|
-
|
|
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
|
-
|
|
51
|
+
## 🔮 Capabilities
|
|
97
52
|
|
|
98
|
-
|
|
53
|
+
### 💬 Unified Chat
|
|
54
|
+
Stop rewriting code for every provider. `node-llm` normalizes inputs and outputs.
|
|
99
55
|
|
|
100
56
|
```ts
|
|
101
|
-
const
|
|
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
|
-
###
|
|
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
|
-
|
|
116
|
-
|
|
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
|
-
###
|
|
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
|
|
74
|
+
const tools = [{
|
|
313
75
|
type: 'function',
|
|
314
|
-
function: {
|
|
315
|
-
|
|
316
|
-
|
|
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
|
-
|
|
80
|
+
await chat.withTools(tools).ask("Weather in Tokyo?");
|
|
81
|
+
```
|
|
335
82
|
|
|
336
|
-
|
|
83
|
+
### ✨ Structured Output
|
|
84
|
+
Get type-safe JSON back using **Zod** schemas.
|
|
337
85
|
|
|
338
86
|
```ts
|
|
339
|
-
import {
|
|
87
|
+
import { z } from "zod";
|
|
340
88
|
|
|
341
|
-
const
|
|
342
|
-
|
|
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
|
-
|
|
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
|
-
|
|
357
|
-
|
|
95
|
+
### 🎨 Image Generation
|
|
358
96
|
```ts
|
|
359
|
-
|
|
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
|
-
###
|
|
377
|
-
|
|
378
|
-
Guarantee valid JSON output without enforcing a strict schema.
|
|
379
|
-
|
|
100
|
+
### 🎤 Audio Transcription
|
|
380
101
|
```ts
|
|
381
|
-
|
|
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
|
-
|
|
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
|
-
|
|
404
|
-
await chat.ask("
|
|
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
|
-
//
|
|
419
|
-
|
|
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
|
-
|
|
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
|
-
|
|
442
|
-
// Refresh model information from the API
|
|
443
|
-
await LLM.models.refresh();
|
|
118
|
+
## 📋 Supported Providers
|
|
444
119
|
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
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
|
-
##
|
|
129
|
+
## 🚀 Why use this over official SDKs?
|
|
455
130
|
|
|
456
|
-
|
|
|
131
|
+
| Feature | node-llm | Official SDKs |
|
|
457
132
|
| :--- | :--- | :--- |
|
|
458
|
-
| **
|
|
459
|
-
| **
|
|
460
|
-
| **
|
|
461
|
-
| **
|
|
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
|
-
##
|
|
141
|
+
## 📚 Documentation & Installation
|
|
466
142
|
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
- **Production Ready**: Built-in retries and strict type checking.
|
|
471
|
-
|
|
472
|
-
---
|
|
143
|
+
```bash
|
|
144
|
+
npm install @node-llm/core
|
|
145
|
+
```
|
|
473
146
|
|
|
474
|
-
|
|
147
|
+
**[View Full Documentation ↗](https://node-llm.eshaiju.com/)**
|
|
475
148
|
|
|
476
|
-
|
|
477
|
-
```bash
|
|
478
|
-
npm run test:unit
|
|
479
|
-
```
|
|
149
|
+
---
|
|
480
150
|
|
|
481
|
-
|
|
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
|
-
|
|
153
|
+
Heavily inspired by the elegant design of [RubyLLM](https://rubyllm.com/).
|
|
492
154
|
|
|
493
155
|
---
|
|
494
156
|
|
package/dist/chat/Chat.d.ts
CHANGED
|
@@ -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.
|
package/dist/chat/Chat.d.ts.map
CHANGED
|
@@ -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,
|
|
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,CAetB;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,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAK7C;;;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;IAgMrF;;OAEG;IACI,MAAM,CAAC,OAAO,EAAE,MAAM;CAI9B"}
|