fix(rag): keep vector top-N on paraphrase queries, not just the single best

The semantic top-keep floor only ever rescued the one highest-similarity
candidate from the gate, so pure-paraphrase queries returned a single chunk
where naive vector retrieval would surface its whole top-N. On-device eval
(266 passages / 1433 queries / 6 languages) showed this as the hybrid
retriever's only regression vs the pure-vector baseline.

Retain the top SEMANTIC_TOP_KEEP_N (=5) candidates above the floor instead.
Measured effect: semantic recall +3, Arabic +7.5, with no regression on any
other query type or language.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: kfaracik

__tests__/hybridRetrieval.test.ts

@@ -266,6 +266,47 @@ describe('hybridRetrieve', () => {
     expect(result.map((c) => c.metadata?.name)).toContain('Everest');
   });
 
+  it('keeps several top-similarity semantic chunks above the floor, not just the single best', async () => {
+    mockKeywordSearch.mockResolvedValue([]);
+    const result = await hybridRetrieve({
+      prompt: 'how do mountains form',
+      enabledSourceIds: [1],
+      vectorStore: makeVectorStore(
+        [
+          {
+            id: '1:0',
+            document: 'first paraphrase-relevant passage',
+            embedding: [1, 0],
+            similarity: 0.33,
+            metadata: { documentId: 1, name: 'A' },
+          },
+          {
+            id: '2:0',
+            document: 'second paraphrase-relevant passage',
+            embedding: [0.9, 0.1],
+            similarity: 0.3,
+            metadata: { documentId: 2, name: 'B' },
+          },
+          {
+            id: '3:0',
+            document: 'third paraphrase-relevant passage',
+            embedding: [0.8, 0.2],
+            similarity: 0.28,
+            metadata: { documentId: 3, name: 'C' },
+          },
+        ],
+        {}
+      ),
+      sourceNamesById: new Map(),
+      embeddings: null,
+    });
+
+    const names = result.map((c) => c.metadata?.name);
+    expect(names).toContain('A');
+    expect(names).toContain('B');
+    expect(names).toContain('C');
+  });
+
   it('keeps a mid-similarity chunk when the query shares terms with it', async () => {
     mockKeywordSearch.mockResolvedValue([]);
     const result = await hybridRetrieve({

constants/retrieval.ts

@@ -32,9 +32,12 @@ export const ADAPTIVE_K_MIN_KEEP = 1;
 /** Cosine floor to qualify on semantics alone. Measured on-device: LFM2.5 true paraphrase matches land ~0.28–0.54, so 0.40 admits clear matches while most unrelated passages stay below. */
 export const STRONG_SEMANTIC_THRESHOLD = 0.4;
 
-/** The single highest-similarity candidate always qualifies above this floor, so the best semantic match is never fully gated out (empty result) on a paraphrase that clears neither the main threshold nor any keyword/coverage overlap. */
+/** The highest-similarity candidates always qualify above this floor, so paraphrase matches are never gated out when they clear neither the main threshold nor any keyword/coverage overlap. */
 export const SEMANTIC_TOP_KEEP_FLOOR = 0.25;
 
+/** How many of the top-similarity candidates the floor keeps. Retains the vector top-N on pure-paraphrase queries, matching what naive vector retrieval would surface. */
+export const SEMANTIC_TOP_KEEP_N = 5;
+
 /** Min cosine to qualify via lexical overlap (paired with non-zero term coverage). */
 export const LEXICAL_MATCH_MIN_SIMILARITY = 0.1;
 

utils/hybridRetrieval.ts

@@ -22,6 +22,7 @@ import {
   MAX_CHUNKS_PER_FILE,
   MAX_RELEVANT_CHUNKS,
   SEMANTIC_TOP_KEEP_FLOOR,
+  SEMANTIC_TOP_KEEP_N,
   STRONG_SEMANTIC_THRESHOLD,
   VECTOR_WEIGHT,
 } from '../constants/retrieval';
@@ -321,10 +322,12 @@ export const hybridRetrieve = async ({
   };
 
   const candidates = [...byId.values()];
-  const topSemantic = candidates.reduce<Candidate | null>(
-    (best, candidate) =>
-      candidate.similarity > (best?.similarity ?? -Infinity) ? candidate : best,
-    null
+  const topSemanticIds = new Set(
+    candidates
+      .filter((c) => c.similarity >= SEMANTIC_TOP_KEEP_FLOOR)
+      .sort((a, b) => b.similarity - a.similarity)
+      .slice(0, SEMANTIC_TOP_KEEP_N)
+      .map((c) => c.id)
   );
 
   const qualified = candidates.filter((candidate) => {
@@ -334,12 +337,7 @@ export const hybridRetrieve = async ({
       if (candidate.similarity >= LEXICAL_MATCH_MIN_SIMILARITY) return true;
     }
     if (candidate.similarity >= STRONG_SEMANTIC_THRESHOLD) return true;
-    if (
-      candidate === topSemantic &&
-      candidate.similarity >= SEMANTIC_TOP_KEEP_FLOOR
-    ) {
-      return true;
-    }
+    if (topSemanticIds.has(candidate.id)) return true;
     return (
       candidate.similarity >= LEXICAL_MATCH_MIN_SIMILARITY &&
       coverageOf(candidate) > 0