@aigne/core 1.72.0 → 1.74.0-beta

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

@@ -1,672 +0,0 @@
-import { type ZodType, z } from "zod";
-import { type PromiseOrValue } from "../utils/type-utils.js";
-import { type AgentInvokeOptions, type AgentOptions, type AgentProcessResult, type AgentResponse, type AgentResponseStream, type GetterSchema, type Message } from "./agent.js";
-import { type FileType, type FileUnionContent, Model } from "./model.js";
-export declare class StructuredOutputError extends Error {
-}
-export interface ChatModelOptions extends Omit<AgentOptions<ChatModelInput, ChatModelOutput>, "model" | "inputSchema" | "outputSchema"> {
-    model?: string;
-    modelOptions?: ChatModelInputOptionsWithGetter;
-}
-/**
- * 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/agents/chat-model.test.ts#example-chat-model}
- *
- * @example
- * Here's an example showing streaming response with readable stream:
- * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-streaming}
- *
- * @example
- * Here's an example showing streaming response with async generator:
- * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-streaming-async-generator}
- *
- * @example
- * Here's an example with tool calls:
- * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-tools}
- */
-export declare abstract class ChatModel extends Model<ChatModelInput, ChatModelOutput> {
-    options?: ChatModelOptions | undefined;
-    tag: string;
-    constructor(options?: ChatModelOptions | undefined);
-    get credential(): PromiseOrValue<{
-        url?: string;
-        apiKey?: string;
-        model?: string;
-    }>;
-    /**
-     * 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;
-    };
-    getModelOptions(input: Message, options: AgentInvokeOptions): Promise<ChatModelInputOptions>;
-    private validateToolNames;
-    countTokens(input: ChatModelInput): Promise<number>;
-    /**
-     * Normalizes tool names to ensure compatibility with language models
-     *
-     * This method converts tool names to a format that complies with model requirements
-     * by replacing hyphens and whitespace characters with underscores. The normalized
-     * names are used for tool calls while preserving the original names for reference.
-     *
-     * @param name - The original tool name to normalize
-     * @returns A promise that resolves to the normalized tool name
-     */
-    protected normalizeToolName(name: string): Promise<string>;
-    /**
-     * 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 options Options for invoking the agent
-     * @throws Error if token usage exceeds maximum limit
-     */
-    protected preprocess(input: ChatModelInput, options: AgentInvokeOptions): Promise<void>;
-    /**
-     * Performs postprocessing operations after handling output
-     *
-     * Primarily updates token usage statistics in the context
-     *
-     * @param input Input message
-     * @param output Output message
-     * @param options Options for invoking the agent
-     */
-    protected postprocess(input: ChatModelInput, output: ChatModelOutput, options: AgentInvokeOptions): Promise<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 options - The options for invoking the agent, including context and limits
-     * @returns A promise or direct value containing the model's response
-     */
-    abstract process(input: ChatModelInput, options: AgentInvokeOptions): PromiseOrValue<AgentProcessResult<ChatModelOutput>>;
-    protected processAgentOutput(input: ChatModelInput, output: Exclude<AgentResponse<ChatModelOutput>, AgentResponseStream<ChatModelOutput>>, options: AgentInvokeOptions): Promise<ChatModelOutput>;
-    protected validateJsonSchema<T>(schema: object, data: T, options?: {
-        safe?: false;
-    }): T;
-    protected validateJsonSchema<T>(schema: object, data: T, options: {
-        safe: true;
-    }): z.SafeParseReturnType<T, T>;
-    protected validateJsonSchema<T>(schema: object, data: T, options?: {
-        safe?: boolean;
-    }): T | z.SafeParseReturnType<T, T>;
-}
-/**
- * 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/agents/chat-model.test.ts#example-chat-model}
- *
- * @example
- * Here's an example with tool calling:
- * {@includeCode ../../test/agents/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;
-    outputFileType?: FileType;
-    /**
-     * List of tools available for the model to use
-     */
-    tools?: ChatModelInputTool[];
-    /**
-     * Specifies the tool selection strategy
-     */
-    toolChoice?: ChatModelInputToolChoice;
-    /**
-     * Model-specific configuration options
-     */
-    modelOptions?: ChatModelInputOptions;
-}
-/**
- * Message role types
- *
- * - system: System instructions
- * - user: User messages
- * - agent: Agent/assistant messages
- * - tool: Tool call responses
- */
-export type Role = "system" | "user" | "agent" | "tool";
-export declare const roleSchema: z.ZodUnion<[z.ZodLiteral<"system">, z.ZodLiteral<"user">, z.ZodLiteral<"agent">, z.ZodLiteral<"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";
-        function: {
-            name: string;
-            arguments: Message;
-        };
-        metadata?: Record<string, any>;
-    }[];
-    /**
-     * For tool response messages, specifies the corresponding tool call ID
-     */
-    toolCallId?: string;
-    /**
-     * Name of the message sender (for multi-agent scenarios)
-     */
-    name?: string;
-    /**
-     * Cache control marker for the entire message (only supported by Claude)
-     *
-     * This is syntactic sugar that applies cacheControl to the last content block
-     * of the message. See {@link CacheControl} for details.
-     */
-    cacheControl?: CacheControl;
-}
-/**
- * Type of input message content
- *
- * Can be a simple string, or a mixed array of text and image content
- */
-export type ChatModelInputMessageContent = string | UnionContent[];
-/**
- * Text content type
- *
- * Used for text parts of message content
- */
-export type TextContent = {
-    type: "text";
-    text: string;
-    isThinking?: boolean;
-    isAgentSkill?: boolean;
-    /**
-     * Cache control marker (only supported by Claude)
-     *
-     * When set, this content block will be marked as a cache breakpoint.
-     * See {@link CacheControl} for details.
-     */
-    cacheControl?: CacheControl;
-};
-export declare const textContentSchema: z.ZodObject<{
-    type: z.ZodLiteral<"text">;
-    text: z.ZodString;
-    cacheControl: ZodType<{
-        type: "ephemeral";
-        ttl?: "5m" | "1h" | undefined;
-    } | undefined, z.ZodTypeDef, {
-        type: "ephemeral";
-        ttl?: "5m" | "1h" | undefined;
-    } | undefined>;
-}, "strip", z.ZodTypeAny, {
-    type: "text";
-    text: string;
-    cacheControl?: {
-        type: "ephemeral";
-        ttl?: "5m" | "1h" | undefined;
-    } | undefined;
-}, {
-    type: "text";
-    text: string;
-    cacheControl?: {
-        type: "ephemeral";
-        ttl?: "5m" | "1h" | undefined;
-    } | undefined;
-}>;
-export type UnionContent = TextContent | FileUnionContent;
-export declare const unionContentSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
-    type: z.ZodLiteral<"text">;
-    text: z.ZodString;
-    cacheControl: ZodType<{
-        type: "ephemeral";
-        ttl?: "5m" | "1h" | undefined;
-    } | undefined, z.ZodTypeDef, {
-        type: "ephemeral";
-        ttl?: "5m" | "1h" | undefined;
-    } | undefined>;
-}, "strip", z.ZodTypeAny, {
-    type: "text";
-    text: string;
-    cacheControl?: {
-        type: "ephemeral";
-        ttl?: "5m" | "1h" | undefined;
-    } | undefined;
-}, {
-    type: "text";
-    text: string;
-    cacheControl?: {
-        type: "ephemeral";
-        ttl?: "5m" | "1h" | undefined;
-    } | undefined;
-}>, z.ZodObject<{
-    filename: ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
-    mimeType: ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
-} & {
-    type: z.ZodLiteral<"local">;
-    path: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    path: string;
-    type: "local";
-    filename?: string | undefined;
-    mimeType?: string | undefined;
-}, {
-    path: string;
-    type: "local";
-    filename?: string | undefined;
-    mimeType?: string | undefined;
-}>, z.ZodObject<{
-    filename: ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
-    mimeType: ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
-} & {
-    type: z.ZodLiteral<"url">;
-    url: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    type: "url";
-    url: string;
-    filename?: string | undefined;
-    mimeType?: string | undefined;
-}, {
-    type: "url";
-    url: string;
-    filename?: string | undefined;
-    mimeType?: string | undefined;
-}>, z.ZodObject<{
-    filename: ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
-    mimeType: ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
-} & {
-    type: z.ZodLiteral<"file">;
-    data: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    type: "file";
-    data: string;
-    filename?: string | undefined;
-    mimeType?: string | undefined;
-}, {
-    type: "file";
-    data: string;
-    filename?: string | undefined;
-    mimeType?: string | undefined;
-}>]>;
-/**
- * Model response format settings
- *
- * Can be specified as plain text format or according to a JSON Schema
- */
-export type ChatModelInputResponseFormat = {
-    type: "text";
-} | {
-    type: "json_schema";
-    jsonSchema: {
-        name: string;
-        description?: string;
-        schema: Record<string, unknown>;
-        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/agents/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;
-    };
-    /**
-     * Provider-specific metadata for the tool
-     * For example, Gemini's thought_signature
-     */
-    metadata?: Record<string, any>;
-    /**
-     * Cache control marker (only supported by Claude)
-     *
-     * When set, this tool definition will be marked as a cache breakpoint.
-     * Typically applied to the last tool in the tools array.
-     * See {@link CacheControl} for details.
-     */
-    cacheControl?: CacheControl;
-}
-/**
- * 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/agents/chat-model.test.ts#example-chat-model-tools}
- */
-export type ChatModelInputToolChoice = "auto" | "none" | "required" | {
-    type: "function";
-    function: {
-        name: string;
-        description?: string;
-    };
-};
-export type Modality = "text" | "image" | "audio";
-/**
- * Cache control marker for prompt caching
- *
- * Used to mark content blocks, messages, or tools for caching.
- * Currently only supported by Anthropic (Claude) models.
- */
-export interface CacheControl {
-    /**
-     * Cache type (currently only "ephemeral" is supported)
-     */
-    type: "ephemeral";
-    /**
-     * Cache TTL (Time To Live)
-     * - "5m": 5 minutes (default)
-     * - "1h": 1 hour
-     */
-    ttl?: "5m" | "1h";
-}
-/**
- * Cache configuration options
- *
- * Controls how prompt caching is used for supported providers.
- * Prompt caching can significantly reduce costs and latency by reusing
- * previously processed prompts (system messages, tool definitions, etc.).
- */
-export interface CacheConfig {
-    /**
-     * Whether to enable prompt caching
-     *
-     * - OpenAI: Ignored (always enabled automatically)
-     * - Gemini: Controls explicit caching
-     * - Claude: Controls whether to add cache_control markers
-     *
-     * @default true
-     */
-    enabled?: boolean;
-    /**
-     * Cache TTL (Time To Live)
-     *
-     * - OpenAI: Ignored (automatic)
-     * - Gemini: Supports custom seconds
-     * - Claude: Only supports "5m" or "1h"
-     *
-     * @default "5m"
-     */
-    ttl?: "5m" | "1h" | number;
-    /**
-     * Caching strategy
-     *
-     * - "auto": Automatically add cache breakpoints at optimal locations
-     * - "manual": Require explicit cacheControl markers on messages/tools
-     *
-     * @default "auto"
-     */
-    strategy?: "auto" | "manual";
-    /**
-     * Auto cache breakpoint locations (only effective when strategy="auto")
-     *
-     * @default { tools: true, system: true, lastMessage: false }
-     */
-    autoBreakpoints?: {
-        /** Cache tool definitions */
-        tools?: boolean;
-        /** Cache system messages */
-        system?: boolean;
-        /** Cache last message in conversation history */
-        lastMessage?: boolean;
-    };
-}
-/**
- * Default cache configuration
- *
- * Enables automatic caching for system messages and tool definitions,
- * which typically provides the best cost/performance tradeoff.
- */
-export declare const DEFAULT_CACHE_CONFIG: CacheConfig;
-/**
- * Model-specific configuration options
- *
- * Contains various parameters for controlling model behavior, such as model name, temperature, etc.
- */
-export interface ChatModelInputOptions extends Record<string, unknown> {
-    /**
-     * 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;
-    modalities?: Modality[];
-    preferInputFileType?: "file" | "url";
-    reasoningEffort?: number | "minimal" | "low" | "medium" | "high";
-    /**
-     * Cache configuration for prompt caching
-     *
-     * Enables caching of system messages, tool definitions, and conversation history
-     * to reduce costs and latency. See {@link CacheConfig} for details.
-     *
-     * @default DEFAULT_CACHE_CONFIG (enabled with auto strategy)
-     */
-    cacheConfig?: CacheConfig;
-}
-export type ChatModelInputOptionsWithGetter = GetterSchema<ChatModelInputOptions>;
-/**
- * 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/agents/chat-model.test.ts#example-chat-model}
- *
- * @example
- * Here's an example with tool calls:
- * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-tools}
- */
-export interface ChatModelOutput extends Message {
-    /**
-     * Text format response content
-     */
-    text?: string;
-    /**
-     * Model's internal thoughts (if supported)
-     */
-    thoughts?: 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;
-    files?: FileUnionContent[];
-}
-/**
- * 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/agents/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;
-    };
-    /**
-     * Provider-specific metadata for the tool call
-     * For example, Gemini's thought_signature
-     */
-    metadata?: Record<string, any>;
-}
-/**
- * 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;
-    /**
-     * AIGNE Hub credit usage
-     */
-    aigneHubCredits?: number;
-    /**
-     * Number of tokens written to cache (first time caching)
-     * Only applicable for providers that support explicit cache creation (e.g., Anthropic)
-     */
-    cacheCreationInputTokens?: number;
-    /**
-     * Number of tokens read from cache (cache hit)
-     * Supported by OpenAI, Anthropic, and Gemini
-     */
-    cacheReadInputTokens?: number;
-    /**
-     * Credit prefix
-     */
-    creditPrefix?: "$" | "€" | "¥";
-}
-export declare const chatModelOutputUsageSchema: z.ZodObject<{
-    inputTokens: z.ZodNumber;
-    outputTokens: z.ZodNumber;
-    aigneHubCredits: ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
-    cacheCreationInputTokens: ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
-    cacheReadInputTokens: ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
-    creditPrefix: ZodType<"$" | "€" | "¥" | undefined, z.ZodTypeDef, "$" | "€" | "¥" | undefined>;
-}, "strip", z.ZodTypeAny, {
-    inputTokens: number;
-    outputTokens: number;
-    aigneHubCredits?: number | undefined;
-    cacheCreationInputTokens?: number | undefined;
-    cacheReadInputTokens?: number | undefined;
-    creditPrefix?: "$" | "€" | "¥" | undefined;
-}, {
-    inputTokens: number;
-    outputTokens: number;
-    aigneHubCredits?: number | undefined;
-    cacheCreationInputTokens?: number | undefined;
-    cacheReadInputTokens?: number | undefined;
-    creditPrefix?: "$" | "€" | "¥" | undefined;
-}>;