@retrivora-ai/rag-engine 2.5.9 → 2.6.2
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 +8 -6
- package/dist/{ILLMProvider-B2N3lMBc.d.mts → ILLMProvider-CzXcTA6d.d.mts} +31 -3
- package/dist/{ILLMProvider-B2N3lMBc.d.ts → ILLMProvider-CzXcTA6d.d.ts} +31 -3
- package/dist/handlers/index.d.mts +2 -2
- package/dist/handlers/index.d.ts +2 -2
- package/dist/handlers/index.js +9815 -8601
- package/dist/handlers/index.mjs +9818 -8612
- package/dist/{index-CAGGPyI7.d.mts → index-BST9Gzsv.d.mts} +8 -7
- package/dist/{index-BxzDv2jd.d.ts → index-CFl4KrKq.d.ts} +58 -46
- package/dist/{index-37V810a-.d.mts → index-D7FuQRSb.d.mts} +58 -46
- package/dist/{index-DdQxoIpu.d.ts → index-qLvtMUr-.d.ts} +8 -7
- package/dist/index.css +23 -0
- package/dist/index.d.mts +4 -4
- package/dist/index.d.ts +4 -4
- package/dist/index.js +267 -187
- package/dist/index.min.css +1 -1
- package/dist/index.mjs +268 -193
- package/dist/server.d.mts +322 -14
- package/dist/server.d.ts +322 -14
- package/dist/server.js +1925 -688
- package/dist/server.mjs +1912 -693
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -32,7 +32,7 @@ sequenceDiagram
|
|
|
32
32
|
activate Facade
|
|
33
33
|
Facade->>Lic: verify(licenseKey, projectId)
|
|
34
34
|
activate Lic
|
|
35
|
-
Note over Lic:
|
|
35
|
+
Note over Lic: Server-backed validation (POST /api/v1/license/validate, 5-min cache)
|
|
36
36
|
Lic-->>Facade: Valid Signature (Green)
|
|
37
37
|
deactivate Lic
|
|
38
38
|
Facade-->>Client: Ready
|
|
@@ -59,7 +59,7 @@ sequenceDiagram
|
|
|
59
59
|
### Key Components:
|
|
60
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
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. **
|
|
62
|
+
3. **Server-Backed Licensing (`LicenseVerifier.ts`)**: License keys are validated against the Retrivora control plane (`POST /api/v1/license/validate`) with a 5-minute success cache and expiration enforcement. Dev mode is fail-open (warning + 24h hobby grant; 10y grant on network error); production is fail-closed (`ConfigurationException` / HTTP 401/403).
|
|
63
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
64
|
|
|
65
65
|
---
|
|
@@ -172,7 +172,7 @@ The SDK enforces license key verification at runtime depending on the hosting en
|
|
|
172
172
|
| :--- | :--- | :--- |
|
|
173
173
|
| **Development** (`process.env.NODE_ENV !== 'production'`) | **Missing / Expired** | **Fail-Open**: Outputs a yellow warning message in the node console. Operations continue. |
|
|
174
174
|
| **Production** (`process.env.NODE_ENV === 'production'`) | **Missing / Expired** | **Fail-Closed**: Throws `ConfigurationException` on `initialize()`. Ingestion/Chat routes are blocked. |
|
|
175
|
-
| **
|
|
175
|
+
| **Offline / No network** | **Any** | **Not supported standalone**: validation calls the Retrivora API (6s timeout); dev falls back to a local hobby grant, production throws. |
|
|
176
176
|
|
|
177
177
|
---
|
|
178
178
|
|
|
@@ -180,7 +180,7 @@ The SDK enforces license key verification at runtime depending on the hosting en
|
|
|
180
180
|
|
|
181
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
182
|
|
|
183
|
-
See [FREE_TIER_ARCHITECTURE.md](
|
|
183
|
+
See [FREE_TIER_ARCHITECTURE.md](./FREE_TIER_ARCHITECTURE.md) for full implementation details, code presets, and limits configuration.
|
|
184
184
|
|
|
185
185
|
---
|
|
186
186
|
|
|
@@ -190,17 +190,19 @@ The SDK's prebuilt server handlers (`createChatHandler`, `createStreamHandler`,
|
|
|
190
190
|
|
|
191
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
192
|
```typescript
|
|
193
|
-
import { createRetrivora } from '@retrivora-ai/rag-engine';
|
|
193
|
+
import { createRetrivora } from '@retrivora-ai/rag-engine/server';
|
|
194
194
|
|
|
195
195
|
// Framework-agnostic controller example
|
|
196
196
|
app.post('/api/chat', async (req, res) => {
|
|
197
197
|
const sdk = await createRetrivora({
|
|
198
198
|
projectId: 'my-project',
|
|
199
|
-
licenseKey: process.env.RETRIVORA_LICENSE_KEY,
|
|
199
|
+
licenseKey: process.env.RETRIVORA_LICENSE_KEY as string,
|
|
200
200
|
});
|
|
201
201
|
const answer = await sdk.query(req.body.message);
|
|
202
202
|
res.json(answer);
|
|
203
203
|
});
|
|
204
204
|
```
|
|
205
205
|
|
|
206
|
+
> **Note:** `createRetrivora` auto-initializes, so no separate `initialize()` call is needed. `query()` returns the full `ChatResponse` (`reply` + `sources` + `trace` + `ui_transformation`).
|
|
207
|
+
|
|
206
208
|
|
|
@@ -443,16 +443,41 @@ interface ObservabilityTrace {
|
|
|
443
443
|
requestId: string;
|
|
444
444
|
query: string;
|
|
445
445
|
rewrittenQuery?: string;
|
|
446
|
-
|
|
447
|
-
|
|
446
|
+
/**
|
|
447
|
+
* System prompt used for this request.
|
|
448
|
+
* @deprecated Excluded from the default trace for security (may contain business logic).
|
|
449
|
+
* Only populated when `includePromptsInTrace` is explicitly enabled.
|
|
450
|
+
*/
|
|
451
|
+
systemPrompt?: string;
|
|
452
|
+
/**
|
|
453
|
+
* User prompt (post-PII masking) used for this request.
|
|
454
|
+
* @deprecated Excluded from the default trace for security.
|
|
455
|
+
* Only populated when `includePromptsInTrace` is explicitly enabled.
|
|
456
|
+
*/
|
|
457
|
+
userPrompt?: string;
|
|
448
458
|
chunks: RetrievedChunk[];
|
|
449
459
|
latency: LatencyBreakdown;
|
|
450
460
|
tokens?: TokenUsage;
|
|
461
|
+
/** LLM model name used to generate the response. */
|
|
451
462
|
model?: string;
|
|
463
|
+
/** LLM provider name (e.g. 'groq', 'openai', 'anthropic'). */
|
|
452
464
|
provider?: string;
|
|
465
|
+
/** Embedding model used for vector search. */
|
|
466
|
+
embeddingModel?: string;
|
|
467
|
+
/** Time-to-first-token in milliseconds (streaming requests only). */
|
|
468
|
+
ttftMs?: number;
|
|
469
|
+
/** Deployment environment (development / production / test). */
|
|
470
|
+
environment?: string;
|
|
453
471
|
/** 0 = fully grounded, 1 = likely hallucinated. */
|
|
454
472
|
hallucinationScore?: number;
|
|
455
473
|
hallucinationReason?: string;
|
|
474
|
+
/** RAG Triad comprehensive scores (Context Relevance, Faithfulness, Answer Relevance). */
|
|
475
|
+
ragTriad?: {
|
|
476
|
+
contextRelevance: number;
|
|
477
|
+
faithfulness: number;
|
|
478
|
+
answerRelevance: number;
|
|
479
|
+
overallQuality: number;
|
|
480
|
+
};
|
|
456
481
|
timestamp: string;
|
|
457
482
|
}
|
|
458
483
|
interface VectorMatch {
|
|
@@ -460,6 +485,9 @@ interface VectorMatch {
|
|
|
460
485
|
score: number;
|
|
461
486
|
content: string;
|
|
462
487
|
metadata?: Record<string, unknown>;
|
|
488
|
+
rerankScore?: number;
|
|
489
|
+
rrfScore?: number;
|
|
490
|
+
bm25Score?: number;
|
|
463
491
|
}
|
|
464
492
|
interface UpsertDocument {
|
|
465
493
|
id: string | number;
|
|
@@ -694,4 +722,4 @@ interface ILLMProvider {
|
|
|
694
722
|
ping(): Promise<boolean>;
|
|
695
723
|
}
|
|
696
724
|
|
|
697
|
-
export { type RetrivoraChunkMetadata as $, type AuthMode as A,
|
|
725
|
+
export { type RetrivoraChunkMetadata as $, type AuthMode as A, type WorkflowConfig as B, type ChatMessage as C, createDefaultProjectSettings as D, type EmbeddingConfig as E, normalizeProjectSettings as F, projectSettingsToUiConfig as G, type GraphDBConfig as H, type ILLMProvider as I, type GraphNode as J, type Edge as K, type LLMConfig as L, type GraphSearchResult as M, type BarChartData as N, type ObservabilityTrace as O, type Product as P, type CarouselProduct as Q, type RagMessage as R, type IRetriever as S, type ThemeMode as T, type UIConfig as U, type VectorMatch as V, type WidgetPosition as W, type LineChartDataPoint as X, type MessageRole as Y, type MetricCardData as Z, type PieChartData as _, type ProjectChatSettings as a, type RetrivoraIngestedDocument as a0, type ScatterPlotDataPoint as a1, type SuggestionsResponse as a2, type TableData as a3, type VisualizationType as a4, type RagConfig as b, type IngestDocument as c, type ChatResponse as d, type RetrievalResult as e, type UniversalRagConfig as f, type UITransformationResponse as g, type VectorDBConfig as h, type UseRagChatOptions as i, type UseRagChatReturn as j, type ChatOptions as k, type EmbedOptions as l, type EmbeddingProvider as m, type LLMProvider as n, type LatencyBreakdown as o, type ProjectAiSettings as p, type ProjectAuthSettings as q, type ProjectBrandingSettings as r, type ProjectTelemetrySettings as s, type ProjectWidgetSettings as t, type RAGConfig as u, type RetrievalConfig as v, type RetrievedChunk as w, type TokenUsage as x, type UpsertDocument as y, type VectorDBProvider as z };
|
|
@@ -443,16 +443,41 @@ interface ObservabilityTrace {
|
|
|
443
443
|
requestId: string;
|
|
444
444
|
query: string;
|
|
445
445
|
rewrittenQuery?: string;
|
|
446
|
-
|
|
447
|
-
|
|
446
|
+
/**
|
|
447
|
+
* System prompt used for this request.
|
|
448
|
+
* @deprecated Excluded from the default trace for security (may contain business logic).
|
|
449
|
+
* Only populated when `includePromptsInTrace` is explicitly enabled.
|
|
450
|
+
*/
|
|
451
|
+
systemPrompt?: string;
|
|
452
|
+
/**
|
|
453
|
+
* User prompt (post-PII masking) used for this request.
|
|
454
|
+
* @deprecated Excluded from the default trace for security.
|
|
455
|
+
* Only populated when `includePromptsInTrace` is explicitly enabled.
|
|
456
|
+
*/
|
|
457
|
+
userPrompt?: string;
|
|
448
458
|
chunks: RetrievedChunk[];
|
|
449
459
|
latency: LatencyBreakdown;
|
|
450
460
|
tokens?: TokenUsage;
|
|
461
|
+
/** LLM model name used to generate the response. */
|
|
451
462
|
model?: string;
|
|
463
|
+
/** LLM provider name (e.g. 'groq', 'openai', 'anthropic'). */
|
|
452
464
|
provider?: string;
|
|
465
|
+
/** Embedding model used for vector search. */
|
|
466
|
+
embeddingModel?: string;
|
|
467
|
+
/** Time-to-first-token in milliseconds (streaming requests only). */
|
|
468
|
+
ttftMs?: number;
|
|
469
|
+
/** Deployment environment (development / production / test). */
|
|
470
|
+
environment?: string;
|
|
453
471
|
/** 0 = fully grounded, 1 = likely hallucinated. */
|
|
454
472
|
hallucinationScore?: number;
|
|
455
473
|
hallucinationReason?: string;
|
|
474
|
+
/** RAG Triad comprehensive scores (Context Relevance, Faithfulness, Answer Relevance). */
|
|
475
|
+
ragTriad?: {
|
|
476
|
+
contextRelevance: number;
|
|
477
|
+
faithfulness: number;
|
|
478
|
+
answerRelevance: number;
|
|
479
|
+
overallQuality: number;
|
|
480
|
+
};
|
|
456
481
|
timestamp: string;
|
|
457
482
|
}
|
|
458
483
|
interface VectorMatch {
|
|
@@ -460,6 +485,9 @@ interface VectorMatch {
|
|
|
460
485
|
score: number;
|
|
461
486
|
content: string;
|
|
462
487
|
metadata?: Record<string, unknown>;
|
|
488
|
+
rerankScore?: number;
|
|
489
|
+
rrfScore?: number;
|
|
490
|
+
bm25Score?: number;
|
|
463
491
|
}
|
|
464
492
|
interface UpsertDocument {
|
|
465
493
|
id: string | number;
|
|
@@ -694,4 +722,4 @@ interface ILLMProvider {
|
|
|
694
722
|
ping(): Promise<boolean>;
|
|
695
723
|
}
|
|
696
724
|
|
|
697
|
-
export { type RetrivoraChunkMetadata as $, type AuthMode as A,
|
|
725
|
+
export { type RetrivoraChunkMetadata as $, type AuthMode as A, type WorkflowConfig as B, type ChatMessage as C, createDefaultProjectSettings as D, type EmbeddingConfig as E, normalizeProjectSettings as F, projectSettingsToUiConfig as G, type GraphDBConfig as H, type ILLMProvider as I, type GraphNode as J, type Edge as K, type LLMConfig as L, type GraphSearchResult as M, type BarChartData as N, type ObservabilityTrace as O, type Product as P, type CarouselProduct as Q, type RagMessage as R, type IRetriever as S, type ThemeMode as T, type UIConfig as U, type VectorMatch as V, type WidgetPosition as W, type LineChartDataPoint as X, type MessageRole as Y, type MetricCardData as Z, type PieChartData as _, type ProjectChatSettings as a, type RetrivoraIngestedDocument as a0, type ScatterPlotDataPoint as a1, type SuggestionsResponse as a2, type TableData as a3, type VisualizationType as a4, type RagConfig as b, type IngestDocument as c, type ChatResponse as d, type RetrievalResult as e, type UniversalRagConfig as f, type UITransformationResponse as g, type VectorDBConfig as h, type UseRagChatOptions as i, type UseRagChatReturn as j, type ChatOptions as k, type EmbedOptions as l, type EmbeddingProvider as m, type LLMProvider as n, type LatencyBreakdown as o, type ProjectAiSettings as p, type ProjectAuthSettings as q, type ProjectBrandingSettings as r, type ProjectTelemetrySettings as s, type ProjectWidgetSettings as t, type RAGConfig as u, type RetrievalConfig as v, type RetrievedChunk as w, type TokenUsage as x, type UpsertDocument as y, type VectorDBProvider as z };
|
|
@@ -1,3 +1,3 @@
|
|
|
1
|
+
export { b as HandlerOptions, d as createChatHandler, e as createFeedbackHandler, f as createHealthHandler, g as createHistoryHandler, h as createIngestHandler, i as createLicenseHandler, j as createRagHandler, k as createSessionsHandler, l as createStreamHandler, m as createSuggestionsHandler, n as createUploadHandler, s as sseErrorFrame, o as sseFrame, p as sseMetaFrame, q as sseObservabilityFrame, r as sseTextFrame, t as sseUIFrame } from '../index-D7FuQRSb.mjs';
|
|
1
2
|
import 'next/server';
|
|
2
|
-
|
|
3
|
-
import '../ILLMProvider-B2N3lMBc.mjs';
|
|
3
|
+
import '../ILLMProvider-CzXcTA6d.mjs';
|
package/dist/handlers/index.d.ts
CHANGED
|
@@ -1,3 +1,3 @@
|
|
|
1
|
+
export { b as HandlerOptions, d as createChatHandler, e as createFeedbackHandler, f as createHealthHandler, g as createHistoryHandler, h as createIngestHandler, i as createLicenseHandler, j as createRagHandler, k as createSessionsHandler, l as createStreamHandler, m as createSuggestionsHandler, n as createUploadHandler, s as sseErrorFrame, o as sseFrame, p as sseMetaFrame, q as sseObservabilityFrame, r as sseTextFrame, t as sseUIFrame } from '../index-CFl4KrKq.js';
|
|
1
2
|
import 'next/server';
|
|
2
|
-
|
|
3
|
-
import '../ILLMProvider-B2N3lMBc.js';
|
|
3
|
+
import '../ILLMProvider-CzXcTA6d.js';
|