@retrivora-ai/rag-engine 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/dist/DocumentChunker-BEyzadsv.d.mts +93 -0
  2. package/dist/DocumentChunker-BEyzadsv.d.ts +93 -0
  3. package/dist/{LLMFactory-XC55FTD2.mjs → LLMFactory-JFOY2V4X.mjs} +2 -1
  4. package/dist/{PineconeProvider-NJ675H7U.mjs → PineconeProvider-ZRAFNFEC.mjs} +1 -1
  5. package/dist/{PostgreSQLProvider-ISNMD3BE.mjs → PostgreSQLProvider-ZNXA67IM.mjs} +1 -1
  6. package/dist/{QdrantProvider-LJWOIGES.mjs → QdrantProvider-NYGHAA7C.mjs} +1 -1
  7. package/dist/{Pipeline-Bo6CUCox.d.mts → RagConfig-hBGXJmSx.d.mts} +23 -93
  8. package/dist/{Pipeline-Bo6CUCox.d.ts → RagConfig-hBGXJmSx.d.ts} +23 -93
  9. package/dist/{chunk-6FODXNUF.mjs → chunk-5K23H7JL.mjs} +27 -1
  10. package/dist/chunk-HSBXE2WV.mjs +1758 -0
  11. package/dist/{chunk-S5DRHETN.mjs → chunk-IUTAZ7QR.mjs} +31 -2
  12. package/dist/{chunk-GD3QJFNN.mjs → chunk-JI6VD5TJ.mjs} +4 -41
  13. package/dist/chunk-UKDXCXW7.mjs +49 -0
  14. package/dist/{chunk-AALIF3AL.mjs → chunk-ZM6TYIDH.mjs} +3 -3
  15. package/dist/handlers/index.d.mts +3 -44
  16. package/dist/handlers/index.d.ts +3 -44
  17. package/dist/handlers/index.js +1322 -57
  18. package/dist/handlers/index.mjs +3 -3
  19. package/dist/index-Bx182KKn.d.ts +64 -0
  20. package/dist/index-Ck2pt7-8.d.mts +64 -0
  21. package/dist/index.d.mts +4 -3
  22. package/dist/index.d.ts +4 -3
  23. package/dist/index.js +19 -1646
  24. package/dist/index.mjs +1 -11
  25. package/dist/server.d.mts +188 -11
  26. package/dist/server.d.ts +188 -11
  27. package/dist/server.js +1322 -57
  28. package/dist/server.mjs +10 -11
  29. package/package.json +20 -2
  30. package/src/config/serverConfig.ts +3 -0
  31. package/src/core/BatchProcessor.ts +347 -0
  32. package/src/core/ConfigValidator.ts +560 -0
  33. package/src/core/Pipeline.ts +91 -49
  34. package/src/core/ProviderHealthCheck.ts +565 -0
  35. package/src/core/VectorPlugin.ts +51 -9
  36. package/src/handlers/index.ts +2 -2
  37. package/src/index.ts +1 -7
  38. package/src/providers/vectordb/BaseVectorProvider.ts +1 -1
  39. package/src/providers/vectordb/MilvusProvider.ts +1 -1
  40. package/src/providers/vectordb/MongoDBProvider.ts +1 -1
  41. package/src/providers/vectordb/PineconeProvider.ts +4 -4
  42. package/src/providers/vectordb/PostgreSQLProvider.ts +35 -3
  43. package/src/providers/vectordb/QdrantProvider.ts +32 -2
  44. package/src/rag/DocumentChunker.ts +2 -2
  45. package/src/server.ts +1 -1
  46. package/src/types/index.ts +13 -2
  47. package/dist/DocumentChunker-BQ5kQD7B.d.ts +0 -155
  48. package/dist/DocumentChunker-D9-fObJp.d.mts +0 -155
  49. package/dist/chunk-AIAB2IEE.mjs +0 -394
  50. package/dist/chunk-FGGSVVSY.mjs +0 -162
package/dist/index.mjs CHANGED
@@ -1,12 +1,6 @@
1
- import {
2
- ConfigResolver,
3
- Pipeline,
4
- ProviderRegistry,
5
- VectorPlugin
6
- } from "./chunk-AIAB2IEE.mjs";
7
1
  import {
8
2
  mergeDefined
9
- } from "./chunk-GD3QJFNN.mjs";
3
+ } from "./chunk-UKDXCXW7.mjs";
10
4
  import {
11
5
  __spreadValues
12
6
  } from "./chunk-I4E63NIC.mjs";
@@ -553,12 +547,8 @@ export {
553
547
  ChatWidget,
554
548
  ChatWindow,
555
549
  ConfigProvider,
556
- ConfigResolver,
557
550
  MessageBubble,
558
- Pipeline,
559
- ProviderRegistry,
560
551
  SourceCard,
561
- VectorPlugin,
562
552
  useConfig,
563
553
  useRagChat
564
554
  };
package/dist/server.d.mts CHANGED
@@ -1,10 +1,182 @@
1
- import { e as RagConfig, g as VectorDBConfig, f as UpsertDocument, V as VectorMatch, L as LLMConfig, c as EmbeddingConfig, I as ILLMProvider, C as ChatMessage, a as ChatOptions, E as EmbedOptions } from './Pipeline-Bo6CUCox.mjs';
2
- export { b as ChatResponse, d as IngestDocument, P as Pipeline, R as RAGConfig, U as UIConfig } from './Pipeline-Bo6CUCox.mjs';
3
- import { B as BaseVectorProvider } from './DocumentChunker-D9-fObJp.mjs';
4
- export { C as Chunk, a as ChunkOptions, b as ConfigResolver, D as DocumentChunker, P as ProviderRegistry, V as VectorPlugin } from './DocumentChunker-D9-fObJp.mjs';
5
- export { createChatHandler, createHealthHandler, createIngestHandler, createUploadHandler } from './handlers/index.mjs';
1
+ import { a as RagConfig, C as ChatResponse, I as IngestDocument, c as VectorDBConfig, b as UpsertDocument, V as VectorMatch, L as LLMConfig, E as EmbeddingConfig } from './RagConfig-hBGXJmSx.mjs';
2
+ export { R as RAGConfig, U as UIConfig } from './RagConfig-hBGXJmSx.mjs';
3
+ import { C as ChatMessage, I as ILLMProvider, a as ChatOptions, E as EmbedOptions } from './DocumentChunker-BEyzadsv.mjs';
4
+ export { b as Chunk, c as ChunkOptions, D as DocumentChunker } from './DocumentChunker-BEyzadsv.mjs';
5
+ import { H as HealthCheckResult } from './index-Ck2pt7-8.mjs';
6
+ export { c as createChatHandler, a as createHealthHandler, b as createIngestHandler, d as createUploadHandler } from './index-Ck2pt7-8.mjs';
6
7
  import 'next/server';
7
8
 
9
+ /**
10
+ * VectorPlugin — main orchestrator class.
11
+ * This is the primary interface for host applications.
12
+ *
13
+ * Features:
14
+ * - Configuration resolution from host + environment
15
+ * - Configuration validation with detailed error messages
16
+ * - Provider health checks before initialization
17
+ * - Multi-provider support (Vector DBs & LLMs)
18
+ * - Per-tenant data isolation via namespacing
19
+ */
20
+ declare class VectorPlugin {
21
+ private config;
22
+ private pipeline;
23
+ /**
24
+ * Initializes the plugin with the host configuration.
25
+ * @param hostConfig - Configuration object passed from the host application.
26
+ * @throws Error if configuration is invalid or providers are unhealthy
27
+ *
28
+ * @example
29
+ * const plugin = new VectorPlugin({
30
+ * projectId: 'my-app',
31
+ * vectorDb: {
32
+ * provider: 'pinecone',
33
+ * indexName: 'my-index',
34
+ * options: { apiKey: process.env.PINECONE_API_KEY }
35
+ * },
36
+ * llm: {
37
+ * provider: 'openai',
38
+ * model: 'gpt-4o',
39
+ * apiKey: process.env.OPENAI_API_KEY
40
+ * }
41
+ * });
42
+ */
43
+ constructor(hostConfig?: Partial<RagConfig>);
44
+ /**
45
+ * Get the current resolved configuration.
46
+ */
47
+ getConfig(): RagConfig;
48
+ /**
49
+ * Perform pre-flight health checks on all configured providers.
50
+ * Useful to verify connectivity before running operations.
51
+ *
52
+ * @returns Health status for vector DB, LLM, and embedding providers
53
+ */
54
+ checkHealth(): Promise<{
55
+ vectorDb: HealthCheckResult;
56
+ llm: HealthCheckResult;
57
+ embedding?: HealthCheckResult;
58
+ allHealthy: boolean;
59
+ }>;
60
+ /**
61
+ * Run a chat query.
62
+ */
63
+ chat(message: string, history?: ChatMessage[], namespace?: string): Promise<ChatResponse>;
64
+ /**
65
+ * Ingest documents into the vector database.
66
+ */
67
+ ingest(documents: IngestDocument[], namespace?: string): Promise<Array<{
68
+ docId: string | number;
69
+ chunksIngested: number;
70
+ }>>;
71
+ }
72
+
73
+ /**
74
+ * Pipeline — orchestrates the RAG flow: Embed → Search → Augment → Generate.
75
+ *
76
+ * Features:
77
+ * - Lazy initialization of providers
78
+ * - Batch processing with retry logic
79
+ * - Configurable embedding strategies
80
+ * - Error recovery for transient failures
81
+ * - Support for multi-tenancy via namespacing
82
+ */
83
+ declare class Pipeline {
84
+ private vectorDB;
85
+ private llmProvider;
86
+ private embeddingProvider;
87
+ private chunker;
88
+ private config;
89
+ private initialised;
90
+ constructor(config: RagConfig);
91
+ initialize(): Promise<void>;
92
+ /**
93
+ * Ingest documents with automatic chunking, embedding, and batch processing.
94
+ * Handles retries for transient failures.
95
+ */
96
+ ingest(documents: IngestDocument[], namespace?: string): Promise<Array<{
97
+ docId: string | number;
98
+ chunksIngested: number;
99
+ }>>;
100
+ ask(question: string, history?: ChatMessage[], namespace?: string): Promise<ChatResponse>;
101
+ }
102
+
103
+ /**
104
+ * ConfigResolver — validates and normalizes host configuration.
105
+ * It merges host-provided config with environment defaults.
106
+ */
107
+ declare class ConfigResolver {
108
+ /**
109
+ * Resolves the final configuration by merging host-provided config with defaults.
110
+ * @param hostConfig - Partial configuration passed from the host application.
111
+ */
112
+ static resolve(hostConfig?: Partial<RagConfig>): RagConfig;
113
+ /**
114
+ * Validates the configuration for required fields.
115
+ */
116
+ static validate(config: RagConfig): void;
117
+ }
118
+
119
+ /**
120
+ * BaseVectorProvider — Abstract base class for all vector database providers.
121
+ * Each provider (Pinecone, Milvus, Redis, etc.) must extend this class.
122
+ */
123
+ declare abstract class BaseVectorProvider {
124
+ protected readonly config: VectorDBConfig;
125
+ protected readonly indexName: string;
126
+ constructor(config: VectorDBConfig);
127
+ /**
128
+ * Initialise the connection (create tables, verify index, etc.)
129
+ */
130
+ abstract initialize(): Promise<void>;
131
+ /**
132
+ * Insert or update a single vector + content pair.
133
+ */
134
+ abstract upsert(doc: UpsertDocument, namespace?: string): Promise<void>;
135
+ /**
136
+ * Batch upsert for efficient ingestion of many documents.
137
+ */
138
+ abstract batchUpsert(docs: UpsertDocument[], namespace?: string): Promise<void>;
139
+ /**
140
+ * Find the top-K most similar vectors to the query vector.
141
+ */
142
+ abstract query(vector: number[], topK: number, namespace?: string, filter?: Record<string, unknown>): Promise<VectorMatch[]>;
143
+ /**
144
+ * Delete a stored vector by ID.
145
+ */
146
+ abstract delete(id: string | number, namespace?: string): Promise<void>;
147
+ /**
148
+ * Delete all vectors in a namespace (full data reset for a project).
149
+ */
150
+ abstract deleteNamespace(namespace: string): Promise<void>;
151
+ /**
152
+ * Check if the underlying DB is reachable.
153
+ */
154
+ abstract ping(): Promise<boolean>;
155
+ /**
156
+ * Gracefully close the connection.
157
+ */
158
+ abstract disconnect(): Promise<void>;
159
+ }
160
+
161
+ /**
162
+ * ProviderRegistry — dynamic provider loader for Vector DBs and LLMs.
163
+ */
164
+ declare class ProviderRegistry {
165
+ private static vectorProviders;
166
+ /**
167
+ * Register a custom vector provider.
168
+ */
169
+ static registerVectorProvider(name: string, providerClass: new (config: VectorDBConfig) => BaseVectorProvider): void;
170
+ /**
171
+ * Creates a vector database provider based on the configuration.
172
+ */
173
+ static createVectorProvider(config: VectorDBConfig): Promise<BaseVectorProvider>;
174
+ /**
175
+ * Creates an LLM provider based on the configuration.
176
+ */
177
+ static createLLMProvider(llmConfig: LLMConfig, embeddingConfig?: EmbeddingConfig): ILLMProvider;
178
+ }
179
+
8
180
  /**
9
181
  * serverConfig.ts — reads RagConfig from environment variables at runtime.
10
182
  *
@@ -23,7 +195,7 @@ declare class PineconeProvider extends BaseVectorProvider {
23
195
  upsert(doc: UpsertDocument, namespace?: string): Promise<void>;
24
196
  batchUpsert(docs: UpsertDocument[], namespace?: string): Promise<void>;
25
197
  query(vector: number[], topK: number, namespace?: string, filter?: Record<string, unknown>): Promise<VectorMatch[]>;
26
- delete(id: string, namespace?: string): Promise<void>;
198
+ delete(id: string | number, namespace?: string): Promise<void>;
27
199
  deleteNamespace(namespace: string): Promise<void>;
28
200
  ping(): Promise<boolean>;
29
201
  disconnect(): Promise<void>;
@@ -42,7 +214,7 @@ declare class PostgreSQLProvider extends BaseVectorProvider {
42
214
  upsert(doc: UpsertDocument, namespace?: string): Promise<void>;
43
215
  batchUpsert(docs: UpsertDocument[], namespace?: string): Promise<void>;
44
216
  query(vector: number[], topK: number, namespace?: string, filter?: Record<string, unknown>): Promise<VectorMatch[]>;
45
- delete(id: string, namespace?: string): Promise<void>;
217
+ delete(id: string | number, namespace?: string): Promise<void>;
46
218
  deleteNamespace(namespace: string): Promise<void>;
47
219
  ping(): Promise<boolean>;
48
220
  disconnect(): Promise<void>;
@@ -65,7 +237,7 @@ declare class MongoDBProvider extends BaseVectorProvider {
65
237
  upsert(doc: UpsertDocument, namespace?: string): Promise<void>;
66
238
  batchUpsert(docs: UpsertDocument[], namespace?: string): Promise<void>;
67
239
  query(vector: number[], topK: number, namespace?: string, filter?: Record<string, unknown>): Promise<VectorMatch[]>;
68
- delete(id: string, namespace?: string): Promise<void>;
240
+ delete(id: string | number, namespace?: string): Promise<void>;
69
241
  deleteNamespace(namespace: string): Promise<void>;
70
242
  ping(): Promise<boolean>;
71
243
  disconnect(): Promise<void>;
@@ -81,7 +253,7 @@ declare class MilvusProvider extends BaseVectorProvider {
81
253
  upsert(doc: UpsertDocument, namespace?: string): Promise<void>;
82
254
  batchUpsert(docs: UpsertDocument[], namespace?: string): Promise<void>;
83
255
  query(vector: number[], topK: number, namespace?: string, _filter?: Record<string, unknown>): Promise<VectorMatch[]>;
84
- delete(id: string, _namespace?: string): Promise<void>;
256
+ delete(id: string | number, _namespace?: string): Promise<void>;
85
257
  deleteNamespace(_namespace: string): Promise<void>;
86
258
  ping(): Promise<boolean>;
87
259
  disconnect(): Promise<void>;
@@ -94,10 +266,15 @@ declare class QdrantProvider extends BaseVectorProvider {
94
266
  private http;
95
267
  constructor(config: VectorDBConfig);
96
268
  initialize(): Promise<void>;
269
+ /**
270
+ * Ensures that the 'namespace' field has a keyword index for efficient filtering.
271
+ * Qdrant requires this for search filters to work in many configurations.
272
+ */
273
+ private ensureIndex;
97
274
  upsert(doc: UpsertDocument, namespace?: string): Promise<void>;
98
275
  batchUpsert(docs: UpsertDocument[], namespace?: string): Promise<void>;
99
276
  query(vector: number[], topK: number, namespace?: string, _filter?: Record<string, unknown>): Promise<VectorMatch[]>;
100
- delete(id: string, _namespace?: string): Promise<void>;
277
+ delete(id: string | number, _namespace?: string): Promise<void>;
101
278
  deleteNamespace(_namespace: string): Promise<void>;
102
279
  ping(): Promise<boolean>;
103
280
  disconnect(): Promise<void>;
@@ -245,4 +422,4 @@ declare class OllamaProvider implements ILLMProvider {
245
422
  ping(): Promise<boolean>;
246
423
  }
247
424
 
248
- export { AnthropicProvider, BaseVectorProvider, ChatMessage, ChatOptions, ChromaDBProvider, EmbedOptions, EmbeddingConfig, ILLMProvider, LLMConfig, LLMFactory, MilvusProvider, MongoDBProvider, OllamaProvider, OpenAIProvider, PineconeProvider, PostgreSQLProvider, QdrantProvider, RagConfig, RedisProvider, UpsertDocument, VectorDBConfig, VectorMatch, WeaviateProvider, getRagConfig };
425
+ export { AnthropicProvider, BaseVectorProvider, ChatMessage, ChatOptions, ChatResponse, ChromaDBProvider, ConfigResolver, EmbedOptions, EmbeddingConfig, ILLMProvider, IngestDocument, LLMConfig, LLMFactory, MilvusProvider, MongoDBProvider, OllamaProvider, OpenAIProvider, PineconeProvider, Pipeline, PostgreSQLProvider, ProviderRegistry, QdrantProvider, RagConfig, RedisProvider, UpsertDocument, VectorDBConfig, VectorMatch, VectorPlugin, WeaviateProvider, getRagConfig };
package/dist/server.d.ts CHANGED
@@ -1,10 +1,182 @@
1
- import { e as RagConfig, g as VectorDBConfig, f as UpsertDocument, V as VectorMatch, L as LLMConfig, c as EmbeddingConfig, I as ILLMProvider, C as ChatMessage, a as ChatOptions, E as EmbedOptions } from './Pipeline-Bo6CUCox.js';
2
- export { b as ChatResponse, d as IngestDocument, P as Pipeline, R as RAGConfig, U as UIConfig } from './Pipeline-Bo6CUCox.js';
3
- import { B as BaseVectorProvider } from './DocumentChunker-BQ5kQD7B.js';
4
- export { C as Chunk, a as ChunkOptions, b as ConfigResolver, D as DocumentChunker, P as ProviderRegistry, V as VectorPlugin } from './DocumentChunker-BQ5kQD7B.js';
5
- export { createChatHandler, createHealthHandler, createIngestHandler, createUploadHandler } from './handlers/index.js';
1
+ import { a as RagConfig, C as ChatResponse, I as IngestDocument, c as VectorDBConfig, b as UpsertDocument, V as VectorMatch, L as LLMConfig, E as EmbeddingConfig } from './RagConfig-hBGXJmSx.js';
2
+ export { R as RAGConfig, U as UIConfig } from './RagConfig-hBGXJmSx.js';
3
+ import { C as ChatMessage, I as ILLMProvider, a as ChatOptions, E as EmbedOptions } from './DocumentChunker-BEyzadsv.js';
4
+ export { b as Chunk, c as ChunkOptions, D as DocumentChunker } from './DocumentChunker-BEyzadsv.js';
5
+ import { H as HealthCheckResult } from './index-Bx182KKn.js';
6
+ export { c as createChatHandler, a as createHealthHandler, b as createIngestHandler, d as createUploadHandler } from './index-Bx182KKn.js';
6
7
  import 'next/server';
7
8
 
9
+ /**
10
+ * VectorPlugin — main orchestrator class.
11
+ * This is the primary interface for host applications.
12
+ *
13
+ * Features:
14
+ * - Configuration resolution from host + environment
15
+ * - Configuration validation with detailed error messages
16
+ * - Provider health checks before initialization
17
+ * - Multi-provider support (Vector DBs & LLMs)
18
+ * - Per-tenant data isolation via namespacing
19
+ */
20
+ declare class VectorPlugin {
21
+ private config;
22
+ private pipeline;
23
+ /**
24
+ * Initializes the plugin with the host configuration.
25
+ * @param hostConfig - Configuration object passed from the host application.
26
+ * @throws Error if configuration is invalid or providers are unhealthy
27
+ *
28
+ * @example
29
+ * const plugin = new VectorPlugin({
30
+ * projectId: 'my-app',
31
+ * vectorDb: {
32
+ * provider: 'pinecone',
33
+ * indexName: 'my-index',
34
+ * options: { apiKey: process.env.PINECONE_API_KEY }
35
+ * },
36
+ * llm: {
37
+ * provider: 'openai',
38
+ * model: 'gpt-4o',
39
+ * apiKey: process.env.OPENAI_API_KEY
40
+ * }
41
+ * });
42
+ */
43
+ constructor(hostConfig?: Partial<RagConfig>);
44
+ /**
45
+ * Get the current resolved configuration.
46
+ */
47
+ getConfig(): RagConfig;
48
+ /**
49
+ * Perform pre-flight health checks on all configured providers.
50
+ * Useful to verify connectivity before running operations.
51
+ *
52
+ * @returns Health status for vector DB, LLM, and embedding providers
53
+ */
54
+ checkHealth(): Promise<{
55
+ vectorDb: HealthCheckResult;
56
+ llm: HealthCheckResult;
57
+ embedding?: HealthCheckResult;
58
+ allHealthy: boolean;
59
+ }>;
60
+ /**
61
+ * Run a chat query.
62
+ */
63
+ chat(message: string, history?: ChatMessage[], namespace?: string): Promise<ChatResponse>;
64
+ /**
65
+ * Ingest documents into the vector database.
66
+ */
67
+ ingest(documents: IngestDocument[], namespace?: string): Promise<Array<{
68
+ docId: string | number;
69
+ chunksIngested: number;
70
+ }>>;
71
+ }
72
+
73
+ /**
74
+ * Pipeline — orchestrates the RAG flow: Embed → Search → Augment → Generate.
75
+ *
76
+ * Features:
77
+ * - Lazy initialization of providers
78
+ * - Batch processing with retry logic
79
+ * - Configurable embedding strategies
80
+ * - Error recovery for transient failures
81
+ * - Support for multi-tenancy via namespacing
82
+ */
83
+ declare class Pipeline {
84
+ private vectorDB;
85
+ private llmProvider;
86
+ private embeddingProvider;
87
+ private chunker;
88
+ private config;
89
+ private initialised;
90
+ constructor(config: RagConfig);
91
+ initialize(): Promise<void>;
92
+ /**
93
+ * Ingest documents with automatic chunking, embedding, and batch processing.
94
+ * Handles retries for transient failures.
95
+ */
96
+ ingest(documents: IngestDocument[], namespace?: string): Promise<Array<{
97
+ docId: string | number;
98
+ chunksIngested: number;
99
+ }>>;
100
+ ask(question: string, history?: ChatMessage[], namespace?: string): Promise<ChatResponse>;
101
+ }
102
+
103
+ /**
104
+ * ConfigResolver — validates and normalizes host configuration.
105
+ * It merges host-provided config with environment defaults.
106
+ */
107
+ declare class ConfigResolver {
108
+ /**
109
+ * Resolves the final configuration by merging host-provided config with defaults.
110
+ * @param hostConfig - Partial configuration passed from the host application.
111
+ */
112
+ static resolve(hostConfig?: Partial<RagConfig>): RagConfig;
113
+ /**
114
+ * Validates the configuration for required fields.
115
+ */
116
+ static validate(config: RagConfig): void;
117
+ }
118
+
119
+ /**
120
+ * BaseVectorProvider — Abstract base class for all vector database providers.
121
+ * Each provider (Pinecone, Milvus, Redis, etc.) must extend this class.
122
+ */
123
+ declare abstract class BaseVectorProvider {
124
+ protected readonly config: VectorDBConfig;
125
+ protected readonly indexName: string;
126
+ constructor(config: VectorDBConfig);
127
+ /**
128
+ * Initialise the connection (create tables, verify index, etc.)
129
+ */
130
+ abstract initialize(): Promise<void>;
131
+ /**
132
+ * Insert or update a single vector + content pair.
133
+ */
134
+ abstract upsert(doc: UpsertDocument, namespace?: string): Promise<void>;
135
+ /**
136
+ * Batch upsert for efficient ingestion of many documents.
137
+ */
138
+ abstract batchUpsert(docs: UpsertDocument[], namespace?: string): Promise<void>;
139
+ /**
140
+ * Find the top-K most similar vectors to the query vector.
141
+ */
142
+ abstract query(vector: number[], topK: number, namespace?: string, filter?: Record<string, unknown>): Promise<VectorMatch[]>;
143
+ /**
144
+ * Delete a stored vector by ID.
145
+ */
146
+ abstract delete(id: string | number, namespace?: string): Promise<void>;
147
+ /**
148
+ * Delete all vectors in a namespace (full data reset for a project).
149
+ */
150
+ abstract deleteNamespace(namespace: string): Promise<void>;
151
+ /**
152
+ * Check if the underlying DB is reachable.
153
+ */
154
+ abstract ping(): Promise<boolean>;
155
+ /**
156
+ * Gracefully close the connection.
157
+ */
158
+ abstract disconnect(): Promise<void>;
159
+ }
160
+
161
+ /**
162
+ * ProviderRegistry — dynamic provider loader for Vector DBs and LLMs.
163
+ */
164
+ declare class ProviderRegistry {
165
+ private static vectorProviders;
166
+ /**
167
+ * Register a custom vector provider.
168
+ */
169
+ static registerVectorProvider(name: string, providerClass: new (config: VectorDBConfig) => BaseVectorProvider): void;
170
+ /**
171
+ * Creates a vector database provider based on the configuration.
172
+ */
173
+ static createVectorProvider(config: VectorDBConfig): Promise<BaseVectorProvider>;
174
+ /**
175
+ * Creates an LLM provider based on the configuration.
176
+ */
177
+ static createLLMProvider(llmConfig: LLMConfig, embeddingConfig?: EmbeddingConfig): ILLMProvider;
178
+ }
179
+
8
180
  /**
9
181
  * serverConfig.ts — reads RagConfig from environment variables at runtime.
10
182
  *
@@ -23,7 +195,7 @@ declare class PineconeProvider extends BaseVectorProvider {
23
195
  upsert(doc: UpsertDocument, namespace?: string): Promise<void>;
24
196
  batchUpsert(docs: UpsertDocument[], namespace?: string): Promise<void>;
25
197
  query(vector: number[], topK: number, namespace?: string, filter?: Record<string, unknown>): Promise<VectorMatch[]>;
26
- delete(id: string, namespace?: string): Promise<void>;
198
+ delete(id: string | number, namespace?: string): Promise<void>;
27
199
  deleteNamespace(namespace: string): Promise<void>;
28
200
  ping(): Promise<boolean>;
29
201
  disconnect(): Promise<void>;
@@ -42,7 +214,7 @@ declare class PostgreSQLProvider extends BaseVectorProvider {
42
214
  upsert(doc: UpsertDocument, namespace?: string): Promise<void>;
43
215
  batchUpsert(docs: UpsertDocument[], namespace?: string): Promise<void>;
44
216
  query(vector: number[], topK: number, namespace?: string, filter?: Record<string, unknown>): Promise<VectorMatch[]>;
45
- delete(id: string, namespace?: string): Promise<void>;
217
+ delete(id: string | number, namespace?: string): Promise<void>;
46
218
  deleteNamespace(namespace: string): Promise<void>;
47
219
  ping(): Promise<boolean>;
48
220
  disconnect(): Promise<void>;
@@ -65,7 +237,7 @@ declare class MongoDBProvider extends BaseVectorProvider {
65
237
  upsert(doc: UpsertDocument, namespace?: string): Promise<void>;
66
238
  batchUpsert(docs: UpsertDocument[], namespace?: string): Promise<void>;
67
239
  query(vector: number[], topK: number, namespace?: string, filter?: Record<string, unknown>): Promise<VectorMatch[]>;
68
- delete(id: string, namespace?: string): Promise<void>;
240
+ delete(id: string | number, namespace?: string): Promise<void>;
69
241
  deleteNamespace(namespace: string): Promise<void>;
70
242
  ping(): Promise<boolean>;
71
243
  disconnect(): Promise<void>;
@@ -81,7 +253,7 @@ declare class MilvusProvider extends BaseVectorProvider {
81
253
  upsert(doc: UpsertDocument, namespace?: string): Promise<void>;
82
254
  batchUpsert(docs: UpsertDocument[], namespace?: string): Promise<void>;
83
255
  query(vector: number[], topK: number, namespace?: string, _filter?: Record<string, unknown>): Promise<VectorMatch[]>;
84
- delete(id: string, _namespace?: string): Promise<void>;
256
+ delete(id: string | number, _namespace?: string): Promise<void>;
85
257
  deleteNamespace(_namespace: string): Promise<void>;
86
258
  ping(): Promise<boolean>;
87
259
  disconnect(): Promise<void>;
@@ -94,10 +266,15 @@ declare class QdrantProvider extends BaseVectorProvider {
94
266
  private http;
95
267
  constructor(config: VectorDBConfig);
96
268
  initialize(): Promise<void>;
269
+ /**
270
+ * Ensures that the 'namespace' field has a keyword index for efficient filtering.
271
+ * Qdrant requires this for search filters to work in many configurations.
272
+ */
273
+ private ensureIndex;
97
274
  upsert(doc: UpsertDocument, namespace?: string): Promise<void>;
98
275
  batchUpsert(docs: UpsertDocument[], namespace?: string): Promise<void>;
99
276
  query(vector: number[], topK: number, namespace?: string, _filter?: Record<string, unknown>): Promise<VectorMatch[]>;
100
- delete(id: string, _namespace?: string): Promise<void>;
277
+ delete(id: string | number, _namespace?: string): Promise<void>;
101
278
  deleteNamespace(_namespace: string): Promise<void>;
102
279
  ping(): Promise<boolean>;
103
280
  disconnect(): Promise<void>;
@@ -245,4 +422,4 @@ declare class OllamaProvider implements ILLMProvider {
245
422
  ping(): Promise<boolean>;
246
423
  }
247
424
 
248
- export { AnthropicProvider, BaseVectorProvider, ChatMessage, ChatOptions, ChromaDBProvider, EmbedOptions, EmbeddingConfig, ILLMProvider, LLMConfig, LLMFactory, MilvusProvider, MongoDBProvider, OllamaProvider, OpenAIProvider, PineconeProvider, PostgreSQLProvider, QdrantProvider, RagConfig, RedisProvider, UpsertDocument, VectorDBConfig, VectorMatch, WeaviateProvider, getRagConfig };
425
+ export { AnthropicProvider, BaseVectorProvider, ChatMessage, ChatOptions, ChatResponse, ChromaDBProvider, ConfigResolver, EmbedOptions, EmbeddingConfig, ILLMProvider, IngestDocument, LLMConfig, LLMFactory, MilvusProvider, MongoDBProvider, OllamaProvider, OpenAIProvider, PineconeProvider, Pipeline, PostgreSQLProvider, ProviderRegistry, QdrantProvider, RagConfig, RedisProvider, UpsertDocument, VectorDBConfig, VectorMatch, VectorPlugin, WeaviateProvider, getRagConfig };