@retrivora-ai/rag-engine 0.4.4 → 1.0.0

package/README.md

@@ -10,44 +10,42 @@
 
 ---
 
-## ✨ Features
+## ✨ Features (v1.0.0)
 
 | Category | Options |
 |---|---|
-| **Vector DBs** | Pinecone, pgVector (PostgreSQL), MongoDB Atlas, ChromaDB, Qdrant, universal REST adapters |
-| **LLM Providers** | OpenAI, Anthropic Claude, Google Gemini, Ollama, LiteLLM, universal REST adapters |
+| **Vector DBs** | Pinecone, pgVector (PostgreSQL), MongoDB Atlas, ChromaDB, Qdrant, Milvus, Weaviate, Redis |
+| **LLM Providers** | OpenAI, Anthropic Claude, Google Gemini, Ollama, LiteLLM, Universal REST |
+| **Integrations** | **LangChain** (Agentic orchestration), **LlamaIndex** (Semantic chunking) |
 | **Document Ingestion** | Universal support for **PDF**, **DOCX**, **CSV**, **JSON**, **MD**, **TXT** |
-| **UI** | Full-page `ChatWindow` + floating `ChatWidget`, fully branded & responsive |
-| **RAG** | Configurable chunk size/overlap, top-K retrieval, score threshold, namespaced multi-tenancy |
+| **Architecture** | **Modular & Pluggable** registry-based system with static health checks & validators |
+| **RAG Patterns** | Simple, Hybrid, Graph-based, and Agentic workflows |
 
 ---
 
 ## 🚀 How it Works
 
-Retrivora AI acts as a universal bridge between your data and your users. It normalizes different AI providers and Vector databases into a single interface.
+Retrivora AI acts as a universal bridge between your data and your users. It normalizes different AI providers and Vector databases into a single interface using a **registry-based architecture**.
 
-1.  **Ingest**: Upload or send documents to the `/api/upload` endpoint. They are automatically parsed, chunked, and embedded.
-2.  **Retrieve**: When a user asks a question, the system converts it to a vector and searches your configured database.
-3.  **Generate**: The retrieved context is combined with the user query and sent to your configured LLM (OpenAI, Claude, etc.) to generate a grounded response.
+1.  **Ingest**: Upload or send documents to the `/api/upload` endpoint. They are parsed and chunked using **LlamaIndex** strategies if configured.
+2.  **Retrieve**: Queries are processed via the [QueryProcessor](file:///src/core/QueryProcessor.ts) to extract semantic hints and filter criteria.
+3.  **Generate**: Context is retrieved and processed through a [Pipeline](file:///src/core/Pipeline.ts) (or [LangChainAgent](file:///src/core/LangChainAgent.ts)) to produce grounded, streaming responses.
 
-### 📦 How to Install
-
-To integrate Retrivora AI into your existing Next.js project, simply run:
+### 📦 Installation
 
 ```bash
 npm install @retrivora-ai/rag-engine
 ```
 
-Alternatively, if you want to run the standalone demo application:
+---
 
-```bash
-git clone https://github.com/abhinav1201/ai-accelerator
-cd ai-accelerator
-npm install
-cp .env.example .env.local
-# Fill in your API keys in .env.local
-npm run dev
-```
+## 🛠️ Pluggable Architecture
+
+Starting with v1.0.0, the engine uses a modular registry for all providers. Every provider now exposes:
+- **Static Validators**: `getValidator()` for deep configuration schema checks.
+- **Static Health Checkers**: `getHealthChecker()` for real-time connectivity and capability validation.
+
+This decoupling allows you to add custom providers without modifying the core engine logic.
 
 ---
 
@@ -55,8 +53,6 @@ npm run dev
 
 ### 1. Embed the ChatWidget
 
-Wrap your application in the `ConfigProvider` and add the `ChatWidget`.
-
 ```tsx
 import { ConfigProvider, ChatWidget } from '@retrivora-ai/rag-engine';
 
@@ -82,25 +78,28 @@ export default function Layout({ children }) {
 
 ### 2. Mount the API routes
 
-Create standard Next.js route handlers and plug in the library's factories.
-
 ```ts
 // src/app/api/chat/route.ts
 import { createChatHandler, getRagConfig } from '@retrivora-ai/rag-engine/server';
 export const POST = createChatHandler(getRagConfig());
 
-// src/app/api/upload/route.ts (Handles PDF, DOCX, etc.)
+// src/app/api/upload/route.ts
 import { createUploadHandler, getRagConfig } from '@retrivora-ai/rag-engine/server';
 export const POST = createUploadHandler(getRagConfig());
 ```
 
-### 3. Use RAGPipeline programmatically
+### 3. Use Pipeline programmatically
 
 ```ts
-import { RAGPipeline } from '@retrivora-ai/rag-engine/server';
+import { Pipeline, getRagConfig } from '@retrivora-ai/rag-engine/server';
 
-const pipeline = new RAGPipeline(config);
+const config = getRagConfig();
+const pipeline = new Pipeline(config);
+
+// Ingest documents
 await pipeline.ingest([{ docId: 'readme', content: 'Your document text here' }]);
+
+// Ask questions
 const { reply, sources } = await pipeline.ask('What is the refund policy?');
 ```
 
@@ -113,34 +112,10 @@ The library is entirely dynamic. You can switch between providers simply by upda
 | Variable | Description |
 |---|---|
 | `RAG_PROJECT_ID` | Project namespace for data isolation |
-| `VECTOR_DB_PROVIDER` | `pinecone`, `pgvector`, `mongodb`, or `universal_rest` |
-| `VECTOR_UNIVERSAL_PROFILE` | `pinecone-rest`, `mongodb-atlas`, `chromadb`, `qdrant` |
-| `LLM_PROVIDER` | `openai`, `anthropic`, `ollama`, or `universal_rest` |
-| `LLM_UNIVERSAL_PROFILE` | `openai-compatible`, `litellm`, `anthropic-claude`, `google-gemini` |
-| `EMBEDDING_PROVIDER` | `openai`, `ollama`, or `rest` |
-
----
-
-## Architecture
-
-```
-User Query
-   |
-   v
-[embed query]  <-- EmbeddingProvider (OpenAI / Ollama / Custom)
-   |
-   v
-[vector search]  <-- IVectorDB (Pinecone / pgVector / MongoDB / Chroma / REST)
-   |
-   v
-[build context]
-   |
-   v
-[LLM chat]  <-- ILLMProvider (OpenAI / Anthropic / Gemini / LiteLLM)
-   |
-   v
-ChatResponse { reply, sources[] }
-```
+| `VECTOR_DB_PROVIDER` | `pinecone`, `pgvector`, `mongodb`, `milvus`, `qdrant`, `weaviate` |
+| `LLM_PROVIDER` | `openai`, `anthropic`, `gemini`, `ollama` |
+| `EMBEDDING_PROVIDER` | `openai`, `ollama`, `google-gemini` |
+| `RAG_ARCHITECTURE` | `simple`, `hybrid`, `graph`, `agentic` |
 
 ---
 

package/dist/{ChromaDBProvider-GI7TB7GJ.mjs → ChromaDBProvider-APQVJ5F7.mjs}

@@ -1,8 +1,8 @@
 import {
   ChromaDBProvider
-} from "./chunk-RK2UDJA2.mjs";
+} from "./chunk-WGSZNY3X.mjs";
 import "./chunk-IMP6FUCY.mjs";
-import "./chunk-FWCSY2DS.mjs";
+import "./chunk-QMIKLALV.mjs";
 export {
   ChromaDBProvider
 };

package/dist/{DocumentChunker-3yElxTO3.d.mts → DocumentChunker-C-sCZPhi.d.mts}

@@ -30,6 +30,11 @@ interface ILLMProvider {
      * @returns        – the assistant's reply text
      */
     chat(messages: ChatMessage[], context: string, options?: ChatOptions): Promise<string>;
+    /**
+     * Send a streaming chat completion request.
+     * @returns – an async iterable of text chunks
+     */
+    chatStream?(messages: ChatMessage[], context: string, options?: ChatOptions): AsyncIterable<string>;
     /**
      * Generate an embedding vector for the given text.
      * @param text    – text to embed
@@ -83,15 +88,10 @@ declare class DocumentChunker {
     constructor(chunkSize?: number, chunkOverlap?: number, separators?: string[]);
     /**
      * Split a single text string into overlapping chunks using a recursive strategy.
+     * Preserves structural boundaries (Markdown headers) where possible.
      */
     chunk(text: string, options?: ChunkOptions): Chunk[];
-    /**
-     * Recursively split text based on separators.
-     */
     private recursiveSplit;
-    /**
-     * Chunk multiple documents at once.
-     */
     chunkMany(documents: Array<{
         content: string;
         docId?: string | number;

package/dist/{DocumentChunker-3yElxTO3.d.ts → DocumentChunker-C-sCZPhi.d.ts}

@@ -30,6 +30,11 @@ interface ILLMProvider {
      * @returns        – the assistant's reply text
      */
     chat(messages: ChatMessage[], context: string, options?: ChatOptions): Promise<string>;
+    /**
+     * Send a streaming chat completion request.
+     * @returns – an async iterable of text chunks
+     */
+    chatStream?(messages: ChatMessage[], context: string, options?: ChatOptions): AsyncIterable<string>;
     /**
      * Generate an embedding vector for the given text.
      * @param text    – text to embed
@@ -83,15 +88,10 @@ declare class DocumentChunker {
     constructor(chunkSize?: number, chunkOverlap?: number, separators?: string[]);
     /**
      * Split a single text string into overlapping chunks using a recursive strategy.
+     * Preserves structural boundaries (Markdown headers) where possible.
      */
     chunk(text: string, options?: ChunkOptions): Chunk[];
-    /**
-     * Recursively split text based on separators.
-     */
     private recursiveSplit;
-    /**
-     * Chunk multiple documents at once.
-     */
     chunkMany(documents: Array<{
         content: string;
         docId?: string | number;

package/dist/{MilvusProvider-WDVTFB7D.mjs → MilvusProvider-35US67MS.mjs}

@@ -1,8 +1,8 @@
 import {
   MilvusProvider
-} from "./chunk-3QWAK3RZ.mjs";
+} from "./chunk-TYHTZIDP.mjs";
 import "./chunk-IMP6FUCY.mjs";
-import "./chunk-FWCSY2DS.mjs";
+import "./chunk-QMIKLALV.mjs";
 export {
   MilvusProvider
 };

package/dist/{MongoDBProvider-ZKW34AEL.mjs → MongoDBProvider-COVYZDP6.mjs}

@@ -1,8 +1,8 @@
 import {
   MongoDBProvider
-} from "./chunk-IWHCAQEA.mjs";
+} from "./chunk-7SOSCZGS.mjs";
 import "./chunk-IMP6FUCY.mjs";
-import "./chunk-FWCSY2DS.mjs";
+import "./chunk-QMIKLALV.mjs";
 export {
   MongoDBProvider
 };

package/dist/{PineconeProvider-BE2JWSPD.mjs → PineconeProvider-AWFJQDZL.mjs}

@@ -1,8 +1,8 @@
 import {
   PineconeProvider
-} from "./chunk-XCNXPECE.mjs";
+} from "./chunk-ZNBKHNJ4.mjs";
 import "./chunk-IMP6FUCY.mjs";
-import "./chunk-FWCSY2DS.mjs";
+import "./chunk-QMIKLALV.mjs";
 export {
   PineconeProvider
 };

package/dist/{PostgreSQLProvider-5HHTK4SU.mjs → PostgreSQLProvider-IEYRJ7XJ.mjs}

@@ -1,8 +1,8 @@
 import {
   PostgreSQLProvider
-} from "./chunk-LJWWPTWE.mjs";
+} from "./chunk-FLOSGE6A.mjs";
 import "./chunk-IMP6FUCY.mjs";
-import "./chunk-FWCSY2DS.mjs";
+import "./chunk-QMIKLALV.mjs";
 export {
   PostgreSQLProvider
 };

package/dist/{QdrantProvider-XVDVBNIG.mjs → QdrantProvider-M6TQYZRO.mjs}

@@ -1,8 +1,8 @@
 import {
   QdrantProvider
-} from "./chunk-5KNBWQM6.mjs";
+} from "./chunk-4A47RCG2.mjs";
 import "./chunk-IMP6FUCY.mjs";
-import "./chunk-FWCSY2DS.mjs";
+import "./chunk-QMIKLALV.mjs";
 export {
   QdrantProvider
 };

package/dist/{RagConfig-BgRDL9Vy.d.mts → RagConfig-DRJO4hGU.d.mts}

@@ -35,6 +35,10 @@ interface GraphSearchResult {
     nodes: GraphNode[];
     edges: Edge[];
 }
+interface RetrievalResult {
+    sources: VectorMatch[];
+    graphData?: GraphSearchResult;
+}
 
 /**
  * constants.ts — Centralized definitions of acceptable configuration values.
@@ -73,6 +77,9 @@ interface VectorDBConfig {
      * - scorePath?: string (e.g. 'similarity')
      * - contentPath?: string (e.g. 'text')
      *
+     * For 'mongodb', the following options are also supported:
+     * - numCandidates?: number // controls search recall depth
+     *
      * For multi-table PostgreSQL search, the following options are also supported:
      * - tables?: string[] | string
      * - searchFields?: string[] | string // optional override for which columns receive exact-match boosts
@@ -170,6 +177,10 @@ interface RAGConfig {
     chunkOverlap?: number;
     /** Characters used to split text, in order of priority */
     separators?: string[];
+    /** Overall RAG architecture pattern */
+    architecture?: 'simple' | 'graph' | 'hybrid' | 'agentic';
+    /** Chunking strategy to use during ingestion */
+    chunkingStrategy?: 'recursive' | 'markdown' | 'semantic' | 'llamaindex';
     /** Whether to use query transformation (e.g. HyDE) */
     useQueryTransformation?: boolean;
     /** Whether to use graph-based retrieval */
@@ -197,4 +208,4 @@ interface RagConfig {
     graphDb?: GraphDBConfig;
 }
 
-export type { ChatResponse as C, EmbeddingConfig as E, GraphDBConfig as G, IngestDocument as I, LLMConfig as L, RAGConfig as R, UIConfig as U, VectorMatch as V, EmbeddingProvider as a, LLMProvider as b, RagConfig as c, UpsertDocument as d, VectorDBConfig as e, VectorDBProvider as f, GraphNode as g, Edge as h, GraphSearchResult as i };
+export type { ChatResponse as C, EmbeddingConfig as E, GraphDBConfig as G, IngestDocument as I, LLMConfig as L, RAGConfig as R, UIConfig as U, VectorMatch as V, EmbeddingProvider as a, LLMProvider as b, RagConfig as c, UpsertDocument as d, VectorDBConfig as e, VectorDBProvider as f, RetrievalResult as g, GraphNode as h, Edge as i, GraphSearchResult as j };

package/dist/{RagConfig-BgRDL9Vy.d.ts → RagConfig-DRJO4hGU.d.ts}

@@ -35,6 +35,10 @@ interface GraphSearchResult {
     nodes: GraphNode[];
     edges: Edge[];
 }
+interface RetrievalResult {
+    sources: VectorMatch[];
+    graphData?: GraphSearchResult;
+}
 
 /**
  * constants.ts — Centralized definitions of acceptable configuration values.
@@ -73,6 +77,9 @@ interface VectorDBConfig {
      * - scorePath?: string (e.g. 'similarity')
      * - contentPath?: string (e.g. 'text')
      *
+     * For 'mongodb', the following options are also supported:
+     * - numCandidates?: number // controls search recall depth
+     *
      * For multi-table PostgreSQL search, the following options are also supported:
      * - tables?: string[] | string
      * - searchFields?: string[] | string // optional override for which columns receive exact-match boosts
@@ -170,6 +177,10 @@ interface RAGConfig {
     chunkOverlap?: number;
     /** Characters used to split text, in order of priority */
     separators?: string[];
+    /** Overall RAG architecture pattern */
+    architecture?: 'simple' | 'graph' | 'hybrid' | 'agentic';
+    /** Chunking strategy to use during ingestion */
+    chunkingStrategy?: 'recursive' | 'markdown' | 'semantic' | 'llamaindex';
     /** Whether to use query transformation (e.g. HyDE) */
     useQueryTransformation?: boolean;
     /** Whether to use graph-based retrieval */
@@ -197,4 +208,4 @@ interface RagConfig {
     graphDb?: GraphDBConfig;
 }
 
-export type { ChatResponse as C, EmbeddingConfig as E, GraphDBConfig as G, IngestDocument as I, LLMConfig as L, RAGConfig as R, UIConfig as U, VectorMatch as V, EmbeddingProvider as a, LLMProvider as b, RagConfig as c, UpsertDocument as d, VectorDBConfig as e, VectorDBProvider as f, GraphNode as g, Edge as h, GraphSearchResult as i };
+export type { ChatResponse as C, EmbeddingConfig as E, GraphDBConfig as G, IngestDocument as I, LLMConfig as L, RAGConfig as R, UIConfig as U, VectorMatch as V, EmbeddingProvider as a, LLMProvider as b, RagConfig as c, UpsertDocument as d, VectorDBConfig as e, VectorDBProvider as f, RetrievalResult as g, GraphNode as h, Edge as i, GraphSearchResult as j };

package/dist/{RedisProvider-EK2R2PQH.mjs → RedisProvider-3G5PBLZ4.mjs}

@@ -1,8 +1,8 @@
 import {
   RedisProvider
-} from "./chunk-H6RKMU7W.mjs";
+} from "./chunk-NXUCKY5L.mjs";
 import "./chunk-IMP6FUCY.mjs";
-import "./chunk-FWCSY2DS.mjs";
+import "./chunk-QMIKLALV.mjs";
 export {
   RedisProvider
 };

package/dist/{SimpleGraphProvider-M6T7SE7D.mjs → SimpleGraphProvider-UK7DJW37.mjs}

@@ -1,4 +1,4 @@
-import "./chunk-FWCSY2DS.mjs";
+import "./chunk-QMIKLALV.mjs";
 
 // src/providers/graphdb/BaseGraphProvider.ts
 var BaseGraphProvider = class {

package/dist/{UniversalVectorProvider-YIDRX6VT.mjs → UniversalVectorProvider-FYQ3B2PW.mjs}

@@ -1,9 +1,9 @@
 import {
   UniversalVectorProvider
-} from "./chunk-GQT5LF4G.mjs";
-import "./chunk-EDLTMSNY.mjs";
+} from "./chunk-U6KHVZLF.mjs";
+import "./chunk-67AJ6SMD.mjs";
 import "./chunk-IMP6FUCY.mjs";
-import "./chunk-FWCSY2DS.mjs";
+import "./chunk-QMIKLALV.mjs";
 export {
   UniversalVectorProvider
 };

package/dist/{WeaviateProvider-4CAPQ7UY.mjs → WeaviateProvider-ITHO36IL.mjs}

@@ -1,8 +1,8 @@
 import {
   WeaviateProvider
-} from "./chunk-KTS3LLHY.mjs";
+} from "./chunk-OOQXNLXD.mjs";
 import "./chunk-IMP6FUCY.mjs";
-import "./chunk-FWCSY2DS.mjs";
+import "./chunk-QMIKLALV.mjs";
 export {
   WeaviateProvider
 };

package/dist/{chunk-5KNBWQM6.mjs → chunk-4A47RCG2.mjs}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-IMP6FUCY.mjs";
 import {
   __spreadValues
-} from "./chunk-FWCSY2DS.mjs";
+} from "./chunk-QMIKLALV.mjs";
 
 // src/providers/vectordb/QdrantProvider.ts
 import axios from "axios";
@@ -99,6 +99,10 @@ var QdrantProvider = class extends BaseVectorProvider {
       vector,
       limit: topK,
       with_payload: true,
+      params: {
+        hnsw_ef: this.config.options.efSearch || Math.max(topK * 20, 128),
+        exact: false
+      },
       filter: namespace ? {
         must: [{ key: "namespace", match: { value: namespace } }]
       } : void 0

package/dist/{chunk-EDLTMSNY.mjs → chunk-67AJ6SMD.mjs}

@@ -1,6 +1,6 @@
 import {
   __spreadValues
-} from "./chunk-FWCSY2DS.mjs";
+} from "./chunk-QMIKLALV.mjs";
 
 // src/utils/templateUtils.ts
 function isRecord(value) {

package/dist/{chunk-IWHCAQEA.mjs → chunk-7SOSCZGS.mjs}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-IMP6FUCY.mjs";
 import {
   __spreadValues
-} from "./chunk-FWCSY2DS.mjs";
+} from "./chunk-QMIKLALV.mjs";
 
 // src/providers/vectordb/MongoDBProvider.ts
 import { MongoClient } from "mongodb";
@@ -21,6 +21,71 @@ var MongoDBProvider = class extends BaseVectorProvider {
     this.contentKey = opts.contentKey || "content";
     this.metadataKey = opts.metadataKey || "metadata";
   }
+  static getValidator() {
+    return {
+      validate(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",
+            severity: "error"
+          });
+        }
+        if (!opts.collection) {
+          errors.push({
+            field: "vectorDb.options.collection",
+            message: "MongoDB collection name is required",
+            severity: "error"
+          });
+        }
+        return errors;
+      }
+    };
+  }
+  static getHealthChecker() {
+    return {
+      async check(config) {
+        const opts = config.options || {};
+        const timestamp = Date.now();
+        try {
+          const { MongoClient: MongoClient2 } = await import("mongodb");
+          const client = new MongoClient2(opts.uri);
+          await client.connect();
+          const db = client.db(opts.database);
+          await db.command({ ping: 1 });
+          const collections = await db.listCollections({ name: opts.collection }).toArray();
+          await client.close();
+          return {
+            healthy: true,
+            provider: "mongodb",
+            capabilities: {
+              database: opts.database,
+              collection: opts.collection,
+              exists: collections.length > 0
+            },
+            timestamp
+          };
+        } catch (error) {
+          return {
+            healthy: false,
+            provider: "mongodb",
+            error: `Connection failed: ${error instanceof Error ? error.message : String(error)}`,
+            timestamp
+          };
+        }
+      }
+    };
+  }
   async initialize() {
     await this.client.connect();
     this.db = this.client.db(this.dbName);
@@ -59,7 +124,7 @@ var MongoDBProvider = class extends BaseVectorProvider {
           index: this.config.indexName || "vector_index",
           path: this.embeddingKey,
           queryVector: vector,
-          numCandidates: Math.max(topK * 10, 100),
+          numCandidates: this.config.options.numCandidates || Math.max(topK * 20, 200),
           limit: topK
         }, Object.keys(publicFilter).length > 0 || namespace ? { filter: __spreadValues(__spreadValues({}, publicFilter), namespace ? { namespace } : {}) } : {})
       },
@@ -77,7 +142,7 @@ var MongoDBProvider = class extends BaseVectorProvider {
     return results.map((res) => ({
       id: res._id,
       content: res[this.contentKey],
-      metadata: res[this.metadataKey],
+      metadata: res[this.metadataKey] || {},
       score: res.score
     }));
   }
@@ -87,10 +152,6 @@ var MongoDBProvider = class extends BaseVectorProvider {
   async deleteNamespace(namespace) {
     await this.collection.deleteMany({ namespace });
   }
-  /**
-   * Sanitise and flatten filter for MongoDB.
-   * Strips internal engine fields and keywords.
-   */
   sanitizeFilter(filter) {
     const sanitized = super.sanitizeFilter(filter);
     const mongoFilter = {};

package/dist/{chunk-LJWWPTWE.mjs → chunk-FLOSGE6A.mjs}

@@ -14,6 +14,61 @@ var PostgreSQLProvider = class extends BaseVectorProvider {
     this.connectionString = opts.connectionString;
     this.dimensions = (_a = opts.dimensions) != null ? _a : 1536;
   }
+  static getValidator() {
+    return {
+      validate(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"
+          });
+        }
+        if (opts.tables && typeof opts.tables !== "string" && !Array.isArray(opts.tables)) {
+          errors.push({
+            field: "vectorDb.options.tables",
+            message: "PostgreSQL tables must be a string or a string array",
+            severity: "error"
+          });
+        }
+        return errors;
+      }
+    };
+  }
+  static getHealthChecker() {
+    return {
+      async check(config) {
+        const opts = config.options || {};
+        const timestamp = Date.now();
+        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
+          };
+        }
+      }
+    };
+  }
   async initialize() {
     this.pool = new Pool({ connectionString: this.connectionString });
     const client = await this.pool.connect();
@@ -99,20 +154,27 @@ var PostgreSQLProvider = class extends BaseVectorProvider {
       }).join(" AND ");
       whereClause = whereClause ? `${whereClause} AND ${filterConditions}` : `WHERE ${filterConditions}`;
     }
-    const result = await this.pool.query(
-      `SELECT id, content, metadata, 1 - (embedding <=> $1::vector) AS score
-       FROM ${this.tableName}
-       ${whereClause}
-       ORDER BY embedding <=> $1::vector
-       LIMIT $2`,
-      params
-    );
-    return result.rows.map((row) => ({
-      id: String(row["id"]),
-      score: parseFloat(String(row["score"])),
-      content: String(row["content"]),
-      metadata: row["metadata"]
-    }));
+    const client = await this.pool.connect();
+    try {
+      const efSearch = this.config.options.efSearch || Math.max(topK * 10, 40);
+      await client.query(`SET LOCAL hnsw.ef_search = ${efSearch}`);
+      const result = await client.query(
+        `SELECT id, content, metadata, 1 - (embedding <=> $1::vector) AS score
+         FROM ${this.tableName}
+         ${whereClause}
+         ORDER BY embedding <=> $1::vector
+         LIMIT $2`,
+        params
+      );
+      return result.rows.map((row) => ({
+        id: String(row["id"]),
+        score: parseFloat(String(row["score"])),
+        content: String(row["content"]),
+        metadata: row["metadata"]
+      }));
+    } finally {
+      client.release();
+    }
   }
   async delete(id, namespace) {
     const where = namespace ? "WHERE id = $1 AND namespace = $2" : "WHERE id = $1";

package/dist/{chunk-H6RKMU7W.mjs → chunk-NXUCKY5L.mjs}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-IMP6FUCY.mjs";
 import {
   __spreadValues
-} from "./chunk-FWCSY2DS.mjs";
+} from "./chunk-QMIKLALV.mjs";
 
 // src/providers/vectordb/RedisProvider.ts
 import axios from "axios";