import type { AICitationChunk, AIProviderConfig, AIProviderMessage, AIProviderResponseFormat, AIProviderToolChoice, AIProviderToolDefinition, AIResponseMetadata, AIToolMap, AIUsage, ReasoningConfig } from "../../types/ai";
export type GenerateAIToolCall = {
    id: string;
    name: string;
    input: unknown;
};
export type GenerateAIOptions = {
    provider: AIProviderConfig;
    model: string;
    messages: AIProviderMessage[];
    systemPrompt?: string;
    /** Cache the system prompt (Anthropic prompt caching). See AIProviderStreamParams. */
    cacheSystemPrompt?: boolean;
    /** Per-call override of the provider `promptCaching` default. See AIProviderStreamParams. */
    promptCaching?: boolean;
    providerOptions?: Record<string, unknown>;
    maxTokens?: number;
    temperature?: number;
    topP?: number;
    stopSequences?: string[];
    tools?: AIProviderToolDefinition[];
    toolChoice?: AIProviderToolChoice;
    responseFormat?: AIProviderResponseFormat;
    /** Portable reasoning effort — translated per provider/model. */
    reasoning?: ReasoningConfig;
    signal?: AbortSignal;
};
export type GenerateAIResult = {
    citations: AICitationChunk[];
    metadata?: AIResponseMetadata;
    text: string;
    toolCalls: GenerateAIToolCall[];
    usage?: AIUsage;
};
/**
 * One-shot, non-streaming generation. Drains the provider stream and returns
 * the full assembled text, any tool calls the model made (with input already
 * JSON-parsed by the provider), and final token usage.
 */
export declare const generateAI: (options: GenerateAIOptions) => Promise<GenerateAIResult>;
export type GenerateAIWithToolsOptions = Omit<GenerateAIOptions, "tools" | "toolChoice"> & {
    /** Tools the model may call — each with a `handler` the loop runs on its behalf. */
    tools: AIToolMap;
    /** Max model⇄tool round-trips before forcing a final answer. Default 6. */
    maxTurns?: number;
    /** Observe each executed tool call (name, parsed input, string result). */
    onToolUse?: (name: string, input: unknown, result: string) => void;
};
export type GenerateAIWithToolsResult = {
    text: string;
    toolCalls: GenerateAIToolCall[];
    usage?: AIUsage;
    /** The full message thread incl. assistant tool_use + tool_result turns. */
    messages: AIProviderMessage[];
};
export declare const mergeUsage: (left: AIUsage | undefined, right: AIUsage | undefined) => AIUsage | undefined;
export declare const toProviderTools: (tools: AIToolMap) => AIProviderToolDefinition[];
/**
 * Agentic, non-streaming generation: the model may call the provided handler tools, this
 * runs them, feeds the results back, and loops until the model answers (or `maxTurns`).
 * Transport-agnostic — usable from HTTP/SSE/generator paths, unlike the WebSocket `streamAI`.
 * Returns the final text, every tool call made, summed usage, and the full message thread.
 */
export declare const generateAIWithTools: (options: GenerateAIWithToolsOptions) => Promise<GenerateAIWithToolsResult>;
export type GenerateObjectAIOptions<T> = {
    provider: AIProviderConfig;
    model: string;
    messages: AIProviderMessage[];
    schema: Record<string, unknown>;
    systemPrompt?: string;
    /** Cache the system prompt (Anthropic prompt caching). See AIProviderStreamParams. */
    cacheSystemPrompt?: boolean;
    /** Per-call override of the provider `promptCaching` default. See AIProviderStreamParams. */
    promptCaching?: boolean;
    toolName?: string;
    toolDescription?: string;
    maxTokens?: number;
    temperature?: number;
    /** Portable reasoning effort — translated per provider/model. */
    reasoning?: ReasoningConfig;
    validate?: (raw: unknown) => T;
    /**
     * When the model fails to produce usable structured output — it skips the tool
     * call, or `validate` throws — re-prompt it with the specific failure and ask
     * it to correct itself, up to this many EXTRA attempts. Default 1.
     *
     * Models routinely overrun a `maxLength`, pick an off-enum value, or drop a
     * field; those are recoverable deviations, not fatal errors. One repair pass
     * turns the common failure from "the whole feature throws" into "the model
     * fixes its own output". Set to 0 to restore strict single-attempt behaviour.
     */
    maxRepairAttempts?: number;
    signal?: AbortSignal;
};
export type GenerateObjectAIResult<T> = {
    object: T;
    usage?: AIUsage;
};
/**
 * One-shot structured output, provider-agnostic. Exposes the caller's JSON
 * schema as a single synthetic tool and forces the model to call it, then
 * returns the parsed tool input as the result object. Pass `validate` (e.g. a
 * Zod `schema.parse`) to narrow `unknown` to `T` and reject malformed output.
 *
 * Malformed output is not treated as fatal: when the model skips the tool call
 * or `validate` throws, the call is retried with the specific failure fed back
 * to the model (`maxRepairAttempts`, default 1) so it can correct itself before
 * the error finally surfaces.
 *
 * Works for any provider that supports forced tool choice — it does not rely
 * on a provider-specific structured-output API.
 */
export declare const generateObjectAI: <T = unknown>(options: GenerateObjectAIOptions<T>) => Promise<GenerateObjectAIResult<T>>;