@node-llm/core 1.5.1 → 1.5.4

package/README.md

@@ -1,16 +1,16 @@
 <p align="left">
   <a href="https://node-llm.eshaiju.com/">
-    <img src="https://github.com/node-llm/node-llm/raw/main/docs/assets/images/logo.jpg" alt="NodeLLM logo" width="300" />
+    <img src="docs/assets/images/logo.jpg" alt="NodeLLM logo" width="300" />
   </a>
 </p>
 
 # NodeLLM
 
-**An opinionated architectural layer for integrating Large Language Models in Node.js.**
+**An architectural layer for integrating Large Language Models in Node.js.**
 
 **Provider-agnostic by design.**
 
-Most LLM SDKs **tightly couple** your application to vendors, APIs, and churn. NodeLLM provides a unified, production-oriented API for interacting with over 540+ models across multiple providers (OpenAI, Gemini, Anthropic, DeepSeek, OpenRouter, Ollama, etc.) without the SDK fatigue.
+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" />
@@ -52,14 +52,14 @@ NodeLLM is **NOT**:
 
 ## 🏗️ Why NodeLLM?
 
-Most AI integrations today are provider-specific, SDK-driven, and leaky at abstraction boundaries. This creates long-term architectural risk. **LLMs should be treated as infrastructure**, and NodeLLM exists to help you integrate them without vendor lock-in.
+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 exists to solve **architectural problems**, not just provide API access. It is the core architectural layer for LLMs in the Node.js ecosystem.
+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, retries, and unified error handling.
-- **Predictable API**: Consistent behavior for Tools, Vision, and Structured Outputs across all models.
+- **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,7 +68,7 @@ NodeLLM exists to solve **architectural problems**, not just provide API access.
 ```ts
 import { NodeLLM } from "@node-llm/core";
 
-// 1. Configure once
+// 1. Configure once (Safe for ESM + dotenv race conditions)
 NodeLLM.configure({ provider: "openai" });
 
 // 2. Chat (High-level request/response)
@@ -77,29 +77,37 @@ 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);
 }
 ```
 
+### 🎯 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>
+
+**[View Example →](examples/brand-perception-checker/)**
+
 
 ---
 
 ## 🔧 Strategic Configuration
 
-NodeLLM provides a flexible configuration system designed for enterprise usage:
+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
-NodeLLM.configure((config) => {
-  config.openaiApiKey = process.env.OPENAI_API_KEY;
-  config.anthropicApiKey = process.env.ANTHROPIC_API_KEY;
-  config.ollamaApiBase = process.env.OLLAMA_API_BASE;
+NodeLLM.configure({
+  openaiApiKey: process.env.OPENAI_API_KEY,
+  anthropicApiKey: process.env.ANTHROPIC_API_KEY,
+  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,
@@ -107,7 +115,7 @@ NodeLLM.configure({
 });
 ```
 
-**[Full Configuration Guide →](https://node-llm.eshaiju.com/getting-started/configuration)**
+**[Full Configuration Guide →](docs/getting_started/configuration.md)**
 
 ---
 
@@ -123,7 +131,7 @@ 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.
+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"] 
@@ -142,42 +150,18 @@ class WeatherTool extends Tool {
   description = "Get current weather";
   schema = z.object({ location: z.string() });
 
-  async handler({ location }) { 
+  async execute({ location }) { 
     return `Sunny in ${location}`; 
   }
 }
 
 // Now the model can use it automatically
 await chat.withTool(WeatherTool).ask("What's the weather in Tokyo?");
-```
 
-### 🛡️ Loop Protection & Resource Limits
-Prevent runaway costs, infinite loops, and hanging requests with comprehensive protection against resource exhaustion.
-
-NodeLLM provides **defense-in-depth** security that you can configure globally or per-request:
-
-```ts
-// 1. Global config
-NodeLLM.configure({ 
-  requestTimeout: 30000, // Timeout requests after 30 seconds (default)
-  maxToolCalls: 5,       // Stop after 5 sequential tool execution turns
-  maxRetries: 2,         // Retry provider-level errors up to 2 times
-  maxTokens: 4096        // Limit output to 4K tokens (default)
-});
-
-// 2. Per request override
-await chat.ask("Deep search task", { 
-  requestTimeout: 120000, // 2 minutes for this request
-  maxToolCalls: 10,
-  maxTokens: 8192         // 8K tokens for this request
-});
+// Lifecycle Hooks for Error & Flow Control
+chat.onToolCallError((call, err) => "STOP"); 
 ```
-
-**Security Benefits:**
-- **`requestTimeout`**: Prevents DoS attacks and hanging requests
-- **`maxToolCalls`**: Prevents infinite tool execution loops
-- **`maxRetries`**: Prevents retry storms during outages
-- **`maxTokens`**: Prevents excessive output and cost overruns
+**[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:
@@ -193,42 +177,6 @@ process.env.NODELLM_DEBUG = "true";
 ```
 **Covers:** Chat, Streaming, Images, Embeddings, Transcription, Moderation - across all providers!
 
-### 🛡️ Content Policy Hooks
-NodeLLM provides pluggable hooks to implement custom security, compliance, and moderation logic. Instead of hard-coded rules, you can inject your own policies at the edge.
-
-- **`beforeRequest()`**: Intercept and modify messages before they hit the LLM (e.g., PII detection/redaction).
-- **`afterResponse()`**: Process the final response before it returns to your code (e.g., output masking or compliance checks).
-
-```ts
-chat
-  .beforeRequest(async (messages) => {
-    // Detect PII and redact
-    return redactSSN(messages);
-  })
-  .afterResponse(async (response) => {
-    // Ensure output compliance
-    return response.withContent(maskSensitiveData(response.content));
-  });
-```
-
-### 🧱 Smart Context Isolation
-Stop worrying about prompt injection or instruction drift. NodeLLM automatically separates system instructions from the conversation history, providing a higher level of protection and strictness.
-
-- **Zero-Config Security**: Enabled by default for all chats. No special flags required.
-- **Smart Model Mapping**: Automatically uses OpenAI's modern `developer` role for compatible models (GPT-4o, o1, o3) while safely falling back to the standard `system` role for older or local models (Ollama, DeepSeek, etc.).
-- **Universal Context**: Instructions stay separated internally, ensuring they are always prioritized by the model and never accidentally overridden by user messages.
-- **Provider Agnostic**: Write instructions once; NodeLLM handles the specific role requirements for every major provider (OpenAI, Anthropic, Gemini).
-
-### 🔍 Observability & Tool Auditing
-For enterprise compliance, NodeLLM provides deep visibility into the tool execution lifecycle. You can monitor, log, and audit every step of a tool's execution.
-
-```ts
-chat
-  .onToolCallStart((call) => log(`Starting tool: ${call.function.name}`))
-  .onToolCallEnd((call, res) => log(`Tool ${call.id} finished with: ${res}`))
-  .onToolCallError((call, err) => alert(`Tool ${call.function.name} failed: ${err.message}`));
-```
-
 ### ✨ Structured Output
 Get type-safe, validated JSON back using **Zod** schemas.
 ```ts
@@ -285,7 +233,7 @@ console.log(res.reasoning); // Chain-of-thought
 
 | 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**, **Smart Developer Role** |
+| <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** |
@@ -302,11 +250,21 @@ 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
+npm install
+npm run demo
+```
+
+
 ---
 
 ## 🤝 Contributing
 
-We welcome contributions! Please see our **[Contributing Guide](https://github.com/node-llm/node-llm/blob/main/CONTRIBUTING.md)** for more details on how to get started.
+We welcome contributions! Please see our **[Contributing Guide](CONTRIBUTING.md)** for more details on how to get started.
 
 ---
 

package/dist/chat/Chat.d.ts

@@ -1,8 +1,9 @@
 import { Message } from "./Message.js";
+import { ContentPart } from "./Content.js";
 import { ChatOptions } from "./ChatOptions.js";
 import { Provider, Usage, ChatChunk } from "../providers/Provider.js";
 import { Stream } from "../streaming/Stream.js";
-import { Tool } from "./Tool.js";
+import { ToolResolvable } from "./Tool.js";
 import { Schema } from "../schema/Schema.js";
 import { z } from "zod";
 import { ToolExecutionMode } from "../constants.js";
@@ -14,6 +15,7 @@ export interface AskOptions {
     headers?: Record<string, string>;
     maxToolCalls?: number;
     requestTimeout?: number;
+    signal?: AbortSignal;
 }
 import { ChatResponseString } from "./ChatResponse.js";
 export declare class Chat {
@@ -40,7 +42,7 @@ export declare class Chat {
      * Add a tool to the chat session (fluent API)
      * Supports passing a tool instance or a tool class (which will be instantiated).
      */
-    withTool(tool: any): this;
+    withTool(tool: ToolResolvable): this;
     /**
    * Add multiple tools to the chat session.
    * Supports passing Tool classes (which will be instantiated) or instances.
@@ -49,9 +51,7 @@ export declare class Chat {
    * @example
    * chat.withTools([WeatherTool, new CalculatorTool()], { replace: true });
    */
-    withTools(tools: (Tool | {
-        new (): Tool;
-    } | any)[], options?: {
+    withTools(tools: ToolResolvable[], options?: {
         replace?: boolean;
     }): this;
     /**
@@ -107,10 +107,7 @@ export declare class Chat {
      * Called when a tool call ends successfully.
      */
     onToolCallEnd(handler: (toolCall: any, result: any) => void): this;
-    /**
-     * Called when a tool call fails.
-     */
-    onToolCallError(handler: (toolCall: any, error: Error) => void): this;
+    onToolCallError(handler: (toolCall: any, error: Error) => 'STOP' | 'CONTINUE' | void | Promise<'STOP' | 'CONTINUE' | void>): this;
     /**
      * Set the tool execution mode.
      * - "auto": (Default) Automatically execute all tool calls.
@@ -140,19 +137,10 @@ export declare class Chat {
     /**
      * Streams the model's response to a user question.
      */
-    stream(content: string): Stream<ChatChunk>;
-    /**
-     * Check if tool execution should proceed based on the current mode.
-     */
-    private shouldExecuteTools;
-    /**
-     * Request user confirmation for a tool call in "confirm" mode.
-     * Returns true if approved, false if rejected.
-     */
-    private requestToolConfirmation;
+    stream(content: string | ContentPart[], options?: AskOptions): Stream<ChatChunk>;
     /**
-     * Execute a single tool call and return the result message.
+     * Normalizes a ToolResolvable into a ToolDefinition.
      */
-    private executeToolCall;
+    private normalizeTool;
 }
 //# sourceMappingURL=Chat.d.ts.map

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

@@ -1,4 +1,5 @@
 import { FileLoader } from "../utils/FileLoader.js";
+import { isBinaryContent, formatMultimodalContent } from "./Content.js";
 import { Executor } from "../executor/Executor.js";
 import { ChatStream } from "./ChatStream.js";
 import { Schema } from "../schema/Schema.js";
@@ -6,6 +7,10 @@ import { toJsonSchema } from "../schema/to-json-schema.js";
 import { z } from "zod";
 import { config } from "../config.js";
 import { ToolExecutionMode } from "../constants.js";
+import { ConfigurationError } from "../errors/index.js";
+import { ChatValidator } from "./Validation.js";
+import { ToolHandler } from "./ToolHandler.js";
+import { logger } from "../utils/logger.js";
 import { ChatResponseString } from "./ChatResponse.js";
 export class Chat {
     provider;
@@ -35,6 +40,11 @@ export class Chat {
         if (!this.options.toolExecution) {
             this.options.toolExecution = config.toolExecution || ToolExecutionMode.AUTO;
         }
+        if (options.tools) {
+            const toolList = options.tools;
+            this.options.tools = []; // Clear and re-add via normalized method
+            this.withTools(toolList);
+        }
     }
     /**
      * Read-only access to message history
@@ -84,27 +94,9 @@ export class Chat {
             this.options.tools = [];
         }
         for (const tool of tools) {
-            let toolInstance;
-            // Handle class constructor
-            if (typeof tool === "function") {
-                try {
-                    toolInstance = new tool();
-                }
-                catch (e) {
-                    console.error(`[NodeLLM] Failed to instantiate tool class: ${tool.name}`, e);
-                    continue;
-                }
-            }
-            else {
-                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);
+            const normalized = this.normalizeTool(tool);
+            if (normalized) {
+                this.options.tools.push(normalized);
             }
         }
         return this;
@@ -213,9 +205,6 @@ export class Chat {
         this.options.onToolCallEnd = handler;
         return this;
     }
-    /**
-     * Called when a tool call fails.
-     */
     onToolCallError(handler) {
         this.options.onToolCallError = handler;
         return this;
@@ -261,41 +250,13 @@ export class Chat {
         let messageContent = content;
         const files = [...(options?.images ?? []), ...(options?.files ?? [])];
         if (files.length > 0) {
-            const processedFiles = await Promise.all(files.map(f => FileLoader.load(f)));
-            const hasBinary = processedFiles.some(p => p.type === "image_url" || p.type === "input_audio" || p.type === "video_url");
-            if (hasBinary && !this.options.assumeModelExists && this.provider.capabilities && !this.provider.capabilities.supportsVision(this.model)) {
-                throw new Error(`Model ${this.model} does not support vision/binary files.`);
-            }
-            if (hasBinary && this.options.assumeModelExists) {
-                console.warn(`[NodeLLM] Skipping vision capability validation for model ${this.model}`);
-            }
-            // Separate text files from binary files
-            const textFiles = processedFiles.filter(p => p.type === "text");
-            const binaryFiles = processedFiles.filter(p => p.type !== "text");
-            // Concatenate text files into the main content
-            let fullText = content;
-            if (textFiles.length > 0) {
-                fullText += "\n" + textFiles.map(f => f.text).join("\n");
-            }
-            // If we have binary files, create multimodal content
-            if (binaryFiles.length > 0) {
-                messageContent = [
-                    { type: "text", text: fullText },
-                    ...binaryFiles
-                ];
-            }
-            else {
-                // Only text files, keep as string
-                messageContent = fullText;
-            }
+            const processedFiles = await Promise.all(files.map((f) => FileLoader.load(f)));
+            const hasBinary = processedFiles.some(isBinaryContent);
+            ChatValidator.validateVision(this.provider, this.model, hasBinary, this.options);
+            messageContent = formatMultimodalContent(content, processedFiles);
         }
         if (this.options.tools && this.options.tools.length > 0) {
-            if (!this.options.assumeModelExists && this.provider.capabilities && !this.provider.capabilities.supportsTools(this.model)) {
-                throw new Error(`Model ${this.model} does not support tool calling.`);
-            }
-            if (this.options.assumeModelExists) {
-                console.warn(`[NodeLLM] Skipping tool capability validation for model ${this.model}`);
-            }
+            ChatValidator.validateTools(this.provider, this.model, true, this.options);
         }
         this.messages.push({
             role: "user",
@@ -304,12 +265,7 @@ export class Chat {
         // Process Schema/Structured Output
         let responseFormat = this.options.responseFormat;
         if (this.options.schema) {
-            if (!this.options.assumeModelExists && this.provider.capabilities && !this.provider.capabilities.supportsStructuredOutput(this.model)) {
-                throw new Error(`Model ${this.model} does not support structured output.`);
-            }
-            if (this.options.assumeModelExists) {
-                console.warn(`[NodeLLM] Skipping structured output capability validation for model ${this.model}`);
-            }
+            ChatValidator.validateStructuredOutput(this.provider, this.model, true, this.options);
             const jsonSchema = toJsonSchema(this.options.schema.definition.schema);
             responseFormat = {
                 type: "json_schema",
@@ -330,6 +286,7 @@ export class Chat {
             headers: { ...this.options.headers, ...options?.headers },
             response_format: responseFormat, // Pass to provider
             requestTimeout: options?.requestTimeout ?? this.options.requestTimeout ?? config.requestTimeout,
+            signal: options?.signal,
             ...this.options.params,
         };
         // --- Content Policy Hooks (Input) ---
@@ -381,7 +338,7 @@ export class Chat {
         let stepCount = 0;
         while (response.tool_calls && response.tool_calls.length > 0) {
             // Dry-run mode: stop after proposing tools
-            if (!this.shouldExecuteTools(response.tool_calls, this.options.toolExecution)) {
+            if (!ToolHandler.shouldExecuteTools(response.tool_calls, this.options.toolExecution)) {
                 break;
             }
             stepCount++;
@@ -389,9 +346,9 @@ export class Chat {
                 throw new Error(`[NodeLLM] Maximum tool execution calls (${maxToolCalls}) exceeded.`);
             }
             for (const toolCall of response.tool_calls) {
-                // Confirm mode: request approval
+                // Human-in-the-loop: check for approval
                 if (this.options.toolExecution === ToolExecutionMode.CONFIRM) {
-                    const approved = await this.requestToolConfirmation(toolCall, this.options.onConfirmToolCall);
+                    const approved = await ToolHandler.requestToolConfirmation(toolCall, this.options.onConfirmToolCall);
                     if (!approved) {
                         this.messages.push({
                             role: "tool",
@@ -401,16 +358,42 @@ export class Chat {
                         continue;
                     }
                 }
-                // Execute the tool
-                const toolResult = await this.executeToolCall(toolCall, this.options.tools, this.options.onToolCallStart, this.options.onToolCallEnd, this.options.onToolCallError);
-                this.messages.push(toolResult);
+                try {
+                    const toolResult = await ToolHandler.execute(toolCall, this.options.tools, this.options.onToolCallStart, this.options.onToolCallEnd);
+                    this.messages.push(toolResult);
+                }
+                catch (error) {
+                    const directive = await this.options.onToolCallError?.(toolCall, error);
+                    if (directive === 'STOP') {
+                        throw error;
+                    }
+                    this.messages.push({
+                        role: "tool",
+                        tool_call_id: toolCall.id,
+                        content: `Fatal error executing tool '${toolCall.function.name}': ${error.message}`,
+                    });
+                    if (directive === 'CONTINUE') {
+                        continue;
+                    }
+                    // Default short-circuit logic
+                    const isFatal = error.fatal === true || error.status === 401 || error.status === 403;
+                    if (isFatal) {
+                        throw error;
+                    }
+                    logger.error(`Tool execution failed for '${toolCall.function.name}':`, error);
+                }
             }
             response = await this.executor.executeChat({
                 model: this.model,
                 messages: [...this.systemMessages, ...this.messages],
                 tools: this.options.tools,
+                temperature: options?.temperature ?? this.options.temperature,
+                max_tokens: options?.maxTokens ?? this.options.maxTokens ?? config.maxTokens,
                 headers: this.options.headers,
+                response_format: responseFormat,
                 requestTimeout: options?.requestTimeout ?? this.options.requestTimeout ?? config.requestTimeout,
+                signal: options?.signal,
+                ...this.options.params,
             });
             trackUsage(response.usage);
             assistantMessage = new ChatResponseString(response.content ?? "", response.usage ?? { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, this.model, this.provider.id, response.reasoning);
@@ -438,68 +421,46 @@ export class Chat {
     /**
      * Streams the model's response to a user question.
      */
-    stream(content) {
+    stream(content, options = {}) {
         const streamer = new ChatStream(this.provider, this.model, this.options, this.messages, this.systemMessages);
-        return streamer.create(content);
-    }
-    /**
-     * Check if tool execution should proceed based on the current mode.
-     */
-    shouldExecuteTools(toolCalls, mode) {
-        if (!toolCalls || toolCalls.length === 0)
-            return false;
-        if (mode === ToolExecutionMode.DRY_RUN)
-            return false;
-        return true;
+        return streamer.create(content, options);
     }
     /**
-     * Request user confirmation for a tool call in "confirm" mode.
-     * Returns true if approved, false if rejected.
+     * Normalizes a ToolResolvable into a ToolDefinition.
      */
-    async requestToolConfirmation(toolCall, onConfirm) {
-        if (!onConfirm)
-            return true;
-        const confirmed = await onConfirm(toolCall);
-        return confirmed !== false;
-    }
-    /**
-     * Execute a single tool call and return the result message.
-     */
-    async executeToolCall(toolCall, tools, onStart, onEnd, onError) {
-        if (onStart)
-            onStart(toolCall);
-        const tool = tools?.find((t) => t.function.name === toolCall.function.name);
-        if (tool?.handler) {
+    normalizeTool(tool) {
+        let toolInstance;
+        // Handle class constructor
+        if (typeof tool === "function") {
             try {
-                const args = JSON.parse(toolCall.function.arguments);
-                const result = await tool.handler(args);
-                if (onEnd)
-                    onEnd(toolCall, result);
-                return {
-                    role: "tool",
-                    tool_call_id: toolCall.id,
-                    content: result,
-                };
+                toolInstance = new tool();
             }
-            catch (error) {
-                if (onError)
-                    onError(toolCall, error);
-                return {
-                    role: "tool",
-                    tool_call_id: toolCall.id,
-                    content: `Error executing tool: ${error.message}`,
-                };
+            catch (e) {
+                logger.error(`Failed to instantiate tool class: ${tool.name}`, e);
+                return null;
             }
         }
         else {
-            const error = new Error("Tool not found or no handler provided");
-            if (onError)
-                onError(toolCall, error);
-            return {
-                role: "tool",
-                tool_call_id: toolCall.id,
-                content: "Error: Tool not found or no handler provided",
-            };
+            toolInstance = tool;
+        }
+        if (!toolInstance)
+            return null;
+        // Normalized to standard ToolDefinition interface if it's a Tool class instance
+        if (typeof toolInstance.toLLMTool === "function") {
+            return toolInstance.toLLMTool();
+        }
+        if (!toolInstance.function || !toolInstance.function.name) {
+            // 1. Validate structure
+            throw new ConfigurationError(`[NodeLLM] Tool validation failed: 'function.name' is required for raw tool objects.`);
+        }
+        if (toolInstance.type !== 'function') {
+            // 2. Ensure 'type: function' exists (standardize for providers)
+            toolInstance.type = 'function';
+        }
+        if (typeof toolInstance.handler !== 'function') {
+            // 3. Validate handler existence
+            throw new ConfigurationError(`[NodeLLM] Tool validation failed: Tool '${toolInstance.function.name}' must have a 'handler' function. (Note: Only Tool subclasses use 'execute()')`);
         }
+        return toolInstance;
     }
 }

package/dist/chat/ChatOptions.d.ts

@@ -1,19 +1,19 @@
 import { Message } from "./Message.js";
-import { ToolDefinition } from "./Tool.js";
+import { ToolResolvable } from "./Tool.js";
 import { Schema } from "../schema/Schema.js";
 import { ChatResponseString } from "./ChatResponse.js";
 import { ToolExecutionMode } from "../constants.js";
 export interface ChatOptions {
     systemPrompt?: string;
     messages?: Message[];
-    tools?: ToolDefinition[];
+    tools?: ToolResolvable[];
     temperature?: number;
     maxTokens?: number;
     onNewMessage?: () => void;
     onEndMessage?: (message: any) => void;
     onToolCallStart?: (toolCall: any) => void;
     onToolCallEnd?: (toolCall: any, result: any) => void;
-    onToolCallError?: (toolCall: any, error: Error) => void;
+    onToolCallError?: (toolCall: any, error: Error) => 'STOP' | 'CONTINUE' | void | Promise<'STOP' | 'CONTINUE' | void>;
     headers?: Record<string, string>;
     schema?: Schema;
     responseFormat?: {