@retrivora-ai/rag-engine 0.1.5 → 0.1.7

package/src/core/ConfigValidator.ts

@@ -0,0 +1,568 @@
+/**
+ * ConfigValidator.ts — Comprehensive configuration validation.
+ *
+ * Validates RagConfig against provider requirements and best practices.
+ * Returns detailed errors for misconfiguration.
+ */
+
+import { RagConfig, VectorDBConfig, LLMConfig, EmbeddingConfig } from '../config/RagConfig';
+
+export interface ValidationError {
+  field: string;
+  message: string;
+  suggestion?: string;
+  severity: 'error' | 'warning';
+}
+
+export class ConfigValidator {
+  /**
+   * Validates the entire RagConfig object.
+   * Returns an array of validation errors. Empty array = valid config.
+   */
+  static validate(config: RagConfig): ValidationError[] {
+    const errors: ValidationError[] = [];
+
+    // Validate root level
+    if (!config.projectId) {
+      errors.push({
+        field: 'projectId',
+        message: 'projectId is required',
+        severity: 'error',
+      });
+    }
+
+    // Validate Vector DB configuration
+    errors.push(...this.validateVectorDbConfig(config.vectorDb));
+
+    // Validate LLM configuration
+    errors.push(...this.validateLLMConfig(config.llm));
+
+    // Validate Embedding configuration (if provided)
+    if (config.embedding) {
+      errors.push(...this.validateEmbeddingConfig(config.embedding));
+    } else if (config.llm.provider === 'anthropic') {
+      // Anthropic should have a separate embedding provider
+      errors.push({
+        field: 'embedding',
+        message: 'Embedding config is required when using Anthropic LLM',
+        suggestion: 'Provide embedding config with provider (e.g., "openai")',
+        severity: 'error',
+      });
+    }
+
+    // Validate UI config if provided
+    if (config.ui) {
+      errors.push(...this.validateUIConfig(config.ui as Record<string, unknown>));
+    }
+
+    // Validate RAG tuning if provided
+    if (config.rag) {
+      errors.push(...this.validateRAGConfig(config.rag as Record<string, unknown>));
+    }
+
+    return errors;
+  }
+
+  private static validateVectorDbConfig(config: VectorDBConfig): ValidationError[] {
+    const errors: ValidationError[] = [];
+
+    if (!config.provider) {
+      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',
+      });
+    }
+
+    // Provider-specific validation
+    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;
+  }
+
+  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',
+      });
+    }
+
+    if (!opts.environment) {
+      errors.push({
+        field: 'vectorDb.options.environment',
+        message: 'Pinecone environment is required',
+        suggestion: 'Set PINECONE_ENVIRONMENT environment variable (e.g., "gcp-starter")',
+        severity: 'error',
+      });
+    }
+
+    return errors;
+  }
+
+  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',
+      });
+    }
+
+    return errors;
+  }
+
+  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',
+      });
+    }
+
+    if (!opts.collection) {
+      errors.push({
+        field: 'vectorDb.options.collection',
+        message: 'MongoDB collection name is required',
+        suggestion: 'Set MONGODB_COLLECTION environment variable',
+        severity: 'error',
+      });
+    }
+
+    return errors;
+  }
+
+  private static validateMilvusConfig(config: VectorDBConfig): ValidationError[] {
+    const errors: ValidationError[] = [];
+    const opts = config.options as Record<string, unknown>;
+
+    if (!opts.host) {
+      errors.push({
+        field: 'vectorDb.options.host',
+        message: 'Milvus host is required',
+        suggestion: 'Set MILVUS_HOST environment variable',
+        severity: 'error',
+      });
+    }
+
+    if (!opts.port) {
+      errors.push({
+        field: 'vectorDb.options.port',
+        message: 'Milvus port is required',
+        suggestion: 'Set MILVUS_PORT environment variable (default: 19530)',
+        severity: 'error',
+      });
+    }
+
+    return errors;
+  }
+
+  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',
+      });
+    }
+
+    return errors;
+  }
+
+  private static validateChromaDBConfig(config: VectorDBConfig): ValidationError[] {
+    const errors: ValidationError[] = [];
+    const opts = config.options as Record<string, unknown>;
+
+    if (!opts.host && !opts.path) {
+      errors.push({
+        field: 'vectorDb.options.host',
+        message: 'ChromaDB host or path is required',
+        suggestion: 'Set CHROMADB_HOST or CHROMADB_PATH environment variable',
+        severity: 'error',
+      });
+    }
+
+    return errors;
+  }
+
+  private static validateRedisConfig(config: VectorDBConfig): ValidationError[] {
+    const errors: ValidationError[] = [];
+    const opts = config.options as Record<string, unknown>;
+
+    if (!opts.url && (!opts.host || !opts.port)) {
+      errors.push({
+        field: 'vectorDb.options.url',
+        message: 'Redis connection URL or host:port is required',
+        suggestion: 'Set REDIS_URL or REDIS_HOST/REDIS_PORT environment variables',
+        severity: 'error',
+      });
+    }
+
+    return errors;
+  }
+
+  private static validateWeaviateConfig(config: VectorDBConfig): ValidationError[] {
+    const errors: ValidationError[] = [];
+    const opts = config.options as Record<string, unknown>;
+
+    if (!opts.url) {
+      errors.push({
+        field: 'vectorDb.options.url',
+        message: 'Weaviate instance URL is required',
+        suggestion: 'Set WEAVIATE_URL environment variable',
+        severity: 'error',
+      });
+    }
+
+    return errors;
+  }
+
+  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',
+      });
+    }
+
+    // Provider-specific validation
+    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 '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',
+          });
+        }
+        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',
+          });
+        }
+        break;
+    }
+
+    // Validate temperature
+    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',
+        });
+      }
+    }
+
+    // Validate maxTokens
+    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;
+    }
+
+    if (!config.model) {
+      errors.push({
+        field: 'embedding.model',
+        message: 'Embedding model name is required',
+        suggestion: 'e.g., "text-embedding-3-small" for OpenAI',
+        severity: 'error',
+      });
+    }
+
+    // Provider-specific validation
+    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 === 'ollama' && !config.baseUrl) {
+      errors.push({
+        field: 'embedding.baseUrl',
+        message: 'Ollama base URL is required',
+        suggestion: 'Set EMBEDDING_BASE_URL environment variable',
+        severity: 'error',
+      });
+    }
+
+    // Validate dimensions
+    if (config.dimensions !== undefined && config.dimensions <= 0) {
+      errors.push({
+        field: 'embedding.dimensions',
+        message: 'Embedding dimensions must be greater than 0',
+        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.borderRadius) {
+      const validValues = ['none', 'sm', 'md', 'lg', 'xl', 'full'];
+      if (!validValues.includes(config.borderRadius as string)) {
+        errors.push({
+          field: 'ui.borderRadius',
+          message: `borderRadius must be one of: ${validValues.join(', ')}`,
+          severity: 'warning',
+        });
+      }
+    }
+
+    if (config.visualStyle) {
+      const validValues = ['glass', 'solid'];
+      if (!validValues.includes(config.visualStyle as string)) {
+        errors.push({
+          field: 'ui.visualStyle',
+          message: `visualStyle must be one of: ${validValues.join(', ')}`,
+          severity: 'warning',
+        });
+      }
+    }
+
+    return errors;
+  }
+
+  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.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 {
+    // Basic regex for hex, rgb, rgba, hsl, hsla
+    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']; // basic set
+
+    return (
+      hexRegex.test(color) ||
+      rgbRegex.test(color) ||
+      hslRegex.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);
+
+    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
+        .map((e) => `${e.field}: ${e.message}${e.suggestion ? ` (${e.suggestion})` : ''}`)
+        .join('\n  ');
+      throw new Error(`[ConfigValidator] Configuration validation failed:\n  ${message}`);
+    }
+  }
+}