@node-llm/core 1.1.0 → 1.3.0

package/README.md

@@ -0,0 +1,243 @@
+<p align="left">
+  <img src="https://github.com/eshaiju/node-llm/raw/main/docs/assets/images/logo.jpg" alt="NodeLLMlogo" width="300" />
+</p>
+
+# NodeLLM
+**An opinionated architectural layer for using Large Language Models in Node.js.**
+
+Build chatbots, autonomous agents, and RAG pipelines without the SDK fatigue. NodeLLM provides a unified, production-oriented API for interacting with over **540+ models** across multiple providers (OpenAI, Gemini, Anthropic, DeepSeek, OpenRouter, Ollama, etc.) without coupling your application to any single SDK.
+
+<br/>
+
+<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/)
+
+---
+
+## ⚡ The Golden Path
+
+```ts
+import { NodeLLM } from "@node-llm/core";
+
+// 1. Configure once
+NodeLLM.configure({ provider: "openai" });
+
+// 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)
+for await (const chunk of chat.stream("Explain event-driven architecture")) {
+  process.stdout.write(chunk.content);
+}
+```
+
+---
+
+## Why`NodeLLM`?
+
+Most AI integrations today are provider-specific, SDK-driven, and leaky at abstraction boundaries. This creates long-term architectural risk. Switching models should not mean a total rewrite of your business logic.
+
+NodeLLMexists to solve **architectural problems**, not just provide API access.
+
+### Strategic Goals
+
+- **Provider Isolation**: Your application logic never touches a provider-specific SDK.
+- **Unified Mental Model**: Chat, streaming, tools, and structured outputs feel identical across providers.
+- **Production-Ready**: Streaming, retries, and errors are first-class concerns. 
+- **The "Standard Library" Voice**: It provides a beautiful, native-feeling API for modern Node.js.
+
+### Non-Goals
+
+- It is **not** a thin wrapper that mirrors every provider's unique API knobs.
+- It is **not** a UI framework or a simple chatbot builder.
+- It prioritizes **architectural clarity** over raw SDK convenience.
+
+---
+
+## 🔧 Strategic Configuration
+
+NodeLLMprovides a flexible configuration system designed for enterprise usage:
+
+```ts
+// Recommended for multi-provider pipelines
+NodeLLM.configure((config) => {
+  config.openaiApiKey = process.env.OPENAI_API_KEY;
+  config.anthropicApiKey = process.env.ANTHROPIC_API_KEY;
+  config.ollamaApiBase = process.env.OLLAMA_API_BASE;
+});
+
+// Switch providers at the framework level
+NodeLLM.configure({ provider: "anthropic" });
+
+// Support for Custom Endpoints (e.g., Azure or LocalAI)
+NodeLLM.configure({
+  openaiApiKey: process.env.AZURE_KEY,
+  openaiApiBase: "https://your-resource.openai.azure.com/openai/deployments/...",
+});
+```
+
+**[Full Configuration Guide →](docs/getting_started/configuration.md)**
+
+---
+
+---
+
+## 🔮 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
+await chat.ask("Hello world");
+```
+
+### 👁️ Smart Vision & Files
+Pass images, PDFs, or audio files directly. 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"] 
+});
+```
+
+### 🛠️ 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
+// Class-based DSL
+class WeatherTool extends Tool {
+  name = "get_weather";
+  description = "Get current weather";
+  schema = z.object({ location: z.string() });
+  async execute({ location }) { return `Sunny in ${location}`; }
+}
+
+// Register tools
+chat.withTools([WeatherTool]);
+
+// Now the model can use it automatically
+await chat.ask("What's the weather in Tokyo?");
+```
+**[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
+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() });
+
+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");
+```
+
+### 🎤 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),
+]);
+```
+
+### 🧠 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
+```
+
+---
+
+## 🚀 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/)**
+
+---
+
+## 🫶 Credits
+
+Heavily inspired by the elegant design of [RubyLLM](https://rubyllm.com/).
+
+---
+
+## 📄 License
+
+MIT © [NodeLLMcontributors]

package/dist/chat/Chat.d.ts

@@ -27,6 +27,7 @@ export declare class Chat {
      * Read-only access to message history
      */
     get history(): readonly Message[];
+    get modelId(): string;
     /**
      * Aggregate usage across the entire conversation
      */
@@ -37,14 +38,16 @@ export declare class Chat {
      */
     withTool(tool: any): this;
     /**
-     * Add multiple tools to the chat session.
-     * Supports passing tool instances or classes (which will be instantiated).
-     * Can replace existing tools if options.replace is true.
-     *
-     * @example
-     * chat.withTools([WeatherTool, new CalculatorTool()], { replace: true });
-     */
-    withTools(tools: (Tool | any)[], options?: {
+   * Add multiple tools to the chat session.
+   * Supports passing Tool classes (which will be instantiated) or instances.
+   * Can replace existing tools if options.replace is true.
+   *
+   * @example
+   * chat.withTools([WeatherTool, new CalculatorTool()], { replace: true });
+   */
+    withTools(tools: (Tool | {
+        new (): Tool;
+    } | any)[], options?: {
         replace?: boolean;
     }): this;
     /**

package/dist/chat/Chat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Chat.d.ts","sourceRoot":"","sources":["../../src/chat/Chat.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Chat.d.ts","sourceRoot":"","sources":["../../src/chat/Chat.ts"],"names":[],"mappings":"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"}

package/dist/chat/Chat.js

@@ -32,6 +32,9 @@ export class Chat {
     get history() {
         return this.messages;
     }
+    get modelId() {
+        return this.model;
+    }
     /**
      * Aggregate usage across the entire conversation
      */
@@ -56,13 +59,13 @@ export class Chat {
         return this.withTools([tool]);
     }
     /**
-     * Add multiple tools to the chat session.
-     * Supports passing tool instances or classes (which will be instantiated).
-     * Can replace existing tools if options.replace is true.
-     *
-     * @example
-     * chat.withTools([WeatherTool, new CalculatorTool()], { replace: true });
-     */
+   * Add multiple tools to the chat session.
+   * Supports passing Tool classes (which will be instantiated) or instances.
+   * Can replace existing tools if options.replace is true.
+   *
+   * @example
+   * chat.withTools([WeatherTool, new CalculatorTool()], { replace: true });
+   */
     withTools(tools, options) {
         if (options?.replace) {
             this.options.tools = [];
@@ -71,20 +74,27 @@ export class Chat {
             this.options.tools = [];
         }
         for (const tool of tools) {
+            let toolInstance;
+            // Handle class constructor
             if (typeof tool === "function") {
                 try {
-                    // Attempt to instantiate if it's a class
-                    this.options.tools.push(new tool());
+                    toolInstance = new tool();
                 }
                 catch (e) {
-                    // If instantiation fails, it might be a function tool or require args? 
-                    // For now, assuming classes with no-arg constructors as per convention.
-                    console.warn("Attempted to instantiate tool class but failed, adding as-is", e);
-                    this.options.tools.push(tool);
+                    console.error(`[NodeLLM] Failed to instantiate tool class: ${tool.name}`, e);
+                    continue;
                 }
             }
             else {
-                this.options.tools.push(tool);
+                toolInstance = tool;
+            }
+            // Normalized to standard ToolDefinition interface if it's a Tool class instance
+            if (toolInstance && typeof toolInstance.toLLMTool === "function") {
+                this.options.tools.push(toolInstance.toLLMTool());
+            }
+            else {
+                // Fallback for legacy raw tool objects (defined as objects with type: 'function')
+                this.options.tools.push(toolInstance);
             }
         }
         return this;

package/dist/chat/ChatOptions.d.ts

@@ -1,10 +1,10 @@
 import { Message } from "./Message.js";
-import { Tool } from "./Tool.js";
+import { ToolDefinition } from "./Tool.js";
 import { Schema } from "../schema/Schema.js";
 export interface ChatOptions {
     systemPrompt?: string;
     messages?: Message[];
-    tools?: Tool[];
+    tools?: ToolDefinition[];
     temperature?: number;
     maxTokens?: number;
     onNewMessage?: () => void;

package/dist/chat/ChatOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChatOptions.d.ts","sourceRoot":"","sources":["../../src/chat/ChatOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C,MAAM,WAAW,WAAW;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,IAAI,CAAC;IACtC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,CAAC;IACrC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE;QAAE,IAAI,EAAE,aAAa,GAAG,MAAM,CAAA;KAAE,CAAC;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"ChatOptions.d.ts","sourceRoot":"","sources":["../../src/chat/ChatOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C,MAAM,WAAW,WAAW;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,IAAI,CAAC;IACtC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,CAAC;IACrC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE;QAAE,IAAI,EAAE,aAAa,GAAG,MAAM,CAAA;KAAE,CAAC;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/chat/ChatStream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChatStream.d.ts","sourceRoot":"","sources":["../../src/chat/ChatStream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAEhD;;;GAGG;AACH,qBAAa,UAAU;IAInB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,OAAO,CAAC,QAAQ,CAAY;gBAGT,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,WAAgB,EAC1C,QAAQ,CAAC,EAAE,OAAO,EAAE;IAmBtB;;OAEG;IACH,IAAI,OAAO,IAAI,SAAS,OAAO,EAAE,CAEhC;IAED;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC;CAyE3C"}
+{"version":3,"file":"ChatStream.d.ts","sourceRoot":"","sources":["../../src/chat/ChatStream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAEhD;;;GAGG;AACH,qBAAa,UAAU;IAInB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,OAAO,CAAC,QAAQ,CAAY;gBAGT,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,WAAgB,EAC1C,QAAQ,CAAC,EAAE,OAAO,EAAE;IAmBtB;;OAEG;IACH,IAAI,OAAO,IAAI,SAAS,OAAO,EAAE,CAEhC;IAED;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC;CAkI3C"}

package/dist/chat/ChatStream.js

@@ -45,47 +45,98 @@ export class ChatStream {
             if (!provider.stream) {
                 throw new Error("Streaming not supported by provider");
             }
-            let full = "";
+            let fullContent = "";
             let fullReasoning = "";
+            let toolCalls;
             let isFirst = true;
-            try {
-                for await (const chunk of provider.stream({
-                    model,
-                    messages,
-                    temperature: options.temperature,
-                    max_tokens: options.maxTokens,
-                    signal: abortController.signal,
-                })) {
-                    if (isFirst) {
-                        if (options.onNewMessage)
-                            options.onNewMessage();
-                        isFirst = false;
+            // Main streaming loop - may iterate multiple times for tool calls
+            while (true) {
+                fullContent = "";
+                fullReasoning = "";
+                toolCalls = undefined;
+                try {
+                    for await (const chunk of provider.stream({
+                        model,
+                        messages,
+                        tools: options.tools,
+                        temperature: options.temperature,
+                        max_tokens: options.maxTokens,
+                        signal: abortController.signal,
+                    })) {
+                        if (isFirst) {
+                            if (options.onNewMessage)
+                                options.onNewMessage();
+                            isFirst = false;
+                        }
+                        if (chunk.content) {
+                            fullContent += chunk.content;
+                            yield chunk;
+                        }
+                        if (chunk.reasoning) {
+                            fullReasoning += chunk.reasoning;
+                            yield { content: "", reasoning: chunk.reasoning };
+                        }
+                        // Accumulate tool calls from the final chunk
+                        if (chunk.tool_calls) {
+                            toolCalls = chunk.tool_calls;
+                        }
                     }
-                    if (chunk.content) {
-                        full += chunk.content;
+                    // Add assistant message to history
+                    messages.push({
+                        role: "assistant",
+                        content: fullContent || null,
+                        tool_calls: toolCalls,
+                        // @ts-ignore
+                        reasoning: fullReasoning || undefined
+                    });
+                    // If no tool calls, we're done
+                    if (!toolCalls || toolCalls.length === 0) {
+                        if (options.onEndMessage) {
+                            options.onEndMessage(new ChatResponseString(fullContent, { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, model, fullReasoning || undefined));
+                        }
+                        break;
                     }
-                    if (chunk.reasoning) {
-                        fullReasoning += chunk.reasoning;
+                    // Execute tool calls
+                    for (const toolCall of toolCalls) {
+                        if (options.onToolCall)
+                            options.onToolCall(toolCall);
+                        const tool = options.tools?.find((t) => t.function.name === toolCall.function.name);
+                        if (tool?.handler) {
+                            try {
+                                const args = JSON.parse(toolCall.function.arguments);
+                                const result = await tool.handler(args);
+                                if (options.onToolResult)
+                                    options.onToolResult(result);
+                                messages.push({
+                                    role: "tool",
+                                    tool_call_id: toolCall.id,
+                                    content: result,
+                                });
+                            }
+                            catch (error) {
+                                messages.push({
+                                    role: "tool",
+                                    tool_call_id: toolCall.id,
+                                    content: `Error executing tool: ${error.message}`,
+                                });
+                            }
+                        }
+                        else {
+                            messages.push({
+                                role: "tool",
+                                tool_call_id: toolCall.id,
+                                content: "Error: Tool not found or no handler provided",
+                            });
+                        }
                     }
-                    yield chunk;
+                    // Continue loop to stream the next response after tool execution
                 }
-                // Finalize history
-                messages.push({
-                    role: "assistant",
-                    content: full,
-                    // @ts-ignore
-                    reasoning: fullReasoning || undefined
-                });
-                if (options.onEndMessage) {
-                    options.onEndMessage(new ChatResponseString(full, { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, model, fullReasoning || undefined));
-                }
-            }
-            catch (error) {
-                if (error instanceof Error && error.name === 'AbortError') {
-                    // Stream was aborted, we might still want to save what we got?
-                    // For now just rethrow or handle as needed
+                catch (error) {
+                    if (error instanceof Error && error.name === 'AbortError') {
+                        // Stream was aborted
+                    }
+                    throw error;
                 }
-                throw error;
             }
         };
         return new Stream(() => sideEffectGenerator(this.provider, this.model, this.messages, this.options, controller), controller);

package/dist/chat/Tool.d.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 export interface ToolCall {
     id: string;
     type: 'function';
@@ -6,7 +7,7 @@ export interface ToolCall {
         arguments: string;
     };
 }
-export interface Tool {
+export interface ToolDefinition {
     type: 'function';
     function: {
         name: string;
@@ -15,4 +16,37 @@ export interface Tool {
     };
     handler?: (args: any) => Promise<string>;
 }
+/**
+ * Subclass this to create tools with auto-generated schemas and type safety.
+ */
+export declare abstract class Tool<T = any> {
+    /**
+     * The name of the tool (must match [a-zA-Z0-9_-]+).
+     */
+    abstract name: string;
+    /**
+     * A clear description of what the tool does, used by the LLM to decide when to call it.
+     */
+    abstract description: string;
+    /**
+     * Parameters the tool accepts.
+     * Can be a Zod object (for auto-schema + type safety) or a raw JSON Schema.
+     */
+    abstract schema: z.ZodObject<any> | Record<string, any>;
+    /**
+     * The core logic for the tool.
+     * 'args' will be parsed and validated based on 'schema'.
+     */
+    abstract execute(args: T): Promise<any>;
+    /**
+     * Internal handler to bridge with LLM providers.
+     * Converts any result to a string (usually JSON).
+     */
+    handler(args: T): Promise<string>;
+    /**
+     * Converts the tool definition and logic into a standard ToolDefinition interface.
+     * This is called automatically by NodeLLM when registering tools.
+     */
+    toLLMTool(): ToolDefinition;
+}
 //# sourceMappingURL=Tool.d.ts.map

package/dist/chat/Tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Tool.d.ts","sourceRoot":"","sources":["../../src/chat/Tool.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KACjC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1C"}
+{"version":3,"file":"Tool.d.ts","sourceRoot":"","sources":["../../src/chat/Tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KACjC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1C;AAED;;GAEG;AACH,8BAAsB,IAAI,CAAC,CAAC,GAAG,GAAG;IAChC;;OAEG;IACH,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,SAAgB,WAAW,EAAE,MAAM,CAAC;IAEpC;;;OAGG;IACH,SAAgB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAE/D;;;OAGG;aACa,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC;IAE9C;;;OAGG;IACU,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAM9C;;;OAGG;IACI,SAAS,IAAI,cAAc;CAoBnC"}

package/dist/chat/Tool.js

@@ -1 +1,38 @@
-export {};
+import { toJsonSchema } from "../schema/to-json-schema.js";
+/**
+ * Subclass this to create tools with auto-generated schemas and type safety.
+ */
+export class Tool {
+    /**
+     * Internal handler to bridge with LLM providers.
+     * Converts any result to a string (usually JSON).
+     */
+    async handler(args) {
+        const result = await this.execute(args);
+        if (result === undefined || result === null)
+            return "";
+        return typeof result === "string" ? result : JSON.stringify(result);
+    }
+    /**
+     * Converts the tool definition and logic into a standard ToolDefinition interface.
+     * This is called automatically by NodeLLM when registering tools.
+     */
+    toLLMTool() {
+        const rawSchema = toJsonSchema(this.schema);
+        // We want the 'properties' and 'required' parts, not the full JSON Schema wrapper if present
+        const parameters = rawSchema.type === "object" ? rawSchema : {
+            type: "object",
+            properties: rawSchema.properties || {},
+            required: rawSchema.required || []
+        };
+        return {
+            type: "function",
+            function: {
+                name: this.name,
+                description: this.description,
+                parameters: parameters,
+            },
+            handler: this.handler.bind(this),
+        };
+    }
+}

package/dist/config.d.ts

@@ -1,5 +1,5 @@
 /**
- * Global configuration for Node-NodeLLM providers.
+ * Global configuration for LLM providers.
  * Values are initialized from environment variables but can be overridden programmatically.
  */
 export interface NodeLLMConfig {

package/dist/errors/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Base class for all node-llm errors
+ * Base class for all NodeLLM errors
  */
 export declare class LLMError extends Error {
     readonly code?: string | undefined;
@@ -64,7 +64,7 @@ export declare class CapabilityError extends LLMError {
     constructor(message: string);
 }
 /**
- * Thrown when NodeLLM provider is not configured
+ * Thrown when LLM provider is not configured
  */
 export declare class ProviderNotConfiguredError extends LLMError {
     constructor();

package/dist/errors/index.js

@@ -1,5 +1,5 @@
 /**
- * Base class for all node-llm errors
+ * Base class for all NodeLLM errors
  */
 export class LLMError extends Error {
     code;
@@ -96,11 +96,11 @@ export class CapabilityError extends LLMError {
     }
 }
 /**
- * Thrown when NodeLLM provider is not configured
+ * Thrown when LLM provider is not configured
  */
 export class ProviderNotConfiguredError extends LLMError {
     constructor() {
-        super("NodeLLM provider not configured", "PROVIDER_NOT_CONFIGURED");
+        super("LLM provider not configured", "PROVIDER_NOT_CONFIGURED");
     }
 }
 /**