dl4rce/flaiwheel

What's New

Cross-Encoder Reranker (optional)

• Rescores candidates with a cross-encoder model that reads (query, document) pairs together — solves vocabulary-mismatch queries (e.g. "auth bypass" now finds "client-side auth flag")
• 10-25% higher precision on mismatched queries, ~50ms latency per search
• Three models: ms-marco-MiniLM-L-6-v2 (90MB, fast), ms-marco-MiniLM-L-12-v2 (130MB), BAAI/bge-reranker-base (420MB, best accuracy)
• Off by default — zero overhead when disabled

Retrieval Pipeline Improvements

• BM25 relevance normalization — BM25-only hits now show proper 0-100% relevance instead of always 0%
• Configurable RRF — rrf_k, rrf_vector_weight, rrf_bm25_weight are now tunable (via Web UI or env vars)
• Minimum relevance threshold — drop low-quality results before they reach the agent (MCP_MIN_RELEVANCE)
• Wider retrieval window — fetches top_k×5 candidates when reranker is enabled; BM25 fetch widened from top_k×3 to top_k×5

Web UI

• New Search & Retrieval configuration card: reranker toggle + model picker, RRF weight sliders, min relevance input
• Reranker status indicator (ON/OFF) in Index Status panel

Documentation

• README: reranker section, search pipeline diagram, new config variables
• GitHub Pages landing site updated with search pipeline walkthrough

Tests

• 6 new tests for reranker config, BM25 normalization, RRF weights, min_relevance filtering
• 226 tests total, all passing

Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| MCP_RERANKER_ENABLED | false | Enable cross-encoder reranker |
| MCP_RERANKER_MODEL | cross-encoder/ms-marco-MiniLM-L-6-v2 | Reranker model |
| MCP_RRF_K | 60 | RRF k parameter |
| MCP_RRF_VECTOR_WEIGHT | 1.0 | Vector search weight |
| MCP_RRF_BM25_WEIGHT | 1.0 | BM25 weight |
| MCP_MIN_RELEVANCE | 0 | Minimum relevance % threshold |

Upgrade

curl -sSL https://raw.githubusercontent.com/dl4rce/flaiwheel/main/scripts/install.sh | bash