@retrivora-ai/rag-engine 2.5.2 → 2.5.4

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 CHANGED
@@ -1,206 +1,206 @@
1
- # Retrivora RAG Engine SDK
2
-
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.
4
-
5
- ---
6
-
7
- ## 1. What is the Retrivora SDK?
8
-
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.
14
-
15
- ---
16
-
17
- ## 2. Architecture & Implementation
18
-
19
- The SDK is built with modularity, performance, and security at its core:
20
-
21
- ```mermaid
22
- sequenceDiagram
23
- autonumber
24
- actor Client as Host Client (Next.js/React)
25
- participant Facade as Retrivora Facade
26
- participant Lic as LicenseVerifier
27
- participant Pipe as Pipeline Engine
28
- participant DB as Vector Database
29
- participant LLM as LLM Provider
30
-
31
- Client->>Facade: initialize(config)
32
- activate Facade
33
- Facade->>Lic: verify(licenseKey, projectId)
34
- activate Lic
35
- Note over Lic: Offline RS256 JWT Decryption
36
- Lic-->>Facade: Valid Signature (Green)
37
- deactivate Lic
38
- Facade-->>Client: Ready
39
- deactivate Facade
40
-
41
- Client->>Facade: ask(question, history)
42
- activate Facade
43
- Facade->>Pipe: ask(question, history)
44
- activate Pipe
45
- Pipe->>DB: search(queryVector)
46
- activate DB
47
- DB-->>Pipe: relevant chunks & meta
48
- deactivate DB
49
- Pipe->>LLM: chatCompletion(context, prompt)
50
- activate LLM
51
- LLM-->>Pipe: generated response
52
- deactivate LLM
53
- Pipe-->>Facade: ChatResponse (reply + sources)
54
- deactivate Pipe
55
- Facade-->>Client: SSE Streaming Chunk / JSON
56
- deactivate Facade
57
- ```
58
-
59
- ### Key Components:
60
- 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()`.
61
- 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.
62
- 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.
63
- 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.
64
-
65
- ---
66
-
67
- ## 3. End-User Integration Guide
68
-
69
- ### Step 1: Installation
70
- Install the SDK alongside its required peer dependencies:
71
- ```bash
72
- npm install @retrivora-ai/rag-engine
73
- ```
74
-
75
- ### Step 2: Environment Configuration
76
- Create a `.env.local` file in your application root to supply your keys and provider selections:
77
- ```bash
78
- # General Setup
79
- NEXT_PUBLIC_PROJECT_ID=my-rag-application
80
- NEXT_PUBLIC_RETRIVORA_LICENSE_KEY=ey... # Required for client & server deployment
81
-
82
- # Vector Database (MongoDB Atlas Example)
83
- VECTOR_DB_PROVIDER=mongodb
84
- MONGODB_URI=mongodb+srv://...
85
- MONGODB_DB=retrivora_db
86
- MONGODB_COLLECTION=vectors
87
- MONGODB_INDEX_NAME=vector_index
88
-
89
- # LLM Provider (Google Gemini Example)
90
- LLM_PROVIDER=gemini
91
- LLM_MODEL=gemini-2.5-flash
92
- GEMINI_API_KEY=AIzaSy...
93
-
94
- # Embedding Provider
95
- EMBEDDING_PROVIDER=gemini
96
- EMBEDDING_MODEL=text-embedding-004
97
- ```
98
-
99
- ### Step 3: Server-Side Ingestion
100
- Initialize the SDK instance on your server-side scripts or background workers to parse and index documents:
101
- ```typescript
102
- import { Retrivora } from '@retrivora-ai/rag-engine/server';
103
-
104
- const retrivora = new Retrivora();
105
-
106
- async function runIngestion() {
107
- // Validate configuration and verify the license key
108
- await retrivora.initialize();
109
-
110
- const documents = [
111
- {
112
- docId: 'doc-001',
113
- content: 'Retrivora supports Pinecone, MongoDB Vector, pgvector, and Qdrant out-of-the-box.',
114
- metadata: { category: 'features', source: 'docs' }
115
- }
116
- ];
117
-
118
- const results = await retrivora.ingest(documents, 'default-namespace');
119
- //console.log(`Successfully ingested ${results.length} documents.`);
120
- }
121
- ```
122
-
123
- ### Step 4: Next.js API Routes (Server Proxy)
124
- Setup Next.js route handlers to stream conversational RAG answers to the frontend client securely:
125
-
126
- **File**: `app/api/chat/route.ts`
127
- ```typescript
128
- import { createStreamHandler } from '@retrivora-ai/rag-engine/server';
129
-
130
- // createStreamHandler automatically instantiates the Retrivora pipeline
131
- // and handles HTTP stream chunking (SSE) transparently.
132
- export const POST = createStreamHandler({
133
- projectId: process.env.RAG_PROJECT_ID ?? 'default-project'
134
- });
135
- ```
136
-
137
- ### Step 5: Client-Side UI Components
138
- Import the Retrivora CSS styles and render the interactive widget in your layout or page:
139
-
140
- **File**: `app/layout.tsx` (or `app/page.tsx`)
141
- ```typescript
142
- 'use client';
143
-
144
- import { ConfigProvider, ChatWidget } from '@retrivora-ai/rag-engine';
145
- import '@retrivora-ai/rag-engine/style.css'; // Load Tailwind styles
146
-
147
- export default function Home() {
148
- return (
149
- <ConfigProvider apiEndpoint="/api/chat">
150
- <main className="min-h-screen p-10 bg-slate-50">
151
- <h1>My Corporate Knowledge Base</h1>
152
-
153
- {/* Drop-in float widget */}
154
- <ChatWidget
155
- title="Retrivora Assistant"
156
- subtitle="Ready to search your documents"
157
- visualStyle="glass"
158
- />
159
- </main>
160
- </ConfigProvider>
161
- );
162
- }
163
- ```
164
-
165
- ---
166
-
167
- ## 4. Licensing and Environments
168
-
169
- The SDK enforces license key verification at runtime depending on the hosting environment:
170
-
171
- | Host Environment | License Key Status | SDK Behavior |
172
- | :--- | :--- | :--- |
173
- | **Development** (`process.env.NODE_ENV !== 'production'`) | **Missing / Expired** | **Fail-Open**: Outputs a yellow warning message in the node console. Operations continue. |
174
- | **Production** (`process.env.NODE_ENV === 'production'`) | **Missing / Expired** | **Fail-Closed**: Throws `ConfigurationException` on `initialize()`. Ingestion/Chat routes are blocked. |
175
- | **Air-Gapped / Offline** | **Valid Signed JWT** | **Fail-Open on Telemetry**: Verifies signature cryptographically offline. Works with no internet connection. |
176
-
177
- ---
178
-
179
- ## 5. Free Tier (MVP) Architecture
180
-
181
- For lightweight deployments, Retrivora includes a standardized Free Tier MVP design featuring shared Pinecone index namespacing, LiteLLM gateway routing, 768-dimension embeddings, and strict operational limit enforcement.
182
-
183
- See [FREE_TIER_ARCHITECTURE.md](file:///Users/abhinavalkuchi/work/retrivora-ai/packages/sdk/FREE_TIER_ARCHITECTURE.md) for full implementation details, code presets, and limits configuration.
184
-
185
- ---
186
-
187
- ## 6. Next.js App Router Integration & Framework Lock-in (PKG-1)
188
-
189
- The SDK's prebuilt server handlers (`createChatHandler`, `createStreamHandler`, `createUploadHandler`) import directly from `next/server`. They are tightly coupled to the Next.js App Router API context and expect standard Next.js requests and responses.
190
-
191
- If you are deploying in non-Next.js server environments (such as Express, Fastify, Hono, or custom Node.js frameworks), do **not** use the route handlers. Instead, invoke the core `LicensedRetrivora` SDK methods directly within your custom controllers:
192
- ```typescript
193
- import { createRetrivora } from '@retrivora-ai/rag-engine';
194
-
195
- // Framework-agnostic controller example
196
- app.post('/api/chat', async (req, res) => {
197
- const sdk = await createRetrivora({
198
- projectId: 'my-project',
199
- licenseKey: process.env.RETRIVORA_LICENSE_KEY,
200
- });
201
- const answer = await sdk.query(req.body.message);
202
- res.json(answer);
203
- });
204
- ```
205
-
206
-
1
+ # Retrivora RAG Engine SDK
2
+
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.
4
+
5
+ ---
6
+
7
+ ## 1. What is the Retrivora SDK?
8
+
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.
14
+
15
+ ---
16
+
17
+ ## 2. Architecture & Implementation
18
+
19
+ The SDK is built with modularity, performance, and security at its core:
20
+
21
+ ```mermaid
22
+ sequenceDiagram
23
+ autonumber
24
+ actor Client as Host Client (Next.js/React)
25
+ participant Facade as Retrivora Facade
26
+ participant Lic as LicenseVerifier
27
+ participant Pipe as Pipeline Engine
28
+ participant DB as Vector Database
29
+ participant LLM as LLM Provider
30
+
31
+ Client->>Facade: initialize(config)
32
+ activate Facade
33
+ Facade->>Lic: verify(licenseKey, projectId)
34
+ activate Lic
35
+ Note over Lic: Offline RS256 JWT Decryption
36
+ Lic-->>Facade: Valid Signature (Green)
37
+ deactivate Lic
38
+ Facade-->>Client: Ready
39
+ deactivate Facade
40
+
41
+ Client->>Facade: ask(question, history)
42
+ activate Facade
43
+ Facade->>Pipe: ask(question, history)
44
+ activate Pipe
45
+ Pipe->>DB: search(queryVector)
46
+ activate DB
47
+ DB-->>Pipe: relevant chunks & meta
48
+ deactivate DB
49
+ Pipe->>LLM: chatCompletion(context, prompt)
50
+ activate LLM
51
+ LLM-->>Pipe: generated response
52
+ deactivate LLM
53
+ Pipe-->>Facade: ChatResponse (reply + sources)
54
+ deactivate Pipe
55
+ Facade-->>Client: SSE Streaming Chunk / JSON
56
+ deactivate Facade
57
+ ```
58
+
59
+ ### Key Components:
60
+ 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()`.
61
+ 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.
62
+ 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.
63
+ 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.
64
+
65
+ ---
66
+
67
+ ## 3. End-User Integration Guide
68
+
69
+ ### Step 1: Installation
70
+ Install the SDK alongside its required peer dependencies:
71
+ ```bash
72
+ npm install @retrivora-ai/rag-engine
73
+ ```
74
+
75
+ ### Step 2: Environment Configuration
76
+ Create a `.env.local` file in your application root to supply your keys and provider selections:
77
+ ```bash
78
+ # General Setup
79
+ NEXT_PUBLIC_PROJECT_ID=my-rag-application
80
+ NEXT_PUBLIC_RETRIVORA_LICENSE_KEY=ey... # Required for client & server deployment
81
+
82
+ # Vector Database (MongoDB Atlas Example)
83
+ VECTOR_DB_PROVIDER=mongodb
84
+ MONGODB_URI=mongodb+srv://...
85
+ MONGODB_DB=retrivora_db
86
+ MONGODB_COLLECTION=vectors
87
+ MONGODB_INDEX_NAME=vector_index
88
+
89
+ # LLM Provider (Google Gemini Example)
90
+ LLM_PROVIDER=gemini
91
+ LLM_MODEL=gemini-2.5-flash
92
+ GEMINI_API_KEY=AIzaSy...
93
+
94
+ # Embedding Provider
95
+ EMBEDDING_PROVIDER=gemini
96
+ EMBEDDING_MODEL=text-embedding-004
97
+ ```
98
+
99
+ ### Step 3: Server-Side Ingestion
100
+ Initialize the SDK instance on your server-side scripts or background workers to parse and index documents:
101
+ ```typescript
102
+ import { Retrivora } from '@retrivora-ai/rag-engine/server';
103
+
104
+ const retrivora = new Retrivora();
105
+
106
+ async function runIngestion() {
107
+ // Validate configuration and verify the license key
108
+ await retrivora.initialize();
109
+
110
+ const documents = [
111
+ {
112
+ docId: 'doc-001',
113
+ content: 'Retrivora supports Pinecone, MongoDB Vector, pgvector, and Qdrant out-of-the-box.',
114
+ metadata: { category: 'features', source: 'docs' }
115
+ }
116
+ ];
117
+
118
+ const results = await retrivora.ingest(documents, 'default-namespace');
119
+ //console.log(`Successfully ingested ${results.length} documents.`);
120
+ }
121
+ ```
122
+
123
+ ### Step 4: Next.js API Routes (Server Proxy)
124
+ Setup Next.js route handlers to stream conversational RAG answers to the frontend client securely:
125
+
126
+ **File**: `app/api/chat/route.ts`
127
+ ```typescript
128
+ import { createStreamHandler } from '@retrivora-ai/rag-engine/server';
129
+
130
+ // createStreamHandler automatically instantiates the Retrivora pipeline
131
+ // and handles HTTP stream chunking (SSE) transparently.
132
+ export const POST = createStreamHandler({
133
+ projectId: process.env.RAG_PROJECT_ID ?? 'default-project'
134
+ });
135
+ ```
136
+
137
+ ### Step 5: Client-Side UI Components
138
+ Import the Retrivora CSS styles and render the interactive widget in your layout or page:
139
+
140
+ **File**: `app/layout.tsx` (or `app/page.tsx`)
141
+ ```typescript
142
+ 'use client';
143
+
144
+ import { ConfigProvider, ChatWidget } from '@retrivora-ai/rag-engine';
145
+ import '@retrivora-ai/rag-engine/style.css'; // Load Tailwind styles
146
+
147
+ export default function Home() {
148
+ return (
149
+ <ConfigProvider apiEndpoint="/api/chat">
150
+ <main className="min-h-screen p-10 bg-slate-50">
151
+ <h1>My Corporate Knowledge Base</h1>
152
+
153
+ {/* Drop-in float widget */}
154
+ <ChatWidget
155
+ title="Retrivora Assistant"
156
+ subtitle="Ready to search your documents"
157
+ visualStyle="glass"
158
+ />
159
+ </main>
160
+ </ConfigProvider>
161
+ );
162
+ }
163
+ ```
164
+
165
+ ---
166
+
167
+ ## 4. Licensing and Environments
168
+
169
+ The SDK enforces license key verification at runtime depending on the hosting environment:
170
+
171
+ | Host Environment | License Key Status | SDK Behavior |
172
+ | :--- | :--- | :--- |
173
+ | **Development** (`process.env.NODE_ENV !== 'production'`) | **Missing / Expired** | **Fail-Open**: Outputs a yellow warning message in the node console. Operations continue. |
174
+ | **Production** (`process.env.NODE_ENV === 'production'`) | **Missing / Expired** | **Fail-Closed**: Throws `ConfigurationException` on `initialize()`. Ingestion/Chat routes are blocked. |
175
+ | **Air-Gapped / Offline** | **Valid Signed JWT** | **Fail-Open on Telemetry**: Verifies signature cryptographically offline. Works with no internet connection. |
176
+
177
+ ---
178
+
179
+ ## 5. Free Tier (MVP) Architecture
180
+
181
+ For lightweight deployments, Retrivora includes a standardized Free Tier MVP design featuring shared Pinecone index namespacing, LiteLLM gateway routing, 768-dimension embeddings, and strict operational limit enforcement.
182
+
183
+ See [FREE_TIER_ARCHITECTURE.md](file:///Users/abhinavalkuchi/work/retrivora-ai/packages/sdk/FREE_TIER_ARCHITECTURE.md) for full implementation details, code presets, and limits configuration.
184
+
185
+ ---
186
+
187
+ ## 6. Next.js App Router Integration & Framework Lock-in (PKG-1)
188
+
189
+ The SDK's prebuilt server handlers (`createChatHandler`, `createStreamHandler`, `createUploadHandler`) import directly from `next/server`. They are tightly coupled to the Next.js App Router API context and expect standard Next.js requests and responses.
190
+
191
+ If you are deploying in non-Next.js server environments (such as Express, Fastify, Hono, or custom Node.js frameworks), do **not** use the route handlers. Instead, invoke the core `LicensedRetrivora` SDK methods directly within your custom controllers:
192
+ ```typescript
193
+ import { createRetrivora } from '@retrivora-ai/rag-engine';
194
+
195
+ // Framework-agnostic controller example
196
+ app.post('/api/chat', async (req, res) => {
197
+ const sdk = await createRetrivora({
198
+ projectId: 'my-project',
199
+ licenseKey: process.env.RETRIVORA_LICENSE_KEY,
200
+ });
201
+ const answer = await sdk.query(req.body.message);
202
+ res.json(answer);
203
+ });
204
+ ```
205
+
206
+
@@ -1,3 +1,3 @@
1
1
  import 'next/server';
2
- export { b as HandlerOptions, d as createChatHandler, e as createFeedbackHandler, f as createHealthHandler, g as createHistoryHandler, h as createIngestHandler, p as createLicenseHandler, i as createRagHandler, j as createSessionsHandler, k as createStreamHandler, q as createSuggestionsHandler, l as createUploadHandler, s as sseErrorFrame, m as sseFrame, n as sseMetaFrame, r as sseObservabilityFrame, o as sseTextFrame, t as sseUIFrame } from '../index-D2mY1CrY.mjs';
3
- import '../ILLMProvider-BynaFBpy.mjs';
2
+ export { b as HandlerOptions, d as createChatHandler, e as createFeedbackHandler, f as createHealthHandler, g as createHistoryHandler, h as createIngestHandler, p as createLicenseHandler, i as createRagHandler, j as createSessionsHandler, k as createStreamHandler, q as createSuggestionsHandler, l as createUploadHandler, s as sseErrorFrame, m as sseFrame, n as sseMetaFrame, r as sseObservabilityFrame, o as sseTextFrame, t as sseUIFrame } from '../index-DE8qPWpI.mjs';
3
+ import '../ILLMProvider-DO5gj-e5.mjs';
@@ -1,3 +1,3 @@
1
1
  import 'next/server';
2
- export { b as HandlerOptions, d as createChatHandler, e as createFeedbackHandler, f as createHealthHandler, g as createHistoryHandler, h as createIngestHandler, p as createLicenseHandler, i as createRagHandler, j as createSessionsHandler, k as createStreamHandler, q as createSuggestionsHandler, l as createUploadHandler, s as sseErrorFrame, m as sseFrame, n as sseMetaFrame, r as sseObservabilityFrame, o as sseTextFrame, t as sseUIFrame } from '../index-BC635WW-.js';
3
- import '../ILLMProvider-BynaFBpy.js';
2
+ export { b as HandlerOptions, d as createChatHandler, e as createFeedbackHandler, f as createHealthHandler, g as createHistoryHandler, h as createIngestHandler, p as createLicenseHandler, i as createRagHandler, j as createSessionsHandler, k as createStreamHandler, q as createSuggestionsHandler, l as createUploadHandler, s as sseErrorFrame, m as sseFrame, n as sseMetaFrame, r as sseObservabilityFrame, o as sseTextFrame, t as sseUIFrame } from '../index-DkOhRqEc.js';
3
+ import '../ILLMProvider-DO5gj-e5.js';