pal-e-docs

Phase 6e: Hybrid Ranking (tsvector + vector)

phase-postgres-6e-hybrid-ranking Phase

Project
Goal: Unify keyword search (tsvector) and semantic search (pgvector) into a single endpoint with hybrid ranking, so agents get the best of both signals in one query.
Owner: Dev agent
Repo: forgejo_admin/pal-e-docs
Depends on: phase-postgres-6d-semantic-search (COMPLETED)

Scope

  • Add mode parameter to GET /notes/search endpoint — values: keyword (default, current behavior), semantic, hybrid
  • Implement hybrid ranking using Reciprocal Rank Fusion (RRF) — combines tsvector ts_rank and cosine similarity without needing score normalization
  • Configurable alpha parameter for weighting between keyword and semantic relevance (default: 0.5)
  • Results include score metadata so agents can assess relevance
  • Backward compatible — omitting mode or using mode=keyword returns identical results to current behavior
  • The /notes/semantic-search endpoint remains for now (deprecation is a separate decision)

Deliverables

  • (to be filled after completion)
  • phase-postgres-6-vector-search — parent phase
  • phase-postgres-6d-semantic-search — prerequisite (semantic search API)
  • phase-postgres-5-fulltext-search — prerequisite (tsvector infrastructure)
  • plan-2026-02-26-tf-modularize-postgres — parent plan