Features Overview¶

Beyond Retrieval v2 is a production-grade Retrieval-Augmented Generation (RAG) platform for enterprise document intelligence. It combines multi-format document ingestion, 10 retrieval strategies, AI-powered chat with citations, and continuous quality evaluation -- all within isolated, shareable notebook workspaces.

Unlike point solutions that handle one piece of the RAG pipeline, Beyond Retrieval v2 delivers the entire stack: parsing, chunking, embedding, retrieval, generation, caching, quality scoring, and collaboration -- ready to deploy on-premises or in the cloud.

Architecture¶

graph LR
    subgraph Clients
        Browser["Browser / API Client"]
    end

    subgraph "FastAPI Backend"
        API["REST API<br/>78+ endpoints"]
        Ingestion["Ingestion Pipeline"]
        RAG["RAG Engine"]
        Judge["LLM Judge"]
        Enhance["AI Enhancer"]
    end

    subgraph "Database Layer"
        Supabase["Supabase PostgreSQL 15<br/>pgvector + pg_trgm"]
        VectorStore["HNSW Vector Index"]
    end

    subgraph "Storage"
        SupaStorage["Supabase Storage"]
        S3["S3-Compatible"]
        LocalFS["Local Filesystem"]
    end

    subgraph "LLM Providers"
        OpenRouter["OpenRouter<br/>21+ embedding models<br/>23+ LLM models"]
        OpenAI["OpenAI Direct"]
        Ollama["Ollama (Local)"]
    end

    subgraph "Document Parsers"
        Docling["Docling Parser"]
        Mistral["Mistral OCR"]
    end

    Browser -->|"HTTPS / JSON"| API
    API --> Ingestion
    API --> RAG
    API --> Judge
    API --> Enhance
    Ingestion --> Docling
    Ingestion --> Mistral
    RAG --> OpenRouter
    RAG --> OpenAI
    RAG --> Ollama
    Ingestion --> SupaStorage
    Ingestion --> S3
    Ingestion --> LocalFS
    RAG --> Supabase
    Supabase --- VectorStore
    Ingestion --> Supabase

Feature Walkthrough¶

Notebook System¶

Notebooks are isolated workspaces that partition documents, conversations, settings, and vector embeddings. Each notebook operates independently, allowing teams to maintain separate knowledge bases for different projects, departments, or use cases.

Document Management¶

Upload, parse, chunk, and embed documents through a multi-stage background pipeline. The system handles 8 file formats with configurable parsing and chunking strategies.

Supported file types: PDF, DOCX, DOC, MD, TXT, CSV, XLSX, XLS

Two parsers for different needs:

Additional capabilities:

• Re-ingestion -- Atomic cleanup of old data + re-pipeline with new settings
• Batch re-ingestion -- Process multiple files independently in one request
• OneDrive/SharePoint import -- Browse folders and import files via OAuth2

RAG Chat¶

The core RAG pipeline combines retrieval, generation, and quality evaluation into a single endpoint. Every response includes numbered citations, source metadata, and suggested follow-up questions.

Pipeline steps:

1. Cache check (exact MD5 + semantic cosine)
2. Query expansion (strategy-dependent)
3. Hybrid retrieval (FTS + semantic + RRF)
4. Chunk deduplication and ghost citation removal
5. LLM generation with system prompt + persona + language
6. Grounding score computation
7. Background LLM Judge evaluation

10 retrieval strategies:

6 personas:

10 languages: English, German, Spanish, French, Italian, Portuguese, Dutch, Russian, Chinese, Japanese

Language modes:

• Auto-detect -- Mirrors the language of the user's question
• Manual -- Always responds in the configured language

Cache-first pipeline:

The system checks for cached responses before running full retrieval:

1. Exact match -- MD5 hash of the query
2. Semantic match -- Cosine similarity >= 0.97 threshold
3. Cache adaptation -- Lightweight LLM call adjusts cached responses for different language/persona combinations while preserving citations

Cache settings: cache_enabled, cache_similarity_threshold (default 0.97), cache_max_age_days (default 7).

LLM Judge:

After every RAG response, a background task evaluates answer quality:

• Scores responses on accuracy, groundedness, and answerability
• Responses scoring >= 80 with grounded=true are cached for future queries
• Results logged to response_quality_log table
• Configurable via judge_enabled kill switch

AI Enhancement¶

The enhancement pipeline enriches document chunks with AI-generated contextual descriptions, improving retrieval accuracy for ambiguous or context-dependent queries.

Lifecycle:

pending --> processing --> success --> embedded (publish)
              |
              v
           failed -----> pending (reset)

Enhanced chunks use the format:

# Context
{AI-generated contextual description}

---

# Content
{Original chunk text}

Health Monitor¶

Automated data quality scoring with duplicate detection and cleanup tools.

Health score formula:

score = 100
      - (duplicates / total) * 40
      - (orphans / total) * 30
      + (enhanced / total) * 10

The score is capped between 0 and 100.

Cleanup tools:

• Remove duplicates -- Keeps the oldest chunk in each duplicate group
• Remove orphans -- Deletes embeddings without parent records

Multi-Provider LLM¶

Beyond Retrieval supports three LLM providers with per-notebook configuration and dynamic API key resolution.

Key resolution chain: User-saved DB key > Server .env key > empty string

Each notebook independently configures its provider, model, and temperature. Switching providers auto-adjusts model ID prefixes (e.g., openai/gpt-4o-mini for OpenRouter vs gpt-4o-mini for OpenAI Direct).

Dynamic API Keys¶

Users can save their own API keys through the Global Settings UI. These keys take priority over server-configured keys and flow through the entire pipeline.

Where user keys are used:

• Chat (LLM inference)
• Retrieval (embedding queries)
• Cache check (embedding for semantic lookup)
• LLM Judge (quality evaluation)
• AI Enhancement (chunk enrichment)

Key management endpoints:

• GET /api/settings/api-keys -- List key status with masked preview
• PUT /api/settings/api-keys -- Save or update keys
• DELETE /api/settings/api-keys/{key_name} -- Remove key (falls back to server config)
• POST /api/settings/api-keys/test -- Validate key against provider

Notebook Sharing¶

Admins can generate invite links to grant other users access to specific notebooks.

OneDrive Integration¶

Import files directly from SharePoint/OneDrive without manual download-upload cycles.

• OAuth2 flow -- Direct authorization via httpx (no MSAL dependency)
• Folder browsing -- Navigate SharePoint folder structure via Graph API
• File import -- Download from OneDrive, upload to configured storage, trigger ingestion
• Token management -- Fernet-encrypted tokens stored in the database

Authentication¶

Beyond Retrieval uses Supabase GoTrue for authentication with a bypass mode for local development.

Authorization levels:

Comparison with Alternatives¶

Use Cases¶

Enterprise Knowledge Base¶

Centralize company policies, product documentation, and internal procedures. Employees ask questions in their preferred language and receive cited answers with source references.

Customer Support¶

Build a support knowledge base from help articles, FAQs, and product manuals. Support agents get instant answers with citations instead of searching through documents manually.

Legal Document Analysis¶

Upload contracts, regulations, and case law. Lawyers can query across thousands of pages and get grounded answers with precise citations pointing to relevant clauses.

Research Assistant¶

Aggregate academic papers, reports, and data sheets. Researchers query across their corpus with different retrieval strategies to find relevant passages.

Internal Wiki Replacement¶

Replace static wikis with a queryable knowledge base that understands context. Unlike keyword search, the RAG pipeline handles paraphrased questions, synonyms, and cross-document reasoning.

Getting Started¶

Ready to deploy? Follow the Quick Start guide to get Beyond Retrieval running in under 10 minutes with Docker Compose.

For API integration, see the API Overview and End-to-End Workflows.