@saulwade/swl-ses 1.5.0 → 1.5.2

package/scripts/benchmark-memoria.js

@@ -1,167 +1,167 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * benchmark-memoria.js — CLI runner para benchmark de retrieval sobre memoria SWL.
- *
- * Ejecuta queries de un dataset JSONL contra `hooks/lib/memory-search`
- * (que usa RRF fusion sobre aprendizajes/sesiones/instintos) y reporta
- * métricas R@5, R@10, R@20, MRR, nDCG@10, P@5.
- *
- * Patrón adoptado de `temp/agentmemory-main/benchmark/longmemeval-bench.ts`.
- * Adaptado para swl-ses: file-based, sin embeddings ML, dataset SWL-específico.
- *
- * Uso:
- *   node scripts/benchmark-memoria.js [opciones]
- *
- * Opciones:
- *   --dataset <ruta>   Dataset JSONL (default: .planning/benchmark/dataset.jsonl)
- *   --limit <n>        Top-k a recuperar por query (default: 20)
- *   --json             Output en JSON (para scripts)
- *   --verbose          Detalle por query
- *
- * Exit codes:
- *   0 - OK
- *   1 - Error de I/O o dataset inválido
- *   2 - Argumentos inválidos
- *
- * Persistencia opcional: si se setea SWL_BENCHMARK_PERSIST=1, escribe
- * el resultado agregado a `.planning/evolucion/benchmark-memoria.jsonl`
- * para tracking histórico.
- */
-
-const fs   = require('fs');
-const path = require('path');
-
-const { ejecutarDataset } = require('./lib/longmemeval-runner');
-
-const DATASET_DEFAULT = '.planning/benchmark/dataset.jsonl';
-const HISTORICO_PATH  = '.planning/evolucion/benchmark-memoria.jsonl';
-
-function uso() {
-  console.error('Uso: node scripts/benchmark-memoria.js [--dataset <ruta>] [--limit <n>] [--json] [--verbose]');
-  process.exit(2);
-}
-
-function parseArgs(argv) {
-  const opts = {
-    dataset: DATASET_DEFAULT,
-    limit: 20,
-    json: false,
-    verbose: false,
-  };
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === '--dataset') opts.dataset = argv[++i];
-    else if (arg === '--limit') opts.limit = parseInt(argv[++i], 10) || 20;
-    else if (arg === '--json') opts.json = true;
-    else if (arg === '--verbose') opts.verbose = true;
-    else if (arg === '--help' || arg === '-h') uso();
-  }
-  return opts;
-}
-
-function persistirHistorico(baseDir, resumen) {
-  if (process.env.SWL_BENCHMARK_PERSIST !== '1') return;
-  try {
-    const dirEvolucion = path.join(baseDir, '.planning', 'evolucion');
-    if (!fs.existsSync(dirEvolucion)) fs.mkdirSync(dirEvolucion, { recursive: true });
-    const linea = JSON.stringify({
-      timestamp: new Date().toISOString(),
-      ...resumen,
-    });
-    fs.appendFileSync(path.join(baseDir, HISTORICO_PATH), linea + '\n', 'utf8');
-  } catch (_) {
-    // best-effort
-  }
-}
-
-function reportarTexto(resultado, opts) {
-  const { promedio, dataset, entries } = resultado;
-
-  console.log('================================================================');
-  console.log('   Benchmark de retrieval de memoria SWL');
-  console.log('================================================================');
-  console.log('');
-  console.log(`Dataset:      ${opts.dataset}`);
-  console.log(`Total queries: ${dataset.total}`);
-  console.log(`  Reales:      ${dataset.real}`);
-  console.log(`  Placeholder: ${dataset.placeholder}`);
-  console.log(`Significativo: ${dataset.significativo ? 'sí' : 'NO (requiere ≥30 reales)'}`);
-  console.log('');
-
-  if (!dataset.significativo) {
-    console.log('⚠ ADVERTENCIA: dataset con menos de 30 queries reales.');
-    console.log('  Las métricas son INDICATIVAS, no estadísticamente significativas.');
-    console.log('  Para usar como gate de release, expandir el dataset con preguntas');
-    console.log('  curadas extraídas de uso real (ver SKILL.md de benchmark-memoria).');
-    console.log('');
-  }
-
-  console.log('────────────── Métricas agregadas ──────────────');
-  console.log(`  Recall @ 5:     ${(promedio.recall_at_5 * 100).toFixed(1)}%`);
-  console.log(`  Recall @ 10:    ${(promedio.recall_at_10 * 100).toFixed(1)}%`);
-  console.log(`  Recall @ 20:    ${(promedio.recall_at_20 * 100).toFixed(1)}%`);
-  console.log(`  MRR:            ${promedio.mrr.toFixed(3)}`);
-  console.log(`  nDCG @ 10:      ${promedio.ndcg_at_10.toFixed(3)}`);
-  console.log(`  Precision @ 5:  ${(promedio.precision_at_5 * 100).toFixed(1)}%`);
-  console.log('');
-
-  if (opts.verbose) {
-    console.log('────────────── Detalle por query ──────────────');
-    for (const r of entries) {
-      const mark = r.metricas.recall_at_5 > 0 ? '✓' : '✗';
-      console.log(`  ${mark} ${r.question_id} [${r.category || 'n/a'}, ${r.status}] ` +
-        `R@5=${r.metricas.recall_at_5} R@10=${r.metricas.recall_at_10} ` +
-        `MRR=${r.metricas.mrr.toFixed(2)} (${r.latencyMs}ms)`);
-      if (r.metricas.recall_at_5 === 0 && opts.verbose) {
-        console.log(`      Q: ${r.question.slice(0, 80)}`);
-        console.log(`      Gold:      ${r.goldIds.slice(0, 3).join(', ')}${r.goldIds.length > 3 ? '...' : ''}`);
-        console.log(`      Retrieved: ${r.retrievedIds.slice(0, 5).join(', ')}`);
-      }
-    }
-    console.log('');
-  }
-}
-
-function main() {
-  const opts = parseArgs(process.argv.slice(2));
-  const baseDir = process.cwd();
-
-  if (!fs.existsSync(opts.dataset)) {
-    console.error(`Dataset no encontrado: ${opts.dataset}`);
-    console.error(`Crea uno o usa el placeholder en ${DATASET_DEFAULT}.`);
-    process.exit(1);
-  }
-
-  let resultado;
-  try {
-    resultado = ejecutarDataset(baseDir, opts.dataset, { limit: opts.limit });
-  } catch (err) {
-    console.error(`Error ejecutando benchmark: ${err.message}`);
-    process.exit(1);
-  }
-
-  if (opts.json) {
-    console.log(JSON.stringify(resultado, null, 2));
-  } else {
-    reportarTexto(resultado, opts);
-  }
-
-  persistirHistorico(baseDir, {
-    dataset: opts.dataset,
-    n: resultado.dataset.total,
-    significativo: resultado.dataset.significativo,
-    promedio: resultado.promedio,
-  });
-
-  process.exit(0);
-}
-
-if (require.main === module) {
-  main();
-}
-
-module.exports = {
-  parseArgs,
-};
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * benchmark-memoria.js — CLI runner para benchmark de retrieval sobre memoria SWL.
+ *
+ * Ejecuta queries de un dataset JSONL contra `hooks/lib/memory-search`
+ * (que usa RRF fusion sobre aprendizajes/sesiones/instintos) y reporta
+ * métricas R@5, R@10, R@20, MRR, nDCG@10, P@5.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/benchmark/longmemeval-bench.ts`.
+ * Adaptado para swl-ses: file-based, sin embeddings ML, dataset SWL-específico.
+ *
+ * Uso:
+ *   node scripts/benchmark-memoria.js [opciones]
+ *
+ * Opciones:
+ *   --dataset <ruta>   Dataset JSONL (default: .planning/benchmark/dataset.jsonl)
+ *   --limit <n>        Top-k a recuperar por query (default: 20)
+ *   --json             Output en JSON (para scripts)
+ *   --verbose          Detalle por query
+ *
+ * Exit codes:
+ *   0 - OK
+ *   1 - Error de I/O o dataset inválido
+ *   2 - Argumentos inválidos
+ *
+ * Persistencia opcional: si se setea SWL_BENCHMARK_PERSIST=1, escribe
+ * el resultado agregado a `.planning/evolucion/benchmark-memoria.jsonl`
+ * para tracking histórico.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const { ejecutarDataset } = require('./lib/longmemeval-runner');
+
+const DATASET_DEFAULT = '.planning/benchmark/dataset.jsonl';
+const HISTORICO_PATH  = '.planning/evolucion/benchmark-memoria.jsonl';
+
+function uso() {
+  console.error('Uso: node scripts/benchmark-memoria.js [--dataset <ruta>] [--limit <n>] [--json] [--verbose]');
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  const opts = {
+    dataset: DATASET_DEFAULT,
+    limit: 20,
+    json: false,
+    verbose: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--dataset') opts.dataset = argv[++i];
+    else if (arg === '--limit') opts.limit = parseInt(argv[++i], 10) || 20;
+    else if (arg === '--json') opts.json = true;
+    else if (arg === '--verbose') opts.verbose = true;
+    else if (arg === '--help' || arg === '-h') uso();
+  }
+  return opts;
+}
+
+function persistirHistorico(baseDir, resumen) {
+  if (process.env.SWL_BENCHMARK_PERSIST !== '1') return;
+  try {
+    const dirEvolucion = path.join(baseDir, '.planning', 'evolucion');
+    if (!fs.existsSync(dirEvolucion)) fs.mkdirSync(dirEvolucion, { recursive: true });
+    const linea = JSON.stringify({
+      timestamp: new Date().toISOString(),
+      ...resumen,
+    });
+    fs.appendFileSync(path.join(baseDir, HISTORICO_PATH), linea + '\n', 'utf8');
+  } catch (_) {
+    // best-effort
+  }
+}
+
+function reportarTexto(resultado, opts) {
+  const { promedio, dataset, entries } = resultado;
+
+  console.log('================================================================');
+  console.log('   Benchmark de retrieval de memoria SWL');
+  console.log('================================================================');
+  console.log('');
+  console.log(`Dataset:      ${opts.dataset}`);
+  console.log(`Total queries: ${dataset.total}`);
+  console.log(`  Reales:      ${dataset.real}`);
+  console.log(`  Placeholder: ${dataset.placeholder}`);
+  console.log(`Significativo: ${dataset.significativo ? 'sí' : 'NO (requiere ≥30 reales)'}`);
+  console.log('');
+
+  if (!dataset.significativo) {
+    console.log('⚠ ADVERTENCIA: dataset con menos de 30 queries reales.');
+    console.log('  Las métricas son INDICATIVAS, no estadísticamente significativas.');
+    console.log('  Para usar como gate de release, expandir el dataset con preguntas');
+    console.log('  curadas extraídas de uso real (ver SKILL.md de benchmark-memoria).');
+    console.log('');
+  }
+
+  console.log('────────────── Métricas agregadas ──────────────');
+  console.log(`  Recall @ 5:     ${(promedio.recall_at_5 * 100).toFixed(1)}%`);
+  console.log(`  Recall @ 10:    ${(promedio.recall_at_10 * 100).toFixed(1)}%`);
+  console.log(`  Recall @ 20:    ${(promedio.recall_at_20 * 100).toFixed(1)}%`);
+  console.log(`  MRR:            ${promedio.mrr.toFixed(3)}`);
+  console.log(`  nDCG @ 10:      ${promedio.ndcg_at_10.toFixed(3)}`);
+  console.log(`  Precision @ 5:  ${(promedio.precision_at_5 * 100).toFixed(1)}%`);
+  console.log('');
+
+  if (opts.verbose) {
+    console.log('────────────── Detalle por query ──────────────');
+    for (const r of entries) {
+      const mark = r.metricas.recall_at_5 > 0 ? '✓' : '✗';
+      console.log(`  ${mark} ${r.question_id} [${r.category || 'n/a'}, ${r.status}] ` +
+        `R@5=${r.metricas.recall_at_5} R@10=${r.metricas.recall_at_10} ` +
+        `MRR=${r.metricas.mrr.toFixed(2)} (${r.latencyMs}ms)`);
+      if (r.metricas.recall_at_5 === 0 && opts.verbose) {
+        console.log(`      Q: ${r.question.slice(0, 80)}`);
+        console.log(`      Gold:      ${r.goldIds.slice(0, 3).join(', ')}${r.goldIds.length > 3 ? '...' : ''}`);
+        console.log(`      Retrieved: ${r.retrievedIds.slice(0, 5).join(', ')}`);
+      }
+    }
+    console.log('');
+  }
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const baseDir = process.cwd();
+
+  if (!fs.existsSync(opts.dataset)) {
+    console.error(`Dataset no encontrado: ${opts.dataset}`);
+    console.error(`Crea uno o usa el placeholder en ${DATASET_DEFAULT}.`);
+    process.exit(1);
+  }
+
+  let resultado;
+  try {
+    resultado = ejecutarDataset(baseDir, opts.dataset, { limit: opts.limit });
+  } catch (err) {
+    console.error(`Error ejecutando benchmark: ${err.message}`);
+    process.exit(1);
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(resultado, null, 2));
+  } else {
+    reportarTexto(resultado, opts);
+  }
+
+  persistirHistorico(baseDir, {
+    dataset: opts.dataset,
+    n: resultado.dataset.total,
+    significativo: resultado.dataset.significativo,
+    promedio: resultado.promedio,
+  });
+
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  parseArgs,
+};