# Retrivora Free Tier (MVP) Architecture & Implementation Guide

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.

---

## 1. Overview & Core Philosophy

The Retrivora Free Tier is built around an intentionally small, highly cost-efficient scope:

- **Storage Isolation**: Single shared vector database index with multi-tenancy via **Pinecone Namespaces**.
- **Fixed Embedding Footprint**: Standardized on **768-dimension embeddings** (e.g. `nomic-embed-text` or `bge-base-en-v1.5`).
- **Vendor-Agnostic LLM Routing**: Unified LLM proxy layer via **LiteLLM** (exposing an OpenAI-compatible REST interface).
- **Simple Retrieval**: Standardized semantic RAG flow ($ \text{Search} \rightarrow \text{Top-K} \rightarrow \text{Rerank (optional)} \rightarrow \text{Prompt} \rightarrow \text{LLM} $).
- **Document Support**: Core business formats only (`PDF`, `DOCX`, `TXT`, `Markdown`).
- **Deterministic Limits**: Strict operational guardrails to prevent infrastructure cost overruns.

---

## 2. Component Specifications

### 2.1 Storage & Multi-Tenancy (Pinecone)

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**.

```
Pinecone Index: retrivora-free (768 dimensions, Cosine metric)
├── Namespace: john@example.com
├── Namespace: abc-company
└── Namespace: workspace-123
```

- **Index Name**: `retrivora-free`
- **Vector Dimension**: `768`
- **Isolation Scope**: One namespace per project / user / workspace (`projectId`).
- **Metadata Filtering**: Fully supported within each isolated namespace.

---

### 2.2 Embedding Model Strategy

To standardize vector dimension sizes across the shared index:

- **Dimensions**: `768`
- **Recommended Models**:
  - `nomic-embed-text` (Ollama or REST, using task prefixes `search_query: ` and `search_document: `).
  - `BAAI/bge-base-en-v1.5` (768-dimension sentence transformer).
  - `BAAI/bge-small-en-v1.5` (384-dimension fallback if required).

---

### 2.3 LLM Routing Layer (LiteLLM Abstraction)

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.

```
Retrivora SDK  ──►  LiteLLM Gateway (/v1)  ──►  OpenAI / Gemini / Claude / Groq / Ollama / OpenRouter
```

---

### 2.4 Retrieval Pipeline

The Free Tier enforces a simple, high-speed semantic search pipeline:

```
User Query ──► Embedding ──► Pinecone Top-K Search ──► (Optional Rerank) ──► Prompt Assembly ──► LLM Generation
```

* **Disabled Features on Free Tier**:
  - Graph retrieval (`useGraphRetrieval: false`)
  - Agentic routing & workflows
  - Hybrid BM25 / dense search

---

### 2.5 Document Ingestion & Parsing & Global Metadata Schema

Supported formats handled by `DocumentParser` & `FreeTierIngestor`:
- `.txt` (Text files)
- `.json` (Structured JSON documents)
- `.pdf` (PDF documents via `pdf-parse`)
- `.xlsx` / `.xls` (Excel spreadsheets via `xlsx` sheet-to-csv)
- `.docx` / `.doc` (Word documents via `mammoth`)
- `.md` (Markdown text)
- `.csv` (Comma-separated values)

#### Global Chunk Metadata Schema (`RetrivoraChunkMetadata`):
All vectors upserted into Pinecone namespaces conform to a standardized schema:
```typescript
interface RetrivoraChunkMetadata {
  docId: string;
  fileName: string;
  fileType: 'txt' | 'json' | 'pdf' | 'excel' | 'word' | 'md' | 'csv' | string;
  mimeType: string;
  chunkIndex: number;
  totalChunks: number;
  content: string;
  characterCount: number;
  workspaceId: string;
  pineconeNamespace: string;
  tier: 'free' | 'enterprise';
  ingestedAt: string;
  customMetadata?: Record<string, unknown>;
}
```

---

### 2.6 Chunking Configuration

- **Strategy**: `Recursive Character Splitter`
- **Target Chunk Size**: `500–800 tokens` ($\approx 2,000–3,200$ characters)
- **Chunk Overlap**: `100 tokens` ($\approx 400$ characters)
- **Separators**: `['\n# ', '\n## ', '\n### ', '\n\n', '\n', ' ', '']`

---

### 2.7 Operational Free Tier Limits

| Feature / Resource | Free Tier Limit |
| :--- | :--- |
| **Documents** | `20` max per workspace |
| **Storage Size** | `50 MB` total file limit |
| **Total Embeddings** | `10,000` vectors |
| **Queries / Day** | `100` queries |
| **Users / Workspaces** | `1` user, `1` namespace, `1` project |

---

## 3. Retrivora SDK Integration

### 3.1 Free Tier Configuration Code Example

Host applications can configure Retrivora using `ConfigBuilder`:

```typescript
import { ConfigBuilder, Retrivora } from '@retrivora-ai/rag-engine/server';

// 1. Construct Free Tier Configuration
const config = new ConfigBuilder()
  .projectId("workspace-123") // Mapped directly to Pinecone Namespace
  .vectorDb("pinecone", {
    indexName: "retrivora-free",
    apiKey: process.env.PINECONE_API_KEY,
  })
  .llm("universal_rest", "groq/qwen-3.6-27b", process.env.LITELLM_API_KEY, {
    baseUrl: process.env.LITELLM_BASE_URL || "http://localhost:4000/v1",
    profile: "litellm",
    temperature: 0.7,
    maxTokens: 1024,
  })
  .embedding("ollama", "nomic-embed-text", undefined, {
    baseUrl: process.env.OLLAMA_BASE_URL || "http://localhost:11434",
    dimensions: 768,
    queryPrefix: "search_query: ",
    documentPrefix: "search_document: ",
  })
  .rag({
    architecture: "simple",
    topK: 5,
    chunkSize: 2500,
    chunkOverlap: 400,
    chunkingStrategy: "recursive",
    useGraphRetrieval: false,
    useQueryTransformation: false,
  })
  .build();

// 2. Initialize Engine Instance
const retrivora = new Retrivora(config);
await retrivora.initialize();
```

---

### 3.2 Free Tier Preset Helper Function

```typescript
export const FREE_TIER_LIMITS = {
  maxDocuments: 20,
  maxStorageBytes: 50 * 1024 * 1024, // 50 MB
  maxEmbeddings: 10000,
  maxQueriesPerDay: 100,
  allowedFormats: ['.pdf', '.docx', '.txt', '.md'],
};

export function createFreeTierConfig(params: {
  workspaceId: string;
  pineconeApiKey: string;
  liteLlmApiKey?: string;
  liteLlmBaseUrl?: string;
}) {
  return new ConfigBuilder()
    .projectId(params.workspaceId)
    .vectorDb("pinecone", {
      indexName: "retrivora-free",
      apiKey: params.pineconeApiKey,
    })
    .llm("universal_rest", "gpt-4o-mini", params.liteLlmApiKey, {
      baseUrl: params.liteLlmBaseUrl || "http://localhost:4000/v1",
      profile: "litellm",
    })
    .embedding("ollama", "nomic-embed-text", undefined, {
      dimensions: 768,
    })
    .rag({
      architecture: "simple",
      topK: 5,
      chunkSize: 2500,
      chunkOverlap: 400,
      chunkingStrategy: "recursive",
      useGraphRetrieval: false,
    })
    .build();
}
```

---

## 4. Feature Comparison Matrix

| Feature | Free Tier (MVP) | Enterprise Tier |
| :--- | :--- | :--- |
| **Vector DB Index** | Shared (`retrivora-free`) | Dedicated index / cluster |
| **Tenancy Isolation** | Namespace | Index / Database / Cloud Project |
| **Embedding Model** | Fixed 768-dim (`nomic-embed-text`, `bge-base`) | Custom / Multimodal / Any dim |
| **LLM Gateway** | LiteLLM Proxy | Direct API / LiteLLM / Enterprise VPC |
| **Retrieval Mode** | Semantic Search (Top-K) | Hybrid + Graph RAG + Agentic Routing |
| **Document Formats** | PDF, DOCX, TXT, MD | All formats + Web scraping + Audio |
| **Document Limit** | 20 documents | Unlimited |
| **Storage Limit** | 50 MB | Custom / Unlimited |