# HybridRAG Architecture

## Overview

HybridRAG combines three search sources to provide comprehensive results:
- **Vector search** (Qdrant) - Semantic similarity via embeddings
- **Graph search** (Neo4j) - Entity relationships in knowledge graph
- **Web search** (SearXNG) - External web results via Trafilatura extraction

## Two-Stage RRF Fusion (v1.3.0+)

To ensure fair ranking between wiki and web results, we use a two-stage Reciprocal Rank Fusion:

```
Stage 1: Wiki Merge
  vector results ─┬─→ Mini-RRF ─→ Unified wiki ranking
  graph results  ─┘

Stage 2: Final RRF
  wiki (merged)  ─┬─→ Final RRF ─→ Combined results
  web results    ─┘
```

**Why two stages?**

Previously, wiki pages found by BOTH vector and graph received double RRF contribution, giving them an unfair 2x advantage over web results. The two-stage approach:
1. Merges vector+graph into a single "wiki" source
2. Wiki's internal ranking still benefits from multi-source confirmation
3. Wiki and web compete as equals in final ranking

## Configuration

| Setting | Default | Description |
|---------|---------|-------------|
| `VECTOR_SIMILARITY_THRESHOLD` | 0.7 | Minimum similarity score for vector results |
| `HYBRID_RAG_VECTOR_LIMIT` | 10 | Max vector results |
| `HYBRID_RAG_GRAPH_LIMIT` | 10 | Max graph results |
| `HYBRID_RAG_WEB_LIMIT` | 5 | Max web results |

## Known Limitations & Future Improvements

### Vector Search Noise

**Status:** Open for improvement if needed after observation period.

Vector search may return generic category/index pages (e.g., "Reference", "Projects", "Places") with high similarity scores (~0.86). These pages often have similar boilerplate content leading to uniform scores.

**Potential solutions if this becomes problematic:**
1. **Raise threshold** - Increase `VECTOR_SIMILARITY_THRESHOLD` to 0.85+
2. **Page-type filtering** - Exclude pages tagged as category/index/stub
3. **Content length signal** - Penalize pages with minimal content
4. **Duplicate score detection** - Flag results with suspiciously identical scores

The LLM re-ranking phase typically demotes these low-quality results, so this may not require immediate action.

### Graph Search

Graph search uses only core keywords (no LLM-generated synonyms) to avoid false matches like "author" → "author2000". This is intentional - vector search handles semantic similarity via embeddings.