===========================================
GUÍA DE VALIDACIÓN SEMÁNTICA CON IA
Framework Hakalab - Sentence Transformers
===========================================

ÍNDICE
------
1. Introducción
2. Instalación
3. Conceptos Clave
4. Modelos Disponibles
5. Umbrales Recomendados
6. Steps Disponibles
7. Ejemplos de Uso
8. Casos de Uso Reales
9. Mejores Prácticas
10. Troubleshooting

===========================================
1. INTRODUCCIÓN
===========================================

La validación semántica permite verificar que dos textos tienen el mismo significado
sin necesidad de que sean idénticos palabra por palabra.

¿Por qué usar validación semántica?
-----------------------------------
✅ Textos dinámicos: "Tu solicitud #12345 fue aprobada" vs "Solicitud aprobada"
✅ Variaciones de redacción: "Pago exitoso" vs "Tu pago se procesó correctamente"
✅ Multilingüe: "Error al procesar" vs "Processing error"
✅ Respuestas de IA/LLM: Validar que la respuesta sea correcta sin texto exacto
✅ Mensajes de usuario: Validar intención sin depender de palabras exactas

Tecnología utilizada:
--------------------
- Sentence Transformers: Convierte texto en vectores numéricos (embeddings)
- Similitud de Coseno: Mide qué tan similares son dos vectores (0.0 a 1.0)
- Modelos pre-entrenados: Multilingües y especializados

===========================================
2. INSTALACIÓN
===========================================

Dependencias requeridas:
-----------------------
pip install sentence-transformers torch

O instalar todas las dependencias del framework:
pip install haka-playwright-engine[all]

Nota: La primera vez que uses un modelo, se descargará automáticamente (~400MB).

===========================================
3. CONCEPTOS CLAVE
===========================================

Embeddings (Vectores)
--------------------
- Representación numérica del significado de un texto
- Textos similares tienen vectores similares
- Ejemplo: "Hola" y "Hello" tendrán vectores cercanos

Similitud de Coseno
------------------
- Mide el ángulo entre dos vectores
- Resultado: 0.0 (completamente diferentes) a 1.0 (idénticos)
- Ejemplo: 0.85 = Alta similitud semántica

Umbral (Threshold)
-----------------
- Valor mínimo de similitud para considerar textos como "similares"
- Se configura según el caso de uso
- Ejemplo: 0.75 = Requiere 75% de similitud para pasar

===========================================
4. MODELOS DISPONIBLES
===========================================

Modelos Multilingües (Recomendados para español)
-----------------------------------------------

1. paraphrase-multilingual-MiniLM-L12-v2 (RECOMENDADO)
   - Tamaño: ~420MB
   - Velocidad: Rápido
   - Precisión: Alta
   - Idiomas: 50+ incluyendo español
   - Uso: General, balanceado

2. paraphrase-multilingual-mpnet-base-v2
   - Tamaño: ~1GB
   - Velocidad: Medio
   - Precisión: Muy alta
   - Idiomas: 50+ incluyendo español
   - Uso: Cuando necesitas máxima precisión

Modelos en Inglés (Más rápidos)
-------------------------------

3. all-MiniLM-L6-v2
   - Tamaño: ~80MB
   - Velocidad: Muy rápido
   - Precisión: Buena
   - Idiomas: Solo inglés
   - Uso: Aplicaciones en inglés, velocidad crítica

4. all-mpnet-base-v2
   - Tamaño: ~420MB
   - Velocidad: Medio
   - Precisión: Muy alta
   - Idiomas: Solo inglés
   - Uso: Máxima precisión en inglés

===========================================
5. UMBRALES RECOMENDADOS
===========================================

Guía de Umbrales
---------------

0.90 - 1.00: Textos casi idénticos
---------------------------------
- Uso: Validación estricta
- Ejemplo: "Pago aprobado" vs "Tu pago fue aprobado"
- Caso: Mensajes críticos de sistema

0.75 - 0.89: Alta similitud semántica (RECOMENDADO PARA QA)
----------------------------------------------------------
- Uso: Validación estándar de QA
- Ejemplo: "Solicitud exitosa" vs "Tu solicitud fue procesada correctamente"
- Caso: Mensajes de éxito, confirmaciones

0.60 - 0.74: Similitud moderada
-------------------------------
- Uso: Validación flexible
- Ejemplo: "Sistema funcionando" vs "Todo está operativo"
- Caso: Mensajes informativos, estados

0.40 - 0.59: Similitud baja
---------------------------
- Uso: Validación muy flexible
- Ejemplo: "Error" vs "Hubo un problema"
- Caso: Categorización amplia

0.00 - 0.39: Textos diferentes
------------------------------
- Uso: No recomendado para validación
- Ejemplo: "Hola" vs "Error"
- Caso: Textos sin relación

Recomendación por Caso de Uso
-----------------------------
- Mensajes de error críticos: 0.85
- Mensajes de éxito: 0.75
- Mensajes informativos: 0.70
- Respuestas de chatbot/LLM: 0.70
- Categorización de texto: 0.60

===========================================
6. STEPS DISPONIBLES
===========================================

CONFIGURACIÓN
-------------

1. Configurar modelo específico:
   Given configuro el modelo semántico como "paraphrase-multilingual-MiniLM-L12-v2"

2. Establecer umbral:
   Given establezco el umbral de similitud semántica en 0.75

3. Usar configuración por defecto:
   Given uso la configuración semántica por defecto
   (Modelo: paraphrase-multilingual-MiniLM-L12-v2, Umbral: 0.75)

VALIDACIONES
-----------

4. Validar similitud entre textos:
   Then el texto "Tu solicitud fue aprobada" debe ser semánticamente similar a "Solicitud exitosa"

5. Validar texto de variable:
   Then el texto de la variable "respuesta_api" debe ser semánticamente similar a "Operación exitosa"

6. Validar texto de elemento web:
   Then el texto del elemento "Mensaje" con identificador "$.HOME.message" debe ser semánticamente similar a "Éxito"

7. Calcular y guardar similitud:
   Then calculo la similitud semántica entre "Texto 1" y "Texto 2" y la guardo en "similitud"

===========================================
7. EJEMPLOS DE USO
===========================================

Ejemplo 1: Validación Básica
----------------------------
Scenario: Validar mensaje de éxito
  Given uso la configuración semántica por defecto
  When hago click en el botón "Enviar"
  Then el texto del elemento "Mensaje" con identificador "$.FORM.message" debe ser semánticamente similar a "Formulario enviado exitosamente"

Ejemplo 2: Validación de API
----------------------------
Scenario: Validar respuesta de API
  Given configuro el modelo semántico como "paraphrase-multilingual-MiniLM-L12-v2"
  And establezco el umbral de similitud semántica en 0.80
  When realizo una petición POST a "https://api.example.com/users"
  And guardo el valor de "response.message" en la variable "api_message"
  Then el texto de la variable "api_message" debe ser semánticamente similar a "Usuario creado correctamente"

Ejemplo 3: Validación Multilingüe
---------------------------------
Scenario: Validar mensajes en diferentes idiomas
  Given configuro el modelo semántico como "paraphrase-multilingual-MiniLM-L12-v2"
  And establezco el umbral de similitud semántica en 0.70
  Then el texto "La operación fue exitosa" debe ser semánticamente similar a "The operation was successful"

Ejemplo 4: Calcular Similitud para Análisis
------------------------------------------
Scenario: Analizar similitud de respuestas
  Given uso la configuración semántica por defecto
  When extraigo el texto del elemento "Respuesta 1" y lo guardo en "resp1"
  And extraigo el texto del elemento "Respuesta 2" y lo guardo en "resp2"
  Then calculo la similitud semántica entre "${resp1}" y "${resp2}" y la guardo en "similitud"
  And muestro en consola el valor de la variable "similitud"

Ejemplo 5: Validación de Chatbot/LLM
------------------------------------
Scenario: Validar respuesta de chatbot
  Given configuro el modelo semántico como "paraphrase-multilingual-mpnet-base-v2"
  And establezco el umbral de similitud semántica en 0.70
  When escribo "¿Cuál es el horario de atención?" en el chat
  And espero 3 segundos
  And extraigo el texto del elemento "Respuesta Bot" y lo guardo en "bot_response"
  Then el texto de la variable "bot_response" debe ser semánticamente similar a "Nuestro horario es de lunes a viernes de 9am a 6pm"

===========================================
8. CASOS DE USO REALES
===========================================

Caso 1: Validación de Mensajes Dinámicos
---------------------------------------
Problema: Los mensajes incluyen IDs, fechas, nombres que cambian
Solución: Validación semántica ignora estos detalles

Ejemplo:
  Texto esperado: "Tu solicitud fue aprobada"
  Texto actual: "Hola Juan, tu solicitud #12345 del 15/01/2024 fue aprobada exitosamente"
  Similitud: ~0.78 ✅ PASS

Caso 2: Respuestas de IA/LLM
---------------------------
Problema: Las respuestas de IA nunca son idénticas
Solución: Validar que la respuesta tenga el significado correcto

Ejemplo:
  Pregunta: "¿Cómo reseteo mi contraseña?"
  Respuesta esperada: "Puedes resetear tu contraseña desde la página de login"
  Respuesta actual: "Para cambiar tu contraseña, ve a la pantalla de inicio de sesión y haz click en 'Olvidé mi contraseña'"
  Similitud: ~0.82 ✅ PASS

Caso 3: Validación Multilingüe
-----------------------------
Problema: Aplicación en múltiples idiomas
Solución: Un solo test valida todos los idiomas

Ejemplo:
  Texto esperado: "Operación exitosa"
  Textos actuales:
    - Español: "La operación se completó correctamente" → 0.85 ✅
    - Inglés: "Operation completed successfully" → 0.83 ✅
    - Portugués: "Operação concluída com sucesso" → 0.84 ✅

Caso 4: Validación de Categorías
-------------------------------
Problema: Clasificar mensajes en categorías
Solución: Comparar con texto representativo de cada categoría

Ejemplo:
  Categorías:
    - Error: "Hubo un error al procesar"
    - Éxito: "Operación completada exitosamente"
    - Advertencia: "Ten cuidado con esta acción"
  
  Mensaje: "No se pudo completar la operación"
  Similitud con "Error": 0.78 ✅ Es un error

Caso 5: Testing de Paráfrasis
----------------------------
Problema: Verificar que diferentes formas de decir lo mismo funcionen
Solución: Validar que todas las variantes sean semánticamente equivalentes

Ejemplo:
  Variantes de "Pago exitoso":
    - "Tu pago fue procesado" → 0.82 ✅
    - "Pago completado correctamente" → 0.88 ✅
    - "Transacción aprobada" → 0.75 ✅

===========================================
9. MEJORES PRÁCTICAS
===========================================

1. Elegir el Modelo Correcto
---------------------------
✅ Usa modelos multilingües si tu app está en español
✅ Usa modelos más grandes si la precisión es crítica
✅ Usa modelos pequeños si la velocidad es importante

2. Configurar Umbrales Apropiados
--------------------------------
✅ Empieza con 0.75 y ajusta según resultados
✅ Usa umbrales más altos (0.85+) para mensajes críticos
✅ Usa umbrales más bajos (0.65-0.70) para categorización

3. Optimizar Performance
-----------------------
✅ Configura el modelo una sola vez al inicio del test
✅ Reutiliza el mismo modelo para múltiples validaciones
✅ Considera cachear embeddings si validas los mismos textos repetidamente

4. Combinar con Validaciones Tradicionales
-----------------------------------------
✅ Usa validación semántica para contenido dinámico
✅ Usa validación exacta para IDs, códigos, números
✅ Combina ambas según el caso

Ejemplo:
  # Validar código exacto
  Then el código de error debe ser "ERR_404"
  # Validar mensaje semánticamente
  Then el mensaje de error debe ser semánticamente similar a "Página no encontrada"

5. Logging y Debugging
---------------------
✅ Los steps muestran la similitud calculada
✅ Revisa los logs para ajustar umbrales
✅ Usa el step de "calcular y guardar" para análisis

6. Testing de la Validación Semántica
------------------------------------
✅ Prueba con textos que SÍ deberían pasar
✅ Prueba con textos que NO deberían pasar
✅ Ajusta umbrales basándote en resultados reales

===========================================
10. TROUBLESHOOTING
===========================================

Problema: "ImportError: No module named 'sentence_transformers'"
---------------------------------------------------------------
Solución: pip install sentence-transformers torch

Problema: "El modelo tarda mucho en cargar la primera vez"
---------------------------------------------------------
Solución: Es normal, el modelo se descarga (~400MB). Las siguientes veces será instantáneo.

Problema: "La similitud es muy baja para textos que deberían ser similares"
--------------------------------------------------------------------------
Solución:
1. Verifica que estés usando un modelo multilingüe si el texto está en español
2. Reduce el umbral (prueba con 0.65-0.70)
3. Considera usar un modelo más grande (mpnet en lugar de MiniLM)

Problema: "La similitud es muy alta para textos que NO deberían ser similares"
-----------------------------------------------------------------------------
Solución:
1. Aumenta el umbral (prueba con 0.85-0.90)
2. Verifica que los textos realmente sean diferentes semánticamente
3. Considera usar validación exacta en lugar de semántica

Problema: "Out of memory al usar el modelo"
------------------------------------------
Solución:
1. Usa un modelo más pequeño (MiniLM en lugar de mpnet)
2. Procesa textos más cortos
3. Aumenta la RAM disponible

Problema: "Los tests son muy lentos"
-----------------------------------
Solución:
1. Configura el modelo una sola vez al inicio
2. Usa un modelo más pequeño (all-MiniLM-L6-v2)
3. Considera usar GPU si está disponible

Problema: "Validación falla en CI/CD pero pasa localmente"
---------------------------------------------------------
Solución:
1. Asegúrate de que sentence-transformers esté en requirements.txt
2. Verifica que el modelo se descargue correctamente en CI/CD
3. Considera cachear el modelo en CI/CD

===========================================
RECURSOS ADICIONALES
===========================================

Documentación oficial:
- Sentence Transformers: https://www.sbert.net/
- Modelos disponibles: https://www.sbert.net/docs/pretrained_models.html

Papers de referencia:
- Sentence-BERT: https://arxiv.org/abs/1908.10084
- Paraphrase Mining: https://arxiv.org/abs/1908.10084

Comunidad:
- GitHub: https://github.com/UKPLab/sentence-transformers
- Hugging Face: https://huggingface.co/sentence-transformers

===========================================
FIN DE LA GUÍA
===========================================


===========================================
11. FUNCIONALIDADES AVANZADAS
===========================================

ANÁLISIS DE SENTIMIENTO
-----------------------

El framework puede analizar el sentimiento (positivo, negativo, neutral) de textos.

Steps disponibles:
1. Verificar sentimiento de texto:
   Then el sentimiento del texto "Me encanta este producto" debe ser "positivo"

2. Verificar sentimiento de variable:
   Then el sentimiento de la variable "comentario" debe ser "negativo"

Sentimientos soportados:
- positivo: Textos con connotación positiva
- negativo: Textos con connotación negativa
- neutral: Textos sin carga emocional clara

Casos de uso:
✅ Validar respuestas empáticas de chatbots
✅ Analizar feedback de usuarios
✅ Verificar tono de mensajes de error
✅ Clasificar comentarios en redes sociales
✅ Validar comunicaciones de servicio al cliente

Ejemplo práctico:
----------------
Scenario: Validar respuesta empática del chatbot
  Given uso la configuración semántica por defecto
  When el usuario escribe "Estoy muy molesto"
  And extraigo la respuesta del bot en "respuesta"
  Then el sentimiento de la variable "respuesta" debe ser "positivo"
  # El bot debe responder con empatía (sentimiento positivo)


CLASIFICACIÓN DE TEXTO
----------------------

Clasifica textos en categorías personalizadas usando similitud semántica.

Steps disponibles:
1. Clasificar y guardar:
   Then clasifico el texto "Error de conexión" en las categorías "error,éxito,advertencia" y guardo el resultado en "tipo"

2. Verificar categoría:
   Then el texto "Operación exitosa" debe pertenecer a la categoría "éxito" de "error,éxito,advertencia"

Casos de uso:
✅ Clasificar mensajes de sistema (error/éxito/advertencia)
✅ Categorizar tickets de soporte (técnico/producto/cuenta)
✅ Clasificar feedback (producto/servicio/precio)
✅ Organizar documentos por tema
✅ Enrutar mensajes a departamentos correctos

Ejemplo práctico:
----------------
Scenario: Clasificar tickets de soporte automáticamente
  Given uso la configuración semántica por defecto
  When extraigo el texto del ticket en "descripcion"
  Then clasifico el texto "${descripcion}" en las categorías "técnico,producto,facturación,consulta" y guardo el resultado en "departamento"
  # Usar "departamento" para enrutar el ticket


DETECCIÓN DE IDIOMA
-------------------

Detecta el idioma de un texto usando similitud semántica.

Idiomas soportados:
- español
- inglés
- portugués
- francés
- alemán

Steps disponibles:
1. Detectar y guardar:
   Then detecto el idioma del texto "Hello world" y lo guardo en "idioma"

2. Verificar idioma:
   Then el idioma del texto "Hola mundo" debe ser "español"

Casos de uso:
✅ Validar localización de aplicaciones
✅ Verificar traducciones automáticas
✅ Enrutar usuarios según idioma
✅ Validar contenido multilingüe
✅ Testing de internacionalización (i18n)

Ejemplo práctico:
----------------
Scenario: Validar que la app muestra el idioma correcto
  Given navego a "https://example.com?lang=es"
  And uso la configuración semántica por defecto
  When extraigo el texto del elemento "Bienvenida" en "mensaje"
  Then el idioma del texto "${mensaje}" debe ser "español"


BÚSQUEDA SEMÁNTICA
-----------------

Encuentra el texto más similar a una consulta en una lista de opciones.

Step disponible:
  Then busco el texto más similar a "problema de red" en la lista "error de conexión,fallo de servidor,datos incorrectos" y lo guardo en "resultado"

Casos de uso:
✅ Buscar FAQ más relevante para una pregunta
✅ Encontrar error más similar al reportado
✅ Sugerir artículos de ayuda relacionados
✅ Matching de intenciones en chatbots
✅ Búsqueda de documentos similares

Ejemplo práctico:
----------------
Scenario: Sugerir FAQ relevante
  Given uso la configuración semántica por defecto
  When el usuario pregunta "¿Cómo cambio mi email?"
  Then busco el texto más similar a "${pregunta}" en la lista "Cambiar contraseña,Actualizar email,Eliminar cuenta,Recuperar acceso" y lo guardo en "faq_sugerida"
  # Mostrar la FAQ más relevante al usuario


COMPARACIÓN MÚLTIPLE
--------------------

Compara un texto con múltiples referencias y muestra todas las similitudes.

Step disponible:
  Then comparo el texto "Error de red" con múltiples referencias "error de conexión,problema de servidor,fallo de autenticación" y muestro las similitudes

Casos de uso:
✅ Análisis exploratorio de similitudes
✅ Debugging de clasificaciones
✅ Ajuste de umbrales
✅ Comparación de variantes de texto
✅ Análisis de paráfrasis

Ejemplo práctico:
----------------
Scenario: Analizar similitud de variantes de mensaje
  Given uso la configuración semántica por defecto
  Then comparo el texto "Pago exitoso" con múltiples referencias "Pago aprobado,Transacción completada,Pago procesado,Operación exitosa" y muestro las similitudes
  # Ver qué variante es más similar


===========================================
12. CASOS DE USO AVANZADOS
===========================================

Caso 1: Validación de Chatbot Empático
--------------------------------------
Problema: El chatbot debe responder con empatía a quejas
Solución: Validar sentimiento de la respuesta

Ejemplo:
  Usuario: "Estoy muy molesto con el servicio"
  Bot: "Lamento mucho que hayas tenido esa experiencia, déjame ayudarte"
  
  Validación:
    - Sentimiento de respuesta debe ser "positivo" (empático)
    - Respuesta debe ser semánticamente similar a "Lamento tu experiencia, te ayudaré"

Caso 2: Enrutamiento Inteligente de Tickets
------------------------------------------
Problema: Tickets deben ir al departamento correcto
Solución: Clasificar automáticamente por categoría

Ejemplo:
  Ticket: "No puedo acceder a mi cuenta"
  Clasificación: "cuenta" → Departamento de Cuentas
  
  Ticket: "El producto llegó dañado"
  Clasificación: "producto" → Departamento de Calidad

Caso 3: Testing de Localización (i18n)
-------------------------------------
Problema: Verificar que la app muestra el idioma correcto
Solución: Detectar idioma del contenido

Ejemplo:
  URL: /app?lang=es
  Contenido: "Bienvenido a nuestra aplicación"
  Validación: Idioma debe ser "español"
  
  URL: /app?lang=en
  Contenido: "Welcome to our application"
  Validación: Idioma debe ser "inglés"

Caso 4: Sugerencia de FAQ Relevante
----------------------------------
Problema: Mostrar la FAQ más relevante a la pregunta del usuario
Solución: Búsqueda semántica en lista de FAQs

Ejemplo:
  Pregunta: "¿Cómo puedo resetear mi contraseña?"
  FAQs: ["Cambiar contraseña", "Recuperar cuenta", "Actualizar perfil"]
  Resultado: "Cambiar contraseña" (más similar)

Caso 5: Análisis de Feedback Multilingüe
---------------------------------------
Problema: Analizar feedback en múltiples idiomas
Solución: Combinar detección de idioma + análisis de sentimiento

Ejemplo:
  Feedback EN: "This product is amazing!" → Positivo, Inglés
  Feedback ES: "Este producto es terrible" → Negativo, Español
  Feedback PT: "Este produto é bom" → Positivo, Portugués

Caso 6: Validación de Mensajes de Error Consistentes
---------------------------------------------------
Problema: Diferentes errores deben clasificarse correctamente
Solución: Clasificar en categorías de error

Ejemplo:
  "No se pudo conectar al servidor" → error de red
  "Credenciales inválidas" → error de autenticación
  "Datos incorrectos" → error de validación

Caso 7: Testing de Respuestas de LLM/IA
--------------------------------------
Problema: Las respuestas de IA nunca son idénticas
Solución: Validación semántica + análisis de sentimiento

Ejemplo:
  Pregunta: "¿Cuál es tu política de devoluciones?"
  Respuesta esperada: "Aceptamos devoluciones dentro de 30 días"
  Respuesta actual: "Puedes devolver productos en un plazo de 30 días desde la compra"
  
  Validaciones:
    - Similitud semántica > 0.75 ✅
    - Sentimiento: neutral ✅
    - Idioma: español ✅


===========================================
13. COMBINANDO FUNCIONALIDADES
===========================================

Puedes combinar múltiples validaciones semánticas en un solo flujo:

Ejemplo Completo: Análisis de Comentario de Usuario
--------------------------------------------------

Scenario: Análisis completo de comentario
  Given navego a "https://example.com/reviews"
  And uso la configuración semántica por defecto
  
  # 1. Extraer comentario
  When extraigo el texto del elemento "Comentario" en "comentario"
  
  # 2. Detectar idioma
  Then detecto el idioma del texto "${comentario}" y lo guardo en "idioma"
  
  # 3. Analizar sentimiento
  Then el sentimiento de la variable "comentario" debe ser "positivo"
  
  # 4. Clasificar tema
  Then clasifico el texto "${comentario}" en las categorías "producto,servicio,precio,entrega" y guardo el resultado en "tema"
  
  # 5. Buscar respuesta sugerida
  Then busco el texto más similar a "${comentario}" en la lista "Gracias por tu feedback,Lamentamos tu experiencia,Nos alegra que te guste" y lo guardo en "respuesta_sugerida"
  
  # 6. Mostrar resultados
  Then muestro en consola el valor de la variable "idioma"
  Then muestro en consola el valor de la variable "tema"
  Then muestro en consola el valor de la variable "respuesta_sugerida"


===========================================
14. MEJORES PRÁCTICAS AVANZADAS
===========================================

1. Análisis de Sentimiento
--------------------------
✅ Usa textos con carga emocional clara
✅ Considera el contexto cultural
✅ Combina con validación semántica para mejor precisión
❌ No uses para textos muy cortos (< 5 palabras)
❌ No asumas que neutral = negativo

2. Clasificación de Texto
-------------------------
✅ Define categorías mutuamente excluyentes
✅ Usa nombres de categorías descriptivos
✅ Prueba con ejemplos de cada categoría
❌ No uses demasiadas categorías (máx 5-7)
❌ No uses categorías ambiguas

3. Detección de Idioma
---------------------
✅ Usa textos de al menos 10 palabras
✅ Verifica con textos representativos del idioma
✅ Considera dialectos y variaciones regionales
❌ No uses para textos muy cortos
❌ No asumas 100% de precisión con textos mixtos

4. Búsqueda Semántica
--------------------
✅ Usa consultas específicas
✅ Mantén la lista de opciones relevante
✅ Revisa la similitud calculada
❌ No uses listas muy largas (> 20 items)
❌ No esperes matches perfectos

5. Combinación de Funcionalidades
--------------------------------
✅ Usa el orden lógico: idioma → sentimiento → clasificación
✅ Guarda resultados intermedios en variables
✅ Valida cada paso antes de continuar
❌ No hagas demasiadas validaciones en un solo test
❌ No ignores los valores de confianza


===========================================
15. TROUBLESHOOTING AVANZADO
===========================================

Problema: "El sentimiento detectado no es correcto"
--------------------------------------------------
Solución:
1. Verifica que el texto tenga carga emocional clara
2. Prueba con textos más largos (> 10 palabras)
3. Considera el contexto cultural
4. Revisa las similitudes con cada sentimiento

Problema: "La clasificación es incorrecta"
-----------------------------------------
Solución:
1. Verifica que las categorías sean claras y distintas
2. Reduce el número de categorías
3. Usa nombres de categorías más descriptivos
4. Revisa la confianza de la clasificación

Problema: "La detección de idioma falla"
---------------------------------------
Solución:
1. Usa textos más largos (> 15 palabras)
2. Evita textos con palabras en múltiples idiomas
3. Verifica que el idioma esté en la lista soportada
4. Considera usar un modelo especializado en detección de idioma

Problema: "La búsqueda semántica no encuentra el resultado esperado"
-------------------------------------------------------------------
Solución:
1. Verifica que la opción esperada esté en la lista
2. Usa consultas más específicas
3. Revisa todas las similitudes calculadas
4. Considera ajustar la lista de opciones

Problema: "Las validaciones son muy lentas"
------------------------------------------
Solución:
1. Usa un modelo más pequeño (MiniLM en lugar de mpnet)
2. Reduce el número de validaciones por test
3. Cachea resultados cuando sea posible
4. Considera usar GPU si está disponible


===========================================
16. FUNCIONALIDADES NLP AVANZADAS
===========================================

El framework incluye capacidades avanzadas de Procesamiento de Lenguaje Natural (NLP)
usando modelos de Hugging Face Transformers.

EXTRACCIÓN DE ENTIDADES (NER)
-----------------------------

Extrae entidades nombradas de un texto (personas, lugares, organizaciones, fechas, etc.).

Steps disponibles:
1. Extraer y guardar entidades:
   Then extraigo las entidades del texto "Juan García trabaja en Microsoft en Madrid desde 2020" y las guardo en "entidades"

2. Verificar que existe una entidad:
   Then el texto "Juan García trabaja en Microsoft" debe contener la entidad "Microsoft" de tipo "ORG"

Tipos de entidades soportadas:
- PER (Persona): Nombres de personas
- ORG (Organización): Empresas, instituciones
- LOC (Lugar): Ciudades, países, lugares
- MISC (Misceláneo): Otros tipos de entidades

Casos de uso:
✅ Extraer información de formularios
✅ Validar datos de contacto
✅ Analizar documentos legales
✅ Procesar currículums
✅ Extraer información de tickets de soporte

Ejemplo práctico:
----------------
Scenario: Extraer información de un ticket
  Given uso la configuración semántica por defecto
  When extraigo el texto del ticket en "descripcion"
  Then extraigo las entidades del texto "${descripcion}" y las guardo en "entidades"
  And muestro en consola el valor de la variable "entidades"
  # Resultado: {"PER": ["Juan García"], "ORG": ["Microsoft"], "LOC": ["Madrid"]}


RESUMEN AUTOMÁTICO
-----------------

Genera resúmenes automáticos de textos largos.

Steps disponibles:
1. Resumir y guardar:
   Then resumo el texto "Texto largo..." y lo guardo en "resumen"

2. Resumir con longitud específica:
   Then resumo el texto "Texto largo..." con longitud máxima de 50 palabras y lo guardo en "resumen"

Casos de uso:
✅ Resumir artículos largos
✅ Generar descripciones cortas
✅ Crear previews de contenido
✅ Resumir conversaciones de chat
✅ Generar títulos automáticos

Ejemplo práctico:
----------------
Scenario: Generar resumen de artículo
  Given uso la configuración semántica por defecto
  When extraigo el texto del artículo en "articulo"
  Then resumo el texto "${articulo}" con longitud máxima de 100 palabras y lo guardo en "resumen"
  And muestro en consola el valor de la variable "resumen"


TRADUCCIÓN AUTOMÁTICA
---------------------

Traduce textos entre diferentes idiomas.

Idiomas soportados:
- es (Español)
- en (Inglés)
- fr (Francés)
- de (Alemán)
- pt (Portugués)

Steps disponibles:
1. Traducir y guardar:
   Then traduzco el texto "Hello world" de "en" a "es" y lo guardo en "traduccion"

2. Verificar traducción:
   Then el texto "Hello world" traducido de "en" a "es" debe ser semánticamente similar a "Hola mundo"

Casos de uso:
✅ Testing de localización (i18n)
✅ Validar traducciones automáticas
✅ Generar contenido multilingüe
✅ Comparar versiones en diferentes idiomas
✅ Testing de aplicaciones multilingües

Ejemplo práctico:
----------------
Scenario: Validar traducción de mensajes
  Given uso la configuración semántica por defecto
  When extraigo el texto del mensaje en inglés en "mensaje_en"
  Then traduzco el texto "${mensaje_en}" de "en" a "es" y lo guardo en "mensaje_es"
  And el texto de la variable "mensaje_es" debe ser semánticamente similar a "Operación exitosa"


GENERACIÓN DE TEXTO
-------------------

Genera texto automáticamente basado en un prompt.

Steps disponibles:
1. Generar y guardar:
   Then genero texto a partir del prompt "Escribe un mensaje de bienvenida" y lo guardo en "texto_generado"

2. Generar con longitud específica:
   Then genero texto a partir del prompt "Escribe un mensaje" con longitud máxima de 50 palabras y lo guardo en "texto"

Casos de uso:
✅ Generar respuestas automáticas
✅ Crear contenido de prueba
✅ Generar mensajes personalizados
✅ Testing de chatbots
✅ Generar datos de prueba realistas

Ejemplo práctico:
----------------
Scenario: Generar respuesta automática
  Given uso la configuración semántica por defecto
  When el usuario envía un mensaje
  Then genero texto a partir del prompt "Genera una respuesta amable para: ${mensaje_usuario}" y lo guardo en "respuesta"
  And el sentimiento de la variable "respuesta" debe ser "positivo"


ANÁLISIS DE TOXICIDAD
---------------------

Detecta contenido ofensivo, tóxico o inapropiado en textos.

Steps disponibles:
1. Verificar que el texto NO es tóxico:
   Then el texto "Gracias por tu ayuda" no debe ser tóxico

2. Verificar que el texto ES tóxico:
   Then el texto "Contenido ofensivo" debe ser tóxico

3. Calcular y guardar nivel de toxicidad:
   Then calculo la toxicidad del texto "Texto a analizar" y la guardo en "toxicidad"

Casos de uso:
✅ Moderar comentarios de usuarios
✅ Filtrar contenido inapropiado
✅ Validar respuestas de chatbots
✅ Analizar feedback de usuarios
✅ Proteger comunidades online

Ejemplo práctico:
----------------
Scenario: Moderar comentario de usuario
  Given uso la configuración semántica por defecto
  When el usuario envía un comentario
  And extraigo el texto del comentario en "comentario"
  Then el texto de la variable "comentario" no debe ser tóxico
  # Si es tóxico, rechazar el comentario


EXTRACCIÓN DE KEYWORDS
----------------------

Identifica las palabras clave más importantes de un texto.

Steps disponibles:
1. Extraer y guardar keywords:
   Then extraigo las keywords del texto "Python es un lenguaje de programación" y las guardo en "keywords"

2. Extraer número específico de keywords:
   Then extraigo 5 keywords del texto "Texto largo..." y las guardo en "keywords"

Casos de uso:
✅ Generar tags automáticos
✅ Indexar documentos
✅ Crear metadatos
✅ Análisis de contenido
✅ SEO y optimización

Ejemplo práctico:
----------------
Scenario: Generar tags para artículo
  Given uso la configuración semántica por defecto
  When extraigo el texto del artículo en "articulo"
  Then extraigo 10 keywords del texto "${articulo}" y las guardo en "tags"
  And muestro en consola el valor de la variable "tags"
  # Resultado: ["python", "programación", "desarrollo", ...]


CLUSTERING DE TEXTOS
--------------------

Agrupa textos similares en clusters automáticamente.

Steps disponibles:
1. Agrupar textos:
   Then agrupo los textos "texto1,texto2,texto3" en 2 clusters y guardo el resultado en "clusters"

Casos de uso:
✅ Agrupar tickets similares
✅ Organizar documentos por tema
✅ Detectar patrones en feedback
✅ Clasificación no supervisada
✅ Análisis exploratorio de datos

Ejemplo práctico:
----------------
Scenario: Agrupar tickets por tema
  Given uso la configuración semántica por defecto
  When extraigo todos los tickets en "lista_tickets"
  Then agrupo los textos "${lista_tickets}" en 3 clusters y guardo el resultado en "grupos"
  And muestro en consola el valor de la variable "grupos"
  # Resultado: {"cluster_0": ["ticket1", "ticket2"], "cluster_1": [...]}


QUESTION ANSWERING (QA)
-----------------------

Responde preguntas basándose en un contexto dado.

Steps disponibles:
1. Responder pregunta:
   Then respondo la pregunta "¿Cuál es la capital?" basándome en el contexto "Francia es un país. París es su capital." y guardo la respuesta en "respuesta"

Casos de uso:
✅ Extraer información de documentos
✅ Responder FAQs automáticamente
✅ Validar contenido de páginas
✅ Testing de chatbots
✅ Búsqueda de información específica

Ejemplo práctico:
----------------
Scenario: Extraer información de documento
  Given uso la configuración semántica por defecto
  When extraigo el texto del documento en "documento"
  Then respondo la pregunta "¿Cuál es la fecha de vencimiento?" basándome en el contexto "${documento}" y guardo la respuesta en "fecha"
  And muestro en consola el valor de la variable "fecha"


===========================================
17. CASOS DE USO NLP AVANZADOS
===========================================

Caso 1: Procesamiento Completo de Ticket de Soporte
--------------------------------------------------
Problema: Analizar y clasificar tickets automáticamente
Solución: Combinar múltiples funcionalidades NLP

Ejemplo:
  Scenario: Análisis completo de ticket
    Given uso la configuración semántica por defecto
    When extraigo el texto del ticket en "ticket"
    
    # 1. Extraer entidades (cliente, empresa, lugar)
    Then extraigo las entidades del texto "${ticket}" y las guardo en "entidades"
    
    # 2. Detectar idioma
    Then detecto el idioma del texto "${ticket}" y lo guardo en "idioma"
    
    # 3. Analizar sentimiento (urgencia)
    Then el sentimiento de la variable "ticket" debe ser "negativo"
    
    # 4. Verificar toxicidad
    Then el texto de la variable "ticket" no debe ser tóxico
    
    # 5. Extraer keywords (temas principales)
    Then extraigo 5 keywords del texto "${ticket}" y las guardo en "temas"
    
    # 6. Clasificar departamento
    Then clasifico el texto "${ticket}" en las categorías "técnico,producto,facturación" y guardo el resultado en "departamento"
    
    # 7. Generar resumen
    Then resumo el texto "${ticket}" con longitud máxima de 50 palabras y lo guardo en "resumen"


Caso 2: Moderación de Contenido Multilingüe
------------------------------------------
Problema: Moderar comentarios en múltiples idiomas
Solución: Detectar idioma + toxicidad + sentimiento

Ejemplo:
  Scenario: Moderar comentario
    Given uso la configuración semántica por defecto
    When extraigo el comentario en "comentario"
    
    # 1. Detectar idioma
    Then detecto el idioma del texto "${comentario}" y lo guardo en "idioma"
    
    # 2. Verificar toxicidad
    Then el texto de la variable "comentario" no debe ser tóxico
    
    # 3. Analizar sentimiento
    Then el sentimiento de la variable "comentario" debe ser "positivo"
    
    # Si pasa todas las validaciones, aprobar comentario


Caso 3: Generación de Respuestas Automáticas
-------------------------------------------
Problema: Responder automáticamente a preguntas frecuentes
Solución: Question Answering + Generación de texto

Ejemplo:
  Scenario: Responder FAQ automáticamente
    Given uso la configuración semántica por defecto
    When el usuario pregunta "¿Cuál es el horario?"
    
    # 1. Buscar respuesta en FAQ
    Then respondo la pregunta "${pregunta}" basándome en el contexto "${faq_documento}" y guardo la respuesta en "respuesta_base"
    
    # 2. Generar respuesta personalizada
    Then genero texto a partir del prompt "Reformula de manera amable: ${respuesta_base}" y lo guardo en "respuesta_final"
    
    # 3. Validar sentimiento
    Then el sentimiento de la variable "respuesta_final" debe ser "positivo"


Caso 4: Análisis de Documentos Legales
-------------------------------------
Problema: Extraer información clave de contratos
Solución: NER + Question Answering + Keywords

Ejemplo:
  Scenario: Analizar contrato
    Given uso la configuración semántica por defecto
    When extraigo el texto del contrato en "contrato"
    
    # 1. Extraer entidades (partes, fechas, lugares)
    Then extraigo las entidades del texto "${contrato}" y las guardo en "entidades"
    
    # 2. Responder preguntas específicas
    Then respondo la pregunta "¿Cuál es la fecha de inicio?" basándome en el contexto "${contrato}" y guardo la respuesta en "fecha_inicio"
    Then respondo la pregunta "¿Cuál es el monto?" basándome en el contexto "${contrato}" y guardo la respuesta en "monto"
    
    # 3. Extraer términos clave
    Then extraigo 10 keywords del texto "${contrato}" y las guardo en "terminos_clave"


Caso 5: Testing de Localización Avanzado
---------------------------------------
Problema: Validar traducciones en múltiples idiomas
Solución: Traducción + Validación semántica

Ejemplo:
  Scenario: Validar traducciones
    Given uso la configuración semántica por defecto
    When extraigo el texto en inglés en "texto_en"
    
    # 1. Traducir a español
    Then traduzco el texto "${texto_en}" de "en" a "es" y lo guardo en "texto_es"
    
    # 2. Validar traducción
    Then el texto de la variable "texto_es" debe ser semánticamente similar a "Operación exitosa"
    
    # 3. Traducir a francés
    Then traduzco el texto "${texto_en}" de "en" a "fr" y lo guardo en "texto_fr"
    
    # 4. Validar traducción
    Then el texto de la variable "texto_fr" debe ser semánticamente similar a "Opération réussie"


Caso 6: Organización Automática de Documentos
--------------------------------------------
Problema: Clasificar y organizar documentos por tema
Solución: Keywords + Clustering + Clasificación

Ejemplo:
  Scenario: Organizar documentos
    Given uso la configuración semántica por defecto
    When extraigo todos los documentos en "documentos"
    
    # 1. Extraer keywords de cada documento
    Then extraigo 5 keywords del texto "${documento_1}" y las guardo en "keywords_1"
    
    # 2. Agrupar documentos similares
    Then agrupo los textos "${documentos}" en 5 clusters y guardo el resultado en "grupos"
    
    # 3. Clasificar por categoría
    Then clasifico el texto "${documento_1}" en las categorías "legal,técnico,comercial,administrativo" y guardo el resultado en "categoria"


===========================================
18. MEJORES PRÁCTICAS NLP
===========================================

1. Extracción de Entidades (NER)
-------------------------------
✅ Usa textos con contexto suficiente
✅ Verifica que las entidades estén bien formadas
✅ Considera variaciones de nombres (Juan vs Juan García)
❌ No uses para textos muy cortos (< 10 palabras)
❌ No asumas 100% de precisión

2. Resumen Automático
--------------------
✅ Usa textos de al menos 100 palabras
✅ Especifica longitud máxima apropiada
✅ Valida que el resumen mantenga información clave
❌ No uses para textos ya cortos
❌ No esperes resúmenes perfectos

3. Traducción Automática
------------------------
✅ Valida traducciones con similitud semántica
✅ Considera variaciones culturales
✅ Prueba con textos representativos
❌ No uses para textos técnicos complejos
❌ No asumas traducción literal

4. Generación de Texto
---------------------
✅ Usa prompts claros y específicos
✅ Especifica longitud máxima
✅ Valida el contenido generado
❌ No uses para contenido crítico sin revisión
❌ No esperes resultados determinísticos

5. Análisis de Toxicidad
-----------------------
✅ Usa umbrales apropiados (0.7-0.8)
✅ Considera falsos positivos
✅ Combina con revisión humana para casos críticos
❌ No uses como único filtro
❌ No asumas 100% de precisión

6. Extracción de Keywords
------------------------
✅ Especifica número apropiado de keywords (5-10)
✅ Usa textos con contenido sustancial
✅ Valida relevancia de keywords extraídas
❌ No uses para textos muy cortos
❌ No esperes keywords perfectas

7. Clustering de Textos
----------------------
✅ Usa número apropiado de clusters (2-5)
✅ Valida que los clusters tengan sentido
✅ Considera usar keywords para entender clusters
❌ No uses demasiados clusters
❌ No asumas clusters perfectos

8. Question Answering
--------------------
✅ Proporciona contexto suficiente
✅ Haz preguntas específicas
✅ Valida que la respuesta esté en el contexto
❌ No hagas preguntas ambiguas
❌ No esperes respuestas si no hay información


===========================================
19. TROUBLESHOOTING NLP
===========================================

Problema: "Las entidades extraídas no son correctas"
--------------------------------------------------
Solución:
1. Verifica que el texto tenga contexto suficiente
2. Usa textos más largos (> 20 palabras)
3. Considera usar un modelo NER especializado
4. Valida manualmente algunos casos

Problema: "El resumen es muy corto o muy largo"
----------------------------------------------
Solución:
1. Ajusta el parámetro de longitud máxima
2. Usa textos de entrada más largos
3. Verifica que el texto tenga contenido sustancial
4. Considera usar un modelo de resumen diferente

Problema: "La traducción no es precisa"
--------------------------------------
Solución:
1. Usa validación semántica en lugar de exacta
2. Considera variaciones culturales
3. Prueba con un modelo de traducción especializado
4. Valida con hablantes nativos

Problema: "El texto generado no tiene sentido"
--------------------------------------------
Solución:
1. Mejora el prompt (más específico)
2. Ajusta la longitud máxima
3. Usa un modelo de generación más grande
4. Considera usar temperatura más baja

Problema: "El análisis de toxicidad da falsos positivos"
-------------------------------------------------------
Solución:
1. Ajusta el umbral de toxicidad (aumentar a 0.8-0.9)
2. Considera el contexto del texto
3. Usa revisión humana para casos límite
4. Prueba con un modelo de toxicidad diferente

Problema: "Las keywords extraídas no son relevantes"
---------------------------------------------------
Solución:
1. Aumenta el número de keywords extraídas
2. Usa textos más largos y con más contenido
3. Considera usar un modelo especializado
4. Valida manualmente la relevancia

Problema: "Los clusters no tienen sentido"
-----------------------------------------
Solución:
1. Ajusta el número de clusters
2. Usa textos más diversos
3. Considera usar keywords para entender clusters
4. Valida manualmente algunos casos

Problema: "Question Answering no encuentra la respuesta"
-------------------------------------------------------
Solución:
1. Verifica que la respuesta esté en el contexto
2. Reformula la pregunta
3. Proporciona más contexto
4. Usa un modelo QA más grande

Problema: "Los modelos NLP son muy lentos"
-----------------------------------------
Solución:
1. Usa modelos más pequeños
2. Procesa textos más cortos
3. Considera usar GPU
4. Cachea resultados cuando sea posible

Problema: "Error al cargar modelos de Hugging Face"
--------------------------------------------------
Solución:
1. Verifica conexión a internet (primera carga)
2. Instala transformers: pip install transformers
3. Verifica espacio en disco (modelos ~500MB-2GB)
4. Considera usar modelos más pequeños


===========================================
20. CONFIGURACIÓN DE MODELOS NLP
===========================================

El framework usa modelos de Hugging Face que se descargan automáticamente
la primera vez que se usan.

Modelos utilizados por defecto:
------------------------------

1. NER (Extracción de Entidades):
   - Modelo: dslim/bert-base-NER
   - Tamaño: ~400MB
   - Idiomas: Inglés (funciona razonablemente en español)

2. Resumen:
   - Modelo: facebook/bart-large-cnn
   - Tamaño: ~1.6GB
   - Idiomas: Inglés

3. Traducción:
   - Modelo: Helsinki-NLP/opus-mt-{src}-{tgt}
   - Tamaño: ~300MB por par de idiomas
   - Idiomas: es, en, fr, de, pt

4. Generación:
   - Modelo: gpt2
   - Tamaño: ~500MB
   - Idiomas: Inglés (funciona en español)

5. Toxicidad:
   - Modelo: unitary/toxic-bert
   - Tamaño: ~400MB
   - Idiomas: Inglés (funciona en español)

6. Keywords:
   - Modelo: KeyBERT con paraphrase-multilingual-MiniLM-L12-v2
   - Tamaño: ~420MB
   - Idiomas: Multilingüe

7. Question Answering:
   - Modelo: deepset/roberta-base-squad2
   - Tamaño: ~500MB
   - Idiomas: Inglés

Requisitos de sistema:
---------------------
- RAM: Mínimo 8GB (recomendado 16GB)
- Disco: ~5GB para todos los modelos
- GPU: Opcional (acelera procesamiento 10-50x)
- Internet: Requerido para primera descarga

Optimización:
------------
- Los modelos se cachean localmente después de la primera descarga
- Usa modelos más pequeños si la RAM es limitada
- Considera usar GPU para procesamiento intensivo
- Cachea resultados cuando sea posible


===========================================
FIN DE LA GUÍA COMPLETA
===========================================

Para más información:
- Documentación básica: Ver secciones 1-10
- Funcionalidades avanzadas: Ver secciones 11-15
- Funcionalidades NLP: Ver secciones 16-20
- Ejemplos de uso: Ver archivos .feature en examples/
- Soporte: GitHub Issues del proyecto

Versión de la guía: 2.0
Última actualización: Incluye funcionalidades NLP completas
