/**
 * Google Gemini Provider Implementation
 *
 * This module provides integration with Google's Gemini models through the official
 * Generative AI SDK. Gemini offers cutting-edge AI capabilities including multimodal
 * understanding, advanced reasoning, and efficient text generation across various tasks.
 *
 * Key Features:
 * - Support for all Gemini model variants (Gemini 1.5 Pro, Flash, Pro Vision)
 * - Advanced streaming support with real-time token delivery
 * - Native multimodal capabilities (text, images, video)
 * - Sophisticated safety settings and content filtering
 * - Flexible generation configuration with fine-grained control
 *
 * Gemini-Specific Considerations:
 * - Uses "candidates" for response variants and "usageMetadata" for token counts
 * - Supports system instructions as separate parameter (not in conversation)
 * - Has sophisticated safety filtering with customizable thresholds
 * - Provides extensive generation configuration options
 * - Supports both single-turn and multi-turn conversations
 * - Offers advanced reasoning and coding capabilities
 *
 * @author Jan-Marlon Leibl
 * @version 1.0.0
 * @see https://ai.google.dev/docs
 */
import type { SafetySetting } from '@google/generative-ai';
import type { AIProviderConfig, CompletionParams, CompletionResponse, CompletionChunk, ProviderInfo } from '../types/index.js';
import { BaseAIProvider } from './base.js';
/**
 * Configuration interface for Gemini provider with Google-specific options.
 *
 * @example
 * ```typescript
 * const config: GeminiConfig = {
 *   apiKey: process.env.GOOGLE_API_KEY!,
 *   defaultModel: 'gemini-1.5-pro',
 *   safetySettings: [
 *     {
 *       category: HarmCategory.HARM_CATEGORY_HARASSMENT,
 *       threshold: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
 *     }
 *   ],
 *   generationConfig: {
 *     temperature: 0.7,
 *     topP: 0.8,
 *     topK: 40,
 *     maxOutputTokens: 2048
 *   }
 * };
 * ```
 */
export interface GeminiConfig extends AIProviderConfig {
    /**
     * Default Gemini model to use for requests.
     *
     * Recommended models:
     * - 'gemini-1.5-pro': Flagship model, best overall performance and multimodal
     * - 'gemini-1.5-flash': Faster and cheaper, good for simple tasks
     * - 'gemini-1.0-pro': Previous generation, cost-effective
     * - 'gemini-pro-vision': Specialized for vision tasks (legacy)
     *
     * @default 'gemini-1.5-flash'
     */
    defaultModel?: string;
    /**
     * Safety settings for content filtering and harm prevention.
     *
     * Gemini includes built-in safety filtering across multiple categories:
     * - Harassment and bullying
     * - Hate speech and discrimination
     * - Sexually explicit content
     * - Dangerous or harmful activities
     *
     * Each category can be configured with different blocking thresholds.
     *
     * @see https://ai.google.dev/docs/safety_setting
     */
    safetySettings?: SafetySetting[];
    /**
     * Generation configuration for controlling output characteristics.
     *
     * This allows fine-tuned control over the generation process including
     * creativity, diversity, length, and stopping conditions.
     *
     * @see https://ai.google.dev/docs/concepts#generation_configuration
     */
    generationConfig?: {
        /** Controls randomness in generation (0.0 to 1.0) */
        temperature?: number;
        /** Controls nucleus sampling for diversity (0.0 to 1.0) */
        topP?: number;
        /** Controls top-k sampling for diversity (positive integer) */
        topK?: number;
        /** Maximum number of tokens to generate */
        maxOutputTokens?: number;
        /** Sequences that will stop generation when encountered */
        stopSequences?: string[];
    };
}
/**
 * Google Gemini provider implementation.
 *
 * This class handles all interactions with Google's Gemini models through their
 * official Generative AI SDK. It provides optimized handling of Gemini's unique
 * features including multimodal inputs, safety filtering, and advanced generation control.
 *
 * Usage Pattern:
 * 1. Create instance with Google API key and configuration
 * 2. Call initialize() to set up client and validate credentials
 * 3. Use complete() or stream() for text generation
 * 4. Handle any AIProviderError exceptions appropriately
 *
 * @example
 * ```typescript
 * const gemini = new GeminiProvider({
 *   apiKey: process.env.GOOGLE_API_KEY!,
 *   defaultModel: 'gemini-1.5-pro',
 *   generationConfig: {
 *     temperature: 0.7,
 *     maxOutputTokens: 2048
 *   }
 * });
 *
 * await gemini.initialize();
 *
 * const response = await gemini.complete({
 *   messages: [
 *     { role: 'system', content: 'You are a helpful research assistant.' },
 *     { role: 'user', content: 'Explain quantum computing.' }
 *   ],
 *   maxTokens: 1000,
 *   temperature: 0.8
 * });
 * ```
 */
export declare class GeminiProvider extends BaseAIProvider {
    /** Google Generative AI client instance (initialized during doInitialize) */
    private client;
    /** Default model instance for requests */
    private model;
    /** Default model identifier for requests */
    private readonly defaultModel;
    /** Safety settings for content filtering */
    private readonly safetySettings?;
    /** Generation configuration defaults */
    private readonly generationConfig?;
    /**
     * Creates a new Gemini provider instance.
     *
     * @param config - Gemini-specific configuration options
     * @throws {AIProviderError} If configuration validation fails
     */
    constructor(config: GeminiConfig);
    /**
     * Initializes the Gemini provider by setting up the client and model.
     *
     * This method:
     * 1. Creates the Google Generative AI client with API key
     * 2. Sets up the default model with safety and generation settings
     * 3. Tests the connection with a minimal API call
     * 4. Validates API key permissions and model access
     *
     * @protected
     * @throws {Error} If client creation or connection validation fails
     */
    protected doInitialize(): Promise<void>;
    /**
     * Generates a text completion using Gemini's generation API.
     *
     * This method:
     * 1. Converts messages to Gemini's format with system instructions
     * 2. Chooses between single-turn and multi-turn conversation modes
     * 3. Makes API call with comprehensive error handling
     * 4. Formats response to standard interface
     *
     * @protected
     * @param params - Validated completion parameters
     * @returns Promise resolving to formatted completion response
     * @throws {Error} If API request fails
     */
    protected doComplete(params: CompletionParams): Promise<CompletionResponse>;
    /**
     * Generates a streaming text completion using Gemini's streaming API.
     *
     * This method:
     * 1. Sets up appropriate streaming mode based on conversation type
     * 2. Handles real-time stream chunks from Gemini
     * 3. Tracks token usage throughout the stream
     * 4. Yields formatted chunks with proper completion tracking
     *
     * @protected
     * @param params - Validated completion parameters
     * @returns AsyncIterable yielding completion chunks
     * @throws {Error} If streaming request fails
     */
    protected doStream(params: CompletionParams): AsyncIterable<CompletionChunk>;
    /**
     * Returns comprehensive information about the Gemini provider.
     *
     * @returns Provider information including models, capabilities, and limits
     */
    getInfo(): ProviderInfo;
    /**
     * Validates the connection by making a minimal test request.
     *
     * @private
     * @throws {AIProviderError} If connection validation fails
     */
    private validateConnection;
    /**
     * Validates model name format for Gemini models.
     *
     * @private
     * @param modelName - Model name to validate
     * @throws {AIProviderError} If model name format is invalid
     */
    private validateModelName;
    /**
     * Gets the appropriate model instance for a request.
     *
     * @private
     * @param params - Completion parameters
     * @returns GenerativeModel instance
     */
    private getModelForRequest;
    /**
     * Converts generic messages to Gemini's conversation format.
     *
     * Gemini handles system messages as separate system instructions
     * rather than part of the conversation flow.
     *
     * @private
     * @param messages - Input messages array
     * @returns Processed messages with system instruction separated
     */
    private convertMessages;
    /**
     * Builds generation configuration from completion parameters.
     *
     * @private
     * @param params - Completion parameters
     * @returns Gemini generation configuration
     */
    private buildGenerationConfig;
    /**
     * Processes streaming response chunks from Gemini API.
     *
     * @private
     * @param stream - Gemini streaming response
     * @returns AsyncIterable of formatted completion chunks
     */
    private processStreamChunks;
    /**
     * Formats Gemini's response to our standard interface.
     *
     * @private
     * @param response - Raw Gemini API response
     * @param model - Model used for generation
     * @returns Formatted completion response
     * @throws {AIProviderError} If response format is unexpected
     */
    private formatCompletionResponse;
    /**
     * Handles and transforms Gemini-specific errors.
     *
     * This method maps Gemini's error responses to our standardized
     * error format, providing helpful context and actionable suggestions.
     *
     * @private
     * @param error - Original error from Gemini API
     * @returns Normalized AIProviderError
     */
    private handleGeminiError;
}