@node-llm/core 1.6.0 → 1.6.2

package/README.md

@@ -1,295 +1,127 @@
+# @node-llm/core
+
 <p align="left">
   <a href="https://node-llm.eshaiju.com/">
-    <img src="docs/assets/images/logo.jpg" alt="NodeLLM logo" width="300" />
+    <img src="https://node-llm.eshaiju.com/assets/images/logo.jpg" alt="NodeLLM logo" width="300" />
   </a>
 </p>
 
-# NodeLLM
-
-**An architectural layer for integrating Large Language Models in Node.js.**
-
-**Provider-agnostic by design.**
-
-Integrating multiple LLM providers often means juggling different SDKs, API styles, and update cycles. NodeLLM provides a single, unified, production-oriented API for interacting with over 540+ models across multiple providers (OpenAI, Gemini, Anthropic, DeepSeek, OpenRouter, Ollama, etc.) that stays consistent even when providers change.
-
-<p align="left">
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openai.svg" height="28" />
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openai-text.svg" height="22" />
-  &nbsp;&nbsp;&nbsp;&nbsp;
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/anthropic-text.svg" height="18" />
-  &nbsp;&nbsp;&nbsp;&nbsp;
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/gemini-color.svg" height="28" />
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/gemini-text.svg" height="20" />
-  &nbsp;&nbsp;&nbsp;&nbsp;
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/deepseek-color.svg" height="28" />
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/deepseek-text.svg" height="20" />
-  &nbsp;&nbsp;&nbsp;&nbsp;
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openrouter.svg" height="28" />
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openrouter-text.svg" height="22" />
-  &nbsp;&nbsp;&nbsp;&nbsp;
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/ollama.svg" height="28" />
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/ollama-text.svg" height="18" />
-</p>
-
-<br/>
-
 [![npm version](https://img.shields.io/npm/v/@node-llm/core.svg)](https://www.npmjs.com/package/@node-llm/core)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 
----
-
-## 🛑 What NodeLLM is NOT
-
-NodeLLM represents a clear architectural boundary between your system and LLM vendors.
+**The production-grade LLM engine for Node.js. Provider-agnostic by design.**
 
-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
-
----
-
-## 🏗️ Why NodeLLM?
-
-Direct integrations often become tightly coupled to specific providers, making it difficult to adapt as models evolve. **LLMs should be treated as infrastructure**, and NodeLLM helps you build a stable foundation that persists regardless of which model is currently "state of the art."
-
-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**.
+`@node-llm/core` provides a single, unified API for interacting with over 540+ models across all major providers. It is built for developers who need stable infrastructure, standard streaming, and automated tool execution without vendor lock-in.
 
 ---
 
-## ⚡ The Architectural Path
-
-```ts
-import { NodeLLM } from "@node-llm/core";
-
-// 1. Zero-Config (NodeLLM automatically reads NODELLM_PROVIDER and API keys)
-const chat = NodeLLM.chat("gpt-4o");
-
-// 2. Chat (High-level request/response)
-const response = await chat.ask("Explain event-driven architecture");
-console.log(response.content);
+## 🚀 Key Features
 
-// 3. Streaming (Standard AsyncIterator)
-for await (const chunk of chat.stream("Explain event-driven architecture")) {
-  process.stdout.write(chunk.content);
-}
-```
-
-### 🎯 Real-World Example: Brand Perception Checker
-
-Built with NodeLLM - Multi-provider AI analysis, tool calling, and structured outputs working together.
-
-**[View Example →](examples/brand-perception-checker/)**
+- **Unified API**: One interface for OpenAI, Anthropic, Gemini, DeepSeek, OpenRouter, and Ollama.
+- **Automated Tool Loops**: Recursive tool execution handled automatically—no manual loops required.
+- **Streaming + Tools**: Seamlessly execute tools and continue the stream with the final response.
+- **Structured Output**: Native Zod support for rigorous schema validation (`.withSchema()`).
+- **Multimodal engine**: Built-in handling for Vision, Audio (Whisper), and Video (Gemini).
+- **Security-First**: Integrated circuit breakers for timeouts, max tokens, and infinite tool loops.
 
 ---
 
-## 🔧 Strategic Configuration
-
-NodeLLM provides a flexible, **lazy-initialized** configuration system designed for enterprise usage. It is safe for ESM and resolved only when your first request is made, eliminating the common `dotenv` race condition.
-
-```ts
-// Recommended for multi-provider pipelines
-const llm = createLLM({
-  openaiApiKey: process.env.OPENAI_API_KEY,
-  anthropicApiKey: process.env.ANTHROPIC_API_KEY,
-  ollamaApiBase: process.env.OLLAMA_API_BASE
-});
-
-// Support for Custom Endpoints (e.g., Azure or LocalAI)
-const llm = createLLM({
-  openaiApiKey: process.env.AZURE_KEY,
-  openaiApiBase: "https://your-resource.openai.azure.com/openai/deployments/..."
-});
-```
-
-**[Full Configuration Guide →](docs/getting_started/configuration.md)**
+## 📋 Supported Providers
 
----
+| Provider       | Supported Features                                               |
+| :------------- | :--------------------------------------------------------------- |
+| **OpenAI**     | Chat, Streaming, Tools, Vision, Audio, Images, Reasoning (o1/o3) |
+| **Anthropic**  | Chat, Streaming, Tools, Vision, PDF Support (Claude 3.5)         |
+| **Gemini**     | Chat, Streaming, Tools, Vision, Audio, Video, Embeddings         |
+| **DeepSeek**   | Chat (V3), Reasoning (R1), Streaming + Tools                     |
+| **OpenRouter** | 540+ models via a single API with automatic capability detection |
+| **Ollama**     | Local LLM inference with full Tool and Vision support            |
 
 ---
 
-## 🔮 Capabilities
+## ⚡ Quick Start
 
-### 💬 Unified Chat
+### Installation
 
-Stop rewriting code for every provider. `NodeLLM` normalizes inputs and outputs into a single, predictable mental model.
-
-```ts
-import { NodeLLM } from "@node-llm/core";
-
-// Uses NODELLM_PROVIDER from environment (defaults to GPT-4o)
-const chat = NodeLLM.chat();
-await chat.ask("Hello world");
+```bash
+npm install @node-llm/core
 ```
 
-### 👁️ Smart Vision & Files
+### Basic Chat & Streaming
 
-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.
+NodeLLM automatically reads your API keys from environment variables (e.g., `OPENAI_API_KEY`).
 
 ```ts
-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!**
+import { createLLM } from "@node-llm/core";
 
-```ts
-import { Tool, z } from "@node-llm/core";
+const llm = createLLM({ provider: "openai" });
 
-// Class-based DSL
-class WeatherTool extends Tool {
-  name = "get_weather";
-  description = "Get current weather";
-  schema = z.object({ location: z.string() });
+// 1. Standard Request
+const res = await llm.chat("gpt-4o").ask("What is the speed of light?");
+console.log(res.content);
 
-  async execute({ location }) {
-    return `Sunny in ${location}`;
-  }
+// 2. Real-time Streaming
+for await (const chunk of llm.chat().stream("Tell me a long story")) {
+  process.stdout.write(chunk.content);
 }
-
-// Now the model can use it automatically
-await chat.withTool(WeatherTool).ask("What's the weather in Tokyo?");
-
-// Lifecycle Hooks for Error & Flow Control
-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";
-
-// Now see detailed logs for every API call:
-// [NodeLLM] [OpenAI] Request: POST https://api.openai.com/v1/chat/completions
-// { "model": "gpt-4o", "messages": [...] }
-// [NodeLLM] [OpenAI] Response: 200 OK
-// { "id": "chatcmpl-123", ... }
 ```
 
-**Covers:** Chat, Streaming, Images, Embeddings, Transcription, Moderation - across all providers!
-
-### ✨ Structured Output
+### Structured Output (Zod)
 
-Get type-safe, validated JSON back using **Zod** schemas.
+Stop parsing markdown. Get typed objects directly.
 
 ```ts
 import { z } from "@node-llm/core";
-const Product = z.object({ name: z.string(), price: z.number() });
-
-const res = await chat.withSchema(Product).ask("Generate a gadget");
-console.log(res.parsed.name); // Full type-safety
-```
-
-### 🎨 Image Generation
 
-```ts
-await NodeLLM.paint("A cyberpunk city in rain");
-```
+const PlayerSchema = z.object({
+  name: z.string(),
+  powerLevel: z.number(),
+  abilities: z.array(z.string())
+});
 
-### 🎤 Audio Transcription
+const chat = llm.chat("gpt-4o-mini").withSchema(PlayerSchema);
+const response = await chat.ask("Generate a random RPG character");
 
-```ts
-await NodeLLM.transcribe("meeting-recording.wav");
+console.log(response.parsed.name); // Fully typed!
 ```
 
-### ⚡ 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)
-]);
-```
+---
 
-### 🧠 Deep Reasoning
+## 🛡️ Security Circuit Breakers
 
-Direct access to the thought process of models like **DeepSeek R1** or **OpenAI o1/o3** using the `.reasoning` field.
+NodeLLM protects your production environment with four built-in safety pillars:
 
 ```ts
-const res = await NodeLLM.chat("deepseek-reasoner").ask("Solve this logical puzzle");
-console.log(res.reasoning); // Chain-of-thought
+const llm = createLLM({
+  requestTimeout: 15000, // 15s DoS Protection
+  maxTokens: 4096, // Cost Protection
+  maxRetries: 3, // Retry Storm Protection
+  maxToolCalls: 5 // Infinite Loop Protection
+});
 ```
 
 ---
 
-## 🚀 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** |
-
----
-
-## 📋 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                  |
-
----
-
-## 📚 Documentation & Installation
-
-```bash
-npm install @node-llm/core
-```
-
-**[View Full Documentation ↗](https://node-llm.eshaiju.com/)**
+## 💾 Ecosystem
 
-### 🍿 Try the Live Demo
+Looking for persistence? use **[@node-llm/orm](https://www.npmjs.com/package/@node-llm/orm)**.
 
-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
-npm install
-npm run demo
-```
+- Automatically saves chat history to PostgreSQL/MySQL/SQLite via Prisma.
+- Tracks tool execution results and API metrics (latency, cost, tokens).
 
 ---
 
-## 🤝 Contributing
-
-We welcome contributions! Please see our **[Contributing Guide](CONTRIBUTING.md)** for more details on how to get started.
-
----
+## 📚 Full Documentation
 
-## 🫶 Credits
+Visit **[node-llm.eshaiju.com](https://node-llm.eshaiju.com/)** for:
 
-Heavily inspired by the elegant design of [RubyLLM](https://rubyllm.com/).
+- [Deep Dive into Tool Calling](https://node-llm.eshaiju.com/core-features/tools)
+- [Multi-modal Vision & Audio Guide](https://node-llm.eshaiju.com/core-features/multimodal)
+- [Custom Provider Plugin System](https://node-llm.eshaiju.com/advanced/custom-providers)
 
 ---
 
-## 📄 License
+## License
 
-MIT © [NodeLLM contributors]
+MIT © [NodeLLM Contributors]

package/dist/aliases.d.ts

@@ -375,6 +375,10 @@ declare const _default: {
         readonly openai: "gpt-5.2-chat-latest";
         readonly openrouter: "openai/gpt-5.2-chat-latest";
     };
+    readonly "gpt-5.2-codex": {
+        readonly openai: "gpt-5.2-codex";
+        readonly openrouter: "openai/gpt-5.2-codex";
+    };
     readonly "gpt-5.2-pro": {
         readonly openai: "gpt-5.2-pro";
         readonly openrouter: "openai/gpt-5.2-pro";

package/dist/aliases.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aliases.d.ts","sourceRoot":"","sources":["../src/aliases.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,wBA+mBW"}
+{"version":3,"file":"aliases.d.ts","sourceRoot":"","sources":["../src/aliases.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,wBAmnBW"}