@node-llm/core 1.5.4 → 1.6.0

package/README.md

@@ -44,9 +44,10 @@ Integrating multiple LLM providers often means juggling different SDKs, API styl
 NodeLLM represents a clear architectural boundary between your system and LLM vendors.
 
 NodeLLM is **NOT**:
- - A wrapper around a single provider SDK (like `openai` or `@google/generative-ai`)
- - A prompt-engineering framework
- - An agent playground or experimental toy
+
+- A wrapper around a single provider SDK (like `openai` or `@google/generative-ai`)
+- A prompt-engineering framework
+- An agent playground or experimental toy
 
 ---
 
@@ -57,6 +58,7 @@ Direct integrations often become tightly coupled to specific providers, making i
 NodeLLM helps solve **architectural problems**, not just provide API access. It serves as the core integration layer for LLMs in the Node.js ecosystem.
 
 ### Strategic Goals
+
 - **Provider Isolation**: Decouple your services from vendor SDKs.
 - **Production-Ready**: Native support for streaming, automatic retries, and unified error handling.
 - **Predictable API**: Consistent behavior for Tools, Vision, and Structured Outputs across all models, **now including full parity for streaming**.
@@ -68,16 +70,14 @@ NodeLLM helps solve **architectural problems**, not just provide API access. It
 ```ts
 import { NodeLLM } from "@node-llm/core";
 
-// 1. Configure once (Safe for ESM + dotenv race conditions)
-NodeLLM.configure({ provider: "openai" });
+// 1. Zero-Config (NodeLLM automatically reads NODELLM_PROVIDER and API keys)
+const chat = NodeLLM.chat("gpt-4o");
 
 // 2. Chat (High-level request/response)
-const chat = NodeLLM.chat("gpt-4o");
 const response = await chat.ask("Explain event-driven architecture");
 console.log(response.content);
 
 // 3. Streaming (Standard AsyncIterator)
-// NOW with full support for Tools, Vision, and Schemas!
 for await (const chunk of chat.stream("Explain event-driven architecture")) {
   process.stdout.write(chunk.content);
 }
@@ -85,15 +85,10 @@ for await (const chunk of chat.stream("Explain event-driven architecture")) {
 
 ### 🎯 Real-World Example: Brand Perception Checker
 
-Built with NodeLLM - Multi-provider AI analysis, tool calling, and structured outputs working together:
-
-<p align="center">
-  <img src="assets/brand-perception-checker.png" alt="Brand Perception Checker" width="800" />
-</p>
+Built with NodeLLM - Multi-provider AI analysis, tool calling, and structured outputs working together.
 
 **[View Example →](examples/brand-perception-checker/)**
 
-
 ---
 
 ## 🔧 Strategic Configuration
@@ -102,16 +97,16 @@ NodeLLM provides a flexible, **lazy-initialized** configuration system designed
 
 ```ts
 // Recommended for multi-provider pipelines
-NodeLLM.configure({
+const llm = createLLM({
   openaiApiKey: process.env.OPENAI_API_KEY,
   anthropicApiKey: process.env.ANTHROPIC_API_KEY,
-  ollamaApiBase: process.env.OLLAMA_API_BASE,
+  ollamaApiBase: process.env.OLLAMA_API_BASE
 });
 
 // Support for Custom Endpoints (e.g., Azure or LocalAI)
-NodeLLM.configure({
+const llm = createLLM({
   openaiApiKey: process.env.AZURE_KEY,
-  openaiApiBase: "https://your-resource.openai.azure.com/openai/deployments/...",
+  openaiApiBase: "https://your-resource.openai.azure.com/openai/deployments/..."
 });
 ```
 
@@ -124,21 +119,29 @@ NodeLLM.configure({
 ## 🔮 Capabilities
 
 ### 💬 Unified Chat
+
 Stop rewriting code for every provider. `NodeLLM` normalizes inputs and outputs into a single, predictable mental model.
+
 ```ts
-const chat = NodeLLM.chat(); // Defaults to GPT-4o
+import { NodeLLM } from "@node-llm/core";
+
+// Uses NODELLM_PROVIDER from environment (defaults to GPT-4o)
+const chat = NodeLLM.chat();
 await chat.ask("Hello world");
 ```
 
 ### 👁️ Smart Vision & Files
+
 Pass images, PDFs, or audio files directly to **both `ask()` and `stream()`**. We handle the heavy lifting: fetching remote URLs, base64 encoding, and MIME type mapping.
+
 ```ts
-await chat.ask("Analyze this interface", { 
-  files: ["./screenshot.png", "https://example.com/spec.pdf"] 
+await chat.ask("Analyze this interface", {
+  files: ["./screenshot.png", "https://example.com/spec.pdf"]
 });
 ```
 
 ### 🛠️ Auto-Executing Tools
+
 Define tools once;`NodeLLM` manages the recursive execution loop for you, keeping your controller logic clean. **Works seamlessly with both regular chat and streaming!**
 
 ```ts
@@ -150,8 +153,8 @@ class WeatherTool extends Tool {
   description = "Get current weather";
   schema = z.object({ location: z.string() });
 
-  async execute({ location }) { 
-    return `Sunny in ${location}`; 
+  async execute({ location }) {
+    return `Sunny in ${location}`;
   }
 }
 
@@ -159,12 +162,15 @@ class WeatherTool extends Tool {
 await chat.withTool(WeatherTool).ask("What's the weather in Tokyo?");
 
 // Lifecycle Hooks for Error & Flow Control
-chat.onToolCallError((call, err) => "STOP"); 
+chat.onToolCallError((call, err) => "STOP");
 ```
+
 **[Full Tool Calling Guide →](https://node-llm.eshaiju.com/core-features/tool-calling)**
 
 ### 🔍 Comprehensive Debug Logging
+
 Enable detailed logging for all API requests and responses across every feature and provider:
+
 ```ts
 // Set environment variable
 process.env.NODELLM_DEBUG = "true";
@@ -175,10 +181,13 @@ process.env.NODELLM_DEBUG = "true";
 // [NodeLLM] [OpenAI] Response: 200 OK
 // { "id": "chatcmpl-123", ... }
 ```
+
 **Covers:** Chat, Streaming, Images, Embeddings, Transcription, Moderation - across all providers!
 
 ### ✨ Structured Output
+
 Get type-safe, validated JSON back using **Zod** schemas.
+
 ```ts
 import { z } from "@node-llm/core";
 const Product = z.object({ name: z.string(), price: z.number() });
@@ -188,27 +197,33 @@ console.log(res.parsed.name); // Full type-safety
 ```
 
 ### 🎨 Image Generation
+
 ```ts
 await NodeLLM.paint("A cyberpunk city in rain");
 ```
 
 ### 🎤 Audio Transcription
+
 ```ts
 await NodeLLM.transcribe("meeting-recording.wav");
 ```
 
 ### ⚡ Scoped Parallelism
+
 Run multiple providers in parallel safely without global configuration side effects using isolated contexts.
+
 ```ts
 const [gpt, claude] = await Promise.all([
   // Each call branch off into its own isolated context
   NodeLLM.withProvider("openai").chat("gpt-4o").ask(prompt),
-  NodeLLM.withProvider("anthropic").chat("claude-3-5-sonnet").ask(prompt),
+  NodeLLM.withProvider("anthropic").chat("claude-3-5-sonnet").ask(prompt)
 ]);
 ```
 
 ### 🧠 Deep Reasoning
+
 Direct access to the thought process of models like **DeepSeek R1** or **OpenAI o1/o3** using the `.reasoning` field.
+
 ```ts
 const res = await NodeLLM.chat("deepseek-reasoner").ask("Solve this logical puzzle");
 console.log(res.reasoning); // Chain-of-thought
@@ -218,27 +233,27 @@ console.log(res.reasoning); // Chain-of-thought
 
 ## 🚀 Why use this over official SDKs?
 
-| Feature | NodeLLM | Official SDKs | Architectural Impact |
-| :--- | :--- | :--- | :--- |
-| **Provider Logic** | Transparently Handled | Exposed to your code | **Low Coupling** |
-| **Streaming** | Standard `AsyncIterator` | Vendor-specific Events | **Predictable Data Flow** |
-| **Streaming + Tools** | Automated Execution | Manual implementation | **Seamless UX** |
-| **Tool Loops** | Automated Recursion | Manual implementation | **Reduced Boilerplate** |
-| **Files/Vision** | Intelligent Path/URL handling | Base64/Buffer management | **Cleaner Service Layer** |
-| **Configuration** | Centralized & Global | Per-instance initialization | **Easier Lifecycle Mgmt** |
+| Feature               | NodeLLM                       | Official SDKs               | Architectural Impact      |
+| :-------------------- | :---------------------------- | :-------------------------- | :------------------------ |
+| **Provider Logic**    | Transparently Handled         | Exposed to your code        | **Low Coupling**          |
+| **Streaming**         | Standard `AsyncIterator`      | Vendor-specific Events      | **Predictable Data Flow** |
+| **Streaming + Tools** | Automated Execution           | Manual implementation       | **Seamless UX**           |
+| **Tool Loops**        | Automated Recursion           | Manual implementation       | **Reduced Boilerplate**   |
+| **Files/Vision**      | Intelligent Path/URL handling | Base64/Buffer management    | **Cleaner Service Layer** |
+| **Configuration**     | Centralized & Global          | Per-instance initialization | **Easier Lifecycle Mgmt** |
 
 ---
 
 ## 📋 Supported Providers
 
-| Provider | Supported Features |
-| :--- | :--- |
-| <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openai.svg" height="18"> **OpenAI** | Chat, **Streaming + Tools**, Vision, Audio, Images, Transcription, **Reasoning** |
-| <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/gemini-color.svg" height="18"> **Gemini** | Chat, **Streaming + Tools**, Vision, Audio, Video, Embeddings |
-| <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/anthropic-text.svg" height="12"> **Anthropic** | Chat, **Streaming + Tools**, Vision, PDF, Structured Output |
-| <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/deepseek-color.svg" height="18"> **DeepSeek** | Chat (V3), **Reasoning (R1)**, **Streaming + Tools** |
-| <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openrouter.svg" height="18"> **OpenRouter** | **Aggregator**, Chat, Streaming, Tools, Vision, Embeddings, **Reasoning** |
-| <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/ollama.svg" height="18"> **Ollama** | **Local Inference**, Chat, Streaming, Tools, Vision, Embeddings |
+| Provider                                                                                                                             | Supported Features                                                               |
+| :----------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------- |
+| <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openai.svg" height="18"> **OpenAI**            | Chat, **Streaming + Tools**, Vision, Audio, Images, Transcription, **Reasoning** |
+| <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/gemini-color.svg" height="18"> **Gemini**      | Chat, **Streaming + Tools**, Vision, Audio, Video, Embeddings                    |
+| <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/anthropic-text.svg" height="12"> **Anthropic** | Chat, **Streaming + Tools**, Vision, PDF, Structured Output                      |
+| <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/deepseek-color.svg" height="18"> **DeepSeek**  | Chat (V3), **Reasoning (R1)**, **Streaming + Tools**                             |
+| <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openrouter.svg" height="18"> **OpenRouter**    | **Aggregator**, Chat, Streaming, Tools, Vision, Embeddings, **Reasoning**        |
+| <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/ollama.svg" height="18"> **Ollama**            | **Local Inference**, Chat, Streaming, Tools, Vision, Embeddings                  |
 
 ---
 
@@ -251,7 +266,9 @@ npm install @node-llm/core
 **[View Full Documentation ↗](https://node-llm.eshaiju.com/)**
 
 ### 🍿 Try the Live Demo
+
 Want to see it in action? Run this in your terminal:
+
 ```bash
 git clone https://github.com/node-llm/node-llm.git
 cd node-llm
@@ -259,7 +276,6 @@ npm install
 npm run demo
 ```
 
-
 ---
 
 ## 🤝 Contributing