===========================================
INICIO RÁPIDO - VALIDACIÓN SEMÁNTICA
Framework Hakalab - Sentence Transformers
===========================================

¿QUÉ ES LA VALIDACIÓN SEMÁNTICA?
=================================

La validación semántica te permite verificar que dos textos tienen el mismo SIGNIFICADO,
sin necesidad de que sean idénticos palabra por palabra. Esto es perfecto para:

✅ Validar respuestas de LLMs (ChatGPT, Claude, Gemini, etc.)
✅ Probar chatbots con respuestas dinámicas
✅ Validar mensajes que cambian pero mantienen el sentido
✅ Testing de aplicaciones multilingües

En lugar de comparar texto exacto:
  ❌ "Tu solicitud fue aprobada" == "Solicitud aprobada exitosamente"  → FALLA

Comparamos el SIGNIFICADO:
  ✅ "Tu solicitud fue aprobada" ≈ "Solicitud aprobada exitosamente"  → PASA (85% similar)

===========================================
CONFIGURACIÓN INICIAL
===========================================

PASO 1: Instalar Dependencias
------------------------------

pip install sentence-transformers torch

O instalar el framework completo:
pip install haka-playwright-engine[all]

PASO 2: Configurar Variables de Entorno (Opcional)
---------------------------------------------------

Crea o edita el archivo .env en la raíz de tu proyecto:

# Validación Semántica
SEMANTIC_MODEL=paraphrase-multilingual-MiniLM-L12-v2
SEMANTIC_THRESHOLD=0.75

Si no configuras estas variables, el framework usará estos valores por defecto.

Modelos disponibles:
- paraphrase-multilingual-MiniLM-L12-v2 (multilingüe, balanceado, ~420MB) ← RECOMENDADO
- paraphrase-multilingual-mpnet-base-v2 (multilingüe, más preciso, ~1GB)
- all-MiniLM-L6-v2 (solo inglés, rápido, ~80MB)

Umbrales recomendados:
- 0.75: Validación estándar (recomendado)
- 0.85: Validación estricta
- 0.70: Validación flexible

===========================================
EJEMPLO PASO A PASO
===========================================

PASO 1: Crear tu Feature
-------------------------

Crea un archivo: features/test_chatbot.feature

Feature: Testing de Chatbot con Validación Semántica

  Scenario: Validar respuesta de bienvenida
    # Configurar el modelo y umbral (carga desde .env o usa valores por defecto)
    Given uso la configuración semántica por defecto
    
    # Interactuar con tu chatbot/LLM
    When hago click en el elemento "Iniciar Chat" con identificador "$.CHAT.start_button"
    And espero 2 segundos
    
    # Extraer la respuesta del chatbot
    And extraigo el texto del elemento "Mensaje Bot" con identificador "$.CHAT.bot_message" y lo guardo en "respuesta_bot"
    
    # Validar semánticamente (no necesita ser texto exacto)
    Then el texto de la variable "respuesta_bot" debe ser semánticamente similar a "Hola, ¿en qué puedo ayudarte hoy?"


PASO 2: Ejecutar el Test
-------------------------

behave features/test_chatbot.feature

PASO 3: Ver Resultados
-----------------------

El framework mostrará:

📋 Cargando configuración semántica desde .env
   Modelo: paraphrase-multilingual-MiniLM-L12-v2
   Umbral: 0.75

🤖 Modelo semántico configurado: paraphrase-multilingual-MiniLM-L12-v2
📊 Umbral de similitud establecido: 0.75

✓ Configuración semántica cargada
  Modelo: paraphrase-multilingual-MiniLM-L12-v2 (~420MB, se descarga automáticamente la primera vez)
  Umbral: 0.75 (75% de similitud mínima)

✓ Texto extraído: "¡Hola! ¿Cómo puedo asistirte hoy?"

✓ Validación semántica:
  Texto esperado: "Hola, ¿en qué puedo ayudarte hoy?"
  Texto actual: "¡Hola! ¿Cómo puedo asistirte hoy?"
  Similitud: 0.87 (umbral: 0.75)
  Resultado: ✓ PASS

===========================================
EJEMPLO COMPLETO CON CONFIGURACIÓN PERSONALIZADA
===========================================

Opción 1: Configurar en .env (Recomendado)
-------------------------------------------

Edita tu archivo .env:

SEMANTIC_MODEL=paraphrase-multilingual-mpnet-base-v2
SEMANTIC_THRESHOLD=0.85

Luego en tu feature:

Feature: Testing Avanzado de Chatbot

  Scenario: Validar respuesta con configuración desde .env
    # Carga automáticamente desde .env
    Given uso la configuración semántica por defecto
    
    When escribo "¿Cuál es el horario de atención?" en el elemento "Input Chat" con identificador "$.CHAT.input"
    And hago click en el elemento "Enviar" con identificador "$.CHAT.send_button"
    And espero 3 segundos
    And extraigo el texto del elemento "Respuesta" con identificador "$.CHAT.response" y lo guardo en "respuesta"
    
    Then el texto de la variable "respuesta" debe ser semánticamente similar a "Nuestro horario es de lunes a viernes de 9am a 6pm"


Opción 2: Configurar manualmente en el feature
-----------------------------------------------

Si quieres sobrescribir la configuración del .env para un test específico:

Feature: Testing Avanzado de Chatbot

  Scenario: Validar respuesta con umbral personalizado
    # Configurar modelo específico (sobrescribe .env)
    Given configuro el modelo semántico como "paraphrase-multilingual-MiniLM-L12-v2"
    
    # Establecer umbral más estricto (sobrescribe .env)
    And establezco el umbral de similitud semántica en 0.85
    
    When escribo "¿Cuál es el horario de atención?" en el elemento "Input Chat" con identificador "$.CHAT.input"
    And hago click en el elemento "Enviar" con identificador "$.CHAT.send_button"
    And espero 3 segundos
    And extraigo el texto del elemento "Respuesta" con identificador "$.CHAT.response" y lo guardo en "respuesta"
    
    Then el texto de la variable "respuesta" debe ser semánticamente similar a "Nuestro horario es de lunes a viernes de 9am a 6pm"
    
    # Opcional: Calcular y guardar la similitud exacta
    And calculo la similitud semántica entre "${respuesta}" y "Nuestro horario es de lunes a viernes de 9am a 6pm" y la guardo en "score"
    And muestro en consola el valor de la variable "score"

===========================================
EJEMPLO CON VALIDACIÓN DIRECTA DE TEXTO
===========================================

Feature: Validación Directa sin Navegador

  Scenario: Validar respuesta de API o LLM
    Given uso la configuración semántica por defecto
    
    # Simular que obtuviste una respuesta de tu LLM/API
    When establezco la variable "respuesta_llm" con el valor "Tu pedido ha sido procesado correctamente y será enviado en 24 horas"
    
    # Validar semánticamente
    Then el texto de la variable "respuesta_llm" debe ser semánticamente similar a "Pedido procesado, envío en 24h"
    
    # Resultado: ✓ PASS (similitud ~0.82)
    # Aunque las palabras son diferentes, el significado es el mismo

===========================================
EJEMPLO CON MÚLTIPLES VALIDACIONES
===========================================

Feature: Testing de Múltiples Respuestas

  Background:
    Given uso la configuración semántica por defecto

  Scenario: Validar varias respuestas del chatbot
    # Pregunta 1
    When escribo "¿Aceptan devoluciones?" en el chat
    And extraigo la respuesta en "respuesta1"
    Then el texto de la variable "respuesta1" debe ser semánticamente similar a "Sí, aceptamos devoluciones dentro de 30 días"
    
    # Pregunta 2
    When escribo "¿Cuánto cuesta el envío?" en el chat
    And extraigo la respuesta en "respuesta2"
    Then el texto de la variable "respuesta2" debe ser semánticamente similar a "El envío cuesta 5 euros, gratis para pedidos mayores a 50 euros"
    
    # Pregunta 3
    When escribo "¿Qué métodos de pago tienen?" en el chat
    And extraigo la respuesta en "respuesta3"
    Then el texto de la variable "respuesta3" debe ser semánticamente similar a "Aceptamos tarjeta, PayPal y transferencia bancaria"

===========================================
CONFIGURACIÓN DE UMBRALES
===========================================

El umbral determina qué tan similar debe ser el texto para pasar:

0.90 - 1.00: Casi idéntico
  Ejemplo: "Hola" vs "Hola, buenos días" → 0.92
  Uso: Validación muy estricta

0.75 - 0.89: Alta similitud (RECOMENDADO POR DEFECTO)
  Ejemplo: "Pedido aprobado" vs "Tu pedido fue aprobado exitosamente" → 0.82
  Uso: Validación estándar de chatbots/LLMs

0.60 - 0.74: Similitud moderada
  Ejemplo: "Sistema funcionando" vs "Todo está operativo" → 0.68
  Uso: Validación flexible

0.40 - 0.59: Similitud baja
  Ejemplo: "Error" vs "Hubo un problema" → 0.55
  Uso: Categorización amplia

Cómo configurar:

Opción 1 - En .env (Recomendado):
  SEMANTIC_THRESHOLD=0.75

Opción 2 - En el feature:
  And establezco el umbral de similitud semántica en 0.85

Recomendación:
- Empieza con 0.75 (por defecto en .env)
- Ajusta según tus resultados
- Usa 0.85 para validación estricta
- Usa 0.70 para validación flexible

===========================================
MODELOS DISPONIBLES
===========================================

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

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

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

Cómo configurar:

Opción 1 - En .env (Recomendado):
  SEMANTIC_MODEL=paraphrase-multilingual-MiniLM-L12-v2

Opción 2 - En el feature:
  Given configuro el modelo semántico como "paraphrase-multilingual-mpnet-base-v2"

===========================================
TIPS Y MEJORES PRÁCTICAS
===========================================

1. CONFIGURACIÓN INICIAL
------------------------
✅ Configura SEMANTIC_MODEL y SEMANTIC_THRESHOLD en tu .env
✅ Usa "uso la configuración semántica por defecto" en tus features
✅ Sobrescribe valores solo cuando necesites configuración específica
✅ Mantén la configuración centralizada en .env para consistencia

2. PRIMERA VEZ
--------------
✅ Empieza con la configuración por defecto (.env)
✅ Prueba con textos que SÍ deberían pasar
✅ Ajusta el umbral en .env según resultados
✅ Documenta por qué elegiste cada valor

3. DEBUGGING
------------
✅ Usa "calculo la similitud" para ver el score exacto
✅ Muestra el score en consola para análisis
✅ Si falla, revisa el score y ajusta el umbral en .env
✅ Verifica que el modelo cargado es el correcto

4. PERFORMANCE
--------------
✅ El modelo se descarga una sola vez (~420MB)
✅ Después es muy rápido (milisegundos)
✅ Reutiliza el mismo modelo en todos los tests
✅ No necesitas GPU (pero acelera si la tienes)

5. CASOS DE USO
---------------
✅ Chatbots con respuestas dinámicas
✅ LLMs (GPT, Claude, Gemini, etc.)
✅ Sistemas de IA generativa
✅ Aplicaciones multilingües
✅ Mensajes con IDs o timestamps variables

===========================================
TROUBLESHOOTING
===========================================

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

Error: "El modelo tarda mucho en cargar"
-----------------------------------------
Es normal la primera vez (descarga ~420MB)
Las siguientes veces será instantáneo

Error: "Similitud muy baja"
----------------------------
1. Verifica que usas modelo multilingüe (si es español)
2. Reduce el umbral (prueba 0.70)
3. Revisa que los textos realmente sean similares

Error: "Similitud muy alta para textos diferentes"
---------------------------------------------------
1. Aumenta el umbral (prueba 0.85)
2. Verifica que los textos realmente sean diferentes
3. Considera usar validación exacta en su lugar

===========================================
EJEMPLO COMPLETO REAL
===========================================

Feature: Testing de Chatbot de Soporte

  Background:
    Given navego a "https://mi-app.com/chat"
    And uso la configuración semántica por defecto

  Scenario: Validar respuestas del chatbot
    # Abrir chat
    When hago click en el elemento "Abrir Chat" con identificador "$.CHAT.open_button"
    And espero 2 segundos
    
    # Pregunta 1: Horario
    When escribo "¿Cuál es el horario?" en el elemento "Input" con identificador "$.CHAT.input"
    And hago click en el elemento "Enviar" con identificador "$.CHAT.send"
    And espero 2 segundos
    And extraigo el texto del elemento "Respuesta" con identificador "$.CHAT.last_message" y lo guardo en "resp1"
    Then el texto de la variable "resp1" debe ser semánticamente similar a "Nuestro horario es de lunes a viernes de 9am a 6pm"
    
    # Pregunta 2: Devoluciones
    When escribo "¿Puedo devolver un producto?" en el elemento "Input" con identificador "$.CHAT.input"
    And hago click en el elemento "Enviar" con identificador "$.CHAT.send"
    And espero 2 segundos
    And extraigo el texto del elemento "Respuesta" con identificador "$.CHAT.last_message" y lo guardo en "resp2"
    Then el texto de la variable "resp2" debe ser semánticamente similar a "Sí, puedes devolver productos dentro de 30 días con el recibo"
    
    # Pregunta 3: Contacto
    When escribo "¿Cómo los contacto?" en el elemento "Input" con identificador "$.CHAT.input"
    And hago click en el elemento "Enviar" con identificador "$.CHAT.send"
    And espero 2 segundos
    And extraigo el texto del elemento "Respuesta" con identificador "$.CHAT.last_message" y lo guardo en "resp3"
    Then el texto de la variable "resp3" debe ser semánticamente similar a "Puedes contactarnos por email a soporte@mi-app.com o llamar al 900123456"

===========================================
RESUMEN
===========================================

1. Instala: pip install sentence-transformers torch

2. Usa en tu feature:
   Given uso la configuración semántica por defecto
   Then el texto de la variable "respuesta" debe ser semánticamente similar a "texto esperado"

3. Ejecuta: behave features/tu_feature.feature

4. Ajusta el umbral si es necesario:
   And establezco el umbral de similitud semántica en 0.85

¡Eso es todo! Ahora puedes validar respuestas de IA sin preocuparte por el texto exacto.

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

Documentación completa:
- GUIA_VALIDACION_SEMANTICA_IA.txt (guía completa con todos los detalles)
- REFERENCIA_RAPIDA_NLP.txt (referencia de todos los steps NLP)

Ejemplos:
- semantic_validation_example.feature (ejemplos básicos)
- semantic_advanced_example.feature (ejemplos avanzados)
- semantic_nlp_example.feature (ejemplos de NLP completo)

===========================================
FIN DEL INICIO RÁPIDO
===========================================

Versión: 1.3.0
Última actualización: 2026-02-12


===========================================
OPTIMIZACIÓN: TAG @no_browser
===========================================

Para pruebas que NO necesitan navegador (validación semántica pura, API testing, etc.),
usa el tag @no_browser para mejorar el rendimiento:

Feature: Validación Semántica sin Navegador

  @no_browser
  Scenario: Calcular similitud sin UI
    # Tag @no_browser desactiva el navegador automáticamente
    Given uso la configuración semántica por defecto
    
    # Calcular similitud directamente
    Then calculo la similitud semántica entre "Compra exitosa" y "Tu compra fue exitosa" y la guardo en "similitud"
    And muestro en consola el valor de la variable "similitud"

Beneficios del tag @no_browser:
✅ No abre ventana del navegador
✅ No captura screenshots innecesarios
✅ Mejora el rendimiento significativamente
✅ Reduce consumo de recursos
✅ Evita errores de cierre de navegador
✅ Código más limpio

IMPORTANTE: Usa el tag @no_browser en lugar del step "desactivo el navegador"

Alternativa (step - menos recomendado):
- desactivo el navegador para esta prueba
- no necesito navegador para esta prueba
- I disable browser for this test

Para reactivar el navegador (si usaste el step):
- reactivo el navegador
- necesito el navegador ahora
- I re-enable the browser

Ver guía completa: GUIA_TAG_NO_BROWSER.txt
