mongodb-hybridrag 0.3.0

State-of-the-art RAG system with MongoDB Atlas and Voyage AI

HybridRAG

State-of-the-art Retrieval-Augmented Generation (RAG) system powered by MongoDB Atlas and Voyage AI.

Features

• MongoDB Atlas Storage - Unified vector, graph, and key-value storage
• Voyage AI Embeddings - High-quality embeddings with voyage-3-large (1024 dimensions)
• Voyage AI Reranking - Precision reranking with rerank-2.5
• Multi-Provider LLM Support - Claude, GPT-4, and Gemini
• Knowledge Graph Construction - Automatic entity and relationship extraction
• Entity Boosting - Enhanced retrieval through entity-aware reranking
• Implicit Semantic Expansion - Find related concepts via vector similarity
• Conversation Memory - Multi-turn conversation support with MongoDB-backed sessions
• Hybrid Search - Combined vector and text search with MongoDB $rankFusion

Quick Start

Prerequisites

• Python 3.11+
• MongoDB Atlas cluster with Vector Search enabled
• Voyage AI API key
• LLM API key (Anthropic, OpenAI, or Google)

Installation

# Clone the repository
git clone https://github.com/romiluz13/Hybrid-Search-RAG.git
cd hybridrag

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

Configuration

Create a .env file with your credentials:

# MongoDB Atlas
MONGODB_URI=mongodb+srv://user:[e-mail]
MONGODB_DATABASE=hybridrag

# Voyage AI
VOYAGE_API_KEY=pa-xxxxxxxxxxxxx

# LLM Provider (choose one)
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx
# OPENAI_API_KEY=sk-xxxxxxxxxxxxx
# GEMINI_API_KEY=xxxxxxxxxxxxx

# Optional: Langfuse Observability
# LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxxxxxxx
# LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxxxxxxx

Basic Usage

import asyncio
from hybridrag import create_hybridrag, Settings

async def main():
    # Initialize HybridRAG
    settings = Settings(
        mongodb_database="my_database",
        llm_provider="anthropic",  # or "openai", "gemini"
    )
    rag = await create_hybridrag(settings)

    # Ingest documents
    await rag.ingest("path/to/document.pdf")

    # Query with conversation memory
    session_id = await rag.create_conversation_session()

    result = await rag.query_with_memory(
        query="What is this document about?",
        session_id=session_id,
        mode="mix",  # Combines knowledge graph and vector search
    )

    print(result["answer"])

asyncio.run(main())

Query Modes

Mode	Description	Best For
mix	Knowledge graph + vector search (recommended)	General queries
local	Entity-focused retrieval	Specific entity queries
global	Community summaries	High-level overview
hybrid	Local + global	Comprehensive answers
naive	Vector search only	Simple similarity search

API Server

Start the FastAPI server:

uvicorn src.hybridrag.api.main:app --reload

Endpoints

• POST /query - Query the RAG system
• POST /ingest - Ingest documents
• POST /sessions - Create conversation session
• GET /sessions/{id}/history - Get conversation history
• GET /health - Health check

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        HybridRAG                            │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   Voyage    │  │   Claude/   │  │    MongoDB Atlas    │  │
│  │  Embeddings │  │  GPT/Gemini │  │  (Vector + Graph)   │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────┐│
│  │                   Enhancements                          ││
│  │  • Entity Boosting  • Implicit Expansion  • Reranking   ││
│  └─────────────────────────────────────────────────────────┘│
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────┐│
│  │                 Conversation Memory                     ││
│  │           MongoDB-backed session storage                ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

Configuration Options

from hybridrag import Settings

settings = Settings(
    # MongoDB
    mongodb_database="hybridrag",

    # Embedding
    embedding_model="voyage-3-large",
    embedding_dimensions=1024,

    # Reranking
    rerank_model="rerank-2.5",
    rerank_top_k=10,

    # LLM
    llm_provider="anthropic",  # "openai", "gemini"
    llm_model="claude-sonnet-4-20250514",

    # Query defaults
    default_query_mode="mix",
    chunk_top_k=10,
    entity_top_k=60,
)

Development

# Run tests
pytest tests/ -v

# Type checking
mypy src/

# Format code
black src/ tests/
isort src/ tests/

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

Apache License 2.0 - see LICENSE for details.