@retrivora-ai/rag-engine 1.9.6 → 1.9.8

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 (62) hide show
  1. package/README.md +130 -113
  2. package/dist/{ILLMProvider-DNhyOYoK.d.mts → ILLMProvider-B8ROITYK.d.mts} +59 -8
  3. package/dist/{ILLMProvider-DNhyOYoK.d.ts → ILLMProvider-B8ROITYK.d.ts} +59 -8
  4. package/dist/handlers/index.d.mts +2 -2
  5. package/dist/handlers/index.d.ts +2 -2
  6. package/dist/handlers/index.js +2376 -489
  7. package/dist/handlers/index.mjs +2372 -489
  8. package/dist/{index-CjQdL0cX.d.ts → index-B8PbEFSY.d.mts} +17 -3
  9. package/dist/{index-CHL1jdYm.d.mts → index-BCPKUAVL.d.ts} +33 -41
  10. package/dist/{index-Hgbwl9X4.d.ts → index-CrxCy36A.d.mts} +33 -41
  11. package/dist/{index-C9v7-tWd.d.mts → index-DNvoi-sV.d.ts} +17 -3
  12. package/dist/index.css +695 -203
  13. package/dist/index.d.mts +37 -7
  14. package/dist/index.d.ts +37 -7
  15. package/dist/index.js +1197 -286
  16. package/dist/index.mjs +1221 -297
  17. package/dist/server.d.mts +62 -6
  18. package/dist/server.d.ts +62 -6
  19. package/dist/server.js +2526 -574
  20. package/dist/server.mjs +2517 -573
  21. package/package.json +12 -10
  22. package/src/app/constants.tsx +207 -212
  23. package/src/app/layout.tsx +4 -28
  24. package/src/app/types.ts +17 -17
  25. package/src/components/AmbientBackground.tsx +10 -10
  26. package/src/components/ArchitectureCard.tsx +43 -7
  27. package/src/components/ArchitectureCardsSection.tsx +37 -4
  28. package/src/components/ChatWidget.tsx +4 -1
  29. package/src/components/ChatWindow.tsx +9 -2
  30. package/src/components/CodeViewer.tsx +19 -14
  31. package/src/components/DocViewer.tsx +75 -15
  32. package/src/components/Documentation.tsx +111 -28
  33. package/src/components/Hero.tsx +103 -20
  34. package/src/components/Lifecycle.tsx +65 -25
  35. package/src/components/MarkdownComponents.tsx +44 -1
  36. package/src/components/MessageBubble.tsx +162 -50
  37. package/src/components/constants.tsx +279 -0
  38. package/src/config/RagConfig.ts +56 -10
  39. package/src/config/constants.ts +5 -0
  40. package/src/config/serverConfig.ts +15 -0
  41. package/src/core/ConfigResolver.ts +30 -25
  42. package/src/core/DatabaseStorage.ts +469 -0
  43. package/src/core/LicenseVerifier.ts +154 -0
  44. package/src/core/MultiAgentCoordinator.ts +239 -0
  45. package/src/core/Pipeline.ts +148 -16
  46. package/src/core/ProviderRegistry.ts +5 -5
  47. package/src/core/Retrivora.ts +52 -6
  48. package/src/core/VectorPlugin.ts +74 -11
  49. package/src/core/mcp.ts +261 -0
  50. package/src/exceptions/index.ts +52 -0
  51. package/src/handlers/index.ts +504 -47
  52. package/src/hooks/useRagChat.ts +100 -43
  53. package/src/hooks/useStoredMessages.ts +15 -4
  54. package/src/index.ts +7 -0
  55. package/src/llm/LLMFactory.ts +15 -6
  56. package/src/llm/providers/GroqProvider.ts +176 -0
  57. package/src/llm/providers/QwenProvider.ts +191 -0
  58. package/src/server.ts +23 -13
  59. package/src/types/chat.ts +16 -0
  60. package/src/types/props.ts +50 -1
  61. package/.env.example +0 -80
  62. package/LICENSE.txt +0 -21
package/README.md CHANGED
@@ -1,150 +1,167 @@
1
- # @retrivora-ai/rag-engine
1
+ # Retrivora RAG Engine SDK
2
2
 
3
- > **Retrivora AI is a plug-and-play AI engine for RAG chat experiences** that can be embedded into Next.js apps or used as a standalone demo app. Bring your own vector database, LLM, embeddings, and UI branding.
4
-
5
- [![NPM Version](https://img.shields.io/npm/v/@retrivora-ai/rag-engine?style=flat-square&color=10b981)](https://www.npmjs.com/package/@retrivora-ai/rag-engine)
6
- [![NPM Downloads](https://img.shields.io/npm/dm/@retrivora-ai/rag-engine?style=flat-square&color=3b82f6)](https://www.npmjs.com/package/@retrivora-ai/rag-engine)
7
- [![GitHub](https://img.shields.io/badge/GitHub-Repository-black?style=flat-square&logo=github)](https://github.com/abhinav1201/ai-accelerator)
8
- ![Next.js](https://img.shields.io/badge/Next.js-14+-black?style=flat-square&logo=next.js)
9
- ![TailwindCSS](https://img.shields.io/badge/TailwindCSS-v4-38bdf8?style=flat-square&logo=tailwindcss)
3
+ Retrivora is a developer-first, vendor-agnostic Retrieval-Augmented Generation (RAG) SDK. It bridges any document source to leading vector databases and LLMs with a clean, standardized API and pre-built, responsive React UI components.
10
4
 
11
5
  ---
12
6
 
13
- ## Features (v1.0.0)
7
+ ## 1. What is the Retrivora SDK?
14
8
 
15
- | Category | Options |
16
- |---|---|
17
- | **Vector DBs** | Pinecone, pgVector (PostgreSQL), MongoDB Atlas, ChromaDB, Qdrant, Milvus, Weaviate, Redis |
18
- | **LLM Providers** | OpenAI, Anthropic Claude, Google Gemini, Ollama, LiteLLM, Universal REST |
19
- | **Integrations** | **LangChain** (Agentic orchestration), **LlamaIndex** (Semantic chunking) |
20
- | **Document Ingestion** | Universal support for **PDF**, **DOCX**, **CSV**, **JSON**, **MD**, **TXT** |
21
- | **Architecture** | **Modular & Pluggable** registry-based system with static health checks & validators |
22
- | **RAG Patterns** | Simple, Hybrid, Graph-based, and Agentic workflows |
9
+ The SDK is a unified suite designed to abstract the complexity of building production-grade RAG systems. It handles:
10
+ - **Document Chunking & Ingestion**: Splits text recursively, extracts semantic embeddings, and uploads vectors in batched operations.
11
+ - **Pluggable Architecture**: Switch vector databases (Pinecone, pgvector, MongoDB Vector, Qdrant, etc.) and LLMs (OpenAI, Anthropic Claude, Google Gemini, Ollama) by changing a single configuration key without rewriting database or chat code.
12
+ - **Client-Safe Proxying**: Exposes clean route handler helpers for Next.js and Node.js backend servers, protecting database connection strings and LLM API keys from frontend exposure.
13
+ - **Drop-in UI Elements**: Exports polished, highly customisable React UI elements (`ChatWidget`, `ChatWindow`, `DocumentUpload`) built with Tailwind CSS v4.
23
14
 
24
15
  ---
25
16
 
26
- ## 🚀 How it Works
27
-
28
- 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**.
29
-
30
- 1. **Ingest**: Upload or send documents to the `/api/upload` endpoint. They are parsed and chunked using **LlamaIndex** strategies if configured.
31
- 2. **Retrieve**: Queries are processed via the [QueryProcessor](file:///src/core/QueryProcessor.ts) to extract semantic hints and filter criteria.
32
- 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.
17
+ ## 2. Architecture & Implementation
33
18
 
34
- ### 📦 Installation
19
+ The SDK is built with modularity, performance, and security at its core:
35
20
 
36
- ```bash
37
- npm install @retrivora-ai/rag-engine
21
+ ```
22
+ ┌─────────────────────────────────────────────────────────┐
23
+ │ Host Client │
24
+ │ (Next.js App / React Frontend) │
25
+ └────────────┬───────────────────────────────▲────────────┘
26
+ │ Ingest / Queries │ Render UI
27
+ ┌────────────▼───────────────────────────────┴────────────┐
28
+ │ Retrivora Facade │
29
+ │ (Config Validation & Resolver) │
30
+ └────────────┬────────────────────────────────────────────┘
31
+
32
+
33
+ ┌─────────────────────────────────────────────────────────┐
34
+ │ LicenseVerifier (Local Cryptography) │
35
+ │ Verifies signed JWT with Public Key locally │
36
+ └────────────┬────────────────────────────────────────────┘
37
+
38
+
39
+ ┌─────────────────────────────────────────────────────────┐
40
+ │ Pipeline Engine │
41
+ │ (BatchProcessor, Chunker, Router, LRU Cache) │
42
+ └────────────┬───────────────────────────────┬────────────┘
43
+ │ │
44
+ ▼ ▼
45
+ ┌─────────────────────────┐ ┌─────────────────────────┐
46
+ │ LLM Adapters │ │ Vector DB Providers │
47
+ │ (OpenAI, Gemini, etc.) │ │ (Pinecone, Mongo, SQL) │
48
+ └─────────────────────────┘ └─────────────────────────┘
38
49
  ```
39
50
 
40
- ---
41
-
42
- ## 🛠️ Pluggable Architecture
43
-
44
- Starting with v1.0.0, the engine uses a modular registry for all providers. Every provider now exposes:
45
- - **Static Validators**: `getValidator()` for deep configuration schema checks.
46
- - **Static Health Checkers**: `getHealthChecker()` for real-time connectivity and capability validation.
47
-
48
- This decoupling allows you to add custom providers without modifying the core engine logic.
51
+ ### Key Components:
52
+ 1. **Facade Pattern (`Retrivora.ts`)**: Serves as the primary public entry point. It wraps configuration resolution, schema validation, and lifecycle calls into simple methods like `initialize()`, `ingest()`, `ask()`, and `askStream()`.
53
+ 2. **Resilient Batch Operations (`BatchProcessor.ts`)**: Bulk operations (such as vector upserts and document indexing) are managed by a custom concurrency runner that chunks workloads, tracks partial successes, and applies exponential backoff with jitter on transient network/rate-limit failures.
54
+ 3. **Local Cryptographic Licensing (`LicenseVerifier.ts`)**: Production license keys are issued as cryptographically signed JWT tokens. The SDK parses, validates expiration, and ensures matching project namespaces locally using Node's `crypto` module. This provides offline-friendly, zero-latency key verification with local fail-open warnings in dev mode and fail-closed blockades in production.
55
+ 4. **Smart Embedding Cache**: Implements an in-memory LRU-bounded cache within the pipeline to avoid re-embedding identical search queries inside the same process lifecycle, reducing network costs and saving latency.
49
56
 
50
57
  ---
51
58
 
52
- ## NPM Package Usage
53
-
54
- ### 1. Embed the ChatWidget
59
+ ## 3. End-User Integration Guide
55
60
 
56
- ```tsx
57
- import { ConfigProvider, ChatWidget } from '@retrivora-ai/rag-engine';
58
-
59
- export default function Layout({ children }) {
60
- return (
61
- <ConfigProvider
62
- config={{
63
- projectId: 'my-project',
64
- ui: {
65
- title: 'Support Bot',
66
- primaryColor: '#6366f1',
67
- accentColor: '#8b5cf6',
68
- welcomeMessage: 'Hi! How can I help you today?',
69
- },
70
- }}
71
- >
72
- {children}
73
- <ChatWidget position="bottom-right" />
74
- </ConfigProvider>
75
- );
76
- }
61
+ ### Step 1: Installation
62
+ Install the SDK alongside its required peer dependencies:
63
+ ```bash
64
+ npm install @retrivora-ai/rag-engine
77
65
  ```
78
66
 
79
- ### 2. Mount the API routes
80
-
81
- ```ts
82
- // src/app/api/chat/route.ts
83
- import { createChatHandler, getRagConfig } from '@retrivora-ai/rag-engine/server';
84
- export const POST = createChatHandler(getRagConfig());
85
-
86
- // src/app/api/upload/route.ts
87
- import { createUploadHandler, getRagConfig } from '@retrivora-ai/rag-engine/server';
88
- export const POST = createUploadHandler(getRagConfig());
67
+ ### Step 2: Environment Configuration
68
+ Create a `.env.local` file in your application root to supply your keys and provider selections:
69
+ ```bash
70
+ # General Setup
71
+ RAG_PROJECT_ID=my-rag-application
72
+ RETRIVORA_LICENSE_KEY=ey... # Required for production deployment
73
+
74
+ # Vector Database (MongoDB Atlas Example)
75
+ VECTOR_DB_PROVIDER=mongodb
76
+ MONGODB_URI=mongodb+srv://...
77
+ MONGODB_DB=retrivora_db
78
+ MONGODB_COLLECTION=vectors
79
+ MONGODB_INDEX_NAME=vector_index
80
+
81
+ # LLM Provider (Google Gemini Example)
82
+ LLM_PROVIDER=gemini
83
+ LLM_MODEL=gemini-2.5-flash
84
+ GEMINI_API_KEY=AIzaSy...
85
+
86
+ # Embedding Provider
87
+ EMBEDDING_PROVIDER=gemini
88
+ EMBEDDING_MODEL=text-embedding-004
89
89
  ```
90
90
 
91
- ### 3. Use Pipeline programmatically
91
+ ### Step 3: Server-Side Ingestion
92
+ Initialize the SDK instance on your server-side scripts or background workers to parse and index documents:
93
+ ```typescript
94
+ import { Retrivora } from '@retrivora-ai/rag-engine/server';
92
95
 
93
- ```ts
94
- import { Pipeline, getRagConfig } from '@retrivora-ai/rag-engine/server';
96
+ const retrivora = new Retrivora();
95
97
 
96
- const config = getRagConfig();
97
- const pipeline = new Pipeline(config);
98
+ async function runIngestion() {
99
+ // Validate configuration and verify the license key
100
+ await retrivora.initialize();
98
101
 
99
- // Ingest documents
100
- await pipeline.ingest([{ docId: 'readme', content: 'Your document text here' }]);
102
+ const documents = [
103
+ {
104
+ docId: 'doc-001',
105
+ content: 'Retrivora supports Pinecone, MongoDB Vector, pgvector, and Qdrant out-of-the-box.',
106
+ metadata: { category: 'features', source: 'docs' }
107
+ }
108
+ ];
101
109
 
102
- // Ask questions
103
- const { reply, sources } = await pipeline.ask('What is the refund policy?');
110
+ const results = await retrivora.ingest(documents, 'default-namespace');
111
+ console.log(`Successfully ingested ${results.length} documents.`);
112
+ }
104
113
  ```
105
114
 
106
- ### 4. Use the Retrivora SDK facade
115
+ ### Step 4: Next.js API Routes (Server Proxy)
116
+ Setup Next.js route handlers to stream conversational RAG answers to the frontend client securely:
107
117
 
108
- ```ts
109
- import { Retrivora } from '@retrivora-ai/rag-engine/server';
118
+ **File**: `app/api/chat/route.ts`
119
+ ```typescript
120
+ import { createStreamHandler } from '@retrivora-ai/rag-engine/server';
110
121
 
111
- const ai = new Retrivora({
112
- llm: {
113
- provider: 'openai',
114
- model: 'gpt-5',
115
- },
116
- embedding: {
117
- provider: 'openai',
118
- },
119
- vectorDatabase: {
120
- provider: 'pinecone',
121
- },
122
- retrieval: {
123
- strategy: 'hybrid',
124
- },
125
- workflow: {
126
- type: 'agentic-rag',
127
- },
122
+ // createStreamHandler automatically instantiates the Retrivora pipeline
123
+ // and handles HTTP stream chunking (SSE) transparently.
124
+ export const POST = createStreamHandler({
125
+ projectId: process.env.RAG_PROJECT_ID ?? 'default-project'
128
126
  });
129
-
130
- const { reply, sources } = await ai.ask('What is the refund policy?');
131
127
  ```
132
128
 
133
- ---
129
+ ### Step 5: Client-Side UI Components
130
+ Import the Retrivora CSS styles and render the interactive widget in your layout or page:
134
131
 
135
- ## Configuration Reference
132
+ **File**: `app/layout.tsx` (or `app/page.tsx`)
133
+ ```typescript
134
+ 'use client';
136
135
 
137
- The library is entirely dynamic. You can switch between providers simply by updating your environment variables.
136
+ import { ConfigProvider, ChatWidget } from '@retrivora-ai/rag-engine';
137
+ import '@retrivora-ai/rag-engine/style.css'; // Load Tailwind styles
138
138
 
139
- | Variable | Description |
140
- |---|---|
141
- | `RAG_PROJECT_ID` | Project namespace for data isolation |
142
- | `VECTOR_DB_PROVIDER` | `pinecone`, `pgvector`, `mongodb`, `milvus`, `qdrant`, `weaviate` |
143
- | `LLM_PROVIDER` | `openai`, `anthropic`, `gemini`, `ollama` |
144
- | `EMBEDDING_PROVIDER` | `openai`, `ollama`, `google-gemini` |
145
- | `RAG_ARCHITECTURE` | `simple`, `hybrid`, `graph`, `agentic` |
139
+ export default function Home() {
140
+ return (
141
+ <ConfigProvider apiEndpoint="/api/chat">
142
+ <main className="min-h-screen p-10 bg-slate-50">
143
+ <h1>My Corporate Knowledge Base</h1>
144
+
145
+ {/* Drop-in float widget */}
146
+ <ChatWidget
147
+ title="Retrivora Assistant"
148
+ subtitle="Ready to search your documents"
149
+ visualStyle="glass"
150
+ />
151
+ </main>
152
+ </ConfigProvider>
153
+ );
154
+ }
155
+ ```
146
156
 
147
157
  ---
148
158
 
149
- ## License
150
- MIT
159
+ ## 4. Licensing and Environments
160
+
161
+ The SDK enforces license key verification at runtime depending on the hosting environment:
162
+
163
+ | Host Environment | License Key Status | SDK Behavior |
164
+ | :--- | :--- | :--- |
165
+ | **Development** (`process.env.NODE_ENV !== 'production'`) | **Missing / Expired** | **Fail-Open**: Outputs a yellow warning message in the node console. Operations continue. |
166
+ | **Production** (`process.env.NODE_ENV === 'production'`) | **Missing / Expired** | **Fail-Closed**: Throws `ConfigurationException` on `initialize()`. Ingestion/Chat routes are blocked. |
167
+ | **Air-Gapped / Offline** | **Valid Signed JWT** | **Fail-Open on Telemetry**: Verifies signature cryptographically offline. Works with no internet connection. |
@@ -35,6 +35,12 @@ interface ChatOptions {
35
35
  interface UseRagChatOptions {
36
36
  /** Override the chat API endpoint (default: /api/chat) */
37
37
  apiUrl?: string;
38
+ /**
39
+ * Base URL for the Retrivora SDK catch-all route used for history, feedback,
40
+ * and sessions endpoints. Defaults to '/api/retrivora'.
41
+ * e.g. if your catch-all is at /api/retrivora/[[...retrivora]], set this to '/api/retrivora'.
42
+ */
43
+ retrivoraApiBase?: string;
38
44
  /** Override project namespace */
39
45
  namespace?: string;
40
46
  /** Persist chat history to localStorage (default: true) */
@@ -43,6 +49,10 @@ interface UseRagChatOptions {
43
49
  onReply?: (message: RagMessage) => void;
44
50
  /** Called on error */
45
51
  onError?: (error: string) => void;
52
+ /** Optional custom headers to send with the chat request */
53
+ headers?: Record<string, string>;
54
+ /** Session ID for history and feedback tracking (default: 'default') */
55
+ sessionId?: string;
46
56
  }
47
57
  interface UseRagChatReturn {
48
58
  /** All messages in the current conversation */
@@ -61,17 +71,17 @@ interface UseRagChatReturn {
61
71
  setMessages: React.Dispatch<React.SetStateAction<RagMessage[]>>;
62
72
  /** Abort the current active stream request */
63
73
  stop: () => void;
74
+ /** Load message history from database storage */
75
+ loadHistory: (sessionId: string) => Promise<void>;
76
+ /** Clear conversation history from database and locally */
77
+ clearHistory: (sessionId: string) => Promise<void>;
78
+ /** Submit rating and optional comment for a specific assistant message */
79
+ submitFeedback: (messageId: string, rating: 'thumbs_up' | 'thumbs_down', comment?: string) => Promise<void>;
64
80
  }
65
81
 
66
- /**
67
- * constants.ts — Centralized definitions of acceptable configuration values.
68
- *
69
- * This file serves as the single source of truth for all statically supported
70
- * providers and stylistic options in the Retrivora AI RAG Engine.
71
- */
72
82
  declare const VECTOR_DB_PROVIDERS: readonly ["pinecone", "pgvector", "postgresql", "mongodb", "qdrant", "milvus", "chromadb", "redis", "weaviate", "rest", "universal_rest", "custom"];
73
- declare const LLM_PROVIDERS: readonly ["openai", "anthropic", "ollama", "gemini", "rest", "universal_rest", "custom"];
74
- declare const EMBEDDING_PROVIDERS: readonly ["openai", "ollama", "gemini", "rest", "universal_rest", "custom"];
83
+ declare const LLM_PROVIDERS: readonly ["openai", "anthropic", "ollama", "gemini", "groq", "qwen", "rest", "universal_rest", "custom"];
84
+ declare const EMBEDDING_PROVIDERS: readonly ["openai", "ollama", "gemini", "qwen", "rest", "universal_rest", "custom"];
75
85
  declare const GRAPH_DB_PROVIDERS: readonly ["neo4j", "memgraph", "simple", "custom"];
76
86
 
77
87
  /**
@@ -193,6 +203,18 @@ interface UIConfig {
193
203
  /** Whether to enable voice search input. Defaults to true. */
194
204
  enableVoiceInput?: boolean;
195
205
  }
206
+ interface CAGConfig {
207
+ /** Enable Cold RAG (Cache Augmented Generation) */
208
+ enabled?: boolean;
209
+ /** Namespace containing the cold data (e.g., static manuals/guides) */
210
+ coldNamespace?: string;
211
+ /** Limit of cold documents to retrieve at initialization and keep in cache/context */
212
+ coldLimit?: number;
213
+ /** Specific search query to retrieve the cold documents (e.g., "manual", "documentation") */
214
+ coldQuery?: string;
215
+ /** Specific document IDs to load as cold context */
216
+ coldDocumentIds?: string[];
217
+ }
196
218
  interface RAGConfig {
197
219
  /** Number of top-K chunks retrieved per query */
198
220
  topK?: number;
@@ -233,6 +255,18 @@ interface RAGConfig {
233
255
  * Defaults to built-in list (find, search, tell me about, etc.).
234
256
  */
235
257
  vectorKeywords?: string[];
258
+ /** Cold RAG (Cache Augmented Generation) configuration */
259
+ cag?: CAGConfig;
260
+ /** Chat history configuration */
261
+ history?: {
262
+ enabled?: boolean;
263
+ tableName?: string;
264
+ };
265
+ /** User feedback configuration */
266
+ feedback?: {
267
+ enabled?: boolean;
268
+ tableName?: string;
269
+ };
236
270
  }
237
271
  interface RetrievalConfig {
238
272
  /** Retrieval strategy selected by the host app. */
@@ -252,7 +286,17 @@ interface WorkflowConfig {
252
286
  /** Future workflow/provider-specific options. */
253
287
  options?: Record<string, unknown>;
254
288
  }
289
+ interface MCPServerConfig {
290
+ name: string;
291
+ transport: 'stdio' | 'sse';
292
+ url?: string;
293
+ command?: string;
294
+ args?: string[];
295
+ env?: Record<string, string>;
296
+ }
255
297
  interface RagConfig {
298
+ /** License key for commercial production validation */
299
+ licenseKey?: string;
256
300
  /**
257
301
  * Unique identifier for the consuming project.
258
302
  * Used as the vector DB namespace to achieve multi-tenancy.
@@ -270,6 +314,13 @@ interface RagConfig {
270
314
  rag?: RAGConfig;
271
315
  /** Optional Graph database configuration */
272
316
  graphDb?: GraphDBConfig;
317
+ /** Optional Telemetry configuration for observability logging */
318
+ telemetry?: {
319
+ enabled?: boolean;
320
+ url?: string;
321
+ };
322
+ /** Optional Model Context Protocol (MCP) server configurations */
323
+ mcpServers?: MCPServerConfig[];
273
324
  }
274
325
  /**
275
326
  * Friendly SDK configuration accepted by the top-level Retrivora facade.
@@ -35,6 +35,12 @@ interface ChatOptions {
35
35
  interface UseRagChatOptions {
36
36
  /** Override the chat API endpoint (default: /api/chat) */
37
37
  apiUrl?: string;
38
+ /**
39
+ * Base URL for the Retrivora SDK catch-all route used for history, feedback,
40
+ * and sessions endpoints. Defaults to '/api/retrivora'.
41
+ * e.g. if your catch-all is at /api/retrivora/[[...retrivora]], set this to '/api/retrivora'.
42
+ */
43
+ retrivoraApiBase?: string;
38
44
  /** Override project namespace */
39
45
  namespace?: string;
40
46
  /** Persist chat history to localStorage (default: true) */
@@ -43,6 +49,10 @@ interface UseRagChatOptions {
43
49
  onReply?: (message: RagMessage) => void;
44
50
  /** Called on error */
45
51
  onError?: (error: string) => void;
52
+ /** Optional custom headers to send with the chat request */
53
+ headers?: Record<string, string>;
54
+ /** Session ID for history and feedback tracking (default: 'default') */
55
+ sessionId?: string;
46
56
  }
47
57
  interface UseRagChatReturn {
48
58
  /** All messages in the current conversation */
@@ -61,17 +71,17 @@ interface UseRagChatReturn {
61
71
  setMessages: React.Dispatch<React.SetStateAction<RagMessage[]>>;
62
72
  /** Abort the current active stream request */
63
73
  stop: () => void;
74
+ /** Load message history from database storage */
75
+ loadHistory: (sessionId: string) => Promise<void>;
76
+ /** Clear conversation history from database and locally */
77
+ clearHistory: (sessionId: string) => Promise<void>;
78
+ /** Submit rating and optional comment for a specific assistant message */
79
+ submitFeedback: (messageId: string, rating: 'thumbs_up' | 'thumbs_down', comment?: string) => Promise<void>;
64
80
  }
65
81
 
66
- /**
67
- * constants.ts — Centralized definitions of acceptable configuration values.
68
- *
69
- * This file serves as the single source of truth for all statically supported
70
- * providers and stylistic options in the Retrivora AI RAG Engine.
71
- */
72
82
  declare const VECTOR_DB_PROVIDERS: readonly ["pinecone", "pgvector", "postgresql", "mongodb", "qdrant", "milvus", "chromadb", "redis", "weaviate", "rest", "universal_rest", "custom"];
73
- declare const LLM_PROVIDERS: readonly ["openai", "anthropic", "ollama", "gemini", "rest", "universal_rest", "custom"];
74
- declare const EMBEDDING_PROVIDERS: readonly ["openai", "ollama", "gemini", "rest", "universal_rest", "custom"];
83
+ declare const LLM_PROVIDERS: readonly ["openai", "anthropic", "ollama", "gemini", "groq", "qwen", "rest", "universal_rest", "custom"];
84
+ declare const EMBEDDING_PROVIDERS: readonly ["openai", "ollama", "gemini", "qwen", "rest", "universal_rest", "custom"];
75
85
  declare const GRAPH_DB_PROVIDERS: readonly ["neo4j", "memgraph", "simple", "custom"];
76
86
 
77
87
  /**
@@ -193,6 +203,18 @@ interface UIConfig {
193
203
  /** Whether to enable voice search input. Defaults to true. */
194
204
  enableVoiceInput?: boolean;
195
205
  }
206
+ interface CAGConfig {
207
+ /** Enable Cold RAG (Cache Augmented Generation) */
208
+ enabled?: boolean;
209
+ /** Namespace containing the cold data (e.g., static manuals/guides) */
210
+ coldNamespace?: string;
211
+ /** Limit of cold documents to retrieve at initialization and keep in cache/context */
212
+ coldLimit?: number;
213
+ /** Specific search query to retrieve the cold documents (e.g., "manual", "documentation") */
214
+ coldQuery?: string;
215
+ /** Specific document IDs to load as cold context */
216
+ coldDocumentIds?: string[];
217
+ }
196
218
  interface RAGConfig {
197
219
  /** Number of top-K chunks retrieved per query */
198
220
  topK?: number;
@@ -233,6 +255,18 @@ interface RAGConfig {
233
255
  * Defaults to built-in list (find, search, tell me about, etc.).
234
256
  */
235
257
  vectorKeywords?: string[];
258
+ /** Cold RAG (Cache Augmented Generation) configuration */
259
+ cag?: CAGConfig;
260
+ /** Chat history configuration */
261
+ history?: {
262
+ enabled?: boolean;
263
+ tableName?: string;
264
+ };
265
+ /** User feedback configuration */
266
+ feedback?: {
267
+ enabled?: boolean;
268
+ tableName?: string;
269
+ };
236
270
  }
237
271
  interface RetrievalConfig {
238
272
  /** Retrieval strategy selected by the host app. */
@@ -252,7 +286,17 @@ interface WorkflowConfig {
252
286
  /** Future workflow/provider-specific options. */
253
287
  options?: Record<string, unknown>;
254
288
  }
289
+ interface MCPServerConfig {
290
+ name: string;
291
+ transport: 'stdio' | 'sse';
292
+ url?: string;
293
+ command?: string;
294
+ args?: string[];
295
+ env?: Record<string, string>;
296
+ }
255
297
  interface RagConfig {
298
+ /** License key for commercial production validation */
299
+ licenseKey?: string;
256
300
  /**
257
301
  * Unique identifier for the consuming project.
258
302
  * Used as the vector DB namespace to achieve multi-tenancy.
@@ -270,6 +314,13 @@ interface RagConfig {
270
314
  rag?: RAGConfig;
271
315
  /** Optional Graph database configuration */
272
316
  graphDb?: GraphDBConfig;
317
+ /** Optional Telemetry configuration for observability logging */
318
+ telemetry?: {
319
+ enabled?: boolean;
320
+ url?: string;
321
+ };
322
+ /** Optional Model Context Protocol (MCP) server configurations */
323
+ mcpServers?: MCPServerConfig[];
273
324
  }
274
325
  /**
275
326
  * Friendly SDK configuration accepted by the top-level Retrivora facade.
@@ -1,3 +1,3 @@
1
- import '../ILLMProvider-DNhyOYoK.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-CHL1jdYm.mjs';
3
1
  import 'next/server';
2
+ export { o as HandlerOptions, c as createChatHandler, d as createFeedbackHandler, e as createHealthHandler, f as createHistoryHandler, g as createIngestHandler, h as createRagHandler, i as createSessionsHandler, j as createStreamHandler, p as createSuggestionsHandler, k as createUploadHandler, s as sseErrorFrame, l as sseFrame, m as sseMetaFrame, q as sseObservabilityFrame, n as sseTextFrame, r as sseUIFrame } from '../index-CrxCy36A.mjs';
3
+ import '../ILLMProvider-B8ROITYK.mjs';
@@ -1,3 +1,3 @@
1
- import '../ILLMProvider-DNhyOYoK.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-Hgbwl9X4.js';
3
1
  import 'next/server';
2
+ export { o as HandlerOptions, c as createChatHandler, d as createFeedbackHandler, e as createHealthHandler, f as createHistoryHandler, g as createIngestHandler, h as createRagHandler, i as createSessionsHandler, j as createStreamHandler, p as createSuggestionsHandler, k as createUploadHandler, s as sseErrorFrame, l as sseFrame, m as sseMetaFrame, q as sseObservabilityFrame, n as sseTextFrame, r as sseUIFrame } from '../index-BCPKUAVL.js';
3
+ import '../ILLMProvider-B8ROITYK.js';