@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 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: Offline RS256 JWT Decryption
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. **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.
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
- | **Air-Gapped / Offline** | **Valid Signed JWT** | **Fail-Open on Telemetry**: Verifies signature cryptographically offline. Works with no internet connection. |
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](file:///Users/abhinavalkuchi/work/retrivora-ai/packages/sdk/FREE_TIER_ARCHITECTURE.md) for full implementation details, code presets, and limits configuration.
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
- systemPrompt: string;
447
- userPrompt: string;
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, createDefaultProjectSettings as B, type ChatMessage as C, normalizeProjectSettings as D, type EmbedOptions as E, projectSettingsToUiConfig as F, type GraphDBConfig as G, type GraphNode as H, type ILLMProvider as I, type Edge as J, type GraphSearchResult as K, type LLMConfig as L, type BarChartData as M, type CarouselProduct as N, type ObservabilityTrace as O, type Product as P, type IRetriever as Q, type RAGConfig as R, type LineChartDataPoint as S, type ThemeMode as T, type UITransformationResponse as U, type VectorDBConfig as V, type WidgetPosition as W, type MessageRole as X, type MetricCardData as Y, type PieChartData as Z, type RetrievalResult as _, type UseRagChatOptions as a, type RetrivoraIngestedDocument as a0, type ScatterPlotDataPoint as a1, type SuggestionsResponse as a2, type TableData as a3, type VisualizationType as a4, type UseRagChatReturn as b, type ProjectChatSettings as c, type ChatOptions as d, type ChatResponse as e, type EmbeddingConfig as f, type EmbeddingProvider as g, type IngestDocument as h, type LLMProvider as i, type LatencyBreakdown as j, type ProjectAiSettings as k, type ProjectAuthSettings as l, type ProjectBrandingSettings as m, type ProjectTelemetrySettings as n, type ProjectWidgetSettings as o, type RagConfig as p, type RagMessage as q, type RetrievalConfig as r, type RetrievedChunk as s, type TokenUsage as t, type UIConfig as u, type UniversalRagConfig as v, type UpsertDocument as w, type VectorDBProvider as x, type VectorMatch as y, type WorkflowConfig as z };
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
- systemPrompt: string;
447
- userPrompt: string;
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, createDefaultProjectSettings as B, type ChatMessage as C, normalizeProjectSettings as D, type EmbedOptions as E, projectSettingsToUiConfig as F, type GraphDBConfig as G, type GraphNode as H, type ILLMProvider as I, type Edge as J, type GraphSearchResult as K, type LLMConfig as L, type BarChartData as M, type CarouselProduct as N, type ObservabilityTrace as O, type Product as P, type IRetriever as Q, type RAGConfig as R, type LineChartDataPoint as S, type ThemeMode as T, type UITransformationResponse as U, type VectorDBConfig as V, type WidgetPosition as W, type MessageRole as X, type MetricCardData as Y, type PieChartData as Z, type RetrievalResult as _, type UseRagChatOptions as a, type RetrivoraIngestedDocument as a0, type ScatterPlotDataPoint as a1, type SuggestionsResponse as a2, type TableData as a3, type VisualizationType as a4, type UseRagChatReturn as b, type ProjectChatSettings as c, type ChatOptions as d, type ChatResponse as e, type EmbeddingConfig as f, type EmbeddingProvider as g, type IngestDocument as h, type LLMProvider as i, type LatencyBreakdown as j, type ProjectAiSettings as k, type ProjectAuthSettings as l, type ProjectBrandingSettings as m, type ProjectTelemetrySettings as n, type ProjectWidgetSettings as o, type RagConfig as p, type RagMessage as q, type RetrievalConfig as r, type RetrievedChunk as s, type TokenUsage as t, type UIConfig as u, type UniversalRagConfig as v, type UpsertDocument as w, type VectorDBProvider as x, type VectorMatch as y, type WorkflowConfig as z };
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
- 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-37V810a-.mjs';
3
- import '../ILLMProvider-B2N3lMBc.mjs';
3
+ import '../ILLMProvider-CzXcTA6d.mjs';
@@ -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
- 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-BxzDv2jd.js';
3
- import '../ILLMProvider-B2N3lMBc.js';
3
+ import '../ILLMProvider-CzXcTA6d.js';