feat(core): Add comprehensive retry mechanism and batch fallback for Gemini embeddings

packages/core/README.md

@@ -238,6 +238,45 @@ const context = new Context({
 })
 ```
 
+### Using Gemini Embeddings with Retry Configuration
+
+```typescript
+import { Context, MilvusVectorDatabase, GeminiEmbedding } from '@pleaseai/context-please-core'
+
+// Initialize with Gemini embedding provider
+const embedding = new GeminiEmbedding({
+  apiKey: process.env.GEMINI_API_KEY || 'your-gemini-api-key',
+  model: 'gemini-embedding-001',
+  outputDimensionality: 768, // Optional: Matryoshka Representation Learning support (256, 768, 1536, 3072)
+  maxRetries: 3, // Optional: Maximum retry attempts (default: 3)
+  baseDelay: 1000 // Optional: Base delay in ms for exponential backoff (default: 1000ms)
+})
+
+const vectorDatabase = new MilvusVectorDatabase({
+  address: process.env.MILVUS_ADDRESS || 'localhost:19530',
+  token: process.env.MILVUS_TOKEN || ''
+})
+
+const context = new Context({
+  embedding,
+  vectorDatabase
+})
+
+// The retry mechanism automatically handles:
+// - Rate limit errors (429)
+// - Server errors (500, 502, 503, 504)
+// - Network errors (ECONNREFUSED, ETIMEDOUT, ENOTFOUND, EAI_AGAIN)
+// - Transient API failures with exponential backoff (1s → 2s → 4s → 8s, capped at 10s)
+
+// Update retry configuration at runtime
+embedding.setMaxRetries(5)
+embedding.setBaseDelay(2000)
+
+// Check current retry configuration
+const retryConfig = embedding.getRetryConfig()
+console.log(`Max retries: ${retryConfig.maxRetries}, Base delay: ${retryConfig.baseDelay}ms`)
+```
+
 ### Custom File Filtering
 
 ```typescript

packages/core/package.json

@@ -33,6 +33,7 @@
     "@qdrant/js-client-grpc": "^1.15.1",
     "@qdrant/js-client-rest": "^1.15.1",
     "@zilliz/milvus2-sdk-node": "^2.5.10",
+    "es-toolkit": "^1.41.0",
     "faiss-node": "^0.5.1",
     "fs-extra": "^11.0.0",
     "glob": "^10.0.0",

packages/core/src/embedding/base-embedding.ts

@@ -16,6 +16,11 @@ export abstract class Embedding {
    * @returns Processed text
    */
   protected preprocessText(text: string): string {
+    // Handle null/undefined by converting to empty string
+    if (text == null) {
+      return ' '
+    }
+
     // Replace empty string with single space
     if (text === '') {
       return ' '

packages/core/src/embedding/gemini-embedding.ts

@@ -1,5 +1,6 @@
 import type { ContentEmbedding } from '@google/genai'
 import type { EmbeddingVector } from './base-embedding'
+import { retry } from 'es-toolkit'
 import { GoogleGenAI } from '@google/genai'
 import { Embedding } from './base-embedding'
 
@@ -8,17 +9,23 @@ export interface GeminiEmbeddingConfig {
   apiKey: string
   baseURL?: string // Optional custom API endpoint URL
   outputDimensionality?: number // Optional dimension override
+  maxRetries?: number // Maximum number of retry attempts (default: 3)
+  baseDelay?: number // Base delay in milliseconds for exponential backoff (default: 1000ms)
 }
 
 export class GeminiEmbedding extends Embedding {
   private client: GoogleGenAI
   private config: GeminiEmbeddingConfig
   private dimension: number = 3072 // Default dimension for gemini-embedding-001
   protected maxTokens: number = 2048 // Maximum tokens for Gemini embedding models
+  private maxRetries: number
+  private baseDelay: number
 
   constructor(config: GeminiEmbeddingConfig) {
     super()
     this.config = config
+    this.maxRetries = config.maxRetries ?? 3
+    this.baseDelay = config.baseDelay ?? 1000
     this.client = new GoogleGenAI({
       apiKey: config.apiKey,
       ...(config.baseURL && {
@@ -52,6 +59,88 @@ export class GeminiEmbedding extends Embedding {
     }
   }
 
+  /**
+   * Determine if an error is retryable
+   * @param error Error object to check
+   * @returns True if error is retryable
+   */
+  private isRetryableError(error: unknown): boolean {
+    if (typeof error !== 'object' || error === null) {
+      return false
+    }
+
+    // Network errors
+    const networkErrorCodes = ['ECONNREFUSED', 'ETIMEDOUT', 'ENOTFOUND', 'EAI_AGAIN']
+    if ('code' in error && typeof error.code === 'string' && networkErrorCodes.includes(error.code)) {
+      return true
+    }
+
+    // HTTP status codes
+    const retryableStatusCodes = [429, 500, 502, 503, 504]
+    if ('status' in error && typeof error.status === 'number' && retryableStatusCodes.includes(error.status)) {
+      return true
+    }
+
+    // Error message patterns
+    const errorMessage = ('message' in error && typeof error.message === 'string')
+      ? error.message.toLowerCase()
+      : ''
+    const retryablePatterns = [
+      'rate limit',
+      'quota exceeded',
+      'service unavailable',
+      'timeout',
+      'connection',
+    ]
+
+    return retryablePatterns.some(pattern => errorMessage.includes(pattern))
+  }
+
+  /**
+   * Execute operation with retry logic using es-toolkit retry
+   * Only retries on retryable errors (network errors, rate limits, server errors)
+   * @param operation Operation to execute
+   * @param context Context string for error messages
+   * @returns Operation result
+   */
+  private async executeWithRetry<T>(
+    operation: () => Promise<T>,
+    context: string,
+  ): Promise<T> {
+    try {
+      return await retry(
+        async () => {
+          try {
+            return await operation()
+          }
+          catch (error) {
+            // If error is not retryable, throw a special error to stop retries
+            if (!this.isRetryableError(error)) {
+              // Wrap in a non-retryable marker
+              const nonRetryableError = new Error(`${context}: ${error instanceof Error ? error.message : 'Unknown error'}`)
+              ;(nonRetryableError as any).__nonRetryable = true
+              throw nonRetryableError
+            }
+            // Re-throw retryable errors to trigger retry
+            throw error
+          }
+        },
+        {
+          retries: this.maxRetries,
+          delay: (attempts) => Math.min(this.baseDelay * Math.pow(2, attempts), 10000),
+        },
+      )
+    }
+    catch (error) {
+      // If it's a non-retryable error, throw as-is
+      if (typeof error === 'object' && error !== null && (error as any).__nonRetryable) {
+        throw error
+      }
+      // If it was retryable but still failed after all retries
+      throw new Error(`${context}: ${error instanceof Error ? error.message : 'Unknown error'}`)
+    }
+  }
+
   async detectDimension(): Promise<number> {
     // Gemini doesn't need dynamic detection, return configured dimension
     return this.dimension
@@ -61,7 +150,7 @@ export class GeminiEmbedding extends Embedding {
     const processedText = this.preprocessText(text)
     const model = this.config.model || 'gemini-embedding-001'
 
-    try {
+    return this.executeWithRetry(async () => {
       const response = await this.client.models.embedContent({
         model,
         contents: processedText,
@@ -78,41 +167,59 @@ export class GeminiEmbedding extends Embedding {
         vector: response.embeddings[0].values,
         dimension: response.embeddings[0].values.length,
       }
-    }
-    catch (error) {
-      throw new Error(`Gemini embedding failed: ${error instanceof Error ? error.message : 'Unknown error'}`)
-    }
+    }, 'Gemini embedding failed')
   }
 
   async embedBatch(texts: string[]): Promise<EmbeddingVector[]> {
     const processedTexts = this.preprocessTexts(texts)
     const model = this.config.model || 'gemini-embedding-001'
 
+    // Try batch processing with retry logic
     try {
-      const response = await this.client.models.embedContent({
-        model,
-        contents: processedTexts,
-        config: {
-          outputDimensionality: this.config.outputDimensionality || this.dimension,
-        },
-      })
+      return await this.executeWithRetry(async () => {
+        const response = await this.client.models.embedContent({
+          model,
+          contents: processedTexts,
+          config: {
+            outputDimensionality: this.config.outputDimensionality || this.dimension,
+          },
+        })
 
-      if (!response.embeddings) {
-        throw new Error('Gemini API returned invalid response')
-      }
+        if (!response.embeddings) {
+          throw new Error('Gemini API returned invalid response')
+        }
+
+        return response.embeddings.map((embedding: ContentEmbedding) => {
+          if (!embedding.values) {
+            throw new Error('Gemini API returned invalid embedding data')
+          }
+          return {
+            vector: embedding.values,
+            dimension: embedding.values.length,
+          }
+        })
+      }, 'Gemini batch embedding failed')
+    }
+    catch (batchError) {
+      // Fallback: Process individually if batch fails after all retries
+      // This handles cases where batch processing is temporarily unavailable
+      // or when individual requests are more reliable
+      const results: EmbeddingVector[] = []
 
-      return response.embeddings.map((embedding: ContentEmbedding) => {
-        if (!embedding.values) {
-          throw new Error('Gemini API returned invalid embedding data')
+      for (const text of processedTexts) {
+        try {
+          const result = await this.embed(text)
+          results.push(result)
         }
-        return {
-          vector: embedding.values,
-          dimension: embedding.values.length,
+        catch (individualError) {
+          // If individual request also fails, re-throw the error with cause
+          const error = new Error('Gemini batch embedding failed (both batch and individual attempts failed)')
+          ;(error as any).cause = individualError
+          throw error
         }
-      })
-    }
-    catch (error) {
-      throw new Error(`Gemini batch embedding failed: ${error instanceof Error ? error.message : 'Unknown error'}`)
+      }
+
+      return results
     }
   }
 
@@ -178,4 +285,37 @@ export class GeminiEmbedding extends Embedding {
     const supportedDimensions = this.getSupportedDimensions()
     return supportedDimensions.includes(dimension)
   }
+
+  /**
+   * Get current retry configuration
+   * @returns Object containing maxRetries and baseDelay
+   */
+  getRetryConfig(): { maxRetries: number, baseDelay: number } {
+    return {
+      maxRetries: this.maxRetries,
+      baseDelay: this.baseDelay,
+    }
+  }
+
+  /**
+   * Set maximum number of retry attempts
+   * @param maxRetries Maximum retry attempts
+   */
+  setMaxRetries(maxRetries: number): void {
+    if (maxRetries < 0) {
+      throw new Error('maxRetries must be non-negative')
+    }
+    this.maxRetries = maxRetries
+  }
+
+  /**
+   * Set base delay for exponential backoff
+   * @param baseDelay Base delay in milliseconds
+   */
+  setBaseDelay(baseDelay: number): void {
+    if (baseDelay <= 0) {
+      throw new Error('baseDelay must be positive')
+    }
+    this.baseDelay = baseDelay
+  }
 }