openprompt-lang 1.2.7 → 1.3.0

package/src/embeddings/embedder.js

@@ -0,0 +1,431 @@
+// @use(kind, contract, limit, deps)
+// @kind(module)
+// @contract(in: string -> out: number[], async: true, sideEffect: red local si provider=ollama)
+// @limit(lines: 425)
+// @deps(ollama | @xenova/transformers, opcional)
+
+/**
+ * Servicio de embeddings vectoriales con soporte multi-proveedor.
+ *
+ * Proveedores:
+ *   - 'ollama':      Usa el API HTTP de Ollama (nomic-embed-text, 768d)
+ *   - 'transformers': Usa Transformers.js en Node.js (all-MiniLM-L6-v2, 384d)
+ *
+ * Auto-fallback: Si Ollama no está disponible, cae a Transformers.js.
+ * Si ningún proveedor funciona, lanza error con mensaje claro.
+ */
+
+import { readFileSync, existsSync } from "fs"
+import { join } from "path"
+
+// ─── Constantes ────────────────────────────────────────────────────
+
+const OLLAMA_BASE_URL = "http://localhost:11434"
+const OLLAMA_DEFAULT_MODEL = "nomic-embed-text"
+const TRANSFORMERS_DEFAULT_MODEL = "Xenova/all-MiniLM-L6-v2"
+const MAX_CHARS = 8000
+const EMBEDDING_TIMEOUT = 30000
+
+// ─── Estado interno ────────────────────────────────────────────────
+
+let _activeProvider = null // 'ollama' | 'transformers' | null (auto)
+let _ollamaModel = OLLAMA_DEFAULT_MODEL
+let _transformersModel = TRANSFORMERS_DEFAULT_MODEL
+
+// Cache de disponibilidad para evitar chequeos repetidos
+let _ollamaAvailable = null // null = no chequeado, boolean
+let _transformersPipeline = null // cache de pipeline
+
+// Test hook: permite forzar transformes no disponible en tests
+let _forceNoTransformers = false
+
+/**
+ * Fuerza que transformers aparezca como no disponible (test hook).
+ * Solo afecta al entorno de pruebas, no usar en producción.
+ *
+ * @param {boolean} val
+ */
+export function _setForceNoTransformers(val) {
+  _forceNoTransformers = val
+}
+
+// ─── Configuración ─────────────────────────────────────────────────
+
+/**
+ * Configura el proveedor activo.
+ * @param {'ollama'|'transformers'} provider
+ */
+export function setActiveProvider(provider) {
+  if (provider !== "ollama" && provider !== "transformers") {
+    throw new Error(`Proveedor inválido: "${provider}". Usa 'ollama' o 'transformers'.`)
+  }
+  _activeProvider = provider
+}
+
+/**
+ * Obtiene el proveedor activo actual.
+ * @returns {'ollama'|'transformers'|null}
+ */
+export function getActiveProvider() {
+  return _activeProvider
+}
+
+/**
+ * Resetea el estado del módulo (útil para tests).
+ * Vuelve a auto-detección y limpia cachés.
+ */
+export function resetEmbedder() {
+  _activeProvider = null
+  _ollamaAvailable = null
+  _transformersPipeline = null
+  _forceNoTransformers = false
+}
+
+/**
+ * Lee configuración desde prompt-lang.json si existe.
+ */
+function loadConfig() {
+  try {
+    const configPath = join(process.cwd(), "prompt-lang.json")
+    if (existsSync(configPath)) {
+      const config = JSON.parse(readFileSync(configPath, "utf-8"))
+      const ec = config.embeddings
+      if (ec) {
+        if (ec.provider) setActiveProvider(ec.provider)
+        if (ec.ollamaModel) _ollamaModel = ec.ollamaModel
+        if (ec.transformersModel) _transformersModel = ec.transformersModel
+      }
+    }
+  } catch {
+    // Usar defaults
+  }
+}
+
+// Cargar configuración al importar
+loadConfig()
+
+// ─── Proveedores ───────────────────────────────────────────────────
+
+/**
+ * Genera embedding via Ollama API.
+ * POST /api/embeddings con { model, prompt }
+ *
+ * @param {string} text
+ * @param {string} model
+ * @returns {Promise<number[]>}
+ */
+async function embedOllama(text, model) {
+  const url = `${OLLAMA_BASE_URL}/api/embeddings`
+  const controller = new AbortController()
+  const timeoutId = setTimeout(() => controller.abort(), EMBEDDING_TIMEOUT)
+
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: model || _ollamaModel,
+        prompt: text,
+      }),
+      signal: controller.signal,
+    })
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "unknown")
+      throw new Error(`Ollama API error (${response.status}): ${errorText}`)
+    }
+
+    const data = await response.json()
+    return Array.from(data.embedding || [])
+  } finally {
+    clearTimeout(timeoutId)
+  }
+}
+
+/**
+ * Genera embedding via Transformers.js.
+ * Usa lazy-loading del pipeline para no bloquear el import.
+ *
+ * @param {string} text
+ * @param {string} model
+ * @returns {Promise<number[]>}
+ */
+async function embedTransformers(text, model) {
+  if (!_transformersPipeline) {
+    const { pipeline } = await import("@xenova/transformers")
+    _transformersPipeline = await pipeline("feature-extraction", model || _transformersModel)
+  }
+
+  const result = await _transformersPipeline(text, {
+    pooling: "mean",
+    normalize: true,
+  })
+
+  return Array.from(result.data)
+}
+
+// ─── Detección de disponibilidad ───────────────────────────────────
+
+/**
+ * Verifica si Ollama está disponible localmente.
+ * Cachea el resultado para evitar llamadas repetidas.
+ *
+ * @returns {Promise<{ available: boolean, error?: string }>}
+ */
+async function checkOllama() {
+  if (_ollamaAvailable !== null) {
+    return { available: _ollamaAvailable }
+  }
+
+  try {
+    const controller = new AbortController()
+    const timeoutId = setTimeout(() => controller.abort(), 3000)
+
+    const response = await fetch(`${OLLAMA_BASE_URL}/api/tags`, {
+      signal: controller.signal,
+    }).finally(() => clearTimeout(timeoutId))
+
+    if (response.ok) {
+      _ollamaAvailable = true
+      return { available: true }
+    }
+    _ollamaAvailable = false
+    return { available: false, error: `HTTP ${response.status}` }
+  } catch (err) {
+    _ollamaAvailable = false
+    return {
+      available: false,
+      error: err.name === "AbortError" ? "Timeout" : err.message,
+    }
+  }
+}
+
+/**
+ * Verifica si Transformers.js está disponible.
+ *
+ * @returns {Promise<{ available: boolean, error?: string }>}
+ */
+async function checkTransformers() {
+  if (_forceNoTransformers) {
+    return { available: false, error: "Forzado por test hook _setForceNoTransformers" }
+  }
+  try {
+    // Verificar que el módulo se puede importar
+    await import("@xenova/transformers")
+    return { available: true }
+  } catch (err) {
+    return { available: false, error: err.message }
+  }
+}
+
+/**
+ * Verifica si un proveedor está disponible.
+ *
+ * @param {'ollama'|'transformers'} provider
+ * @returns {Promise<{ available: boolean, error?: string }>}
+ */
+export async function checkProvider(provider) {
+  switch (provider) {
+    case "ollama":
+      return checkOllama()
+    case "transformers":
+      return checkTransformers()
+    default:
+      return { available: false, error: `Proveedor desconocido: "${provider}"` }
+  }
+}
+
+/**
+ * Resuelve qué proveedor usar según configuración y disponibilidad.
+ *
+ * @returns {Promise<{ provider: string, model: string }>}
+ */
+async function resolveProvider() {
+  // Si hay un proveedor activo configurado, verificar disponibilidad
+  if (_activeProvider) {
+    const status = await checkProvider(_activeProvider)
+    if (status.available) {
+      const model = _activeProvider === "ollama" ? _ollamaModel : _transformersModel
+      return { provider: _activeProvider, model }
+    }
+    // Si el configurado no está disponible, caer al otro
+  }
+
+  // Auto-detección: probar Ollama primero, luego Transformers
+  const ollamaStatus = await checkOllama()
+  if (ollamaStatus.available) {
+    return { provider: "ollama", model: _ollamaModel }
+  }
+
+  const transformersStatus = await checkTransformers()
+  if (transformersStatus.available) {
+    return { provider: "transformers", model: _transformersModel }
+  }
+
+  throw new Error(
+    "Ningún proveedor de embeddings disponible. " +
+      "Instala Ollama (ollama pull nomic-embed-text) o " +
+      "@xenova/transformers (npm install @xenova/transformers)."
+  )
+}
+
+// ─── API Principal ─────────────────────────────────────────────────
+
+/**
+ * Valida y prepara el texto para embedding.
+ * @param {string} text
+ * @returns {string}
+ */
+function prepareText(text) {
+  if (!text || (typeof text === "string" && text.trim().length === 0)) {
+    throw new Error("El texto a embedder no puede estar vacío.")
+  }
+
+  if (text.length > MAX_CHARS) {
+    console.warn(
+      `⚠️  Texto de ${text.length} caracteres excede el máximo de ${MAX_CHARS}. ` +
+        "Se truncará automáticamente."
+    )
+    return text.slice(0, MAX_CHARS)
+  }
+
+  return text
+}
+
+/**
+ * Obtiene el vector embedding para un texto.
+ *
+ * @param {string} text - Texto a embedder (máx 8000 chars)
+ * @param {Object} [options]
+ * @param {'ollama'|'transformers'} [options.provider] - Forzar proveedor específico
+ * @param {string} [options.model] - Modelo específico
+ * @returns {Promise<number[]>} Vector de 384-768 dimensiones
+ */
+export async function embed(text, options = {}) {
+  const cleanText = prepareText(text)
+
+  if (options.provider) {
+    // Usar proveedor específico
+    const status = await checkProvider(options.provider)
+    if (!status.available) {
+      throw new Error(`Proveedor "${options.provider}" no disponible: ${status.error}`)
+    }
+
+    switch (options.provider) {
+      case "ollama":
+        return embedOllama(cleanText, options.model || _ollamaModel)
+      case "transformers":
+        return embedTransformers(cleanText, options.model || _transformersModel)
+      default:
+        throw new Error(`Proveedor inválido: "${options.provider}"`)
+    }
+  }
+
+  // Auto-detección
+  const resolved = await resolveProvider()
+
+  switch (resolved.provider) {
+    case "ollama":
+      return embedOllama(cleanText, resolved.model)
+    case "transformers":
+      return embedTransformers(cleanText, resolved.model)
+    default:
+      throw new Error(`Proveedor no soportado: "${resolved.provider}"`)
+  }
+}
+
+/**
+ * Obtiene embeddings en batch.
+ * Procesa múltiples textos de forma más eficiente que llamadas separadas.
+ *
+ * @param {string[]} texts - Array de textos a embedder
+ * @param {Object} [options]
+ * @param {'ollama'|'transformers'} [options.provider]
+ * @param {string} [options.model]
+ * @returns {Promise<number[][]>} Array de vectores
+ */
+export async function embedBatch(texts, options = {}) {
+  if (!Array.isArray(texts) || texts.length === 0) {
+    throw new Error("embedBatch requiere un array no vacío de textos.")
+  }
+
+  const resolved = options.provider
+    ? { provider: options.provider, model: options.model }
+    : await resolveProvider()
+
+  // Transformers.js soporta batch nativamente
+  if (resolved.provider === "transformers") {
+    const cleanTexts = texts.map(prepareText)
+    return embedTransformersBatch(cleanTexts, resolved.model)
+  }
+
+  // Ollama: secuencial (Ollama no tiene batch embedding nativo)
+  const results = []
+  for (const t of texts) {
+    const cleanText = prepareText(t)
+    const vector = await embedOllama(cleanText, resolved.model)
+    results.push(vector)
+  }
+  return results
+}
+
+/**
+ * Batch embedding con Transformers.js (nativamente más rápido).
+ *
+ * @param {string[]} texts
+ * @param {string} model
+ * @returns {Promise<number[][]>}
+ */
+async function embedTransformersBatch(texts, model) {
+  if (!_transformersPipeline) {
+    const { pipeline } = await import("@xenova/transformers")
+    _transformersPipeline = await pipeline("feature-extraction", model || _transformersModel)
+  }
+
+  const result = await _transformersPipeline(texts, {
+    pooling: "mean",
+    normalize: true,
+  })
+
+  // result.data es un tensor con shape [n_texts, dim]
+  // result.tolist() devuelve un array 2D
+  const array = result.tolist()
+  return array.map((row) => Array.from(row))
+}
+
+// ─── Utilidades ────────────────────────────────────────────────────
+
+/**
+ * Calcula la similitud de coseno entre dos vectores.
+ *
+ * @param {number[]} a - Primer vector
+ * @param {number[]} b - Segundo vector
+ * @returns {number} Similitud entre -1 y 1
+ * @throws {Error} Si los vectores tienen diferente dimensión o están vacíos
+ */
+export function cosineSimilarity(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b)) {
+    throw new Error("Ambos argumentos deben ser arrays.")
+  }
+  if (a.length === 0 || b.length === 0) {
+    throw new Error("Los vectores no pueden estar vacíos.")
+  }
+  if (a.length !== b.length) {
+    throw new Error(`Dimensión incorrecta: vector A tiene ${a.length}, vector B tiene ${b.length}.`)
+  }
+
+  let dotProduct = 0
+  let normA = 0
+  let normB = 0
+
+  for (let i = 0; i < a.length; i++) {
+    dotProduct += a[i] * b[i]
+    normA += a[i] * a[i]
+    normB += b[i] * b[i]
+  }
+
+  const magnitude = Math.sqrt(normA) * Math.sqrt(normB)
+
+  if (magnitude === 0) return 0
+  return dotProduct / magnitude
+}