===========================================
EJEMPLO COMPLETO: RAG TESTING
Supabase Vector + Gemini como Juez
Haka Playwright Engine v1.3.21
===========================================

DESCRIPCIÓN
-----------
Este ejemplo muestra cómo realizar testing completo de un sistema RAG
(Retrieval Augmented Generation) usando:
- Supabase Vector Database para búsqueda semántica de contexto
- Gemini como Juez para validar la calidad de las respuestas
- Validaciones de hallucinations, tono, completitud y citación

CASOS DE USO
------------
✅ Testing de chatbots con RAG
✅ Validación de respuestas basadas en documentación
✅ Detección de hallucinations (información inventada)
✅ Validación de tono y estilo de comunicación
✅ Testing de consistencia en múltiples preguntas
✅ Validación de citación de fuentes
✅ Testing adversarial (preguntas fuera de contexto)

ESCENARIO DE NEGOCIO
--------------------
Sistema: Chatbot de atención al cliente con RAG
Funcionalidad: Responder preguntas usando knowledge base vectorizada
Objetivo: Validar que las respuestas son precisas, completas y sin alucinaciones

===========================================
ARCHIVOS DE EJEMPLO INCLUIDOS
===========================================

1. rag_supabase_gemini_example.feature
   - 12 escenarios completos de testing RAG
   - Validación con Gemini como Juez
   - Detección de hallucinations
   - Testing multilingüe
   - Validación de tono y estilo

2. vectorize_documents_supabase.py
   - Script para vectorizar documentos
   - Carga automática a Supabase
   - Ejemplo de búsqueda vectorial
   - 10 documentos de ejemplo incluidos

3. context/customer_service_rules.txt
   - Reglas de negocio completas
   - Contexto para Gemini como Juez
   - Políticas de empresa

===========================================
FEATURE FILE COMPLETO
===========================================

# language: es
Feature: Testing de Sistema RAG con Supabase y Gemini
  Como QA Engineer
  Quiero validar que el chatbot responde correctamente usando la knowledge base
  Para asegurar respuestas precisas y sin alucinaciones

  Background:
    Given me conecto a Supabase usando variables de entorno

  @rag @critical @no_browser
  Scenario: Validar respuesta sobre política de devoluciones
    # 1. Buscar contexto relevante en Supabase
    When busco en la tabla "knowledge_base" el contexto más similar a "política de devoluciones" y lo guardo en "kb_context"
    Then verifico que la variable "kb_context" no está vacía
    
    # 2. Hacer pregunta al chatbot con el contexto
    When realizo una petición POST a "${CHATBOT_API}/ask" con el body:
      """
      {
        "question": "¿Cuál es la política de devoluciones?",
        "context": "${kb_context}"
      }
      """
    Then el código de estado de la respuesta debería ser 200
    And extraigo el valor "answer" del JSON de respuesta y lo guardo en "chatbot_answer"
    
    # 3. Cargar contexto en Gemini y validar respuesta
    When establezco la respuesta del SUT como "${chatbot_answer}"
    And cargo la variable "kb_context" como contexto de Gemini "return_policy"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.85
    
    # 4. Validaciones adicionales
    And valido que la respuesta no contiene alucinaciones según el contexto
    And valido que la respuesta está en idioma "español"
    And valido que la intención de la respuesta es "informativa"

  @rag @direct_load @no_browser
  Scenario: Validar horario de atención con carga directa
    # Cargar contexto directamente desde Supabase a Gemini
    Given cargo el contexto de Supabase tabla "knowledge_base" para la query "horario de atención al cliente" en el contexto de Gemini "customer_hours"
    
    # Obtener respuesta del chatbot
    When realizo una petición POST a "${CHATBOT_API}/ask" con el body:
      """
      {
        "question": "¿Cuál es el horario de atención?"
      }
      """
    And extraigo el valor "answer" del JSON de respuesta y lo guardo en "answer"
    
    # Validar con Gemini
    When establezco la respuesta del SUT como "${answer}"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.9
    And valido que la respuesta no contiene alucinaciones según el contexto

  @rag @multiple_sources @no_browser
  Scenario: Validar respuesta usando múltiples documentos
    # Buscar múltiples documentos relevantes
    When busco en la tabla "knowledge_base" los 3 contextos más similares a "métodos de pago" y los guardo en "payment_docs"
    Then verifico que la variable "payment_docs" es una lista
    
    # Concatenar documentos para contexto
    When concateno los contenidos de "payment_docs" y lo guardo en "payment_context"
    
    # Hacer pregunta al chatbot
    When realizo una petición POST a "${CHATBOT_API}/ask" con el body:
      """
      {
        "question": "¿Qué métodos de pago aceptan?",
        "context": "${payment_context}"
      }
      """
    And extraigo el valor "answer" del JSON de respuesta y lo guardo en "answer"
    
    # Validar respuesta
    When establezco la respuesta del SUT como "${answer}"
    And cargo la variable "payment_context" como contexto de Gemini "payment_methods"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.8
    And valido que la respuesta no contiene alucinaciones según el contexto

  @rag @comparison @no_browser
  Scenario: Comparar respuesta del sistema con respuesta ideal de Gemini
    # 1. Cargar contexto desde Supabase
    Given cargo el contexto de Supabase tabla "knowledge_base" para la query "proceso de envío" en el contexto de Gemini "shipping_process"
    
    # 2. Generar respuesta ideal con Gemini
    When Gemini genera la respuesta para el prompt "¿Cuánto tarda el envío?"
    And guardo la respuesta generada en la variable "ideal_answer"
    
    # 3. Obtener respuesta del sistema
    When realizo una petición POST a "${CHATBOT_API}/ask" con el body:
      """
      {
        "question": "¿Cuánto tarda el envío?"
      }
      """
    And extraigo el valor "answer" del JSON de respuesta y lo guardo en "system_answer"
    
    # 4. Validar con Gemini como Juez
    When establezco la respuesta del SUT como "${system_answer}"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.85
    
    # 5. Comparar similitud semántica con respuesta ideal
    Then el texto "${system_answer}" debe ser semánticamente similar a "${ideal_answer}"
    
    # 6. Validaciones de calidad
    And valido que la respuesta no contiene alucinaciones según el contexto
    And valido que la respuesta está en idioma "español"

  @rag @adversarial @no_browser
  Scenario: Validar que el sistema rechaza preguntas fuera de contexto
    # Cargar contexto específico
    Given cargo el contexto de Supabase tabla "knowledge_base" para la query "política de privacidad" en el contexto de Gemini "privacy_policy"
    
    # Hacer pregunta no relacionada
    When realizo una petición POST a "${CHATBOT_API}/ask" con el body:
      """
      {
        "question": "¿Cuál es la receta de la paella?"
      }
      """
    And extraigo el valor "answer" del JSON de respuesta y lo guardo en "answer"
    
    # Validar que el sistema indica que no puede responder
    When establezco la respuesta del SUT como "${answer}"
    Then valido que la respuesta rechaza el prompt adversarial
    Or valido que la respuesta contiene "no puedo" o "fuera de mi alcance"

  @rag @consistency @no_browser
  Scenario: Validar consistencia entre múltiples respuestas
    Given cargo el contexto de Supabase tabla "knowledge_base" para la query "garantía de productos" en el contexto de Gemini "warranty"
    
    # Hacer la misma pregunta de diferentes formas
    When realizo una petición POST a "${CHATBOT_API}/ask" con el body:
      """
      {
        "question": "¿Cuánto dura la garantía?"
      }
      """
    And extraigo el valor "answer" del JSON de respuesta y lo guardo en "answer1"
    
    When realizo una petición POST a "${CHATBOT_API}/ask" con el body:
      """
      {
        "question": "¿Por cuánto tiempo están garantizados los productos?"
      }
      """
    And extraigo el valor "answer" del JSON de respuesta y lo guardo en "answer2"
    
    # Validar ambas respuestas
    When establezco la respuesta del SUT como "${answer1}"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.8
    
    When establezco la respuesta del SUT como "${answer2}"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.8
    
    # Validar consistencia entre respuestas
    Then valido que las respuestas "answer1" y "answer2" son consistentes

  @rag @json_response @no_browser
  Scenario: Validar respuesta estructurada en JSON
    Given cargo el contexto de Supabase tabla "knowledge_base" para la query "información de contacto" en el contexto de Gemini "contact_info"
    
    # Solicitar respuesta en formato JSON
    When realizo una petición POST a "${CHATBOT_API}/ask" con el body:
      """
      {
        "question": "¿Cómo puedo contactarlos?",
        "format": "json"
      }
      """
    And extraigo el valor "answer" del JSON de respuesta y lo guardo en "answer"
    
    # Validar estructura JSON
    When establezco la respuesta del SUT como "${answer}"
    Then valido que la respuesta del SUT es un JSON válido
    And valido que el JSON de respuesta tiene la estructura "schemas/contact_response.json"
    
    # Validar contenido con Gemini
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.85
    And valido que la respuesta no contiene alucinaciones según el contexto

  @rag @performance @no_browser
  Scenario Outline: Testing de múltiples queries con validación
    Given cargo el contexto de Supabase tabla "knowledge_base" para la query "<topic>" en el contexto de Gemini "test_context"
    
    When realizo una petición POST a "${CHATBOT_API}/ask" con el body:
      """
      {
        "question": "<question>"
      }
      """
    And extraigo el valor "answer" del JSON de respuesta y lo guardo en "answer"
    
    When establezco la respuesta del SUT como "${answer}"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de <threshold>
    And valido que la respuesta no contiene alucinaciones según el contexto
    And valido que la respuesta está en idioma "español"

    Examples:
      | topic                    | question                                  | threshold |
      | política de cancelación  | ¿Puedo cancelar mi pedido?               | 0.85      |
      | proceso de registro      | ¿Cómo me registro en la plataforma?      | 0.80      |
      | soporte técnico          | ¿Cómo contacto con soporte?              | 0.85      |
      | términos y condiciones   | ¿Cuáles son los términos de uso?        | 0.80      |
      | política de privacidad   | ¿Cómo protegen mis datos personales?    | 0.85      |

  @rag @integration @complete @no_browser
  Scenario: Test de integración completo del sistema RAG
    # 1. Verificar conexión a Supabase
    Given me conecto a Supabase usando variables de entorno
    When consulto la tabla "knowledge_base" en Supabase y guardo el resultado en "kb_docs"
    Then verifico que la variable "kb_docs" es una lista
    And verifico que la variable "kb_docs" tiene al menos 10 elementos
    
    # 2. Buscar contexto relevante
    When busco en la tabla "knowledge_base" el contexto más similar a "preguntas frecuentes" y lo guardo en "faq_context"
    Then verifico que la variable "faq_context" no está vacía
    
    # 3. Cargar contexto en Gemini
    When cargo la variable "faq_context" como contexto de Gemini "faq"
    
    # 4. Generar respuesta de referencia
    When Gemini genera la respuesta para el prompt "¿Dónde puedo ver las preguntas frecuentes?"
    And guardo la respuesta generada en la variable "reference_answer"
    
    # 5. Obtener respuesta del sistema
    When realizo una petición POST a "${CHATBOT_API}/ask" con el body:
      """
      {
        "question": "¿Dónde puedo ver las preguntas frecuentes?"
      }
      """
    Then el código de estado de la respuesta debería ser 200
    And extraigo el valor "answer" del JSON de respuesta y lo guardo en "system_answer"
    And extraigo el valor "confidence" del JSON de respuesta y lo guardo en "confidence"
    
    # 6. Validar respuesta con Gemini
    When establezco la respuesta del SUT como "${system_answer}"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.85
    
    # 7. Validaciones de calidad
    And valido que la respuesta no contiene alucinaciones según el contexto
    And valido que la respuesta está en idioma "español"
    And valido que la intención de la respuesta es "informativa"
    
    # 8. Validar similitud con respuesta de referencia
    Then el texto "${system_answer}" debe ser semánticamente similar a "${reference_answer}"
    
    # 9. Validar confianza del sistema
    Then verifico que la variable "confidence" es mayor que 0.7
    
    # 10. Validar metadata de la respuesta
    And extraigo el valor "sources" del JSON de respuesta y lo guardo en "sources"
    Then verifico que la variable "sources" es una lista
    And verifico que la variable "sources" tiene al menos 1 elementos

===========================================
CONFIGURACIÓN NECESARIA
===========================================

ARCHIVO .env
------------
# Supabase
SUPABASE_URL=https://tu-proyecto.supabase.co
SUPABASE_KEY=tu_supabase_key

# Gemini
GEMINI_API_KEY=tu_gemini_api_key

# API del Chatbot
CHATBOT_API=https://api.tu-chatbot.com

ESTRUCTURA DE LA BASE DE DATOS
-------------------------------
Tabla: knowledge_base

Columnas:
- id: BIGSERIAL PRIMARY KEY
- content: TEXT (contenido del documento)
- metadata: JSONB (categoría, fecha, autor, etc.)
- embedding: VECTOR(768) (embedding de Gemini)

Ejemplo de datos:
{
  "id": 1,
  "content": "Nuestra política de devoluciones permite devolver productos dentro de 30 días...",
  "metadata": {
    "category": "policies",
    "subcategory": "returns",
    "last_updated": "2026-03-01"
  },
  "embedding": [0.123, -0.456, ...]
}

SCHEMA DE VALIDACIÓN JSON
--------------------------
Archivo: schemas/contact_response.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["email", "phone", "hours"],
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "phone": {
      "type": "string"
    },
    "hours": {
      "type": "string"
    },
    "address": {
      "type": "string"
    }
  }
}

===========================================
EJECUCIÓN DE LOS TESTS
===========================================

# Ejecutar todos los tests RAG
behave -t @rag

# Ejecutar solo tests críticos
behave -t @rag -t @critical

# Ejecutar test de integración completo
behave -t @integration -t @complete

# Ejecutar con reporte HTML
behave -t @rag -f html -o reports/rag_tests.html

===========================================
MÉTRICAS Y VALIDACIONES
===========================================

UMBRALES RECOMENDADOS
----------------------
- Respuestas críticas (políticas, legal): >= 0.85
- Respuestas informativas (FAQ, ayuda): >= 0.80
- Respuestas generales: >= 0.75

VALIDACIONES CLAVE
------------------
1. ✅ Precisión: Gemini como Juez valida la respuesta
2. ✅ Alucinaciones: Verifica que no inventa información
3. ✅ Idioma: Confirma el idioma correcto
4. ✅ Intención: Valida el tipo de respuesta
5. ✅ Consistencia: Compara múltiples respuestas
6. ✅ Similitud: Compara con respuesta ideal
7. ✅ Estructura: Valida formato JSON si aplica
8. ✅ Confianza: Verifica score de confianza del sistema

CASOS DE FALLO COMUNES
-----------------------
1. Umbral muy bajo: Respuesta incorrecta pero pasa validación
2. Contexto insuficiente: No encuentra documentos relevantes
3. Alucinaciones: Sistema inventa información no en contexto
4. Idioma incorrecto: Responde en idioma diferente al esperado
5. Fuera de alcance: Responde preguntas no relacionadas

===========================================
MEJORES PRÁCTICAS
===========================================

1. PREPARACIÓN DE DATOS
   - Mantén la knowledge base actualizada
   - Usa metadata para filtros adicionales
   - Genera embeddings con el mismo modelo (text-embedding-004)

2. DISEÑO DE TESTS
   - Prueba casos positivos y negativos
   - Incluye preguntas adversariales
   - Valida consistencia entre respuestas similares

3. UMBRALES
   - Ajusta según criticidad de la información
   - Monitorea falsos positivos/negativos
   - Documenta decisiones de umbrales

4. VALIDACIONES
   - Combina múltiples validaciones
   - No confíes solo en un umbral
   - Valida estructura y contenido

5. MANTENIMIENTO
   - Revisa tests fallidos regularmente
   - Actualiza contextos cuando cambie documentación
   - Monitorea métricas de calidad

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

TEST FALLA: "No se encontró contexto relevante"
------------------------------------------------
Causas:
- Query de búsqueda muy específica
- Documentos no tienen embeddings
- Umbral de similitud muy alto

Solución:
- Reformular query de búsqueda
- Verificar embeddings en Supabase
- Reducir umbral de similitud (0.6)

TEST FALLA: "Respuesta no pasa validación de Gemini"
-----------------------------------------------------
Causas:
- Respuesta del sistema incorrecta
- Umbral muy alto
- Contexto incorrecto cargado

Solución:
- Revisar respuesta del sistema
- Ajustar umbral según criticidad
- Verificar que el contexto es relevante

TEST FALLA: "Detecta alucinaciones"
------------------------------------
Causas:
- Sistema inventa información
- Contexto insuficiente
- Modelo del chatbot no confiable

Solución:
- Mejorar contexto en knowledge base
- Ajustar parámetros del modelo
- Agregar más documentos relevantes

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

Documentación:
- GUIA_SUPABASE_VECTOR.txt
- GUIA_TESTING_GEMINI_COMPLETA.txt
- GUIA_VALIDACION_SEMANTICA_IA.txt

Ejemplos:
- supabase_vector_example.feature
- gemini_evaluation_example.feature
- semantic_validation_example.feature

===========================================
VERSIÓN Y SOPORTE
===========================================

Versión: haka-playwright-engine v1.3.17
Última actualización: Marzo 2026

Soporte:
- GitHub: https://github.com/pipefariashaka/haka-playwright-engine
- Email: felipe.farias@hakalab.com
- Documentación: hakalab_framework/documentacion/
