simple-ai-provider
Version:
A simple and extensible AI provider package for easy integration of multiple AI services
276 lines (275 loc) • 9.79 kB
TypeScript
/**
* 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;
}