/**
 * Utilities Module
 *
 * Handles validation, normalization, schema conversion, and error handling utilities.
 * Extracted from BaseProvider to follow Single Responsibility Principle.
 *
 * Responsibilities:
 * - Options validation (text generation and stream options)
 * - Options normalization (string to object conversion)
 * - Provider information formatting
 * - Timeout parsing and calculation
 * - Schema utilities (Zod detection, permissive schema creation, OpenAI strict mode fixes)
 * - Tool result conversion
 * - Middleware options extraction
 * - Common error pattern handling
 *
 * @module core/modules/Utilities
 */
import type { AIProviderName, TextGenerationOptions, StreamOptions, MiddlewareFactoryOptions, ZodUnknownSchema } from "../../types/index.js";
/**
 * Utilities class - Provides validation, normalization, and utility methods
 */
export declare class Utilities {
    private readonly providerName;
    private readonly modelName;
    private readonly defaultTimeout;
    private readonly middlewareOptions?;
    constructor(providerName: AIProviderName, modelName: string, defaultTimeout?: number, middlewareOptions?: MiddlewareFactoryOptions | undefined);
    /**
     * Validate text generation options
     */
    validateOptions(options: TextGenerationOptions): void;
    /**
     * Validate stream options
     */
    validateStreamOptions(options: StreamOptions): void;
    /**
     * Normalize text generation options from string or object
     */
    normalizeTextOptions(optionsOrPrompt: TextGenerationOptions | string): TextGenerationOptions;
    /**
     * Normalize stream options from string or object
     */
    normalizeStreamOptions(optionsOrPrompt: StreamOptions | string): StreamOptions;
    /**
     * Get provider information
     */
    getProviderInfo(): {
        provider: string;
        model: string;
    };
    /**
     * Get timeout value in milliseconds from options
     * Supports number or string formats (e.g., '30s', '2m', '1h')
     */
    getTimeout(options: TextGenerationOptions | StreamOptions): number;
    /**
     * Get timeout scaled by estimated input token count.
     * For large contexts (>100K tokens), increase timeout proportionally.
     */
    getContextAwareTimeout(options: TextGenerationOptions | StreamOptions, estimatedTokens?: number): number;
    /**
     * Check if a schema is a Zod schema
     */
    isZodSchema(schema: unknown): boolean;
    /**
     * Convert tool execution result from MCP format to standard format
     * Handles tool failures gracefully to prevent stream termination
     */
    convertToolResult(result: unknown): Promise<unknown>;
    /**
     * Create a permissive Zod schema that accepts all parameters as-is
     */
    createPermissiveZodSchema(): ZodUnknownSchema;
    /**
     * Recursively fix JSON Schema for OpenAI strict mode compatibility
     * OpenAI requires additionalProperties: false at ALL levels and preserves required array
     */
    fixSchemaForOpenAIStrictMode(schema: Record<string, unknown>): Record<string, unknown>;
    /**
     * Extract middleware options from generation/stream options
     * This is the single source of truth for deciding if middleware should be applied
     */
    extractMiddlewareOptions(options: TextGenerationOptions | StreamOptions): MiddlewareFactoryOptions | null;
    /**
     * Handle common error patterns across providers
     * Returns transformed error or null if not a common pattern
     */
    handleCommonErrors(error: unknown): Error | null;
}