@retrivora-ai/rag-engine 0.4.4 → 1.0.0

package/src/core/ProviderRegistry.ts

@@ -3,123 +3,138 @@ import { BaseGraphProvider } from '@/providers/graphdb/BaseGraphProvider';
 import { VectorDBConfig, GraphDBConfig, LLMConfig, EmbeddingConfig } from '../config/RagConfig';
 import { LLMFactory } from '../llm/LLMFactory';
 import { ILLMProvider } from '../llm/ILLMProvider';
+import { IProviderValidator, IProviderHealthChecker } from './ProviderInterfaces';
 
 /**
  * ProviderRegistry — dynamic provider loader for Vector DBs and LLMs.
- *
- * Supports:
- * - Built-in providers loaded on-demand via dynamic imports (tree-shaking friendly)
- * - Custom provider registration via registerVectorProvider()
  */
+type VectorProviderClass = {
+  new (config: VectorDBConfig): BaseVectorProvider;
+  getValidator?: () => IProviderValidator;
+  getHealthChecker?: () => IProviderHealthChecker;
+};
+
+type GraphProviderClass = new (config: GraphDBConfig) => BaseGraphProvider;
+
 export class ProviderRegistry {
-  private static vectorProviders: Record<string, new (config: VectorDBConfig) => BaseVectorProvider> = {};
-  private static graphProviders: Record<string, new (config: GraphDBConfig) => BaseGraphProvider> = {};
+  private static vectorProviders: Record<string, VectorProviderClass> = {};
+  private static graphProviders: Record<string, GraphProviderClass> = {};
+  
+  private static vectorValidators: Record<string, IProviderValidator> = {};
+  private static vectorHealthCheckers: Record<string, IProviderHealthChecker> = {};
+  
+  private static llmValidators: Record<string, IProviderValidator> = {};
+  private static llmHealthCheckers: Record<string, IProviderHealthChecker> = {};
 
-  static registerVectorProvider(name: string, providerClass: new (config: VectorDBConfig) => BaseVectorProvider) {
+  static registerVectorProvider(name: string, providerClass: VectorProviderClass) {
     this.vectorProviders[name] = providerClass;
+    if (providerClass.getValidator) {
+      this.vectorValidators[name] = providerClass.getValidator();
+    }
+    if (providerClass.getHealthChecker) {
+      this.vectorHealthCheckers[name] = providerClass.getHealthChecker();
+    }
   }
 
-  /**
-   * Register a custom graph provider class by name.
-   */
-  static registerGraphProvider(name: string, providerClass: new (config: GraphDBConfig) => BaseGraphProvider) {
-    this.graphProviders[name] = providerClass;
+  static async getVectorValidator(provider: string): Promise<IProviderValidator | null> {
+    if (this.vectorValidators[provider]) return this.vectorValidators[provider];
+    
+    // Try to load built-in validator
+    try {
+      const providerClass = await this.loadVectorProviderClass(provider);
+      if (providerClass.getValidator) {
+        this.vectorValidators[provider] = providerClass.getValidator();
+        return this.vectorValidators[provider];
+      }
+    } catch (e) {
+      console.warn(`[ProviderRegistry] Failed to load validator for ${provider}:`, e);
+    }
+    return null;
   }
 
-  /**
-   * Creates a vector database provider based on the configuration.
-   * Built-in providers are dynamically imported to avoid bundling all SDKs.
-   */
-  static async createVectorProvider(config: VectorDBConfig): Promise<BaseVectorProvider> {
-    const { provider } = config;
-
-    // Custom registered provider takes priority
-    if (this.vectorProviders[provider]) {
-      return new this.vectorProviders[provider](config);
+  static async getVectorHealthChecker(provider: string): Promise<IProviderHealthChecker | null> {
+    if (this.vectorHealthCheckers[provider]) return this.vectorHealthCheckers[provider];
+    
+    try {
+      const providerClass = await this.loadVectorProviderClass(provider);
+      if (providerClass.getHealthChecker) {
+        this.vectorHealthCheckers[provider] = providerClass.getHealthChecker();
+        return this.vectorHealthCheckers[provider];
+      }
+    } catch (e) {
+      console.warn(`[ProviderRegistry] Failed to load health checker for ${provider}:`, e);
     }
+    return null;
+  }
+
+  private static async loadVectorProviderClass(provider: string): Promise<VectorProviderClass> {
+    if (this.vectorProviders[provider]) return this.vectorProviders[provider];
 
-    // Built-in providers — lazy-loaded
     switch (provider) {
       case 'pinecone': {
         const { PineconeProvider } = await import('../providers/vectordb/PineconeProvider');
-        return new PineconeProvider(config);
+        return PineconeProvider;
       }
       case 'pgvector':
       case 'postgresql': {
         const { PostgreSQLProvider } = await import('../providers/vectordb/PostgreSQLProvider');
-        return new PostgreSQLProvider(config);
+        return PostgreSQLProvider;
       }
       case 'mongodb': {
         const { MongoDBProvider } = await import('../providers/vectordb/MongoDBProvider');
-        return new MongoDBProvider(config);
+        return MongoDBProvider;
       }
       case 'milvus': {
         const { MilvusProvider } = await import('../providers/vectordb/MilvusProvider');
-        return new MilvusProvider(config);
+        return MilvusProvider;
       }
       case 'qdrant': {
         const { QdrantProvider } = await import('../providers/vectordb/QdrantProvider');
-        return new QdrantProvider(config);
+        return QdrantProvider;
       }
       case 'chromadb': {
         const { ChromaDBProvider } = await import('../providers/vectordb/ChromaDBProvider');
-        return new ChromaDBProvider(config);
+        return ChromaDBProvider;
       }
       case 'redis': {
         const { RedisProvider } = await import('../providers/vectordb/RedisProvider');
-        return new RedisProvider(config);
+        return RedisProvider;
       }
       case 'weaviate': {
         const { WeaviateProvider } = await import('../providers/vectordb/WeaviateProvider');
-        return new WeaviateProvider(config);
+        return WeaviateProvider;
       }
       case 'universal_rest':
       case 'rest': {
         const { UniversalVectorProvider } = await import('../providers/vectordb/UniversalVectorProvider');
-        return new UniversalVectorProvider(config);
+        return UniversalVectorProvider;
       }
       default:
-        throw new Error(
-          `[ProviderRegistry] Unsupported vector provider: "${provider}". ` +
-          `Built-in providers: pinecone | pgvector | postgresql | mongodb | milvus | qdrant | chromadb | redis | weaviate | universal_rest. ` +
-          `For custom providers, call ProviderRegistry.registerVectorProvider("${provider}", YourClass).`
-        );
+        throw new Error(`Unsupported vector provider: ${provider}`);
     }
   }
 
-  /**
-   * Creates a graph database provider based on the configuration.
-   */
+  static async createVectorProvider(config: VectorDBConfig): Promise<BaseVectorProvider> {
+    const providerClass = await this.loadVectorProviderClass(config.provider);
+    return new providerClass(config);
+  }
+
   static async createGraphProvider(config: GraphDBConfig): Promise<BaseGraphProvider> {
     const { provider } = config;
-
-    // Custom registered provider takes priority
     if (this.graphProviders[provider]) {
       return new this.graphProviders[provider](config);
     }
 
-    // Built-in providers — lazy-loaded
     switch (provider) {
-      case 'neo4j': {
-        // Placeholder for real Neo4j provider
-        throw new Error('[ProviderRegistry] Neo4j provider not implemented yet.');
-      }
       case 'simple': {
         const { SimpleGraphProvider } = await import('@/providers/graphdb/SimpleGraphProvider');
         return new SimpleGraphProvider(config);
       }
       default:
-        throw new Error(
-          `[ProviderRegistry] Unsupported graph provider: "${provider}". ` +
-          `Built-in providers: simple. ` +
-          `For custom providers, call ProviderRegistry.registerGraphProvider("${provider}", YourClass).`
-        );
+        throw new Error(`Unsupported graph provider: ${provider}`);
     }
   }
 
-  /**
-   * Creates an LLM provider based on the configuration.
-   */
   static createLLMProvider(llmConfig: LLMConfig, embeddingConfig?: EmbeddingConfig): ILLMProvider {
     return LLMFactory.create(llmConfig, embeddingConfig);
   }

package/src/core/QueryProcessor.ts

@@ -0,0 +1,173 @@
+/**
+ * QueryProcessor.ts — Utilities for pre-processing user questions.
+ * 
+ * Responsibilities:
+ * - Extracting semantic hints from natural language (emails, IDs, quoted phrases).
+ * - Normalizing text values for consistent filtering.
+ * - Building structured query filters for vector databases.
+ */
+
+export interface QueryFieldHint {
+  field?: string;
+  value: string;
+}
+
+export interface QueryFilter {
+  metadata?: Record<string, string>;
+  keywords?: string[];
+  queryText?: string;
+  [key: string]: unknown;
+}
+
+export class QueryProcessor {
+  /**
+   * Normalizes a string value by collapsing whitespace and trimming.
+   */
+  static normalizeHintValue(value: string): string {
+    return value.replace(/\s+/g, ' ').trim();
+  }
+
+  /**
+   * Checks if a string is likely a question word or common prompt phrase.
+   */
+  static isLikelyPromptPhrase(value: string): boolean {
+    return /^(what|which|who|where|when|why|how)\b/i.test(value.trim());
+  }
+
+  /**
+   * Scans a natural language question for potential metadata hints and keywords.
+   */
+  static extractQueryFieldHints(question: string): QueryFieldHint[] {
+    if (!question.trim()) return [];
+
+    const hints = new Map<string, QueryFieldHint>();
+
+    const addHint = (value: string, field?: string) => {
+      const normalizedValue = this.normalizeHintValue(value);
+      if (!normalizedValue) return;
+
+      const normalizedField = field
+        ? field
+          .toLowerCase()
+          .replace(/[^a-z0-9]+/g, ' ')
+          .trim()
+        : undefined;
+
+      const key = `${normalizedField ?? '*'}::${normalizedValue.toLowerCase()}`;
+      if (!hints.has(key)) {
+        hints.set(key, {
+          value: normalizedValue,
+          ...(normalizedField ? { field: normalizedField } : {}),
+        });
+      }
+    };
+
+    // 1. Quoted phrases
+    for (const match of question.matchAll(/["']([^"']{2,100})["']/g)) {
+      addHint(match[1]);
+    }
+
+    // 2. Natural question patterns
+    const naturalQuestionPatterns = [
+      /\b(?:what|which)\s+(?:is|are|was|were)\s+(?:the\s+)?([^?.!,]{1,60}?)\s+of\s+["']?([^"'\n?.!,]{2,120})["']?(?=[?.!,]|$)/gi,
+      /\b(?:who|what)\s+(?:is|are|was|were)\s+["']?([^"'\n?.!,]{2,120})["']?(?=[?.!,]|$)/gi,
+      /\b(?:about|for|regarding)\s+["']?([^"'\n?.!,]{2,120})["']?(?=[?.!,]|$)/gi,
+    ];
+
+    // 3. Person/Company targeted patterns
+    const personCompanyPatterns = [
+      /\bcompany(?:\s+name)?\s+(?:of|for)\s+["']?([^"'\n?.!,]{2,120})["']?(?=[?.!,]|$)/gi,
+      /\b(?:which|what)\s+company\s+does\s+["']?([^"'\n?.!,]{2,120})["']?\s+work(?:\s+for|\s+at)?(?=[?.!,]|$)/gi,
+      /\bwhere\s+does\s+["']?([^"'\n?.!,]{2,120})["']?\s+work(?:\s+for|\s+at)?(?=[?.!,]|$)/gi,
+    ];
+
+    for (const pattern of personCompanyPatterns) {
+      for (const match of question.matchAll(pattern)) {
+        const name = match[1];
+        if (name) addHint(name, 'name');
+      }
+    }
+
+    // 4. Universal patterns (email, phone, etc.)
+    const universalPatterns: Array<{ regex: RegExp; field?: string; group?: number }> = [
+      { regex: /([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})/gi, field: 'email', group: 1 },
+      { regex: /(\+?\d[\d\-\.\s\(\)]{6,}\d)/g, field: 'phone', group: 1 },
+      { regex: /(\b\d{4}-\d{2}-\d{2}\b|\b\d{1,2}\/\d{1,2}\/\d{2,4}\b)/g, field: 'date', group: 1 },
+      { regex: /(\$\s?\d{1,3}(?:,\d{3})*(?:\.\d+)?)/g, field: 'amount', group: 1 },
+      { regex: /\b(ID|id|identifier)[: ]\s*([A-Za-z0-9\-]{3,})\b/gi, field: 'id', group: 2 },
+      { regex: /"([^"]{2,120})"/g, group: 1 },
+      { regex: /'([^']{2,120})'/g, group: 1 },
+    ];
+
+    for (const p of universalPatterns) {
+      for (const match of question.matchAll(p.regex)) {
+        const val = p.group ? match[p.group] ?? match[0] : match[0];
+        if (!val) continue;
+        if (p.field) addHint(val, p.field);
+        else addHint(val);
+      }
+    }
+
+    for (const pattern of naturalQuestionPatterns) {
+      for (const match of question.matchAll(pattern)) {
+        const value = match[2] ?? match[1];
+        if (value) addHint(value);
+      }
+    }
+
+    // 5. Explicit field-value pairs (e.g., status=active, priority:high)
+    const fieldPattern = `([^\\n:=?.!,]{1,60}?)`;
+    const valuePattern = `([^\\n?.!,]{1,120}?)`;
+    const fieldValuePatterns = [
+      new RegExp(`\\b${fieldPattern}\\s*(?:=|:)\\s*["']?${valuePattern}["']?(?=[?.!,]|$)`, 'gi'),
+      new RegExp(`\\b${fieldPattern}\\s+(?:is|are|was|were|equals?|equal to|named|called)\\s+["']?${valuePattern}["']?(?=[?.!,]|$)`, 'gi'),
+      new RegExp(`\\bwith\\s+${fieldPattern}\\s+["']?${valuePattern}["']?(?=[?.!,]|$)`, 'gi'),
+    ];
+
+    for (const pattern of fieldValuePatterns) {
+      for (const match of question.matchAll(pattern)) {
+        const field = this.normalizeHintValue(match[1] ?? '');
+        const value = match[2] ?? '';
+
+        if (field && !this.isLikelyPromptPhrase(field)) {
+          addHint(value, field);
+        } else {
+          addHint(value);
+        }
+      }
+    }
+
+    // 6. Capitalized proper nouns
+    for (const match of question.matchAll(/\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+){0,3}\b/g)) {
+      addHint(match[0]);
+    }
+
+    return [...hints.values()];
+  }
+
+  /**
+   * Constructs a QueryFilter object from extracted hints.
+   */
+  static buildQueryFilter(question: string, hints: QueryFieldHint[]): QueryFilter {
+    const filter: QueryFilter = { metadata: {}, keywords: [], queryText: question };
+
+    for (const hint of hints) {
+      if (hint.field) {
+        filter.metadata![hint.field] = hint.value;
+      } else {
+        filter.keywords!.push(hint.value);
+      }
+    }
+
+    // Capture proper-noun sequences as keywords
+    for (const match of question.matchAll(/\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+){0,3}\b/g)) {
+      const term = this.normalizeHintValue(match[0]);
+      if (term && !filter.keywords!.includes(term)) filter.keywords!.push(term);
+    }
+
+    if (Object.keys(filter.metadata || {}).length === 0) delete filter.metadata;
+    if (filter.keywords && filter.keywords.length === 0) delete filter.keywords;
+
+    return filter;
+  }
+}

package/src/llm/ILLMProvider.ts

@@ -39,6 +39,16 @@ export interface ILLMProvider {
     options?: ChatOptions
   ): Promise<string>;
 
+  /**
+   * Send a streaming chat completion request.
+   * @returns – an async iterable of text chunks
+   */
+  chatStream?(
+    messages: ChatMessage[],
+    context: string,
+    options?: ChatOptions
+  ): AsyncIterable<string>;
+
   /**
    * Generate an embedding vector for the given text.
    * @param text    – text to embed

package/src/llm/LLMFactory.ts

@@ -1,10 +1,3 @@
-/**
- * LLMFactory — instantiates the correct ILLMProvider based on llmConfig.provider.
- *
- * Also accepts an optional EmbeddingConfig so providers that support embedding
- * can be initialised with separate embedding credentials.
- */
-
 import { ILLMProvider } from './ILLMProvider';
 import { LLMConfig, EmbeddingConfig, LLMProvider } from '../config/RagConfig';
 import { OpenAIProvider } from './providers/OpenAIProvider';
@@ -12,7 +5,16 @@ import { AnthropicProvider } from './providers/AnthropicProvider';
 import { OllamaProvider } from './providers/OllamaProvider';
 import { GeminiProvider } from './providers/GeminiProvider';
 import { UniversalLLMAdapter } from './providers/UniversalLLMAdapter';
+import { IProviderValidator, IProviderHealthChecker } from '../core/ProviderInterfaces';
 
+interface LLMProviderStatic {
+  getValidator?: () => IProviderValidator;
+  getHealthChecker?: () => IProviderHealthChecker;
+}
+
+/**
+ * LLMFactory — instantiates the correct ILLMProvider based on llmConfig.provider.
+ */
 export class LLMFactory {
   static create(llmConfig: LLMConfig, embeddingConfig?: EmbeddingConfig): ILLMProvider {
     switch (llmConfig.provider) {
@@ -29,20 +31,38 @@ export class LLMFactory {
       case 'custom':
         return new UniversalLLMAdapter(llmConfig);
       default:
-        // If baseUrl is provided but provider is unknown, fallback to Universal Adapter
         if (llmConfig.baseUrl || (llmConfig.options as Record<string, unknown>)?.baseUrl) {
           return new UniversalLLMAdapter(llmConfig);
         }
-        throw new Error(
-          `[LLMFactory] Unknown provider "${llmConfig.provider}". ` +
-            `Supported: openai | anthropic | ollama | rest | custom`
-        );
+        throw new Error(`[LLMFactory] Unknown provider "${llmConfig.provider}"`);
+    }
+  }
+
+  static getValidator(provider: LLMProvider): IProviderValidator | null {
+    const providerClass = this.getProviderClass(provider);
+    return providerClass && providerClass.getValidator ? providerClass.getValidator() : null;
+  }
+
+  static getHealthChecker(provider: LLMProvider): IProviderHealthChecker | null {
+    const providerClass = this.getProviderClass(provider);
+    return providerClass && providerClass.getHealthChecker ? providerClass.getHealthChecker() : null;
+  }
+
+  private static getProviderClass(provider: string): LLMProviderStatic | null {
+    switch (provider) {
+      case 'openai': return OpenAIProvider;
+      case 'anthropic': return AnthropicProvider;
+      case 'ollama': return OllamaProvider;
+      case 'gemini': return GeminiProvider;
+      case 'rest':
+      case 'universal_rest':
+      case 'custom': return UniversalLLMAdapter as unknown as LLMProviderStatic;
+      default: return null;
     }
   }
 
   /**
    * Creates a dedicated embedding-only provider.
-   * Useful when the LLM provider (e.g. Anthropic) doesn't support embeddings.
    */
   static createEmbeddingProvider(embeddingConfig: EmbeddingConfig): ILLMProvider {
     const fakeLLMConfig: LLMConfig = {

package/src/llm/providers/AnthropicProvider.ts

@@ -1,18 +1,12 @@
 /**
  * Anthropic (Claude) LLM Provider
- *
- * Handles chat completion via Anthropic's Messages API.
- * Note: Anthropic does NOT provide embedding models — use OpenAIProvider
- * or OllamaProvider for embedding when pairing with this provider.
- *
- * Required LLMConfig fields:
- *   - apiKey: string  – Anthropic API key
- *   - model:  string  – e.g. "claude-3-5-sonnet-20241022"
  */
 
 import Anthropic from '@anthropic-ai/sdk';
 import { ILLMProvider, ChatMessage, ChatOptions, EmbedOptions } from '../ILLMProvider';
 import { LLMConfig, EmbeddingConfig } from '../../config/RagConfig';
+import { IProviderValidator, IProviderHealthChecker, HealthCheckResult } from '../../core/ProviderInterfaces';
+import { ValidationError } from '../../core/ConfigValidator';
 
 export class AnthropicProvider implements ILLMProvider {
   private readonly client: Anthropic;
@@ -26,6 +20,59 @@ export class AnthropicProvider implements ILLMProvider {
     this.embeddingConfig = embeddingConfig;
   }
 
+  static getValidator(): IProviderValidator {
+    return {
+      validate(config: Record<string, unknown>): ValidationError[] {
+        const errors: ValidationError[] = [];
+        if (!config.apiKey) {
+          errors.push({
+            field: 'llm.apiKey',
+            message: 'Anthropic API key is required',
+            suggestion: 'Set ANTHROPIC_API_KEY environment variable',
+            severity: 'error',
+          });
+        }
+        if (!config.model) {
+          errors.push({
+            field: 'llm.model',
+            message: 'Anthropic model name is required',
+            suggestion: 'e.g., "claude-3-5-sonnet-20241022"',
+            severity: 'error',
+          });
+        }
+        return errors;
+      }
+    };
+  }
+
+  static getHealthChecker(): IProviderHealthChecker {
+    return {
+      async check(config: Record<string, unknown>): Promise<HealthCheckResult> {
+        const timestamp = Date.now();
+        const apiKey = config.apiKey as string;
+        const modelName = config.model as string;
+        
+        try {
+          const { default: Anthropic } = await import('@anthropic-ai/sdk');
+          const client = new Anthropic({ apiKey });
+          await client.messages.create({
+            model: modelName,
+            max_tokens: 10,
+            messages: [{ role: 'user', content: 'ping' }],
+          });
+          return { healthy: true, provider: 'anthropic', capabilities: { model: modelName }, timestamp };
+        } catch (error) {
+          return {
+            healthy: false,
+            provider: 'anthropic',
+            error: `Connection failed: ${error instanceof Error ? error.message : String(error)}`,
+            timestamp,
+          };
+        }
+      }
+    };
+  }
+
   async chat(messages: ChatMessage[], context: string, options?: ChatOptions): Promise<string> {
     const systemPrompt =
       this.llmConfig.systemPrompt ??
@@ -35,7 +82,6 @@ export class AnthropicProvider implements ILLMProvider {
       ? systemPrompt.replace('{{context}}', context)
       : `${systemPrompt}\n\nContext:\n${context}`;
 
-    // Anthropic requires alternating user/assistant messages
     const anthropicMessages: Anthropic.MessageParam[] = messages.map((m) => ({
       role: m.role === 'assistant' ? 'assistant' : 'user',
       content: m.content,
@@ -52,11 +98,6 @@ export class AnthropicProvider implements ILLMProvider {
     return block.type === 'text' ? block.text : '';
   }
 
-  /**
-   * Anthropic does not offer an embedding API.
-   * This method throws with a clear error so developers know to configure
-   * a separate embedding provider (OpenAI or Ollama).
-   */
   async embed(text: string, options?: EmbedOptions): Promise<number[]> {
     void text;
     void options;
@@ -76,7 +117,6 @@ export class AnthropicProvider implements ILLMProvider {
 
   async ping(): Promise<boolean> {
     try {
-      // Lightweight model list call to verify connectivity
       await this.client.models.list();
       return true;
     } catch (err) {

package/src/llm/providers/GeminiProvider.ts

@@ -17,6 +17,8 @@
 import { GoogleGenAI } from '@google/genai';
 import { ILLMProvider, ChatMessage, ChatOptions, EmbedOptions } from '../ILLMProvider';
 import { LLMConfig, EmbeddingConfig } from '../../config/RagConfig';
+import { IProviderValidator, IProviderHealthChecker, HealthCheckResult } from '../../core/ProviderInterfaces';
+import { ValidationError } from '../../core/ConfigValidator';
 
 export class GeminiProvider implements ILLMProvider {
   private readonly client: GoogleGenAI;
@@ -41,6 +43,55 @@ export class GeminiProvider implements ILLMProvider {
     }
   }
 
+  static getValidator(): IProviderValidator {
+    return {
+      validate(config: Record<string, unknown>): ValidationError[] {
+        const errors: ValidationError[] = [];
+        if (!config.apiKey && !process.env.GOOGLE_GENAI_API_KEY) {
+          errors.push({
+            field: 'llm.apiKey',
+            message: 'Gemini API key is required',
+            suggestion: 'Set GOOGLE_GENAI_API_KEY environment variable or provide in config',
+            severity: 'error'
+          });
+        }
+        if (!config.model) {
+          errors.push({ field: 'llm.model', message: 'Gemini model name is required', severity: 'error' });
+        }
+        return errors;
+      }
+    };
+  }
+
+  static getHealthChecker(): IProviderHealthChecker {
+    return {
+      async check(config: Record<string, unknown>): Promise<HealthCheckResult> {
+        const timestamp = Date.now();
+        const apiKey = (config.apiKey as string) || process.env.GOOGLE_GENAI_API_KEY || '';
+        const modelName = config.model as string;
+        try {
+          const { GoogleGenAI } = await import('@google/genai');
+          const genAI = new GoogleGenAI({ apiKey });
+          // Verify model availability
+          await genAI.models.get({ model: modelName });
+          return {
+            healthy: true,
+            provider: 'gemini',
+            capabilities: { model: modelName },
+            timestamp,
+          };
+        } catch (error) {
+          return {
+            healthy: false,
+            provider: 'gemini',
+            error: error instanceof Error ? error.message : String(error),
+            timestamp,
+          };
+        }
+      }
+    };
+  }
+
   private sanitizeModel(model: string): string {
     if (!model) return model;
     // Strip :latest suffix common in Ollama but invalid in Google SDK