@saulwade/swl-ses 1.5.1 → 1.6.0

package/scripts/lib/semantic-search.js

@@ -1,252 +1,252 @@
-'use strict';
-
-/**
- * semantic-search.js
- *
- * Búsqueda híbrida con fallback automático:
- *   - Default: Jaccard similarity sobre tokens normalizados (zero-deps).
- *   - Opt-in: embeddings con @xenova/transformers (vía SWL_SEMANTIC_BACKEND=xenova).
- *
- * Patrón adaptado de `temp/cass_memory_system-main/src/semantic.ts`. Diferencias:
- *   - Carga lazy de Xenova (no requiere instalación si no se usa).
- *   - API uniforme: el caller no sabe qué backend está activo.
- *   - Tokenización compatible con español (acentos preservados, stopwords es-MX).
- *
- * Cuándo usar:
- *   - Buscar skills similares por significado, no solo keywords (150 skills).
- *   - Encontrar instintos relacionados a un patrón observado.
- *   - Detectar duplicados semánticos en APRENDIZAJES.md.
- *
- * API:
- *   - jaccardSimilarity(a, b)              → [0, 1]
- *   - cosineSimilarity(a, b)               → [-1, 1] (vectores numéricos)
- *   - tokenize(text)                       → array de tokens
- *   - semanticRank(query, items, opts)     → items rankeados por similitud
- *
- * Backend: el módulo NO requiere Xenova. Si SWL_SEMANTIC_BACKEND=xenova y
- * @xenova/transformers está instalado, se usa para embeddings. Si no, Jaccard.
- *
- * Instalación opt-in del backend de embeddings:
- *
- *   npm install -g @xenova/transformers
- *   export SWL_SEMANTIC_BACKEND=xenova
- *
- * @xenova/transformers ya NO es dependencia del paquete swl-ses (v1.0.1+)
- * porque arrastra `prebuild-install@7.1.3` deprecated y sumaba ~50 MB al
- * install para una feature opt-in raramente usada. El usuario que quiera
- * el backend semántico lo instala manualmente.
- *
- * @module scripts/lib/semantic-search
- */
-
-// ── stopwords es-MX ───────────────────────────────────────────────────────────
-
-const STOPWORDS = new Set([
-  'a', 'al', 'algo', 'algunas', 'algunos', 'ante', 'antes', 'aunque',
-  'cada', 'cierta', 'ciertas', 'cierto', 'ciertos', 'como', 'con', 'contra',
-  'cual', 'cuando', 'de', 'del', 'desde', 'donde', 'durante',
-  'e', 'el', 'ella', 'ellas', 'ellos', 'en', 'entre', 'era', 'erais', 'eran',
-  'eras', 'eres', 'es', 'esa', 'esas', 'ese', 'eso', 'esos', 'esta', 'estaba',
-  'estaban', 'estado', 'estamos', 'estan', 'están', 'estar', 'estas', 'este',
-  'esto', 'estos', 'estoy', 'fue', 'fuera', 'fueron', 'fui', 'ha', 'habia',
-  'había', 'han', 'hasta', 'hay', 'haya', 'la', 'las', 'le', 'les', 'lo',
-  'los', 'me', 'mi', 'mis', 'mucho', 'muchos', 'muy', 'nada', 'ni', 'no',
-  'nos', 'nosotros', 'nuestra', 'nuestras', 'nuestro', 'nuestros', 'o', 'os',
-  'otra', 'otras', 'otro', 'otros', 'para', 'pero', 'poco', 'por', 'porque',
-  'que', 'quien', 'quienes', 'qué', 'se', 'sea', 'sean', 'ser', 'si', 'sí',
-  'sido', 'siendo', 'sin', 'sobre', 'soy', 'su', 'sus', 'también', 'tan',
-  'tanto', 'te', 'tener', 'ti', 'tiene', 'tienen', 'todo', 'todos', 'tu',
-  'tus', 'un', 'una', 'unas', 'uno', 'unos', 'usted', 'ustedes', 'va', 'vais',
-  'van', 'vas', 'ver', 'y', 'ya', 'yo',
-]);
-
-// ── tokenización ──────────────────────────────────────────────────────────────
-
-/**
- * Tokeniza texto en español de México. Pasos:
- *   1. lowercase
- *   2. eliminar puntuación
- *   3. dividir en palabras
- *   4. eliminar stopwords
- *   5. eliminar tokens muy cortos (<2 chars)
- *
- * Preserva acentos (cá vs ca son distintos). No hace stemming.
- *
- * @param {string} texto
- * @returns {string[]} tokens
- */
-function tokenize(texto) {
-  if (!texto || typeof texto !== 'string') return [];
-  return texto
-    .toLowerCase()
-    .replace(/[^\p{L}\p{N}\s]/gu, ' ')   // letras unicode + números
-    .split(/\s+/)
-    .filter(t => t.length >= 2 && !STOPWORDS.has(t));
-}
-
-// ── Jaccard ───────────────────────────────────────────────────────────────────
-
-/**
- * Jaccard similarity sobre conjuntos de tokens.
- * jaccard(A, B) = |A ∩ B| / |A ∪ B|
- *
- * Ambos textos vacíos → 0 (no hay similitud, no hay info).
- * Un texto vacío + uno con tokens → 0.
- *
- * @param {string} textA
- * @param {string} textB
- * @returns {number} en [0, 1]
- */
-function jaccardSimilarity(textA, textB) {
-  const a = new Set(tokenize(textA));
-  const b = new Set(tokenize(textB));
-  if (a.size === 0 && b.size === 0) return 0;
-  if (a.size === 0 || b.size === 0) return 0;
-
-  let inter = 0;
-  for (const t of a) if (b.has(t)) inter++;
-  const union = a.size + b.size - inter;
-  return inter / union;
-}
-
-// ── Cosine (para embeddings) ──────────────────────────────────────────────────
-
-/**
- * Cosine similarity entre dos vectores numéricos.
- * cos(A, B) = (A · B) / (||A|| × ||B||)
- *
- * @param {number[]} vecA
- * @param {number[]} vecB
- * @returns {number} en [-1, 1]
- */
-function cosineSimilarity(vecA, vecB) {
-  if (!Array.isArray(vecA) || !Array.isArray(vecB)) return 0;
-  if (vecA.length !== vecB.length || vecA.length === 0) return 0;
-
-  let dot = 0, normA = 0, normB = 0;
-  for (let i = 0; i < vecA.length; i++) {
-    const a = vecA[i] || 0;
-    const b = vecB[i] || 0;
-    dot += a * b;
-    normA += a * a;
-    normB += b * b;
-  }
-  if (normA === 0 || normB === 0) return 0;
-  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
-}
-
-// ── backend de embeddings (Xenova lazy) ───────────────────────────────────────
-
-/**
- * Estado lazy del backend Xenova. Se carga la primera vez que se invoca
- * embeddingsBackend() y NO falla si no está instalado.
- */
-let _xenovaPipeline = null;
-let _xenovaTried = false;
-
-async function tryLoadXenova() {
-  if (_xenovaPipeline || _xenovaTried) return _xenovaPipeline;
-  _xenovaTried = true;
-  try {
-    // Carga dinámica para evitar require al inicio
-    const transformers = require('@xenova/transformers');
-    const { pipeline } = transformers;
-    _xenovaPipeline = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2');
-    return _xenovaPipeline;
-  } catch (_) {
-    // No instalado o error al cargar: silencioso. Caller usará fallback.
-    return null;
-  }
-}
-
-/**
- * Detecta el backend activo según SWL_SEMANTIC_BACKEND.
- * Sin variable o valor != 'xenova' → 'jaccard'.
- */
-function activeBackend() {
-  const env = (process.env.SWL_SEMANTIC_BACKEND || '').toLowerCase().trim();
-  return env === 'xenova' ? 'xenova' : 'jaccard';
-}
-
-/**
- * Embebe un texto en un vector. Solo disponible si Xenova está activo.
- * Retorna null si el backend no es xenova o no se pudo cargar.
- *
- * @param {string} texto
- * @returns {Promise<number[]|null>}
- */
-async function embed(texto) {
-  if (activeBackend() !== 'xenova') return null;
-  const pipe = await tryLoadXenova();
-  if (!pipe) return null;
-  try {
-    const out = await pipe(texto, { pooling: 'mean', normalize: true });
-    return Array.from(out.data);
-  } catch (_) {
-    return null;
-  }
-}
-
-// ── ranking ──────────────────────────────────────────────────────────────────
-
-/**
- * Rankea items por similitud con la query.
- *
- * @param {string} query
- * @param {Array<{id: string, text: string, embedding?: number[]}>} items
- * @param {object} [opts]
- * @param {number} [opts.threshold=0]  - filtra resultados con score < threshold
- * @param {number} [opts.limit=10]     - limita resultados
- * @returns {Promise<Array<{id, text, score, backend}>>}
- */
-async function semanticRank(query, items, opts = {}) {
-  const { threshold = 0, limit = 10 } = opts;
-  if (!query || !Array.isArray(items)) return [];
-
-  const backend = activeBackend();
-  let results;
-
-  if (backend === 'xenova') {
-    const queryEmb = await embed(query);
-    if (queryEmb) {
-      results = await Promise.all(items.map(async (item) => {
-        let itemEmb = item.embedding;
-        if (!itemEmb) itemEmb = await embed(item.text || '');
-        const score = (queryEmb && itemEmb) ? cosineSimilarity(queryEmb, itemEmb) : 0;
-        return { id: item.id, text: item.text, score, backend: 'xenova' };
-      }));
-    } else {
-      // Backend declarado pero no disponible → fallback transparente
-      results = items.map(item => ({
-        id: item.id,
-        text: item.text,
-        score: jaccardSimilarity(query, item.text || ''),
-        backend: 'jaccard-fallback',
-      }));
-    }
-  } else {
-    results = items.map(item => ({
-      id: item.id,
-      text: item.text,
-      score: jaccardSimilarity(query, item.text || ''),
-      backend: 'jaccard',
-    }));
-  }
-
-  return results
-    .filter(r => r.score >= threshold)
-    .sort((a, b) => b.score - a.score)
-    .slice(0, limit);
-}
-
-// ── exports ───────────────────────────────────────────────────────────────────
-
-module.exports = {
-  tokenize,
-  jaccardSimilarity,
-  cosineSimilarity,
-  embed,
-  semanticRank,
-  activeBackend,
-  STOPWORDS,
-};
+'use strict';
+
+/**
+ * semantic-search.js
+ *
+ * Búsqueda híbrida con fallback automático:
+ *   - Default: Jaccard similarity sobre tokens normalizados (zero-deps).
+ *   - Opt-in: embeddings con @xenova/transformers (vía SWL_SEMANTIC_BACKEND=xenova).
+ *
+ * Patrón adaptado de `temp/cass_memory_system-main/src/semantic.ts`. Diferencias:
+ *   - Carga lazy de Xenova (no requiere instalación si no se usa).
+ *   - API uniforme: el caller no sabe qué backend está activo.
+ *   - Tokenización compatible con español (acentos preservados, stopwords es-MX).
+ *
+ * Cuándo usar:
+ *   - Buscar skills similares por significado, no solo keywords (150 skills).
+ *   - Encontrar instintos relacionados a un patrón observado.
+ *   - Detectar duplicados semánticos en APRENDIZAJES.md.
+ *
+ * API:
+ *   - jaccardSimilarity(a, b)              → [0, 1]
+ *   - cosineSimilarity(a, b)               → [-1, 1] (vectores numéricos)
+ *   - tokenize(text)                       → array de tokens
+ *   - semanticRank(query, items, opts)     → items rankeados por similitud
+ *
+ * Backend: el módulo NO requiere Xenova. Si SWL_SEMANTIC_BACKEND=xenova y
+ * @xenova/transformers está instalado, se usa para embeddings. Si no, Jaccard.
+ *
+ * Instalación opt-in del backend de embeddings:
+ *
+ *   npm install -g @xenova/transformers
+ *   export SWL_SEMANTIC_BACKEND=xenova
+ *
+ * @xenova/transformers ya NO es dependencia del paquete swl-ses (v1.0.1+)
+ * porque arrastra `prebuild-install@7.1.3` deprecated y sumaba ~50 MB al
+ * install para una feature opt-in raramente usada. El usuario que quiera
+ * el backend semántico lo instala manualmente.
+ *
+ * @module scripts/lib/semantic-search
+ */
+
+// ── stopwords es-MX ───────────────────────────────────────────────────────────
+
+const STOPWORDS = new Set([
+  'a', 'al', 'algo', 'algunas', 'algunos', 'ante', 'antes', 'aunque',
+  'cada', 'cierta', 'ciertas', 'cierto', 'ciertos', 'como', 'con', 'contra',
+  'cual', 'cuando', 'de', 'del', 'desde', 'donde', 'durante',
+  'e', 'el', 'ella', 'ellas', 'ellos', 'en', 'entre', 'era', 'erais', 'eran',
+  'eras', 'eres', 'es', 'esa', 'esas', 'ese', 'eso', 'esos', 'esta', 'estaba',
+  'estaban', 'estado', 'estamos', 'estan', 'están', 'estar', 'estas', 'este',
+  'esto', 'estos', 'estoy', 'fue', 'fuera', 'fueron', 'fui', 'ha', 'habia',
+  'había', 'han', 'hasta', 'hay', 'haya', 'la', 'las', 'le', 'les', 'lo',
+  'los', 'me', 'mi', 'mis', 'mucho', 'muchos', 'muy', 'nada', 'ni', 'no',
+  'nos', 'nosotros', 'nuestra', 'nuestras', 'nuestro', 'nuestros', 'o', 'os',
+  'otra', 'otras', 'otro', 'otros', 'para', 'pero', 'poco', 'por', 'porque',
+  'que', 'quien', 'quienes', 'qué', 'se', 'sea', 'sean', 'ser', 'si', 'sí',
+  'sido', 'siendo', 'sin', 'sobre', 'soy', 'su', 'sus', 'también', 'tan',
+  'tanto', 'te', 'tener', 'ti', 'tiene', 'tienen', 'todo', 'todos', 'tu',
+  'tus', 'un', 'una', 'unas', 'uno', 'unos', 'usted', 'ustedes', 'va', 'vais',
+  'van', 'vas', 'ver', 'y', 'ya', 'yo',
+]);
+
+// ── tokenización ──────────────────────────────────────────────────────────────
+
+/**
+ * Tokeniza texto en español de México. Pasos:
+ *   1. lowercase
+ *   2. eliminar puntuación
+ *   3. dividir en palabras
+ *   4. eliminar stopwords
+ *   5. eliminar tokens muy cortos (<2 chars)
+ *
+ * Preserva acentos (cá vs ca son distintos). No hace stemming.
+ *
+ * @param {string} texto
+ * @returns {string[]} tokens
+ */
+function tokenize(texto) {
+  if (!texto || typeof texto !== 'string') return [];
+  return texto
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s]/gu, ' ')   // letras unicode + números
+    .split(/\s+/)
+    .filter(t => t.length >= 2 && !STOPWORDS.has(t));
+}
+
+// ── Jaccard ───────────────────────────────────────────────────────────────────
+
+/**
+ * Jaccard similarity sobre conjuntos de tokens.
+ * jaccard(A, B) = |A ∩ B| / |A ∪ B|
+ *
+ * Ambos textos vacíos → 0 (no hay similitud, no hay info).
+ * Un texto vacío + uno con tokens → 0.
+ *
+ * @param {string} textA
+ * @param {string} textB
+ * @returns {number} en [0, 1]
+ */
+function jaccardSimilarity(textA, textB) {
+  const a = new Set(tokenize(textA));
+  const b = new Set(tokenize(textB));
+  if (a.size === 0 && b.size === 0) return 0;
+  if (a.size === 0 || b.size === 0) return 0;
+
+  let inter = 0;
+  for (const t of a) if (b.has(t)) inter++;
+  const union = a.size + b.size - inter;
+  return inter / union;
+}
+
+// ── Cosine (para embeddings) ──────────────────────────────────────────────────
+
+/**
+ * Cosine similarity entre dos vectores numéricos.
+ * cos(A, B) = (A · B) / (||A|| × ||B||)
+ *
+ * @param {number[]} vecA
+ * @param {number[]} vecB
+ * @returns {number} en [-1, 1]
+ */
+function cosineSimilarity(vecA, vecB) {
+  if (!Array.isArray(vecA) || !Array.isArray(vecB)) return 0;
+  if (vecA.length !== vecB.length || vecA.length === 0) return 0;
+
+  let dot = 0, normA = 0, normB = 0;
+  for (let i = 0; i < vecA.length; i++) {
+    const a = vecA[i] || 0;
+    const b = vecB[i] || 0;
+    dot += a * b;
+    normA += a * a;
+    normB += b * b;
+  }
+  if (normA === 0 || normB === 0) return 0;
+  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+
+// ── backend de embeddings (Xenova lazy) ───────────────────────────────────────
+
+/**
+ * Estado lazy del backend Xenova. Se carga la primera vez que se invoca
+ * embeddingsBackend() y NO falla si no está instalado.
+ */
+let _xenovaPipeline = null;
+let _xenovaTried = false;
+
+async function tryLoadXenova() {
+  if (_xenovaPipeline || _xenovaTried) return _xenovaPipeline;
+  _xenovaTried = true;
+  try {
+    // Carga dinámica para evitar require al inicio
+    const transformers = require('@xenova/transformers');
+    const { pipeline } = transformers;
+    _xenovaPipeline = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2');
+    return _xenovaPipeline;
+  } catch (_) {
+    // No instalado o error al cargar: silencioso. Caller usará fallback.
+    return null;
+  }
+}
+
+/**
+ * Detecta el backend activo según SWL_SEMANTIC_BACKEND.
+ * Sin variable o valor != 'xenova' → 'jaccard'.
+ */
+function activeBackend() {
+  const env = (process.env.SWL_SEMANTIC_BACKEND || '').toLowerCase().trim();
+  return env === 'xenova' ? 'xenova' : 'jaccard';
+}
+
+/**
+ * Embebe un texto en un vector. Solo disponible si Xenova está activo.
+ * Retorna null si el backend no es xenova o no se pudo cargar.
+ *
+ * @param {string} texto
+ * @returns {Promise<number[]|null>}
+ */
+async function embed(texto) {
+  if (activeBackend() !== 'xenova') return null;
+  const pipe = await tryLoadXenova();
+  if (!pipe) return null;
+  try {
+    const out = await pipe(texto, { pooling: 'mean', normalize: true });
+    return Array.from(out.data);
+  } catch (_) {
+    return null;
+  }
+}
+
+// ── ranking ──────────────────────────────────────────────────────────────────
+
+/**
+ * Rankea items por similitud con la query.
+ *
+ * @param {string} query
+ * @param {Array<{id: string, text: string, embedding?: number[]}>} items
+ * @param {object} [opts]
+ * @param {number} [opts.threshold=0]  - filtra resultados con score < threshold
+ * @param {number} [opts.limit=10]     - limita resultados
+ * @returns {Promise<Array<{id, text, score, backend}>>}
+ */
+async function semanticRank(query, items, opts = {}) {
+  const { threshold = 0, limit = 10 } = opts;
+  if (!query || !Array.isArray(items)) return [];
+
+  const backend = activeBackend();
+  let results;
+
+  if (backend === 'xenova') {
+    const queryEmb = await embed(query);
+    if (queryEmb) {
+      results = await Promise.all(items.map(async (item) => {
+        let itemEmb = item.embedding;
+        if (!itemEmb) itemEmb = await embed(item.text || '');
+        const score = (queryEmb && itemEmb) ? cosineSimilarity(queryEmb, itemEmb) : 0;
+        return { id: item.id, text: item.text, score, backend: 'xenova' };
+      }));
+    } else {
+      // Backend declarado pero no disponible → fallback transparente
+      results = items.map(item => ({
+        id: item.id,
+        text: item.text,
+        score: jaccardSimilarity(query, item.text || ''),
+        backend: 'jaccard-fallback',
+      }));
+    }
+  } else {
+    results = items.map(item => ({
+      id: item.id,
+      text: item.text,
+      score: jaccardSimilarity(query, item.text || ''),
+      backend: 'jaccard',
+    }));
+  }
+
+  return results
+    .filter(r => r.score >= threshold)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit);
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  tokenize,
+  jaccardSimilarity,
+  cosineSimilarity,
+  embed,
+  semanticRank,
+  activeBackend,
+  STOPWORDS,
+};