@node-llm/core 1.8.0 → 1.10.0

package/dist/chat/Chat.js

@@ -5,6 +5,7 @@ import { ChatStream } from "./ChatStream.js";
 import { ModelRegistry } from "../models/ModelRegistry.js";
 import { Schema } from "../schema/Schema.js";
 import { toJsonSchema } from "../schema/to-json-schema.js";
+import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import { config } from "../config.js";
 import { ToolExecutionMode } from "../constants.js";
@@ -12,6 +13,7 @@ import { ConfigurationError } from "../errors/index.js";
 import { ChatValidator } from "./Validation.js";
 import { ToolHandler } from "./ToolHandler.js";
 import { logger } from "../utils/logger.js";
+import { runMiddleware } from "../utils/middleware-runner.js";
 import { ChatResponseString } from "./ChatResponse.js";
 export class Chat {
     provider;
@@ -20,10 +22,12 @@ export class Chat {
     messages = [];
     systemMessages = [];
     executor;
+    middlewares = [];
     constructor(provider, model, options = {}, retryConfig = { attempts: 1, delayMs: 0 }) {
         this.provider = provider;
         this.model = model;
         this.options = options;
+        this.middlewares = options.middlewares || [];
         this.executor = new Executor(provider, retryConfig);
         if (options.systemPrompt) {
             this.withInstructions(options.systemPrompt);
@@ -150,6 +154,18 @@ export class Chat {
         }
         return this;
     }
+    /**
+     * Add a raw Message object to the chat history.
+     */
+    addMessage(message) {
+        if (message.role === "system" || message.role === "developer") {
+            this.systemMessages.push(message);
+        }
+        else {
+            this.messages.push(message);
+        }
+        return this;
+    }
     /**
      * Set the temperature for the chat session.
      * Controls randomness: 0.0 (deterministic) to 1.0 (creative).
@@ -290,6 +306,8 @@ export class Chat {
      * Ask the model a question
      */
     async ask(content, options) {
+        const requestId = randomUUID();
+        const state = {};
         let messageContent = content;
         const files = [...(options?.images ?? []), ...(options?.files ?? [])];
         if (files.length > 0) {
@@ -320,146 +338,74 @@ export class Chat {
                 }
             };
         }
-        const executeOptions = {
+        // Prepare Middleware Context
+        const context = {
+            requestId,
+            provider: this.provider.id,
             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, ...options?.headers },
-            response_format: responseFormat, // Pass to provider
-            requestTimeout: options?.requestTimeout ?? this.options.requestTimeout ?? config.requestTimeout,
-            thinking: options?.thinking ?? this.options.thinking,
-            signal: options?.signal,
-            ...this.options.params
+            options: this.options,
+            state
         };
-        // --- Content Policy Hooks (Input) ---
-        if (this.options.onBeforeRequest) {
-            const messagesToProcess = [...this.systemMessages, ...this.messages];
-            const result = await this.options.onBeforeRequest(messagesToProcess);
-            if (result) {
-                // If the hook returned modified messages, use them for this request
-                executeOptions.messages = result;
-            }
-        }
-        const totalUsage = { input_tokens: 0, output_tokens: 0, total_tokens: 0 };
-        const trackUsage = (u) => {
-            if (u) {
-                // Fallback cost calculation if provider didn't return it
-                if (u.cost === undefined) {
-                    const withCost = ModelRegistry.calculateCost(u, this.model, this.provider.id);
-                    u.cost = withCost.cost;
-                    u.input_cost = withCost.input_cost;
-                    u.output_cost = withCost.output_cost;
-                }
-                totalUsage.input_tokens += u.input_tokens;
-                totalUsage.output_tokens += u.output_tokens;
-                totalUsage.total_tokens += u.total_tokens;
-                if (u.cached_tokens) {
-                    totalUsage.cached_tokens = (totalUsage.cached_tokens ?? 0) + u.cached_tokens;
-                }
-                if (u.cost !== undefined) {
-                    totalUsage.cost = (totalUsage.cost ?? 0) + u.cost;
-                }
-                if (u.input_cost !== undefined) {
-                    totalUsage.input_cost = (totalUsage.input_cost ?? 0) + u.input_cost;
-                }
-                if (u.output_cost !== undefined) {
-                    totalUsage.output_cost = (totalUsage.output_cost ?? 0) + u.output_cost;
+        try {
+            // 1. onRequest Hook
+            await runMiddleware(this.middlewares, "onRequest", context);
+            // Re-read mutable context
+            const messagesToUse = context.messages || [];
+            const executeOptions = {
+                model: this.model,
+                messages: messagesToUse,
+                tools: this.options.tools,
+                temperature: options?.temperature ?? this.options.temperature,
+                max_tokens: options?.maxTokens ?? this.options.maxTokens ?? config.maxTokens,
+                headers: { ...this.options.headers, ...options?.headers },
+                response_format: responseFormat, // Pass to provider
+                requestTimeout: options?.requestTimeout ?? this.options.requestTimeout ?? config.requestTimeout,
+                thinking: options?.thinking ?? this.options.thinking,
+                signal: options?.signal,
+                ...this.options.params
+            };
+            // --- Content Policy Hooks (Input) ---
+            if (this.options.onBeforeRequest) {
+                const result = await this.options.onBeforeRequest(executeOptions.messages);
+                if (result) {
+                    executeOptions.messages = result;
                 }
             }
-        };
-        // First round
-        if (this.options.onNewMessage)
-            this.options.onNewMessage();
-        let response = await this.executor.executeChat(executeOptions);
-        trackUsage(response.usage);
-        let assistantMessage = new ChatResponseString(response.content ?? "", response.usage ?? { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, this.model, this.provider.id, response.thinking, response.reasoning, response.tool_calls, response.finish_reason);
-        // --- Content Policy Hooks (Output - Turn 1) ---
-        if (this.options.onAfterResponse) {
-            const result = await this.options.onAfterResponse(assistantMessage);
-            if (result) {
-                assistantMessage = result;
-            }
-        }
-        this.messages.push({
-            role: "assistant",
-            content: assistantMessage?.toString() || null,
-            tool_calls: response.tool_calls,
-            usage: response.usage
-        });
-        if (this.options.onEndMessage && (!response.tool_calls || response.tool_calls.length === 0)) {
-            this.options.onEndMessage(assistantMessage);
-        }
-        const maxToolCalls = options?.maxToolCalls ?? this.options.maxToolCalls ?? 5;
-        let stepCount = 0;
-        while (response.tool_calls && response.tool_calls.length > 0) {
-            // Dry-run mode: stop after proposing tools
-            if (!ToolHandler.shouldExecuteTools(response.tool_calls, this.options.toolExecution)) {
-                break;
-            }
-            stepCount++;
-            if (stepCount > maxToolCalls) {
-                throw new Error(`[NodeLLM] Maximum tool execution calls (${maxToolCalls}) exceeded.`);
-            }
-            for (const toolCall of response.tool_calls) {
-                // Human-in-the-loop: check for approval
-                if (this.options.toolExecution === ToolExecutionMode.CONFIRM) {
-                    const approved = await ToolHandler.requestToolConfirmation(toolCall, this.options.onConfirmToolCall);
-                    if (!approved) {
-                        this.messages.push(this.provider.formatToolResultMessage(toolCall.id, "Action cancelled by user."));
-                        continue;
+            const totalUsage = { input_tokens: 0, output_tokens: 0, total_tokens: 0 };
+            const trackUsage = (u) => {
+                if (u) {
+                    // Fallback cost calculation if provider didn't return it
+                    if (u.cost === undefined) {
+                        const withCost = ModelRegistry.calculateCost(u, this.model, this.provider.id);
+                        u.cost = withCost.cost;
+                        u.input_cost = withCost.input_cost;
+                        u.output_cost = withCost.output_cost;
                     }
-                }
-                try {
-                    const toolResult = await ToolHandler.execute(toolCall, this.options.tools, this.options.onToolCallStart, this.options.onToolCallEnd);
-                    this.messages.push(this.provider.formatToolResultMessage(toolResult.tool_call_id, toolResult.content));
-                }
-                catch (error) {
-                    let currentError = error;
-                    const directive = await this.options.onToolCallError?.(toolCall, currentError);
-                    if (directive === "STOP") {
-                        throw currentError;
+                    totalUsage.input_tokens += u.input_tokens;
+                    totalUsage.output_tokens += u.output_tokens;
+                    totalUsage.total_tokens += u.total_tokens;
+                    if (u.cached_tokens) {
+                        totalUsage.cached_tokens = (totalUsage.cached_tokens ?? 0) + u.cached_tokens;
                     }
-                    if (directive === "RETRY") {
-                        try {
-                            const toolResult = await ToolHandler.execute(toolCall, this.options.tools, this.options.onToolCallStart, this.options.onToolCallEnd);
-                            this.messages.push(this.provider.formatToolResultMessage(toolResult.tool_call_id, toolResult.content));
-                            continue;
-                        }
-                        catch (retryError) {
-                            // If retry also fails, fall through to default logic
-                            currentError = retryError;
-                        }
+                    if (u.cost !== undefined) {
+                        totalUsage.cost = (totalUsage.cost ?? 0) + u.cost;
                     }
-                    this.messages.push(this.provider.formatToolResultMessage(toolCall.id, `Fatal error executing tool '${toolCall.function.name}': ${currentError.message}`, { isError: true }));
-                    if (directive === "CONTINUE") {
-                        continue;
+                    if (u.input_cost !== undefined) {
+                        totalUsage.input_cost = (totalUsage.input_cost ?? 0) + u.input_cost;
                     }
-                    // Default short-circuit logic
-                    const errorObj = currentError;
-                    const isFatal = errorObj.fatal === true || errorObj.status === 401 || errorObj.status === 403;
-                    if (isFatal) {
-                        throw currentError;
+                    if (u.output_cost !== undefined) {
+                        totalUsage.output_cost = (totalUsage.output_cost ?? 0) + u.output_cost;
                     }
-                    logger.error(`Tool execution failed for '${toolCall.function.name}':`, currentError);
                 }
-            }
-            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
-            });
+            };
+            // First round
+            if (this.options.onNewMessage)
+                this.options.onNewMessage();
+            let response = await this.executor.executeChat(executeOptions);
             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.thinking, response.reasoning, response.tool_calls, response.finish_reason);
-            // --- Content Policy Hooks (Output - Tool Turns) ---
+            let assistantMessage = new ChatResponseString(response.content ?? "", response.usage ?? { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, this.model, this.provider.id, response.thinking, response.reasoning, response.tool_calls, response.finish_reason, this.options.schema);
+            // --- Content Policy Hooks (Output - Turn 1) ---
             if (this.options.onAfterResponse) {
                 const result = await this.options.onAfterResponse(assistantMessage);
                 if (result) {
@@ -475,10 +421,114 @@ export class Chat {
             if (this.options.onEndMessage && (!response.tool_calls || response.tool_calls.length === 0)) {
                 this.options.onEndMessage(assistantMessage);
             }
+            const maxToolCalls = options?.maxToolCalls ?? this.options.maxToolCalls ?? 5;
+            let stepCount = 0;
+            while (response.tool_calls && response.tool_calls.length > 0) {
+                // Dry-run mode: stop after proposing tools
+                if (!ToolHandler.shouldExecuteTools(response.tool_calls, this.options.toolExecution)) {
+                    break;
+                }
+                stepCount++;
+                if (stepCount > maxToolCalls) {
+                    throw new Error(`[NodeLLM] Maximum tool execution calls (${maxToolCalls}) exceeded.`);
+                }
+                for (const toolCall of response.tool_calls) {
+                    // Human-in-the-loop: check for approval
+                    if (this.options.toolExecution === ToolExecutionMode.CONFIRM) {
+                        const approved = await ToolHandler.requestToolConfirmation(toolCall, this.options.onConfirmToolCall);
+                        if (!approved) {
+                            this.messages.push(this.provider.formatToolResultMessage(toolCall.id, "Action cancelled by user."));
+                            continue;
+                        }
+                    }
+                    // 2. onToolCallStart Hook
+                    await runMiddleware(this.middlewares, "onToolCallStart", context, toolCall);
+                    try {
+                        const toolResult = await ToolHandler.execute(toolCall, this.options.tools, this.options.onToolCallStart, this.options.onToolCallEnd);
+                        // 3. onToolCallEnd Hook
+                        await runMiddleware(this.middlewares, "onToolCallEnd", context, toolCall, toolResult.content);
+                        this.messages.push(this.provider.formatToolResultMessage(toolResult.tool_call_id, toolResult.content));
+                    }
+                    catch (error) {
+                        let currentError = error;
+                        // 4. onToolCallError Hook
+                        const middlewareDirective = await runMiddleware(this.middlewares, "onToolCallError", context, toolCall, currentError);
+                        const directive = middlewareDirective ||
+                            (await this.options.onToolCallError?.(toolCall, currentError));
+                        if (directive === "STOP") {
+                            throw currentError;
+                        }
+                        if (directive === "RETRY") {
+                            // ... retry logic (simplified: recurse or duplicate logic? adhering to original logic)
+                            // Original logic duplicated the execution block. For brevity in this replacement, I'll simplified retry to "try once more"
+                            try {
+                                // Retry Hook? Maybe skip start hook on retry or re-run?
+                                // Let's assume onToolCallStart fires again for cleanliness?
+                                // Or just execute directly to match existing behavior.
+                                // Existing logs show we just call ToolHandler.execute again.
+                                const toolResult = await ToolHandler.execute(toolCall, this.options.tools, this.options.onToolCallStart, this.options.onToolCallEnd);
+                                await runMiddleware(this.middlewares, "onToolCallEnd", context, toolCall, toolResult.content);
+                                this.messages.push(this.provider.formatToolResultMessage(toolResult.tool_call_id, toolResult.content));
+                                continue;
+                            }
+                            catch (retryError) {
+                                currentError = retryError;
+                                await runMiddleware(this.middlewares, "onToolCallError", context, toolCall, currentError);
+                            }
+                        }
+                        this.messages.push(this.provider.formatToolResultMessage(toolCall.id, `Fatal error executing tool '${toolCall.function.name}': ${currentError.message}`, { isError: true }));
+                        if (directive === "CONTINUE") {
+                            continue;
+                        }
+                        // Default short-circuit logic
+                        const errorObj = currentError;
+                        const isFatal = errorObj.fatal === true || errorObj.status === 401 || errorObj.status === 403;
+                        if (isFatal) {
+                            throw currentError;
+                        }
+                        logger.error(`Tool execution failed for '${toolCall.function.name}':`, currentError);
+                    }
+                }
+                response = await this.executor.executeChat({
+                    model: this.model,
+                    messages: [...this.systemMessages, ...this.messages], // Use updated history
+                    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, // Pass to provider
+                    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.thinking, response.reasoning, response.tool_calls, response.finish_reason, this.options.schema);
+                if (this.options.onAfterResponse) {
+                    const result = await this.options.onAfterResponse(assistantMessage);
+                    if (result)
+                        assistantMessage = result;
+                }
+                this.messages.push({
+                    role: "assistant",
+                    content: assistantMessage?.toString() || null,
+                    tool_calls: response.tool_calls,
+                    usage: response.usage
+                });
+                if (this.options.onEndMessage &&
+                    (!response.tool_calls || response.tool_calls.length === 0)) {
+                    this.options.onEndMessage(assistantMessage);
+                }
+            }
+            const finalResponse = new ChatResponseString(assistantMessage.toString() || "", totalUsage, this.model, this.provider.id, assistantMessage.thinking, assistantMessage.reasoning, response.tool_calls, assistantMessage.finish_reason, this.options.schema);
+            // 5. onResponse Hook
+            await runMiddleware(this.middlewares, "onResponse", context, finalResponse);
+            return finalResponse;
+        }
+        catch (err) {
+            // 6. onError Hook
+            await runMiddleware(this.middlewares, "onError", context, err);
+            throw err;
         }
-        // For the final return, we might want to aggregate reasoning too if it happened in multiple turns?
-        // Usually reasoning only happens once or we just want the last one.
-        return new ChatResponseString(assistantMessage.toString() || "", totalUsage, this.model, this.provider.id, assistantMessage.thinking, assistantMessage.reasoning, response.tool_calls, assistantMessage.finish_reason);
     }
     /**
      * Streams the model's response to a user question.

package/dist/chat/ChatOptions.d.ts

@@ -1,3 +1,4 @@
+import { Middleware } from "../types/Middleware.js";
 import { Message } from "./Message.js";
 import { ToolResolvable } from "./Tool.js";
 import { Schema } from "../schema/Schema.js";
@@ -6,6 +7,7 @@ import { ToolExecutionMode } from "../constants.js";
 import { ResponseFormat, ThinkingConfig } from "../providers/Provider.js";
 export interface ChatOptions {
     systemPrompt?: string;
+    middlewares?: Middleware[];
     messages?: Message[];
     tools?: ToolResolvable[];
     temperature?: number;

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,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1E,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,kBAAkB,KAAK,IAAI,CAAC;IACrD,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IAC9C,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7D,eAAe,CAAC,EAAE,CAChB,QAAQ,EAAE,OAAO,EACjB,KAAK,EAAE,KAAK,KACT,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACtE,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;IACrE,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;CACxF"}
+{"version":3,"file":"ChatOptions.d.ts","sourceRoot":"","sources":["../../src/chat/ChatOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1E,MAAM,WAAW,WAAW;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,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,kBAAkB,KAAK,IAAI,CAAC;IACrD,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IAC9C,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7D,eAAe,CAAC,EAAE,CAChB,QAAQ,EAAE,OAAO,EACjB,KAAK,EAAE,KAAK,KACT,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACtE,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;IACrE,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;CACxF"}

package/dist/chat/ChatResponse.d.ts

@@ -1,5 +1,6 @@
 import { Usage, ThinkingResult } from "../providers/Provider.js";
 import { ToolCall } from "./Tool.js";
+import { Schema } from "../schema/Schema.js";
 /**
  * Enhanced string that includes token usage metadata.
  * Behaves like a regular string but has .usage and .input_tokens etc.
@@ -12,7 +13,10 @@ export declare class ChatResponseString extends String {
     readonly reasoning?: string | null | undefined;
     readonly tool_calls?: ToolCall[] | undefined;
     readonly finish_reason?: string | null | undefined;
-    constructor(content: string, usage: Usage, model: string, provider: string, thinking?: ThinkingResult | undefined, reasoning?: string | null | undefined, tool_calls?: ToolCall[] | undefined, finish_reason?: string | null | undefined);
+    readonly schema?: Schema | undefined;
+    private _cachedData;
+    private _validationError;
+    constructor(content: string, usage: Usage, model: string, provider: string, thinking?: ThinkingResult | undefined, reasoning?: string | null | undefined, tool_calls?: ToolCall[] | undefined, finish_reason?: string | null | undefined, schema?: Schema | undefined);
     get finishReason(): string | null | undefined;
     get input_tokens(): number;
     get output_tokens(): number;
@@ -58,9 +62,26 @@ export declare class ChatResponseString extends String {
      */
     withContent(newContent: string): ChatResponseString;
     /**
-     * Attempt to parse the content as JSON.
-     * Returns the parsed object or null if parsing fails.
+     * Attempt to extract and parse the content as JSON.
      */
     get parsed(): unknown;
+    /**
+     * Access the parsed data.
+     * If a Zod schema was provided via .withSchema(), this will validate the data.
+     * Throws ZodError if validation fails.
+     */
+    get data(): unknown;
+    /**
+     * Safe version of .data that returns null instead of throwing on validation error.
+     */
+    get safeData(): unknown;
+    /**
+     * Returns true if the content contains valid JSON that matches the schema (if provided).
+     */
+    get isValid(): boolean;
+    /**
+     * Returns the validation error if the content doesn't match the schema.
+     */
+    get validationError(): Error | null;
 }
 //# sourceMappingURL=ChatResponse.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ChatResponse.d.ts","sourceRoot":"","sources":["../../src/chat/ChatResponse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,MAAM;aAG1B,KAAK,EAAE,KAAK;aACZ,KAAK,EAAE,MAAM;aACb,QAAQ,EAAE,MAAM;aAChB,QAAQ,CAAC,EAAE,cAAc;aACzB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;aACzB,UAAU,CAAC,EAAE,QAAQ,EAAE;aACvB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;gBAP7C,OAAO,EAAE,MAAM,EACC,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,cAAc,YAAA,EACzB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,YAAA,EACzB,UAAU,CAAC,EAAE,QAAQ,EAAE,YAAA,EACvB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,YAAA;IAK/C,IAAI,YAAY,8BAEf;IAED,IAAI,YAAY,WAEf;IACD,IAAI,aAAa,WAEhB;IACD,IAAI,YAAY,WAEf;IACD,IAAI,aAAa,uBAEhB;IACD,IAAI,IAAI,uBAEP;IACD,IAAI,UAAU,uBAEb;IACD,IAAI,WAAW,uBAEd;IAGD,IAAI,WAAW,WAEd;IACD,IAAI,YAAY,WAEf;IACD,IAAI,WAAW,WAEd;IACD,IAAI,YAAY,uBAEf;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;;OAGG;IACH,IAAI,IAAI;;;;;;;;MAUP;IAED;;OAEG;IACH,IAAI,GAAG;;;;;;;;MAEN;IAED,QAAQ;IAIR;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB;IAanD;;;OAGG;IACH,IAAI,MAAM,IAAI,OAAO,CAMpB;CACF"}
+{"version":3,"file":"ChatResponse.d.ts","sourceRoot":"","sources":["../../src/chat/ChatResponse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAI7C;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,MAAM;aAM1B,KAAK,EAAE,KAAK;aACZ,KAAK,EAAE,MAAM;aACb,QAAQ,EAAE,MAAM;aAChB,QAAQ,CAAC,EAAE,cAAc;aACzB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;aACzB,UAAU,CAAC,EAAE,QAAQ,EAAE;aACvB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;aAC7B,MAAM,CAAC,EAAE,MAAM;IAZjC,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,gBAAgB,CAAsB;gBAG5C,OAAO,EAAE,MAAM,EACC,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,cAAc,YAAA,EACzB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,YAAA,EACzB,UAAU,CAAC,EAAE,QAAQ,EAAE,YAAA,EACvB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,YAAA,EAC7B,MAAM,CAAC,EAAE,MAAM,YAAA;IAKjC,IAAI,YAAY,8BAEf;IAED,IAAI,YAAY,WAEf;IACD,IAAI,aAAa,WAEhB;IACD,IAAI,YAAY,WAEf;IACD,IAAI,aAAa,uBAEhB;IACD,IAAI,IAAI,uBAEP;IACD,IAAI,UAAU,uBAEb;IACD,IAAI,WAAW,uBAEd;IAGD,IAAI,WAAW,WAEd;IACD,IAAI,YAAY,WAEf;IACD,IAAI,WAAW,WAEd;IACD,IAAI,YAAY,uBAEf;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;;OAGG;IACH,IAAI,IAAI;;;;;;;;MAUP;IAED;;OAEG;IACH,IAAI,GAAG;;;;;;;;MAEN;IAED,QAAQ;IAIR;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB;IAcnD;;OAEG;IACH,IAAI,MAAM,IAAI,OAAO,CAOpB;IAED;;;;OAIG;IACH,IAAI,IAAI,IAAI,OAAO,CAkBlB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,OAAO,CAMtB;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,OAAO,CAQrB;IAED;;OAEG;IACH,IAAI,eAAe,IAAI,KAAK,GAAG,IAAI,CAOlC;CACF"}

package/dist/chat/ChatResponse.js

@@ -1,3 +1,5 @@
+import { extractJson } from "../utils/json.js";
+import { z } from "zod";
 /**
  * Enhanced string that includes token usage metadata.
  * Behaves like a regular string but has .usage and .input_tokens etc.
@@ -10,7 +12,10 @@ export class ChatResponseString extends String {
     reasoning;
     tool_calls;
     finish_reason;
-    constructor(content, usage, model, provider, thinking, reasoning, tool_calls, finish_reason) {
+    schema;
+    _cachedData = undefined;
+    _validationError = null;
+    constructor(content, usage, model, provider, thinking, reasoning, tool_calls, finish_reason, schema) {
         super(content);
         this.usage = usage;
         this.model = model;
@@ -19,6 +24,7 @@ export class ChatResponseString extends String {
         this.reasoning = reasoning;
         this.tool_calls = tool_calls;
         this.finish_reason = finish_reason;
+        this.schema = schema;
     }
     get finishReason() {
         return this.finish_reason;
@@ -91,18 +97,79 @@ export class ChatResponseString extends String {
      * Return a new ChatResponseString with modified content but preserved metadata.
      */
     withContent(newContent) {
-        return new ChatResponseString(newContent, this.usage, this.model, this.provider, this.thinking, this.reasoning, this.tool_calls, this.finish_reason);
+        return new ChatResponseString(newContent, this.usage, this.model, this.provider, this.thinking, this.reasoning, this.tool_calls, this.finish_reason, this.schema);
     }
     /**
-     * Attempt to parse the content as JSON.
-     * Returns the parsed object or null if parsing fails.
+     * Attempt to extract and parse the content as JSON.
      */
     get parsed() {
         try {
-            return JSON.parse(this.valueOf());
+            const cleanJson = extractJson(this.valueOf());
+            return JSON.parse(cleanJson);
         }
         catch {
             return null;
         }
     }
+    /**
+     * Access the parsed data.
+     * If a Zod schema was provided via .withSchema(), this will validate the data.
+     * Throws ZodError if validation fails.
+     */
+    get data() {
+        if (this._cachedData !== undefined)
+            return this._cachedData;
+        if (this._validationError)
+            throw this._validationError;
+        const json = this.parsed;
+        if (this.schema && this.schema.definition.schema instanceof z.ZodType) {
+            try {
+                this._cachedData = this.schema.definition.schema.parse(json);
+                return this._cachedData;
+            }
+            catch (e) {
+                this._validationError = e;
+                throw e;
+            }
+        }
+        this._cachedData = json;
+        return json;
+    }
+    /**
+     * Safe version of .data that returns null instead of throwing on validation error.
+     */
+    get safeData() {
+        try {
+            return this.data;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Returns true if the content contains valid JSON that matches the schema (if provided).
+     */
+    get isValid() {
+        if (!this.schema)
+            return this.parsed !== null;
+        try {
+            void this.data;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Returns the validation error if the content doesn't match the schema.
+     */
+    get validationError() {
+        try {
+            void this.data;
+            return null;
+        }
+        catch (e) {
+            return e;
+        }
+    }
 }

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,EACL,WAAW,EAIZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAyB,MAAM,0BAA0B,CAAC;AAEtF,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAGhD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AASvC;;;GAGG;AACH,qBAAa,UAAU;IAKnB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,QAAQ,CAAY;IAC5B,OAAO,CAAC,cAAc,CAAY;gBAGf,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,WAAgB,EAC1C,QAAQ,CAAC,EAAE,OAAO,EAAE,EACpB,cAAc,CAAC,EAAE,OAAO,EAAE;IA6B5B,IAAI,OAAO,IAAI,SAAS,OAAO,EAAE,CAEhC;IAED,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,EAAE,OAAO,GAAE,UAAe,GAAG,MAAM,CAAC,SAAS,CAAC;CA4QrF"}
+{"version":3,"file":"ChatStream.d.ts","sourceRoot":"","sources":["../../src/chat/ChatStream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EACL,WAAW,EAIZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAyB,MAAM,0BAA0B,CAAC;AAEtF,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAGhD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAavC;;;GAGG;AACH,qBAAa,UAAU;IAKnB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,QAAQ,CAAY;IAC5B,OAAO,CAAC,cAAc,CAAY;gBAGf,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,WAAgB,EAC1C,QAAQ,CAAC,EAAE,OAAO,EAAE,EACpB,cAAc,CAAC,EAAE,OAAO,EAAE;IA6B5B,IAAI,OAAO,IAAI,SAAS,OAAO,EAAE,CAEhC;IAED,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,EAAE,OAAO,GAAE,UAAe,GAAG,MAAM,CAAC,SAAS,CAAC;CA8WrF"}