# Retrivora RAG Engine SDK 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. --- ## 1. What is the Retrivora SDK? 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. --- ## 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 ``` ### 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. --- ## 3. End-User Integration Guide ### Step 1: Installation Install the SDK alongside its required peer dependencies: ```bash npm install @retrivora-ai/rag-engine ``` ### Step 2: Environment Configuration Create a `.env.local` file in your application root to supply your keys and provider selections: ```bash # General Setup NEXT_PUBLIC_PROJECT_ID=my-rag-application NEXT_PUBLIC_RETRIVORA_LICENSE_KEY=ey... # Required for client & server 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'; const retrivora = new Retrivora(); async function runIngestion() { // Validate configuration and verify the license key await retrivora.initialize(); 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.`); } ``` ### Step 4: Next.js API Routes (Server Proxy) Setup Next.js route handlers to stream conversational RAG answers to the frontend client securely: **File**: `app/api/chat/route.ts` ```typescript import { createStreamHandler } from '@retrivora-ai/rag-engine/server'; // 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' }); ``` ### Step 5: Client-Side UI Components Import the Retrivora CSS styles and render the interactive widget in your layout or page: **File**: `app/layout.tsx` (or `app/page.tsx`) ```typescript 'use client'; import { ConfigProvider, ChatWidget } from '@retrivora-ai/rag-engine'; import '@retrivora-ai/rag-engine/style.css'; // Load Tailwind styles export default function Home() { return (

My Corporate Knowledge Base

{/* Drop-in float widget */}
); } ``` --- ## 4. Licensing and Environments The SDK enforces license key verification at runtime depending on the hosting environment: | 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. | --- ## 5. Free Tier (MVP) Architecture 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. 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. --- ## 6. Next.js App Router Integration & Framework Lock-in (PKG-1) 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. 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: ```typescript import { createRetrivora } from '@retrivora-ai/rag-engine'; // Framework-agnostic controller example app.post('/api/chat', async (req, res) => { const sdk = await createRetrivora({ projectId: 'my-project', licenseKey: process.env.RETRIVORA_LICENSE_KEY, }); const answer = await sdk.query(req.body.message); res.json(answer); }); ```