@retrivora-ai/rag-engine 0.1.5 → 0.1.7

package/src/core/ProviderHealthCheck.ts

@@ -0,0 +1,568 @@
+/**
+ * ProviderHealthCheck.ts — Pre-flight validation for vector DB and LLM providers.
+ *
+ * Performs connectivity tests, credential validation, and capability checks
+ * before initializing providers.
+ */
+
+import { VectorDBConfig, LLMConfig, EmbeddingConfig } from '../config/RagConfig';
+import { ConfigValidator } from './ConfigValidator';
+
+export interface HealthCheckResult {
+  healthy: boolean;
+  provider: string;
+  version?: string;
+  capabilities?: Record<string, unknown>;
+  error?: string;
+  timestamp: number;
+}
+
+export class ProviderHealthCheck {
+  /**
+   * Validates vector database configuration before initialization.
+   * Performs connectivity checks and verifies required resources exist.
+   */
+  static async checkVectorProvider(config: VectorDBConfig): Promise<HealthCheckResult> {
+    const timestamp = Date.now();
+
+    // First validate configuration
+    const configErrors = ConfigValidator.validate({
+      projectId: 'health-check',
+      vectorDb: config,
+      llm: { provider: 'openai', model: 'gpt-4o' }, // dummy
+      embedding: { provider: 'openai', model: 'text-embedding-3-small' },
+    });
+
+    const vectorDbErrors = configErrors.filter((e) => e.field.startsWith('vectorDb'));
+    if (vectorDbErrors.length > 0) {
+      return {
+        healthy: false,
+        provider: config.provider,
+        error: `Configuration validation failed: ${vectorDbErrors.map((e) => e.message).join('; ')}`,
+        timestamp,
+      };
+    }
+
+    try {
+      switch (config.provider) {
+        case 'pinecone':
+          return await this.checkPinecone(config, timestamp);
+        case 'pgvector':
+        case 'postgresql':
+          return await this.checkPostgres(config, timestamp);
+        case 'mongodb':
+          return await this.checkMongoDB(config, timestamp);
+        case 'milvus':
+          return await this.checkMilvus(config, timestamp);
+        case 'qdrant':
+          return await this.checkQdrant(config, timestamp);
+        case 'chromadb':
+          return await this.checkChromaDB(config, timestamp);
+        case 'redis':
+          return await this.checkRedis(config, timestamp);
+        case 'weaviate':
+          return await this.checkWeaviate(config, timestamp);
+        case 'rest':
+        case 'universal_rest':
+          return await this.checkRestAPI(config, timestamp);
+        default:
+          return {
+            healthy: false,
+            provider: config.provider,
+            error: `Unsupported provider: ${config.provider}`,
+            timestamp,
+          };
+      }
+    } catch (error) {
+      return {
+        healthy: false,
+        provider: config.provider,
+        error: error instanceof Error ? error.message : String(error),
+        timestamp,
+      };
+    }
+  }
+
+  private static async checkPinecone(config: VectorDBConfig, timestamp: number): Promise<HealthCheckResult> {
+    const opts = config.options as Record<string, string>;
+    
+    try {
+      // Dynamic import to avoid requiring all dependencies
+      const { Pinecone } = await import('@pinecone-database/pinecone');
+      const client = new Pinecone({ apiKey: opts.apiKey });
+      
+      const indexes = await client.listIndexes();
+      const indexNames = indexes.indexes?.map((i) => i.name) ?? [];
+      
+      if (!indexNames.includes(config.indexName)) {
+        return {
+          healthy: false,
+          provider: 'pinecone',
+          error: `Index "${config.indexName}" not found. Available: ${indexNames.join(', ')}`,
+          timestamp,
+        };
+      }
+
+      return {
+        healthy: true,
+        provider: 'pinecone',
+        capabilities: {
+          indexes: indexNames.length,
+          targetIndex: config.indexName,
+        },
+        timestamp,
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        provider: 'pinecone',
+        error: `Connection failed: ${error instanceof Error ? error.message : String(error)}`,
+        timestamp,
+      };
+    }
+  }
+
+  private static async checkPostgres(config: VectorDBConfig, timestamp: number): Promise<HealthCheckResult> {
+    const opts = config.options as Record<string, string>;
+
+    try {
+      const { Client } = await import('pg');
+      const client = new Client({ connectionString: opts.connectionString });
+      
+      await client.connect();
+      
+      // Check if pgvector extension is installed
+      const result = await client.query(`
+        SELECT EXISTS(
+          SELECT 1 FROM pg_extension WHERE extname = 'vector'
+        );
+      `);
+      
+      const hasVector = result.rows[0].exists;
+      
+      await client.end();
+
+      return {
+        healthy: true,
+        provider: 'postgresql',
+        capabilities: { pgvectorInstalled: hasVector },
+        timestamp,
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        provider: 'postgresql',
+        error: `Connection failed: ${error instanceof Error ? error.message : String(error)}`,
+        timestamp,
+      };
+    }
+  }
+
+  private static async checkMongoDB(config: VectorDBConfig, timestamp: number): Promise<HealthCheckResult> {
+    const opts = config.options as Record<string, string>;
+
+    try {
+      const { MongoClient } = await import('mongodb');
+      const client = new MongoClient(opts.uri);
+      
+      await client.connect();
+      
+      const db = client.db(opts.database);
+      const collections = await db.listCollections().toArray();
+      const collectionNames = collections.map((c) => c.name);
+      
+      const hasCollection = collectionNames.includes(opts.collection);
+      
+      await client.close();
+
+      return {
+        healthy: true,
+        provider: 'mongodb',
+        capabilities: {
+          collections: collectionNames.length,
+          targetCollection: hasCollection ? opts.collection : 'NOT FOUND',
+        },
+        timestamp,
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        provider: 'mongodb',
+        error: `Connection failed: ${error instanceof Error ? error.message : String(error)}`,
+        timestamp,
+      };
+    }
+  }
+
+  private static async checkMilvus(config: VectorDBConfig, timestamp: number): Promise<HealthCheckResult> {
+    const opts = config.options as Record<string, unknown>;
+    const host = (opts.host as string) || 'localhost';
+    const port = (opts.port as number) || 19530;
+
+    try {
+      // Try HTTP health check endpoint
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), 5000);
+      
+      const response = await fetch(`http://${host}:${port}/healthz`, {
+        signal: controller.signal,
+      });
+      
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        throw new Error(`Health check returned ${response.status}`);
+      }
+
+      return {
+        healthy: true,
+        provider: 'milvus',
+        capabilities: { endpoint: `${host}:${port}` },
+        timestamp,
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        provider: 'milvus',
+        error: `Connection failed: ${error instanceof Error ? error.message : String(error)}`,
+        timestamp,
+      };
+    }
+  }
+
+  private static async checkQdrant(config: VectorDBConfig, timestamp: number): Promise<HealthCheckResult> {
+    const opts = config.options as Record<string, unknown>;
+    const baseUrl = (opts.baseUrl as string) || (opts.url as string) || 'http://localhost:6333';
+
+    try {
+      const apiKey = opts.apiKey as string | undefined;
+      const response = await fetch(`${baseUrl}/`, {
+        headers: apiKey ? { 'api-key': apiKey } : {},
+      });
+      
+      if (!response.ok) {
+        throw new Error(`Health check returned ${response.status}`);
+      }
+
+      const health = await response.json();
+
+      return {
+        healthy: true,
+        provider: 'qdrant',
+        capabilities: health as Record<string, unknown>,
+        timestamp,
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        provider: 'qdrant',
+        error: `Connection failed: ${error instanceof Error ? error.message : String(error)}`,
+        timestamp,
+      };
+    }
+  }
+
+  private static async checkChromaDB(config: VectorDBConfig, timestamp: number): Promise<HealthCheckResult> {
+    const opts = config.options as Record<string, unknown>;
+    const host = (opts.host as string) || 'localhost';
+    const port = (opts.port as number) || 8000;
+
+    try {
+      const response = await fetch(`http://${host}:${port}/api/v1/heartbeat`);
+      
+      if (!response.ok) {
+        throw new Error(`Health check returned ${response.status}`);
+      }
+
+      return {
+        healthy: true,
+        provider: 'chromadb',
+        capabilities: { endpoint: `${host}:${port}` },
+        timestamp,
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        provider: 'chromadb',
+        error: `Connection failed: ${error instanceof Error ? error.message : String(error)}`,
+        timestamp,
+      };
+    }
+  }
+
+  private static async checkRedis(config: VectorDBConfig, timestamp: number): Promise<HealthCheckResult> {
+    const opts = config.options as Record<string, string>;
+    const url = opts.url || `redis://${opts.host}:${opts.port}`;
+
+    try {
+      // Try to connect via simple TCP check using fetch
+      // Note: Full Redis connection would require redis package as optional dependency
+      await fetch(url);
+      
+      return {
+        healthy: true,
+        provider: 'redis',
+        capabilities: { endpoint: url },
+        timestamp,
+      };
+    } catch (error) {
+      // If fetch fails, try to gracefully handle (redis may not have HTTP interface)
+      return {
+        healthy: false,
+        provider: 'redis',
+        error: `Connection check failed: ${error instanceof Error ? error.message : String(error)}. Ensure Redis is running at ${url}`,
+        timestamp,
+      };
+    }
+  }
+
+  private static async checkWeaviate(config: VectorDBConfig, timestamp: number): Promise<HealthCheckResult> {
+    const opts = config.options as Record<string, string>;
+    const url = (opts.url || 'http://localhost:8080').replace(/\/$/, '');
+
+    try {
+      const response = await fetch(`${url}/.well-known/ready`);
+      
+      if (!response.ok) {
+        throw new Error(`Health check returned ${response.status}`);
+      }
+
+      return {
+        healthy: true,
+        provider: 'weaviate',
+        capabilities: { endpoint: url },
+        timestamp,
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        provider: 'weaviate',
+        error: `Connection failed: ${error instanceof Error ? error.message : String(error)}`,
+        timestamp,
+      };
+    }
+  }
+
+  private static async checkRestAPI(config: VectorDBConfig, timestamp: number): Promise<HealthCheckResult> {
+    const opts = config.options as Record<string, string>;
+    const baseUrl = (opts.baseUrl || '').replace(/\/$/, '');
+
+    if (!baseUrl) {
+      return {
+        healthy: false,
+        provider: 'rest',
+        error: 'baseUrl is required',
+        timestamp,
+      };
+    }
+
+    try {
+      const response = await fetch(`${baseUrl}/health`, {
+        headers: opts.headers ? JSON.parse(opts.headers) : {},
+      });
+
+      return {
+        healthy: response.ok,
+        provider: 'rest',
+        error: response.ok ? undefined : `Health check returned ${response.status}`,
+        timestamp,
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        provider: 'rest',
+        error: `Connection failed: ${error instanceof Error ? error.message : String(error)}`,
+        timestamp,
+      };
+    }
+  }
+
+  /**
+   * Validates LLM provider configuration.
+   */
+  static async checkLLMProvider(config: LLMConfig): Promise<HealthCheckResult> {
+    const timestamp = Date.now();
+
+    try {
+      switch (config.provider) {
+        case 'openai':
+          return await this.checkOpenAI(config, timestamp);
+        case 'anthropic':
+          return await this.checkAnthropic(config, timestamp);
+        case 'ollama':
+          return await this.checkOllama(config, timestamp);
+        case 'rest':
+        case 'universal_rest':
+          return await this.checkLLMRestAPI(config, timestamp);
+        default:
+          return {
+            healthy: false,
+            provider: config.provider,
+            error: `Unsupported provider: ${config.provider}`,
+            timestamp,
+          };
+      }
+    } catch (error) {
+      return {
+        healthy: false,
+        provider: config.provider,
+        error: error instanceof Error ? error.message : String(error),
+        timestamp,
+      };
+    }
+  }
+
+  private static async checkOpenAI(config: LLMConfig, timestamp: number): Promise<HealthCheckResult> {
+    try {
+      const OpenAI = await import('openai');
+      const client = new OpenAI.default({ apiKey: config.apiKey });
+
+      // Test models endpoint
+      const models = await client.models.list();
+      
+      const hasModel = models.data.some((m) => m.id === config.model);
+
+      return {
+        healthy: true,
+        provider: 'openai',
+        capabilities: {
+          model: config.model,
+          available: hasModel,
+          totalModels: models.data.length,
+        },
+        timestamp,
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        provider: 'openai',
+        error: `Connection failed: ${error instanceof Error ? error.message : String(error)}`,
+        timestamp,
+      };
+    }
+  }
+
+  private static async checkAnthropic(config: LLMConfig, timestamp: number): Promise<HealthCheckResult> {
+    try {
+      const { default: Anthropic } = await import('@anthropic-ai/sdk');
+      const client = new Anthropic({ apiKey: config.apiKey });
+
+      // Try a minimal API call to verify credentials
+      await client.messages.create({
+        model: config.model,
+        max_tokens: 10,
+        messages: [{ role: 'user', content: 'ping' }],
+      });
+
+      return {
+        healthy: true,
+        provider: 'anthropic',
+        capabilities: { model: config.model },
+        timestamp,
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        provider: 'anthropic',
+        error: `Connection failed: ${error instanceof Error ? error.message : String(error)}`,
+        timestamp,
+      };
+    }
+  }
+
+  private static async checkOllama(config: LLMConfig, timestamp: number): Promise<HealthCheckResult> {
+    const baseUrl = (config.baseUrl || 'http://localhost:11434').replace(/\/$/, '');
+
+    try {
+      const response = await fetch(`${baseUrl}/api/tags`);
+      
+      if (!response.ok) {
+        throw new Error(`Health check returned ${response.status}`);
+      }
+
+      const data = await response.json() as Record<string, unknown>;
+      const models = (data.models as Array<{ name: string }>) || [];
+      const hasModel = models.some((m) => m.name === config.model);
+
+      return {
+        healthy: true,
+        provider: 'ollama',
+        capabilities: {
+          model: config.model,
+          available: hasModel,
+          totalModels: models.length,
+        },
+        timestamp,
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        provider: 'ollama',
+        error: `Connection failed: ${error instanceof Error ? error.message : String(error)}`,
+        timestamp,
+      };
+    }
+  }
+
+  private static async checkLLMRestAPI(config: LLMConfig, timestamp: number): Promise<HealthCheckResult> {
+    const baseUrlRaw = config.baseUrl || (config.options as Record<string, unknown>)?.baseUrl;
+    const baseUrl = (typeof baseUrlRaw === 'string' ? baseUrlRaw : '').replace(/\/$/, '');
+
+    if (!baseUrl) {
+      return {
+        healthy: false,
+        provider: config.provider,
+        error: 'baseUrl is required',
+        timestamp,
+      };
+    }
+
+    try {
+      const headers = (config.options as Record<string, unknown>)?.headers as Record<string, string> | undefined;
+      const response = await fetch(`${baseUrl}/health`, {
+        headers: headers || undefined,
+      });
+
+      return {
+        healthy: response.ok,
+        provider: config.provider,
+        error: response.ok ? undefined : `Health check returned ${response.status}`,
+        timestamp,
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        provider: config.provider,
+        error: `Connection failed: ${error instanceof Error ? error.message : String(error)}`,
+        timestamp,
+      };
+    }
+  }
+
+  /**
+   * Runs comprehensive health checks on all configured providers.
+   */
+  static async checkAll(
+    vectorDbConfig: VectorDBConfig,
+    llmConfig: LLMConfig,
+    embeddingConfig?: EmbeddingConfig
+  ): Promise<{
+    vectorDb: HealthCheckResult;
+    llm: HealthCheckResult;
+    embedding?: HealthCheckResult;
+    allHealthy: boolean;
+  }> {
+    const [vectorDb, llm, embedding] = await Promise.all([
+      this.checkVectorProvider(vectorDbConfig),
+      this.checkLLMProvider(llmConfig),
+      embeddingConfig ? this.checkLLMProvider(embeddingConfig as LLMConfig) : Promise.resolve(undefined),
+    ]);
+
+    return {
+      vectorDb,
+      llm,
+      embedding,
+      allHealthy: vectorDb.healthy && llm.healthy && (!embedding || embedding.healthy),
+    };
+  }
+}

package/src/core/VectorPlugin.ts

@@ -1,12 +1,21 @@
 import { RagConfig } from '../config/RagConfig';
 import { ConfigResolver } from './ConfigResolver';
+import { ConfigValidator } from './ConfigValidator';
 import { Pipeline } from './Pipeline';
+import { ProviderHealthCheck, HealthCheckResult } from './ProviderHealthCheck';
 import { IngestDocument, ChatResponse } from '../types';
 import { ChatMessage } from '../llm/ILLMProvider';
 
 /**
  * VectorPlugin — main orchestrator class.
  * This is the primary interface for host applications.
+ *
+ * Features:
+ * - Configuration resolution from host + environment
+ * - Configuration validation with detailed error messages
+ * - Provider health checks before initialization
+ * - Multi-provider support (Vector DBs & LLMs)
+ * - Per-tenant data isolation via namespacing
  */
 export class VectorPlugin {
   private config: RagConfig;
@@ -15,10 +24,29 @@ export class VectorPlugin {
   /**
    * Initializes the plugin with the host configuration.
    * @param hostConfig - Configuration object passed from the host application.
+   * @throws Error if configuration is invalid or providers are unhealthy
+   *
+   * @example
+   * const plugin = new VectorPlugin({
+   *   projectId: 'my-app',
+   *   vectorDb: {
+   *     provider: 'pinecone',
+   *     indexName: 'my-index',
+   *     options: { apiKey: process.env.PINECONE_API_KEY }
+   *   },
+   *   llm: {
+   *     provider: 'openai',
+   *     model: 'gpt-4o',
+   *     apiKey: process.env.OPENAI_API_KEY
+   *   }
+   * });
    */
   constructor(hostConfig?: Partial<RagConfig>) {
     this.config = ConfigResolver.resolve(hostConfig);
-    ConfigResolver.validate(this.config);
+    
+    // Validate configuration early with detailed error messages
+    ConfigValidator.validateAndThrow(this.config);
+    
     this.pipeline = new Pipeline(this.config);
   }
 
@@ -29,6 +57,25 @@ export class VectorPlugin {
     return this.config;
   }
 
+  /**
+   * Perform pre-flight health checks on all configured providers.
+   * Useful to verify connectivity before running operations.
+   *
+   * @returns Health status for vector DB, LLM, and embedding providers
+   */
+  async checkHealth(): Promise<{
+    vectorDb: HealthCheckResult;
+    llm: HealthCheckResult;
+    embedding?: HealthCheckResult;
+    allHealthy: boolean;
+  }> {
+    return ProviderHealthCheck.checkAll(
+      this.config.vectorDb,
+      this.config.llm,
+      this.config.embedding
+    );
+  }
+
   /**
    * Run a chat query.
    */
@@ -39,14 +86,8 @@ export class VectorPlugin {
   /**
    * Ingest documents into the vector database.
    */
-  async ingest(documents: IngestDocument[], namespace?: string): Promise<Array<{ docId: string; chunksIngested: number }>> {
+  async ingest(documents: IngestDocument[], namespace?: string): Promise<Array<{ docId: string | number; chunksIngested: number }>> {
     return this.pipeline.ingest(documents, namespace);
   }
 
-  /**
-   * Check the health of the connected providers.
-   */
-  async health(): Promise<Record<string, boolean>> {
-    return this.pipeline.health();
-  }
 }

package/src/handlers/index.ts

@@ -67,8 +67,8 @@ export function createHealthHandler(config?: Partial<RagConfig>) {
 
   return async function GET() {
     try {
-      const health = await plugin.health();
-      const status = health.vectorDB && health.llm ? 'ok' : 'degraded';
+      const health = await plugin.checkHealth();
+      const status = health.allHealthy ? 'ok' : 'degraded';
       return NextResponse.json({
         status,
         ...health,

package/src/providers/vectordb/BaseVectorProvider.ts

@@ -42,7 +42,7 @@ export abstract class BaseVectorProvider {
   /**
    * Delete a stored vector by ID.
    */
-  abstract delete(id: string, namespace?: string): Promise<void>;
+  abstract delete(id: string | number, namespace?: string): Promise<void>;
 
   /**
    * Delete all vectors in a namespace (full data reset for a project).

package/src/providers/vectordb/MilvusProvider.ts

@@ -74,7 +74,7 @@ export class MilvusProvider extends BaseVectorProvider {
   }
 
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async delete(id: string, _namespace?: string): Promise<void> {
+  async delete(id: string | number, _namespace?: string): Promise<void> {
     await this.http.post('/v1/vector/delete', {
       collectionName: this.indexName,
       id: id,

package/src/providers/vectordb/MongoDBProvider.ts

@@ -95,7 +95,7 @@ export class MongoDBProvider extends BaseVectorProvider {
     }));
   }
 
-  async delete(id: string, namespace?: string): Promise<void> {
+  async delete(id: string | number, namespace?: string): Promise<void> {
     await this.collection!.deleteOne({ _id: id, ...(namespace ? { namespace } : {}) });
   }