Phase 1c: Cross-Encoder Reranking

[brian-lai]

Summary

Implements cross-encoder reranking to improve search quality by 10-15% through two-stage retrieval.

Phase: Phase 1c - Cross-Encoder Reranking
Plan: context/plans/2026-02-03-phase1c-cross-encoder-reranking.md

Implementation

Core Components

1. Reranker Infrastructure (internal/reranker/)

   • Reranker interface with Rerank(query, candidates, topK) method
   • ScoredResult type for scored documents
   • Factory function NewReranker(provider string)
   • Error handling for unavailable rerankers

2. Qwen3-Reranker Integration (internal/reranker/qwen3.go)

   • Full implementation using Ollama /api/generate endpoint
   • Parallel batch scoring with goroutines
   • Document truncation to 500 chars for performance
   • Score parsing with fallback to 0.5
   • 5s timeout per candidate, 30s HTTP timeout

3. Hybrid Search Integration (internal/search/hybrid/hybrid.go)

   • Added Rerank and RerankTopK fields to Config
   • SetReranker() method for dependency injection
   • Reranking pipeline: retrieve → fuse → rerank → return top-K
   • Graceful fallback if reranking fails

Features

• ✅ Optional reranking (disabled by default)
• ✅ Parallel goroutine scoring for performance
• ✅ Graceful fallback on errors
• ✅ MCP tool support (hybrid_search_v2 with rerank parameter)
• ✅ Environment variable configuration
• ✅ YAML configuration support
• ✅ Comprehensive documentation

Testing

• ✅ Unit tests for score parsing (9 test cases)
• ✅ Unit tests for score clamping (7 test cases)
• ✅ Unit tests for result sorting (4 test cases)
• ✅ All tests passing

Documentation

• ✅ Comprehensive reranking guide (docs/reranking.md)
• ✅ Updated README.md with hybrid_search_v2 documentation
• ✅ Configuration examples (environment variables and YAML)
• ✅ Troubleshooting section
• ✅ Performance metrics and latency breakdown

Success Criteria

Criterion	Status	Notes
MRR improves by >10%	⏸️ Pending	Requires manual benchmarking with Ollama
Latency <200ms end-to-end	⏸️ Pending	Requires manual benchmarking
Reranking optional (flag-controlled)	✅ Complete	rerank parameter in MCP tool
Graceful fallback if unavailable	✅ Complete	Error handling with fallback to original results

Manual Validation Required

Before merging, please validate:

1. Install Qwen3-Reranker:

   ollama pull sam860/qwen3-reranker

2. Enable reranking:

   export CODETECT_RERANK_ENABLED=true
   export CODETECT_RERANK_MODEL=sam860/qwen3-reranker

3. Test with hybrid_search_v2:

   {
     "query": "authentication middleware",
     "limit": 20,
     "rerank": true
   }

4. Verify:

   • Reranking completes in <200ms
   • Results are reordered by relevance
   • MRR improves (compare against baseline)

Next Steps

After merging Phase 1c:

• Phase 1d: .codetectignore Support
• Phase 1e: HTTP API

References

• Master Plan: context/plans/2026-02-02-phase1-implementation-roadmap.md
• Phase 1c Plan: context/plans/2026-02-03-phase1c-cross-encoder-reranking.md
• Reranking Research: context/data/2026-02-03-cross-encoder-reranking-research.md