@saulwade/swl-ses 1.0.0

package/hooks/lib/token-estimator.js

@@ -0,0 +1,420 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Módulo: token-estimator.js
+ * Librería compartida para hooks de tracking de costos.
+ *
+ * Proporciona heurísticas de estimación de tokens por herramienta y cálculo
+ * de costo en USD basado en precios de Anthropic a marzo 2026.
+ *
+ * No se conecta a ningún servicio externo. Todos los cálculos son deterministas
+ * a partir del nombre de la herramienta y la etiqueta del modelo.
+ *
+ * Uso:
+ *   const { estimarToolCall, formatearCosto } = require('./lib/token-estimator');
+ *   const { tokensEstimados, costoEstimado } = estimarToolCall('Bash', 'sonnet');
+ *   console.log(formatearCosto(costoEstimado)); // "$0.00"
+ */
+
+// ---------------------------------------------------------------------------
+// Heurísticas de tokens por herramienta
+// ---------------------------------------------------------------------------
+
+/**
+ * Tokens estimados de entrada por invocación de herramienta.
+ * Valores basados en uso típico (prompt + parámetros + respuesta promedio).
+ * Las herramientas de subagentes tienen valores más altos porque generan
+ * conversaciones completas anidadas.
+ *
+ * @type {Object.<string, number>}
+ */
+const TOKENS_POR_HERRAMIENTA = {
+  Bash:         500,
+  Read:         300,   // promedio; varía según tamaño del archivo
+  Write:        400,
+  Edit:         200,
+  Grep:         250,
+  Glob:         150,
+  Agent:       1500,   // subagentes consumen conversaciones completas
+  Task:        1500,   // alias de Agent en algunos runtimes
+  NotebookEdit: 300,
+  WebSearch:    600,
+  WebFetch:     800,
+  Skill:        100,
+  // Herramientas de Claude Code menos frecuentes
+  MultiEdit:    350,
+  TodoRead:      80,
+  TodoWrite:    120,
+};
+
+/** Tokens por defecto para herramientas no listadas. */
+const TOKENS_DEFAULT = 300;
+
+// ---------------------------------------------------------------------------
+// Precios por modelo
+// ---------------------------------------------------------------------------
+
+/**
+ * Costo en USD por 1,000,000 tokens de entrada, por familia de modelo.
+ * Precios de Anthropic a marzo 2026.
+ *
+ * @type {Object.<string, number>}
+ */
+const COSTO_POR_MILLON = {
+  opus:   15.0,
+  sonnet:  3.0,
+  haiku:   0.25,
+};
+
+/** Costo por millón de tokens para modelos no reconocidos (sonnet como fallback). */
+const COSTO_DEFAULT_POR_MILLON = 3.0;
+
+// ---------------------------------------------------------------------------
+// Pricing canónico por modelo — precios oficiales Anthropic/OpenAI (abril 2026)
+// Adoptado de Hermes Agent (agent/usage_pricing.py)
+// ---------------------------------------------------------------------------
+
+/**
+ * Tabla de precios canónicos por modelo con desglose completo:
+ * input, output, cache_read, cache_write.
+ *
+ * Fuente: documentación oficial de Anthropic y OpenAI (snapshot abril 2026).
+ * Tabla actualizada 2026-04-19 desde mission-control-main/src/lib/token-pricing.ts (MIT)
+ * para agregar aliases anthropic/* y modelos 4-5.
+ *
+ * @type {Object.<string, { input: number, output: number, cacheRead: number, cacheWrite: number }>}
+ */
+const PRICING_CANONICO = {
+  // Anthropic — precios por 1M tokens (nombres canónicos)
+  'claude-opus-4-7':                        { input: 15.00, output: 75.00, cacheRead: 1.50,  cacheWrite: 18.75 },
+  'claude-opus-4-6':                        { input: 15.00, output: 75.00, cacheRead: 1.50,  cacheWrite: 18.75 },
+  'claude-opus-4-5':                        { input: 15.00, output: 75.00, cacheRead: 1.50,  cacheWrite: 18.75 },
+  'claude-sonnet-4-6':                      { input:  3.00, output: 15.00, cacheRead: 0.30,  cacheWrite:  3.75 },
+  'claude-sonnet-4-5':                      { input:  3.00, output: 15.00, cacheRead: 0.30,  cacheWrite:  3.75 },
+  'claude-sonnet-4':                        { input:  3.00, output: 15.00, cacheRead: 0.30,  cacheWrite:  3.75 },
+  'claude-sonnet-4-20250514':               { input:  3.00, output: 15.00, cacheRead: 0.30,  cacheWrite:  3.75 },
+  'claude-haiku-4-5':                       { input:  0.80, output:  4.00, cacheRead: 0.08,  cacheWrite:  1.00 },
+  'claude-3-5-haiku':                       { input:  0.80, output:  4.00, cacheRead: 0.08,  cacheWrite:  1.00 },
+  // Aliases con prefijo anthropic/ (compatibilidad con mission-control y gateways)
+  'anthropic/claude-opus-4-7':              { input: 15.00, output: 75.00, cacheRead: 1.50,  cacheWrite: 18.75 },
+  'anthropic/claude-opus-4-6':              { input: 15.00, output: 75.00, cacheRead: 1.50,  cacheWrite: 18.75 },
+  'anthropic/claude-opus-4-5':              { input: 15.00, output: 75.00, cacheRead: 1.50,  cacheWrite: 18.75 },
+  'anthropic/claude-sonnet-4-6':            { input:  3.00, output: 15.00, cacheRead: 0.30,  cacheWrite:  3.75 },
+  'anthropic/claude-sonnet-4-5':            { input:  3.00, output: 15.00, cacheRead: 0.30,  cacheWrite:  3.75 },
+  'anthropic/claude-sonnet-4-20250514':     { input:  3.00, output: 15.00, cacheRead: 0.30,  cacheWrite:  3.75 },
+  'anthropic/claude-haiku-4-5':             { input:  0.80, output:  4.00, cacheRead: 0.08,  cacheWrite:  1.00 },
+  'anthropic/claude-3-5-haiku-latest':      { input:  0.80, output:  4.00, cacheRead: 0.08,  cacheWrite:  1.00 },
+  // Alias cortos — apuntan al modelo actual por defecto de cada familia
+  'opus':                                   { input: 15.00, output: 75.00, cacheRead: 1.50,  cacheWrite: 18.75 },
+  'sonnet':                                 { input:  3.00, output: 15.00, cacheRead: 0.30,  cacheWrite:  3.75 },
+  'haiku':                                  { input:  0.80, output:  4.00, cacheRead: 0.08,  cacheWrite:  1.00 },
+  // OpenAI — referencia para multi-proveedor
+  'gpt-4o':                                 { input:  2.50, output: 10.00, cacheRead: 1.25,  cacheWrite:  2.50 },
+  'gpt-4o-mini':                            { input:  0.15, output:  0.60, cacheRead: 0.075, cacheWrite:  0.15 },
+  'gpt-4.1':                                { input:  2.00, output:  8.00, cacheRead: 0.50,  cacheWrite:  2.00 },
+  'gpt-4.1-mini':                           { input:  0.40, output:  1.60, cacheRead: 0.10,  cacheWrite:  0.40 },
+};
+
+/**
+ * Calcula el costo real de una invocación con desglose canónico.
+ *
+ * A diferencia de estimarToolCall() que usa heurísticas, esta función
+ * acepta conteos reales de tokens (input, output, cache) y calcula
+ * el costo exacto basado en la tabla de precios oficial.
+ *
+ * @param {object} uso
+ * @param {number} uso.inputTokens       - Tokens de entrada (sin caché)
+ * @param {number} uso.outputTokens      - Tokens de salida
+ * @param {number} [uso.cacheReadTokens=0]  - Tokens leídos de caché
+ * @param {number} [uso.cacheWriteTokens=0] - Tokens escritos a caché
+ * @param {string} modelo - Identificador del modelo o etiqueta corta
+ * @returns {{ costoUsd: number, desglose: object, ahorroCache: number, modelo: string }}
+ */
+function calcularCostoCanonicoTokens(uso, modelo) {
+  const {
+    inputTokens = 0,
+    outputTokens = 0,
+    cacheReadTokens = 0,
+    cacheWriteTokens = 0,
+  } = uso;
+
+  // Buscar pricing: primero exacto, luego por familia
+  let pricing = PRICING_CANONICO[modelo];
+  if (!pricing) {
+    const familia = inferirFamiliaModelo(modelo);
+    pricing = PRICING_CANONICO[familia] || PRICING_CANONICO['sonnet'];
+  }
+
+  const costoInput      = (inputTokens / 1_000_000) * pricing.input;
+  const costoOutput     = (outputTokens / 1_000_000) * pricing.output;
+  const costoCacheRead  = (cacheReadTokens / 1_000_000) * pricing.cacheRead;
+  const costoCacheWrite = (cacheWriteTokens / 1_000_000) * pricing.cacheWrite;
+  const costoTotal      = costoInput + costoOutput + costoCacheRead + costoCacheWrite;
+
+  // Ahorro por caché: cuánto habría costado si no hubiera caché
+  const costoSinCache = ((inputTokens + cacheReadTokens) / 1_000_000) * pricing.input;
+  const costoConCache = costoInput + costoCacheRead;
+  const ahorroCache   = costoSinCache - costoConCache;
+
+  return {
+    costoUsd: Math.round(costoTotal * 1_000_000) / 1_000_000,
+    desglose: {
+      input: Math.round(costoInput * 1_000_000) / 1_000_000,
+      output: Math.round(costoOutput * 1_000_000) / 1_000_000,
+      cacheRead: Math.round(costoCacheRead * 1_000_000) / 1_000_000,
+      cacheWrite: Math.round(costoCacheWrite * 1_000_000) / 1_000_000,
+    },
+    ahorroCache: Math.round(ahorroCache * 1_000_000) / 1_000_000,
+    modelo,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Funciones exportadas
+// ---------------------------------------------------------------------------
+
+/**
+ * Infiere la familia del modelo a partir del identificador completo.
+ *
+ * @param {string} modelId - Identificador completo, ej: "claude-sonnet-4-5-20251101"
+ * @returns {string} Etiqueta corta: 'opus' | 'sonnet' | 'haiku'
+ */
+function inferirFamiliaModelo(modelId) {
+  const id = String(modelId || '').toLowerCase();
+  if (id.includes('opus'))   return 'opus';
+  if (id.includes('haiku'))  return 'haiku';
+  if (id.includes('sonnet')) return 'sonnet';
+  return 'sonnet'; // fallback conservador
+}
+
+/**
+ * Estima el consumo de tokens y el costo en USD para una invocación de herramienta.
+ *
+ * Los valores son estimaciones heurísticas, no mediciones exactas. El objetivo
+ * es dar una orden de magnitud útil para presupuesto y alertas, no facturación exacta.
+ *
+ * @param {string} toolName   - Nombre de la herramienta invocada (ej: "Bash", "Read").
+ * @param {string} modelLabel - Etiqueta corta del modelo ('opus'|'sonnet'|'haiku')
+ *                              o identificador completo del modelo.
+ * @returns {{ tokensEstimados: number, costoEstimado: number }}
+ */
+function estimarToolCall(toolName, modelLabel) {
+  const tokens = TOKENS_POR_HERRAMIENTA[toolName] ?? TOKENS_DEFAULT;
+
+  // Aceptar tanto etiqueta corta ('opus') como model_id completo
+  const familia = COSTO_POR_MILLON[modelLabel] !== undefined
+    ? modelLabel
+    : inferirFamiliaModelo(modelLabel);
+
+  const costoPorMillon = COSTO_POR_MILLON[familia] ?? COSTO_DEFAULT_POR_MILLON;
+
+  // Costo = tokens / 1_000_000 * costo_por_millon
+  const costoEstimado = (tokens / 1_000_000) * costoPorMillon;
+
+  return { tokensEstimados: tokens, costoEstimado };
+}
+
+/**
+ * Formatea un costo en USD con dos decimales para mostrar en reportes.
+ *
+ * @param {number} totalUsd - Costo total en dólares.
+ * @returns {string} Ejemplo: "$1.87" o "$0.03"
+ */
+function formatearCosto(totalUsd) {
+  const valor = typeof totalUsd === 'number' && isFinite(totalUsd) ? totalUsd : 0;
+  return `$${valor.toFixed(2)}`;
+}
+
+/**
+ * Formatea un número grande con separadores de miles para lectura humana.
+ *
+ * @param {number} n - Número a formatear.
+ * @returns {string} Ejemplo: "125,000"
+ */
+function formatearNumero(n) {
+  return Math.round(n).toLocaleString('en-US');
+}
+
+/**
+ * Devuelve los tokens estimados por defecto para herramientas no registradas.
+ * Útil para que el hook de tracking pueda mostrar el valor de fallback.
+ *
+ * @returns {number}
+ */
+function tokensDefault() {
+  return TOKENS_DEFAULT;
+}
+
+// ---------------------------------------------------------------------------
+// Tracking acumulativo por reintentos (patrón reask/retry)
+// ---------------------------------------------------------------------------
+
+/**
+ * Crea un acumulador de uso de tokens para rastrear consumo total
+ * incluyendo reintentos. Inspirado en el patrón update_total_usage
+ * de instructor (structured outputs).
+ *
+ * Uso:
+ *   const tracker = crearTrackerReintentos('sonnet');
+ *   tracker.registrarIntento({ tokensInput: 500, tokensOutput: 200 });
+ *   tracker.registrarIntento({ tokensInput: 600, tokensOutput: 150 }); // reask
+ *   const resumen = tracker.resumen();
+ *   // { intentos: 2, tokensInputTotal: 1100, tokensOutputTotal: 350,
+ *   //   costoTotal: 0.0048, exitoso: false, desperdicio: 0.0015 }
+ *
+ * @param {string} modelLabel - Etiqueta del modelo ('opus'|'sonnet'|'haiku')
+ * @returns {object} Tracker con métodos registrarIntento, marcarExito, resumen
+ */
+function crearTrackerReintentos(modelLabel) {
+  const familia = COSTO_POR_MILLON[modelLabel] !== undefined
+    ? modelLabel
+    : inferirFamiliaModelo(modelLabel);
+  const costoPorMillon = COSTO_POR_MILLON[familia] ?? COSTO_DEFAULT_POR_MILLON;
+
+  const intentos = [];
+  let exitoso = false;
+
+  return {
+    /**
+     * Registra un intento de llamada al LLM (exitoso o no).
+     *
+     * @param {{ tokensInput: number, tokensOutput: number }} uso
+     */
+    registrarIntento(uso) {
+      intentos.push({
+        numero: intentos.length + 1,
+        tokensInput: uso.tokensInput || 0,
+        tokensOutput: uso.tokensOutput || 0,
+        timestamp: Date.now(),
+      });
+    },
+
+    /** Marca la cadena de reintentos como exitosa (último intento pasó). */
+    marcarExito() { exitoso = true; },
+
+    /**
+     * Genera resumen del consumo acumulado incluyendo reintentos.
+     *
+     * @returns {{
+     *   intentos: number,
+     *   tokensInputTotal: number,
+     *   tokensOutputTotal: number,
+     *   tokensTotal: number,
+     *   costoTotal: number,
+     *   exitoso: boolean,
+     *   desperdicio: number,
+     *   descripcion: string
+     * }}
+     */
+    resumen() {
+      const tokensInputTotal = intentos.reduce((s, i) => s + i.tokensInput, 0);
+      const tokensOutputTotal = intentos.reduce((s, i) => s + i.tokensOutput, 0);
+      const tokensTotal = tokensInputTotal + tokensOutputTotal;
+      const costoTotal = (tokensTotal / 1_000_000) * costoPorMillon;
+
+      // Desperdicio = costo de intentos fallidos (todos menos el último si exitoso)
+      let desperdicio = 0;
+      if (exitoso && intentos.length > 1) {
+        const intentosFallidos = intentos.slice(0, -1);
+        const tokensFallidos = intentosFallidos.reduce(
+          (s, i) => s + i.tokensInput + i.tokensOutput, 0
+        );
+        desperdicio = (tokensFallidos / 1_000_000) * costoPorMillon;
+      } else if (!exitoso) {
+        desperdicio = costoTotal; // todo fue desperdicio
+      }
+
+      const numIntentos = intentos.length;
+      let descripcion;
+      if (numIntentos === 1) {
+        descripcion = 'Éxito en primer intento';
+      } else if (exitoso) {
+        descripcion = `Éxito en intento ${numIntentos} de ${numIntentos} — `
+          + `${formatearCosto(desperdicio)} en reintentos`;
+      } else {
+        descripcion = `Fallido después de ${numIntentos} intentos — `
+          + `${formatearCosto(costoTotal)} desperdiciados`;
+      }
+
+      return {
+        intentos: numIntentos,
+        tokensInputTotal,
+        tokensOutputTotal,
+        tokensTotal,
+        costoTotal: Math.round(costoTotal * 1_000_000) / 1_000_000,
+        exitoso,
+        desperdicio: Math.round(desperdicio * 1_000_000) / 1_000_000,
+        descripcion,
+      };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// ROI de reutilización de tokens
+// ---------------------------------------------------------------------------
+
+/**
+ * Calcula el ROI de reutilizacion de una observacion.
+ *
+ * discovery_tokens: tokens que costo descubrir esta informacion originalmente
+ * injection_tokens: tokens que cuesta inyectar el resumen en contexto
+ *
+ * ROI = (discovery_tokens - injection_tokens) / discovery_tokens * 100
+ *
+ * Ejemplo: descubrir un patron costo 5000 tokens, inyectarlo cuesta 50 tokens
+ * ROI = (5000 - 50) / 5000 * 100 = 99% de ahorro
+ *
+ * @param {number} discoveryTokens - Tokens originales de descubrimiento
+ * @param {number} injectionTokens - Tokens de inyeccion del resumen
+ * @returns {{ roi: number, ahorro: number, descripcion: string }}
+ */
+function calcularROI(discoveryTokens, injectionTokens) {
+  if (discoveryTokens <= 0) return { roi: 0, ahorro: 0, descripcion: 'Sin datos de descubrimiento' };
+
+  const ahorro = discoveryTokens - injectionTokens;
+  const roi = (ahorro / discoveryTokens) * 100;
+
+  return {
+    roi: Math.round(roi * 10) / 10,
+    ahorro,
+    descripcion: roi > 80
+      ? `Excelente: ${roi.toFixed(1)}% de ahorro (${formatearNumero(ahorro)} tokens reutilizados)`
+      : roi > 50
+        ? `Bueno: ${roi.toFixed(1)}% de ahorro`
+        : `Moderado: ${roi.toFixed(1)}% de ahorro`,
+  };
+}
+
+/**
+ * Estima tokens de inyeccion para un bloque de contexto.
+ * Heuristica: ~4 caracteres por token en espanol.
+ *
+ * @param {string} texto
+ * @returns {number}
+ */
+function estimarTokensTexto(texto) {
+  if (!texto) return 0;
+  return Math.ceil(texto.length / 4);
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  estimarToolCall,
+  formatearCosto,
+  formatearNumero,
+  inferirFamiliaModelo,
+  tokensDefault,
+  calcularROI,
+  estimarTokensTexto,
+  crearTrackerReintentos,
+  calcularCostoCanonicoTokens,
+  // Exponer tablas para tests y uso avanzado
+  TOKENS_POR_HERRAMIENTA,
+  COSTO_POR_MILLON,
+  PRICING_CANONICO,
+};

package/hooks/lib/toon-compressor.js

@@ -0,0 +1,245 @@
+'use strict';
+
+/**
+ * TOON Compressor — Compresión de schemas y documentos estructurados.
+ *
+ * Patrón adoptado de CC Workflow Studio (generate-toon-schema.ts).
+ * Reduce el tamaño de JSON schemas y documentos estructurados ~20-25%
+ * eliminando redundancia sin perder información semántica.
+ *
+ * Técnicas aplicadas:
+ *   1. Eliminar whitespace y formateo innecesario
+ *   2. Abreviar claves repetitivas con diccionario
+ *   3. Colapsar descripciones a una línea
+ *   4. Eliminar campos opcionales con valor default
+ *   5. Usar notación compacta para tipos simples
+ *
+ * Zero dependencias externas.
+ *
+ * Uso:
+ *   const { comprimirSchema, descomprimirSchema, comprimirTexto } = require('./lib/toon-compressor');
+ *   const compacto = comprimirSchema(schemaJSON);
+ *   console.log(`Reducción: ${compacto.reduccionPorcentaje}%`);
+ *
+ * @module hooks/lib/toon-compressor
+ */
+
+// ---------------------------------------------------------------------------
+// Diccionario de abreviaciones para claves JSON Schema
+// ---------------------------------------------------------------------------
+
+/**
+ * Mapeo de claves largas a abreviaciones cortas.
+ * Solo para claves que aparecen ≥3 veces en un schema típico.
+ */
+const ABREVIACIONES = {
+  description: 'desc',
+  properties: 'props',
+  required: 'req',
+  additionalProperties: 'addl',
+  type: 't',
+  items: 'it',
+  default: 'def',
+  enum: 'en',
+  maxLength: 'maxL',
+  minLength: 'minL',
+  minimum: 'min',
+  maximum: 'max',
+  pattern: 'pat',
+  oneOf: '1of',
+  anyOf: 'aof',
+  allOf: 'allof',
+};
+
+/** Mapeo inverso para descompresión. */
+const ABREVIACIONES_INV = Object.fromEntries(
+  Object.entries(ABREVIACIONES).map(([k, v]) => [v, k])
+);
+
+// ---------------------------------------------------------------------------
+// Funciones core
+// ---------------------------------------------------------------------------
+
+/**
+ * Comprime un objeto JSON Schema reemplazando claves por abreviaciones.
+ *
+ * @param {object} obj - Objeto a comprimir (se clona internamente)
+ * @returns {object} Objeto con claves abreviadas
+ */
+function _abreviarClaves(obj) {
+  if (Array.isArray(obj)) {
+    return obj.map(_abreviarClaves);
+  }
+  if (obj !== null && typeof obj === 'object') {
+    const resultado = {};
+    for (const [clave, valor] of Object.entries(obj)) {
+      const claveCorta = ABREVIACIONES[clave] || clave;
+      resultado[claveCorta] = _abreviarClaves(valor);
+    }
+    return resultado;
+  }
+  return obj;
+}
+
+/**
+ * Descomprime un objeto con claves abreviadas a sus nombres originales.
+ *
+ * @param {object} obj - Objeto con claves abreviadas
+ * @returns {object} Objeto con claves originales
+ */
+function _expandirClaves(obj) {
+  if (Array.isArray(obj)) {
+    return obj.map(_expandirClaves);
+  }
+  if (obj !== null && typeof obj === 'object') {
+    const resultado = {};
+    for (const [clave, valor] of Object.entries(obj)) {
+      const claveLarga = ABREVIACIONES_INV[clave] || clave;
+      resultado[claveLarga] = _expandirClaves(valor);
+    }
+    return resultado;
+  }
+  return obj;
+}
+
+/**
+ * Elimina campos opcionales con valor default conocido.
+ *
+ * @param {object} obj - Schema JSON
+ * @returns {object} Schema sin defaults redundantes
+ */
+function _eliminarDefaults(obj) {
+  if (Array.isArray(obj)) {
+    return obj.map(_eliminarDefaults);
+  }
+  if (obj !== null && typeof obj === 'object') {
+    const resultado = {};
+    for (const [clave, valor] of Object.entries(obj)) {
+      // Eliminar additionalProperties: true (es el default)
+      if (clave === 'additionalProperties' && valor === true) continue;
+      // Eliminar required: [] (vacío = sin requeridos)
+      if (clave === 'required' && Array.isArray(valor) && valor.length === 0) continue;
+      // Eliminar description vacía
+      if (clave === 'description' && valor === '') continue;
+      resultado[clave] = _eliminarDefaults(valor);
+    }
+    return resultado;
+  }
+  return obj;
+}
+
+/**
+ * Colapsa descripciones multi-línea a una sola línea.
+ *
+ * @param {object} obj
+ * @returns {object}
+ */
+function _colapsarDescripciones(obj) {
+  if (Array.isArray(obj)) {
+    return obj.map(_colapsarDescripciones);
+  }
+  if (obj !== null && typeof obj === 'object') {
+    const resultado = {};
+    for (const [clave, valor] of Object.entries(obj)) {
+      if (clave === 'description' && typeof valor === 'string') {
+        resultado[clave] = valor.replace(/\s+/g, ' ').trim();
+      } else {
+        resultado[clave] = _colapsarDescripciones(valor);
+      }
+    }
+    return resultado;
+  }
+  return obj;
+}
+
+// ---------------------------------------------------------------------------
+// API pública
+// ---------------------------------------------------------------------------
+
+/**
+ * Comprime un JSON Schema aplicando todas las técnicas de reducción.
+ *
+ * @param {object|string} schema - JSON Schema (objeto o string JSON)
+ * @returns {{ comprimido: string, original: number, reducido: number, reduccionPorcentaje: number }}
+ */
+function comprimirSchema(schema) {
+  const obj = typeof schema === 'string' ? JSON.parse(schema) : schema;
+  const original = JSON.stringify(obj);
+
+  let procesado = _eliminarDefaults(obj);
+  procesado = _colapsarDescripciones(procesado);
+  procesado = _abreviarClaves(procesado);
+
+  const comprimido = JSON.stringify(procesado);
+
+  const tamOriginal = original.length;
+  const tamReducido = comprimido.length;
+  const reduccion = ((tamOriginal - tamReducido) / tamOriginal) * 100;
+
+  return {
+    comprimido,
+    original: tamOriginal,
+    reducido: tamReducido,
+    reduccionPorcentaje: Math.round(reduccion * 10) / 10,
+  };
+}
+
+/**
+ * Descomprime un JSON Schema con claves abreviadas.
+ *
+ * @param {string|object} comprimido - Schema comprimido
+ * @returns {object} Schema original con claves expandidas
+ */
+function descomprimirSchema(comprimido) {
+  const obj = typeof comprimido === 'string' ? JSON.parse(comprimido) : comprimido;
+  return _expandirClaves(obj);
+}
+
+/**
+ * Comprime texto Markdown eliminando redundancia para reducir tokens.
+ *
+ * Técnicas:
+ *   - Colapsar múltiples líneas vacías a una
+ *   - Eliminar trailing whitespace
+ *   - Comprimir tablas (eliminar padding)
+ *   - Eliminar comentarios HTML
+ *
+ * @param {string} texto - Texto Markdown
+ * @returns {{ comprimido: string, original: number, reducido: number, reduccionPorcentaje: number }}
+ */
+function comprimirTexto(texto) {
+  const original = texto.length;
+
+  let resultado = texto;
+  // Colapsar 3+ líneas vacías a 2
+  resultado = resultado.replace(/\n{3,}/g, '\n\n');
+  // Eliminar trailing whitespace
+  resultado = resultado.replace(/[ \t]+$/gm, '');
+  // Eliminar comentarios HTML
+  resultado = resultado.replace(/<!--[\s\S]*?-->/g, '');
+  // Comprimir padding en tablas (múltiples espacios → uno)
+  resultado = resultado.replace(/\|[ \t]{2,}/g, '| ');
+  resultado = resultado.replace(/[ \t]{2,}\|/g, ' |');
+
+  const reducido = resultado.length;
+  const reduccion = ((original - reducido) / original) * 100;
+
+  return {
+    comprimido: resultado,
+    original,
+    reducido,
+    reduccionPorcentaje: Math.round(reduccion * 10) / 10,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  comprimirSchema,
+  descomprimirSchema,
+  comprimirTexto,
+  // Exponer diccionario para tests
+  ABREVIACIONES,
+};