@retrivora-ai/rag-engine 1.9.7 → 1.9.9

package/README.md

@@ -1,175 +1,175 @@
-# @retrivora-ai/rag-engine
+# Retrivora RAG Engine SDK
 
-> **Retrivora AI is a plug-and-play AI engine for RAG chat experiences** that can be embedded into Next.js apps or used as a standalone demo app. Bring your own vector database, LLM, embeddings, and UI branding.
-
-[![NPM Version](https://img.shields.io/npm/v/@retrivora-ai/rag-engine?style=flat-square&color=10b981)](https://www.npmjs.com/package/@retrivora-ai/rag-engine)
-[![NPM Downloads](https://img.shields.io/npm/dm/@retrivora-ai/rag-engine?style=flat-square&color=3b82f6)](https://www.npmjs.com/package/@retrivora-ai/rag-engine)
-[![GitHub](https://img.shields.io/badge/GitHub-Repository-black?style=flat-square&logo=github)](https://github.com/abhinav1201/ai-accelerator)
-![Next.js](https://img.shields.io/badge/Next.js-14+-black?style=flat-square&logo=next.js)
-![TailwindCSS](https://img.shields.io/badge/TailwindCSS-v4-38bdf8?style=flat-square&logo=tailwindcss)
+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.
 
 ---
 
-## ✨ Features (v1.0.0)
+## 1. What is the Retrivora SDK?
 
-| Category | Options |
-|---|---|
-| **Vector DBs** | Pinecone, pgVector (PostgreSQL), MongoDB Atlas, ChromaDB, Qdrant, Milvus, Weaviate, Redis |
-| **LLM Providers** | OpenAI, Anthropic Claude, Google Gemini, Ollama, LiteLLM, Universal REST |
-| **Integrations** | **LangChain** (Agentic orchestration), **LlamaIndex** (Semantic chunking) |
-| **Document Ingestion** | Universal support for **PDF**, **DOCX**, **CSV**, **JSON**, **MD**, **TXT** |
-| **Architecture** | **Modular & Pluggable** registry-based system with static health checks & validators |
-| **RAG Patterns** | Simple, Hybrid, Graph-based, and Agentic workflows |
+The SDK is a unified suite designed to abstract the complexity of building production-grade RAG systems. It handles:
+- **Document Chunking & Ingestion**: Splits text recursively, extracts semantic embeddings, and uploads vectors in batched operations.
+- **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.
+- **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.
+- **Drop-in UI Elements**: Exports polished, highly customisable React UI elements (`ChatWidget`, `ChatWindow`, `DocumentUpload`) built with Tailwind CSS v4.
 
 ---
 
-## 🚀 How it Works
-
-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**.
+## 2. Architecture & Implementation
+
+The SDK is built with modularity, performance, and security at its core:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor Client as Host Client (Next.js/React)
+    participant Facade as Retrivora Facade
+    participant Lic as LicenseVerifier
+    participant Pipe as Pipeline Engine
+    participant DB as Vector Database
+    participant LLM as LLM Provider
+
+    Client->>Facade: initialize(config)
+    activate Facade
+    Facade->>Lic: verify(licenseKey, projectId)
+    activate Lic
+    Note over Lic: Offline RS256 JWT Decryption
+    Lic-->>Facade: Valid Signature (Green)
+    deactivate Lic
+    Facade-->>Client: Ready
+    deactivate Facade
+
+    Client->>Facade: ask(question, history)
+    activate Facade
+    Facade->>Pipe: ask(question, history)
+    activate Pipe
+    Pipe->>DB: search(queryVector)
+    activate DB
+    DB-->>Pipe: relevant chunks & meta
+    deactivate DB
+    Pipe->>LLM: chatCompletion(context, prompt)
+    activate LLM
+    LLM-->>Pipe: generated response
+    deactivate LLM
+    Pipe-->>Facade: ChatResponse (reply + sources)
+    deactivate Pipe
+    Facade-->>Client: SSE Streaming Chunk / JSON
+    deactivate Facade
+```
 
-1.  **Ingest**: Upload or send documents to the `/api/upload` endpoint. They are parsed and chunked using **LlamaIndex** strategies if configured.
-2.  **Retrieve**: Queries are processed via the [QueryProcessor](file:///src/core/QueryProcessor.ts) to extract semantic hints and filter criteria.
-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.
+### Key Components:
+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()`.
+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.
+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.
+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.
 
-### 📦 Installation
+---
 
-Install the core package using npm:
+## 3. End-User Integration Guide
 
+### Step 1: Installation
+Install the SDK alongside its required peer dependencies:
 ```bash
 npm install @retrivora-ai/rag-engine
 ```
 
-#### 🎨 Auto-Injected Styles
-To render the built-in UI components (like `ChatWidget`, `ChatWindow`, `DocumentUpload`) correctly, stylesheet rules are **auto-injected directly into the document `<head>` on load**. No manual CSS imports are required in your application layout!
-
-*(Note: The raw stylesheet remains exported at `@retrivora-ai/rag-engine/style.css` if your custom bundler or setup requires manual stylesheet referencing).*
-
-#### 🔌 Peer & Optional Dependencies
-Depending on the specific database providers or features you use, you may need to install additional peer dependencies:
-* **PostgreSQL / PGVector**: `npm install pg @types/pg`
-* **MongoDB Atlas**: `npm install mongodb`
-* **Word/PDF parsing capabilities**: `npm install mammoth pdf-parse`
-* **Agentic/Semantic Chunking**: `npm install langchain llamaindex`
+### Step 2: Environment Configuration
+Create a `.env.local` file in your application root to supply your keys and provider selections:
+```bash
+# General Setup
+RAG_PROJECT_ID=my-rag-application
+RETRIVORA_LICENSE_KEY=ey... # Required for production deployment
+
+# Vector Database (MongoDB Atlas Example)
+VECTOR_DB_PROVIDER=mongodb
+MONGODB_URI=mongodb+srv://...
+MONGODB_DB=retrivora_db
+MONGODB_COLLECTION=vectors
+MONGODB_INDEX_NAME=vector_index
+
+# LLM Provider (Google Gemini Example)
+LLM_PROVIDER=gemini
+LLM_MODEL=gemini-2.5-flash
+GEMINI_API_KEY=AIzaSy...
+
+# Embedding Provider
+EMBEDDING_PROVIDER=gemini
+EMBEDDING_MODEL=text-embedding-004
+```
 
----
+### Step 3: Server-Side Ingestion
+Initialize the SDK instance on your server-side scripts or background workers to parse and index documents:
+```typescript
+import { Retrivora } from '@retrivora-ai/rag-engine/server';
 
-## 🛠️ Pluggable Architecture
+const retrivora = new Retrivora();
 
-Starting with v1.0.0, the engine uses a modular registry for all providers. Every provider now exposes:
-- **Static Validators**: `getValidator()` for deep configuration schema checks.
-- **Static Health Checkers**: `getHealthChecker()` for real-time connectivity and capability validation.
+async function runIngestion() {
+  // Validate configuration and verify the license key
+  await retrivora.initialize();
 
-This decoupling allows you to add custom providers without modifying the core engine logic.
+  const documents = [
+    {
+      docId: 'doc-001',
+      content: 'Retrivora supports Pinecone, MongoDB Vector, pgvector, and Qdrant out-of-the-box.',
+      metadata: { category: 'features', source: 'docs' }
+    }
+  ];
 
----
+  const results = await retrivora.ingest(documents, 'default-namespace');
+  console.log(`Successfully ingested ${results.length} documents.`);
+}
+```
 
-## NPM Package Usage
+### Step 4: Next.js API Routes (Server Proxy)
+Setup Next.js route handlers to stream conversational RAG answers to the frontend client securely:
 
-The package exports are split between **client-side** and **server-side** entry points to keep server secrets/native packages safe from your React browser bundle.
+**File**: `app/api/chat/route.ts`
+```typescript
+import { createStreamHandler } from '@retrivora-ai/rag-engine/server';
 
-| Import Path | Context | Exports |
-|---|---|---|
-| `@retrivora-ai/rag-engine` | **Client/Browser** | `ChatWidget`, `ChatWindow`, `ConfigProvider`, `useRagChat` |
-| `@retrivora-ai/rag-engine/server` | **Server Only** | `Retrivora` (SDK facade), `Pipeline`, `ConfigBuilder`, custom exceptions |
-| `@retrivora-ai/rag-engine/handlers` | **Server Only** | Next.js API Route Handler factories (e.g. `createRagHandler`, `createChatHandler`) |
-| `@retrivora-ai/rag-engine/style.css` | **Universal** | Required CSS styles for custom bundler setups (auto-injected by default) |
+// createStreamHandler automatically instantiates the Retrivora pipeline
+// and handles HTTP stream chunking (SSE) transparently.
+export const POST = createStreamHandler({
+  projectId: process.env.RAG_PROJECT_ID ?? 'default-project'
+});
+```
 
-### 1. Embed the ChatWidget
+### Step 5: Client-Side UI Components
+Import the Retrivora CSS styles and render the interactive widget in your layout or page:
 
-Drop the widget inside your application layout:
+**File**: `app/layout.tsx` (or `app/page.tsx`)
+```typescript
+'use client';
 
-```tsx
 import { ConfigProvider, ChatWidget } from '@retrivora-ai/rag-engine';
+import '@retrivora-ai/rag-engine/style.css'; // Load Tailwind styles
 
-export default function Layout({ children }) {
+export default function Home() {
   return (
-    <ConfigProvider
-      config={{
-        projectId: 'my-project',
-        ui: {
-          title: 'Support Bot',
-          primaryColor: '#6366f1',
-          accentColor: '#8b5cf6',
-          welcomeMessage: 'Hi! How can I help you today?',
-        },
-      }}
-    >
-      {children}
-      <ChatWidget position="bottom-right" />
+    <ConfigProvider apiEndpoint="/api/chat">
+      <main className="min-h-screen p-10 bg-slate-50">
+        <h1>My Corporate Knowledge Base</h1>
+        
+        {/* Drop-in float widget */}
+        <ChatWidget 
+          title="Retrivora Assistant" 
+          subtitle="Ready to search your documents"
+          visualStyle="glass" 
+        />
+      </main>
     </ConfigProvider>
   );
 }
 ```
 
-### 2. Mount Catch-All API Handler
-
-Create a single dynamic catch-all route file to handle chat streaming, document upload, and suggestions automatically:
-
-```ts
-// src/app/api/retrivora/[[...retrivora]]/route.ts
-import { createRagHandler } from '@retrivora-ai/rag-engine/handlers';
-
-// Handles GET /api/retrivora/health and POST /api/retrivora/chat, upload, suggestions
-export const { GET, POST } = createRagHandler();
-```
-
-### 3. Use Pipeline programmatically
-
-```ts
-import { Pipeline, getRagConfig } from '@retrivora-ai/rag-engine/server';
-
-const config = getRagConfig();
-const pipeline = new Pipeline(config);
-
-// Ingest documents
-await pipeline.ingest([{ docId: 'readme', content: 'Your document text here' }]);
-
-// Ask questions
-const { reply, sources } = await pipeline.ask('What is the refund policy?');
-```
-
-### 4. Use the Retrivora SDK facade
-
-```ts
-import { Retrivora } from '@retrivora-ai/rag-engine/server';
-
-const ai = new Retrivora({
-  llm: {
-    provider: 'openai',
-    model: 'gpt-5',
-  },
-  embedding: {
-    provider: 'openai',
-  },
-  vectorDatabase: {
-    provider: 'pinecone',
-  },
-  retrieval: {
-    strategy: 'hybrid',
-  },
-  workflow: {
-    type: 'agentic-rag',
-  },
-});
-
-const { reply, sources } = await ai.ask('What is the refund policy?');
-```
-
 ---
 
-## Configuration Reference
-
-The library is entirely dynamic. You can switch between providers simply by updating your environment variables.
+## 4. Licensing and Environments
 
-| Variable | Description |
-|---|---|
-| `RAG_PROJECT_ID` | Project namespace for data isolation |
-| `VECTOR_DB_PROVIDER` | `pinecone`, `pgvector`, `mongodb`, `milvus`, `qdrant`, `weaviate` |
-| `LLM_PROVIDER` | `openai`, `anthropic`, `gemini`, `ollama` |
-| `EMBEDDING_PROVIDER` | `openai`, `ollama`, `google-gemini` |
-| `RAG_ARCHITECTURE` | `simple`, `hybrid`, `graph`, `agentic` |
-
----
+The SDK enforces license key verification at runtime depending on the hosting environment:
 
-## License
-MIT
+| Host Environment | License Key Status | SDK Behavior |
+| :--- | :--- | :--- |
+| **Development** (`process.env.NODE_ENV !== 'production'`) | **Missing / Expired** | **Fail-Open**: Outputs a yellow warning message in the node console. Operations continue. |
+| **Production** (`process.env.NODE_ENV === 'production'`) | **Missing / Expired** | **Fail-Closed**: Throws `ConfigurationException` on `initialize()`. Ingestion/Chat routes are blocked. |
+| **Air-Gapped / Offline** | **Valid Signed JWT** | **Fail-Open on Telemetry**: Verifies signature cryptographically offline. Works with no internet connection. |

package/dist/{ILLMProvider-Bhk6zJOK.d.mts → ILLMProvider-DMxLyTdq.d.mts}

@@ -35,6 +35,12 @@ interface ChatOptions {
 interface UseRagChatOptions {
     /** Override the chat API endpoint (default: /api/chat) */
     apiUrl?: string;
+    /**
+     * Base URL for the Retrivora SDK catch-all route used for history, feedback,
+     * and sessions endpoints. Defaults to '/api/retrivora'.
+     * e.g. if your catch-all is at /api/retrivora/[[...retrivora]], set this to '/api/retrivora'.
+     */
+    retrivoraApiBase?: string;
     /** Override project namespace */
     namespace?: string;
     /** Persist chat history to localStorage (default: true) */
@@ -45,6 +51,8 @@ interface UseRagChatOptions {
     onError?: (error: string) => void;
     /** Optional custom headers to send with the chat request */
     headers?: Record<string, string>;
+    /** Session ID for history and feedback tracking (default: 'default') */
+    sessionId?: string;
 }
 interface UseRagChatReturn {
     /** All messages in the current conversation */
@@ -63,11 +71,17 @@ interface UseRagChatReturn {
     setMessages: React.Dispatch<React.SetStateAction<RagMessage[]>>;
     /** Abort the current active stream request */
     stop: () => void;
+    /** Load message history from database storage */
+    loadHistory: (sessionId: string) => Promise<void>;
+    /** Clear conversation history from database and locally */
+    clearHistory: (sessionId: string) => Promise<void>;
+    /** Submit rating and optional comment for a specific assistant message */
+    submitFeedback: (messageId: string, rating: 'thumbs_up' | 'thumbs_down', comment?: string) => Promise<void>;
 }
 
 declare const VECTOR_DB_PROVIDERS: readonly ["pinecone", "pgvector", "postgresql", "mongodb", "qdrant", "milvus", "chromadb", "redis", "weaviate", "rest", "universal_rest", "custom"];
-declare const LLM_PROVIDERS: readonly ["openai", "anthropic", "ollama", "gemini", "rest", "universal_rest", "custom"];
-declare const EMBEDDING_PROVIDERS: readonly ["openai", "ollama", "gemini", "rest", "universal_rest", "custom"];
+declare const LLM_PROVIDERS: readonly ["openai", "anthropic", "ollama", "gemini", "groq", "qwen", "rest", "universal_rest", "custom"];
+declare const EMBEDDING_PROVIDERS: readonly ["openai", "ollama", "gemini", "qwen", "rest", "universal_rest", "custom"];
 declare const GRAPH_DB_PROVIDERS: readonly ["neo4j", "memgraph", "simple", "custom"];
 
 /**
@@ -189,6 +203,18 @@ interface UIConfig {
     /** Whether to enable voice search input. Defaults to true. */
     enableVoiceInput?: boolean;
 }
+interface CAGConfig {
+    /** Enable Cold RAG (Cache Augmented Generation) */
+    enabled?: boolean;
+    /** Namespace containing the cold data (e.g., static manuals/guides) */
+    coldNamespace?: string;
+    /** Limit of cold documents to retrieve at initialization and keep in cache/context */
+    coldLimit?: number;
+    /** Specific search query to retrieve the cold documents (e.g., "manual", "documentation") */
+    coldQuery?: string;
+    /** Specific document IDs to load as cold context */
+    coldDocumentIds?: string[];
+}
 interface RAGConfig {
     /** Number of top-K chunks retrieved per query */
     topK?: number;
@@ -201,7 +227,7 @@ interface RAGConfig {
     /** Characters used to split text, in order of priority */
     separators?: string[];
     /** Overall RAG architecture pattern */
-    architecture?: 'simple' | 'graph' | 'hybrid' | 'agentic';
+    architecture?: 'simple' | 'graph' | 'hybrid' | 'agentic' | 'naive' | 'retrieve-and-rerank' | 'multimodal' | 'agentic-router' | 'multi-agent';
     /** Chunking strategy to use during ingestion */
     chunkingStrategy?: 'recursive' | 'markdown' | 'semantic' | 'llamaindex';
     /** Whether to use query transformation (e.g. HyDE) */
@@ -229,6 +255,18 @@ interface RAGConfig {
      * Defaults to built-in list (find, search, tell me about, etc.).
      */
     vectorKeywords?: string[];
+    /** Cold RAG (Cache Augmented Generation) configuration */
+    cag?: CAGConfig;
+    /** Chat history configuration */
+    history?: {
+        enabled?: boolean;
+        tableName?: string;
+    };
+    /** User feedback configuration */
+    feedback?: {
+        enabled?: boolean;
+        tableName?: string;
+    };
 }
 interface RetrievalConfig {
     /** Retrieval strategy selected by the host app. */
@@ -244,11 +282,21 @@ interface RetrievalConfig {
 }
 interface WorkflowConfig {
     /** High-level workflow selector from the SDK prompt. */
-    type?: 'simple-rag' | 'rag' | 'hybrid-rag' | 'graph-rag' | 'agentic-rag' | 'agentic';
+    type?: 'simple-rag' | 'rag' | 'hybrid-rag' | 'graph-rag' | 'agentic-rag' | 'agentic' | 'naive-rag' | 'retrieve-and-rerank' | 'multimodal-rag' | 'agentic-router' | 'multi-agent-rag' | 'multi-agent';
     /** Future workflow/provider-specific options. */
     options?: Record<string, unknown>;
 }
+interface MCPServerConfig {
+    name: string;
+    transport: 'stdio' | 'sse';
+    url?: string;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
 interface RagConfig {
+    /** License key for commercial production validation */
+    licenseKey?: string;
     /**
      * Unique identifier for the consuming project.
      * Used as the vector DB namespace to achieve multi-tenancy.
@@ -266,6 +314,13 @@ interface RagConfig {
     rag?: RAGConfig;
     /** Optional Graph database configuration */
     graphDb?: GraphDBConfig;
+    /** Optional Telemetry configuration for observability logging */
+    telemetry?: {
+        enabled?: boolean;
+        url?: string;
+    };
+    /** Optional Model Context Protocol (MCP) server configurations */
+    mcpServers?: MCPServerConfig[];
 }
 /**
  * Friendly SDK configuration accepted by the top-level Retrivora facade.

package/dist/{ILLMProvider-Bhk6zJOK.d.ts → ILLMProvider-DMxLyTdq.d.ts}

@@ -35,6 +35,12 @@ interface ChatOptions {
 interface UseRagChatOptions {
     /** Override the chat API endpoint (default: /api/chat) */
     apiUrl?: string;
+    /**
+     * Base URL for the Retrivora SDK catch-all route used for history, feedback,
+     * and sessions endpoints. Defaults to '/api/retrivora'.
+     * e.g. if your catch-all is at /api/retrivora/[[...retrivora]], set this to '/api/retrivora'.
+     */
+    retrivoraApiBase?: string;
     /** Override project namespace */
     namespace?: string;
     /** Persist chat history to localStorage (default: true) */
@@ -45,6 +51,8 @@ interface UseRagChatOptions {
     onError?: (error: string) => void;
     /** Optional custom headers to send with the chat request */
     headers?: Record<string, string>;
+    /** Session ID for history and feedback tracking (default: 'default') */
+    sessionId?: string;
 }
 interface UseRagChatReturn {
     /** All messages in the current conversation */
@@ -63,11 +71,17 @@ interface UseRagChatReturn {
     setMessages: React.Dispatch<React.SetStateAction<RagMessage[]>>;
     /** Abort the current active stream request */
     stop: () => void;
+    /** Load message history from database storage */
+    loadHistory: (sessionId: string) => Promise<void>;
+    /** Clear conversation history from database and locally */
+    clearHistory: (sessionId: string) => Promise<void>;
+    /** Submit rating and optional comment for a specific assistant message */
+    submitFeedback: (messageId: string, rating: 'thumbs_up' | 'thumbs_down', comment?: string) => Promise<void>;
 }
 
 declare const VECTOR_DB_PROVIDERS: readonly ["pinecone", "pgvector", "postgresql", "mongodb", "qdrant", "milvus", "chromadb", "redis", "weaviate", "rest", "universal_rest", "custom"];
-declare const LLM_PROVIDERS: readonly ["openai", "anthropic", "ollama", "gemini", "rest", "universal_rest", "custom"];
-declare const EMBEDDING_PROVIDERS: readonly ["openai", "ollama", "gemini", "rest", "universal_rest", "custom"];
+declare const LLM_PROVIDERS: readonly ["openai", "anthropic", "ollama", "gemini", "groq", "qwen", "rest", "universal_rest", "custom"];
+declare const EMBEDDING_PROVIDERS: readonly ["openai", "ollama", "gemini", "qwen", "rest", "universal_rest", "custom"];
 declare const GRAPH_DB_PROVIDERS: readonly ["neo4j", "memgraph", "simple", "custom"];
 
 /**
@@ -189,6 +203,18 @@ interface UIConfig {
     /** Whether to enable voice search input. Defaults to true. */
     enableVoiceInput?: boolean;
 }
+interface CAGConfig {
+    /** Enable Cold RAG (Cache Augmented Generation) */
+    enabled?: boolean;
+    /** Namespace containing the cold data (e.g., static manuals/guides) */
+    coldNamespace?: string;
+    /** Limit of cold documents to retrieve at initialization and keep in cache/context */
+    coldLimit?: number;
+    /** Specific search query to retrieve the cold documents (e.g., "manual", "documentation") */
+    coldQuery?: string;
+    /** Specific document IDs to load as cold context */
+    coldDocumentIds?: string[];
+}
 interface RAGConfig {
     /** Number of top-K chunks retrieved per query */
     topK?: number;
@@ -201,7 +227,7 @@ interface RAGConfig {
     /** Characters used to split text, in order of priority */
     separators?: string[];
     /** Overall RAG architecture pattern */
-    architecture?: 'simple' | 'graph' | 'hybrid' | 'agentic';
+    architecture?: 'simple' | 'graph' | 'hybrid' | 'agentic' | 'naive' | 'retrieve-and-rerank' | 'multimodal' | 'agentic-router' | 'multi-agent';
     /** Chunking strategy to use during ingestion */
     chunkingStrategy?: 'recursive' | 'markdown' | 'semantic' | 'llamaindex';
     /** Whether to use query transformation (e.g. HyDE) */
@@ -229,6 +255,18 @@ interface RAGConfig {
      * Defaults to built-in list (find, search, tell me about, etc.).
      */
     vectorKeywords?: string[];
+    /** Cold RAG (Cache Augmented Generation) configuration */
+    cag?: CAGConfig;
+    /** Chat history configuration */
+    history?: {
+        enabled?: boolean;
+        tableName?: string;
+    };
+    /** User feedback configuration */
+    feedback?: {
+        enabled?: boolean;
+        tableName?: string;
+    };
 }
 interface RetrievalConfig {
     /** Retrieval strategy selected by the host app. */
@@ -244,11 +282,21 @@ interface RetrievalConfig {
 }
 interface WorkflowConfig {
     /** High-level workflow selector from the SDK prompt. */
-    type?: 'simple-rag' | 'rag' | 'hybrid-rag' | 'graph-rag' | 'agentic-rag' | 'agentic';
+    type?: 'simple-rag' | 'rag' | 'hybrid-rag' | 'graph-rag' | 'agentic-rag' | 'agentic' | 'naive-rag' | 'retrieve-and-rerank' | 'multimodal-rag' | 'agentic-router' | 'multi-agent-rag' | 'multi-agent';
     /** Future workflow/provider-specific options. */
     options?: Record<string, unknown>;
 }
+interface MCPServerConfig {
+    name: string;
+    transport: 'stdio' | 'sse';
+    url?: string;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
 interface RagConfig {
+    /** License key for commercial production validation */
+    licenseKey?: string;
     /**
      * Unique identifier for the consuming project.
      * Used as the vector DB namespace to achieve multi-tenancy.
@@ -266,6 +314,13 @@ interface RagConfig {
     rag?: RAGConfig;
     /** Optional Graph database configuration */
     graphDb?: GraphDBConfig;
+    /** Optional Telemetry configuration for observability logging */
+    telemetry?: {
+        enabled?: boolean;
+        url?: string;
+    };
+    /** Optional Model Context Protocol (MCP) server configurations */
+    mcpServers?: MCPServerConfig[];
 }
 /**
  * Friendly SDK configuration accepted by the top-level Retrivora facade.

package/dist/handlers/index.d.mts

@@ -1,3 +1,3 @@
-import '../ILLMProvider-Bhk6zJOK.mjs';
-export { c as createChatHandler, d as createHealthHandler, e as createIngestHandler, f as createRagHandler, g as createStreamHandler, l as createSuggestionsHandler, h as createUploadHandler, s as sseErrorFrame, i as sseFrame, j as sseMetaFrame, m as sseObservabilityFrame, k as sseTextFrame, n as sseUIFrame } from '../index-C3SVtPYg.mjs';
 import 'next/server';
+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-DXd29KMq.mjs';
+import '../ILLMProvider-DMxLyTdq.mjs';

package/dist/handlers/index.d.ts

@@ -1,3 +1,3 @@
-import '../ILLMProvider-Bhk6zJOK.js';
-export { c as createChatHandler, d as createHealthHandler, e as createIngestHandler, f as createRagHandler, g as createStreamHandler, l as createSuggestionsHandler, h as createUploadHandler, s as sseErrorFrame, i as sseFrame, j as sseMetaFrame, m as sseObservabilityFrame, k as sseTextFrame, n as sseUIFrame } from '../index-Bu7T6xgr.js';
 import 'next/server';
+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-D_bOdJML.js';
+import '../ILLMProvider-DMxLyTdq.js';