@node-llm/core 1.9.0 → 1.11.0

package/README.md

@@ -1,8 +1,8 @@
 # @node-llm/core
 
 <p align="left">
-  <a href="https://node-llm.eshaiju.com/">
-    <img src="https://node-llm.eshaiju.com/assets/images/logo.jpg" alt="NodeLLM logo" width="300" />
+  <a href="https://nodellm.dev/">
+    <img src="https://nodellm.dev/assets/images/logo.jpg" alt="NodeLLM logo" width="300" />
   </a>
 </p>
 
@@ -104,6 +104,89 @@ const llm = createLLM({
 
 ---
 
+## 🔌 Middleware System
+
+NodeLLM 1.9.0 introduces a powerful lifecycle hook system for audit, security, and observability.
+
+```ts
+import { createLLM, PIIMaskMiddleware, UsageLoggerMiddleware } from "@node-llm/core";
+
+const llm = createLLM({
+  provider: "openai",
+  middlewares: [
+    new PIIMaskMiddleware(), // Redact emails/phone numbers automatically
+    new UsageLoggerMiddleware() // Log structured token usage & costs
+  ]
+});
+
+// All chats created from this instance inherit these middlewares
+const chat = llm.chat("gpt-4o");
+```
+
+### Decisive Tool Safety
+
+Middlewares can control the engine's recovery strategy during tool failures.
+
+```ts
+const safetyMiddleware = {
+  name: "Audit",
+  onToolCallError: async (ctx, tool, error) => {
+    if (tool.function.name === "delete_user") return "STOP"; // Kill the loop
+    return "RETRY"; // Attempt recovery
+  }
+};
+```
+
+---
+
+## 🤖 Agent Class
+
+Define reusable, class-configured agents with a declarative DSL:
+
+```ts
+import { Agent, Tool, z } from "@node-llm/core";
+
+class LookupOrderTool extends Tool<{ orderId: string }> {
+  name = "lookup_order";
+  description = "Look up an order by ID";
+  schema = z.object({ orderId: z.string() });
+
+  async execute({ orderId }: { orderId: string }) {
+    return { status: "shipped", eta: "Tomorrow" };
+  }
+}
+
+class SupportAgent extends Agent {
+  static model = "gpt-4.1";
+  static instructions = "You are a helpful support agent.";
+  static tools = [LookupOrderTool];
+  static temperature = 0.2;
+}
+
+// Use anywhere in your app
+const agent = new SupportAgent();
+const response = await agent.ask("Where is order #123?");
+console.log(response.content);
+```
+
+### ToolHalt - Early Loop Termination
+
+Stop the agentic loop early when a definitive answer is found:
+
+```ts
+class FinalAnswerTool extends Tool<{ answer: string }> {
+  name = "final_answer";
+  description = "Return the final answer to the user";
+  schema = z.object({ answer: z.string() });
+
+  async execute({ answer }: { answer: string }) {
+    return this.halt(answer); // Stops the loop, returns this result
+  }
+}
+```
+
+---
+
 ## 💾 Ecosystem
 
 Looking for persistence? use **[@node-llm/orm](https://www.npmjs.com/package/@node-llm/orm)**.
@@ -115,11 +198,11 @@ Looking for persistence? use **[@node-llm/orm](https://www.npmjs.com/package/@no
 
 ## 📚 Full Documentation
 
-Visit **[node-llm.eshaiju.com](https://node-llm.eshaiju.com/)** for:
+Visit **[nodellm.dev](https://nodellm.dev/)** for:
 
-- [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)
+- [Deep Dive into Tool Calling](https://nodellm.dev/core-features/tools)
+- [Multi-modal Vision & Audio Guide](https://nodellm.dev/core-features/multimodal)
+- [Custom Provider Plugin System](https://nodellm.dev/advanced/custom-providers)
 
 ---
 

package/dist/agent/Agent.d.ts

@@ -0,0 +1,191 @@
+import { z } from "zod";
+import { Chat, AskOptions } from "../chat/Chat.js";
+import { ChatOptions } from "../chat/ChatOptions.js";
+import { ChatResponseString } from "../chat/ChatResponse.js";
+import { ToolResolvable } from "../chat/Tool.js";
+import { ThinkingConfig, ThinkingResult } from "../providers/Provider.js";
+import { Schema } from "../schema/Schema.js";
+import { NodeLLMCore } from "../llm.js";
+/**
+ * Configuration options that can be defined as static properties on Agent subclasses.
+ */
+export interface AgentConfig {
+    /** The model ID to use (e.g., "gpt-4o", "claude-sonnet-4-20250514") */
+    model?: string;
+    /** The provider to use (e.g., "openai", "anthropic") */
+    provider?: string;
+    /** System instructions for the agent */
+    instructions?: string;
+    /** Tools available to the agent */
+    tools?: ToolResolvable[];
+    /** Temperature for response generation (0.0 - 1.0) */
+    temperature?: number;
+    /** Extended thinking configuration */
+    thinking?: ThinkingConfig;
+    /** Output schema for structured responses */
+    schema?: z.ZodType | Schema | Record<string, unknown>;
+    /** Provider-specific parameters */
+    params?: Record<string, unknown>;
+    /** Custom headers for requests */
+    headers?: Record<string, string>;
+    /** Maximum tokens in response */
+    maxTokens?: number;
+    /** Maximum tool call iterations */
+    maxToolCalls?: number;
+    /** Assume model exists without validation */
+    assumeModelExists?: boolean;
+    /** Optional LLM instance to use instead of global NodeLLM */
+    llm?: NodeLLMCore;
+}
+/**
+ * Base class for creating reusable, class-configured agents.
+ *
+ * Define your agent configuration using static properties, then instantiate
+ * and use it anywhere in your application.
+ *
+ * @example
+ * ```typescript
+ * class SupportAgent extends Agent {
+ *   static model = "gpt-4o";
+ *   static instructions = "You are a helpful support agent";
+ *   static tools = [SearchDocs, LookupAccount];
+ *   static temperature = 0.2;
+ * }
+ *
+ * const agent = new SupportAgent();
+ * const response = await agent.ask("How can I reset my password?");
+ * ```
+ *
+ * @example Override configuration per instance:
+ * ```typescript
+ * const agent = new SupportAgent({ model: "gpt-4o-mini" });
+ * ```
+ */
+export declare abstract class Agent<S extends Record<string, unknown> = Record<string, unknown>> {
+    static model?: string;
+    static provider?: string;
+    static instructions?: string;
+    static tools?: ToolResolvable[];
+    static temperature?: number;
+    static thinking?: ThinkingConfig;
+    static schema?: z.ZodType | Schema | Record<string, unknown>;
+    static params?: Record<string, unknown>;
+    static headers?: Record<string, string>;
+    static maxTokens?: number;
+    static maxToolCalls?: number;
+    static assumeModelExists?: boolean;
+    /**
+     * Hook called when the agent starts a new session (ask/stream).
+     * @param context - Initial context including messages/options
+     */
+    static onStart(_context: {
+        messages: unknown[];
+    }): void | Promise<void>;
+    /**
+     * Hook called when the agent generates a reasoning trace (thinking).
+     * @param thinking - The content of the thinking trace
+     * @param result - The full response object containing the thinking
+     */
+    static onThinking(_thinking: ThinkingResult, _result: ChatResponseString): void | Promise<void>;
+    /**
+     * Hook called when a tool execution starts.
+     * @param toolCall - The tool call object (id, function name, arguments)
+     */
+    static onToolStart(_toolCall: unknown): void | Promise<void>;
+    /**
+     * Hook called when a tool execution ends.
+     * @param toolCall - The tool call object
+     * @param result - The result of the tool execution
+     */
+    static onToolEnd(_toolCall: unknown, _result: unknown): void | Promise<void>;
+    /**
+     * Hook called when a tool execution encounters an error.
+     * @param toolCall - The tool call object
+     * @param error - The error that occurred
+     */
+    static onToolError(_toolCall: unknown, _error: Error): void | Promise<void>;
+    /**
+     * Hook called when the agent completes a response turn.
+     * @param result - The final response object
+     */
+    static onComplete(_result: ChatResponseString): void | Promise<void>;
+    /**
+     * Run the agent immediately with a prompt.
+     * Creates a new instance of the agent, runs the prompt, and disposes it.
+     *
+     * @example
+     * ```typescript
+     * const result = await TravelAgent.ask("Find flights to Paris");
+     * ```
+     */
+    static ask(message: string, options?: AskOptions): Promise<ChatResponseString>;
+    /**
+     * Stream the agent response immediately.
+     * Creates a new instance of the agent and streams the response.
+     *
+     * @example
+     * ```typescript
+     * for await (const chunk of TravelAgent.stream("Write a poem")) {
+     *   process.stdout.write(chunk.content);
+     * }
+     * ```
+     */
+    static stream(message: string, options?: AskOptions): import("../index.js").Stream<import("../providers/Provider.js").ChatChunk>;
+    /** The underlying Chat instance */
+    protected readonly chat: Chat<S>;
+    /**
+     * Create a new agent instance.
+     * @param overrides - Optional configuration to override static properties
+     */
+    constructor(overrides?: Partial<AgentConfig & ChatOptions>);
+    /**
+     * Send a message to the agent and get a response.
+     * @param message - The user message
+     * @param options - Optional request options
+     */
+    ask(message: string, options?: AskOptions): Promise<ChatResponseString>;
+    /**
+     * Alias for ask()
+     */
+    say(message: string, options?: AskOptions): Promise<ChatResponseString>;
+    /**
+     * Stream a response from the agent.
+     * @param message - The user message
+     * @param options - Optional request options
+     */
+    stream(message: string, options?: AskOptions): import("../index.js").Stream<import("../providers/Provider.js").ChatChunk>;
+    /**
+     * Get the conversation history.
+     */
+    get history(): readonly import("../index.js").Message[];
+    /**
+     * Get the model ID being used.
+     */
+    get modelId(): string;
+    /**
+     * Get aggregate token usage across the conversation.
+     */
+    get totalUsage(): import("../providers/Provider.js").Usage;
+    /**
+     * Access the underlying Chat instance for advanced operations.
+     */
+    get underlyingChat(): Chat<S>;
+}
+/**
+ * Helper function to define an agent inline without creating a class.
+ *
+ * @example
+ * ```typescript
+ * const SupportAgent = defineAgent({
+ *   model: "gpt-4o",
+ *   instructions: "You are a helpful support agent",
+ *   tools: [SearchDocs, LookupAccount],
+ *   temperature: 0.2
+ * });
+ *
+ * const agent = new SupportAgent();
+ * const response = await agent.ask("Help me!");
+ * ```
+ */
+export declare function defineAgent<S extends Record<string, unknown> = Record<string, unknown>>(config: AgentConfig): new (overrides?: Partial<AgentConfig & ChatOptions>) => Agent<S>;
+//# sourceMappingURL=Agent.d.ts.map

package/dist/agent/Agent.d.ts.map

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

package/dist/agent/Agent.js

@@ -0,0 +1,272 @@
+import { NodeLLM } from "../llm.js";
+/**
+ * Base class for creating reusable, class-configured agents.
+ *
+ * Define your agent configuration using static properties, then instantiate
+ * and use it anywhere in your application.
+ *
+ * @example
+ * ```typescript
+ * class SupportAgent extends Agent {
+ *   static model = "gpt-4o";
+ *   static instructions = "You are a helpful support agent";
+ *   static tools = [SearchDocs, LookupAccount];
+ *   static temperature = 0.2;
+ * }
+ *
+ * const agent = new SupportAgent();
+ * const response = await agent.ask("How can I reset my password?");
+ * ```
+ *
+ * @example Override configuration per instance:
+ * ```typescript
+ * const agent = new SupportAgent({ model: "gpt-4o-mini" });
+ * ```
+ */
+export class Agent {
+    // Static configuration properties - override these in subclasses
+    static model;
+    static provider;
+    static instructions;
+    static tools;
+    static temperature;
+    static thinking;
+    static schema;
+    static params;
+    static headers;
+    static maxTokens;
+    static maxToolCalls;
+    static assumeModelExists;
+    /**
+     * Hook called when the agent starts a new session (ask/stream).
+     * @param context - Initial context including messages/options
+     */
+    static onStart(_context) {
+        // Override in subclass
+    }
+    /**
+     * Hook called when the agent generates a reasoning trace (thinking).
+     * @param thinking - The content of the thinking trace
+     * @param result - The full response object containing the thinking
+     */
+    static onThinking(_thinking, _result) {
+        // Override in subclass
+    }
+    /**
+     * Hook called when a tool execution starts.
+     * @param toolCall - The tool call object (id, function name, arguments)
+     */
+    static onToolStart(_toolCall) {
+        // Override in subclass
+    }
+    /**
+     * Hook called when a tool execution ends.
+     * @param toolCall - The tool call object
+     * @param result - The result of the tool execution
+     */
+    static onToolEnd(_toolCall, _result) {
+        // Override in subclass
+    }
+    /**
+     * Hook called when a tool execution encounters an error.
+     * @param toolCall - The tool call object
+     * @param error - The error that occurred
+     */
+    static onToolError(_toolCall, _error) {
+        // Override in subclass
+    }
+    /**
+     * Hook called when the agent completes a response turn.
+     * @param result - The final response object
+     */
+    static onComplete(_result) {
+        // Override in subclass
+    }
+    // --- Static Execution API ---
+    /**
+     * Run the agent immediately with a prompt.
+     * Creates a new instance of the agent, runs the prompt, and disposes it.
+     *
+     * @example
+     * ```typescript
+     * const result = await TravelAgent.ask("Find flights to Paris");
+     * ```
+     */
+    static async ask(message, options) {
+        const Ctor = this;
+        const agent = new Ctor({});
+        return agent.ask(message, options);
+    }
+    /**
+     * Stream the agent response immediately.
+     * Creates a new instance of the agent and streams the response.
+     *
+     * @example
+     * ```typescript
+     * for await (const chunk of TravelAgent.stream("Write a poem")) {
+     *   process.stdout.write(chunk.content);
+     * }
+     * ```
+     */
+    static stream(message, options) {
+        const Ctor = this;
+        const agent = new Ctor({});
+        return agent.stream(message, options);
+    }
+    /** The underlying Chat instance */
+    chat;
+    /**
+     * Create a new agent instance.
+     * @param overrides - Optional configuration to override static properties
+     */
+    constructor(overrides = {}) {
+        const ctor = this.constructor;
+        // Build chat options from static properties + overrides
+        const chatOptions = {
+            provider: overrides.provider ?? ctor.provider,
+            assumeModelExists: overrides.assumeModelExists ?? ctor.assumeModelExists,
+            temperature: overrides.temperature ?? ctor.temperature,
+            maxTokens: overrides.maxTokens ?? ctor.maxTokens,
+            maxToolCalls: overrides.maxToolCalls ?? ctor.maxToolCalls,
+            headers: { ...ctor.headers, ...overrides.headers },
+            params: { ...ctor.params, ...overrides.params },
+            thinking: overrides.thinking ?? ctor.thinking,
+            messages: overrides.messages // Allow history injection
+        };
+        // Determine model
+        const model = overrides.model ?? ctor.model;
+        if (!model) {
+            throw new Error(`[Agent] No model specified. Set static model property or pass model in constructor.`);
+        }
+        // Use provided LLM instance or fall back to global NodeLLM
+        const llm = overrides.llm ?? NodeLLM;
+        this.chat = llm.chat(model, chatOptions);
+        // Apply instructions
+        const instructions = overrides.instructions ?? ctor.instructions;
+        if (instructions) {
+            this.chat.withInstructions(instructions);
+        }
+        // Apply tools
+        const tools = overrides.tools ?? ctor.tools;
+        if (tools && tools.length > 0) {
+            this.chat.withTools(tools);
+        }
+        // Apply schema
+        const schema = overrides.schema ?? ctor.schema;
+        if (schema) {
+            this.chat.withSchema(schema);
+        }
+        // Wire up global/static telemetry hooks
+        // Trigger onStart immediately
+        if (ctor.onStart) {
+            this.chat.beforeRequest(async (messages) => {
+                if (ctor.onStart) {
+                    await ctor.onStart({ messages });
+                }
+            });
+        }
+        if (ctor.onToolStart) {
+            this.chat.onToolCallStart(async (toolCall) => {
+                await ctor.onToolStart(toolCall);
+            });
+        }
+        if (ctor.onToolEnd) {
+            this.chat.onToolCallEnd(async (toolCall, result) => {
+                await ctor.onToolEnd(toolCall, result);
+            });
+        }
+        if (ctor.onToolError) {
+            this.chat.onToolCallError(async (toolCall, error) => {
+                await ctor.onToolError(toolCall, error);
+            });
+        }
+        if (ctor.onComplete || ctor.onThinking) {
+            this.chat.onEndMessage(async (msg) => {
+                if (msg.thinking && ctor.onThinking) {
+                    await ctor.onThinking(msg.thinking, msg);
+                }
+                if (ctor.onComplete) {
+                    await ctor.onComplete(msg);
+                }
+            });
+        }
+    }
+    /**
+     * Send a message to the agent and get a response.
+     * @param message - The user message
+     * @param options - Optional request options
+     */
+    async ask(message, options) {
+        return this.chat.ask(message, options);
+    }
+    /**
+     * Alias for ask()
+     */
+    async say(message, options) {
+        return this.ask(message, options);
+    }
+    /**
+     * Stream a response from the agent.
+     * @param message - The user message
+     * @param options - Optional request options
+     */
+    stream(message, options) {
+        return this.chat.stream(message, options);
+    }
+    /**
+     * Get the conversation history.
+     */
+    get history() {
+        return this.chat.history;
+    }
+    /**
+     * Get the model ID being used.
+     */
+    get modelId() {
+        return this.chat.modelId;
+    }
+    /**
+     * Get aggregate token usage across the conversation.
+     */
+    get totalUsage() {
+        return this.chat.totalUsage;
+    }
+    /**
+     * Access the underlying Chat instance for advanced operations.
+     */
+    get underlyingChat() {
+        return this.chat;
+    }
+}
+/**
+ * Helper function to define an agent inline without creating a class.
+ *
+ * @example
+ * ```typescript
+ * const SupportAgent = defineAgent({
+ *   model: "gpt-4o",
+ *   instructions: "You are a helpful support agent",
+ *   tools: [SearchDocs, LookupAccount],
+ *   temperature: 0.2
+ * });
+ *
+ * const agent = new SupportAgent();
+ * const response = await agent.ask("Help me!");
+ * ```
+ */
+export function defineAgent(config) {
+    return class extends Agent {
+        static model = config.model;
+        static provider = config.provider;
+        static instructions = config.instructions;
+        static tools = config.tools;
+        static temperature = config.temperature;
+        static thinking = config.thinking;
+        static schema = config.schema;
+        static params = config.params;
+        static headers = config.headers;
+        static maxTokens = config.maxTokens;
+        static maxToolCalls = config.maxToolCalls;
+        static assumeModelExists = config.assumeModelExists;
+    };
+}