@retrivora-ai/rag-engine 2.0.2 → 2.0.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.
Files changed (51) hide show
  1. package/FREE_TIER_ARCHITECTURE.md +232 -0
  2. package/README.md +9 -0
  3. package/dist/{ILLMProvider-DMxLyTdq.d.mts → ILLMProvider-0rRBYbVW.d.mts} +133 -1
  4. package/dist/{ILLMProvider-DMxLyTdq.d.ts → ILLMProvider-0rRBYbVW.d.ts} +133 -1
  5. package/dist/handlers/index.d.mts +2 -2
  6. package/dist/handlers/index.d.ts +2 -2
  7. package/dist/handlers/index.js +681 -17
  8. package/dist/handlers/index.mjs +681 -17
  9. package/dist/index-B1wGUlSL.d.mts +532 -0
  10. package/dist/{index-tzwc7UhY.d.ts → index-BIHHp_f6.d.ts} +1 -1
  11. package/dist/{index-DHsFLJXQ.d.mts → index-BvODr57d.d.mts} +1 -1
  12. package/dist/index-DcklhThn.d.ts +532 -0
  13. package/dist/index.css +51 -3
  14. package/dist/index.d.mts +6 -105
  15. package/dist/index.d.ts +6 -105
  16. package/dist/index.js +1918 -8
  17. package/dist/index.mjs +1913 -8
  18. package/dist/server.d.mts +51 -7
  19. package/dist/server.d.ts +51 -7
  20. package/dist/server.js +723 -17
  21. package/dist/server.mjs +706 -17
  22. package/package.json +9 -7
  23. package/src/app/page.tsx +54 -18
  24. package/src/components/ChatWindow.tsx +2 -2
  25. package/src/components/DocumentUpload.tsx +5 -4
  26. package/src/components/MessageBubble.tsx +2 -4
  27. package/src/core/DatabaseStorage.ts +5 -1
  28. package/src/core/LicenseVerifier.ts +1 -1
  29. package/src/core/Pipeline.ts +23 -5
  30. package/src/handlers/index.ts +48 -1
  31. package/src/index.ts +22 -4
  32. package/src/rendering/IntentClassifier.ts +167 -0
  33. package/src/rendering/RendererRegistry.ts +164 -0
  34. package/src/rendering/RuleEngine.ts +67 -0
  35. package/src/rendering/VisualizationDecisionEngine.ts +164 -0
  36. package/src/rendering/__tests__/VisualizationDecisionEngine.test.ts +237 -0
  37. package/src/rendering/index.ts +12 -0
  38. package/src/rendering/rules/Rule1SpecificInfoRule.ts +28 -0
  39. package/src/rendering/rules/Rule2ComparisonRule.ts +24 -0
  40. package/src/rendering/rules/Rule3ProductDiscoveryRule.ts +28 -0
  41. package/src/rendering/rules/Rule4AnalyticalRule.ts +38 -0
  42. package/src/rendering/rules/Rule5MixedResponseRule.ts +29 -0
  43. package/src/rendering/rules/Rule6SmallResultSetRule.ts +24 -0
  44. package/src/rendering/rules/Rule7LargeTableRule.ts +35 -0
  45. package/src/rendering/types.ts +96 -0
  46. package/src/server.ts +3 -2
  47. package/src/types/index.ts +48 -0
  48. package/src/utils/DocumentParser.ts +64 -28
  49. package/src/utils/UITransformer.ts +15 -4
  50. package/dist/index-CfkqZd2Y.d.ts +0 -197
  51. package/dist/index-xygonxpW.d.mts +0 -197
@@ -0,0 +1,232 @@
1
+ # Retrivora Free Tier (MVP) Architecture & Implementation Guide
2
+
3
+ This document outlines the architecture, constraints, and SDK integration patterns for the **Retrivora Free Tier (MVP)**. The objective of this design is to maximize functionality for multi-tenant users while maintaining near-zero fixed infrastructure costs per tenant.
4
+
5
+ ---
6
+
7
+ ## 1. Overview & Core Philosophy
8
+
9
+ The Retrivora Free Tier is built around an intentionally small, highly cost-efficient scope:
10
+
11
+ - **Storage Isolation**: Single shared vector database index with multi-tenancy via **Pinecone Namespaces**.
12
+ - **Fixed Embedding Footprint**: Standardized on **768-dimension embeddings** (e.g. `nomic-embed-text` or `bge-base-en-v1.5`).
13
+ - **Vendor-Agnostic LLM Routing**: Unified LLM proxy layer via **LiteLLM** (exposing an OpenAI-compatible REST interface).
14
+ - **Simple Retrieval**: Standardized semantic RAG flow ($ \text{Search} \rightarrow \text{Top-K} \rightarrow \text{Rerank (optional)} \rightarrow \text{Prompt} \rightarrow \text{LLM} $).
15
+ - **Document Support**: Core business formats only (`PDF`, `DOCX`, `TXT`, `Markdown`).
16
+ - **Deterministic Limits**: Strict operational guardrails to prevent infrastructure cost overruns.
17
+
18
+ ---
19
+
20
+ ## 2. Component Specifications
21
+
22
+ ### 2.1 Storage & Multi-Tenancy (Pinecone)
23
+
24
+ Instead of instantiating dedicated Pinecone accounts or indexes per user, all free-tier tenants share **one Retrivora Pinecone index** (`retrivora-free`). Complete tenant data isolation is guaranteed using **Pinecone Namespaces**.
25
+
26
+ ```
27
+ Pinecone Index: retrivora-free (768 dimensions, Cosine metric)
28
+ ├── Namespace: john@example.com
29
+ ├── Namespace: abc-company
30
+ └── Namespace: workspace-123
31
+ ```
32
+
33
+ - **Index Name**: `retrivora-free`
34
+ - **Vector Dimension**: `768`
35
+ - **Isolation Scope**: One namespace per project / user / workspace (`projectId`).
36
+ - **Metadata Filtering**: Fully supported within each isolated namespace.
37
+
38
+ ---
39
+
40
+ ### 2.2 Embedding Model Strategy
41
+
42
+ To standardize vector dimension sizes across the shared index:
43
+
44
+ - **Dimensions**: `768`
45
+ - **Recommended Models**:
46
+ - `nomic-embed-text` (Ollama or REST, using task prefixes `search_query: ` and `search_document: `).
47
+ - `BAAI/bge-base-en-v1.5` (768-dimension sentence transformer).
48
+ - `BAAI/bge-small-en-v1.5` (384-dimension fallback if required).
49
+
50
+ ---
51
+
52
+ ### 2.3 LLM Routing Layer (LiteLLM Abstraction)
53
+
54
+ Retrivora integrates with **LiteLLM** as a centralized model gateway. Host applications configure a single LiteLLM endpoint, giving end users access to OpenAI, Gemini, Claude, Groq, Ollama, Azure OpenAI, and OpenRouter without vendor lock-in.
55
+
56
+ ```
57
+ Retrivora SDK ──► LiteLLM Gateway (/v1) ──► OpenAI / Gemini / Claude / Groq / Ollama / OpenRouter
58
+ ```
59
+
60
+ ---
61
+
62
+ ### 2.4 Retrieval Pipeline
63
+
64
+ The Free Tier enforces a simple, high-speed semantic search pipeline:
65
+
66
+ ```
67
+ User Query ──► Embedding ──► Pinecone Top-K Search ──► (Optional Rerank) ──► Prompt Assembly ──► LLM Generation
68
+ ```
69
+
70
+ * **Disabled Features on Free Tier**:
71
+ - Graph retrieval (`useGraphRetrieval: false`)
72
+ - Agentic routing & workflows
73
+ - Hybrid BM25 / dense search
74
+
75
+ ---
76
+
77
+ ### 2.5 Document Ingestion & Parsing & Global Metadata Schema
78
+
79
+ Supported formats handled by `DocumentParser` & `FreeTierIngestor`:
80
+ - `.txt` (Text files)
81
+ - `.json` (Structured JSON documents)
82
+ - `.pdf` (PDF documents via `pdf-parse`)
83
+ - `.xlsx` / `.xls` (Excel spreadsheets via `xlsx` sheet-to-csv)
84
+ - `.docx` / `.doc` (Word documents via `mammoth`)
85
+ - `.md` (Markdown text)
86
+ - `.csv` (Comma-separated values)
87
+
88
+ #### Global Chunk Metadata Schema (`RetrivoraChunkMetadata`):
89
+ All vectors upserted into Pinecone namespaces conform to a standardized schema:
90
+ ```typescript
91
+ interface RetrivoraChunkMetadata {
92
+ docId: string;
93
+ fileName: string;
94
+ fileType: 'txt' | 'json' | 'pdf' | 'excel' | 'word' | 'md' | 'csv' | string;
95
+ mimeType: string;
96
+ chunkIndex: number;
97
+ totalChunks: number;
98
+ content: string;
99
+ characterCount: number;
100
+ workspaceId: string;
101
+ pineconeNamespace: string;
102
+ tier: 'free' | 'enterprise';
103
+ ingestedAt: string;
104
+ customMetadata?: Record<string, unknown>;
105
+ }
106
+ ```
107
+
108
+ ---
109
+
110
+ ### 2.6 Chunking Configuration
111
+
112
+ - **Strategy**: `Recursive Character Splitter`
113
+ - **Target Chunk Size**: `500–800 tokens` ($\approx 2,000–3,200$ characters)
114
+ - **Chunk Overlap**: `100 tokens` ($\approx 400$ characters)
115
+ - **Separators**: `['\n# ', '\n## ', '\n### ', '\n\n', '\n', ' ', '']`
116
+
117
+ ---
118
+
119
+ ### 2.7 Operational Free Tier Limits
120
+
121
+ | Feature / Resource | Free Tier Limit |
122
+ | :--- | :--- |
123
+ | **Documents** | `20` max per workspace |
124
+ | **Storage Size** | `50 MB` total file limit |
125
+ | **Total Embeddings** | `10,000` vectors |
126
+ | **Queries / Day** | `100` queries |
127
+ | **Users / Workspaces** | `1` user, `1` namespace, `1` project |
128
+
129
+ ---
130
+
131
+ ## 3. Retrivora SDK Integration
132
+
133
+ ### 3.1 Free Tier Configuration Code Example
134
+
135
+ Host applications can configure Retrivora using `ConfigBuilder`:
136
+
137
+ ```typescript
138
+ import { ConfigBuilder, Retrivora } from '@retrivora-ai/rag-engine/server';
139
+
140
+ // 1. Construct Free Tier Configuration
141
+ const config = new ConfigBuilder()
142
+ .projectId("workspace-123") // Mapped directly to Pinecone Namespace
143
+ .vectorDb("pinecone", {
144
+ indexName: "retrivora-free",
145
+ apiKey: process.env.PINECONE_API_KEY,
146
+ })
147
+ .llm("universal_rest", "groq/llama-3.3-70b-versatile", process.env.LITELLM_API_KEY, {
148
+ baseUrl: process.env.LITELLM_BASE_URL || "http://localhost:4000/v1",
149
+ profile: "litellm",
150
+ temperature: 0.7,
151
+ maxTokens: 1024,
152
+ })
153
+ .embedding("ollama", "nomic-embed-text", undefined, {
154
+ baseUrl: process.env.OLLAMA_BASE_URL || "http://localhost:11434",
155
+ dimensions: 768,
156
+ queryPrefix: "search_query: ",
157
+ documentPrefix: "search_document: ",
158
+ })
159
+ .rag({
160
+ architecture: "simple",
161
+ topK: 5,
162
+ chunkSize: 2500,
163
+ chunkOverlap: 400,
164
+ chunkingStrategy: "recursive",
165
+ useGraphRetrieval: false,
166
+ useQueryTransformation: false,
167
+ })
168
+ .build();
169
+
170
+ // 2. Initialize Engine Instance
171
+ const retrivora = new Retrivora(config);
172
+ await retrivora.initialize();
173
+ ```
174
+
175
+ ---
176
+
177
+ ### 3.2 Free Tier Preset Helper Function
178
+
179
+ ```typescript
180
+ export const FREE_TIER_LIMITS = {
181
+ maxDocuments: 20,
182
+ maxStorageBytes: 50 * 1024 * 1024, // 50 MB
183
+ maxEmbeddings: 10000,
184
+ maxQueriesPerDay: 100,
185
+ allowedFormats: ['.pdf', '.docx', '.txt', '.md'],
186
+ };
187
+
188
+ export function createFreeTierConfig(params: {
189
+ workspaceId: string;
190
+ pineconeApiKey: string;
191
+ liteLlmApiKey?: string;
192
+ liteLlmBaseUrl?: string;
193
+ }) {
194
+ return new ConfigBuilder()
195
+ .projectId(params.workspaceId)
196
+ .vectorDb("pinecone", {
197
+ indexName: "retrivora-free",
198
+ apiKey: params.pineconeApiKey,
199
+ })
200
+ .llm("universal_rest", "gpt-4o-mini", params.liteLlmApiKey, {
201
+ baseUrl: params.liteLlmBaseUrl || "http://localhost:4000/v1",
202
+ profile: "litellm",
203
+ })
204
+ .embedding("ollama", "nomic-embed-text", undefined, {
205
+ dimensions: 768,
206
+ })
207
+ .rag({
208
+ architecture: "simple",
209
+ topK: 5,
210
+ chunkSize: 2500,
211
+ chunkOverlap: 400,
212
+ chunkingStrategy: "recursive",
213
+ useGraphRetrieval: false,
214
+ })
215
+ .build();
216
+ }
217
+ ```
218
+
219
+ ---
220
+
221
+ ## 4. Feature Comparison Matrix
222
+
223
+ | Feature | Free Tier (MVP) | Enterprise Tier |
224
+ | :--- | :--- | :--- |
225
+ | **Vector DB Index** | Shared (`retrivora-free`) | Dedicated index / cluster |
226
+ | **Tenancy Isolation** | Namespace | Index / Database / Cloud Project |
227
+ | **Embedding Model** | Fixed 768-dim (`nomic-embed-text`, `bge-base`) | Custom / Multimodal / Any dim |
228
+ | **LLM Gateway** | LiteLLM Proxy | Direct API / LiteLLM / Enterprise VPC |
229
+ | **Retrieval Mode** | Semantic Search (Top-K) | Hybrid + Graph RAG + Agentic Routing |
230
+ | **Document Formats** | PDF, DOCX, TXT, MD | All formats + Web scraping + Audio |
231
+ | **Document Limit** | 20 documents | Unlimited |
232
+ | **Storage Limit** | 50 MB | Custom / Unlimited |
package/README.md CHANGED
@@ -173,3 +173,12 @@ The SDK enforces license key verification at runtime depending on the hosting en
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
  | **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
+
@@ -424,6 +424,12 @@ interface RetrievalResult {
424
424
  sources: VectorMatch[];
425
425
  graphData?: GraphSearchResult;
426
426
  }
427
+ interface IRetriever {
428
+ retrieve(query: string, options?: Record<string, unknown>): Promise<RetrievalResult>;
429
+ }
430
+ interface SuggestionsResponse {
431
+ suggestions: string[];
432
+ }
427
433
  interface Product {
428
434
  id: string | number;
429
435
  name: string;
@@ -433,6 +439,132 @@ interface Product {
433
439
  link?: string;
434
440
  description?: string;
435
441
  }
442
+ /**
443
+ * Supported UI visualization types
444
+ */
445
+ type VisualizationType = 'pie_chart' | 'bar_chart' | 'line_chart' | 'histogram' | 'horizontal_bar' | 'scatter_plot' | 'radar_chart' | 'metric_card' | 'geo_map' | 'table' | 'product_carousel' | 'carousel' | 'text';
446
+ /**
447
+ * Base structure for all UI transformation responses
448
+ */
449
+ interface UITransformationResponse {
450
+ type: VisualizationType;
451
+ title: string;
452
+ description?: string;
453
+ data: unknown;
454
+ }
455
+ /**
456
+ * Pie chart data structure
457
+ */
458
+ interface PieChartData {
459
+ label: string;
460
+ value: number;
461
+ inStockCount?: number;
462
+ outOfStockCount?: number;
463
+ [key: string]: unknown;
464
+ }
465
+ /**
466
+ * Bar chart data structure
467
+ */
468
+ interface BarChartData {
469
+ category: string;
470
+ value: number;
471
+ inStockCount?: number;
472
+ outOfStockCount?: number;
473
+ [key: string]: unknown;
474
+ }
475
+ /**
476
+ * Line chart data point
477
+ */
478
+ interface LineChartDataPoint {
479
+ timestamp: string | number;
480
+ value: number;
481
+ label?: string;
482
+ [key: string]: unknown;
483
+ }
484
+ /**
485
+ * Scatter plot data point
486
+ */
487
+ interface ScatterPlotDataPoint {
488
+ x: number;
489
+ y: number;
490
+ label?: string;
491
+ [key: string]: unknown;
492
+ }
493
+ /**
494
+ * KPI / metric card representation
495
+ */
496
+ interface MetricCardData {
497
+ label: string;
498
+ value: number;
499
+ operation?: 'sum' | 'average' | 'count' | 'min' | 'max' | 'median';
500
+ unit?: string;
501
+ details?: Record<string, string | number | boolean>;
502
+ }
503
+ /**
504
+ * Table representation
505
+ */
506
+ interface TableData {
507
+ columns: string[];
508
+ rows: (string | number | boolean)[][];
509
+ }
510
+ /**
511
+ * Product carousel item
512
+ */
513
+ interface CarouselProduct {
514
+ id: string | number;
515
+ name: string;
516
+ price?: number | string;
517
+ image?: string;
518
+ inStock?: boolean;
519
+ brand?: string;
520
+ description?: string;
521
+ [key: string]: unknown;
522
+ }
523
+
524
+ /**
525
+ * Standardized Retrivora Metadata Schema for document vectors and storage.
526
+ * Guarantees uniform metadata structure across vector DB backends (Pinecone, MongoDB, etc.).
527
+ */
528
+ interface RetrivoraChunkMetadata {
529
+ /** Document unique identifier */
530
+ docId: string;
531
+ /** Original file name (e.g. report.pdf, data.json, sheets.xlsx) */
532
+ fileName: string;
533
+ /** File format type identifier */
534
+ fileType: 'txt' | 'json' | 'pdf' | 'excel' | 'word' | 'md' | 'csv' | string;
535
+ /** MIME type string */
536
+ mimeType: string;
537
+ /** 0-indexed position of chunk within the parent document */
538
+ chunkIndex: number;
539
+ /** Total count of chunks in the document */
540
+ totalChunks: number;
541
+ /** Extracted text content of the chunk */
542
+ content: string;
543
+ /** Character length of the chunk content */
544
+ characterCount: number;
545
+ /** Workspace or Project ID */
546
+ workspaceId: string;
547
+ /** Isolated vector database namespace (e.g. Pinecone namespace) */
548
+ pineconeNamespace: string;
549
+ /** Retrivora Tier level */
550
+ tier: 'free' | 'enterprise';
551
+ /** ISO 8601 timestamp when the document was processed */
552
+ ingestedAt: string;
553
+ /** Additional custom metadata Key-Value pairs */
554
+ customMetadata?: Record<string, unknown>;
555
+ }
556
+ interface RetrivoraIngestedDocument {
557
+ docId: string;
558
+ fileName: string;
559
+ fileType: string;
560
+ mimeType: string;
561
+ fileSizeBytes?: number;
562
+ totalChunks: number;
563
+ workspaceId: string;
564
+ pineconeNamespace: string;
565
+ ingestedAt: string;
566
+ chunks: RetrivoraChunkMetadata[];
567
+ }
436
568
 
437
569
  /**
438
570
  * Generic LLM Provider interface.
@@ -480,4 +612,4 @@ interface ILLMProvider {
480
612
  ping(): Promise<boolean>;
481
613
  }
482
614
 
483
- export type { ChatMessage as C, EmbedOptions as E, GraphDBConfig as G, ILLMProvider as I, LLMConfig as L, ObservabilityTrace as O, Product as P, RagMessage as R, TokenUsage as T, UIConfig as U, VectorMatch as V, WorkflowConfig as W, UseRagChatOptions as a, UseRagChatReturn as b, ChatOptions as c, ChatResponse as d, EmbeddingConfig as e, EmbeddingProvider as f, IngestDocument as g, LLMProvider as h, LatencyBreakdown as i, RAGConfig as j, RagConfig as k, RetrievalConfig as l, RetrievedChunk as m, UniversalRagConfig as n, UpsertDocument as o, VectorDBConfig as p, VectorDBProvider as q, GraphNode as r, Edge as s, GraphSearchResult as t, RetrievalResult as u };
615
+ export type { RetrivoraChunkMetadata as A, BarChartData as B, ChatMessage as C, RetrivoraIngestedDocument as D, EmbedOptions as E, SuggestionsResponse as F, GraphDBConfig as G, TableData as H, ILLMProvider as I, UITransformationResponse as J, VisualizationType as K, LLMConfig as L, MessageRole as M, ObservabilityTrace as O, PieChartData as P, RAGConfig as R, ScatterPlotDataPoint as S, TokenUsage as T, UseRagChatOptions as U, VectorDBConfig as V, WorkflowConfig as W, UseRagChatReturn as a, ChatOptions as b, ChatResponse as c, EmbeddingConfig as d, EmbeddingProvider as e, IngestDocument as f, LLMProvider as g, LatencyBreakdown as h, RagConfig as i, RagMessage as j, RetrievalConfig as k, RetrievedChunk as l, UIConfig as m, UniversalRagConfig as n, UpsertDocument as o, VectorDBProvider as p, VectorMatch as q, GraphNode as r, Edge as s, GraphSearchResult as t, CarouselProduct as u, IRetriever as v, LineChartDataPoint as w, MetricCardData as x, Product as y, RetrievalResult as z };
@@ -424,6 +424,12 @@ interface RetrievalResult {
424
424
  sources: VectorMatch[];
425
425
  graphData?: GraphSearchResult;
426
426
  }
427
+ interface IRetriever {
428
+ retrieve(query: string, options?: Record<string, unknown>): Promise<RetrievalResult>;
429
+ }
430
+ interface SuggestionsResponse {
431
+ suggestions: string[];
432
+ }
427
433
  interface Product {
428
434
  id: string | number;
429
435
  name: string;
@@ -433,6 +439,132 @@ interface Product {
433
439
  link?: string;
434
440
  description?: string;
435
441
  }
442
+ /**
443
+ * Supported UI visualization types
444
+ */
445
+ type VisualizationType = 'pie_chart' | 'bar_chart' | 'line_chart' | 'histogram' | 'horizontal_bar' | 'scatter_plot' | 'radar_chart' | 'metric_card' | 'geo_map' | 'table' | 'product_carousel' | 'carousel' | 'text';
446
+ /**
447
+ * Base structure for all UI transformation responses
448
+ */
449
+ interface UITransformationResponse {
450
+ type: VisualizationType;
451
+ title: string;
452
+ description?: string;
453
+ data: unknown;
454
+ }
455
+ /**
456
+ * Pie chart data structure
457
+ */
458
+ interface PieChartData {
459
+ label: string;
460
+ value: number;
461
+ inStockCount?: number;
462
+ outOfStockCount?: number;
463
+ [key: string]: unknown;
464
+ }
465
+ /**
466
+ * Bar chart data structure
467
+ */
468
+ interface BarChartData {
469
+ category: string;
470
+ value: number;
471
+ inStockCount?: number;
472
+ outOfStockCount?: number;
473
+ [key: string]: unknown;
474
+ }
475
+ /**
476
+ * Line chart data point
477
+ */
478
+ interface LineChartDataPoint {
479
+ timestamp: string | number;
480
+ value: number;
481
+ label?: string;
482
+ [key: string]: unknown;
483
+ }
484
+ /**
485
+ * Scatter plot data point
486
+ */
487
+ interface ScatterPlotDataPoint {
488
+ x: number;
489
+ y: number;
490
+ label?: string;
491
+ [key: string]: unknown;
492
+ }
493
+ /**
494
+ * KPI / metric card representation
495
+ */
496
+ interface MetricCardData {
497
+ label: string;
498
+ value: number;
499
+ operation?: 'sum' | 'average' | 'count' | 'min' | 'max' | 'median';
500
+ unit?: string;
501
+ details?: Record<string, string | number | boolean>;
502
+ }
503
+ /**
504
+ * Table representation
505
+ */
506
+ interface TableData {
507
+ columns: string[];
508
+ rows: (string | number | boolean)[][];
509
+ }
510
+ /**
511
+ * Product carousel item
512
+ */
513
+ interface CarouselProduct {
514
+ id: string | number;
515
+ name: string;
516
+ price?: number | string;
517
+ image?: string;
518
+ inStock?: boolean;
519
+ brand?: string;
520
+ description?: string;
521
+ [key: string]: unknown;
522
+ }
523
+
524
+ /**
525
+ * Standardized Retrivora Metadata Schema for document vectors and storage.
526
+ * Guarantees uniform metadata structure across vector DB backends (Pinecone, MongoDB, etc.).
527
+ */
528
+ interface RetrivoraChunkMetadata {
529
+ /** Document unique identifier */
530
+ docId: string;
531
+ /** Original file name (e.g. report.pdf, data.json, sheets.xlsx) */
532
+ fileName: string;
533
+ /** File format type identifier */
534
+ fileType: 'txt' | 'json' | 'pdf' | 'excel' | 'word' | 'md' | 'csv' | string;
535
+ /** MIME type string */
536
+ mimeType: string;
537
+ /** 0-indexed position of chunk within the parent document */
538
+ chunkIndex: number;
539
+ /** Total count of chunks in the document */
540
+ totalChunks: number;
541
+ /** Extracted text content of the chunk */
542
+ content: string;
543
+ /** Character length of the chunk content */
544
+ characterCount: number;
545
+ /** Workspace or Project ID */
546
+ workspaceId: string;
547
+ /** Isolated vector database namespace (e.g. Pinecone namespace) */
548
+ pineconeNamespace: string;
549
+ /** Retrivora Tier level */
550
+ tier: 'free' | 'enterprise';
551
+ /** ISO 8601 timestamp when the document was processed */
552
+ ingestedAt: string;
553
+ /** Additional custom metadata Key-Value pairs */
554
+ customMetadata?: Record<string, unknown>;
555
+ }
556
+ interface RetrivoraIngestedDocument {
557
+ docId: string;
558
+ fileName: string;
559
+ fileType: string;
560
+ mimeType: string;
561
+ fileSizeBytes?: number;
562
+ totalChunks: number;
563
+ workspaceId: string;
564
+ pineconeNamespace: string;
565
+ ingestedAt: string;
566
+ chunks: RetrivoraChunkMetadata[];
567
+ }
436
568
 
437
569
  /**
438
570
  * Generic LLM Provider interface.
@@ -480,4 +612,4 @@ interface ILLMProvider {
480
612
  ping(): Promise<boolean>;
481
613
  }
482
614
 
483
- export type { ChatMessage as C, EmbedOptions as E, GraphDBConfig as G, ILLMProvider as I, LLMConfig as L, ObservabilityTrace as O, Product as P, RagMessage as R, TokenUsage as T, UIConfig as U, VectorMatch as V, WorkflowConfig as W, UseRagChatOptions as a, UseRagChatReturn as b, ChatOptions as c, ChatResponse as d, EmbeddingConfig as e, EmbeddingProvider as f, IngestDocument as g, LLMProvider as h, LatencyBreakdown as i, RAGConfig as j, RagConfig as k, RetrievalConfig as l, RetrievedChunk as m, UniversalRagConfig as n, UpsertDocument as o, VectorDBConfig as p, VectorDBProvider as q, GraphNode as r, Edge as s, GraphSearchResult as t, RetrievalResult as u };
615
+ export type { RetrivoraChunkMetadata as A, BarChartData as B, ChatMessage as C, RetrivoraIngestedDocument as D, EmbedOptions as E, SuggestionsResponse as F, GraphDBConfig as G, TableData as H, ILLMProvider as I, UITransformationResponse as J, VisualizationType as K, LLMConfig as L, MessageRole as M, ObservabilityTrace as O, PieChartData as P, RAGConfig as R, ScatterPlotDataPoint as S, TokenUsage as T, UseRagChatOptions as U, VectorDBConfig as V, WorkflowConfig as W, UseRagChatReturn as a, ChatOptions as b, ChatResponse as c, EmbeddingConfig as d, EmbeddingProvider as e, IngestDocument as f, LLMProvider as g, LatencyBreakdown as h, RagConfig as i, RagMessage as j, RetrievalConfig as k, RetrievedChunk as l, UIConfig as m, UniversalRagConfig as n, UpsertDocument as o, VectorDBProvider as p, VectorMatch as q, GraphNode as r, Edge as s, GraphSearchResult as t, CarouselProduct as u, IRetriever as v, LineChartDataPoint as w, MetricCardData as x, Product as y, RetrievalResult as z };
@@ -1,3 +1,3 @@
1
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-DHsFLJXQ.mjs';
3
- import '../ILLMProvider-DMxLyTdq.mjs';
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-BvODr57d.mjs';
3
+ import '../ILLMProvider-0rRBYbVW.mjs';
@@ -1,3 +1,3 @@
1
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-tzwc7UhY.js';
3
- import '../ILLMProvider-DMxLyTdq.js';
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-BIHHp_f6.js';
3
+ import '../ILLMProvider-0rRBYbVW.js';