@retrivora-ai/rag-engine 1.9.3 → 1.9.7

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 (69) hide show
  1. package/README.md +59 -7
  2. package/dist/{ILLMProvider-Bw2A28nU.d.mts → ILLMProvider-Bhk6zJOK.d.mts} +43 -7
  3. package/dist/{ILLMProvider-Bw2A28nU.d.ts → ILLMProvider-Bhk6zJOK.d.ts} +43 -7
  4. package/dist/handlers/index.d.mts +2 -2
  5. package/dist/handlers/index.d.ts +2 -2
  6. package/dist/handlers/index.js +737 -237
  7. package/dist/handlers/index.mjs +736 -237
  8. package/dist/index-B9J_XEh0.d.ts +187 -0
  9. package/dist/index-BJ4cd-t5.d.mts +187 -0
  10. package/dist/{index-B70ZLkfG.d.mts → index-Bu7T6xgr.d.ts} +20 -3
  11. package/dist/{index-DVu-mkAM.d.ts → index-C3SVtPYg.d.mts} +20 -3
  12. package/dist/index.css +237 -10
  13. package/dist/index.d.mts +13 -5
  14. package/dist/index.d.ts +13 -5
  15. package/dist/index.js +365 -164
  16. package/dist/index.mjs +350 -158
  17. package/dist/server.d.mts +15 -94
  18. package/dist/server.d.ts +15 -94
  19. package/dist/server.js +850 -239
  20. package/dist/server.mjs +839 -238
  21. package/package.json +2 -4
  22. package/src/app/api/chat/route.ts +2 -2
  23. package/src/app/api/health/route.ts +3 -2
  24. package/src/app/api/ingest/route.ts +3 -2
  25. package/src/app/api/suggestions/route.ts +3 -2
  26. package/src/app/api/upload/route.ts +3 -2
  27. package/src/app/constants.tsx +168 -148
  28. package/src/app/layout.tsx +5 -18
  29. package/src/app/types.ts +17 -17
  30. package/src/components/ChatWidget.tsx +3 -1
  31. package/src/components/ChatWindow.tsx +5 -1
  32. package/src/components/DocViewer.tsx +71 -5
  33. package/src/components/Documentation.tsx +74 -11
  34. package/src/components/MessageBubble.tsx +39 -2
  35. package/src/components/ThinkingBlock.tsx +75 -0
  36. package/src/components/VisualizationRenderer.tsx +27 -1
  37. package/src/components/constants.tsx +275 -0
  38. package/src/config/RagConfig.ts +47 -0
  39. package/src/config/constants.ts +1 -0
  40. package/src/config/serverConfig.ts +25 -0
  41. package/src/core/ConfigResolver.ts +73 -22
  42. package/src/core/ConfigValidator.ts +2 -1
  43. package/src/core/Pipeline.ts +226 -68
  44. package/src/core/ProviderRegistry.ts +16 -7
  45. package/src/core/QueryProcessor.ts +38 -4
  46. package/src/core/Retrivora.ts +91 -0
  47. package/src/core/VectorPlugin.ts +62 -8
  48. package/src/exceptions/index.ts +111 -0
  49. package/src/handlers/index.ts +73 -0
  50. package/src/hooks/useRagChat.ts +30 -5
  51. package/src/index.ts +27 -1
  52. package/src/lib/plugin.ts +24 -0
  53. package/src/llm/LLMFactory.ts +8 -4
  54. package/src/llm/providers/AnthropicProvider.ts +70 -20
  55. package/src/llm/providers/GeminiProvider.ts +14 -15
  56. package/src/llm/providers/OllamaProvider.ts +13 -16
  57. package/src/llm/providers/OpenAIProvider.ts +9 -14
  58. package/src/llm/providers/UniversalLLMAdapter.ts +5 -5
  59. package/src/llm/utils.ts +46 -0
  60. package/src/providers/vectordb/MongoDBProvider.ts +9 -4
  61. package/src/providers/vectordb/MultiTablePostgresProvider.ts +45 -13
  62. package/src/rag/EntityExtractor.ts +2 -2
  63. package/src/rag/Reranker.ts +9 -16
  64. package/src/server.ts +30 -1
  65. package/src/types/chat.ts +9 -0
  66. package/src/types/props.ts +38 -1
  67. package/src/utils/UITransformer.ts +73 -4
  68. package/dist/DocumentChunker-Dh9TvmGG.d.mts +0 -45
  69. package/dist/DocumentChunker-Dh9TvmGG.d.ts +0 -45
package/README.md CHANGED
@@ -33,10 +33,24 @@ Retrivora AI acts as a universal bridge between your data and your users. It nor
33
33
 
34
34
  ### 📦 Installation
35
35
 
36
+ Install the core package using npm:
37
+
36
38
  ```bash
37
39
  npm install @retrivora-ai/rag-engine
38
40
  ```
39
41
 
42
+ #### 🎨 Auto-Injected Styles
43
+ To render the built-in UI components (like `ChatWidget`, `ChatWindow`, `DocumentUpload`) correctly, stylesheet rules are **auto-injected directly into the document `<head>` on load**. No manual CSS imports are required in your application layout!
44
+
45
+ *(Note: The raw stylesheet remains exported at `@retrivora-ai/rag-engine/style.css` if your custom bundler or setup requires manual stylesheet referencing).*
46
+
47
+ #### 🔌 Peer & Optional Dependencies
48
+ Depending on the specific database providers or features you use, you may need to install additional peer dependencies:
49
+ * **PostgreSQL / PGVector**: `npm install pg @types/pg`
50
+ * **MongoDB Atlas**: `npm install mongodb`
51
+ * **Word/PDF parsing capabilities**: `npm install mammoth pdf-parse`
52
+ * **Agentic/Semantic Chunking**: `npm install langchain llamaindex`
53
+
40
54
  ---
41
55
 
42
56
  ## 🛠️ Pluggable Architecture
@@ -51,8 +65,19 @@ This decoupling allows you to add custom providers without modifying the core en
51
65
 
52
66
  ## NPM Package Usage
53
67
 
68
+ The package exports are split between **client-side** and **server-side** entry points to keep server secrets/native packages safe from your React browser bundle.
69
+
70
+ | Import Path | Context | Exports |
71
+ |---|---|---|
72
+ | `@retrivora-ai/rag-engine` | **Client/Browser** | `ChatWidget`, `ChatWindow`, `ConfigProvider`, `useRagChat` |
73
+ | `@retrivora-ai/rag-engine/server` | **Server Only** | `Retrivora` (SDK facade), `Pipeline`, `ConfigBuilder`, custom exceptions |
74
+ | `@retrivora-ai/rag-engine/handlers` | **Server Only** | Next.js API Route Handler factories (e.g. `createRagHandler`, `createChatHandler`) |
75
+ | `@retrivora-ai/rag-engine/style.css` | **Universal** | Required CSS styles for custom bundler setups (auto-injected by default) |
76
+
54
77
  ### 1. Embed the ChatWidget
55
78
 
79
+ Drop the widget inside your application layout:
80
+
56
81
  ```tsx
57
82
  import { ConfigProvider, ChatWidget } from '@retrivora-ai/rag-engine';
58
83
 
@@ -76,16 +101,16 @@ export default function Layout({ children }) {
76
101
  }
77
102
  ```
78
103
 
79
- ### 2. Mount the API routes
104
+ ### 2. Mount Catch-All API Handler
105
+
106
+ Create a single dynamic catch-all route file to handle chat streaming, document upload, and suggestions automatically:
80
107
 
81
108
  ```ts
82
- // src/app/api/chat/route.ts
83
- import { createChatHandler, getRagConfig } from '@retrivora-ai/rag-engine/server';
84
- export const POST = createChatHandler(getRagConfig());
109
+ // src/app/api/retrivora/[[...retrivora]]/route.ts
110
+ import { createRagHandler } from '@retrivora-ai/rag-engine/handlers';
85
111
 
86
- // src/app/api/upload/route.ts
87
- import { createUploadHandler, getRagConfig } from '@retrivora-ai/rag-engine/server';
88
- export const POST = createUploadHandler(getRagConfig());
112
+ // Handles GET /api/retrivora/health and POST /api/retrivora/chat, upload, suggestions
113
+ export const { GET, POST } = createRagHandler();
89
114
  ```
90
115
 
91
116
  ### 3. Use Pipeline programmatically
@@ -103,6 +128,33 @@ await pipeline.ingest([{ docId: 'readme', content: 'Your document text here' }])
103
128
  const { reply, sources } = await pipeline.ask('What is the refund policy?');
104
129
  ```
105
130
 
131
+ ### 4. Use the Retrivora SDK facade
132
+
133
+ ```ts
134
+ import { Retrivora } from '@retrivora-ai/rag-engine/server';
135
+
136
+ const ai = new Retrivora({
137
+ llm: {
138
+ provider: 'openai',
139
+ model: 'gpt-5',
140
+ },
141
+ embedding: {
142
+ provider: 'openai',
143
+ },
144
+ vectorDatabase: {
145
+ provider: 'pinecone',
146
+ },
147
+ retrieval: {
148
+ strategy: 'hybrid',
149
+ },
150
+ workflow: {
151
+ type: 'agentic-rag',
152
+ },
153
+ });
154
+
155
+ const { reply, sources } = await ai.ask('What is the refund policy?');
156
+ ```
157
+
106
158
  ---
107
159
 
108
160
  ## Configuration Reference
package/dist/{ILLMProvider-Bw2A28nU.d.mts → ILLMProvider-Bhk6zJOK.d.mts} RENAMED
@@ -10,6 +10,13 @@ interface RagMessage extends ChatMessage {
10
10
  /** Full observability trace emitted by the backend. Only present on assistant messages. */
11
11
  trace?: ObservabilityTrace;
12
12
  createdAt: string;
13
+ /**
14
+ * Chain-of-thought reasoning from the LLM.
15
+ * Populated by native Anthropic extended thinking or simulated <think> tag stripping.
16
+ */
17
+ thinking?: string;
18
+ /** Wall-clock ms the model spent in the thinking phase. */
19
+ thinkingMs?: number;
13
20
  }
14
21
  interface ChatOptions {
15
22
  /** Override max tokens for this specific call */
@@ -36,6 +43,8 @@ interface UseRagChatOptions {
36
43
  onReply?: (message: RagMessage) => void;
37
44
  /** Called on error */
38
45
  onError?: (error: string) => void;
46
+ /** Optional custom headers to send with the chat request */
47
+ headers?: Record<string, string>;
39
48
  }
40
49
  interface UseRagChatReturn {
41
50
  /** All messages in the current conversation */
@@ -56,12 +65,6 @@ interface UseRagChatReturn {
56
65
  stop: () => void;
57
66
  }
58
67
 
59
- /**
60
- * constants.ts — Centralized definitions of acceptable configuration values.
61
- *
62
- * This file serves as the single source of truth for all statically supported
63
- * providers and stylistic options in the Retrivora AI RAG Engine.
64
- */
65
68
  declare const VECTOR_DB_PROVIDERS: readonly ["pinecone", "pgvector", "postgresql", "mongodb", "qdrant", "milvus", "chromadb", "redis", "weaviate", "rest", "universal_rest", "custom"];
66
69
  declare const LLM_PROVIDERS: readonly ["openai", "anthropic", "ollama", "gemini", "rest", "universal_rest", "custom"];
67
70
  declare const EMBEDDING_PROVIDERS: readonly ["openai", "ollama", "gemini", "rest", "universal_rest", "custom"];
@@ -227,6 +230,24 @@ interface RAGConfig {
227
230
  */
228
231
  vectorKeywords?: string[];
229
232
  }
233
+ interface RetrievalConfig {
234
+ /** Retrieval strategy selected by the host app. */
235
+ strategy?: 'vector' | 'keyword' | 'hybrid' | 'multi-query' | 'self-query' | 'parent-document' | 'contextual-compression' | 'ensemble' | 'recursive' | 'agentic';
236
+ /** Number of documents/chunks retrieved per query. */
237
+ topK?: number;
238
+ /** Minimum similarity score to include a retrieved chunk. */
239
+ scoreThreshold?: number;
240
+ /** Whether to rerank retrieved chunks before generation. */
241
+ useReranking?: boolean;
242
+ /** Provider-specific retrieval options for future strategies. */
243
+ options?: Record<string, unknown>;
244
+ }
245
+ interface WorkflowConfig {
246
+ /** High-level workflow selector from the SDK prompt. */
247
+ type?: 'simple-rag' | 'rag' | 'hybrid-rag' | 'graph-rag' | 'agentic-rag' | 'agentic';
248
+ /** Future workflow/provider-specific options. */
249
+ options?: Record<string, unknown>;
250
+ }
230
251
  interface RagConfig {
231
252
  /**
232
253
  * Unique identifier for the consuming project.
@@ -246,6 +267,21 @@ interface RagConfig {
246
267
  /** Optional Graph database configuration */
247
268
  graphDb?: GraphDBConfig;
248
269
  }
270
+ /**
271
+ * Friendly SDK configuration accepted by the top-level Retrivora facade.
272
+ * It supports the prompt's `vectorDatabase`, `retrieval`, and `workflow`
273
+ * naming while normalizing to the internal RagConfig shape.
274
+ */
275
+ type UniversalRagConfig = Partial<Omit<RagConfig, 'vectorDb' | 'rag' | 'llm' | 'embedding' | 'graphDb'>> & {
276
+ vectorDb?: Partial<VectorDBConfig>;
277
+ vectorDatabase?: Partial<VectorDBConfig>;
278
+ llm?: Partial<LLMConfig>;
279
+ embedding?: Partial<EmbeddingConfig>;
280
+ graphDb?: Partial<GraphDBConfig>;
281
+ retrieval?: RetrievalConfig;
282
+ rag?: RAGConfig;
283
+ workflow?: WorkflowConfig;
284
+ };
249
285
 
250
286
  /** Per-stage latency breakdown for a single RAG request. */
251
287
  interface LatencyBreakdown {
@@ -389,4 +425,4 @@ interface ILLMProvider {
389
425
  ping(): Promise<boolean>;
390
426
  }
391
427
 
392
- export type { ChatMessage as C, EmbedOptions as E, GraphDBConfig as G, ILLMProvider as I, LLMConfig as L, ObservabilityTrace as O, Product as P, RagMessage as R, TokenUsage as T, UIConfig as U, VectorMatch as V, UseRagChatOptions as a, UseRagChatReturn as b, ChatOptions as c, ChatResponse as d, EmbeddingConfig as e, EmbeddingProvider as f, IngestDocument as g, LLMProvider as h, LatencyBreakdown as i, RAGConfig as j, RagConfig as k, RetrievedChunk as l, UpsertDocument as m, VectorDBConfig as n, VectorDBProvider as o, RetrievalResult as p, GraphNode as q, Edge as r, GraphSearchResult as s };
428
+ export type { ChatMessage as C, EmbedOptions as E, GraphDBConfig as G, ILLMProvider as I, LLMConfig as L, ObservabilityTrace as O, Product as P, RagMessage as R, TokenUsage as T, UIConfig as U, VectorMatch as V, WorkflowConfig as W, UseRagChatOptions as a, UseRagChatReturn as b, ChatOptions as c, ChatResponse as d, EmbeddingConfig as e, EmbeddingProvider as f, IngestDocument as g, LLMProvider as h, LatencyBreakdown as i, RAGConfig as j, RagConfig as k, RetrievalConfig as l, RetrievedChunk as m, UniversalRagConfig as n, UpsertDocument as o, VectorDBConfig as p, VectorDBProvider as q, GraphNode as r, Edge as s, GraphSearchResult as t, RetrievalResult as u };
package/dist/{ILLMProvider-Bw2A28nU.d.ts → ILLMProvider-Bhk6zJOK.d.ts} RENAMED
@@ -10,6 +10,13 @@ interface RagMessage extends ChatMessage {
10
10
  /** Full observability trace emitted by the backend. Only present on assistant messages. */
11
11
  trace?: ObservabilityTrace;
12
12
  createdAt: string;
13
+ /**
14
+ * Chain-of-thought reasoning from the LLM.
15
+ * Populated by native Anthropic extended thinking or simulated <think> tag stripping.
16
+ */
17
+ thinking?: string;
18
+ /** Wall-clock ms the model spent in the thinking phase. */
19
+ thinkingMs?: number;
13
20
  }
14
21
  interface ChatOptions {
15
22
  /** Override max tokens for this specific call */
@@ -36,6 +43,8 @@ interface UseRagChatOptions {
36
43
  onReply?: (message: RagMessage) => void;
37
44
  /** Called on error */
38
45
  onError?: (error: string) => void;
46
+ /** Optional custom headers to send with the chat request */
47
+ headers?: Record<string, string>;
39
48
  }
40
49
  interface UseRagChatReturn {
41
50
  /** All messages in the current conversation */
@@ -56,12 +65,6 @@ interface UseRagChatReturn {
56
65
  stop: () => void;
57
66
  }
58
67
 
59
- /**
60
- * constants.ts — Centralized definitions of acceptable configuration values.
61
- *
62
- * This file serves as the single source of truth for all statically supported
63
- * providers and stylistic options in the Retrivora AI RAG Engine.
64
- */
65
68
  declare const VECTOR_DB_PROVIDERS: readonly ["pinecone", "pgvector", "postgresql", "mongodb", "qdrant", "milvus", "chromadb", "redis", "weaviate", "rest", "universal_rest", "custom"];
66
69
  declare const LLM_PROVIDERS: readonly ["openai", "anthropic", "ollama", "gemini", "rest", "universal_rest", "custom"];
67
70
  declare const EMBEDDING_PROVIDERS: readonly ["openai", "ollama", "gemini", "rest", "universal_rest", "custom"];
@@ -227,6 +230,24 @@ interface RAGConfig {
227
230
  */
228
231
  vectorKeywords?: string[];
229
232
  }
233
+ interface RetrievalConfig {
234
+ /** Retrieval strategy selected by the host app. */
235
+ strategy?: 'vector' | 'keyword' | 'hybrid' | 'multi-query' | 'self-query' | 'parent-document' | 'contextual-compression' | 'ensemble' | 'recursive' | 'agentic';
236
+ /** Number of documents/chunks retrieved per query. */
237
+ topK?: number;
238
+ /** Minimum similarity score to include a retrieved chunk. */
239
+ scoreThreshold?: number;
240
+ /** Whether to rerank retrieved chunks before generation. */
241
+ useReranking?: boolean;
242
+ /** Provider-specific retrieval options for future strategies. */
243
+ options?: Record<string, unknown>;
244
+ }
245
+ interface WorkflowConfig {
246
+ /** High-level workflow selector from the SDK prompt. */
247
+ type?: 'simple-rag' | 'rag' | 'hybrid-rag' | 'graph-rag' | 'agentic-rag' | 'agentic';
248
+ /** Future workflow/provider-specific options. */
249
+ options?: Record<string, unknown>;
250
+ }
230
251
  interface RagConfig {
231
252
  /**
232
253
  * Unique identifier for the consuming project.
@@ -246,6 +267,21 @@ interface RagConfig {
246
267
  /** Optional Graph database configuration */
247
268
  graphDb?: GraphDBConfig;
248
269
  }
270
+ /**
271
+ * Friendly SDK configuration accepted by the top-level Retrivora facade.
272
+ * It supports the prompt's `vectorDatabase`, `retrieval`, and `workflow`
273
+ * naming while normalizing to the internal RagConfig shape.
274
+ */
275
+ type UniversalRagConfig = Partial<Omit<RagConfig, 'vectorDb' | 'rag' | 'llm' | 'embedding' | 'graphDb'>> & {
276
+ vectorDb?: Partial<VectorDBConfig>;
277
+ vectorDatabase?: Partial<VectorDBConfig>;
278
+ llm?: Partial<LLMConfig>;
279
+ embedding?: Partial<EmbeddingConfig>;
280
+ graphDb?: Partial<GraphDBConfig>;
281
+ retrieval?: RetrievalConfig;
282
+ rag?: RAGConfig;
283
+ workflow?: WorkflowConfig;
284
+ };
249
285
 
250
286
  /** Per-stage latency breakdown for a single RAG request. */
251
287
  interface LatencyBreakdown {
@@ -389,4 +425,4 @@ interface ILLMProvider {
389
425
  ping(): Promise<boolean>;
390
426
  }
391
427
 
392
- export type { ChatMessage as C, EmbedOptions as E, GraphDBConfig as G, ILLMProvider as I, LLMConfig as L, ObservabilityTrace as O, Product as P, RagMessage as R, TokenUsage as T, UIConfig as U, VectorMatch as V, UseRagChatOptions as a, UseRagChatReturn as b, ChatOptions as c, ChatResponse as d, EmbeddingConfig as e, EmbeddingProvider as f, IngestDocument as g, LLMProvider as h, LatencyBreakdown as i, RAGConfig as j, RagConfig as k, RetrievedChunk as l, UpsertDocument as m, VectorDBConfig as n, VectorDBProvider as o, RetrievalResult as p, GraphNode as q, Edge as r, GraphSearchResult as s };
428
+ export type { ChatMessage as C, EmbedOptions as E, GraphDBConfig as G, ILLMProvider as I, LLMConfig as L, ObservabilityTrace as O, Product as P, RagMessage as R, TokenUsage as T, UIConfig as U, VectorMatch as V, WorkflowConfig as W, UseRagChatOptions as a, UseRagChatReturn as b, ChatOptions as c, ChatResponse as d, EmbeddingConfig as e, EmbeddingProvider as f, IngestDocument as g, LLMProvider as h, LatencyBreakdown as i, RAGConfig as j, RagConfig as k, RetrievalConfig as l, RetrievedChunk as m, UniversalRagConfig as n, UpsertDocument as o, VectorDBConfig as p, VectorDBProvider as q, GraphNode as r, Edge as s, GraphSearchResult as t, RetrievalResult as u };
package/dist/handlers/index.d.mts CHANGED
@@ -1,3 +1,3 @@
1
- import '../ILLMProvider-Bw2A28nU.mjs';
2
- export { c as createChatHandler, d as createHealthHandler, e as createIngestHandler, f as createStreamHandler, k as createSuggestionsHandler, g as createUploadHandler, s as sseErrorFrame, h as sseFrame, i as sseMetaFrame, l as sseObservabilityFrame, j as sseTextFrame, m as sseUIFrame } from '../index-B70ZLkfG.mjs';
1
+ import '../ILLMProvider-Bhk6zJOK.mjs';
2
+ export { c as createChatHandler, d as createHealthHandler, e as createIngestHandler, f as createRagHandler, g as createStreamHandler, l as createSuggestionsHandler, h as createUploadHandler, s as sseErrorFrame, i as sseFrame, j as sseMetaFrame, m as sseObservabilityFrame, k as sseTextFrame, n as sseUIFrame } from '../index-C3SVtPYg.mjs';
3
3
  import 'next/server';
package/dist/handlers/index.d.ts CHANGED
@@ -1,3 +1,3 @@
1
- import '../ILLMProvider-Bw2A28nU.js';
2
- export { c as createChatHandler, d as createHealthHandler, e as createIngestHandler, f as createStreamHandler, k as createSuggestionsHandler, g as createUploadHandler, s as sseErrorFrame, h as sseFrame, i as sseMetaFrame, l as sseObservabilityFrame, j as sseTextFrame, m as sseUIFrame } from '../index-DVu-mkAM.js';
1
+ import '../ILLMProvider-Bhk6zJOK.js';
2
+ export { c as createChatHandler, d as createHealthHandler, e as createIngestHandler, f as createRagHandler, g as createStreamHandler, l as createSuggestionsHandler, h as createUploadHandler, s as sseErrorFrame, i as sseFrame, j as sseMetaFrame, m as sseObservabilityFrame, k as sseTextFrame, n as sseUIFrame } from '../index-Bu7T6xgr.js';
3
3
  import 'next/server';