@aigne/core 1.13.0 → 1.14.0

package/lib/cjs/models/bedrock-chat-model.js

@@ -6,14 +6,21 @@ const client_bedrock_runtime_1 = require("@aws-sdk/client-bedrock-runtime");
 const nanoid_1 = require("nanoid");
 const zod_1 = require("zod");
 const json_schema_js_1 = require("../utils/json-schema.js");
+const model_utils_js_1 = require("../utils/model-utils.js");
 const prompts_js_1 = require("../utils/prompts.js");
 const stream_utils_js_1 = require("../utils/stream-utils.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
 const chat_model_js_1 = require("./chat-model.js");
+/**
+ * @hidden
+ */
 function extractLastJsonObject(text) {
     return text.replace(/<thinking>[\s\S]*?<\/thinking>/g, "").trim();
 }
 const BEDROCK_DEFAULT_CHAT_MODEL = "us.amazon.nova-lite-v1:0";
+/**
+ * @hidden
+ */
 exports.bedrockChatModelOptionsSchema = zod_1.z.object({
     region: zod_1.z.string().optional(),
     model: zod_1.z.string().optional(),
@@ -36,6 +43,9 @@ class BedrockChatModel extends chat_model_js_1.ChatModel {
         super();
         this.options = options;
     }
+    /**
+     * @hidden
+     */
     _client;
     get client() {
         const credentials = this.options?.accessKeyId && this.options?.secretAccessKey
@@ -53,7 +63,7 @@ class BedrockChatModel extends chat_model_js_1.ChatModel {
     get modelOptions() {
         return this.options?.modelOptions;
     }
-    async process(input, _context, options) {
+    async process(input) {
         const modelId = input.modelOptions?.model ?? this.modelOptions?.model ?? BEDROCK_DEFAULT_CHAT_MODEL;
         const { messages, system } = getRunMessages(input);
         const toolConfig = convertTools(input);
@@ -70,13 +80,17 @@ class BedrockChatModel extends chat_model_js_1.ChatModel {
         const command = new client_bedrock_runtime_1.ConverseStreamCommand(body);
         const response = await this.client.send(command);
         const jsonMode = input.responseFormat?.type === "json_schema";
-        if (options?.streaming && !jsonMode) {
-            return this.extractResultFromStream(response.stream, modelId, false, true);
+        if (!jsonMode) {
+            return this.extractResultFromStream(response.stream, modelId, true);
+        }
+        const result = await this.extractResultFromStream(response.stream, modelId, false);
+        if (!result.toolCalls?.length && jsonMode && result.text) {
+            const output = await this.requestStructuredOutput(body, input.responseFormat);
+            return { ...output, usage: (0, model_utils_js_1.mergeUsage)(result.usage, output.usage) };
         }
-        const result = await this.extractResultFromStream(response.stream, modelId, jsonMode, false);
         return result;
     }
-    async extractResultFromStream(stream, modelId, jsonMode, streaming) {
+    async extractResultFromStream(stream, modelId, streaming) {
         if (!stream)
             throw new Error("Unable to get AI model response.");
         const result = new ReadableStream({
@@ -84,7 +98,6 @@ class BedrockChatModel extends chat_model_js_1.ChatModel {
                 try {
                     controller.enqueue({ delta: { json: { model: modelId } } });
                     const toolCalls = [];
-                    let text = "";
                     let usage;
                     for await (const chunk of stream) {
                         if (chunk.contentBlockStart?.start?.toolUse) {
@@ -107,10 +120,7 @@ class BedrockChatModel extends chat_model_js_1.ChatModel {
                             const block = chunk.contentBlockDelta;
                             const delta = block.delta;
                             if (delta?.text) {
-                                text += delta.text;
-                                if (!jsonMode) {
-                                    controller.enqueue({ delta: { text: { text: delta.text } } });
-                                }
+                                controller.enqueue({ delta: { text: { text: delta.text } } });
                             }
                             if (delta?.toolUse) {
                                 if (block.contentBlockIndex === undefined)
@@ -125,14 +135,6 @@ class BedrockChatModel extends chat_model_js_1.ChatModel {
                             usage = chunk.metadata.usage;
                         }
                     }
-                    if (jsonMode && text) {
-                        const match = extractLastJsonObject(text);
-                        if (!match)
-                            throw new Error("Failed to extract JSON object from model output");
-                        controller.enqueue({
-                            delta: { json: { json: (0, json_schema_js_1.parseJSON)(match) } },
-                        });
-                    }
                     if (toolCalls.length) {
                         controller.enqueue({
                             delta: {
@@ -157,9 +159,42 @@ class BedrockChatModel extends chat_model_js_1.ChatModel {
         });
         return streaming ? result : await (0, stream_utils_js_1.agentResponseStreamToObject)(result);
     }
+    async requestStructuredOutput(body, responseFormat) {
+        if (responseFormat?.type !== "json_schema") {
+            throw new Error("Expected json_schema response format");
+        }
+        const system = [
+            ...(body.system ?? []),
+            {
+                text: `Use the generate_json tool to generate a json result. ${(0, prompts_js_1.getJsonToolInputPrompt)(responseFormat.jsonSchema.schema)}`,
+            },
+        ];
+        const toolConfig = {
+            tools: [
+                {
+                    toolSpec: {
+                        name: "generate_json",
+                        description: "Generate a json result by given context",
+                        inputSchema: { json: responseFormat.jsonSchema.schema },
+                    },
+                },
+            ],
+            toolChoice: { tool: { name: "generate_json" } },
+        };
+        const command = new client_bedrock_runtime_1.ConverseCommand({ ...body, system, toolConfig });
+        const response = await this.client.send(command);
+        const jsonTool = response.output?.message?.content?.find((i) => i.toolUse?.name === "generate_json");
+        if (!jsonTool)
+            throw new Error("Json tool not found");
+        return {
+            json: jsonTool.toolUse?.input,
+            model: body.modelId,
+            usage: response.usage,
+        };
+    }
 }
 exports.BedrockChatModel = BedrockChatModel;
-const getRunMessages = ({ messages: msgs, responseFormat, }) => {
+const getRunMessages = ({ messages: msgs, }) => {
     const system = [];
     const messages = [];
     for (const msg of msgs) {
@@ -221,11 +256,6 @@ const getRunMessages = ({ messages: msgs, responseFormat, }) => {
     if (messages.at(0)?.role !== "user") {
         messages.unshift({ role: "user", content: [{ text: "." }] });
     }
-    if (responseFormat?.type === "json_schema") {
-        system.push({
-            text: (0, prompts_js_1.getJsonOutputPrompt)(responseFormat.jsonSchema.schema),
-        });
-    }
     return { messages, system };
 };
 function convertContent(content) {

package/lib/cjs/models/chat-model.d.ts

@@ -1,26 +1,154 @@
-import { Agent, type Message } from "../agents/agent.js";
+import { Agent, type AgentProcessResult, type Message } from "../agents/agent.js";
 import type { Context } from "../aigne/context.js";
+import type { PromiseOrValue } from "../utils/type-utils.js";
+/**
+ * ChatModel is an abstract base class for interacting with Large Language Models (LLMs).
+ *
+ * This class extends the Agent class and provides a common interface for handling model inputs,
+ * outputs, and capabilities. Specific model implementations (like OpenAI, Anthropic, etc.)
+ * should inherit from this class and implement their specific functionalities.
+ *
+ * @example
+ * Here's how to implement a custom ChatModel:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model}
+ *
+ * @example
+ * Here's an example showing streaming response with readable stream:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-streaming}
+ *
+ * @example
+ * Here's an example showing streaming response with async generator:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-streaming-async-generator}
+ *
+ * @example
+ * Here's an example with tool calls:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ */
 export declare abstract class ChatModel extends Agent<ChatModelInput, ChatModelOutput> {
     constructor();
+    /**
+     * Indicates whether the model supports parallel tool calls
+     *
+     * Defaults to true, subclasses can override this property based on
+     * specific model capabilities
+     */
     protected supportsParallelToolCalls: boolean;
+    /**
+     * Gets the model's supported capabilities
+     *
+     * Currently returns capabilities including: whether parallel tool calls are supported
+     *
+     * @returns An object containing model capabilities
+     */
     getModelCapabilities(): {
         supportsParallelToolCalls: boolean;
     };
     private validateToolNames;
+    /**
+     * Performs preprocessing operations before handling input
+     *
+     * Primarily checks if token usage exceeds limits, throwing an exception if limits are exceeded
+     *
+     * @param input Input message
+     * @param context Execution context
+     * @throws Error if token usage exceeds maximum limit
+     */
     protected preprocess(input: ChatModelInput, context: Context): void;
+    /**
+     * Performs postprocessing operations after handling output
+     *
+     * Primarily updates token usage statistics in the context
+     *
+     * @param input Input message
+     * @param output Output message
+     * @param context Execution context
+     */
     protected postprocess(input: ChatModelInput, output: ChatModelOutput, context: Context): void;
+    /**
+     * Processes input messages and generates model responses
+     *
+     * This is the core method that must be implemented by all ChatModel subclasses.
+     * It handles the communication with the underlying language model,
+     * processes the input messages, and generates appropriate responses.
+     *
+     * Implementations should handle:
+     * - Conversion of input format to model-specific format
+     * - Sending requests to the language model
+     * - Processing model responses
+     * - Handling streaming responses if supported
+     * - Proper error handling and retries
+     * - Token counting and usage tracking
+     * - Tool call processing if applicable
+     *
+     * @param input - The standardized input containing messages and model options
+     * @param context - The execution context with settings and state
+     * @returns A promise or direct value containing the model's response
+     */
+    abstract process(input: ChatModelInput, context: Context): PromiseOrValue<AgentProcessResult<ChatModelOutput>>;
 }
+/**
+ * Input message format for ChatModel
+ *
+ * Contains an array of messages to send to the model, response format settings,
+ * tool definitions, and model-specific options
+ *
+ * @example
+ * Here's a basic ChatModel input example:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model}
+ *
+ * @example
+ * Here's an example with tool calling:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ */
 export interface ChatModelInput extends Message {
+    /**
+     * Array of messages to send to the model
+     */
     messages: ChatModelInputMessage[];
+    /**
+     * Specifies the expected response format
+     */
     responseFormat?: ChatModelInputResponseFormat;
+    /**
+     * List of tools available for the model to use
+     */
     tools?: ChatModelInputTool[];
+    /**
+     * Specifies the tool selection strategy
+     */
     toolChoice?: ChatModelInputToolChoice;
+    /**
+     * Model-specific configuration options
+     */
     modelOptions?: ChatModelOptions;
 }
+/**
+ * Message role types
+ *
+ * - system: System instructions
+ * - user: User messages
+ * - agent: Agent/assistant messages
+ * - tool: Tool call responses
+ */
 export type Role = "system" | "user" | "agent" | "tool";
+/**
+ * Structure of input messages
+ *
+ * Defines the format of each message sent to the model, including
+ * role, content, and tool call related information
+ */
 export interface ChatModelInputMessage {
+    /**
+     * Role of the message (system, user, agent, or tool)
+     */
     role: Role;
+    /**
+     * Message content, can be text or multimodal content array
+     */
     content?: ChatModelInputMessageContent;
+    /**
+     * Tool call details when the agent wants to execute tool calls
+     */
     toolCalls?: {
         id: string;
         type: "function";
@@ -29,18 +157,44 @@ export interface ChatModelInputMessage {
             arguments: Message;
         };
     }[];
+    /**
+     * For tool response messages, specifies the corresponding tool call ID
+     */
     toolCallId?: string;
+    /**
+     * Name of the message sender (for multi-agent scenarios)
+     */
     name?: string;
 }
+/**
+ * Type of input message content
+ *
+ * Can be a simple string, or a mixed array of text and image content
+ */
 export type ChatModelInputMessageContent = string | (TextContent | ImageUrlContent)[];
+/**
+ * Text content type
+ *
+ * Used for text parts of message content
+ */
 export type TextContent = {
     type: "text";
     text: string;
 };
+/**
+ * Image URL content type
+ *
+ * Used for image parts of message content, referencing images via URL
+ */
 export type ImageUrlContent = {
     type: "image_url";
     url: string;
 };
+/**
+ * Model response format settings
+ *
+ * Can be specified as plain text format or according to a JSON Schema
+ */
 export type ChatModelInputResponseFormat = {
     type: "text";
 } | {
@@ -52,14 +206,51 @@ export type ChatModelInputResponseFormat = {
         strict?: boolean;
     };
 };
+/**
+ * Tool definition provided to the model
+ *
+ * Defines a function tool, including name, description and parameter structure
+ *
+ * @example
+ * Here's an example showing how to use tools:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ */
 export interface ChatModelInputTool {
+    /**
+     * Tool type, currently only "function" is supported
+     */
     type: "function";
+    /**
+     * Function tool definition
+     */
     function: {
+        /**
+         * Function name
+         */
         name: string;
+        /**
+         * Function description
+         */
         description?: string;
+        /**
+         * Function parameter structure definition
+         */
         parameters: object;
     };
 }
+/**
+ * Tool selection strategy
+ *
+ * Determines how the model selects and uses tools:
+ * - "auto": Automatically decides whether to use tools
+ * - "none": Does not use any tools
+ * - "required": Must use tools
+ * - object: Specifies a particular tool function
+ *
+ * @example
+ * Here's an example showing how to use tools:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ */
 export type ChatModelInputToolChoice = "auto" | "none" | "required" | {
     type: "function";
     function: {
@@ -67,30 +258,116 @@ export type ChatModelInputToolChoice = "auto" | "none" | "required" | {
         description?: string;
     };
 };
+/**
+ * Model-specific configuration options
+ *
+ * Contains various parameters for controlling model behavior, such as model name, temperature, etc.
+ */
 export interface ChatModelOptions {
+    /**
+     * Model name or version
+     */
     model?: string;
+    /**
+     * Temperature parameter, controls randomness (0-1)
+     */
     temperature?: number;
+    /**
+     * Top-p parameter, controls vocabulary diversity
+     */
     topP?: number;
+    /**
+     * Frequency penalty parameter, reduces repetition
+     */
     frequencyPenalty?: number;
+    /**
+     * Presence penalty parameter, encourages diversity
+     */
     presencePenalty?: number;
+    /**
+     * Whether to allow parallel tool calls
+     */
     parallelToolCalls?: boolean;
 }
+/**
+ * Output message format for ChatModel
+ *
+ * Contains model response content, which can be text, JSON data, tool calls, and usage statistics
+ *
+ * @example
+ * Here's a basic output example:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model}
+ *
+ * @example
+ * Here's an example with tool calls:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ */
 export interface ChatModelOutput extends Message {
+    /**
+     * Text format response content
+     */
     text?: string;
+    /**
+     * JSON format response content
+     */
     json?: object;
+    /**
+     * List of tools the model requested to call
+     */
     toolCalls?: ChatModelOutputToolCall[];
+    /**
+     * Token usage statistics
+     */
     usage?: ChatModelOutputUsage;
+    /**
+     * Model name or version used
+     */
     model?: string;
 }
+/**
+ * Tool call information in model output
+ *
+ * Describes tool calls requested by the model, including tool ID and call parameters
+ *
+ * @example
+ * Here's an example with tool calls:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ */
 export interface ChatModelOutputToolCall {
+    /**
+     * Unique ID of the tool call
+     */
     id: string;
+    /**
+     * Tool type, currently only "function" is supported
+     */
     type: "function";
+    /**
+     * Function call details
+     */
     function: {
+        /**
+         * Name of the function being called
+         */
         name: string;
+        /**
+         * Arguments for the function call
+         */
         arguments: Message;
     };
 }
+/**
+ * Model usage statistics
+ *
+ * Records the number of input and output tokens for tracking model usage
+ */
 export interface ChatModelOutputUsage {
+    /**
+     * Number of input tokens
+     */
     inputTokens: number;
+    /**
+     * Number of output tokens
+     */
     outputTokens: number;
 }

package/lib/cjs/models/chat-model.js

@@ -3,6 +3,29 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChatModel = void 0;
 const zod_1 = require("zod");
 const agent_js_1 = require("../agents/agent.js");
+/**
+ * ChatModel is an abstract base class for interacting with Large Language Models (LLMs).
+ *
+ * This class extends the Agent class and provides a common interface for handling model inputs,
+ * outputs, and capabilities. Specific model implementations (like OpenAI, Anthropic, etc.)
+ * should inherit from this class and implement their specific functionalities.
+ *
+ * @example
+ * Here's how to implement a custom ChatModel:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model}
+ *
+ * @example
+ * Here's an example showing streaming response with readable stream:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-streaming}
+ *
+ * @example
+ * Here's an example showing streaming response with async generator:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-streaming-async-generator}
+ *
+ * @example
+ * Here's an example with tool calls:
+ * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ */
 class ChatModel extends agent_js_1.Agent {
     constructor() {
         super({
@@ -10,7 +33,20 @@ class ChatModel extends agent_js_1.Agent {
             outputSchema: chatModelOutputSchema,
         });
     }
+    /**
+     * Indicates whether the model supports parallel tool calls
+     *
+     * Defaults to true, subclasses can override this property based on
+     * specific model capabilities
+     */
     supportsParallelToolCalls = true;
+    /**
+     * Gets the model's supported capabilities
+     *
+     * Currently returns capabilities including: whether parallel tool calls are supported
+     *
+     * @returns An object containing model capabilities
+     */
     getModelCapabilities() {
         return {
             supportsParallelToolCalls: this.supportsParallelToolCalls,
@@ -23,6 +59,15 @@ class ChatModel extends agent_js_1.Agent {
             }
         }
     }
+    /**
+     * Performs preprocessing operations before handling input
+     *
+     * Primarily checks if token usage exceeds limits, throwing an exception if limits are exceeded
+     *
+     * @param input Input message
+     * @param context Execution context
+     * @throws Error if token usage exceeds maximum limit
+     */
     preprocess(input, context) {
         super.preprocess(input, context);
         const { limits, usage } = context;
@@ -32,6 +77,15 @@ class ChatModel extends agent_js_1.Agent {
         }
         this.validateToolNames(input.tools);
     }
+    /**
+     * Performs postprocessing operations after handling output
+     *
+     * Primarily updates token usage statistics in the context
+     *
+     * @param input Input message
+     * @param output Output message
+     * @param context Execution context
+     */
     postprocess(input, output, context) {
         super.postprocess(input, output, context);
         const { usage } = output;

package/lib/cjs/models/claude-chat-model.d.ts

@@ -1,13 +1,32 @@
 import Anthropic from "@anthropic-ai/sdk";
 import { z } from "zod";
-import type { AgentInvokeOptions, AgentResponse } from "../agents/agent.js";
-import type { Context } from "../aigne/context.js";
+import type { AgentProcessResult } from "../agents/agent.js";
+import { type PromiseOrValue } from "../utils/type-utils.js";
 import { ChatModel, type ChatModelInput, type ChatModelOptions, type ChatModelOutput } from "./chat-model.js";
+/**
+ * Configuration options for Claude Chat Model
+ */
 export interface ClaudeChatModelOptions {
+    /**
+     * API key for Anthropic's Claude API
+     *
+     * If not provided, will look for ANTHROPIC_API_KEY or CLAUDE_API_KEY in environment variables
+     */
     apiKey?: string;
+    /**
+     * Claude model to use
+     *
+     * Defaults to 'claude-3-7-sonnet-latest'
+     */
     model?: string;
+    /**
+     * Additional model options to control behavior
+     */
     modelOptions?: ChatModelOptions;
 }
+/**
+ * @hidden
+ */
 export declare const claudeChatModelOptionsSchema: z.ZodObject<{
     apiKey: z.ZodOptional<z.ZodString>;
     model: z.ZodOptional<z.ZodString>;
@@ -56,13 +75,40 @@ export declare const claudeChatModelOptionsSchema: z.ZodObject<{
     model?: string | undefined;
     apiKey?: string | undefined;
 }>;
+/**
+ * Implementation of the ChatModel interface for Anthropic's Claude API
+ *
+ * This model provides access to Claude's capabilities including:
+ * - Text generation
+ * - Tool use
+ * - JSON structured output
+ *
+ * Default model: 'claude-3-7-sonnet-latest'
+ *
+ * @example
+ * Here's how to create and use a Claude chat model:
+ * {@includeCode ../../test/models/claude-chat-model.test.ts#example-claude-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../../test/models/claude-chat-model.test.ts#example-claude-chat-model-streaming-async-generator}
+ */
 export declare class ClaudeChatModel extends ChatModel {
     options?: ClaudeChatModelOptions | undefined;
     constructor(options?: ClaudeChatModelOptions | undefined);
+    /**
+     * @hidden
+     */
     protected _client?: Anthropic;
     get client(): Anthropic;
     get modelOptions(): ChatModelOptions | undefined;
-    process(input: ChatModelInput, _context: Context, options?: AgentInvokeOptions): Promise<AgentResponse<ChatModelOutput>>;
+    /**
+     * Process the input using Claude's chat model
+     * @param input - The input to process
+     * @returns The processed output from the model
+     */
+    process(input: ChatModelInput): PromiseOrValue<AgentProcessResult<ChatModelOutput>>;
+    private _process;
     private extractResultFromClaudeStream;
     private requestStructuredOutput;
 }