@saulwade/swl-ses 1.4.1 → 1.5.0

package/scripts/lib/rrf-fusion.js

@@ -1,175 +1,175 @@
-'use strict';
-
-/**
- * rrf-fusion.js — Reciprocal Rank Fusion para combinar streams de búsqueda.
- *
- * Patrón adoptado de `temp/agentmemory-main/src/state/hybrid-search.ts`. El
- * algoritmo RRF combina rankings de múltiples sistemas de retrieval (BM25,
- * vector, graph) sin requerir que sus scores sean comparables — solo importa
- * la posición relativa (rank) en cada lista.
- *
- * Fórmula:
- *
- *     RRF(d) = Σ_i  w_i / (k + rank_i(d))
- *
- *   donde:
- *     d         = un documento candidato
- *     i         = índice del stream (BM25, vector, graph, ...)
- *     w_i       = peso del stream i (default 1.0 si no se especifica)
- *     rank_i(d) = posición 1-indexed de d en el stream i, o ∞ si no aparece
- *     k         = constante de smoothing (default 60, estándar Cormack 2009)
- *
- * Propiedades:
- *   - Robust frente a magnitudes de score heterogéneas — solo usa rank.
- *   - Documentos que aparecen en múltiples streams reciben boost natural.
- *   - Documentos que aparecen solo una vez no son penalizados — su rank ∞ en
- *     otros streams contribuye 0.
- *   - k ≈ 60 minimiza el peso de ranks bajos (< 60 efectivos).
- *
- * Versus suma simple de scores:
- *   - No requiere normalización entre streams (BM25 vs vector cosine son
- *     incomparables).
- *   - Más resistente a outliers (un score muy alto en un stream no domina).
- *
- * Sin dependencias — Node stdlib only. Backward compatible: el caller puede
- * mantener su lógica anterior y usar RRF solo cuando combine ≥2 streams.
- *
- * @module scripts/lib/rrf-fusion
- */
-
-// ── constantes ────────────────────────────────────────────────────────────────
-
-/** Constante k del RRF estándar (Cormack et al., 2009). */
-const RRF_K_DEFAULT = 60;
-
-// ── funciones puras ───────────────────────────────────────────────────────────
-
-/**
- * Construye un mapa `id → rank` desde un stream de resultados ordenados.
- * Rank es 1-indexed: el primer elemento tiene rank 1.
- * Si un id aparece varias veces, conserva el rank más bajo (mejor).
- *
- * @param {Array<{id: string}>} stream - Resultados ordenados (mejor primero).
- * @returns {Map<string, number>} Mapa id → rank.
- */
-function rankMap(stream) {
-  const map = new Map();
-  if (!Array.isArray(stream)) return map;
-  for (let i = 0; i < stream.length; i++) {
-    const item = stream[i];
-    if (!item || typeof item.id !== 'string') continue;
-    const rank = i + 1;
-    const previo = map.get(item.id);
-    if (previo === undefined || rank < previo) {
-      map.set(item.id, rank);
-    }
-  }
-  return map;
-}
-
-/**
- * Score parcial del stream para un id dado.
- * Si el id NO aparece en el stream, devuelve 0 (rank ∞).
- *
- * @param {Map<string, number>} map - Resultado de rankMap().
- * @param {string} id
- * @param {number} k
- * @returns {number} contribución 1/(k + rank), o 0 si no aparece.
- */
-function streamScore(map, id, k) {
-  const rank = map.get(id);
-  if (rank === undefined) return 0;
-  return 1 / (k + rank);
-}
-
-/**
- * Reciprocal Rank Fusion: combina N streams de búsqueda en un ranking unificado.
- *
- * Cada stream es un array de objetos con al menos `{ id: string }`. La posición
- * en el array determina el rank (1-indexed). Cualquier metadata extra (titulo,
- * fecha, score, etc.) del primer stream donde aparece el id se preserva en el
- * resultado.
- *
- * Si se proveen `weights`, se ponderan los streams. El array de pesos debe
- * tener el mismo largo que `streams`. Si no se provee, todos los streams pesan
- * 1.0. Pesos no positivos se tratan como 0 (efectivamente desactivan el stream).
- *
- * Si todos los pesos suman > 0, se normalizan a 1.0 para que el `combinedScore`
- * resultante sea comparable entre invocaciones con distintos pesos.
- *
- * @param {Array<Array<object>>} streams - Lista de streams ordenados.
- * @param {object} [opts]
- * @param {number} [opts.k=60] - Constante k del RRF.
- * @param {number[]} [opts.weights] - Pesos por stream (alineado con streams[]).
- * @param {number} [opts.limit] - Limita la salida a N elementos top.
- * @returns {Array<object>} Resultados combinados con `combinedScore`,
- *   ordenados descendente. Conserva metadata del primer stream donde apareció
- *   cada id.
- */
-function rrfFusion(streams, opts = {}) {
-  if (!Array.isArray(streams) || streams.length === 0) return [];
-
-  const k = typeof opts.k === 'number' && opts.k > 0 ? opts.k : RRF_K_DEFAULT;
-
-  // Normalizar pesos
-  let weights;
-  if (Array.isArray(opts.weights) && opts.weights.length === streams.length) {
-    const positivos = opts.weights.map(w =>
-      typeof w === 'number' && w > 0 ? w : 0,
-    );
-    const total = positivos.reduce((a, b) => a + b, 0);
-    weights = total > 0 ? positivos.map(w => w / total) : positivos;
-  } else {
-    // Sin weights explícitos: todos iguales y normalizados (suman 1.0).
-    const efectivos = streams.filter(s => Array.isArray(s) && s.length > 0).length;
-    if (efectivos === 0) return [];
-    weights = streams.map(s =>
-      Array.isArray(s) && s.length > 0 ? 1 / efectivos : 0,
-    );
-  }
-
-  // Construir rankMap por stream + recolectar metadata por id
-  const maps = streams.map(rankMap);
-  const metadata = new Map(); // id → primer item visto
-
-  for (const stream of streams) {
-    if (!Array.isArray(stream)) continue;
-    for (const item of stream) {
-      if (!item || typeof item.id !== 'string') continue;
-      if (!metadata.has(item.id)) {
-        metadata.set(item.id, item);
-      }
-    }
-  }
-
-  // Calcular combinedScore para cada id
-  const combined = [];
-  for (const id of metadata.keys()) {
-    let score = 0;
-    for (let i = 0; i < streams.length; i++) {
-      score += weights[i] * streamScore(maps[i], id, k);
-    }
-    if (score > 0) {
-      combined.push({
-        ...metadata.get(id),
-        combinedScore: score,
-      });
-    }
-  }
-
-  combined.sort((a, b) => b.combinedScore - a.combinedScore);
-
-  if (typeof opts.limit === 'number' && opts.limit > 0) {
-    return combined.slice(0, opts.limit);
-  }
-  return combined;
-}
-
-// ── exports ───────────────────────────────────────────────────────────────────
-
-module.exports = {
-  rrfFusion,
-  rankMap,
-  streamScore,
-  RRF_K_DEFAULT,
-};
+'use strict';
+
+/**
+ * rrf-fusion.js — Reciprocal Rank Fusion para combinar streams de búsqueda.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/src/state/hybrid-search.ts`. El
+ * algoritmo RRF combina rankings de múltiples sistemas de retrieval (BM25,
+ * vector, graph) sin requerir que sus scores sean comparables — solo importa
+ * la posición relativa (rank) en cada lista.
+ *
+ * Fórmula:
+ *
+ *     RRF(d) = Σ_i  w_i / (k + rank_i(d))
+ *
+ *   donde:
+ *     d         = un documento candidato
+ *     i         = índice del stream (BM25, vector, graph, ...)
+ *     w_i       = peso del stream i (default 1.0 si no se especifica)
+ *     rank_i(d) = posición 1-indexed de d en el stream i, o ∞ si no aparece
+ *     k         = constante de smoothing (default 60, estándar Cormack 2009)
+ *
+ * Propiedades:
+ *   - Robust frente a magnitudes de score heterogéneas — solo usa rank.
+ *   - Documentos que aparecen en múltiples streams reciben boost natural.
+ *   - Documentos que aparecen solo una vez no son penalizados — su rank ∞ en
+ *     otros streams contribuye 0.
+ *   - k ≈ 60 minimiza el peso de ranks bajos (< 60 efectivos).
+ *
+ * Versus suma simple de scores:
+ *   - No requiere normalización entre streams (BM25 vs vector cosine son
+ *     incomparables).
+ *   - Más resistente a outliers (un score muy alto en un stream no domina).
+ *
+ * Sin dependencias — Node stdlib only. Backward compatible: el caller puede
+ * mantener su lógica anterior y usar RRF solo cuando combine ≥2 streams.
+ *
+ * @module scripts/lib/rrf-fusion
+ */
+
+// ── constantes ────────────────────────────────────────────────────────────────
+
+/** Constante k del RRF estándar (Cormack et al., 2009). */
+const RRF_K_DEFAULT = 60;
+
+// ── funciones puras ───────────────────────────────────────────────────────────
+
+/**
+ * Construye un mapa `id → rank` desde un stream de resultados ordenados.
+ * Rank es 1-indexed: el primer elemento tiene rank 1.
+ * Si un id aparece varias veces, conserva el rank más bajo (mejor).
+ *
+ * @param {Array<{id: string}>} stream - Resultados ordenados (mejor primero).
+ * @returns {Map<string, number>} Mapa id → rank.
+ */
+function rankMap(stream) {
+  const map = new Map();
+  if (!Array.isArray(stream)) return map;
+  for (let i = 0; i < stream.length; i++) {
+    const item = stream[i];
+    if (!item || typeof item.id !== 'string') continue;
+    const rank = i + 1;
+    const previo = map.get(item.id);
+    if (previo === undefined || rank < previo) {
+      map.set(item.id, rank);
+    }
+  }
+  return map;
+}
+
+/**
+ * Score parcial del stream para un id dado.
+ * Si el id NO aparece en el stream, devuelve 0 (rank ∞).
+ *
+ * @param {Map<string, number>} map - Resultado de rankMap().
+ * @param {string} id
+ * @param {number} k
+ * @returns {number} contribución 1/(k + rank), o 0 si no aparece.
+ */
+function streamScore(map, id, k) {
+  const rank = map.get(id);
+  if (rank === undefined) return 0;
+  return 1 / (k + rank);
+}
+
+/**
+ * Reciprocal Rank Fusion: combina N streams de búsqueda en un ranking unificado.
+ *
+ * Cada stream es un array de objetos con al menos `{ id: string }`. La posición
+ * en el array determina el rank (1-indexed). Cualquier metadata extra (titulo,
+ * fecha, score, etc.) del primer stream donde aparece el id se preserva en el
+ * resultado.
+ *
+ * Si se proveen `weights`, se ponderan los streams. El array de pesos debe
+ * tener el mismo largo que `streams`. Si no se provee, todos los streams pesan
+ * 1.0. Pesos no positivos se tratan como 0 (efectivamente desactivan el stream).
+ *
+ * Si todos los pesos suman > 0, se normalizan a 1.0 para que el `combinedScore`
+ * resultante sea comparable entre invocaciones con distintos pesos.
+ *
+ * @param {Array<Array<object>>} streams - Lista de streams ordenados.
+ * @param {object} [opts]
+ * @param {number} [opts.k=60] - Constante k del RRF.
+ * @param {number[]} [opts.weights] - Pesos por stream (alineado con streams[]).
+ * @param {number} [opts.limit] - Limita la salida a N elementos top.
+ * @returns {Array<object>} Resultados combinados con `combinedScore`,
+ *   ordenados descendente. Conserva metadata del primer stream donde apareció
+ *   cada id.
+ */
+function rrfFusion(streams, opts = {}) {
+  if (!Array.isArray(streams) || streams.length === 0) return [];
+
+  const k = typeof opts.k === 'number' && opts.k > 0 ? opts.k : RRF_K_DEFAULT;
+
+  // Normalizar pesos
+  let weights;
+  if (Array.isArray(opts.weights) && opts.weights.length === streams.length) {
+    const positivos = opts.weights.map(w =>
+      typeof w === 'number' && w > 0 ? w : 0,
+    );
+    const total = positivos.reduce((a, b) => a + b, 0);
+    weights = total > 0 ? positivos.map(w => w / total) : positivos;
+  } else {
+    // Sin weights explícitos: todos iguales y normalizados (suman 1.0).
+    const efectivos = streams.filter(s => Array.isArray(s) && s.length > 0).length;
+    if (efectivos === 0) return [];
+    weights = streams.map(s =>
+      Array.isArray(s) && s.length > 0 ? 1 / efectivos : 0,
+    );
+  }
+
+  // Construir rankMap por stream + recolectar metadata por id
+  const maps = streams.map(rankMap);
+  const metadata = new Map(); // id → primer item visto
+
+  for (const stream of streams) {
+    if (!Array.isArray(stream)) continue;
+    for (const item of stream) {
+      if (!item || typeof item.id !== 'string') continue;
+      if (!metadata.has(item.id)) {
+        metadata.set(item.id, item);
+      }
+    }
+  }
+
+  // Calcular combinedScore para cada id
+  const combined = [];
+  for (const id of metadata.keys()) {
+    let score = 0;
+    for (let i = 0; i < streams.length; i++) {
+      score += weights[i] * streamScore(maps[i], id, k);
+    }
+    if (score > 0) {
+      combined.push({
+        ...metadata.get(id),
+        combinedScore: score,
+      });
+    }
+  }
+
+  combined.sort((a, b) => b.combinedScore - a.combinedScore);
+
+  if (typeof opts.limit === 'number' && opts.limit > 0) {
+    return combined.slice(0, opts.limit);
+  }
+  return combined;
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  rrfFusion,
+  rankMap,
+  streamScore,
+  RRF_K_DEFAULT,
+};