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;
}>;