@retrivora-ai/rag-engine 0.4.5 → 1.0.0

package/src/core/ConfigValidator.ts

@@ -1,19 +1,9 @@
-/**
- * ConfigValidator.ts — Comprehensive configuration validation.
- *
- * Validates RagConfig against provider requirements and best practices.
- * Returns detailed errors for misconfiguration.
- *
- * Key invariant: option keys validated here MUST match the keys each
- * Provider constructor reads. See each provider's constructor for the
- * canonical option names.
- */
-
 import { RagConfig, VectorDBConfig, LLMConfig, EmbeddingConfig } from '../config/RagConfig';
 import {
-  UI_VISUAL_STYLES,
   UI_BORDER_RADIUS_OPTIONS,
 } from '../config/constants';
+import { ProviderRegistry } from './ProviderRegistry';
+import { LLMFactory } from '../llm/LLMFactory';
 
 export interface ValidationError {
   field: string;
@@ -22,12 +12,15 @@ export interface ValidationError {
   severity: 'error' | 'warning';
 }
 
+/**
+ * ConfigValidator.ts — Comprehensive configuration validation.
+ * Uses a pluggable architecture to delegate provider-specific checks.
+ */
 export class ConfigValidator {
   /**
    * Validates the entire RagConfig object.
-   * Returns an array of validation errors. Empty array = valid config.
    */
-  static validate(config: RagConfig): ValidationError[] {
+  static async validate(config: RagConfig): Promise<ValidationError[]> {
     const errors: ValidationError[] = [];
 
     if (!config.projectId) {
@@ -38,11 +31,11 @@ export class ConfigValidator {
       });
     }
 
-    errors.push(...this.validateVectorDbConfig(config.vectorDb));
-    errors.push(...this.validateLLMConfig(config.llm));
+    errors.push(...(await this.validateVectorDbConfig(config.vectorDb)));
+    errors.push(...(await this.validateLLMConfig(config.llm)));
 
     if (config.embedding) {
-      errors.push(...this.validateEmbeddingConfig(config.embedding));
+      errors.push(...(await this.validateEmbeddingConfig(config.embedding)));
     } else if (config.llm.provider === 'anthropic') {
       errors.push({
         field: 'embedding',
@@ -63,472 +56,112 @@ export class ConfigValidator {
     return errors;
   }
 
-  private static validateVectorDbConfig(config: VectorDBConfig): ValidationError[] {
+  private static async validateVectorDbConfig(config: VectorDBConfig): Promise<ValidationError[]> {
     const errors: ValidationError[] = [];
 
     if (!config.provider) {
-      errors.push({
-        field: 'vectorDb.provider',
-        message: 'Vector database provider is required',
-        severity: 'error',
-      });
+      errors.push({ field: 'vectorDb.provider', message: 'Vector database provider is required', severity: 'error' });
       return errors;
     }
 
     if (!config.indexName) {
-      errors.push({
-        field: 'vectorDb.indexName',
-        message: 'Vector database index name is required',
-        severity: 'error',
-      });
-    }
-
-    switch (config.provider) {
-      case 'pinecone':
-        errors.push(...this.validatePineconeConfig(config));
-        break;
-      case 'pgvector':
-      case 'postgresql':
-        errors.push(...this.validatePostgresConfig(config));
-        break;
-      case 'mongodb':
-        errors.push(...this.validateMongoDBConfig(config));
-        break;
-      case 'milvus':
-        errors.push(...this.validateMilvusConfig(config));
-        break;
-      case 'qdrant':
-        errors.push(...this.validateQdrantConfig(config));
-        break;
-      case 'chromadb':
-        errors.push(...this.validateChromaDBConfig(config));
-        break;
-      case 'redis':
-        errors.push(...this.validateRedisConfig(config));
-        break;
-      case 'weaviate':
-        errors.push(...this.validateWeaviateConfig(config));
-        break;
-      case 'universal_rest':
-      case 'rest':
-        errors.push(...this.validateRestConfig(config));
-        break;
-    }
-
-    return errors;
-  }
-
-  /**
-   * Pinecone — only needs apiKey (environment was removed in SDK v7+).
-   * Options key: { apiKey: string }
-   */
-  private static validatePineconeConfig(config: VectorDBConfig): ValidationError[] {
-    const errors: ValidationError[] = [];
-    const opts = config.options as Record<string, unknown>;
-
-    if (!opts.apiKey) {
-      errors.push({
-        field: 'vectorDb.options.apiKey',
-        message: 'Pinecone API key is required',
-        suggestion: 'Set PINECONE_API_KEY environment variable',
-        severity: 'error',
-      });
-    }
-
-    return errors;
-  }
-
-  /**
-   * PostgreSQL / pgvector — needs a connection string.
-   * Options key: { connectionString: string }
-   */
-  private static validatePostgresConfig(config: VectorDBConfig): ValidationError[] {
-    const errors: ValidationError[] = [];
-    const opts = config.options as Record<string, unknown>;
-
-    if (!opts.connectionString) {
-      errors.push({
-        field: 'vectorDb.options.connectionString',
-        message: 'PostgreSQL connection string is required',
-        suggestion: 'Set PGVECTOR_CONNECTION_STRING environment variable',
-        severity: 'error',
-      });
-    }
-
-    if (opts.tables && typeof opts.tables !== 'string' && !Array.isArray(opts.tables)) {
-      errors.push({
-        field: 'vectorDb.options.tables',
-        message: 'PostgreSQL tables must be a string or a string array',
-        severity: 'error',
-      });
-    }
-
-    if (opts.searchFields && typeof opts.searchFields !== 'string' && !Array.isArray(opts.searchFields)) {
-      errors.push({
-        field: 'vectorDb.options.searchFields',
-        message: 'PostgreSQL searchFields must be a string or a string array',
-        severity: 'error',
-      });
-    }
-
-    return errors;
-  }
-
-  /**
-   * MongoDB — needs uri, database, and collection.
-   * Options keys: { uri: string, database: string, collection: string }
-   */
-  private static validateMongoDBConfig(config: VectorDBConfig): ValidationError[] {
-    const errors: ValidationError[] = [];
-    const opts = config.options as Record<string, unknown>;
-
-    if (!opts.uri) {
-      errors.push({
-        field: 'vectorDb.options.uri',
-        message: 'MongoDB connection URI is required',
-        suggestion: 'Set MONGODB_URI environment variable',
-        severity: 'error',
-      });
-    }
-
-    if (!opts.database) {
-      errors.push({
-        field: 'vectorDb.options.database',
-        message: 'MongoDB database name is required',
-        suggestion: 'Set MONGODB_DB environment variable',
-        severity: 'error',
-      });
+      errors.push({ field: 'vectorDb.indexName', message: 'Vector database index name is required', severity: 'error' });
     }
 
-    if (!opts.collection) {
-      errors.push({
-        field: 'vectorDb.options.collection',
-        message: 'MongoDB collection name is required',
-        suggestion: 'Set MONGODB_COLLECTION environment variable',
-        severity: 'error',
-      });
+    // Delegate to pluggable validator if available
+    const validator = await ProviderRegistry.getVectorValidator(config.provider);
+    if (validator) {
+      errors.push(...validator.validate(config as unknown as Record<string, unknown>));
+    } else {
+      // Fallback for non-migrated providers
+      this.fallbackVectorValidation(config, errors);
     }
 
     return errors;
   }
 
-  /**
-   * Milvus — accepts baseUrl OR uri (preferred) OR host+port.
-   * MilvusProvider reads opts.baseUrl ?? opts.uri.
-   * Options keys: { baseUrl?: string, uri?: string, host?: string, port?: number }
-   */
-  private static validateMilvusConfig(config: VectorDBConfig): ValidationError[] {
+  private static async validateLLMConfig(config: LLMConfig): Promise<ValidationError[]> {
     const errors: ValidationError[] = [];
-    const opts = config.options as Record<string, unknown>;
 
-    const hasBaseUrl = Boolean(opts.baseUrl || opts.uri);
-    const hasHostPort = Boolean(opts.host && opts.port);
-
-    if (!hasBaseUrl && !hasHostPort) {
-      errors.push({
-        field: 'vectorDb.options.baseUrl',
-        message: 'Milvus connection is required: provide baseUrl (e.g., "http://localhost:19530") or host + port',
-        suggestion: 'Set MILVUS_URL environment variable',
-        severity: 'error',
-      });
+    if (!config.provider) {
+      errors.push({ field: 'llm.provider', message: 'LLM provider is required', severity: 'error' });
+      return errors;
     }
 
-    return errors;
-  }
-
-  /**
-   * Qdrant — needs baseUrl (or url alias).
-   * Options keys: { baseUrl: string, apiKey?: string }
-   */
-  private static validateQdrantConfig(config: VectorDBConfig): ValidationError[] {
-    const errors: ValidationError[] = [];
-    const opts = config.options as Record<string, unknown>;
-
-    if (!opts.baseUrl && !opts.url) {
-      errors.push({
-        field: 'vectorDb.options.baseUrl',
-        message: 'Qdrant base URL is required',
-        suggestion: 'Set QDRANT_URL environment variable (e.g., "http://localhost:6333")',
-        severity: 'error',
-      });
+    const validator = LLMFactory.getValidator(config.provider);
+    if (validator) {
+      errors.push(...validator.validate(config as unknown as Record<string, unknown>));
+    } else {
+      this.fallbackLLMValidation(config, errors);
     }
 
-    return errors;
-  }
-
-  /**
-   * ChromaDB — accepts baseUrl OR host.
-   * ChromaDBProvider reads opts.baseUrl.
-   * Options keys: { baseUrl?: string, host?: string, port?: number }
-   */
-  private static validateChromaDBConfig(config: VectorDBConfig): ValidationError[] {
-    const errors: ValidationError[] = [];
-    const opts = config.options as Record<string, unknown>;
-
-    if (!opts.baseUrl && !opts.host) {
-      errors.push({
-        field: 'vectorDb.options.baseUrl',
-        message: 'ChromaDB connection is required: provide baseUrl (e.g., "http://localhost:8000") or host',
-        suggestion: 'Set CHROMADB_URL environment variable',
-        severity: 'error',
-      });
+    if (config.temperature !== undefined && (config.temperature < 0 || config.temperature > 2)) {
+      errors.push({ field: 'llm.temperature', message: 'Temperature must be between 0 and 2', severity: 'error' });
     }
 
     return errors;
   }
 
-  /**
-   * Redis — accepts baseUrl OR url OR host+port.
-   * RedisProvider reads opts.baseUrl.
-   * Options keys: { baseUrl?: string, url?: string, host?: string, port?: number, apiKey?: string }
-   */
-  private static validateRedisConfig(config: VectorDBConfig): ValidationError[] {
+  private static async validateEmbeddingConfig(config: EmbeddingConfig): Promise<ValidationError[]> {
     const errors: ValidationError[] = [];
-    const opts = config.options as Record<string, unknown>;
-
-    const hasUrl = Boolean(opts.baseUrl || opts.url);
-    const hasHostPort = Boolean(opts.host && opts.port);
 
-    if (!hasUrl && !hasHostPort) {
-      errors.push({
-        field: 'vectorDb.options.baseUrl',
-        message: 'Redis connection is required: provide baseUrl/url or host + port',
-        suggestion: 'Set REDIS_URL environment variable',
-        severity: 'error',
-      });
+    if (!config.provider) {
+      errors.push({ field: 'embedding.provider', message: 'Embedding provider is required', severity: 'error' });
+      return errors;
     }
 
-    return errors;
-  }
-
-  /**
-   * Weaviate — accepts baseUrl OR url.
-   * WeaviateProvider reads opts.baseUrl.
-   * Options keys: { baseUrl?: string, url?: string, apiKey?: string }
-   */
-  private static validateWeaviateConfig(config: VectorDBConfig): ValidationError[] {
-    const errors: ValidationError[] = [];
-    const opts = config.options as Record<string, unknown>;
-
-    if (!opts.baseUrl && !opts.url) {
-      errors.push({
-        field: 'vectorDb.options.baseUrl',
-        message: 'Weaviate instance URL is required',
-        suggestion: 'Set WEAVIATE_URL environment variable',
-        severity: 'error',
-      });
+    const validator = LLMFactory.getValidator(config.provider as unknown as LLMConfig['provider']);
+    if (validator) {
+      errors.push(...validator.validate(config as unknown as Record<string, unknown>));
+    } else {
+      this.fallbackEmbeddingValidation(config, errors);
     }
 
     return errors;
   }
 
   /**
-   * Universal REST / custom REST adapter.
-   * Options key: { baseUrl: string }
+   * Temporary fallbacks for providers not yet migrated to the pluggable architecture.
    */
-  private static validateRestConfig(config: VectorDBConfig): ValidationError[] {
-    const errors: ValidationError[] = [];
-    const opts = config.options as Record<string, unknown>;
-
-    if (!opts.baseUrl) {
-      errors.push({
-        field: 'vectorDb.options.baseUrl',
-        message: 'REST API base URL is required',
-        suggestion: 'Set VECTOR_BASE_URL environment variable',
-        severity: 'error',
-      });
-    }
-
-    return errors;
-  }
-
-  private static validateLLMConfig(config: LLMConfig): ValidationError[] {
-    const errors: ValidationError[] = [];
-
-    if (!config.provider) {
-      errors.push({
-        field: 'llm.provider',
-        message: 'LLM provider is required',
-        severity: 'error',
-      });
-      return errors;
-    }
-
-    if (!config.model) {
-      errors.push({
-        field: 'llm.model',
-        message: 'LLM model name is required',
-        suggestion: `e.g., "gpt-4o" for OpenAI, "claude-3-opus" for Anthropic`,
-        severity: 'error',
-      });
-    }
-
+  private static fallbackVectorValidation(config: VectorDBConfig, errors: ValidationError[]) {
+    const opts = (config.options || {}) as Record<string, unknown>;
     switch (config.provider) {
-      case 'openai':
-        if (!config.apiKey) {
-          errors.push({
-            field: 'llm.apiKey',
-            message: 'OpenAI API key is required',
-            suggestion: 'Set OPENAI_API_KEY environment variable',
-            severity: 'error',
-          });
-        }
-        break;
-      case 'anthropic':
-        if (!config.apiKey) {
-          errors.push({
-            field: 'llm.apiKey',
-            message: 'Anthropic API key is required',
-            suggestion: 'Set ANTHROPIC_API_KEY environment variable',
-            severity: 'error',
-          });
-        }
-        break;
-      case 'gemini':
-        if (!config.apiKey) {
-          errors.push({
-            field: 'llm.apiKey',
-            message: 'Gemini API key is required',
-            suggestion: 'Set GEMINI_API_KEY environment variable',
-            severity: 'error',
-          });
-        }
-        break;
-      case 'ollama':
-        if (!config.baseUrl) {
-          errors.push({
-            field: 'llm.baseUrl',
-            message: 'Ollama base URL is required',
-            suggestion: 'Set LLM_BASE_URL environment variable (e.g., "http://localhost:11434")',
-            severity: 'error',
-          });
+      case 'milvus':
+        if (!opts.baseUrl && !opts.uri && !(opts.host && opts.port)) {
+          errors.push({ field: 'vectorDb.options.baseUrl', message: 'Milvus connection info required', severity: 'error' });
         }
         break;
-      case 'rest':
-      case 'universal_rest':
-        if (!config.baseUrl && !(config.options as Record<string, unknown>)?.baseUrl) {
-          errors.push({
-            field: 'llm.baseUrl',
-            message: 'REST API base URL is required',
-            suggestion: 'Set LLM_BASE_URL environment variable',
-            severity: 'error',
-          });
+      case 'qdrant':
+        if (!opts.baseUrl && !opts.url) {
+          errors.push({ field: 'vectorDb.options.baseUrl', message: 'Qdrant URL required', severity: 'error' });
         }
         break;
+      // ... other fallbacks
     }
-
-    if (config.temperature !== undefined) {
-      if (config.temperature < 0 || config.temperature > 2) {
-        errors.push({
-          field: 'llm.temperature',
-          message: 'Temperature must be between 0 and 2',
-          severity: 'error',
-        });
-      }
-    }
-
-    if (config.maxTokens !== undefined && config.maxTokens <= 0) {
-      errors.push({
-        field: 'llm.maxTokens',
-        message: 'maxTokens must be greater than 0',
-        severity: 'error',
-      });
-    }
-
-    return errors;
   }
 
-  private static validateEmbeddingConfig(config: EmbeddingConfig): ValidationError[] {
-    const errors: ValidationError[] = [];
-
-    if (!config.provider) {
-      errors.push({
-        field: 'embedding.provider',
-        message: 'Embedding provider is required',
-        severity: 'error',
-      });
-      return errors;
-    }
-
+  private static fallbackLLMValidation(config: LLMConfig, errors: ValidationError[]) {
     if (!config.model) {
-      errors.push({
-        field: 'embedding.model',
-        message: 'Embedding model name is required',
-        suggestion: 'e.g., "text-embedding-3-small" for OpenAI, "nomic-embed-text" for Ollama',
-        severity: 'error',
-      });
-    }
-
-    if (config.provider === 'openai' && !config.apiKey) {
-      errors.push({
-        field: 'embedding.apiKey',
-        message: 'OpenAI API key is required for embedding',
-        suggestion: 'Set OPENAI_API_KEY environment variable',
-        severity: 'error',
-      });
-    }
-
-    if (config.provider === 'gemini' && !config.apiKey) {
-      errors.push({
-        field: 'embedding.apiKey',
-        message: 'Gemini API key is required for embedding',
-        suggestion: 'Set GEMINI_API_KEY environment variable',
-        severity: 'error',
-      });
-    }
-
-    if (config.provider === 'ollama' && !config.baseUrl) {
-      errors.push({
-        field: 'embedding.baseUrl',
-        message: 'Ollama base URL is required for embedding',
-        suggestion: 'Set EMBEDDING_BASE_URL environment variable',
-        severity: 'error',
-      });
+      errors.push({ field: 'llm.model', message: 'LLM model name is required', severity: 'error' });
     }
+    // Add other LLM fallbacks if needed
+  }
 
-    if (config.dimensions !== undefined && config.dimensions <= 0) {
-      errors.push({
-        field: 'embedding.dimensions',
-        message: 'Embedding dimensions must be greater than 0',
-        severity: 'error',
-      });
+  private static fallbackEmbeddingValidation(config: EmbeddingConfig, errors: ValidationError[]) {
+    if (!config.model) {
+      errors.push({ field: 'embedding.model', message: 'Embedding model name is required', severity: 'error' });
     }
-
-    return errors;
   }
 
   private static validateUIConfig(config: Record<string, unknown>): ValidationError[] {
     const errors: ValidationError[] = [];
 
-    if (config.primaryColor) {
-      if (!this.isValidCSSColor(config.primaryColor as string)) {
-        errors.push({
-          field: 'ui.primaryColor',
-          message: 'Invalid CSS color format',
-          suggestion: 'Use valid CSS colors: hex (#FF0000), rgb, hsl, or named colors',
-          severity: 'warning',
-        });
-      }
+    if (config.primaryColor && !this.isValidCSSColor(config.primaryColor as string)) {
+      errors.push({ field: 'ui.primaryColor', message: 'Invalid CSS color format', severity: 'warning' });
     }
 
-    if (config.borderRadius) {
-      if (!UI_BORDER_RADIUS_OPTIONS.includes(config.borderRadius as (typeof UI_BORDER_RADIUS_OPTIONS)[number])) {
-        errors.push({
-          field: 'ui.borderRadius',
-          message: `borderRadius must be one of: ${UI_BORDER_RADIUS_OPTIONS.join(', ')}`,
-          severity: 'warning',
-        });
-      }
-    }
-
-    if (config.visualStyle) {
-      if (!UI_VISUAL_STYLES.includes(config.visualStyle as (typeof UI_VISUAL_STYLES)[number])) {
-        errors.push({
-          field: 'ui.visualStyle',
-          message: `visualStyle must be one of: ${UI_VISUAL_STYLES.join(', ')}`,
-          severity: 'warning',
-        });
-      }
+    if (config.borderRadius && !UI_BORDER_RADIUS_OPTIONS.includes(config.borderRadius as typeof UI_BORDER_RADIUS_OPTIONS[number])) {
+      errors.push({ field: 'ui.borderRadius', message: `borderRadius must be one of: ${UI_BORDER_RADIUS_OPTIONS.join(', ')}`, severity: 'warning' });
     }
 
     return errors;
@@ -536,81 +169,22 @@ export class ConfigValidator {
 
   private static validateRAGConfig(config: Record<string, unknown>): ValidationError[] {
     const errors: ValidationError[] = [];
-
-    if (config.topK !== undefined) {
-      if (typeof config.topK !== 'number' || config.topK <= 0) {
-        errors.push({
-          field: 'rag.topK',
-          message: 'topK must be a positive integer',
-          severity: 'error',
-        });
-      }
+    if (config.topK !== undefined && (typeof config.topK !== 'number' || config.topK <= 0)) {
+      errors.push({ field: 'rag.topK', message: 'topK must be a positive integer', severity: 'error' });
     }
-
-    if (config.scoreThreshold !== undefined) {
-      if (typeof config.scoreThreshold !== 'number' || config.scoreThreshold < 0 || config.scoreThreshold > 1) {
-        errors.push({
-          field: 'rag.scoreThreshold',
-          message: 'scoreThreshold must be between 0 and 1',
-          severity: 'error',
-        });
-      }
-    }
-
-    if (config.chunkSize !== undefined) {
-      if (typeof config.chunkSize !== 'number' || config.chunkSize <= 0) {
-        errors.push({
-          field: 'rag.chunkSize',
-          message: 'chunkSize must be a positive integer',
-          severity: 'error',
-        });
-      }
-    }
-
-    if (config.chunkOverlap !== undefined) {
-      if (typeof config.chunkOverlap !== 'number' || config.chunkOverlap < 0) {
-        errors.push({
-          field: 'rag.chunkOverlap',
-          message: 'chunkOverlap must be a non-negative integer',
-          severity: 'error',
-        });
-      }
-    }
-
     return errors;
   }
 
   private static isValidCSSColor(color: string): boolean {
     const hexRegex = /^#([0-9a-f]{3}){1,2}$/i;
     const rgbRegex = /^rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*(\d+(?:\.\d+)?))?\)$/i;
-    const hslRegex = /^hsla?\((\d+),\s*(\d+)%,\s*(\d+)%(?:,\s*(\d+(?:\.\d+)?))?\)$/i;
     const namedColors = ['red', 'blue', 'green', 'black', 'white', 'transparent'];
-
-    return (
-      hexRegex.test(color) ||
-      rgbRegex.test(color) ||
-      hslRegex.test(color) ||
-      namedColors.includes(color.toLowerCase())
-    );
+    return hexRegex.test(color) || rgbRegex.test(color) || namedColors.includes(color.toLowerCase());
   }
 
-  /**
-   * Throws if there are error-level validation issues.
-   * Logs warnings to console.
-   */
-  static validateAndThrow(config: RagConfig): void {
-    const errors = this.validate(config);
-
+  static async validateAndThrow(config: RagConfig): Promise<void> {
+    const errors = await this.validate(config);
     const errorItems = errors.filter((e) => e.severity === 'error');
-    const warnings = errors.filter((e) => e.severity === 'warning');
-
-    if (warnings.length > 0) {
-      console.warn('[ConfigValidator] Configuration warnings:');
-      warnings.forEach((w) => {
-        console.warn(`  ${w.field}: ${w.message}`);
-        if (w.suggestion) console.warn(`    Suggestion: ${w.suggestion}`);
-      });
-    }
 
     if (errorItems.length > 0) {
       const message = errorItems