@aigne/core 1.12.0 → 1.14.0

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

@@ -0,0 +1,303 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BedrockChatModel = exports.bedrockChatModelOptionsSchema = void 0;
+exports.extractLastJsonObject = extractLastJsonObject;
+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(),
+    modelOptions: zod_1.z
+        .object({
+        model: zod_1.z.string().optional(),
+        temperature: zod_1.z.number().optional(),
+        topP: zod_1.z.number().optional(),
+        frequencyPenalty: zod_1.z.number().optional(),
+        presencePenalty: zod_1.z.number().optional(),
+        parallelToolCalls: zod_1.z.boolean().optional().default(true),
+    })
+        .optional(),
+});
+class BedrockChatModel extends chat_model_js_1.ChatModel {
+    options;
+    constructor(options) {
+        if (options)
+            (0, type_utils_js_1.checkArguments)("BedrockChatModel", exports.bedrockChatModelOptionsSchema, options);
+        super();
+        this.options = options;
+    }
+    /**
+     * @hidden
+     */
+    _client;
+    get client() {
+        const credentials = this.options?.accessKeyId && this.options?.secretAccessKey
+            ? {
+                accessKeyId: this.options.accessKeyId,
+                secretAccessKey: this.options.secretAccessKey,
+            }
+            : undefined;
+        this._client ??= new client_bedrock_runtime_1.BedrockRuntimeClient({
+            region: this.options?.region,
+            credentials,
+        });
+        return this._client;
+    }
+    get modelOptions() {
+        return this.options?.modelOptions;
+    }
+    async process(input) {
+        const modelId = input.modelOptions?.model ?? this.modelOptions?.model ?? BEDROCK_DEFAULT_CHAT_MODEL;
+        const { messages, system } = getRunMessages(input);
+        const toolConfig = convertTools(input);
+        const body = {
+            modelId,
+            messages,
+            system,
+            toolConfig,
+            inferenceConfig: {
+                temperature: input.modelOptions?.temperature ?? this.modelOptions?.temperature,
+                topP: input.modelOptions?.topP ?? this.modelOptions?.topP,
+            },
+        };
+        const command = new client_bedrock_runtime_1.ConverseStreamCommand(body);
+        const response = await this.client.send(command);
+        const jsonMode = input.responseFormat?.type === "json_schema";
+        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) };
+        }
+        return result;
+    }
+    async extractResultFromStream(stream, modelId, streaming) {
+        if (!stream)
+            throw new Error("Unable to get AI model response.");
+        const result = new ReadableStream({
+            start: async (controller) => {
+                try {
+                    controller.enqueue({ delta: { json: { model: modelId } } });
+                    const toolCalls = [];
+                    let usage;
+                    for await (const chunk of stream) {
+                        if (chunk.contentBlockStart?.start?.toolUse) {
+                            const toolUse = chunk.contentBlockStart.start.toolUse;
+                            if (!toolUse.name)
+                                throw new Error("Tool use is invalid");
+                            if (chunk.contentBlockStart.contentBlockIndex === undefined)
+                                throw new Error("Tool use content block index is required");
+                            toolCalls[chunk.contentBlockStart.contentBlockIndex] = {
+                                type: "function",
+                                id: toolUse.toolUseId || (0, nanoid_1.nanoid)(),
+                                function: {
+                                    name: toolUse.name,
+                                    arguments: {},
+                                },
+                                args: "",
+                            };
+                        }
+                        if (chunk.contentBlockDelta) {
+                            const block = chunk.contentBlockDelta;
+                            const delta = block.delta;
+                            if (delta?.text) {
+                                controller.enqueue({ delta: { text: { text: delta.text } } });
+                            }
+                            if (delta?.toolUse) {
+                                if (block.contentBlockIndex === undefined)
+                                    throw new Error("Content block index is required");
+                                const call = toolCalls[block.contentBlockIndex];
+                                if (!call)
+                                    throw new Error("Tool call not found");
+                                call.args += delta.toolUse.input;
+                            }
+                        }
+                        if (chunk.metadata) {
+                            usage = chunk.metadata.usage;
+                        }
+                    }
+                    if (toolCalls.length) {
+                        controller.enqueue({
+                            delta: {
+                                json: {
+                                    toolCalls: toolCalls
+                                        .map(({ args, ...c }) => ({
+                                        ...c,
+                                        function: { ...c.function, arguments: (0, json_schema_js_1.parseJSON)(args) },
+                                    }))
+                                        .filter(type_utils_js_1.isNonNullable),
+                                },
+                            },
+                        });
+                    }
+                    controller.enqueue({ delta: { json: { usage } } });
+                    controller.close();
+                }
+                catch (error) {
+                    controller.error(error);
+                }
+            },
+        });
+        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, }) => {
+    const system = [];
+    const messages = [];
+    for (const msg of msgs) {
+        if (msg.role === "system") {
+            if (typeof msg.content !== "string")
+                throw new Error("System message must have content");
+            system.push({ text: msg.content });
+        }
+        else if (msg.role === "tool") {
+            if (!msg.toolCallId)
+                throw new Error("Tool message must have toolCallId");
+            if (typeof msg.content !== "string")
+                throw new Error("Tool message must have string content");
+            if (messages.at(-1)?.role === "user") {
+                messages.at(-1)?.content?.push({
+                    toolResult: { toolUseId: msg.toolCallId, content: [{ json: (0, json_schema_js_1.parseJSON)(msg.content) }] },
+                });
+            }
+            else {
+                messages.push({
+                    role: "user",
+                    content: [
+                        {
+                            toolResult: {
+                                toolUseId: msg.toolCallId,
+                                content: [{ json: (0, json_schema_js_1.parseJSON)(msg.content) }],
+                            },
+                        },
+                    ],
+                });
+            }
+        }
+        else if (msg.role === "user") {
+            if (!msg.content)
+                throw new Error("User message must have content");
+            messages.push({ role: "user", content: convertContent(msg.content) });
+        }
+        else if (msg.role === "agent") {
+            if (msg.toolCalls?.length) {
+                messages.push({
+                    role: "assistant",
+                    content: msg.toolCalls.map((i) => ({
+                        toolUse: {
+                            toolUseId: i.id,
+                            name: i.function.name,
+                            input: i.function.arguments,
+                        },
+                    })),
+                });
+            }
+            else if (msg.content) {
+                messages.push({ role: "assistant", content: convertContent(msg.content) });
+            }
+            else {
+                throw new Error("Agent message must have content or toolCalls");
+            }
+        }
+    }
+    if (messages.at(0)?.role !== "user") {
+        messages.unshift({ role: "user", content: [{ text: "." }] });
+    }
+    return { messages, system };
+};
+function convertContent(content) {
+    if (typeof content === "string")
+        return [{ text: content }];
+    if (Array.isArray(content)) {
+        const blocks = [];
+        for (const item of content) {
+            if (item.type === "text")
+                blocks.push({ text: item.text });
+        }
+        return blocks;
+    }
+    throw new Error("Invalid chat message content");
+}
+function convertTools({ tools, toolChoice }) {
+    if (!tools?.length || toolChoice === "none")
+        return undefined;
+    let choice;
+    if (typeof toolChoice === "object" && "type" in toolChoice && toolChoice.type === "function") {
+        choice = { tool: { name: toolChoice.function.name } };
+    }
+    else if (toolChoice === "required") {
+        choice = { any: {} };
+    }
+    else if (toolChoice === "auto") {
+        choice = { auto: {} };
+    }
+    return {
+        tools: tools.map((i) => {
+            const parameters = i.function.parameters;
+            if (Object.keys(parameters).length === 0) {
+                parameters.type = "object";
+            }
+            return {
+                toolSpec: {
+                    name: i.function.name,
+                    description: i.function.description,
+                    inputSchema: { json: parameters },
+                },
+            };
+        }),
+        toolChoice: choice,
+    };
+}

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

@@ -1,25 +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";
@@ -28,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";
 } | {
@@ -51,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: {
@@ -66,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;
 }