@aigne/core 1.12.0 → 1.14.0

package/lib/dts/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;
 }

package/lib/dts/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/dts/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/dts/models/gemini-chat-model.d.ts

@@ -1,8 +1,23 @@
 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;
     protected supportsEndWithSystemMessage: boolean;
     protected supportsToolsUseWithJsonSchema: boolean;
     protected supportsParallelToolCalls: boolean;
+    protected supportsToolStreaming: boolean;
 }

package/lib/dts/models/ollama-chat-model.d.ts

@@ -1,4 +1,20 @@
 import { OpenAIChatModel, type OpenAIChatModelOptions } from "./openai-chat-model.js";
+/**
+ * Implementation of the ChatModel interface for Ollama
+ *
+ * This model allows you to run open-source LLMs locally using Ollama,
+ * with an OpenAI-compatible API interface.
+ *
+ * Default model: 'llama3.2'
+ *
+ * @example
+ * Here's how to create and use an Ollama chat model:
+ * {@includeCode ../../test/models/ollama-chat-model.test.ts#example-ollama-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../../test/models/ollama-chat-model.test.ts#example-ollama-chat-model-streaming}
+ */
 export declare class OllamaChatModel extends OpenAIChatModel {
     constructor(options?: OpenAIChatModelOptions);
     protected apiKeyEnvName: string;

package/lib/dts/models/open-router-chat-model.d.ts

@@ -1,4 +1,20 @@
 import { OpenAIChatModel, type OpenAIChatModelOptions } from "./openai-chat-model.js";
+/**
+ * Implementation of the ChatModel interface for OpenRouter service
+ *
+ * OpenRouter provides access to a variety of large language models through a unified API.
+ * This implementation uses the OpenAI-compatible interface to connect to OpenRouter's service.
+ *
+ * Default model: 'openai/gpt-4o'
+ *
+ * @example
+ * Here's how to create and use an OpenRouter chat model:
+ * {@includeCode ../../test/models/open-router-chat-model.test.ts#example-openrouter-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../../test/models/open-router-chat-model.test.ts#example-openrouter-chat-model-streaming}
+ */
 export declare class OpenRouterChatModel extends OpenAIChatModel {
     constructor(options?: OpenAIChatModelOptions);
     protected apiKeyEnvName: string;

package/lib/dts/models/openai-chat-model.d.ts

@@ -1,8 +1,8 @@
 import OpenAI from "openai";
 import type { ChatCompletionMessageParam, ChatCompletionTool } from "openai/resources";
 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 ChatModelInputMessage, type ChatModelInputTool, type ChatModelOptions, type ChatModelOutput, type Role } from "./chat-model.js";
 export interface OpenAIChatModelCapabilities {
     supportsNativeStructuredOutputs: boolean;
@@ -10,14 +10,39 @@ export interface OpenAIChatModelCapabilities {
     supportsToolsUseWithJsonSchema: boolean;
     supportsParallelToolCalls: boolean;
     supportsToolsEmptyParameters: boolean;
+    supportsToolStreaming: boolean;
     supportsTemperature: boolean;
 }
+/**
+ * Configuration options for OpenAI Chat Model
+ */
 export interface OpenAIChatModelOptions {
+    /**
+     * API key for OpenAI API
+     *
+     * If not provided, will look for OPENAI_API_KEY in environment variables
+     */
     apiKey?: string;
+    /**
+     * Base URL for OpenAI API
+     *
+     * Useful for proxies or alternate endpoints
+     */
     baseURL?: string;
+    /**
+     * OpenAI model to use
+     *
+     * Defaults to 'gpt-4o-mini'
+     */
     model?: string;
+    /**
+     * Additional model options to control behavior
+     */
     modelOptions?: ChatModelOptions;
 }
+/**
+ * @hidden
+ */
 export declare const openAIChatModelOptionsSchema: z.ZodObject<{
     apiKey: z.ZodOptional<z.ZodString>;
     baseURL: z.ZodOptional<z.ZodString>;
@@ -69,9 +94,31 @@ export declare const openAIChatModelOptionsSchema: z.ZodObject<{
     apiKey?: string | undefined;
     baseURL?: string | undefined;
 }>;
+/**
+ * Implementation of the ChatModel interface for OpenAI's API
+ *
+ * This model provides access to OpenAI's capabilities including:
+ * - Text generation
+ * - Tool use with parallel tool calls
+ * - JSON structured output
+ * - Image understanding
+ *
+ * Default model: 'gpt-4o-mini'
+ *
+ * @example
+ * Here's how to create and use an OpenAI chat model:
+ * {@includeCode ../../test/models/openai-chat-model.test.ts#example-openai-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../../test/models/openai-chat-model.test.ts#example-openai-chat-model-streaming}
+ */
 export declare class OpenAIChatModel extends ChatModel {
     options?: OpenAIChatModelOptions | undefined;
     constructor(options?: OpenAIChatModelOptions | undefined);
+    /**
+     * @hidden
+     */
     protected _client?: OpenAI;
     protected apiKeyEnvName: string;
     protected apiKeyDefault: string | undefined;
@@ -80,20 +127,40 @@ export declare class OpenAIChatModel extends ChatModel {
     protected supportsToolsUseWithJsonSchema: boolean;
     protected supportsParallelToolCalls: boolean;
     protected supportsToolsEmptyParameters: boolean;
+    protected supportsToolStreaming: boolean;
     protected supportsTemperature: boolean;
     get client(): OpenAI;
     get modelOptions(): ChatModelOptions | undefined;
-    process(input: ChatModelInput, _context: Context, options?: AgentInvokeOptions): Promise<AgentResponse<ChatModelOutput>>;
+    /**
+     * Process the input and generate a response
+     * @param input The input to process
+     * @returns The generated response
+     */
+    process(input: ChatModelInput): PromiseOrValue<AgentProcessResult<ChatModelOutput>>;
+    private _process;
     private getParallelToolCalls;
     private getRunMessages;
     private getRunResponseFormat;
     private requestStructuredOutput;
+    private extractResultFromStream;
 }
+/**
+ * @hidden
+ */
 export declare const ROLE_MAP: {
     [key in Role]: ChatCompletionMessageParam["role"];
 };
+/**
+ * @hidden
+ */
 export declare function contentsFromInputMessages(messages: ChatModelInputMessage[]): Promise<ChatCompletionMessageParam[]>;
+/**
+ * @hidden
+ */
 export declare function toolsFromInputTools(tools?: ChatModelInputTool[], options?: {
     addTypeToEmptyParameters?: boolean;
 }): ChatCompletionTool[] | undefined;
+/**
+ * @hidden
+ */
 export declare function jsonSchemaToOpenAIJsonSchema(schema: Record<string, unknown>): Record<string, unknown>;

package/lib/dts/models/xai-chat-model.d.ts

@@ -1,4 +1,20 @@
 import { OpenAIChatModel, type OpenAIChatModelOptions } from "./openai-chat-model.js";
+/**
+ * Implementation of the ChatModel interface for X.AI's API (Grok)
+ *
+ * This model uses OpenAI-compatible API format to interact with X.AI models,
+ * providing access to models like Grok.
+ *
+ * Default model: 'grok-2-latest'
+ *
+ * @example
+ * Here's how to create and use an X.AI chat model:
+ * {@includeCode ../../test/models/xai-chat-model.test.ts#example-xai-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../../test/models/xai-chat-model.test.ts#example-xai-chat-model-streaming}
+ */
 export declare class XAIChatModel extends OpenAIChatModel {
     constructor(options?: OpenAIChatModelOptions);
     protected apiKeyEnvName: string;