@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.
- package/README.md +130 -113
- package/dist/{ILLMProvider-DNhyOYoK.d.mts → ILLMProvider-B8ROITYK.d.mts} +59 -8
- package/dist/{ILLMProvider-DNhyOYoK.d.ts → ILLMProvider-B8ROITYK.d.ts} +59 -8
- package/dist/handlers/index.d.mts +2 -2
- package/dist/handlers/index.d.ts +2 -2
- package/dist/handlers/index.js +2376 -489
- package/dist/handlers/index.mjs +2372 -489
- package/dist/{index-CjQdL0cX.d.ts → index-B8PbEFSY.d.mts} +17 -3
- package/dist/{index-CHL1jdYm.d.mts → index-BCPKUAVL.d.ts} +33 -41
- package/dist/{index-Hgbwl9X4.d.ts → index-CrxCy36A.d.mts} +33 -41
- package/dist/{index-C9v7-tWd.d.mts → index-DNvoi-sV.d.ts} +17 -3
- package/dist/index.css +695 -203
- package/dist/index.d.mts +37 -7
- package/dist/index.d.ts +37 -7
- package/dist/index.js +1197 -286
- package/dist/index.mjs +1221 -297
- package/dist/server.d.mts +62 -6
- package/dist/server.d.ts +62 -6
- package/dist/server.js +2526 -574
- package/dist/server.mjs +2517 -573
- package/package.json +12 -10
- package/src/app/constants.tsx +207 -212
- package/src/app/layout.tsx +4 -28
- package/src/app/types.ts +17 -17
- package/src/components/AmbientBackground.tsx +10 -10
- package/src/components/ArchitectureCard.tsx +43 -7
- package/src/components/ArchitectureCardsSection.tsx +37 -4
- package/src/components/ChatWidget.tsx +4 -1
- package/src/components/ChatWindow.tsx +9 -2
- package/src/components/CodeViewer.tsx +19 -14
- package/src/components/DocViewer.tsx +75 -15
- package/src/components/Documentation.tsx +111 -28
- package/src/components/Hero.tsx +103 -20
- package/src/components/Lifecycle.tsx +65 -25
- package/src/components/MarkdownComponents.tsx +44 -1
- package/src/components/MessageBubble.tsx +162 -50
- package/src/components/constants.tsx +279 -0
- package/src/config/RagConfig.ts +56 -10
- package/src/config/constants.ts +5 -0
- package/src/config/serverConfig.ts +15 -0
- package/src/core/ConfigResolver.ts +30 -25
- package/src/core/DatabaseStorage.ts +469 -0
- package/src/core/LicenseVerifier.ts +154 -0
- package/src/core/MultiAgentCoordinator.ts +239 -0
- package/src/core/Pipeline.ts +148 -16
- package/src/core/ProviderRegistry.ts +5 -5
- package/src/core/Retrivora.ts +52 -6
- package/src/core/VectorPlugin.ts +74 -11
- package/src/core/mcp.ts +261 -0
- package/src/exceptions/index.ts +52 -0
- package/src/handlers/index.ts +504 -47
- package/src/hooks/useRagChat.ts +100 -43
- package/src/hooks/useStoredMessages.ts +15 -4
- package/src/index.ts +7 -0
- package/src/llm/LLMFactory.ts +15 -6
- package/src/llm/providers/GroqProvider.ts +176 -0
- package/src/llm/providers/QwenProvider.ts +191 -0
- package/src/server.ts +23 -13
- package/src/types/chat.ts +16 -0
- package/src/types/props.ts +50 -1
- package/.env.example +0 -80
- package/LICENSE.txt +0 -21
package/README.md
CHANGED
|
@@ -1,150 +1,167 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Retrivora RAG Engine SDK
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
[](https://www.npmjs.com/package/@retrivora-ai/rag-engine)
|
|
6
|
-
[](https://www.npmjs.com/package/@retrivora-ai/rag-engine)
|
|
7
|
-
[](https://github.com/abhinav1201/ai-accelerator)
|
|
8
|
-

|
|
9
|
-

|
|
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
|
-
##
|
|
7
|
+
## 1. What is the Retrivora SDK?
|
|
14
8
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
19
|
+
The SDK is built with modularity, performance, and security at its core:
|
|
35
20
|
|
|
36
|
-
```
|
|
37
|
-
|
|
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
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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
|
-
##
|
|
53
|
-
|
|
54
|
-
### 1. Embed the ChatWidget
|
|
59
|
+
## 3. End-User Integration Guide
|
|
55
60
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
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
|
|
80
|
-
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
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
|
|
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
|
-
|
|
94
|
-
import { Pipeline, getRagConfig } from '@retrivora-ai/rag-engine/server';
|
|
96
|
+
const retrivora = new Retrivora();
|
|
95
97
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
+
async function runIngestion() {
|
|
99
|
+
// Validate configuration and verify the license key
|
|
100
|
+
await retrivora.initialize();
|
|
98
101
|
|
|
99
|
-
|
|
100
|
-
|
|
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
|
-
|
|
103
|
-
|
|
110
|
+
const results = await retrivora.ingest(documents, 'default-namespace');
|
|
111
|
+
console.log(`Successfully ingested ${results.length} documents.`);
|
|
112
|
+
}
|
|
104
113
|
```
|
|
105
114
|
|
|
106
|
-
### 4.
|
|
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
|
-
|
|
109
|
-
|
|
118
|
+
**File**: `app/api/chat/route.ts`
|
|
119
|
+
```typescript
|
|
120
|
+
import { createStreamHandler } from '@retrivora-ai/rag-engine/server';
|
|
110
121
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
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
|
-
|
|
132
|
+
**File**: `app/layout.tsx` (or `app/page.tsx`)
|
|
133
|
+
```typescript
|
|
134
|
+
'use client';
|
|
136
135
|
|
|
137
|
-
|
|
136
|
+
import { ConfigProvider, ChatWidget } from '@retrivora-ai/rag-engine';
|
|
137
|
+
import '@retrivora-ai/rag-engine/style.css'; // Load Tailwind styles
|
|
138
138
|
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
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
|
-
##
|
|
150
|
-
|
|
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';
|
package/dist/handlers/index.d.ts
CHANGED
|
@@ -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';
|