@node-llm/core 1.10.0 → 1.12.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>
 
@@ -139,6 +139,54 @@ const safetyMiddleware = {
 
 ---
 
+## 🤖 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)**.
@@ -150,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,178 @@
+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";
+/**
+ * A value that can be a static T or a function that returns T based on inputs.
+ */
+export type LazyValue<T, I = any> = T | ((inputs: I) => T);
+/**
+ * Configuration options for Agent.
+ */
+export interface AgentConfig<I = any> {
+    /** The model ID to use (e.g., "gpt-4o") */
+    model?: string;
+    /** The provider to use (e.g., "openai") */
+    provider?: string;
+    /** System instructions for the agent (can be lazy) */
+    instructions?: LazyValue<string, I>;
+    /** Tools available to the agent (can be lazy) */
+    tools?: LazyValue<ToolResolvable[], I>;
+    /** 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;
+    /** Optional initial inputs to resolve lazy config immediately */
+    inputs?: I;
+}
+/**
+ * Base class for creating reusable, class-configured agents.
+ */
+export declare abstract class Agent<I extends Record<string, any> = Record<string, any>, S extends Record<string, unknown> = Record<string, unknown>> {
+    static model?: string;
+    static provider?: string;
+    static instructions?: LazyValue<string, any>;
+    static tools?: LazyValue<ToolResolvable[], any>;
+    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;
+    /**
+     * Explicitly declare which inputs this agent expects.
+     * Useful for introspection and validation.
+     */
+    static inputs?: string[];
+    /**
+     * Hook called when the agent starts a new session (ask/stream).
+     */
+    static onStart(_context: {
+        messages: unknown[];
+    }): void | Promise<void>;
+    static onThinking(_thinking: ThinkingResult, _result: ChatResponseString): void | Promise<void>;
+    static onToolStart(_toolCall: unknown): void | Promise<void>;
+    static onToolEnd(_toolCall: unknown, _result: unknown): void | Promise<void>;
+    static onToolError(_toolCall: unknown, _error: Error): void | Promise<void>;
+    static onComplete(_result: ChatResponseString): void | Promise<void>;
+    /**
+     * Run the agent immediately with a prompt.
+     */
+    static ask<I extends Record<string, any>, S extends Record<string, any>>(this: new (overrides?: Partial<AgentConfig<I> & ChatOptions>) => Agent<I, S>, message: string, options?: AskOptions & {
+        inputs?: I;
+    }): Promise<ChatResponseString>;
+    /**
+     * Stream the agent response immediately.
+     */
+    static stream<I extends Record<string, any>, S extends Record<string, any>>(this: new (overrides?: Partial<AgentConfig<I> & ChatOptions>) => Agent<I, S>, message: string, options?: AskOptions & {
+        inputs?: I;
+    }): import("../index.js").Stream<import("../providers/Provider.js").ChatChunk>;
+    /** The underlying Chat instance */
+    protected readonly chat: Chat<S>;
+    /** Private reference to configuration overrides for lazy resolution */
+    private readonly config;
+    /**
+     * Create a new agent instance.
+     * @param overrides - Optional configuration to override static properties
+     */
+    constructor(overrides?: Partial<AgentConfig<I> & ChatOptions>);
+    /**
+     * Helper to resolve lazy instructions and tools based on inputs.
+     */
+    private resolveLazyConfig;
+    /**
+     * Add instructions to the agent (replaces or appends).
+     */
+    withInstructions(instructions: string, options?: {
+        replace?: boolean;
+    }): this;
+    /**
+     * Add tools to the agent.
+     */
+    withTools(tools: ToolResolvable[], options?: {
+        replace?: boolean;
+    }): this;
+    /**
+     * Alias for withTools([tool]).
+     */
+    use(tool: ToolResolvable): this;
+    /**
+     * Send a message to the agent and get a response.
+     */
+    ask(message: string, options?: AskOptions & {
+        inputs?: I;
+    }): Promise<ChatResponseString>;
+    /**
+     * Hook called when a tool call starts.
+     */
+    onToolCallStart(handler: (toolCall: any) => void | Promise<void>): this;
+    /**
+     * Hook called when a tool call ends.
+     */
+    onToolCallEnd(handler: (toolCall: any, result: any) => void | Promise<void>): this;
+    /**
+     * Hook called when a tool call errors.
+     */
+    onToolCallError(handler: (toolCall: any, error: Error) => any): this;
+    /**
+     * Hook called before a request.
+     */
+    beforeRequest(handler: (messages: any[]) => any): this;
+    /**
+     * Hook called after a response.
+     */
+    afterResponse(handler: (response: ChatResponseString) => any): this;
+    /**
+     * Alias for ask()
+     */
+    say(message: string, options?: AskOptions & {
+        inputs?: I;
+    }): Promise<ChatResponseString>;
+    /**
+     * Stream a response from the agent.
+     */
+    stream(message: string, options?: AskOptions & {
+        inputs?: I;
+    }): 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.
+ */
+export declare function defineAgent<I extends Record<string, any> = Record<string, any>, S extends Record<string, unknown> = Record<string, unknown>>(config: AgentConfig<I>): new (overrides?: Partial<AgentConfig<I> & ChatOptions>) => Agent<I, 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,293 @@
+import { NodeLLM } from "../llm.js";
+/**
+ * Base class for creating reusable, class-configured agents.
+ */
+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;
+    /**
+     * Explicitly declare which inputs this agent expects.
+     * Useful for introspection and validation.
+     */
+    static inputs;
+    /**
+     * Hook called when the agent starts a new session (ask/stream).
+     */
+    static onStart(_context) {
+        // Override in subclass
+    }
+    static onThinking(_thinking, _result) {
+        // Override in subclass
+    }
+    static onToolStart(_toolCall) {
+        // Override in subclass
+    }
+    static onToolEnd(_toolCall, _result) {
+        // Override in subclass
+    }
+    static onToolError(_toolCall, _error) {
+        // Override in subclass
+    }
+    static onComplete(_result) {
+        // Override in subclass
+    }
+    // --- Static Execution API ---
+    /**
+     * Run the agent immediately with a prompt.
+     */
+    static async ask(message, options) {
+        const agent = new this({ ...options });
+        return agent.ask(message, options);
+    }
+    /**
+     * Stream the agent response immediately.
+     */
+    static stream(message, options) {
+        const agent = new this({ ...options });
+        return agent.stream(message, options);
+    }
+    /** The underlying Chat instance */
+    chat;
+    /** Private reference to configuration overrides for lazy resolution */
+    config;
+    /**
+     * Create a new agent instance.
+     * @param overrides - Optional configuration to override static properties
+     */
+    constructor(overrides = {}) {
+        this.config = 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
+        };
+        // 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.`);
+        }
+        const llm = overrides.llm ?? NodeLLM;
+        this.chat = llm.chat(model, chatOptions);
+        // Initial resolution if inputs are provided in constructor
+        if (overrides.inputs) {
+            this.resolveLazyConfig(overrides.inputs);
+        }
+        else {
+            // Fallback: apply static/direct instructions immediately if they aren't functions
+            const instructions = overrides.instructions ?? ctor.instructions;
+            if (instructions && typeof instructions !== "function") {
+                this.chat.withInstructions(instructions);
+            }
+            const tools = overrides.tools ?? ctor.tools;
+            if (tools && typeof tools !== "function" && tools.length > 0) {
+                this.chat.withTools(tools);
+            }
+        }
+        // Apply schema
+        const schema = overrides.schema ?? ctor.schema;
+        if (schema) {
+            this.chat.withSchema(schema);
+        }
+        // Wire up telemetry hooks
+        if (ctor.onStart) {
+            this.chat.beforeRequest(async (messages) => {
+                if (ctor.onStart)
+                    await ctor.onStart({ messages });
+            });
+        }
+        if (ctor.onToolStart) {
+            this.chat.onToolCallStart(async (toolCall) => {
+                if (ctor.onToolStart)
+                    await ctor.onToolStart(toolCall);
+            });
+        }
+        if (ctor.onToolEnd) {
+            this.chat.onToolCallEnd(async (toolCall, result) => {
+                if (ctor.onToolEnd)
+                    await ctor.onToolEnd(toolCall, result);
+            });
+        }
+        if (ctor.onToolError) {
+            this.chat.onToolCallError(async (toolCall, error) => {
+                if (ctor.onToolError)
+                    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);
+                }
+            });
+        }
+    }
+    /**
+     * Helper to resolve lazy instructions and tools based on inputs.
+     */
+    resolveLazyConfig(inputs) {
+        if (!inputs)
+            return;
+        const ctor = this.constructor;
+        // 1. Resolve Instructions
+        let instructions = this.config.instructions ?? ctor.instructions;
+        if (typeof instructions === "function") {
+            instructions = instructions(inputs);
+        }
+        if (typeof instructions === "string") {
+            this.chat.withInstructions(instructions, { replace: true });
+        }
+        // 2. Resolve Tools
+        let tools = this.config.tools ?? ctor.tools;
+        if (typeof tools === "function") {
+            tools = tools(inputs);
+        }
+        if (Array.isArray(tools)) {
+            this.chat.withTools(tools, { replace: true });
+        }
+    }
+    // --- Fluent Configuration ---
+    /**
+     * Add instructions to the agent (replaces or appends).
+     */
+    withInstructions(instructions, options) {
+        this.chat.withInstructions(instructions, options);
+        return this;
+    }
+    /**
+     * Add tools to the agent.
+     */
+    withTools(tools, options) {
+        this.chat.withTools(tools, options);
+        return this;
+    }
+    /**
+     * Alias for withTools([tool]).
+     */
+    use(tool) {
+        return this.withTools([tool]);
+    }
+    /**
+     * Send a message to the agent and get a response.
+     */
+    async ask(message, options) {
+        if (options?.inputs) {
+            this.resolveLazyConfig(options.inputs);
+        }
+        return this.chat.ask(message, options);
+    }
+    /**
+     * Hook called when a tool call starts.
+     */
+    onToolCallStart(handler) {
+        this.chat.onToolCallStart(handler);
+        return this;
+    }
+    /**
+     * Hook called when a tool call ends.
+     */
+    onToolCallEnd(handler) {
+        this.chat.onToolCallEnd(handler);
+        return this;
+    }
+    /**
+     * Hook called when a tool call errors.
+     */
+    onToolCallError(handler) {
+        this.chat.onToolCallError(handler);
+        return this;
+    }
+    /**
+     * Hook called before a request.
+     */
+    beforeRequest(handler) {
+        this.chat.beforeRequest(handler);
+        return this;
+    }
+    /**
+     * Hook called after a response.
+     */
+    afterResponse(handler) {
+        this.chat.afterResponse(handler);
+        return this;
+    }
+    /**
+     * Alias for ask()
+     */
+    async say(message, options) {
+        return this.ask(message, options);
+    }
+    /**
+     * Stream a response from the agent.
+     */
+    stream(message, options) {
+        if (options?.inputs) {
+            this.resolveLazyConfig(options.inputs);
+        }
+        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.
+ */
+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;
+    };
+}