@saulwade/swl-ses 1.1.4 → 1.2.0

package/scripts/lib/eval-quality.js

@@ -0,0 +1,171 @@
+'use strict';
+
+/**
+ * eval-quality.js — Métricas de calidad para outputs estructurados de SWL.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/src/eval/quality.ts`. Adaptado a
+ * swl-ses: scoring de aprendizajes, instintos, y resultados de búsqueda
+ * memoria.
+ *
+ * Cada función devuelve un score en [0, 100]. Los puntos se asignan por
+ * "presencia y calidad de campos clave" — un output con todos los campos
+ * tiene score 100, un output trivial tiene score bajo.
+ *
+ * Funciones puras zero-deps.
+ *
+ * @module scripts/lib/eval-quality
+ */
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function clamp(n, min, max) {
+  if (Number.isNaN(n)) return min;
+  return Math.max(min, Math.min(max, n));
+}
+
+// ── scoring de outputs ────────────────────────────────────────────────────────
+
+/**
+ * Score de calidad de una observación comprimida.
+ * Adaptado de scoreCompression() de agentmemory.
+ *
+ * Distribución de puntos:
+ *   - facts presentes (no vacíos):       25
+ *   - facts ≥ 3:                         +10
+ *   - narrative ≥ 20 chars:               20
+ *   - narrative ≥ 50 chars:               +5
+ *   - title 5-120 chars:                  15
+ *   - concepts presentes:                 15
+ *   - importance ∈ [1, 10]:               10
+ *
+ * @param {object} obs
+ * @returns {number} en [0, 100]
+ */
+function scoreObservacion(obs) {
+  let score = 0;
+  if (Array.isArray(obs?.facts) && obs.facts.length > 0) score += 25;
+  if (Array.isArray(obs?.facts) && obs.facts.length >= 3) score += 10;
+  if (typeof obs?.narrative === 'string' && obs.narrative.length >= 20) score += 20;
+  if (typeof obs?.narrative === 'string' && obs.narrative.length >= 50) score += 5;
+  if (typeof obs?.title === 'string' && obs.title.length >= 5 && obs.title.length <= 120) score += 15;
+  if (Array.isArray(obs?.concepts) && obs.concepts.length > 0) score += 15;
+  if (typeof obs?.importance === 'number' && obs.importance >= 1 && obs.importance <= 10) score += 10;
+  return clamp(score, 0, 100);
+}
+
+/**
+ * Score de calidad de un resumen de sesión.
+ * Adaptado de scoreSummary() de agentmemory.
+ *
+ * @param {object} summary
+ * @returns {number} en [0, 100]
+ */
+function scoreResumen(summary) {
+  let score = 0;
+  if (typeof summary?.title === 'string' && summary.title.length >= 5) score += 20;
+  if (typeof summary?.narrative === 'string' && summary.narrative.length >= 20) score += 25;
+  if (typeof summary?.narrative === 'string' && summary.narrative.length >= 100) score += 5;
+  if (Array.isArray(summary?.keyDecisions) && summary.keyDecisions.length > 0) score += 20;
+  if (Array.isArray(summary?.filesModified) && summary.filesModified.length > 0) score += 15;
+  if (Array.isArray(summary?.concepts) && summary.concepts.length > 0) score += 15;
+  return clamp(score, 0, 100);
+}
+
+/**
+ * Score de relevancia de un contexto inyectado.
+ * Adaptado de scoreContextRelevance() de agentmemory.
+ *
+ * @param {string} context - Texto del contexto.
+ * @param {string} project - Nombre del proyecto.
+ * @returns {number} en [0, 100]
+ */
+function scoreRelevanciaContexto(context, project) {
+  if (typeof context !== 'string') return 0;
+  let score = 0;
+  if (context.length > 0) score += 20;
+  if (project && context.toLowerCase().includes(String(project).toLowerCase())) score += 20;
+  if (context.includes('<')) score += 15;
+  const sectionCount = (context.match(/<\w+>/g) || []).length;
+  if (sectionCount >= 2) score += 15;
+  if (sectionCount >= 4) score += 10;
+  if (context.length >= 100) score += 10;
+  if (context.length >= 500) score += 10;
+  return clamp(score, 0, 100);
+}
+
+/**
+ * Score de calidad de un aprendizaje SWL extraído de una sesión.
+ * Específico de swl-ses (no en agentmemory).
+ *
+ * Distribución:
+ *   - título no vacío y descriptivo (≥ 10 chars):  20
+ *   - título empieza con fecha [YYYY-MM-DD]:       10
+ *   - cuerpo ≥ 100 chars:                          20
+ *   - cuerpo ≥ 300 chars:                          +10
+ *   - tipo identificado (decisión|patrón|...):     15
+ *   - menciona archivo o regla concreta:           15
+ *   - tiene "trigger" o "criterio de disparo":     10
+ *
+ * @param {object} aprendizaje { titulo, contenido, tipo? }
+ * @returns {number}
+ */
+function scoreAprendizaje(aprendizaje) {
+  let score = 0;
+  const titulo = String(aprendizaje?.titulo || '');
+  const contenido = String(aprendizaje?.contenido || '');
+
+  if (titulo.length >= 10) score += 20;
+  if (/^\[\d{4}-\d{2}-\d{2}\]/.test(titulo)) score += 10;
+  if (contenido.length >= 100) score += 20;
+  if (contenido.length >= 300) score += 10;
+
+  const tipos = ['decisión', 'patrón', 'anti-patrón', 'bug-fix', 'descubrimiento', 'gotcha'];
+  if (aprendizaje?.tipo && tipos.some(t => String(aprendizaje.tipo).includes(t))) {
+    score += 15;
+  }
+
+  if (/`[^`]+\.(js|ts|md|py|json|yaml)`|`[^`]+\/[^`]+`/.test(contenido)) score += 15;
+  if (/trigger|criterio de disparo|cuando .+ entonces/i.test(contenido)) score += 10;
+
+  return clamp(score, 0, 100);
+}
+
+/**
+ * Score de calidad de un instinto.
+ * Específico de swl-ses.
+ *
+ * Distribución:
+ *   - pattern presente:                          25
+ *   - pattern ≥ 30 chars:                        +10
+ *   - confidence ∈ [0, 1]:                       15
+ *   - status válido (active|degraded|archived):  10
+ *   - source_sessions o source_agents declarado: 15
+ *   - evidence_count ≥ 1:                        15
+ *   - last_validated_at presente:                10
+ *
+ * @param {object} instinto
+ * @returns {number}
+ */
+function scoreInstinto(instinto) {
+  let score = 0;
+  const pattern = String(instinto?.pattern || '');
+  if (pattern.length > 0) score += 25;
+  if (pattern.length >= 30) score += 10;
+  if (typeof instinto?.confidence === 'number' && instinto.confidence >= 0 && instinto.confidence <= 1) score += 15;
+  if (['active', 'degraded', 'archived'].includes(instinto?.status)) score += 10;
+  if ((Array.isArray(instinto?.source_sessions) && instinto.source_sessions.length > 0) ||
+      (Array.isArray(instinto?.source_agents) && instinto.source_agents.length > 0)) score += 15;
+  if (typeof instinto?.evidence_count === 'number' && instinto.evidence_count >= 1) score += 15;
+  if (instinto?.last_validated_at || instinto?.last_validated) score += 10;
+  return clamp(score, 0, 100);
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  scoreObservacion,
+  scoreResumen,
+  scoreRelevanciaContexto,
+  scoreAprendizaje,
+  scoreInstinto,
+};

package/scripts/lib/eval-schemas.js

@@ -0,0 +1,144 @@
+'use strict';
+
+/**
+ * eval-schemas.js — Schemas JSON-lite para evaluación de outputs SWL.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/src/eval/schemas.ts`. Adaptado a
+ * swl-ses: sin Zod (sería dep externa). Uso JSON Schema-lite con validador
+ * propio en `eval-validator.js`. Funciones puras zero-deps.
+ *
+ * Cada schema describe la estructura esperada de un output evaluable. El
+ * validador devuelve `{ valid, errors[] }` para que el caller decida.
+ *
+ * @module scripts/lib/eval-schemas
+ */
+
+// ── tipos enumerados ──────────────────────────────────────────────────────────
+
+const TIPOS_OBSERVACION = [
+  'file_read', 'file_write', 'file_edit',
+  'command_run', 'search', 'web_fetch',
+  'conversation', 'error', 'decision',
+  'discovery', 'subagent', 'notification',
+  'task', 'other',
+];
+
+const TIPOS_MEMORIA = [
+  'pattern', 'preference', 'architecture',
+  'bug', 'workflow', 'fact',
+];
+
+const TIPOS_RELACION = [
+  'supersedes', 'extends', 'derives', 'contradicts', 'related',
+];
+
+// ── schemas JSON-lite ─────────────────────────────────────────────────────────
+
+/**
+ * Schema para output de compresión de observación.
+ * Estructura compatible con `CompressOutputSchema` de agentmemory.
+ */
+const COMPRESS_OUTPUT_SCHEMA = {
+  type: 'object',
+  required: ['type', 'title', 'facts', 'narrative', 'concepts', 'files', 'importance'],
+  properties: {
+    type: { type: 'string', enum: TIPOS_OBSERVACION },
+    title: { type: 'string', minLength: 1, maxLength: 120 },
+    subtitle: { type: 'string' },
+    facts: { type: 'array', minItems: 1, items: { type: 'string' } },
+    narrative: { type: 'string', minLength: 10 },
+    concepts: { type: 'array', items: { type: 'string' } },
+    files: { type: 'array', items: { type: 'string' } },
+    importance: { type: 'integer', minimum: 1, maximum: 10 },
+  },
+};
+
+/**
+ * Schema para output de resumen de sesión.
+ */
+const SUMMARY_OUTPUT_SCHEMA = {
+  type: 'object',
+  required: ['title', 'narrative', 'keyDecisions', 'filesModified', 'concepts'],
+  properties: {
+    title: { type: 'string', minLength: 1 },
+    narrative: { type: 'string', minLength: 20 },
+    keyDecisions: { type: 'array', items: { type: 'string' } },
+    filesModified: { type: 'array', items: { type: 'string' } },
+    concepts: { type: 'array', items: { type: 'string' } },
+  },
+};
+
+/**
+ * Schema para input de búsqueda.
+ */
+const SEARCH_INPUT_SCHEMA = {
+  type: 'object',
+  required: ['query'],
+  properties: {
+    query: { type: 'string', minLength: 1 },
+    limit: { type: 'integer', minimum: 1 },
+  },
+};
+
+/**
+ * Schema para input de "remember" (guardar memoria).
+ */
+const REMEMBER_INPUT_SCHEMA = {
+  type: 'object',
+  required: ['content'],
+  properties: {
+    content: { type: 'string', minLength: 1 },
+    type: { type: 'string', enum: TIPOS_MEMORIA },
+    concepts: { type: 'array', items: { type: 'string' } },
+    files: { type: 'array', items: { type: 'string' } },
+  },
+};
+
+/**
+ * Schema para resultado de evaluación.
+ */
+const EVAL_RESULT_SCHEMA = {
+  type: 'object',
+  required: ['valid', 'qualityScore', 'latencyMs', 'functionId'],
+  properties: {
+    valid: { type: 'boolean' },
+    errors: { type: 'array', items: { type: 'string' } },
+    qualityScore: { type: 'number', minimum: 0, maximum: 100 },
+    latencyMs: { type: 'number', minimum: 0 },
+    functionId: { type: 'string', minLength: 1 },
+    metadata: { type: 'object' },
+  },
+};
+
+/**
+ * Schema para resultado de búsqueda en memoria SWL.
+ */
+const MEMORY_SEARCH_RESULT_SCHEMA = {
+  type: 'object',
+  required: ['id', 'tipo', 'titulo', 'fecha', 'relevancia'],
+  properties: {
+    id: { type: 'string', minLength: 1 },
+    tipo: { type: 'string', enum: ['aprendizaje', 'sesion', 'instinto'] },
+    titulo: { type: 'string' },
+    fecha: { type: 'string' },
+    relevancia: { type: 'number', minimum: 0, maximum: 1 },
+    combinedScore: { type: 'number', minimum: 0 },
+    confidence: { type: 'number', minimum: 0, maximum: 1 },
+  },
+};
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  // Schemas
+  COMPRESS_OUTPUT_SCHEMA,
+  SUMMARY_OUTPUT_SCHEMA,
+  SEARCH_INPUT_SCHEMA,
+  REMEMBER_INPUT_SCHEMA,
+  EVAL_RESULT_SCHEMA,
+  MEMORY_SEARCH_RESULT_SCHEMA,
+  // Enums
+  TIPOS_OBSERVACION,
+  TIPOS_MEMORIA,
+  TIPOS_RELACION,
+};

package/scripts/lib/eval-self-correct.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * eval-self-correct.js — Loop de auto-corrección para outputs invalidos.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/src/eval/self-correct.ts`.
+ * Adaptado a swl-ses: en lugar de un MemoryProvider que llama a un LLM, este
+ * módulo expone un loop genérico que:
+ *
+ *   1. Ejecuta una función productora.
+ *   2. Valida el output con un validador.
+ *   3. Si falla, re-ejecuta con el prompt ampliado con un sufijo más estricto.
+ *   4. Repite hasta `maxRetries` o éxito.
+ *
+ * El productor es agnóstico: puede ser una llamada a Claude (Skill o Bash),
+ * o cualquier función async que produzca un output basado en un prompt.
+ *
+ * No intenta automatizar llamadas LLM — el caller pasa la función concreta.
+ * Esto mantiene swl-ses zero-deps.
+ *
+ * @module scripts/lib/eval-self-correct
+ */
+
+const SUFIJO_ESTRICTO = `
+
+IMPORTANTE: Tu respuesta anterior fue inválida. Por favor asegúrate de que tu
+output siga ESTRICTAMENTE el formato requerido. Cada campo obligatorio debe
+estar presente con valores válidos.
+
+Errores detectados en el intento anterior:
+{{ERRORS}}
+`;
+
+/**
+ * Ejecuta un loop de auto-corrección sobre una función productora.
+ *
+ * @param {object} opts
+ * @param {function(string, string): Promise<string>} opts.productor - Recibe (sysPrompt, userPrompt) y devuelve output.
+ * @param {function(string): {valid: boolean, errors?: string[]}} opts.validador
+ * @param {string} opts.sysPrompt
+ * @param {string} opts.userPrompt
+ * @param {number} [opts.maxRetries=1] - Número máximo de reintentos tras fallo inicial.
+ * @returns {Promise<{ output: string, valid: boolean, retried: boolean, intentos: number, errors?: string[] }>}
+ */
+async function compresseConReintento(opts) {
+  const { productor, validador, sysPrompt, userPrompt, maxRetries = 1 } = opts;
+
+  if (typeof productor !== 'function') {
+    throw new Error('productor debe ser una función async (sysPrompt, userPrompt) => Promise<string>');
+  }
+  if (typeof validador !== 'function') {
+    throw new Error('validador debe ser una función (output) => {valid, errors?}');
+  }
+
+  // Intento 1
+  const primerOutput = await productor(sysPrompt, userPrompt);
+  const primerResultado = validador(primerOutput);
+  if (primerResultado.valid) {
+    return {
+      output: primerOutput,
+      valid: true,
+      retried: false,
+      intentos: 1,
+    };
+  }
+
+  let ultimoOutput = primerOutput;
+  let ultimosErrores = primerResultado.errors || [];
+
+  for (let i = 0; i < maxRetries; i++) {
+    const erroresFmt = ultimosErrores.length > 0
+      ? ultimosErrores.map(e => `  - ${e}`).join('\n')
+      : '  (sin detalle)';
+    const sysAmpliado = sysPrompt + SUFIJO_ESTRICTO.replace('{{ERRORS}}', erroresFmt);
+
+    const reintentoOutput = await productor(sysAmpliado, userPrompt);
+    const reintentoResultado = validador(reintentoOutput);
+
+    if (reintentoResultado.valid) {
+      return {
+        output: reintentoOutput,
+        valid: true,
+        retried: true,
+        intentos: i + 2,
+      };
+    }
+
+    ultimoOutput = reintentoOutput;
+    ultimosErrores = reintentoResultado.errors || [];
+  }
+
+  return {
+    output: ultimoOutput,
+    valid: false,
+    retried: maxRetries > 0,
+    intentos: maxRetries + 1,
+    errors: ultimosErrores,
+  };
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  compresseConReintento,
+  SUFIJO_ESTRICTO,
+};

package/scripts/lib/eval-validator.js

@@ -0,0 +1,185 @@
+'use strict';
+
+/**
+ * eval-validator.js — Validador JSON Schema-lite para outputs SWL.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/src/eval/validator.ts`. Adaptado a
+ * swl-ses: sin Zod (mantiene principio zero-deps). Implementación propia que
+ * cubre el subset de JSON Schema usado por `eval-schemas.js`:
+ *   - type: object | array | string | number | integer | boolean
+ *   - required, properties (object)
+ *   - items, minItems (array)
+ *   - minLength, maxLength (string)
+ *   - minimum, maximum (number)
+ *   - enum
+ *
+ * Funciones puras zero-deps. Backward compatible: schemas pueden agregar
+ * keywords nuevos en el futuro sin romper validaciones existentes.
+ *
+ * @module scripts/lib/eval-validator
+ */
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function obtenerTipo(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  return typeof value;
+}
+
+function esEntero(value) {
+  return typeof value === 'number' && Number.isInteger(value);
+}
+
+// ── validadores por tipo ──────────────────────────────────────────────────────
+
+function validarString(value, schema, errors, ruta) {
+  if (typeof value !== 'string') {
+    errors.push(`${ruta}: esperado string, recibido ${obtenerTipo(value)}`);
+    return;
+  }
+  if (typeof schema.minLength === 'number' && value.length < schema.minLength) {
+    errors.push(`${ruta}: longitud ${value.length} < minLength ${schema.minLength}`);
+  }
+  if (typeof schema.maxLength === 'number' && value.length > schema.maxLength) {
+    errors.push(`${ruta}: longitud ${value.length} > maxLength ${schema.maxLength}`);
+  }
+  if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+    errors.push(`${ruta}: valor "${value}" no en enum [${schema.enum.join(', ')}]`);
+  }
+}
+
+function validarNumber(value, schema, errors, ruta) {
+  if (schema.type === 'integer') {
+    if (!esEntero(value)) {
+      errors.push(`${ruta}: esperado integer, recibido ${obtenerTipo(value)}`);
+      return;
+    }
+  } else if (typeof value !== 'number') {
+    errors.push(`${ruta}: esperado number, recibido ${obtenerTipo(value)}`);
+    return;
+  }
+  if (typeof schema.minimum === 'number' && value < schema.minimum) {
+    errors.push(`${ruta}: valor ${value} < minimum ${schema.minimum}`);
+  }
+  if (typeof schema.maximum === 'number' && value > schema.maximum) {
+    errors.push(`${ruta}: valor ${value} > maximum ${schema.maximum}`);
+  }
+  if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+    errors.push(`${ruta}: valor ${value} no en enum`);
+  }
+}
+
+function validarBoolean(value, schema, errors, ruta) {
+  if (typeof value !== 'boolean') {
+    errors.push(`${ruta}: esperado boolean, recibido ${obtenerTipo(value)}`);
+  }
+}
+
+function validarArray(value, schema, errors, ruta) {
+  if (!Array.isArray(value)) {
+    errors.push(`${ruta}: esperado array, recibido ${obtenerTipo(value)}`);
+    return;
+  }
+  if (typeof schema.minItems === 'number' && value.length < schema.minItems) {
+    errors.push(`${ruta}: ${value.length} items < minItems ${schema.minItems}`);
+  }
+  if (typeof schema.maxItems === 'number' && value.length > schema.maxItems) {
+    errors.push(`${ruta}: ${value.length} items > maxItems ${schema.maxItems}`);
+  }
+  if (schema.items) {
+    for (let i = 0; i < value.length; i++) {
+      validarValor(value[i], schema.items, errors, `${ruta}[${i}]`);
+    }
+  }
+}
+
+function validarObject(value, schema, errors, ruta) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    errors.push(`${ruta}: esperado object, recibido ${obtenerTipo(value)}`);
+    return;
+  }
+  if (Array.isArray(schema.required)) {
+    for (const key of schema.required) {
+      if (!(key in value)) {
+        errors.push(`${ruta}: campo requerido faltante: "${key}"`);
+      }
+    }
+  }
+  if (schema.properties && typeof schema.properties === 'object') {
+    for (const [key, subSchema] of Object.entries(schema.properties)) {
+      if (key in value) {
+        validarValor(value[key], subSchema, errors, `${ruta}.${key}`);
+      }
+    }
+  }
+}
+
+function validarValor(value, schema, errors, ruta) {
+  if (!schema || typeof schema !== 'object') return;
+
+  switch (schema.type) {
+    case 'string':  validarString(value, schema, errors, ruta); break;
+    case 'number':
+    case 'integer': validarNumber(value, schema, errors, ruta); break;
+    case 'boolean': validarBoolean(value, schema, errors, ruta); break;
+    case 'array':   validarArray(value, schema, errors, ruta); break;
+    case 'object':  validarObject(value, schema, errors, ruta); break;
+    default:
+      // Sin type explícito: validar enum si aplica, sino aceptar
+      if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+        errors.push(`${ruta}: valor no en enum`);
+      }
+  }
+}
+
+// ── API pública ───────────────────────────────────────────────────────────────
+
+/**
+ * Valida un valor contra un schema JSON-lite.
+ * @param {*} value
+ * @param {object} schema
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+function validar(value, schema) {
+  const errors = [];
+  validarValor(value, schema, errors, '$');
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Valida input contra schema, devolviendo formato compatible con eval results.
+ * @param {object} schema
+ * @param {*} data
+ * @param {string} functionId
+ * @returns {object} { valid, data?, result? }
+ */
+function validarInput(schema, data, functionId) {
+  const result = validar(data, schema);
+  if (result.valid) {
+    return { valid: true, data };
+  }
+  return {
+    valid: false,
+    result: {
+      valid: false,
+      errors: result.errors,
+      qualityScore: 0,
+      latencyMs: 0,
+      functionId: functionId || 'unknown',
+    },
+  };
+}
+
+/**
+ * Conveniencia: valida output (alias de validarInput).
+ */
+const validarOutput = validarInput;
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  validar,
+  validarInput,
+  validarOutput,
+};