@retrivora-ai/rag-engine 0.1.5 → 0.1.7

package/dist/server.js

@@ -557,7 +557,7 @@ var init_PineconeProvider = __esm({
         var _a;
         await this.index(namespace).upsert({
           records: [{
-            id: doc.id,
+            id: String(doc.id),
             values: doc.vector,
             metadata: __spreadValues({ content: doc.content }, (_a = doc.metadata) != null ? _a : {})
           }]
@@ -569,7 +569,7 @@ var init_PineconeProvider = __esm({
           const records = docs.slice(i, i + BATCH).map((d) => {
             var _a;
             return {
-              id: d.id,
+              id: String(d.id),
               values: d.vector,
               metadata: __spreadValues({ content: d.content }, (_a = d.metadata) != null ? _a : {})
             };
@@ -595,7 +595,7 @@ var init_PineconeProvider = __esm({
         });
       }
       async delete(id, namespace) {
-        await this.index(namespace).deleteOne({ id });
+        await this.index(namespace).deleteOne({ id: String(id) });
       }
       async deleteNamespace(namespace) {
         await this.client.index(this.indexName).namespace(namespace).deleteAll();
@@ -673,8 +673,37 @@ var init_PostgreSQLProvider = __esm({
         );
       }
       async batchUpsert(docs, namespace = "") {
-        for (const doc of docs) {
-          await this.upsert(doc, namespace);
+        if (docs.length === 0) return;
+        const client = await this.pool.connect();
+        try {
+          await client.query("BEGIN");
+          const BATCH_SIZE = 50;
+          for (let i = 0; i < docs.length; i += BATCH_SIZE) {
+            const batch = docs.slice(i, i + BATCH_SIZE);
+            const values = [];
+            const valuePlaceholders = batch.map((doc, idx) => {
+              var _a;
+              const offset = idx * 5;
+              values.push(doc.id, namespace, doc.content, JSON.stringify((_a = doc.metadata) != null ? _a : {}), `[${doc.vector.join(",")}]`);
+              return `($${offset + 1}, $${offset + 2}, $${offset + 3}, $${offset + 4}, $${offset + 5}::vector)`;
+            }).join(", ");
+            const query = `
+          INSERT INTO ${this.tableName} (id, namespace, content, metadata, embedding)
+          VALUES ${valuePlaceholders}
+          ON CONFLICT (id) DO UPDATE
+            SET namespace = EXCLUDED.namespace,
+                content   = EXCLUDED.content,
+                metadata  = EXCLUDED.metadata,
+                embedding = EXCLUDED.embedding
+        `;
+            await client.query(query, values);
+          }
+          await client.query("COMMIT");
+        } catch (error) {
+          await client.query("ROLLBACK");
+          throw error;
+        } finally {
+          client.release();
         }
       }
       async query(vector, topK, namespace, filter) {
@@ -926,11 +955,12 @@ var QdrantProvider_exports = {};
 __export(QdrantProvider_exports, {
   QdrantProvider: () => QdrantProvider
 });
-var import_axios4, QdrantProvider;
+var import_axios4, import_crypto, QdrantProvider;
 var init_QdrantProvider = __esm({
   "src/providers/vectordb/QdrantProvider.ts"() {
     "use strict";
     import_axios4 = __toESM(require("axios"));
+    import_crypto = __toESM(require("crypto"));
     init_BaseVectorProvider();
     QdrantProvider = class extends BaseVectorProvider {
       constructor(config) {
@@ -947,6 +977,61 @@ var init_QdrantProvider = __esm({
       }
       async initialize() {
         await this.ping();
+        await this.ensureCollection();
+        await this.ensureIndex();
+      }
+      /**
+       * Ensures the collection exists. Creates it if missing.
+       */
+      async ensureCollection() {
+        var _a;
+        try {
+          const opts = this.config.options;
+          const dimensions = opts.dimensions || 1536;
+          await this.http.get(`/collections/${this.indexName}`);
+          console.log(`[QdrantProvider] \u2705 Collection "${this.indexName}" already exists.`);
+        } catch (err) {
+          if (import_axios4.default.isAxiosError(err) && ((_a = err.response) == null ? void 0 : _a.status) === 404) {
+            const opts = this.config.options;
+            const dimensions = opts.dimensions || 1536;
+            console.log(`[QdrantProvider] \u23F3 Creating collection "${this.indexName}" (dimensions: ${dimensions})...`);
+            await this.http.put(`/collections/${this.indexName}`, {
+              vectors: {
+                size: dimensions,
+                distance: "Cosine"
+              }
+            });
+            console.log(`[QdrantProvider] \u2705 Created collection "${this.indexName}"`);
+          } else {
+            throw err;
+          }
+        }
+      }
+      /**
+       * Ensures that the 'namespace' field has a keyword index for efficient filtering.
+       * Qdrant requires this for search filters to work in many configurations.
+       */
+      async ensureIndex() {
+        var _a, _b;
+        try {
+          await this.http.put(`/collections/${this.indexName}/index`, {
+            field_name: "namespace",
+            field_schema: "keyword"
+          });
+          console.log(`[QdrantProvider] \u2705 Ensured keyword index for "namespace" on collection "${this.indexName}"`);
+        } catch (err) {
+          let status;
+          let data;
+          if (import_axios4.default.isAxiosError(err)) {
+            status = (_a = err.response) == null ? void 0 : _a.status;
+            data = (_b = err.response) == null ? void 0 : _b.data;
+          }
+          if (status === 409) {
+            return;
+          }
+          const errorMessage = err instanceof Error ? err.message : String(err);
+          console.warn(`[QdrantProvider] \u26A0\uFE0F Could not ensure namespace index (Status: ${status}):`, JSON.stringify(data || errorMessage));
+        }
       }
       async upsert(doc, namespace) {
         await this.batchUpsert([doc], namespace);
@@ -954,7 +1039,7 @@ var init_QdrantProvider = __esm({
       async batchUpsert(docs, namespace) {
         const payload = {
           points: docs.map((doc) => ({
-            id: doc.id,
+            id: this.normalizeId(doc.id),
             vector: doc.vector,
             payload: __spreadValues({
               content: doc.content,
@@ -988,10 +1073,9 @@ var init_QdrantProvider = __esm({
       // eslint-disable-next-line @typescript-eslint/no-unused-vars
       async delete(id, _namespace) {
         await this.http.post(`/collections/${this.indexName}/points/delete`, {
-          points: [id]
+          points: [this.normalizeId(id)]
         });
       }
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       async deleteNamespace(_namespace) {
         await this.http.post(`/collections/${this.indexName}/points/delete`, {
           filter: {
@@ -1007,6 +1091,17 @@ var init_QdrantProvider = __esm({
           return false;
         }
       }
+      /**
+       * Normalizes an ID into a format Qdrant accepts (UUID or integer).
+       * For string IDs that aren't UUIDs, it generates a deterministic UUID v5-like hash.
+       */
+      normalizeId(id) {
+        if (typeof id === "number") return id;
+        const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+        if (uuidRegex.test(id)) return id.toLowerCase();
+        const hash = import_crypto.default.createHash("md5").update(id).digest("hex");
+        return `${hash.slice(0, 8)}-${hash.slice(8, 12)}-${hash.slice(12, 16)}-${hash.slice(16, 20)}-${hash.slice(20, 32)}`;
+      }
       async disconnect() {
       }
     };
@@ -1353,7 +1448,7 @@ function readEnum(env, name, fallback, allowed) {
   throw new Error(`[getRagConfig] ${name} must be one of: ${allowed.join(", ")}`);
 }
 function getRagConfig(env = process.env) {
-  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _A, _B, _C, _D, _E, _F, _G, _H, _I, _J;
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _A, _B, _C, _D, _E, _F, _G, _H, _I, _J, _K;
   const projectId = (_b = (_a = readString(env, "RAG_PROJECT_ID")) != null ? _a : readString(env, "NEXT_PUBLIC_PROJECT_ID")) != null ? _b : "__default__";
   const vectorProvider = readEnum(env, "VECTOR_DB_PROVIDER", "pinecone", VECTOR_DB_PROVIDERS);
   const llmProvider = readEnum(env, "LLM_PROVIDER", "openai", LLM_PROVIDERS);
@@ -1378,6 +1473,10 @@ function getRagConfig(env = process.env) {
     vectorDbOptions.database = (_j = readString(env, "MONGODB_DB")) != null ? _j : "";
     vectorDbOptions.collection = (_k = readString(env, "MONGODB_COLLECTION")) != null ? _k : "";
     vectorDbOptions.indexName = (_l = readString(env, "MONGODB_INDEX_NAME")) != null ? _l : "vector_index";
+  } else if (vectorProvider === "qdrant") {
+    vectorDbOptions.baseUrl = (_m = readString(env, "QDRANT_URL")) != null ? _m : "http://localhost:6333";
+    vectorDbOptions.apiKey = readString(env, "QDRANT_API_KEY");
+    vectorDbOptions.dimensions = embeddingDimensions;
   }
   const llmApiKeyByProvider = {
     openai: readString(env, "OPENAI_API_KEY"),
@@ -1388,19 +1487,19 @@ function getRagConfig(env = process.env) {
   const embeddingApiKeyByProvider = {
     openai: readString(env, "OPENAI_API_KEY"),
     ollama: void 0,
-    custom: (_m = readString(env, "EMBEDDING_API_KEY")) != null ? _m : readString(env, "OPENAI_API_KEY")
+    custom: (_n = readString(env, "EMBEDDING_API_KEY")) != null ? _n : readString(env, "OPENAI_API_KEY")
   };
   return {
     projectId,
     vectorDb: {
       provider: vectorProvider,
-      indexName: (_n = readString(env, "VECTOR_DB_INDEX")) != null ? _n : "rag-index",
+      indexName: (_o = readString(env, "VECTOR_DB_INDEX")) != null ? _o : "rag-index",
       options: vectorDbOptions
     },
     llm: {
       provider: llmProvider,
-      model: (_o = readString(env, "LLM_MODEL")) != null ? _o : "gpt-4o",
-      apiKey: (_p = llmApiKeyByProvider[llmProvider]) != null ? _p : "",
+      model: (_p = readString(env, "LLM_MODEL")) != null ? _p : "gpt-4o",
+      apiKey: (_q = llmApiKeyByProvider[llmProvider]) != null ? _q : "",
       baseUrl: readString(env, "LLM_BASE_URL"),
       systemPrompt: readString(env, "LLM_SYSTEM_PROMPT"),
       maxTokens: readNumber(env, "LLM_MAX_TOKENS", 1024),
@@ -1411,7 +1510,7 @@ function getRagConfig(env = process.env) {
     },
     embedding: {
       provider: embeddingProvider,
-      model: (_q = readString(env, "EMBEDDING_MODEL")) != null ? _q : "text-embedding-3-small",
+      model: (_r = readString(env, "EMBEDDING_MODEL")) != null ? _r : "text-embedding-3-small",
       apiKey: embeddingApiKeyByProvider[embeddingProvider],
       baseUrl: readString(env, "EMBEDDING_BASE_URL"),
       dimensions: embeddingDimensions,
@@ -1420,16 +1519,16 @@ function getRagConfig(env = process.env) {
       }
     },
     ui: {
-      title: (_s = (_r = readString(env, "NEXT_PUBLIC_UI_TITLE")) != null ? _r : readString(env, "UI_TITLE")) != null ? _s : "AI Assistant",
-      subtitle: (_u = (_t = readString(env, "NEXT_PUBLIC_UI_SUBTITLE")) != null ? _t : readString(env, "UI_SUBTITLE")) != null ? _u : "Powered by RAG",
-      primaryColor: (_w = (_v = readString(env, "NEXT_PUBLIC_PRIMARY_COLOR")) != null ? _v : readString(env, "UI_PRIMARY_COLOR")) != null ? _w : "#10b981",
-      accentColor: (_y = (_x = readString(env, "NEXT_PUBLIC_ACCENT_COLOR")) != null ? _x : readString(env, "UI_ACCENT_COLOR")) != null ? _y : "#3b82f6",
-      logoUrl: (_z = readString(env, "NEXT_PUBLIC_LOGO_URL")) != null ? _z : readString(env, "UI_LOGO_URL"),
-      placeholder: (_B = (_A = readString(env, "NEXT_PUBLIC_PLACEHOLDER")) != null ? _A : readString(env, "UI_PLACEHOLDER")) != null ? _B : "Ask me anything\u2026",
-      showSources: ((_D = (_C = readString(env, "NEXT_PUBLIC_SHOW_SOURCES")) != null ? _C : readString(env, "UI_SHOW_SOURCES")) != null ? _D : "true") !== "false",
-      welcomeMessage: (_F = (_E = readString(env, "NEXT_PUBLIC_WELCOME_MESSAGE")) != null ? _E : readString(env, "UI_WELCOME_MESSAGE")) != null ? _F : "Hello! I'm your AI assistant. Ask me anything about your documents.",
-      visualStyle: (_H = (_G = readString(env, "NEXT_PUBLIC_UI_VISUAL_STYLE")) != null ? _G : readString(env, "UI_VISUAL_STYLE")) != null ? _H : "glass",
-      borderRadius: (_J = (_I = readString(env, "NEXT_PUBLIC_UI_BORDER_RADIUS")) != null ? _I : readString(env, "UI_BORDER_RADIUS")) != null ? _J : "xl"
+      title: (_t = (_s = readString(env, "NEXT_PUBLIC_UI_TITLE")) != null ? _s : readString(env, "UI_TITLE")) != null ? _t : "AI Assistant",
+      subtitle: (_v = (_u = readString(env, "NEXT_PUBLIC_UI_SUBTITLE")) != null ? _u : readString(env, "UI_SUBTITLE")) != null ? _v : "Powered by RAG",
+      primaryColor: (_x = (_w = readString(env, "NEXT_PUBLIC_PRIMARY_COLOR")) != null ? _w : readString(env, "UI_PRIMARY_COLOR")) != null ? _x : "#10b981",
+      accentColor: (_z = (_y = readString(env, "NEXT_PUBLIC_ACCENT_COLOR")) != null ? _y : readString(env, "UI_ACCENT_COLOR")) != null ? _z : "#3b82f6",
+      logoUrl: (_A = readString(env, "NEXT_PUBLIC_LOGO_URL")) != null ? _A : readString(env, "UI_LOGO_URL"),
+      placeholder: (_C = (_B = readString(env, "NEXT_PUBLIC_PLACEHOLDER")) != null ? _B : readString(env, "UI_PLACEHOLDER")) != null ? _C : "Ask me anything\u2026",
+      showSources: ((_E = (_D = readString(env, "NEXT_PUBLIC_SHOW_SOURCES")) != null ? _D : readString(env, "UI_SHOW_SOURCES")) != null ? _E : "true") !== "false",
+      welcomeMessage: (_G = (_F = readString(env, "NEXT_PUBLIC_WELCOME_MESSAGE")) != null ? _F : readString(env, "UI_WELCOME_MESSAGE")) != null ? _G : "Hello! I'm your AI assistant. Ask me anything about your documents.",
+      visualStyle: (_I = (_H = readString(env, "NEXT_PUBLIC_UI_VISUAL_STYLE")) != null ? _H : readString(env, "UI_VISUAL_STYLE")) != null ? _I : "glass",
+      borderRadius: (_K = (_J = readString(env, "NEXT_PUBLIC_UI_BORDER_RADIUS")) != null ? _J : readString(env, "UI_BORDER_RADIUS")) != null ? _K : "xl"
     },
     rag: {
       topK: readNumber(env, "RAG_TOP_K", 5),
@@ -1482,6 +1581,467 @@ var ConfigResolver = class {
   }
 };
 
+// src/core/ConfigValidator.ts
+var ConfigValidator = class {
+  /**
+   * Validates the entire RagConfig object.
+   * Returns an array of validation errors. Empty array = valid config.
+   */
+  static validate(config) {
+    const errors = [];
+    if (!config.projectId) {
+      errors.push({
+        field: "projectId",
+        message: "projectId is required",
+        severity: "error"
+      });
+    }
+    errors.push(...this.validateVectorDbConfig(config.vectorDb));
+    errors.push(...this.validateLLMConfig(config.llm));
+    if (config.embedding) {
+      errors.push(...this.validateEmbeddingConfig(config.embedding));
+    } else if (config.llm.provider === "anthropic") {
+      errors.push({
+        field: "embedding",
+        message: "Embedding config is required when using Anthropic LLM",
+        suggestion: 'Provide embedding config with provider (e.g., "openai")',
+        severity: "error"
+      });
+    }
+    if (config.ui) {
+      errors.push(...this.validateUIConfig(config.ui));
+    }
+    if (config.rag) {
+      errors.push(...this.validateRAGConfig(config.rag));
+    }
+    return errors;
+  }
+  static validateVectorDbConfig(config) {
+    const errors = [];
+    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"
+      });
+    }
+    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;
+  }
+  static validatePineconeConfig(config) {
+    const errors = [];
+    const opts = config.options;
+    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;
+  }
+  static validatePostgresConfig(config) {
+    const errors = [];
+    const opts = config.options;
+    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;
+  }
+  static validateMongoDBConfig(config) {
+    const errors = [];
+    const opts = config.options;
+    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;
+  }
+  static validateMilvusConfig(config) {
+    const errors = [];
+    const opts = config.options;
+    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;
+  }
+  static validateQdrantConfig(config) {
+    const errors = [];
+    const opts = config.options;
+    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;
+  }
+  static validateChromaDBConfig(config) {
+    const errors = [];
+    const opts = config.options;
+    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;
+  }
+  static validateRedisConfig(config) {
+    const errors = [];
+    const opts = config.options;
+    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;
+  }
+  static validateWeaviateConfig(config) {
+    const errors = [];
+    const opts = config.options;
+    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;
+  }
+  static validateRestConfig(config) {
+    const errors = [];
+    const opts = config.options;
+    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;
+  }
+  static validateLLMConfig(config) {
+    var _a;
+    const errors = [];
+    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"
+      });
+    }
+    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 && !((_a = config.options) == null ? void 0 : _a.baseUrl)) {
+          errors.push({
+            field: "llm.baseUrl",
+            message: "REST API base URL is required",
+            suggestion: "Set LLM_BASE_URL environment variable",
+            severity: "error"
+          });
+        }
+        break;
+    }
+    if (config.temperature !== void 0) {
+      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 !== void 0 && config.maxTokens <= 0) {
+      errors.push({
+        field: "llm.maxTokens",
+        message: "maxTokens must be greater than 0",
+        severity: "error"
+      });
+    }
+    return errors;
+  }
+  static validateEmbeddingConfig(config) {
+    const errors = [];
+    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"
+      });
+    }
+    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"
+      });
+    }
+    if (config.dimensions !== void 0 && config.dimensions <= 0) {
+      errors.push({
+        field: "embedding.dimensions",
+        message: "Embedding dimensions must be greater than 0",
+        severity: "error"
+      });
+    }
+    return errors;
+  }
+  static validateUIConfig(config) {
+    const errors = [];
+    if (config.primaryColor) {
+      if (!this.isValidCSSColor(config.primaryColor)) {
+        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)) {
+        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)) {
+        errors.push({
+          field: "ui.visualStyle",
+          message: `visualStyle must be one of: ${validValues.join(", ")}`,
+          severity: "warning"
+        });
+      }
+    }
+    return errors;
+  }
+  static validateRAGConfig(config) {
+    const errors = [];
+    if (config.topK !== void 0) {
+      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 !== void 0) {
+      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 !== void 0) {
+      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 !== void 0) {
+      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;
+  }
+  static isValidCSSColor(color) {
+    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());
+  }
+  /**
+   * Throws if there are error-level validation issues.
+   * Logs warnings to console.
+   */
+  static validateAndThrow(config) {
+    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:
+  ${message}`);
+    }
+  }
+};
+
 // src/rag/DocumentChunker.ts
 var DocumentChunker = class {
   constructor(chunkSize = 1e3, chunkOverlap = 200) {
@@ -1597,6 +2157,230 @@ var ProviderRegistry = class {
 };
 ProviderRegistry.vectorProviders = {};
 
+// src/core/BatchProcessor.ts
+function isTransientError(error) {
+  if (!(error instanceof Error)) return false;
+  const message = error.message.toLowerCase();
+  if (message.includes("econnrefused") || message.includes("econnreset") || message.includes("timeout") || message.includes("network") || message.includes("socket")) {
+    return true;
+  }
+  if (message.includes("429") || message.includes("503") || message.includes("502") || message.includes("rate limit") || message.includes("too many requests")) {
+    return true;
+  }
+  return false;
+}
+function calculateBackoffDelay(attempt, initialDelayMs, maxDelayMs, multiplier) {
+  const exponentialDelay = Math.min(
+    initialDelayMs * Math.pow(multiplier, attempt),
+    maxDelayMs
+  );
+  const jitter = exponentialDelay * 0.1 * (Math.random() * 2 - 1);
+  return Math.max(0, exponentialDelay + jitter);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var BatchProcessor = class {
+  /**
+   * Processes an array of items in configurable batches with retry logic.
+   *
+   * @param items - Items to process
+   * @param processor - Async function that processes a batch of items
+   * @param options - Configuration for batch size, retries, etc.
+   * @returns Object with results, errors, and statistics
+   *
+   * @example
+   * const docs = [...];
+   * const result = await BatchProcessor.processBatch(
+   *   docs,
+   *   (batch) => vectorDB.batchUpsert(batch),
+   *   { batchSize: 100, maxRetries: 3 }
+   * );
+   */
+  static async processBatch(items, processor, options) {
+    const {
+      batchSize = 100,
+      maxRetries = 3,
+      initialDelayMs = 100,
+      maxDelayMs = 1e4,
+      backoffMultiplier = 2,
+      throwOnPartialFailure = false
+    } = options != null ? options : {};
+    const results = [];
+    const errors = [];
+    const batches = [];
+    for (let i = 0; i < items.length; i += batchSize) {
+      batches.push(items.slice(i, i + batchSize));
+    }
+    if (batches.length === 0) {
+      return { results: [], errors: [], totalProcessed: 0, totalFailed: 0 };
+    }
+    for (let batchIndex = 0; batchIndex < batches.length; batchIndex++) {
+      const batch = batches[batchIndex];
+      let success = false;
+      let lastError;
+      for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+          const result = await processor(batch);
+          results.push(result);
+          success = true;
+          break;
+        } catch (err) {
+          lastError = err instanceof Error ? err : new Error(String(err));
+          if (!isTransientError(err) || attempt === maxRetries) {
+            break;
+          }
+          const delay = calculateBackoffDelay(
+            attempt,
+            initialDelayMs,
+            maxDelayMs,
+            backoffMultiplier
+          );
+          await sleep(delay);
+        }
+      }
+      if (!success && lastError) {
+        errors.push({
+          index: batchIndex,
+          error: lastError,
+          itemCount: batch.length
+        });
+      }
+    }
+    const totalProcessed = items.length - (errors.length > 0 ? errors.reduce((sum, e) => sum + (e.itemCount || 0), 0) : 0);
+    const totalFailed = errors.reduce((sum, e) => sum + (e.itemCount || 0), 0);
+    if (throwOnPartialFailure && errors.length > 0) {
+      const errorMessages = errors.map((e) => `Batch ${e.index} (${e.itemCount} items): ${e.error.message}`).join("\n");
+      throw new Error(
+        `[BatchProcessor] Batch processing failed:
+${errorMessages}`
+      );
+    }
+    return { results, errors, totalProcessed, totalFailed };
+  }
+  /**
+   * Processes items sequentially (one at a time) with retry logic.
+   * Useful for operations that don't support batching or when granular
+   * error tracking is needed.
+   */
+  static async processSequential(items, processor, options) {
+    const {
+      maxRetries = 3,
+      initialDelayMs = 100,
+      maxDelayMs = 1e4,
+      backoffMultiplier = 2,
+      throwOnPartialFailure = false
+    } = options != null ? options : {};
+    const results = [];
+    const errors = [];
+    for (let itemIndex = 0; itemIndex < items.length; itemIndex++) {
+      const item = items[itemIndex];
+      let success = false;
+      let lastError;
+      for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+          const result = await processor(item);
+          results.push(result);
+          success = true;
+          break;
+        } catch (err) {
+          lastError = err instanceof Error ? err : new Error(String(err));
+          if (!isTransientError(err) || attempt === maxRetries) {
+            break;
+          }
+          const delay = calculateBackoffDelay(
+            attempt,
+            initialDelayMs,
+            maxDelayMs,
+            backoffMultiplier
+          );
+          await sleep(delay);
+        }
+      }
+      if (!success && lastError) {
+        errors.push({ index: itemIndex, error: lastError, itemCount: 1 });
+      }
+    }
+    const totalProcessed = items.length - errors.length;
+    const totalFailed = errors.length;
+    if (throwOnPartialFailure && errors.length > 0) {
+      const errorMessages = errors.map((e) => `Item ${e.index}: ${e.error.message}`).join("\n");
+      throw new Error(
+        `[BatchProcessor] Sequential processing failed:
+${errorMessages}`
+      );
+    }
+    return { results, errors, totalProcessed, totalFailed };
+  }
+  /**
+   * Maps over items with retry logic, returning results in order.
+   * Like Array.map() but with async processing and automatic retries.
+   */
+  static async mapWithRetry(items, mapper, options) {
+    const result = await this.processSequential(items, mapper, options);
+    if (result.errors.length > 0) {
+      console.warn(
+        `[BatchProcessor] mapWithRetry: ${result.errors.length} items failed`
+      );
+    }
+    const orderedResults = new Array(items.length);
+    let resultIndex = 0;
+    let errorIndex = 0;
+    for (let i = 0; i < items.length; i++) {
+      if (errorIndex < result.errors.length && result.errors[errorIndex].index === i) {
+        orderedResults[i] = void 0;
+        errorIndex++;
+      } else {
+        orderedResults[i] = result.results[resultIndex];
+        resultIndex++;
+      }
+    }
+    return orderedResults.filter((r) => r !== void 0);
+  }
+  /**
+   * Parallel processor with concurrency limit.
+   * Processes up to `concurrency` items at the same time.
+   */
+  static async processConcurrent(items, processor, concurrency = 5, options) {
+    const { throwOnPartialFailure = false } = options != null ? options : {};
+    const results = [];
+    const errors = [];
+    for (let i = 0; i < items.length; i += concurrency) {
+      const chunk = items.slice(i, i + concurrency).map((item, idx) => ({
+        item,
+        originalIndex: i + idx
+      }));
+      const chunkPromises = chunk.map(async ({ item, originalIndex }) => {
+        try {
+          const result = await processor(item);
+          return { success: true, result, index: originalIndex };
+        } catch (err) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          return { success: false, error, index: originalIndex };
+        }
+      });
+      const chunkResults = await Promise.all(chunkPromises);
+      for (const { success, result, error, index } of chunkResults) {
+        if (success) {
+          results.push(result);
+        } else {
+          errors.push({ index, error, itemCount: 1 });
+        }
+      }
+    }
+    const totalProcessed = items.length - errors.length;
+    const totalFailed = errors.length;
+    if (throwOnPartialFailure && errors.length > 0) {
+      const errorMessages = errors.map((e) => `Item ${e.index}: ${e.error.message}`).join("\n");
+      throw new Error(
+        `[BatchProcessor] Concurrent processing failed:
+${errorMessages}`
+      );
+    }
+    return { results, errors, totalProcessed, totalFailed };
+  }
+};
+
 // src/core/Pipeline.ts
 var Pipeline = class {
   constructor(config) {
@@ -1621,24 +2405,64 @@ var Pipeline = class {
     await this.vectorDB.initialize();
     this.initialised = true;
   }
+  /**
+   * Ingest documents with automatic chunking, embedding, and batch processing.
+   * Handles retries for transient failures.
+   */
   async ingest(documents, namespace) {
     await this.initialize();
     const ns = namespace != null ? namespace : this.config.projectId;
     const results = [];
     for (const doc of documents) {
-      const chunks = this.chunker.chunk(doc.content, {
-        docId: doc.docId,
-        metadata: doc.metadata
-      });
-      const vectors = await this.embeddingProvider.batchEmbed(chunks.map((c) => c.content));
-      const upsertDocs = chunks.map((chunk, i) => ({
-        id: chunk.id,
-        vector: vectors[i],
-        content: chunk.content,
-        metadata: chunk.metadata
-      }));
-      await this.vectorDB.batchUpsert(upsertDocs, ns);
-      results.push({ docId: doc.docId, chunksIngested: chunks.length });
+      try {
+        const chunks = this.chunker.chunk(doc.content, {
+          docId: doc.docId,
+          metadata: doc.metadata
+        });
+        const batchOptions = {
+          batchSize: 50,
+          // Embedding batch size
+          maxRetries: 3,
+          initialDelayMs: 100
+        };
+        const vectors = await BatchProcessor.mapWithRetry(
+          chunks.map((c) => c.content),
+          (text) => this.embeddingProvider.embed(text),
+          batchOptions
+        );
+        if (vectors.length !== chunks.length) {
+          throw new Error(`Embedding failed: got ${vectors.length} vectors for ${chunks.length} chunks`);
+        }
+        const upsertDocs = chunks.map((chunk, i) => ({
+          id: chunk.id,
+          vector: vectors[i],
+          content: chunk.content,
+          metadata: chunk.metadata
+        }));
+        const upsertBatchOptions = {
+          batchSize: 100,
+          maxRetries: 3,
+          initialDelayMs: 100
+        };
+        const upsertResult = await BatchProcessor.processBatch(
+          upsertDocs,
+          (batch) => this.vectorDB.batchUpsert(batch, ns),
+          upsertBatchOptions
+        );
+        if (upsertResult.errors.length > 0) {
+          console.warn(`[Pipeline] Ingestion: ${upsertResult.errors.length} batches failed for doc ${doc.docId}`);
+        }
+        results.push({
+          docId: doc.docId,
+          chunksIngested: upsertResult.totalProcessed
+        });
+      } catch (error) {
+        console.error(`[Pipeline] Failed to ingest document ${doc.docId}:`, error);
+        results.push({
+          docId: doc.docId,
+          chunksIngested: 0
+        });
+      }
     }
     return results;
   }
@@ -1648,22 +2472,486 @@ var Pipeline = class {
     const ns = namespace != null ? namespace : this.config.projectId;
     const topK = (_b = (_a = this.config.rag) == null ? void 0 : _a.topK) != null ? _b : 5;
     const scoreThreshold = (_d = (_c = this.config.rag) == null ? void 0 : _c.scoreThreshold) != null ? _d : 0;
-    const queryVector = await this.embeddingProvider.embed(question);
-    const rawMatches = await this.vectorDB.query(queryVector, topK, ns);
-    const sources = rawMatches.filter((m) => m.score >= scoreThreshold);
-    const context = sources.length ? sources.map((m, i) => `[Source ${i + 1}]
+    try {
+      const queryVector = await this.embeddingProvider.embed(question);
+      const rawMatches = await this.vectorDB.query(queryVector, topK, ns);
+      const sources = rawMatches.filter((m) => m.score >= scoreThreshold);
+      const context = sources.length ? sources.map((m, i) => `[Source ${i + 1}]
 ${m.content}`).join("\n\n---\n\n") : "No relevant context found.";
-    const messages = [...history, { role: "user", content: question }];
-    const reply = await this.llmProvider.chat(messages, context);
-    return { reply, sources };
+      const messages = [...history, { role: "user", content: question }];
+      const reply = await this.llmProvider.chat(messages, context);
+      return { reply, sources };
+    } catch (error) {
+      throw new Error(`[Pipeline] Chat failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
   }
-  async health() {
-    await this.initialize();
-    const [vectorDB, llm] = await Promise.all([
-      this.vectorDB.ping().catch(() => false),
-      this.llmProvider.ping().catch(() => false)
+};
+
+// src/core/ProviderHealthCheck.ts
+var ProviderHealthCheck = class {
+  /**
+   * Validates vector database configuration before initialization.
+   * Performs connectivity checks and verifies required resources exist.
+   */
+  static async checkVectorProvider(config) {
+    const timestamp = Date.now();
+    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
+      };
+    }
+  }
+  static async checkPinecone(config, timestamp) {
+    var _a, _b;
+    const opts = config.options;
+    try {
+      const { Pinecone: Pinecone2 } = await import("@pinecone-database/pinecone");
+      const client = new Pinecone2({ apiKey: opts.apiKey });
+      const indexes = await client.listIndexes();
+      const indexNames = (_b = (_a = indexes.indexes) == null ? void 0 : _a.map((i) => i.name)) != null ? _b : [];
+      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
+      };
+    }
+  }
+  static async checkPostgres(config, timestamp) {
+    const opts = config.options;
+    try {
+      const { Client } = await import("pg");
+      const client = new Client({ connectionString: opts.connectionString });
+      await client.connect();
+      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
+      };
+    }
+  }
+  static async checkMongoDB(config, timestamp) {
+    const opts = config.options;
+    try {
+      const { MongoClient: MongoClient2 } = await import("mongodb");
+      const client = new MongoClient2(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
+      };
+    }
+  }
+  static async checkMilvus(config, timestamp) {
+    const opts = config.options;
+    const host = opts.host || "localhost";
+    const port = opts.port || 19530;
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), 5e3);
+      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
+      };
+    }
+  }
+  static async checkQdrant(config, timestamp) {
+    const opts = config.options;
+    const baseUrl = opts.baseUrl || opts.url || "http://localhost:6333";
+    try {
+      const apiKey = opts.apiKey;
+      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,
+        timestamp
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        provider: "qdrant",
+        error: `Connection failed: ${error instanceof Error ? error.message : String(error)}`,
+        timestamp
+      };
+    }
+  }
+  static async checkChromaDB(config, timestamp) {
+    const opts = config.options;
+    const host = opts.host || "localhost";
+    const port = opts.port || 8e3;
+    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
+      };
+    }
+  }
+  static async checkRedis(config, timestamp) {
+    const opts = config.options;
+    const url = opts.url || `redis://${opts.host}:${opts.port}`;
+    try {
+      await fetch(url);
+      return {
+        healthy: true,
+        provider: "redis",
+        capabilities: { endpoint: url },
+        timestamp
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        provider: "redis",
+        error: `Connection check failed: ${error instanceof Error ? error.message : String(error)}. Ensure Redis is running at ${url}`,
+        timestamp
+      };
+    }
+  }
+  static async checkWeaviate(config, timestamp) {
+    const opts = config.options;
+    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
+      };
+    }
+  }
+  static async checkRestAPI(config, timestamp) {
+    const opts = config.options;
+    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 ? void 0 : `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) {
+    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
+      };
+    }
+  }
+  static async checkOpenAI(config, timestamp) {
+    try {
+      const OpenAI2 = await import("openai");
+      const client = new OpenAI2.default({ apiKey: config.apiKey });
+      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
+      };
+    }
+  }
+  static async checkAnthropic(config, timestamp) {
+    try {
+      const { default: Anthropic2 } = await import("@anthropic-ai/sdk");
+      const client = new Anthropic2({ apiKey: config.apiKey });
+      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
+      };
+    }
+  }
+  static async checkOllama(config, timestamp) {
+    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();
+      const models = data.models || [];
+      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
+      };
+    }
+  }
+  static async checkLLMRestAPI(config, timestamp) {
+    var _a, _b;
+    const baseUrlRaw = config.baseUrl || ((_a = config.options) == null ? void 0 : _a.baseUrl);
+    const baseUrl = (typeof baseUrlRaw === "string" ? baseUrlRaw : "").replace(/\/$/, "");
+    if (!baseUrl) {
+      return {
+        healthy: false,
+        provider: config.provider,
+        error: "baseUrl is required",
+        timestamp
+      };
+    }
+    try {
+      const headers = (_b = config.options) == null ? void 0 : _b.headers;
+      const response = await fetch(`${baseUrl}/health`, {
+        headers: headers || void 0
+      });
+      return {
+        healthy: response.ok,
+        provider: config.provider,
+        error: response.ok ? void 0 : `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, llmConfig, embeddingConfig) {
+    const [vectorDb, llm, embedding] = await Promise.all([
+      this.checkVectorProvider(vectorDbConfig),
+      this.checkLLMProvider(llmConfig),
+      embeddingConfig ? this.checkLLMProvider(embeddingConfig) : Promise.resolve(void 0)
     ]);
-    return { vectorDB, llm };
+    return {
+      vectorDb,
+      llm,
+      embedding,
+      allHealthy: vectorDb.healthy && llm.healthy && (!embedding || embedding.healthy)
+    };
   }
 };
 
@@ -1672,10 +2960,26 @@ var VectorPlugin = class {
   /**
    * 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) {
     this.config = ConfigResolver.resolve(hostConfig);
-    ConfigResolver.validate(this.config);
+    ConfigValidator.validateAndThrow(this.config);
     this.pipeline = new Pipeline(this.config);
   }
   /**
@@ -1684,6 +2988,19 @@ var VectorPlugin = class {
   getConfig() {
     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() {
+    return ProviderHealthCheck.checkAll(
+      this.config.vectorDb,
+      this.config.llm,
+      this.config.embedding
+    );
+  }
   /**
    * Run a chat query.
    */
@@ -1696,12 +3013,6 @@ var VectorPlugin = class {
   async ingest(documents, namespace) {
     return this.pipeline.ingest(documents, namespace);
   }
-  /**
-   * Check the health of the connected providers.
-   */
-  async health() {
-    return this.pipeline.health();
-  }
 };
 
 // src/server.ts
@@ -1820,8 +3131,8 @@ function createHealthHandler(config) {
   const plugin = new VectorPlugin(config);
   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 import_server.NextResponse.json(__spreadProps(__spreadValues({
         status
       }, health), {