@saulwade/swl-ses 1.5.0 → 1.5.2

package/scripts/lib/benchmark-metrics.js

@@ -1,160 +1,160 @@
-'use strict';
-
-/**
- * benchmark-metrics.js — Métricas de retrieval para benchmark de memoria SWL.
- *
- * Patrón adoptado de `temp/agentmemory-main/benchmark/longmemeval-bench.ts`.
- * Funciones puras zero-deps. Adaptado a IDs SWL (aprendizaje, sesion,
- * instinto) en lugar de session_id de agentmemory.
- *
- * Métricas:
- *   - recallAt(k): 1.0 si al menos un gold ID está en los top-k, sino 0.0
- *   - precisionAt(k): proporción de top-k que son gold
- *   - mrr: Mean Reciprocal Rank (1/rank del primer gold encontrado)
- *   - ndcgAt(k): Normalized Discounted Cumulative Gain
- *
- * @module scripts/lib/benchmark-metrics
- */
-
-// ── helpers ───────────────────────────────────────────────────────────────────
-
-function asSet(arr) {
-  return new Set(Array.isArray(arr) ? arr : []);
-}
-
-// ── métricas individuales ─────────────────────────────────────────────────────
-
-/**
- * Recall @ k: 1.0 si ALGÚN id gold está en los primeros k retrieved.
- *
- * @param {string[]} retrievedIds - IDs ordenados (mejor primero).
- * @param {string[]} goldIds - IDs correctos esperados.
- * @param {number} k
- * @returns {number} 0 o 1
- */
-function recallAt(retrievedIds, goldIds, k) {
-  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds)) return 0;
-  const topK = new Set(retrievedIds.slice(0, k));
-  return goldIds.some(g => topK.has(g)) ? 1.0 : 0.0;
-}
-
-/**
- * Precision @ k: proporción de los primeros k retrieved que son gold.
- *
- * @param {string[]} retrievedIds
- * @param {string[]} goldIds
- * @param {number} k
- * @returns {number} en [0, 1]
- */
-function precisionAt(retrievedIds, goldIds, k) {
-  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds) || k <= 0) return 0;
-  const goldSet = asSet(goldIds);
-  const topK = retrievedIds.slice(0, k);
-  if (topK.length === 0) return 0;
-  const hits = topK.filter(id => goldSet.has(id)).length;
-  return hits / topK.length;
-}
-
-/**
- * Mean Reciprocal Rank: 1/rank del primer gold encontrado, o 0 si ninguno.
- *
- * @param {string[]} retrievedIds
- * @param {string[]} goldIds
- * @returns {number} en [0, 1]
- */
-function mrr(retrievedIds, goldIds) {
-  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds)) return 0;
-  const goldSet = asSet(goldIds);
-  for (let i = 0; i < retrievedIds.length; i++) {
-    if (goldSet.has(retrievedIds[i])) {
-      return 1 / (i + 1);
-    }
-  }
-  return 0;
-}
-
-function dcg(relevancias, k) {
-  let suma = 0;
-  for (let i = 0; i < Math.min(k, relevancias.length); i++) {
-    suma += (relevancias[i] ? 1 : 0) / Math.log2(i + 2);
-  }
-  return suma;
-}
-
-/**
- * Normalized Discounted Cumulative Gain @ k.
- *
- * @param {string[]} retrievedIds
- * @param {string[]} goldIds
- * @param {number} k
- * @returns {number} en [0, 1]
- */
-function ndcgAt(retrievedIds, goldIds, k) {
-  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds) || k <= 0) return 0;
-  const goldSet = asSet(goldIds);
-  const rels = retrievedIds.slice(0, k).map(id => goldSet.has(id));
-  const idealRels = Array.from({ length: Math.min(k, goldSet.size) }, () => true);
-  const idealDCG = dcg(idealRels, k);
-  if (idealDCG === 0) return 0;
-  return dcg(rels, k) / idealDCG;
-}
-
-// ── agregados ─────────────────────────────────────────────────────────────────
-
-/**
- * Calcula el conjunto completo de métricas para una query.
- *
- * @param {string[]} retrievedIds
- * @param {string[]} goldIds
- * @returns {{ recall_at_5, recall_at_10, recall_at_20, mrr, ndcg_at_10, precision_at_5 }}
- */
-function calcularMetricas(retrievedIds, goldIds) {
-  return {
-    recall_at_5:    recallAt(retrievedIds, goldIds, 5),
-    recall_at_10:   recallAt(retrievedIds, goldIds, 10),
-    recall_at_20:   recallAt(retrievedIds, goldIds, 20),
-    mrr:            mrr(retrievedIds, goldIds),
-    ndcg_at_10:     ndcgAt(retrievedIds, goldIds, 10),
-    precision_at_5: precisionAt(retrievedIds, goldIds, 5),
-  };
-}
-
-/**
- * Promedia métricas sobre múltiples queries.
- *
- * @param {Array<object>} resultados - Array de objetos producidos por calcularMetricas().
- * @returns {object} Promedios con campo `n` (cantidad de queries).
- */
-function promediar(resultados) {
-  if (!Array.isArray(resultados) || resultados.length === 0) {
-    return {
-      n: 0,
-      recall_at_5: 0,
-      recall_at_10: 0,
-      recall_at_20: 0,
-      mrr: 0,
-      ndcg_at_10: 0,
-      precision_at_5: 0,
-    };
-  }
-
-  const claves = ['recall_at_5', 'recall_at_10', 'recall_at_20', 'mrr', 'ndcg_at_10', 'precision_at_5'];
-  const promedio = { n: resultados.length };
-  for (const k of claves) {
-    const sum = resultados.reduce((a, r) => a + (r[k] || 0), 0);
-    promedio[k] = sum / resultados.length;
-  }
-  return promedio;
-}
-
-// ── exports ───────────────────────────────────────────────────────────────────
-
-module.exports = {
-  recallAt,
-  precisionAt,
-  mrr,
-  ndcgAt,
-  dcg,
-  calcularMetricas,
-  promediar,
-};
+'use strict';
+
+/**
+ * benchmark-metrics.js — Métricas de retrieval para benchmark de memoria SWL.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/benchmark/longmemeval-bench.ts`.
+ * Funciones puras zero-deps. Adaptado a IDs SWL (aprendizaje, sesion,
+ * instinto) en lugar de session_id de agentmemory.
+ *
+ * Métricas:
+ *   - recallAt(k): 1.0 si al menos un gold ID está en los top-k, sino 0.0
+ *   - precisionAt(k): proporción de top-k que son gold
+ *   - mrr: Mean Reciprocal Rank (1/rank del primer gold encontrado)
+ *   - ndcgAt(k): Normalized Discounted Cumulative Gain
+ *
+ * @module scripts/lib/benchmark-metrics
+ */
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function asSet(arr) {
+  return new Set(Array.isArray(arr) ? arr : []);
+}
+
+// ── métricas individuales ─────────────────────────────────────────────────────
+
+/**
+ * Recall @ k: 1.0 si ALGÚN id gold está en los primeros k retrieved.
+ *
+ * @param {string[]} retrievedIds - IDs ordenados (mejor primero).
+ * @param {string[]} goldIds - IDs correctos esperados.
+ * @param {number} k
+ * @returns {number} 0 o 1
+ */
+function recallAt(retrievedIds, goldIds, k) {
+  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds)) return 0;
+  const topK = new Set(retrievedIds.slice(0, k));
+  return goldIds.some(g => topK.has(g)) ? 1.0 : 0.0;
+}
+
+/**
+ * Precision @ k: proporción de los primeros k retrieved que son gold.
+ *
+ * @param {string[]} retrievedIds
+ * @param {string[]} goldIds
+ * @param {number} k
+ * @returns {number} en [0, 1]
+ */
+function precisionAt(retrievedIds, goldIds, k) {
+  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds) || k <= 0) return 0;
+  const goldSet = asSet(goldIds);
+  const topK = retrievedIds.slice(0, k);
+  if (topK.length === 0) return 0;
+  const hits = topK.filter(id => goldSet.has(id)).length;
+  return hits / topK.length;
+}
+
+/**
+ * Mean Reciprocal Rank: 1/rank del primer gold encontrado, o 0 si ninguno.
+ *
+ * @param {string[]} retrievedIds
+ * @param {string[]} goldIds
+ * @returns {number} en [0, 1]
+ */
+function mrr(retrievedIds, goldIds) {
+  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds)) return 0;
+  const goldSet = asSet(goldIds);
+  for (let i = 0; i < retrievedIds.length; i++) {
+    if (goldSet.has(retrievedIds[i])) {
+      return 1 / (i + 1);
+    }
+  }
+  return 0;
+}
+
+function dcg(relevancias, k) {
+  let suma = 0;
+  for (let i = 0; i < Math.min(k, relevancias.length); i++) {
+    suma += (relevancias[i] ? 1 : 0) / Math.log2(i + 2);
+  }
+  return suma;
+}
+
+/**
+ * Normalized Discounted Cumulative Gain @ k.
+ *
+ * @param {string[]} retrievedIds
+ * @param {string[]} goldIds
+ * @param {number} k
+ * @returns {number} en [0, 1]
+ */
+function ndcgAt(retrievedIds, goldIds, k) {
+  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds) || k <= 0) return 0;
+  const goldSet = asSet(goldIds);
+  const rels = retrievedIds.slice(0, k).map(id => goldSet.has(id));
+  const idealRels = Array.from({ length: Math.min(k, goldSet.size) }, () => true);
+  const idealDCG = dcg(idealRels, k);
+  if (idealDCG === 0) return 0;
+  return dcg(rels, k) / idealDCG;
+}
+
+// ── agregados ─────────────────────────────────────────────────────────────────
+
+/**
+ * Calcula el conjunto completo de métricas para una query.
+ *
+ * @param {string[]} retrievedIds
+ * @param {string[]} goldIds
+ * @returns {{ recall_at_5, recall_at_10, recall_at_20, mrr, ndcg_at_10, precision_at_5 }}
+ */
+function calcularMetricas(retrievedIds, goldIds) {
+  return {
+    recall_at_5:    recallAt(retrievedIds, goldIds, 5),
+    recall_at_10:   recallAt(retrievedIds, goldIds, 10),
+    recall_at_20:   recallAt(retrievedIds, goldIds, 20),
+    mrr:            mrr(retrievedIds, goldIds),
+    ndcg_at_10:     ndcgAt(retrievedIds, goldIds, 10),
+    precision_at_5: precisionAt(retrievedIds, goldIds, 5),
+  };
+}
+
+/**
+ * Promedia métricas sobre múltiples queries.
+ *
+ * @param {Array<object>} resultados - Array de objetos producidos por calcularMetricas().
+ * @returns {object} Promedios con campo `n` (cantidad de queries).
+ */
+function promediar(resultados) {
+  if (!Array.isArray(resultados) || resultados.length === 0) {
+    return {
+      n: 0,
+      recall_at_5: 0,
+      recall_at_10: 0,
+      recall_at_20: 0,
+      mrr: 0,
+      ndcg_at_10: 0,
+      precision_at_5: 0,
+    };
+  }
+
+  const claves = ['recall_at_5', 'recall_at_10', 'recall_at_20', 'mrr', 'ndcg_at_10', 'precision_at_5'];
+  const promedio = { n: resultados.length };
+  for (const k of claves) {
+    const sum = resultados.reduce((a, r) => a + (r[k] || 0), 0);
+    promedio[k] = sum / resultados.length;
+  }
+  return promedio;
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  recallAt,
+  precisionAt,
+  mrr,
+  ndcgAt,
+  dcg,
+  calcularMetricas,
+  promediar,
+};