claude-brain 0.15.2 → 0.17.0

package/src/retrieval/fusion/rrf.ts

@@ -1,163 +1,163 @@
-/**
- * Reciprocal Rank Fusion (RRF)
- * Combines multiple ranked lists into a single fused ranking
- *
- * RRF formula: score(d) = sum(1 / (k + rank(d)))
- * where k is a constant (default 60) and rank starts at 1
- */
-
-import type { HybridSearchResult } from '../types'
-
-export interface RRFConfig {
-  /** RRF k parameter (default 60) */
-  k: number
-}
-
-const DEFAULT_K = 60
-
-/**
- * Calculate RRF score for a document across multiple ranked lists
- *
- * @param ranks - Array of ranks (1-indexed) across different lists. Use 0 or undefined if not present.
- * @param k - RRF k parameter
- * @returns Combined RRF score
- */
-export function calculateRRFScore(ranks: (number | undefined)[], k: number = DEFAULT_K): number {
-  return ranks.reduce((score, rank) => {
-    if (rank === undefined || rank === 0) return score
-    return score + (1 / (k + rank))
-  }, 0)
-}
-
-/**
- * Fuse dense and sparse search results using RRF
- */
-export function fuseWithRRF(
-  denseResults: HybridSearchResult[],
-  sparseResults: HybridSearchResult[],
-  config: RRFConfig = { k: DEFAULT_K }
-): HybridSearchResult[] {
-  const { k } = config
-
-  // Create map of id -> result with ranks from each list
-  const fusedMap = new Map<string, {
-    result: HybridSearchResult
-    denseRank: number | undefined
-    sparseRank: number | undefined
-  }>()
-
-  // Add dense results with their ranks
-  denseResults.forEach((result, index) => {
-    fusedMap.set(result.id, {
-      result: { ...result, provenance: 'dense' as const },
-      denseRank: index + 1, // 1-indexed
-      sparseRank: undefined
-    })
-  })
-
-  // Add sparse results, merging with existing if present
-  sparseResults.forEach((result, index) => {
-    const existing = fusedMap.get(result.id)
-    if (existing) {
-      // Document appears in both lists
-      existing.sparseRank = index + 1
-      existing.result.provenance = 'both'
-      // Update sparse score
-      existing.result.scores.sparse = result.scores.sparse
-    } else {
-      // Document only in sparse results
-      fusedMap.set(result.id, {
-        result: { ...result, provenance: 'sparse' as const },
-        denseRank: undefined,
-        sparseRank: index + 1
-      })
-    }
-  })
-
-  // Calculate RRF scores and update results
-  const fusedResults: HybridSearchResult[] = []
-  fusedMap.forEach(({ result, denseRank, sparseRank }) => {
-    const rrfScore = calculateRRFScore([denseRank, sparseRank], k)
-
-    fusedResults.push({
-      ...result,
-      scores: {
-        ...result.scores,
-        fusion: rrfScore,
-        final: rrfScore // Fusion score becomes final (unless reranked later)
-      }
-    })
-  })
-
-  // Sort by RRF score descending
-  fusedResults.sort((a, b) => b.scores.fusion - a.scores.fusion)
-
-  return fusedResults
-}
-
-/**
- * Fuse multiple ranked lists using RRF
- * More general version that handles N lists
- */
-export function fuseMultipleWithRRF(
-  rankedLists: HybridSearchResult[][],
-  config: RRFConfig = { k: DEFAULT_K }
-): HybridSearchResult[] {
-  const { k } = config
-
-  // Track ranks for each document
-  const docRanks = new Map<string, {
-    result: HybridSearchResult
-    ranks: number[]
-  }>()
-
-  // Process each ranked list
-  rankedLists.forEach((list, listIndex) => {
-    list.forEach((result, rank) => {
-      const existing = docRanks.get(result.id)
-      if (existing) {
-        // Add rank for this list
-        existing.ranks[listIndex] = rank + 1
-        // Merge scores (keep highest)
-        existing.result.scores.dense = Math.max(
-          existing.result.scores.dense || 0,
-          result.scores.dense || 0
-        )
-        existing.result.scores.sparse = Math.max(
-          existing.result.scores.sparse || 0,
-          result.scores.sparse || 0
-        )
-        // Update provenance if appears in multiple lists
-        if (existing.result.provenance !== 'both') {
-          existing.result.provenance = 'both'
-        }
-      } else {
-        const ranks = new Array(rankedLists.length).fill(undefined)
-        ranks[listIndex] = rank + 1
-        docRanks.set(result.id, {
-          result: { ...result },
-          ranks
-        })
-      }
-    })
-  })
-
-  // Calculate RRF scores
-  const fusedResults: HybridSearchResult[] = []
-  docRanks.forEach(({ result, ranks }) => {
-    const rrfScore = calculateRRFScore(ranks, k)
-    fusedResults.push({
-      ...result,
-      scores: {
-        ...result.scores,
-        fusion: rrfScore,
-        final: rrfScore
-      }
-    })
-  })
-
-  // Sort by score descending
-  fusedResults.sort((a, b) => b.scores.fusion - a.scores.fusion)
-
-  return fusedResults
-}
+/**
+ * Reciprocal Rank Fusion (RRF)
+ * Combines multiple ranked lists into a single fused ranking
+ *
+ * RRF formula: score(d) = sum(1 / (k + rank(d)))
+ * where k is a constant (default 60) and rank starts at 1
+ */
+
+import type { HybridSearchResult } from '../types'
+
+export interface RRFConfig {
+  /** RRF k parameter (default 60) */
+  k: number
+}
+
+const DEFAULT_K = 60
+
+/**
+ * Calculate RRF score for a document across multiple ranked lists
+ *
+ * @param ranks - Array of ranks (1-indexed) across different lists. Use 0 or undefined if not present.
+ * @param k - RRF k parameter
+ * @returns Combined RRF score
+ */
+export function calculateRRFScore(ranks: (number | undefined)[], k: number = DEFAULT_K): number {
+  return ranks.reduce((score, rank) => {
+    if (rank === undefined || rank === 0) return score
+    return score + (1 / (k + rank))
+  }, 0)
+}
+
+/**
+ * Fuse dense and sparse search results using RRF
+ */
+export function fuseWithRRF(
+  denseResults: HybridSearchResult[],
+  sparseResults: HybridSearchResult[],
+  config: RRFConfig = { k: DEFAULT_K }
+): HybridSearchResult[] {
+  const { k } = config
+
+  // Create map of id -> result with ranks from each list
+  const fusedMap = new Map<string, {
+    result: HybridSearchResult
+    denseRank: number | undefined
+    sparseRank: number | undefined
+  }>()
+
+  // Add dense results with their ranks
+  denseResults.forEach((result, index) => {
+    fusedMap.set(result.id, {
+      result: { ...result, provenance: 'dense' as const },
+      denseRank: index + 1, // 1-indexed
+      sparseRank: undefined
+    })
+  })
+
+  // Add sparse results, merging with existing if present
+  sparseResults.forEach((result, index) => {
+    const existing = fusedMap.get(result.id)
+    if (existing) {
+      // Document appears in both lists
+      existing.sparseRank = index + 1
+      existing.result.provenance = 'both'
+      // Update sparse score
+      existing.result.scores.sparse = result.scores.sparse
+    } else {
+      // Document only in sparse results
+      fusedMap.set(result.id, {
+        result: { ...result, provenance: 'sparse' as const },
+        denseRank: undefined,
+        sparseRank: index + 1
+      })
+    }
+  })
+
+  // Calculate RRF scores and update results
+  const fusedResults: HybridSearchResult[] = []
+  fusedMap.forEach(({ result, denseRank, sparseRank }) => {
+    const rrfScore = calculateRRFScore([denseRank, sparseRank], k)
+
+    fusedResults.push({
+      ...result,
+      scores: {
+        ...result.scores,
+        fusion: rrfScore,
+        final: rrfScore // Fusion score becomes final (unless reranked later)
+      }
+    })
+  })
+
+  // Sort by RRF score descending
+  fusedResults.sort((a, b) => b.scores.fusion - a.scores.fusion)
+
+  return fusedResults
+}
+
+/**
+ * Fuse multiple ranked lists using RRF
+ * More general version that handles N lists
+ */
+export function fuseMultipleWithRRF(
+  rankedLists: HybridSearchResult[][],
+  config: RRFConfig = { k: DEFAULT_K }
+): HybridSearchResult[] {
+  const { k } = config
+
+  // Track ranks for each document
+  const docRanks = new Map<string, {
+    result: HybridSearchResult
+    ranks: number[]
+  }>()
+
+  // Process each ranked list
+  rankedLists.forEach((list, listIndex) => {
+    list.forEach((result, rank) => {
+      const existing = docRanks.get(result.id)
+      if (existing) {
+        // Add rank for this list
+        existing.ranks[listIndex] = rank + 1
+        // Merge scores (keep highest)
+        existing.result.scores.dense = Math.max(
+          existing.result.scores.dense || 0,
+          result.scores.dense || 0
+        )
+        existing.result.scores.sparse = Math.max(
+          existing.result.scores.sparse || 0,
+          result.scores.sparse || 0
+        )
+        // Update provenance if appears in multiple lists
+        if (existing.result.provenance !== 'both') {
+          existing.result.provenance = 'both'
+        }
+      } else {
+        const ranks = new Array(rankedLists.length).fill(undefined)
+        ranks[listIndex] = rank + 1
+        docRanks.set(result.id, {
+          result: { ...result },
+          ranks
+        })
+      }
+    })
+  })
+
+  // Calculate RRF scores
+  const fusedResults: HybridSearchResult[] = []
+  docRanks.forEach(({ result, ranks }) => {
+    const rrfScore = calculateRRFScore(ranks, k)
+    fusedResults.push({
+      ...result,
+      scores: {
+        ...result.scores,
+        fusion: rrfScore,
+        final: rrfScore
+      }
+    })
+  })
+
+  // Sort by score descending
+  fusedResults.sort((a, b) => b.scores.fusion - a.scores.fusion)
+
+  return fusedResults
+}

package/src/retrieval/index.ts

@@ -1,12 +1,12 @@
-/**
- * Retrieval Module Exports
- * Hybrid retrieval system with BM25 + Dense search + Reranking
- */
-
-export * from './types'
-export { RetrievalPipeline } from './pipeline'
-export { FeedbackStore, FeedbackMetrics, AdaptiveLearner } from './feedback'
-export { BM25Engine } from './bm25'
-export { RRFFusion, LinearFusion, MaxFusion } from './fusion'
-export { Reranker } from './reranker'
-export { IntentClassifier, QueryExpander, TemporalParser } from './query'
+/**
+ * Retrieval Module Exports
+ * Hybrid retrieval system with BM25 + Dense search + Reranking
+ */
+
+export * from './types'
+export { RetrievalPipeline } from './pipeline'
+export { FeedbackStore, FeedbackMetrics, AdaptiveLearner } from './feedback'
+export { BM25Engine } from './bm25'
+export { RRFFusion, LinearFusion, MaxFusion } from './fusion'
+export { Reranker } from './reranker'
+export { IntentClassifier, QueryExpander, TemporalParser } from './query'