agentic-kdd 3.0.3 → 3.1.1

package/bin/akdd.js

@@ -55,6 +55,13 @@ const HELP = `
     akdd adr               Ingest ADRs from docs/adr/
     akdd knowledge         Ingest gotchas/conventions from docs/
 
+  Memory Governance (v3.2):
+    akdd cure              Run MemCurator — TTL, dedup, conflicts, scores
+    akdd cure report       Preview what curation would do (no changes)
+    akdd llms              Generate llms.txt + knowledge-graph.json
+    akdd benchmarks        LongMemEval + Token Reduction + Memory Quality scores
+    akdd causal-prune      Prune causal graph to prevent context collapse
+
   Metrics & Observability:
     akdd metrics           Project KPIs — success rate, rework, autonomy score
     akdd metrics trend     Show trend of last 10 cycles
@@ -64,7 +71,8 @@ const HELP = `
 
   Collaborative Mode (Legion):
     akdd collab init       Activate collaborative mode — creates shared DB automatically
-    akdd collab join <url> <token>   Join an existing team's shared memory
+    akdd collab invite     Generate a 6-char invite code for a team member (24h, one-use)
+    akdd collab join <code>  Join the team with an invite code (e.g. LUMO-X7K2P4)
     akdd collab push       Push your learnings to the team
     akdd collab pull       Pull team's latest learnings
     akdd collab status     Check collaborative sync status
@@ -219,17 +227,47 @@ switch (command) {
     break;
   }
 
+
+  // ── v3.2: MemCurator ───────────────────────────────────────────────────────
+  case 'cure': {
+    const sub = arg1 || 'run';
+    runModule('mem-curator.cjs', sub);
+    break;
+  }
+
+  // ── v3.2: llms.txt generator ───────────────────────────────────────────────
+  case 'llms': {
+    const sub = arg1 || 'all';
+    runModule('llms-generator.cjs', sub);
+    break;
+  }
+
+  // ── v3.2: Report benchmarks ────────────────────────────────────────────────
+  case 'benchmarks': {
+    runModule('metrics.cjs', 'benchmarks');
+    break;
+  }
+
+  // ── v3.2: Causal prune ─────────────────────────────────────────────────────
+  case 'causal-prune': {
+    runModule('causal-edges.cjs', 'prune');
+    break;
+  }
+
   // ── v3.0: Collaborative Mode (Legion) ────────────────────────────────
   case 'collab': {
     const sub = arg1 || 'status';
     if (sub === 'init') {
       runModule('collab-manager.cjs', 'init');
+    } else if (sub === 'invite') {
+      runModule('collab-manager.cjs', 'invite');
     } else if (sub === 'join') {
-      if (!arg2 || !args[3]) {
-        console.log('\n  Uso: akdd collab join <url> <token>\n');
+      if (!arg2) {
+        console.log('\n  Uso: akdd collab join <código>\n');
+        console.log('  El código lo genera el jefe con: akdd collab invite\n');
         break;
       }
-      runModule('collab-manager.cjs', 'join', `"${arg2}" "${args[3]}"`);
+      runModule('collab-manager.cjs', 'join', `"${arg2}"`);
     } else if (sub === 'push') {
       runModule('collab-manager.cjs', 'push');
     } else if (sub === 'pull') {

package/collab-manager.cjs

@@ -153,13 +153,43 @@ async function collabInit(projectRoot) {
 
 // ─── JOIN — PARA EL DEV QUE SE UNE AL EQUIPO ─────────────────────────────────
 
-async function collabJoin(projectRoot, url, token) {
+async function collabJoin(projectRoot, urlOrCode, token) {
   console.log('\n[COLLAB] Uniéndose al equipo...\n');
 
+  let finalUrl = urlOrCode;
+  let finalToken = token;
+
+  // Detectar si es un código de invitación (formato: PREFIX-XXXXXX)
+  const isInviteCode = !urlOrCode?.startsWith('libsql://') && !urlOrCode?.startsWith('http');
+
+  if (isInviteCode) {
+    console.log(`[COLLAB] Resolviendo código: ${urlOrCode}`);
+    try {
+      const response = await fetch(`${PROVISIONER_URL}/join`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ code: urlOrCode }),
+      });
+      const result = await response.json();
+
+      if (!result.ok) {
+        console.error(`[COLLAB] ❌ ${result.error}`);
+        process.exit(1);
+      }
+
+      finalUrl   = result.url;
+      finalToken = result.token;
+      console.log(`[COLLAB] ✅ Código válido. Conectando a: ${result.db}`);
+    } catch (e) {
+      console.error('[COLLAB] Error resolviendo código:', e.message);
+      process.exit(1);
+    }
+  }
+
   const config = {
     enabled: true,
-    url,
-    token,
+    url: finalUrl,
+    token: finalToken,
     member_id: os.userInfo().username,
     sync_on_cycle_end: true,
     last_sync: null,
@@ -176,6 +206,48 @@ async function collabJoin(projectRoot, url, token) {
   console.log('[COLLAB] ✅ Listo. Ya tienes toda la memoria del equipo.\n');
 }
 
+// ─── INVITE ───────────────────────────────────────────────────────────────────
+
+async function collabInvite(projectRoot) {
+  const config = loadConfig(projectRoot);
+  if (!config?.enabled) {
+    console.log('\n[COLLAB] Modo colaborativo no activado. Correr: akdd collab init\n');
+    return;
+  }
+
+  const projectId = config.project_id || getProjectId(projectRoot);
+  console.log('\n[COLLAB] Generando código de invitación...');
+
+  let result;
+  try {
+    const response = await fetch(`${PROVISIONER_URL}/invite`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ projectId }),
+    });
+    result = await response.json();
+  } catch (e) {
+    console.error('[COLLAB] Error:', e.message);
+    return;
+  }
+
+  if (!result.ok) {
+    console.error('[COLLAB] Error generando código:', result.error);
+    return;
+  }
+
+  console.log('\n' + '═'.repeat(50));
+  console.log('  🔑 Código de invitación Agentic KDD');
+  console.log('═'.repeat(50));
+  console.log(`\n  Código:   ${result.code}`);
+  console.log(`  Expira:   ${result.expires_in}`);
+  console.log(`  Un solo uso — expira al usarse o en 24h`);
+  console.log('\n  Comparte este código por Slack/WhatsApp.');
+  console.log('  El miembro del equipo corre:');
+  console.log(`\n  akdd collab join ${result.code}\n`);
+  console.log('═'.repeat(50) + '\n');
+}
+
 // ─── SYNC UP (local → Turso) ──────────────────────────────────────────────────
 
 async function syncUp(projectRoot) {
@@ -368,9 +440,13 @@ if (require.main === module) {
     case 'init':
       collabInit(projectRoot).catch(console.error);
       break;
+    case 'invite':
+      collabInvite(projectRoot).catch(console.error);
+      break;
     case 'join':
-      if (!arg1 || !arg2) {
-        console.error('Uso: collab-manager.cjs join <url> <token>');
+      if (!arg1) {
+        console.error('Uso: collab-manager.cjs join <código>');
+        console.error('  o: collab-manager.cjs join <url> <token>');
         process.exit(1);
       }
       collabJoin(projectRoot, arg1, arg2).catch(console.error);
@@ -396,6 +472,7 @@ if (require.main === module) {
 module.exports = {
   collabInit,
   collabJoin,
+  collabInvite,
   syncUp,
   syncDown,
   status,

package/embeddings-v2.cjs

@@ -0,0 +1,320 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Agentic KDD — Embeddings Engine v2.0
+ *
+ * Modelo DEFAULT: jina-embeddings-v2-base-code (Jina AI)
+ *   - 137M parámetros entrenados en CODE + texto natural (bimodal NL-PL)
+ *   - 768 dimensiones vs 384 de all-MiniLM
+ *   - Entiende relaciones lógicas de tipos, AST, control de flujo
+ *   - ~500MB instalado, 100% offline
+ *
+ * Fallback automático si jina no está: all-MiniLM-L6-v2 (384 dims, ~23MB)
+ *
+ * Gap cerrado: all-MiniLM-L6-v2 fue entrenado en NL natural, no en código.
+ * UniXcoder/jina mapean correctamente la semántica formal de lenguajes de programación.
+ *
+ * Uso:
+ *   node embeddings.cjs embed "function calculateTotal(price, qty)"
+ *   node embeddings.cjs status
+ *   node embeddings.cjs install-jina
+ *   node embeddings.cjs install-mini   (fallback ligero)
+ */
+
+const path = require('path');
+const fs   = require('fs');
+const { execSync } = require('child_process');
+
+// ─── MODELOS ──────────────────────────────────────────────────────────────────
+
+const MODELS = {
+  // Modelo primario: bimodal NL-PL, específico para código
+  JINA_CODE: {
+    id:   'jinaai/jina-embeddings-v2-base-code',
+    name: 'jina-embeddings-v2-base-code',
+    dims: 768,
+    size: '~500MB',
+    type: 'bimodal_nlpl',
+    description: 'Entrenado en código + texto. Entiende relaciones de tipos, AST, control de flujo.',
+  },
+  // Fallback: modelo NL general, ligero
+  MINI_LM: {
+    id:   'Xenova/all-MiniLM-L6-v2',
+    name: 'all-MiniLM-L6-v2',
+    dims: 384,
+    size: '~23MB',
+    type: 'natural_language',
+    description: 'Modelo NL general. Fallback cuando jina no está instalado.',
+  },
+};
+
+// ─── ESTADO INTERNO ───────────────────────────────────────────────────────────
+
+let _pipeline = null;
+let _activeModel = null;
+let _available = null;
+
+// ─── DETECCIÓN DE MODELO DISPONIBLE ──────────────────────────────────────────
+
+function detectAvailableModel(projectRoot) {
+  if (_available !== null) return _available;
+
+  // 1. Verificar si jina está en cache local del proyecto
+  const localCache = path.join(projectRoot || process.cwd(), '.agentic', '.model_cache');
+  if (fs.existsSync(localCache)) {
+    const jinaDir = path.join(localCache, 'models--jinaai--jina-embeddings-v2-base-code');
+    if (fs.existsSync(jinaDir)) {
+      _available = 'jina';
+      return 'jina';
+    }
+  }
+
+  // 2. Verificar cache global de HuggingFace
+  const hfCache = path.join(require('os').homedir(), '.cache', 'huggingface', 'hub');
+  if (fs.existsSync(hfCache)) {
+    const jinaGlobal = path.join(hfCache, 'models--jinaai--jina-embeddings-v2-base-code');
+    if (fs.existsSync(jinaGlobal)) {
+      _available = 'jina';
+      return 'jina';
+    }
+  }
+
+  // 3. Verificar si @xenova/transformers está instalado
+  try {
+    require.resolve('@xenova/transformers');
+    // MiniLM siempre descargable si transformers está
+    _available = 'mini';
+    return 'mini';
+  } catch {}
+
+  _available = false;
+  return false;
+}
+
+// ─── CARGAR PIPELINE ─────────────────────────────────────────────────────────
+
+async function getPipeline(projectRoot) {
+  if (_pipeline) return { pipeline: _pipeline, model: _activeModel };
+
+  const available = detectAvailableModel(projectRoot || process.cwd());
+
+  if (!available) {
+    return { pipeline: null, model: null };
+  }
+
+  try {
+    process.env.TRANSFORMERS_VERBOSITY = 'error';
+    const { pipeline, env } = require('@xenova/transformers');
+
+    // Usar cache local del proyecto si existe
+    const localCache = path.join(projectRoot || process.cwd(), '.agentic', '.model_cache');
+    if (fs.existsSync(localCache)) env.cacheDir = localCache;
+
+    const model = available === 'jina' ? MODELS.JINA_CODE : MODELS.MINI_LM;
+    _activeModel = model;
+
+    _pipeline = await pipeline('feature-extraction', model.id, { quantized: true });
+
+    return { pipeline: _pipeline, model };
+  } catch (e) {
+    _available = false;
+    return { pipeline: null, model: null };
+  }
+}
+
+// ─── GENERAR EMBEDDING ────────────────────────────────────────────────────────
+
+/**
+ * Genera embedding para código o texto.
+ * Retorna array de dims (768 con jina, 384 con mini) o null si no disponible.
+ */
+async function embed(text, projectRoot) {
+  const { pipeline: pipe } = await getPipeline(projectRoot);
+  if (!pipe) return null;
+  try {
+    const output = await pipe(text, { pooling: 'mean', normalize: true });
+    return Array.from(output.data);
+  } catch { return null; }
+}
+
+// ─── SIMILITUD COSENO ────────────────────────────────────────────────────────
+
+function cosineSim(a, b) {
+  if (!a || !b || a.length !== b.length) return 0;
+  let dot = 0, normA = 0, normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot   += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  return denom === 0 ? 0 : dot / denom;
+}
+
+// ─── BÚSQUEDA SEMÁNTICA ───────────────────────────────────────────────────────
+
+/**
+ * Búsqueda semántica sobre un array de items.
+ * @param {string} query - consulta en lenguaje natural o código
+ * @param {Array} items - [{id, texto, embedding}]
+ * @param {number} topK
+ */
+async function semanticSearch(query, items, topK = 10, projectRoot) {
+  const queryEmbed = await embed(query, projectRoot);
+  if (!queryEmbed) return items.slice(0, topK); // fallback sin embeddings
+
+  const scored = items
+    .filter(item => item.embedding && Array.isArray(item.embedding))
+    .map(item => ({
+      ...item,
+      score: cosineSim(queryEmbed, item.embedding),
+    }))
+    .sort((a, b) => b.score - a.score)
+    .slice(0, topK);
+
+  return scored;
+}
+
+// ─── STATUS ───────────────────────────────────────────────────────────────────
+
+async function getStatus(projectRoot) {
+  const available = detectAvailableModel(projectRoot || process.cwd());
+  const model = available === 'jina' ? MODELS.JINA_CODE : available === 'mini' ? MODELS.MINI_LM : null;
+
+  return {
+    available: !!available,
+    active_model: model?.name || 'none',
+    model_type: model?.type || 'none',
+    dims: model?.dims || 0,
+    size: model?.size || 'N/A',
+    description: model?.description || 'Sin modelo de embeddings instalado',
+    recommended: 'jina-embeddings-v2-base-code',
+    install_command: available === 'jina' ? 'Ya instalado ✅' : 'akdd jina-install',
+    gap_status: available === 'jina'
+      ? '✅ Modelo bimodal NL-PL activo — semántica de código precisa'
+      : available === 'mini'
+        ? '⚠️  Usando all-MiniLM-L6-v2 — no optimizado para código. Ejecutar: akdd jina-install'
+        : '❌ Sin embeddings — búsqueda semántica desactivada. Ejecutar: akdd embed-install',
+  };
+}
+
+// ─── INSTALACIÓN ─────────────────────────────────────────────────────────────
+
+/**
+ * Instalar jina-embeddings-v2-base-code (modelo primario recomendado).
+ * ~500MB. Se guarda en .agentic/.model_cache para uso offline.
+ */
+async function installJina(projectRoot) {
+  projectRoot = projectRoot || process.cwd();
+  console.log('\n[EMBEDDINGS] Instalando jina-embeddings-v2-base-code...');
+  console.log('[EMBEDDINGS] Tamaño: ~500MB. Puede tomar 5-10 minutos.');
+  console.log('[EMBEDDINGS] Modelo bimodal NL-PL — entrenado específicamente en código.\n');
+
+  // Verificar que @xenova/transformers está instalado
+  try {
+    require.resolve('@xenova/transformers');
+  } catch {
+    console.log('[EMBEDDINGS] Instalando @xenova/transformers primero...');
+    execSync('npm install @xenova/transformers --save-dev', {
+      stdio: 'inherit',
+      cwd: projectRoot,
+    });
+  }
+
+  // Descargar el modelo
+  try {
+    process.env.TRANSFORMERS_VERBOSITY = 'info';
+    const { pipeline, env } = require('@xenova/transformers');
+    const localCache = path.join(projectRoot, '.agentic', '.model_cache');
+    fs.mkdirSync(localCache, { recursive: true });
+    env.cacheDir = localCache;
+
+    console.log('[EMBEDDINGS] Descargando modelo...');
+    const pipe = await pipeline('feature-extraction', MODELS.JINA_CODE.id, { quantized: true });
+
+    // Test
+    const testEmbed = await pipe('function test() { return 1; }', { pooling: 'mean', normalize: true });
+    if (testEmbed && testEmbed.data.length > 0) {
+      console.log(`\n[EMBEDDINGS] ✅ jina-embeddings-v2-base-code instalado.`);
+      console.log(`[EMBEDDINGS] Dimensiones: ${testEmbed.data.length}`);
+      console.log(`[EMBEDDINGS] Búsqueda semántica de código ahora es precisa.\n`);
+      _available = 'jina';
+      _pipeline = pipe;
+    }
+  } catch (e) {
+    console.error('[EMBEDDINGS] Error instalando jina:', e.message);
+    console.log('[EMBEDDINGS] Alternativa: akdd embed-install (all-MiniLM-L6-v2, 23MB)\n');
+  }
+}
+
+/**
+ * Instalar all-MiniLM-L6-v2 (fallback ligero, ~23MB).
+ */
+async function installMini(projectRoot) {
+  projectRoot = projectRoot || process.cwd();
+  console.log('\n[EMBEDDINGS] Instalando all-MiniLM-L6-v2 (modelo ligero, 23MB)...');
+  console.log('[EMBEDDINGS] Nota: este modelo es para texto natural, no optimizado para código.');
+  console.log('[EMBEDDINGS] Para precisión máxima en código: akdd jina-install\n');
+
+  try {
+    require.resolve('@xenova/transformers');
+  } catch {
+    execSync('npm install @xenova/transformers --save-dev', { stdio: 'inherit', cwd: projectRoot });
+  }
+
+  try {
+    const { pipeline, env } = require('@xenova/transformers');
+    const localCache = path.join(projectRoot, '.agentic', '.model_cache');
+    fs.mkdirSync(localCache, { recursive: true });
+    env.cacheDir = localCache;
+
+    const pipe = await pipeline('feature-extraction', MODELS.MINI_LM.id, { quantized: true });
+    console.log('\n[EMBEDDINGS] ✅ all-MiniLM-L6-v2 instalado como fallback.\n');
+    _available = 'mini';
+    _pipeline = pipe;
+  } catch (e) {
+    console.error('[EMBEDDINGS] Error:', e.message);
+  }
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+
+if (require.main === module) {
+  const [,, cmd, ...args] = process.argv;
+  const projectRoot = process.cwd();
+
+  switch (cmd) {
+    case 'embed':
+      if (!args[0]) { console.error('Uso: embeddings.cjs embed "<texto>"'); break; }
+      embed(args.join(' '), projectRoot).then(v => {
+        if (!v) console.log('Sin embeddings disponibles. Ejecutar: akdd jina-install');
+        else console.log(`Vector [${v.length} dims]: [${v.slice(0,4).map(x=>x.toFixed(4)).join(', ')}...]`);
+      });
+      break;
+
+    case 'status':
+      getStatus(projectRoot).then(s => {
+        console.log('\n=== Embeddings Status ===');
+        console.log(`Modelo activo: ${s.active_model}`);
+        console.log(`Tipo:          ${s.model_type}`);
+        console.log(`Dimensiones:   ${s.dims}`);
+        console.log(`Gap:           ${s.gap_status}`);
+        console.log(`Instalar:      ${s.install_command}\n`);
+      });
+      break;
+
+    case 'install-jina':
+      installJina(projectRoot).catch(console.error);
+      break;
+
+    case 'install-mini':
+      installMini(projectRoot).catch(console.error);
+      break;
+
+    default:
+      console.log('Uso: embeddings.cjs [embed <text> | status | install-jina | install-mini]');
+  }
+}
+
+module.exports = { embed, cosineSim, semanticSearch, getStatus, installJina, installMini, detectAvailableModel, MODELS };