Metadata-Version: 2.4
Name: mongodb-hybridrag
Version: 0.4.0
Summary: MongoDB-native AI application starter with hybrid search, graphs, and live validation
Author-email: MongoDB <devrel@mongodb.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/romiluz13/Hybrid-Search-RAG
Project-URL: Documentation, https://github.com/romiluz13/Hybrid-Search-RAG#readme
Project-URL: Repository, https://github.com/romiluz13/Hybrid-Search-RAG
Project-URL: Issues, https://github.com/romiluz13/Hybrid-Search-RAG/issues
Keywords: rag,retrieval-augmented-generation,mongodb,atlas,vector-search,voyage-ai,knowledge-graph,llm,ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Database
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: certifi>=2024.2.2
Requires-Dist: numpy>=1.24.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: voyageai>=0.3.0
Requires-Dist: anthropic>=0.39.0
Requires-Dist: openai>=1.45.0
Requires-Dist: google-genai>=0.2.0
Requires-Dist: pymongo<5.0,>=4.7.0
Requires-Dist: motor<4.0,>=3.4.0
Requires-Dist: tiktoken>=0.8.0
Requires-Dist: tenacity>=9.0.0
Requires-Dist: aioboto3>=13.2.0
Requires-Dist: aiohttp>=3.11.9
Requires-Dist: httpx>=0.27.0
Requires-Dist: json_repair>=0.54.0
Provides-Extra: api
Requires-Dist: ascii_colors>=0.11.0; extra == "api"
Requires-Dist: fastapi>=0.109.0; extra == "api"
Requires-Dist: PyJWT>=2.8.0; extra == "api"
Requires-Dist: python-multipart>=0.0.18; extra == "api"
Requires-Dist: uvicorn>=0.27.0; extra == "api"
Provides-Extra: ui
Requires-Dist: chainlit>=1.0.0; extra == "ui"
Requires-Dist: pymupdf>=1.23.0; extra == "ui"
Provides-Extra: cli
Requires-Dist: rich>=13.0.0; extra == "cli"
Requires-Dist: typer>=0.9.0; extra == "cli"
Provides-Extra: ingestion
Requires-Dist: docling>=2.0.0; extra == "ingestion"
Requires-Dist: docling-core>=2.0.0; extra == "ingestion"
Requires-Dist: transformers>=4.30.0; extra == "ingestion"
Requires-Dist: tavily-python>=0.3.0; extra == "ingestion"
Provides-Extra: observability
Requires-Dist: langfuse>=2.0.0; extra == "observability"
Provides-Extra: evaluation
Requires-Dist: ragas>=0.2.0; extra == "evaluation"
Requires-Dist: datasets>=2.14.0; extra == "evaluation"
Requires-Dist: langchain-openai>=0.2.0; extra == "evaluation"
Provides-Extra: agent
Requires-Dist: langchain-core>=0.3.0; extra == "agent"
Requires-Dist: langchain-anthropic>=0.3.0; extra == "agent"
Requires-Dist: langgraph>=0.2.0; extra == "agent"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: isort>=5.13.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: ruff>=0.2.0; extra == "dev"
Provides-Extra: all
Requires-Dist: mongodb-hybridrag[agent,api,cli,dev,evaluation,ingestion,observability,ui]; extra == "all"
Dynamic: license-file

<div align="center">

```
██╗  ██╗██╗   ██╗██████╗ ██████╗ ██╗██████╗ ██████╗  █████╗  ██████╗
██║  ██║╚██╗ ██╔╝██╔══██╗██╔══██╗██║██╔══██╗██╔══██╗██╔══██╗██╔════╝
███████║ ╚████╔╝ ██████╔╝██████╔╝██║██║  ██║██████╔╝███████║██║  ███╗
██╔══██║  ╚██╔╝  ██╔══██╗██╔══██╗██║██║  ██║██╔══██╗██╔══██║██║   ██║
██║  ██║   ██║   ██████╔╝██║  ██║██║██████╔╝██║  ██║██║  ██║╚██████╔╝
╚═╝  ╚═╝   ╚═╝   ╚═════╝ ╚═╝  ╚═╝╚═╝╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝
```

# MongoDB-Native AI Starter

### **Backend-First • Latest MongoDB Search • Hybrid Search • Knowledge Graph**

**HybridRAG is a backend-first Python starter for MongoDB-native AI applications with real live validation on a blessed stack.**

[![License](https://img.shields.io/badge/License-Apache_2.0-green.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![MongoDB](https://img.shields.io/badge/MongoDB-Search-47A248.svg)](https://www.mongodb.com/atlas)
[![Voyage AI](https://img.shields.io/badge/Voyage_AI-Embeddings-purple.svg)](https://www.voyageai.com/)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)

[Features](#-features) • [MongoDB Search](#-latest-mongodb-search) • [Quick Start](#-quick-start) • [Documentation](#-documentation) • [Contributing](#-contributing)

</div>

---

## 🎯 The Problem

```
┌─────────────────────────────────────────────────────────────────────────┐
│  THE FRAGMENTED WAY                                                      │
│                                                                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐                 │
│  │ Pinecone │  │  Neo4j   │  │  Redis   │  │ Postgres │                 │
│  │ Vectors  │  │  Graph   │  │  Cache   │  │ Metadata │                 │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘                 │
│       │             │             │             │                        │
│       └─────────────┴─────────────┴─────────────┘                        │
│                         │                                                │
│                    SYNC HELL 😱                                          │
│         If one write fails, your RAG returns                             │
│         vectors for deleted text                                         │
└─────────────────────────────────────────────────────────────────────────┘

                              VS

┌─────────────────────────────────────────────────────────────────────────┐
│  THE HYBRIDRAG WAY                                                       │
│                                                                          │
│                    ┌─────────────────────┐                               │
│                    │   MongoDB Atlas     │                               │
│                    │  ┌───┐ ┌───┐ ┌───┐  │                               │
│                    │  │ V │ │ G │ │ K │  │                               │
│                    │  └───┘ └───┘ └───┘  │                               │
│                    │  Vector Graph  KV   │                               │
│                    └─────────────────────┘                               │
│                              │                                           │
│                    ONE DOCUMENT = ATOMIC ✅                              │
│              All or nothing. Never inconsistent.                         │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## ✨ Features

<table>
<tr>
<td width="50%">

### 🔄 Core Capabilities

| Feature | Description |
| --------- | ------------- |
| **Atomic Updates** | Vector + metadata + graph in one transaction |
| **$rankFusion** | Native weighted reciprocal-rank fusion |
| **$scoreFusion** | Score-based fusion with normalization |
| **Knowledge Graph** | Automatic entity & relationship extraction |
| **Self-Compacting Memory** | Conversations auto-summarize |

</td>
<td width="50%">

### 🚀 Latest MongoDB Search

| Feature | Description |
| --------- | ------------- |
| **Lexical Prefilters** | Fuzzy, phrase, wildcard BEFORE vectors |
| **Dynamic numCandidates** | Auto-tuned (top_k × 20) |
| **scoreDetails** | Per-pipeline score debugging |
| **Explicit Weights** | Configurable vector/text weights |
| **Fail-Fast Support** | Explicit capability errors on the blessed stack |

</td>
</tr>
</table>

### 🔌 Blessed Stack

```
┌─────────────────────────────────────────────────────────────────────────┐
│  DATABASE         │  EMBEDDINGS       │  LLM             │  SURFACE      │
│  ────────────     │  ─────────────    │  ────────────    │  ──           │
│  ✓ MongoDB Search │  ✓ Voyage AI      │  ✓ OpenAI API    │  ✓ Python API │
│  ✓ atlas-local    │  ✓ voyage-4-large │  ✓ Compatible    │  ✓ REST API   │
│  ✓ Atlas cloud    │  ✓ Reranking      │    endpoints     │  ✓ Rich CLI   │
└─────────────────────────────────────────────────────────────────────────┘
```

### One Supported Story

HybridRAG supports multiple integrations internally, but the public reference path is intentionally narrow:

- **MongoDB:** a deployment with Search and Vector Search capabilities
- **Embeddings/Rerank:** Voyage
- **LLM:** OpenAI API or an OpenAI-compatible endpoint
- **Product shape:** Python library + FastAPI + CLI

That is the stack exercised by the release gate. Unsupported capabilities on this path should fail explicitly rather than silently degrading.

---

## 🆕 Latest MongoDB Search

HybridRAG probes capabilities by executing them. It does not select behavior from a numeric server-version policy.

### Three Filter Systems

```python
from hybridrag import (
    # 1. Vector Search Filters (MQL - for $vectorSearch)
    VectorSearchFilterConfig,
    build_vector_search_filters,

    # 2. Atlas Search Filters (for $search compound queries)
    AtlasSearchFilterConfig,
    build_atlas_search_filters,

    # 3. Lexical Prefilters (NEW - for $search.vectorSearch)
    LexicalPrefilterConfig,
    build_lexical_prefilters,
    TextFilter, FuzzyFilter, PhraseFilter, WildcardFilter, GeoFilter,
)
```

### Low-level lexical prefilter builders

**The game-changer**: Apply Atlas Search operators (fuzzy, phrase, wildcard, geo) **BEFORE** vector search.

```python
from hybridrag import LexicalPrefilterConfig, HybridRAG

# Create a lexical prefilter config
filter_config = LexicalPrefilterConfig(
    # Fuzzy text matching (typo-tolerant)
    fuzzy_filters=[{"path": "content", "query": "machin lerning", "maxEdits": 2}],

    # Exact phrase matching
    phrase_filters=[{"path": "title", "query": "vector database"}],

    # Wildcard patterns
    wildcard_filters=[{"path": "tags", "query": "tech*"}],

    # Date range filtering
    range_filters={"timestamp": {"gte": "2024-01-01"}},

    # Geospatial (find docs near a location)
    geo_filters=[{"path": "location", "geometry": {"type": "Point", "coordinates": [-73.9, 40.7]}}],
)

# This is a low-level pipeline builder. HybridRAG.query() accepts the
# backend-neutral FilterConfig documented below, not lexical_filter_config.
```

### Why Lexical Prefilters Matter

| Scenario | Legacy $vectorSearch | New $search.vectorSearch |
| ---------- | --------------------- | -------------------------- |
| "Find docs about *machin lerning*" | ❌ No fuzzy support | ✅ `fuzzy: {maxEdits: 2}` |
| "Exact phrase 'machine learning'" | ❌ Vector similarity only | ✅ `phrase: {slop: 0}` |
| "Tags matching tech*" | ❌ No wildcards | ✅ `wildcard: {query: "tech*"}` |
| "Docs within 10km of NYC" | ❌ No geo filtering | ✅ `geoWithin` |
| "Combined filters" | ❌ MQL only ($eq, $gte) | ✅ Full Atlas Search syntax |

### $meta Score Fields Reference

```python
# $vectorSearch and $search use operator-specific $meta keywords.
# $rankFusion and $scoreFusion both expose the combined score via "score".
OPERATOR_SCORE_FIELDS = {
    "$vectorSearch":        "vectorSearchScore",   # legacy $vectorSearch stage
    "$search.vectorSearch": "searchScore",
    "$rankFusion":          "score",               # also "scoreDetails"
    "$scoreFusion":         "score",               # also "scoreDetails"
}
```

---

## 🔀 How Hybrid Search Works

```
  ┌─────────────────────────────────────────────────────────────────────┐
  │                    $scoreFusion (default native fusion)             │
  │                                                                      │
  │   ┌───────────────────────┐          ┌───────────────────────┐      │
  │   │    VECTOR PIPELINE    │          │    TEXT PIPELINE      │      │
  │   │  $search.vectorSearch │          │  $search.compound     │      │
  │   │                       │          │                       │      │
  │   │  ┌─────────────────┐  │          │  ┌─────────────────┐  │      │
  │   │  │ Lexical Prefilter│  │          │  │  Fuzzy Matching │  │      │
  │   │  │ (fuzzy/phrase/  │  │          │  │                 │  │      │
  │   │  │  wildcard/geo)  │  │          │  │                 │  │      │
  │   │  └────────┬────────┘  │          │  └────────┬────────┘  │      │
  │   │           ↓           │          │           ↓           │      │
  │   │  ┌─────────────────┐  │          │  ┌─────────────────┐  │      │
  │   │  │ Vector Similarity│  │          │  │  BM25 Scoring   │  │      │
  │   │  └────────┬────────┘  │          │  └────────┬────────┘  │      │
  │   └───────────┼───────────┘          └───────────┼───────────┘      │
  │               │                                  │                  │
  │               └──────────────┬───────────────────┘                  │
  │                              ↓                                      │
  │                  ┌───────────────────────┐                          │
  │                  │  Weighted Fusion      │                          │
  │                  │  vector: 0.6          │                          │
  │                  │  text:   0.4          │                          │
  │                  │  scoreDetails: true   │                          │
  │                  └───────────────────────┘                          │
  └─────────────────────────────────────────────────────────────────────┘

  ┌─────────────────────────────────────────────────────────────────────┐
  │              KNOWLEDGE GRAPH ($graphLookup)                          │
  │                                                                      │
  │   Entity Boosting: KG relationships enhance reranking scores         │
  │   Mix Mode: Combines vector + text + graph for comprehensive RAG     │
  └─────────────────────────────────────────────────────────────────────┘
```

---

## 🚀 Quick Start

### See MongoDB value in 60 seconds (no API keys, no signup)

**Prerequisites:** Python 3.11+ and Docker Desktop (running).

```bash
git clone https://github.com/romiluz13/Hybrid-Search-RAG.git
cd Hybrid-Search-RAG

# Create a virtual environment and install (one-time)
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[all]"            # or just run: make first-time-setup

make demo                         # starts local MongoDB + runs the showcase
```

`make demo` brings up a local MongoDB (`mongodb/mongodb-atlas-local:preview` via
Docker) and runs the **real** native hybrid-search pipeline against
seeded data — no Voyage key, no LLM key, no Atlas account. You see:

- `$vectorSearch` — semantic nearest neighbors (cosine)
- `$search` — lexical / BM25
- `$rankFusion` — native hybrid search merging vector + lexical via RRF
- `$graphLookup` — knowledge-graph traversal in one pipeline

> The demo uses sample vectors (labeled). In production, embeddings come from
> Voyage AI — that's the `make demo-full` path below.

### Full generative RAG (bring Voyage + LLM keys)

```bash
# 1. Configure API keys
cp .env.example .env              # MONGODB_URI defaults to local; add your keys
#    Required: VOYAGE_API_KEY (https://dash.voyageai.com/)
#    Required: one LLM key — set LLM_PROVIDER to match:
#              - anthropic (default) — ANTHROPIC_API_KEY
#              - openai              — OPENAI_API_KEY
#              - gemini              — GEMINI_API_KEY
#              - grove               — GROVE_API_KEY + GROVE_BASE_URL
#                (MongoDB internal OpenAI-compatible gateway; for SAs
#                 without an OpenAI/Anthropic key)

# 2. Run full RAG (ingests real Voyage embeddings + generates an answer)
make demo-full

# 3. Or start a server
make run-api        # FastAPI  → http://localhost:8000  (/health, /docs)
make run-ui         # Chainlit → http://localhost:8001
make run-cli        # interactive CLI
```

> **macOS + Atlas SSL note:** if you hit `SSL: CERTIFICATE_VERIFY_FAILED`
> against Atlas (common with python.org Python, which doesn't bundle CA
> certs), HybridRAG now automatically uses `certifi`'s CA bundle for
> `mongodb+srv://` connections. No action needed. For a corporate/custom CA,
> set `MONGODB_TLS_CA_FILE=/path/to/your-ca.pem`.

### Canonical Query Paths (Python SDK)

```python
# Simple answer
answer = await rag.query("How does hybrid search work?", mode="mix")

# Source-aware response
result = await rag.query_with_sources(
    "How does hybrid search work?",
    mode="mix",
    top_k=5,
)
print(result["answer"])
print(result["references"])

# Streaming response
stream = await rag.stream_query(
    "What should a production RAG boilerplate expose?",
    mode="mix",
    include_context=True,
    include_references=True,
)
async for chunk in stream["response_iterator"]:
    print(chunk, end="")
```

### Release Gate

The repo is considered publish-ready only when the blessed stack passes:

- fast PR checks
- API contract tests
- example smoke tests
- deterministic live seeded validation on `atlas-local:preview`
- no skipped release tests
- no silent fallback on the blessed path

### Basic Usage

```python
import asyncio
from hybridrag import FilterConfig, FilterPredicate, create_hybridrag

async def main():
    # Initialize
    rag = await create_hybridrag()

    # Ingest documents
    await rag.ingest_files("./documents/")

    # Simple query
    result = await rag.query_with_memory(
        query="What are the key findings?",
        mode="mix",  # Vector + Graph + Keyword
    )
    print(result["answer"])

    # Advanced: Query with one backend-neutral metadata filter
    filter_config = FilterConfig(
        predicates=[
            FilterPredicate(
                field="metadata.category",
                operator="eq",
                value="research",
            )
        ]
    )

    result = await rag.query(
        query="machine learning trends",
        mode="naive",
        filter_config=filter_config,
    )

asyncio.run(main())
```

### CLI

```bash
# Launch interactive CLI
hybridrag chat

# Or use Typer commands
hybridrag ingest ./documents/
hybridrag query "What is MongoDB Atlas?"
hybridrag status
hybridrag benchmark
```

---

## 📊 Query Modes

| Mode | Description | Use Case |
| ------ | ------------- | ---------- |
| `mix` | KG + vector/keyword fusion | **Recommended** - General queries |
| `hybrid` | Local + global KG retrieval | Entity facts plus overview |
| `local` | Entity-focused retrieval | Specific entities |
| `global` | Relationship-focused retrieval | High-level overview |
| `naive` | Vector + keyword fusion, no KG | Filtered document retrieval |
| `bypass` | No retrieval | Direct LLM queries |

---

## Supported capability surface

- Six query modes: `local`, `global`, `hybrid`, `mix`, `naive`, and `bypass`
- MongoDB score fusion by default, with rank fusion as an explicit option
- Native reranking with preserved fusion and rerank scores
- ANN and exact vector execution
- Backend-neutral metadata filters for `naive` retrieval
- Operator-authenticated query explanation and search-index readiness diagnostics
- Explicit all-index plan/apply/wait/rollback operations; startup does not mutate search indexes
- Optional MongoDB Automated Embedding for chunk retrieval
- Knowledge-graph entity/relationship extraction and visualization
- Conversation memory with compaction
- CLI, REST APIs, Chainlit UI, and an Ollama-compatible API
- RAGAS evaluation and Langfuse observability
- Namespace isolation, schema-validation migration, and cache maintenance tools
- Multiple production LLM providers plus engine-level bindings

Preview or beta maturity does not exclude a capability. Unsupported capabilities fail explicitly. Backup, monitoring, security, administration, and production index authorization remain deployment responsibilities.

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────────────────┐
│                              HybridRAG                                   │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────────────────┐ │
│  │   Voyage AI    │  │  Claude/GPT/   │  │      MongoDB Search        │ │
│  │   Embeddings   │  │    Gemini      │  │                            │ │
│  │   + Reranking  │  │                │  │  ┌──────────────────────┐  │ │
│  └────────────────┘  └────────────────┘  │  │ $rankFusion          │  │ │
│                                          │  │ $scoreFusion         │  │ │
│                                          │  │ $search.vectorSearch │  │ │
│                                          │  │ $graphLookup         │  │ │
│                                          │  └──────────────────────┘  │ │
│                                          └────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────────────────┐│
│  │                         FILTER SYSTEMS                              ││
│  │  Public FilterConfig → backend-specific MongoDB translators             ││
│  │  (Vector MQL)       │ (Atlas Search)       │ (Lexical prefilters)       ││
│  └─────────────────────────────────────────────────────────────────────┘│
├─────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────────────────┐│
│  │                         ENHANCEMENTS                                 ││
│  │  Entity Boosting │ Query Optimizer │ Self-Compacting Memory         ││
│  └─────────────────────────────────────────────────────────────────────┘│
├─────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────────────────┐│
│  │                        INTERFACES                                    ││
│  │        Chainlit UI  │  Typer CLI  │  REST API  │  Python SDK        ││
│  └─────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────┘
```

---

## 📚 Documentation

| Document | Description |
| ---------- | ------------- |
| **[Cookbook](docs/cookbook/)** | **8 production recipes** for building AI apps |
| [Installation Guide](docs/installation.md) | Setup and configuration |
| [Architecture Decisions](docs/adr/) | ADRs for key decisions |
| [Enhanced Search](docs/enhanced-search.md) | Graph traversal, mix mode |
| [Search Capability Guide](docs/capability-guide.md) | Filters, fusion, diagnostics, index safety |
| [Capability Catalog](docs/capabilities.md) | Supported, gated, monitored, and deployment-owned features |
| [Accepted Capability Roadmap](docs/specs/hybridrag-capability-roadmap.md) | Scope, contracts, and testing decisions |
| [Notebooks](notebooks/) | Interactive tutorials (5) |
| [Examples](examples/) | Code examples (8) |

### Cookbook Recipes

| Recipe | Topic | Description |
| -------- | ------- | ------------- |
| [01](docs/cookbook/01-hybrid-search.md) | Hybrid Search | MongoDB $scoreFusion and $rankFusion |
| [02](docs/cookbook/02-lexical-prefilters.md) | Lexical Prefilters | Fuzzy/phrase/wildcard/geo builders |
| [03](docs/cookbook/03-conversation-memory.md) | Conversation Memory | Multi-turn chat with self-compaction |
| [04](docs/cookbook/04-vector-search-optimization.md) | Vector Optimization | numCandidates, quantization, tuning |
| [05](docs/cookbook/05-knowledge-graph.md) | Knowledge Graph | $graphLookup for entity relationships |
| [06](docs/cookbook/06-filtering-strategies.md) | Filtering Strategies | Three filter systems explained |
| [07](docs/cookbook/07-agent-memory-patterns.md) | Agent Memory | Long-term, working, episodic memory |
| [08](docs/cookbook/08-production-deployment.md) | Production | Scaling, monitoring, security |

### Architecture Decision Records

- [ADR-001: MongoDB Single Database](docs/adr/0001-mongodb-single-database.md)
- [ADR-002: Voyage AI Embeddings](docs/adr/0002-voyage-ai-embeddings.md)
- [ADR-003: Hybrid Search RRF](docs/adr/0003-hybrid-search-rrf.md)
- [ADR-004: Prompts Module](docs/adr/0004-prompts-module-architecture.md)
- [ADR-005: Filter Builder Systems](docs/adr/0005-filter-builder-systems.md)
- [ADR-006: Lexical Prefilters](docs/adr/0006-lexical-prefilters.md)

---

## 🧪 Development

```bash
# Setup development environment
make first-time-setup

# Run tests
make test              # All tests
make test-quick        # Fast unit tests
make test-cov          # With coverage

# Code quality
make lint              # Ruff linting
make format            # Auto-format
make typecheck         # MyPy

# Full CI suite
make ci
```

---

## 📊 Why MongoDB Over Postgres?

| Task | Postgres + pgvector | HybridRAG + MongoDB |
| ------ | --------------------- | --------------------- |
| Add metadata field | `ALTER TABLE` + backfill + reindex | Just add it |
| Change embedding model | Rewrite entire table (MVCC bloat) | Bulk update, no rewrite |
| Hybrid search | Manual result merging in app code | Single `$rankFusion` pipeline |
| Lexical prefilters | Not supported | `$search.vectorSearch` native |
| Filter vectors by metadata | Separate index, query planner struggles | Compound index, native |
| Time to first query | Hours (extensions, schema, indexes) | 30 minutes (Atlas free tier) |

---

## 🤝 Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

```bash
# Development setup
git clone https://github.com/romiluz13/Hybrid-Search-RAG.git
cd Hybrid-Search-RAG
make first-time-setup

# Run tests before submitting
make ci
```

---

## 📜 License

Apache License 2.0 - see [LICENSE](LICENSE) for details.

---

```text
╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   MongoDB Native: $scoreFusion • $rankFusion • $rerank • Vector Search          ║
║                                                                           ║
║   Three Filter Systems: Vector (MQL) • Atlas • Lexical Prefilters         ║
║                                                                           ║
║   One MongoDB document. Atomic updates. Never inconsistent.               ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝
```

### Built with MongoDB Search • Voyage AI • Claude

[⬆ Back to Top](#mongodb-native-ai-starter)
