@retrivora-ai/rag-engine 0.1.3 → 0.1.5

package/src/{vectordb/adapters/PineconeAdapter.ts → providers/vectordb/PineconeProvider.ts}

@@ -1,37 +1,25 @@
-/**
- * Pinecone Vector DB Adapter
- *
- * Required options in VectorDBConfig.options:
- *   - apiKey:       string  – Pinecone API key
- *   - environment?: string  – Pinecone environment (legacy, optional for new projects)
- */
-
 import { Pinecone, RecordMetadata } from '@pinecone-database/pinecone';
-import { IVectorDB, VectorMatch, UpsertDocument } from '../IVectorDB';
 import { VectorDBConfig } from '../../config/RagConfig';
+import { BaseVectorProvider } from './BaseVectorProvider';
+import { VectorMatch, UpsertDocument } from '../../types';
 
-export class PineconeAdapter implements IVectorDB {
+export class PineconeProvider extends BaseVectorProvider {
   private client!: Pinecone;
-  private readonly indexName: string;
   private readonly apiKey: string;
 
   constructor(config: VectorDBConfig) {
-    this.indexName = config.indexName;
+    super(config);
     const opts = config.options as Record<string, string>;
-    if (!opts.apiKey) throw new Error('[PineconeAdapter] options.apiKey is required');
+    if (!opts.apiKey) throw new Error('[PineconeProvider] options.apiKey is required');
     this.apiKey = opts.apiKey;
   }
 
   async initialize(): Promise<void> {
     this.client = new Pinecone({ apiKey: this.apiKey });
-    // Verify index exists
     const indexes = await this.client.listIndexes();
     const names = indexes.indexes?.map((i) => i.name) ?? [];
     if (!names.includes(this.indexName)) {
-      throw new Error(
-        `[PineconeAdapter] Index "${this.indexName}" not found. ` +
-          `Available: ${names.join(', ')}`
-      );
+      throw new Error(`[PineconeProvider] Index "${this.indexName}" not found.`);
     }
   }
 
@@ -42,16 +30,11 @@ export class PineconeAdapter implements IVectorDB {
 
   async upsert(doc: UpsertDocument, namespace?: string): Promise<void> {
     await this.index(namespace).upsert({
-      records: [
-        {
-          id: doc.id,
-          values: doc.vector,
-          metadata: {
-            content: doc.content,
-            ...(doc.metadata ?? {}),
-          } as RecordMetadata,
-        },
-      ],
+      records: [{
+        id: doc.id,
+        values: doc.vector,
+        metadata: { content: doc.content, ...(doc.metadata ?? {}) } as RecordMetadata,
+      }],
     });
   }
 
@@ -61,40 +44,25 @@ export class PineconeAdapter implements IVectorDB {
       const records = docs.slice(i, i + BATCH).map((d) => ({
         id: d.id,
         values: d.vector,
-        metadata: {
-          content: d.content,
-          ...(d.metadata ?? {}),
-        } as RecordMetadata,
+        metadata: { content: d.content, ...(d.metadata ?? {}) } as RecordMetadata,
       }));
       await this.index(namespace).upsert({ records });
     }
   }
 
-  async query(
-    vector: number[],
-    topK: number,
-    namespace?: string,
-    filter?: Record<string, unknown>
-  ): Promise<VectorMatch[]> {
+  async query(vector: number[], topK: number, namespace?: string, filter?: Record<string, unknown>): Promise<VectorMatch[]> {
     const result = await this.index(namespace).query({
       vector,
       topK,
       includeMetadata: true,
       ...(filter ? { filter } : {}),
     });
-
-    return (result.matches ?? []).map((m) => {
-      const metadata = m.metadata as Record<string, unknown>;
-      // Try multiple common fields for content
-      const content = (metadata?.content || metadata?.text || metadata?.body || metadata?.description || '') as string;
-      
-      return {
-        id: m.id,
-        score: m.score ?? 0,
-        content,
-        metadata,
-      };
-    });
+    return (result.matches ?? []).map((m) => ({
+      id: m.id,
+      score: m.score ?? 0,
+      content: (m.metadata?.content || '') as string,
+      metadata: m.metadata as Record<string, unknown>,
+    }));
   }
 
   async delete(id: string, namespace?: string): Promise<void> {
@@ -109,13 +77,10 @@ export class PineconeAdapter implements IVectorDB {
     try {
       await this.client.listIndexes();
       return true;
-    } catch (err) {
-      console.error('[PineconeAdapter] Ping failed:', err);
+    } catch {
       return false;
     }
   }
 
-  async disconnect(): Promise<void> {
-    // Pinecone SDK is stateless REST, no persistent connection to close.
-  }
+  async disconnect(): Promise<void> {}
 }

package/src/{vectordb/adapters/PgVectorAdapter.ts → providers/vectordb/PostgreSQLProvider.ts}

@@ -1,43 +1,31 @@
-/**
- * pgVector Adapter
- *
- * Stores embeddings in a PostgreSQL table using the pgvector extension.
- * Required options in VectorDBConfig.options:
- *   - connectionString: string  – PostgreSQL connection string
- *   - dimensions?:      number  – vector dimensions (default 1536 for OpenAI ada-002)
- *
- * The adapter auto-creates the table and index on initialize().
- */
-
 import { Pool, PoolClient } from 'pg';
-import { IVectorDB, VectorMatch, UpsertDocument } from '../IVectorDB';
 import { VectorDBConfig } from '../../config/RagConfig';
+import { BaseVectorProvider } from './BaseVectorProvider';
+import { VectorMatch, UpsertDocument } from '../../types';
 
-export class PgVectorAdapter implements IVectorDB {
+/**
+ * PostgreSQLProvider — PostgreSQL implementation using the pgvector extension.
+ */
+export class PostgreSQLProvider extends BaseVectorProvider {
   private pool!: Pool;
-  private readonly tableName: string;
   private readonly dimensions: number;
   private readonly connectionString: string;
+  private readonly tableName: string;
 
   constructor(config: VectorDBConfig) {
-    this.tableName = config.indexName.replace(/[^a-z0-9_]/gi, '_'); // sanitize
+    super(config);
+    this.tableName = this.indexName.replace(/[^a-z0-9_]/gi, '_');
     const opts = config.options as Record<string, unknown>;
-    if (!opts.connectionString) {
-      throw new Error('[PgVectorAdapter] options.connectionString is required');
-    }
+    if (!opts.connectionString) throw new Error('[PostgreSQLProvider] options.connectionString is required');
     this.connectionString = opts.connectionString as string;
     this.dimensions = (opts.dimensions as number) ?? 1536;
   }
 
   async initialize(): Promise<void> {
     this.pool = new Pool({ connectionString: this.connectionString });
-
     const client: PoolClient = await this.pool.connect();
     try {
-      // Enable pgvector extension
       await client.query('CREATE EXTENSION IF NOT EXISTS vector');
-
-      // Create the chunks table if it doesn't exist
       await client.query(`
         CREATE TABLE IF NOT EXISTS ${this.tableName} (
           id          TEXT PRIMARY KEY,
@@ -47,8 +35,6 @@ export class PgVectorAdapter implements IVectorDB {
           embedding   VECTOR(${this.dimensions})
         )
       `);
-
-      // Create HNSW index for fast approximate nearest-neighbour search
       await client.query(`
         CREATE INDEX IF NOT EXISTS ${this.tableName}_embedding_idx
         ON ${this.tableName}
@@ -74,25 +60,17 @@ export class PgVectorAdapter implements IVectorDB {
   }
 
   async batchUpsert(docs: UpsertDocument[], namespace = ''): Promise<void> {
-    // Sequential for simplicity; swap for COPY or multi-row INSERT for perf
     for (const doc of docs) {
       await this.upsert(doc, namespace);
     }
   }
 
-  async query(
-    vector: number[],
-    topK: number,
-    namespace?: string,
-    filter?: Record<string, unknown>
-  ): Promise<VectorMatch[]> {
+  async query(vector: number[], topK: number, namespace?: string, filter?: Record<string, unknown>): Promise<VectorMatch[]> {
     const vectorLiteral = `[${vector.join(',')}]`;
-
     let whereClause = namespace ? `WHERE namespace = $3` : '';
     const params: unknown[] = [vectorLiteral, topK];
     if (namespace) params.push(namespace);
 
-    // Append metadata filter conditions if provided
     if (filter && Object.keys(filter).length > 0) {
       const filterConditions = Object.entries(filter)
         .map(([key, val]) => {
@@ -101,28 +79,23 @@ export class PgVectorAdapter implements IVectorDB {
           return `metadata->>'${key}' = $${paramIdx}`;
         })
         .join(' AND ');
-      whereClause = whereClause
-        ? `${whereClause} AND ${filterConditions}`
-        : `WHERE ${filterConditions}`;
+      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}
+      `SELECT id, content, metadata, 1 - (embedding <=> $1::vector) AS score
+       FROM ${this.tableName}
        ${whereClause}
-       ORDER  BY embedding <=> $1::vector
-       LIMIT  $2`,
+       ORDER BY embedding <=> $1::vector
+       LIMIT $2`,
       params
     );
 
     return result.rows.map((row: Record<string, unknown>) => ({
-      id: String(row.id),
-      score: parseFloat(String(row.score)),
-      content: String(row.content),
-      metadata: row.metadata as Record<string, unknown>,
+      id: String(row['id']),
+      score: parseFloat(String(row['score'])),
+      content: String(row['content']),
+      metadata: row['metadata'] as Record<string, unknown>,
     }));
   }
 
@@ -133,27 +106,19 @@ export class PgVectorAdapter implements IVectorDB {
   }
 
   async deleteNamespace(namespace: string): Promise<void> {
-    await this.pool.query(
-      `DELETE FROM ${this.tableName} WHERE namespace = $1`,
-      [namespace]
-    );
+    await this.pool.query(`DELETE FROM ${this.tableName} WHERE namespace = $1`, [namespace]);
   }
 
   async ping(): Promise<boolean> {
     try {
       await this.pool.query('SELECT 1');
       return true;
-    } catch (err) {
-      console.error('[PgVectorAdapter] Ping failed:', err);
+    } catch {
       return false;
     }
   }
 
   async disconnect(): Promise<void> {
-    try {
-      await this.pool.end();
-    } catch (err) {
-      console.error('[PgVectorAdapter] Failed to disconnect:', err);
-    }
+    await this.pool.end();
   }
 }

package/src/providers/vectordb/QdrantProvider.ts

@@ -0,0 +1,95 @@
+import axios, { AxiosInstance } from 'axios';
+import { VectorDBConfig } from '../../config/RagConfig';
+import { BaseVectorProvider } from './BaseVectorProvider';
+import { VectorMatch, UpsertDocument } from '../../types';
+
+/**
+ * QdrantProvider — implementation for Qdrant using its REST API.
+ */
+export class QdrantProvider extends BaseVectorProvider {
+  private http: AxiosInstance;
+
+  constructor(config: VectorDBConfig) {
+    super(config);
+    const opts = config.options as Record<string, unknown>;
+    const baseUrl = opts.baseUrl as string;
+    if (!baseUrl) throw new Error('[QdrantProvider] baseUrl is required');
+
+    this.http = axios.create({
+      baseURL: baseUrl,
+      headers: {
+        'Content-Type': 'application/json',
+        ...(opts.apiKey ? { 'api-key': opts.apiKey as string } : {}),
+      },
+    });
+  }
+
+  async initialize(): Promise<void> {
+    await this.ping();
+  }
+
+  async upsert(doc: UpsertDocument, namespace?: string): Promise<void> {
+    await this.batchUpsert([doc], namespace);
+  }
+
+  async batchUpsert(docs: UpsertDocument[], namespace?: string): Promise<void> {
+    const payload = {
+      points: docs.map(doc => ({
+        id: doc.id,
+        vector: doc.vector,
+        payload: {
+          content: doc.content,
+          metadata: doc.metadata || {},
+          ...(namespace ? { namespace } : {}),
+        },
+      })),
+    };
+    await this.http.put(`/collections/${this.indexName}/points`, payload);
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async query(vector: number[], topK: number, namespace?: string, _filter?: Record<string, unknown>): Promise<VectorMatch[]> {
+    const payload = {
+      vector: vector,
+      limit: topK,
+      with_payload: true,
+      filter: namespace ? {
+        must: [{ key: 'namespace', match: { value: namespace } }]
+      } : undefined,
+    };
+    const { data } = await this.http.post(`/collections/${this.indexName}/points/search`, payload);
+    return (data.result || []).map((res: Record<string, unknown>) => ({
+      id: res['id'] as string,
+      score: res['score'] as number,
+      content: (res['payload'] as Record<string, unknown>)?.content as string || '',
+      metadata: (res['payload'] as Record<string, unknown>)?.metadata as Record<string, unknown> || {},
+    }));
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async delete(id: string, _namespace?: string): Promise<void> {
+    await this.http.post(`/collections/${this.indexName}/points/delete`, {
+      points: [id],
+    });
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async deleteNamespace(_namespace: string): Promise<void> {
+    await this.http.post(`/collections/${this.indexName}/points/delete`, {
+      filter: {
+        must: [{ key: 'namespace', match: { value: _namespace } }]
+      }
+    });
+  }
+
+  async ping(): Promise<boolean> {
+    try {
+      await this.http.get('/healthz');
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async disconnect(): Promise<void> {}
+}

package/src/providers/vectordb/RedisProvider.ts

@@ -0,0 +1,84 @@
+import axios, { AxiosInstance } from 'axios';
+import { VectorDBConfig } from '../../config/RagConfig';
+import { BaseVectorProvider } from './BaseVectorProvider';
+import { VectorMatch, UpsertDocument } from '../../types';
+
+/**
+ * RedisProvider — implementation for Redis (e.g. Upstash) using its REST API.
+ */
+export class RedisProvider extends BaseVectorProvider {
+  private http: AxiosInstance;
+
+  constructor(config: VectorDBConfig) {
+    super(config);
+    const opts = config.options as Record<string, unknown>;
+    const baseUrl = opts.baseUrl as string;
+    if (!baseUrl) throw new Error('[RedisProvider] baseUrl is required');
+
+    this.http = axios.create({
+      baseURL: baseUrl,
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${opts.apiKey}`,
+      },
+    });
+  }
+
+  async initialize(): Promise<void> {
+    await this.ping();
+  }
+
+  async upsert(doc: UpsertDocument, namespace?: string): Promise<void> {
+    const key = namespace ? `${namespace}:${doc.id}` : doc.id;
+    await this.http.post('/', ['JSON.SET', key, '$', JSON.stringify({
+      vector: doc.vector,
+      content: doc.content,
+      metadata: doc.metadata || {},
+    })]);
+  }
+
+  async batchUpsert(docs: UpsertDocument[], namespace?: string): Promise<void> {
+    for (const doc of docs) {
+      await this.upsert(doc, namespace);
+    }
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async query(vector: number[], topK: number, namespace?: string, _filter?: Record<string, unknown>): Promise<VectorMatch[]> {
+    // This is a simplified representation of FT.SEARCH in Redis Vector
+    const payload = {
+      index: this.indexName,
+      vector: vector,
+      topK: topK,
+      namespace: namespace,
+    };
+    const { data } = await this.http.post('/search', payload);
+    return (data.results || []).map((res: Record<string, unknown>) => ({
+      id: res['id'] as string,
+      score: res['score'] as number,
+      content: res['content'] as string,
+      metadata: res['metadata'] as Record<string, unknown>,
+    }));
+  }
+
+  async delete(id: string, namespace?: string): Promise<void> {
+    const key = namespace ? `${namespace}:${id}` : id;
+    await this.http.post('/', ['DEL', key]);
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async deleteNamespace(_namespace: string): Promise<void> {
+    // Redis doesn't have a direct "delete namespace" easily without SCAN
+  }
+
+  async ping(): Promise<boolean> {
+    try {
+      await this.http.post('/', ['PING']);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async disconnect(): Promise<void> {}
+}

package/src/providers/vectordb/WeaviateProvider.ts

@@ -0,0 +1,124 @@
+import axios, { AxiosInstance } from 'axios';
+import { VectorDBConfig } from '../../config/RagConfig';
+import { BaseVectorProvider } from './BaseVectorProvider';
+import { VectorMatch, UpsertDocument } from '../../types';
+
+/**
+ * WeaviateProvider — implementation for Weaviate using its REST/GraphQL API.
+ */
+export class WeaviateProvider extends BaseVectorProvider {
+  private http: AxiosInstance;
+
+  constructor(config: VectorDBConfig) {
+    super(config);
+    const opts = config.options as Record<string, unknown>;
+    const baseUrl = opts.baseUrl as string;
+    if (!baseUrl) throw new Error('[WeaviateProvider] baseUrl is required');
+
+    this.http = axios.create({
+      baseURL: baseUrl,
+      headers: {
+        'Content-Type': 'application/json',
+        ...(opts.apiKey ? { 
+          'X-OpenAI-Api-Key': opts.apiKey as string, 
+          'Authorization': `Bearer ${opts.apiKey as string}` 
+        } : {}),
+      },
+    });
+  }
+
+  async initialize(): Promise<void> {
+    await this.ping();
+  }
+
+  async upsert(doc: UpsertDocument, namespace?: string): Promise<void> {
+    const payload = {
+      class: this.indexName,
+      id: doc.id,
+      vector: doc.vector,
+      properties: {
+        content: doc.content,
+        metadata: JSON.stringify(doc.metadata || {}),
+        namespace: namespace || '',
+      },
+    };
+    await this.http.post('/v1/objects', payload);
+  }
+
+  async batchUpsert(docs: UpsertDocument[], namespace?: string): Promise<void> {
+    const payload = {
+      objects: docs.map(doc => ({
+        class: this.indexName,
+        id: doc.id,
+        vector: doc.vector,
+        properties: {
+          content: doc.content,
+          metadata: JSON.stringify(doc.metadata || {}),
+          namespace: namespace || '',
+        },
+      })),
+    };
+    await this.http.post('/v1/batch/objects', payload);
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async query(vector: number[], topK: number, namespace?: string, _filter?: Record<string, unknown>): Promise<VectorMatch[]> {
+    const graphqlQuery = {
+      query: `
+        {
+          Get {
+            ${this.indexName}(
+              nearVector: {
+                vector: ${JSON.stringify(vector)}
+              }
+              limit: ${topK}
+              ${namespace ? `where: { path: ["namespace"], operator: Equal, valueString: "${namespace}" }` : ''}
+            ) {
+              content
+              metadata
+              _additional {
+                id
+                distance
+              }
+            }
+          }
+        }
+      `
+    };
+    const { data } = await this.http.post('/v1/graphql', graphqlQuery);
+    const results = data.data?.Get?.[this.indexName] || [];
+    
+    return results.map((res: Record<string, unknown>) => ({
+      id: (res['_additional'] as Record<string, unknown>).id as string,
+      score: 1 - ((res['_additional'] as Record<string, unknown>).distance as number),
+      content: res['content'] as string,
+      metadata: res['metadata'] ? JSON.parse(res['metadata'] as string) : {},
+    }));
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async delete(id: string, _namespace?: string): Promise<void> {
+    await this.http.delete(`/v1/objects/${this.indexName}/${id}`);
+  }
+
+  async deleteNamespace(namespace: string): Promise<void> {
+    // Weaviate batch delete
+    await this.http.post('/v1/batch/objects', {
+      match: {
+        class: this.indexName,
+        where: { path: ['namespace'], operator: 'Equal', valueString: namespace }
+      }
+    });
+  }
+
+  async ping(): Promise<boolean> {
+    try {
+      await this.http.get('/v1/.well-known/live');
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async disconnect(): Promise<void> {}
+}

package/src/server.ts

@@ -5,21 +5,29 @@
 
 // ── Shared Types (Safe for both) ──────────────────────────────
 export type { RagConfig, VectorDBConfig, LLMConfig, EmbeddingConfig, UIConfig, RAGConfig } from './config/RagConfig';
-export type { IVectorDB, VectorMatch, UpsertDocument } from './vectordb/IVectorDB';
+export type { VectorMatch, UpsertDocument } from './types';
 export type { ILLMProvider, ChatMessage, ChatOptions, EmbedOptions } from './llm/ILLMProvider';
-export type { IngestDocument, ChatResponse } from './rag/RAGPipeline';
+export type { IngestDocument, ChatResponse } from './types';
 export type { Chunk, ChunkOptions } from './rag/DocumentChunker';
 
 // ── Server-Only Logic (Node.js dependent) ─────────────────────
-export { RAGPipeline } from './rag/RAGPipeline';
+export { VectorPlugin } from './core/VectorPlugin';
+export { Pipeline } from './core/Pipeline';
+export { ConfigResolver } from './core/ConfigResolver';
+export { ProviderRegistry } from './core/ProviderRegistry';
 export { DocumentChunker } from './rag/DocumentChunker';
 export { getRagConfig } from './config/serverConfig';
 
-// ── Factories & Adapters (Node.js dependent) ──────────────────
-export { VectorDBFactory } from './vectordb/VectorDBFactory';
-export { PineconeAdapter } from './vectordb/adapters/PineconeAdapter';
-export { PgVectorAdapter } from './vectordb/adapters/PgVectorAdapter';
-export { MongoDbAdapter } from './vectordb/adapters/MongoDbAdapter';
+// ── Providers (Node.js dependent) ─────────────────────────────
+export { BaseVectorProvider } from './providers/vectordb/BaseVectorProvider';
+export { PineconeProvider } from './providers/vectordb/PineconeProvider';
+export { PostgreSQLProvider } from './providers/vectordb/PostgreSQLProvider';
+export { MongoDBProvider } from './providers/vectordb/MongoDBProvider';
+export { MilvusProvider } from './providers/vectordb/MilvusProvider';
+export { QdrantProvider } from './providers/vectordb/QdrantProvider';
+export { ChromaDBProvider } from './providers/vectordb/ChromaDBProvider';
+export { RedisProvider } from './providers/vectordb/RedisProvider';
+export { WeaviateProvider } from './providers/vectordb/WeaviateProvider';
 
 export { LLMFactory } from './llm/LLMFactory';
 export { OpenAIProvider } from './llm/providers/OpenAIProvider';