@aigne/core 1.13.0 → 1.14.0

package/lib/esm/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/esm/models/chat-model.js

@@ -1,5 +1,28 @@
 import { z } from "zod";
 import { Agent } from "../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}
+ */
 export class ChatModel extends Agent {
     constructor() {
         super({
@@ -7,7 +30,20 @@ export class ChatModel extends 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,
@@ -20,6 +56,15 @@ export class ChatModel extends 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;
@@ -29,6 +74,15 @@ export class ChatModel extends 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/esm/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;
 }

package/lib/esm/models/claude-chat-model.js

@@ -3,9 +3,12 @@ import { z } from "zod";
 import { parseJSON } from "../utils/json-schema.js";
 import { mergeUsage } from "../utils/model-utils.js";
 import { agentResponseStreamToObject } from "../utils/stream-utils.js";
-import { checkArguments, isEmpty, isNonNullable } from "../utils/type-utils.js";
+import { checkArguments, isEmpty, isNonNullable, } from "../utils/type-utils.js";
 import { ChatModel, } from "./chat-model.js";
 const CHAT_MODEL_CLAUDE_DEFAULT_MODEL = "claude-3-7-sonnet-latest";
+/**
+ * @hidden
+ */
 export const claudeChatModelOptionsSchema = z.object({
     apiKey: z.string().optional(),
     model: z.string().optional(),
@@ -20,6 +23,24 @@ export const claudeChatModelOptionsSchema = z.object({
     })
         .optional(),
 });
+/**
+ * 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 class ClaudeChatModel extends ChatModel {
     options;
     constructor(options) {
@@ -28,6 +49,9 @@ export class ClaudeChatModel extends ChatModel {
         super();
         this.options = options;
     }
+    /**
+     * @hidden
+     */
     _client;
     get client() {
         const apiKey = this.options?.apiKey || process.env.ANTHROPIC_API_KEY || process.env.CLAUDE_API_KEY;
@@ -39,7 +63,15 @@ export class ClaudeChatModel extends ChatModel {
     get modelOptions() {
         return this.options?.modelOptions;
     }
-    async process(input, _context, options) {
+    /**
+     * Process the input using Claude's chat model
+     * @param input - The input to process
+     * @returns The processed output from the model
+     */
+    process(input) {
+        return this._process(input);
+    }
+    async _process(input) {
         const model = this.options?.model || CHAT_MODEL_CLAUDE_DEFAULT_MODEL;
         const disableParallelToolUse = input.modelOptions?.parallelToolCalls === false ||
             this.modelOptions?.parallelToolCalls === false;
@@ -56,7 +88,7 @@ export class ClaudeChatModel extends ChatModel {
             ...body,
             stream: true,
         });
-        if (options?.streaming && input.responseFormat?.type !== "json_schema") {
+        if (input.responseFormat?.type !== "json_schema") {
             return this.extractResultFromClaudeStream(stream, true);
         }
         const result = await this.extractResultFromClaudeStream(stream);

package/lib/esm/models/deepseek-chat-model.d.ts

@@ -1,4 +1,20 @@
 import { OpenAIChatModel, type OpenAIChatModelOptions } from "./openai-chat-model.js";
+/**
+ * Implementation of the ChatModel interface for DeepSeek's API
+ *
+ * This model uses OpenAI-compatible API format to interact with DeepSeek's models,
+ * but with specific configuration and capabilities for DeepSeek.
+ *
+ * Default model: 'deepseek-chat'
+ *
+ * @example
+ * Here's how to create and use a DeepSeek chat model:
+ * {@includeCode ../../test/models/deepseek-chat-model.test.ts#example-deepseek-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../../test/models/deepseek-chat-model.test.ts#example-deepseek-chat-model-streaming}
+ */
 export declare class DeepSeekChatModel extends OpenAIChatModel {
     constructor(options?: OpenAIChatModelOptions);
     protected apiKeyEnvName: string;

package/lib/esm/models/deepseek-chat-model.js

@@ -1,6 +1,22 @@
 import { OpenAIChatModel } from "./openai-chat-model.js";
 const DEEPSEEK_DEFAULT_CHAT_MODEL = "deepseek-chat";
 const DEEPSEEK_BASE_URL = "https://api.deepseek.com";
+/**
+ * Implementation of the ChatModel interface for DeepSeek's API
+ *
+ * This model uses OpenAI-compatible API format to interact with DeepSeek's models,
+ * but with specific configuration and capabilities for DeepSeek.
+ *
+ * Default model: 'deepseek-chat'
+ *
+ * @example
+ * Here's how to create and use a DeepSeek chat model:
+ * {@includeCode ../../test/models/deepseek-chat-model.test.ts#example-deepseek-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../../test/models/deepseek-chat-model.test.ts#example-deepseek-chat-model-streaming}
+ */
 export class DeepSeekChatModel extends OpenAIChatModel {
     constructor(options) {
         super({

package/lib/esm/models/gemini-chat-model.d.ts

@@ -1,4 +1,18 @@
 import { OpenAIChatModel, type OpenAIChatModelOptions } from "./openai-chat-model.js";
+/**
+ * Implementation of the ChatModel interface for Google's Gemini API
+ *
+ * This model uses OpenAI-compatible API format to interact with Google's Gemini models,
+ * providing access to models like Gemini 1.5 and Gemini 2.0.
+ *
+ * @example
+ * Here's how to create and use a Gemini chat model:
+ * {@includeCode ../../test/models/gemini-chat-model.test.ts#example-gemini-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../../test/models/gemini-chat-model.test.ts#example-gemini-chat-model-streaming}
+ */
 export declare class GeminiChatModel extends OpenAIChatModel {
     constructor(options?: OpenAIChatModelOptions);
     protected apiKeyEnvName: string;

package/lib/esm/models/gemini-chat-model.js

@@ -1,6 +1,20 @@
 import { OpenAIChatModel } from "./openai-chat-model.js";
 const GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai";
 const GEMINI_DEFAULT_CHAT_MODEL = "gemini-2.0-flash";
+/**
+ * Implementation of the ChatModel interface for Google's Gemini API
+ *
+ * This model uses OpenAI-compatible API format to interact with Google's Gemini models,
+ * providing access to models like Gemini 1.5 and Gemini 2.0.
+ *
+ * @example
+ * Here's how to create and use a Gemini chat model:
+ * {@includeCode ../../test/models/gemini-chat-model.test.ts#example-gemini-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../../test/models/gemini-chat-model.test.ts#example-gemini-chat-model-streaming}
+ */
 export class GeminiChatModel extends OpenAIChatModel {
     constructor(options) {
         super({