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:

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:

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:

# 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:

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

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)

'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 (
    <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>
  );
}

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 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:

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);
});