===========================================
GUÍA COMPLETA DE TESTING CON GEMINI
Framework Hakalab - Evaluación de IA Generativa
===========================================

Esta guía explica cómo evaluar respuestas de IA Generativa (LLMs, chatbots, etc.)
usando Gemini como Juez, con Context Caching y optimización de tokens.

===========================================
ÍNDICE
===========================================

1. Introducción
2. Configuración Inicial
3. Conceptos Clave
4. Context Caching vs System Instruction
5. Steps Disponibles
6. Flujo de Trabajo Completo
7. Ejemplos Prácticos
8. Casos de Uso Reales
9. Optimización de Costos
10. Mejores Prácticas
11. Troubleshooting

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

¿Qué es Gemini como Juez?
--------------------------
Gemini como Juez es una técnica donde usamos el modelo Gemini de Google para
evaluar automáticamente las respuestas de otros sistemas de IA (LLMs, chatbots, etc.).

¿Por qué usar Gemini como Juez?
--------------------------------
✅ Evaluación automática de respuestas de IA
✅ Validación de calidad sin intervención humana
✅ Escalable para miles de tests
✅ Consistente y reproducible
✅ Soporta Context Caching para optimizar costos
✅ Evaluación basada en reglas de negocio complejas

¿Cuándo usar esta funcionalidad?
---------------------------------
- Testing de chatbots y asistentes virtuales
- Validación de respuestas de LLMs (GPT, Claude, etc.)
- Evaluación de sistemas de IA generativa
- Testing de calidad de contenido generado
- Validación de cumplimiento de reglas de negocio

Arquitectura del Sistema:
--------------------------
1. SUT (System Under Test): Tu sistema de IA que genera respuestas
2. Contexto de Negocio: Reglas, políticas, ejemplos de respuestas correctas
3. Gemini como Juez: Evalúa si la respuesta del SUT cumple con el contexto
4. Framework: Orquesta todo el proceso y valida resultados

===========================================
2. CONFIGURACIÓN INICIAL
===========================================

Paso 1: Obtener API Key de Gemini
----------------------------------
1. Ve a: https://makersuite.google.com/app/apikey
2. Crea un nuevo proyecto o selecciona uno existente
3. Genera una API Key
4. Copia la API Key

Paso 2: Configurar Variables de Entorno
----------------------------------------
Crea o edita el archivo .env en la raíz de tu proyecto:

# Gemini API Configuration
GEMINI_API_KEY=tu_api_key_aqui
GEMINI_JUDGE_MODEL=gemini-1.5-pro-002
GEMINI_DEFAULT_THRESHOLD=0.8
GEMINI_CACHE_TTL_HOURS=1

Paso 3: Instalar Dependencias
------------------------------
pip install google-genai>=0.1.0

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

Paso 4: Verificar Configuración
--------------------------------
Ejecuta un test simple para verificar que todo funciona:

Feature: Verificar configuración de Gemini
  Scenario: Test básico
    Given el contexto de reglas de negocio "test" está cargado desde el archivo "context/test_rules.txt"
    When establezco la respuesta del SUT como "Hola, ¿en qué puedo ayudarte?"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.7

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

SUT (System Under Test):
-------------------------
El sistema que estás probando. Puede ser:
- Un chatbot
- Un LLM (GPT, Claude, etc.)
- Un sistema de IA generativa
- Cualquier sistema que genere texto

Contexto de Negocio:
--------------------
Archivo de texto que contiene:
- Reglas de negocio
- Políticas de la empresa
- Ejemplos de respuestas correctas
- Criterios de evaluación
- Restricciones y limitaciones

Gemini como Juez:
-----------------
El modelo Gemini que evalúa si la respuesta del SUT cumple con el contexto.
Devuelve un score de 0.0 a 1.0 y una justificación.

Context Caching:
----------------
Técnica de optimización que cachea el contexto de negocio en los servidores
de Google para reducir costos y latencia. Se activa automáticamente para
contextos mayores a 32,000 tokens.

Umbral (Threshold):
-------------------
Valor mínimo de score (0.0 a 1.0) que debe alcanzar la respuesta para
considerarse válida. Ejemplo: 0.8 = 80% de cumplimiento.

===========================================
4. CONTEXT CACHING VS SYSTEM INSTRUCTION
===========================================

El framework decide automáticamente cuál usar según el tamaño del contexto:

Context Caching (Contextos > 32k tokens):
------------------------------------------
✅ Ventajas:
   - Reduce costos significativamente (hasta 90%)
   - Reduce latencia en evaluaciones repetidas
   - Ideal para contextos grandes (reglas extensas)
   - Cache válido por 1 hora (configurable)

❌ Desventajas:
   - Solo disponible para contextos > 32k tokens
   - Requiere tiempo inicial de caching (~30 segundos)
   - Cache expira después del TTL

Cuándo se usa:
- Archivos de contexto > 32,000 tokens
- Múltiples evaluaciones con el mismo contexto
- Reglas de negocio extensas

System Instruction (Contextos < 32k tokens):
---------------------------------------------
✅ Ventajas:
   - Instantáneo (no requiere caching)
   - Más simple de usar
   - Ideal para contextos pequeños

❌ Desventajas:
   - Costos más altos para contextos grandes
   - No optimizado para uso repetido

Cuándo se usa:
- Archivos de contexto < 32,000 tokens
- Evaluaciones únicas o esporádicas
- Contextos simples

Decisión Automática:
--------------------
El framework cuenta los tokens automáticamente y decide:
- Si tokens > 32,000 → Context Caching
- Si tokens < 32,000 → System Instruction

No necesitas hacer nada, el framework lo maneja por ti.

===========================================
5. STEPS DISPONIBLES
===========================================

GESTIÓN DE CONTEXTO:
--------------------

1. Cargar Contexto de Negocio:
   el contexto de reglas de negocio "{context_name}" está cargado desde el archivo "{file_path}"
   que el contexto de reglas de negocio "{context_name}" está cargado desde el archivo "{file_path}"

   Ejemplo:
   Given el contexto de reglas de negocio "chatbot_rules" está cargado desde el archivo "context/chatbot_rules.txt"

2. Cambiar Contexto Activo:
   cambio al contexto de reglas de negocio "{context_name}"

   Ejemplo:
   When cambio al contexto de reglas de negocio "support_rules"

3. Limpiar Cachés:
   limpio todos los cachés de contexto

   Ejemplo:
   When limpio todos los cachés de contexto

INTERACCIÓN CON EL SUT:
-----------------------

4. Interactuar con el SUT:
   interactúo con la IA con el prompt "{user_query}"
   envío el prompt "{user_query}" a la IA

   Ejemplo:
   When interactúo con la IA con el prompt "¿Cuál es el horario de atención?"

5. Establecer Respuesta del SUT Manualmente:
   establezco la respuesta del SUT como "{response_text}"
   la respuesta del SUT es "{response_text}"

   Ejemplo:
   When establezco la respuesta del SUT como "Nuestro horario es de 9am a 6pm"

6. Cargar Respuesta del SUT desde Archivo:
   cargo la respuesta del SUT desde el archivo "{file_path}"

   Ejemplo:
   When cargo la respuesta del SUT desde el archivo "responses/chatbot_response.txt"

EVALUACIÓN CON GEMINI:
----------------------

7. Validar con Umbral:
   el Juez Gemini debe validar la respuesta con un umbral mínimo de {threshold}
   el Juez Gemini valida la respuesta con umbral {threshold}
   el Juez Gemini debe validar la respuesta

   Ejemplo:
   Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.8
   Then el Juez Gemini debe validar la respuesta

8. Validar con Criterios Personalizados:
   el Juez Gemini debe validar la respuesta con criterios personalizados "{criteria}" y umbral {threshold}

   Ejemplo:
   Then el Juez Gemini debe validar la respuesta con criterios personalizados "tono empático,respuesta en menos de 50 palabras" y umbral 0.85

9. Validar Pregunta-Respuesta Directamente (NUEVO):
   valido con Gemini que según el contexto para la pregunta "{pregunta}" la respuesta "{respuesta}" es válida con umbral {threshold}
   el Juez Gemini valida que para la pregunta "{pregunta}" la respuesta "{respuesta}" es correcta con umbral {threshold}

   Ejemplo:
   Then valido con Gemini que según el contexto para la pregunta "¿Cuál es el horario?" la respuesta "Lunes a viernes de 9am a 6pm" es válida con umbral 0.8
   
   Ventajas:
   - Valida pregunta y respuesta en un solo paso
   - Ideal para testing rápido de FAQs
   - No necesitas pasos intermedios para establecer pregunta/respuesta
   - Perfecto para validar múltiples respuestas de tu chatbot

GENERACIÓN DE RESPUESTAS:
--------------------------

10. Generar Respuesta con Gemini (NUEVO):
    Gemini genera la respuesta para el prompt "{user_query}"
    genero la respuesta con Gemini para el prompt "{user_query}"

    Ejemplo:
    When Gemini genera la respuesta para el prompt "¿Cuál es el horario de atención?"
    
    Casos de uso:
    - Generar golden answers (respuestas de referencia)
    - Testing de RAG (comparar tu IA vs Gemini)
    - Crear datasets de entrenamiento automáticamente
    - Validar consistencia de respuestas

GESTIÓN DE RESULTADOS:
----------------------

11. Guardar Evaluación:
    guardo la evaluación del Juez en el archivo "{file_path}"

    Ejemplo:
    And guardo la evaluación del Juez en el archivo "evaluations/test_001.json"

12. Verificar Score Mínimo:
    el score de la última evaluación debe ser mayor o igual a {min_score}

    Ejemplo:
    And el score de la última evaluación debe ser mayor o igual a 0.85

===========================================
6. FLUJO DE TRABAJO COMPLETO
===========================================

Paso 1: Preparar Contexto de Negocio
-------------------------------------
Crea un archivo de texto con las reglas de negocio:

# context/chatbot_rules.txt
Eres un asistente de atención al cliente para una tienda online.

REGLAS OBLIGATORIAS:
1. Siempre saluda de manera amable
2. Responde en español
3. Sé conciso (máximo 100 palabras)
4. Si no sabes algo, deriva al equipo humano
5. Nunca inventes información

INFORMACIÓN CLAVE:
- Horario: Lunes a Viernes 9am-6pm
- Email: soporte@tienda.com
- Teléfono: +34 900 123 456

EJEMPLOS DE RESPUESTAS CORRECTAS:
Q: ¿Cuál es el horario?
A: Nuestro horario de atención es de lunes a viernes de 9am a 6pm.

Q: ¿Cómo contacto con soporte?
A: Puedes contactarnos por email a soporte@tienda.com o llamar al +34 900 123 456.

TIPOS DE DOCUMENTOS QUE PUEDES USAR COMO CONTEXTO:
---------------------------------------------------

✅ **Documentos Técnicos**:
   - Especificaciones de API (OpenAPI, Swagger)
   - Documentación técnica de productos
   - Manuales de usuario
   - Guías de arquitectura
   - Diagramas de flujo (en texto)

✅ **Documentos de Negocio**:
   - Políticas de la empresa
   - Reglas de negocio
   - Términos y condiciones
   - Políticas de privacidad
   - Contratos y acuerdos

✅ **Documentos de Conocimiento**:
   - Base de conocimiento (KB)
   - FAQs completas
   - Guías de estilo
   - Glosarios de términos
   - Procedimientos operativos

✅ **Documentos de Cumplimiento**:
   - Regulaciones (GDPR, HIPAA, etc.)
   - Estándares de calidad (ISO)
   - Códigos de conducta
   - Políticas de seguridad

✅ **Documentos de Producto**:
   - Catálogos de productos
   - Fichas técnicas
   - Especificaciones de características
   - Comparativas de productos

✅ **Documentos de Soporte**:
   - Scripts de atención al cliente
   - Guías de troubleshooting
   - Procedimientos de escalación
   - Plantillas de respuesta

EJEMPLO: Usar Especificación de API como Contexto
--------------------------------------------------

# context/api_specification.txt

API REST de E-commerce v2.0

ENDPOINT: POST /api/orders
Descripción: Crear una nueva orden de compra

Request Body:
{
  "customer_id": "string (required, UUID)",
  "items": [
    {
      "product_id": "string (required, UUID)",
      "quantity": "integer (required, min: 1, max: 100)",
      "price": "number (required, min: 0.01)"
    }
  ],
  "shipping_address": {
    "street": "string (required, max: 200)",
    "city": "string (required, max: 100)",
    "postal_code": "string (required, format: XXXXX)",
    "country": "string (required, ISO 3166-1 alpha-2)"
  },
  "payment_method": "string (required, enum: ['credit_card', 'paypal', 'bank_transfer'])"
}

Response 201 Created:
{
  "order_id": "string (UUID)",
  "status": "string (enum: ['pending', 'confirmed', 'processing'])",
  "total": "number",
  "created_at": "string (ISO 8601 datetime)"
}

Response 400 Bad Request:
{
  "error": "string",
  "details": ["string"]
}

REGLAS DE VALIDACIÓN:
- customer_id debe existir en la base de datos
- Todos los product_id deben existir y estar disponibles
- quantity debe ser positivo y no exceder stock disponible
- price debe coincidir con el precio actual del producto
- postal_code debe ser válido para el país especificado
- payment_method debe ser uno de los valores permitidos

EJEMPLO DE USO:
----------------
Feature: Validar Documentación de API

  Background:
    Given cargo el contexto de negocio "api_spec" desde el archivo "context/api_specification.txt"

  Scenario: Validar respuesta de documentación generada
    When establezco la respuesta del SUT como "Para crear una orden, envía un POST a /api/orders con customer_id, items (product_id, quantity, price), shipping_address y payment_method. Recibirás un order_id y status en la respuesta."
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.85

EJEMPLO: Usar Manual Técnico como Contexto
-------------------------------------------

# context/technical_manual.txt

MANUAL TÉCNICO - SISTEMA DE GESTIÓN DE INVENTARIO v3.5

MÓDULO: Gestión de Stock

FUNCIONALIDAD: Actualización Automática de Stock
-------------------------------------------------

Descripción:
El sistema actualiza automáticamente el stock cuando se realizan las siguientes operaciones:
1. Venta completada: Reduce stock en cantidad vendida
2. Devolución procesada: Incrementa stock en cantidad devuelta
3. Recepción de mercancía: Incrementa stock según albarán
4. Ajuste manual: Modifica stock según autorización

Reglas de Negocio:
- Stock mínimo: 10 unidades (genera alerta automática)
- Stock máximo: 1000 unidades (bloquea recepción adicional)
- Stock de seguridad: 20% del stock mínimo
- Reorden automático: Cuando stock < stock mínimo + stock de seguridad

Alertas:
- CRÍTICA: Stock = 0 (producto agotado)
- ALTA: Stock < stock mínimo (reorden urgente)
- MEDIA: Stock < stock de seguridad (planificar reorden)
- BAJA: Stock > 80% del máximo (revisar espacio)

Permisos Requeridos:
- Consultar stock: ROL_USER
- Ajustar stock: ROL_INVENTORY_MANAGER
- Configurar alertas: ROL_ADMIN

EJEMPLO DE USO:
----------------
Feature: Validar Documentación Técnica Generada

  Background:
    Given cargo el contexto de negocio "tech_manual" desde el archivo "context/technical_manual.txt"

  Scenario: Validar explicación de actualización de stock
    When establezco la respuesta del SUT como "El stock se actualiza automáticamente en ventas, devoluciones y recepciones. Cuando el stock baja del mínimo (10 unidades), se genera una alerta y se activa el reorden automático."
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.85

Paso 2: Crear Feature de Test
------------------------------
Feature: Testing de Chatbot con Gemini

  Background:
    Given el contexto de reglas de negocio "chatbot" está cargado desde el archivo "context/chatbot_rules.txt"

  Scenario: Validar respuesta sobre horario
    When interactúo con la IA con el prompt "¿Cuál es el horario de atención?"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.8
    And guardo la evaluación del Juez en el archivo "evaluations/horario_test.json"

  Scenario: Validar respuesta sobre contacto
    When interactúo con la IA con el prompt "¿Cómo puedo contactar con soporte?"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.8

Paso 3: Ejecutar Tests
-----------------------
behave features/chatbot_test.feature

Paso 4: Revisar Resultados
---------------------------
El framework mostrará:
- Score de evaluación (0.0 a 1.0)
- Justificación de Gemini
- Aspectos positivos
- Aspectos a mejorar
- Resultado: PASS o FAIL

===========================================
7. EJEMPLOS PRÁCTICOS
===========================================

EJEMPLO 1: Testing de Chatbot Básico
-------------------------------------
Feature: Chatbot de Soporte

  Background:
    # Tag @no_browser desactiva el navegador para pruebas de IA sin UI
    Given el contexto de reglas de negocio "support" está cargado desde el archivo "context/support_rules.txt"

  @no_browser
  Scenario: Respuesta sobre devoluciones
    When establezco la respuesta del SUT como "Puedes devolver productos dentro de 30 días desde la compra. Solo necesitas el recibo y el producto en buen estado."
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.8

  Scenario: Respuesta sobre envíos
    When establezco la respuesta del SUT como "Los envíos tardan entre 3-5 días hábiles. El costo es de 5€ para pedidos menores a 50€."
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.8

EJEMPLO 2: Testing con Múltiples Contextos
-------------------------------------------
Feature: Chatbot Multicontexto

  Scenario: Soporte técnico
    Given el contexto de reglas de negocio "tech_support" está cargado desde el archivo "context/tech_support.txt"
    When establezco la respuesta del SUT como "Para resetear tu contraseña, ve a 'Olvidé mi contraseña' en la página de login."
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.85

  Scenario: Ventas
    Given cambio al contexto de reglas de negocio "sales"
    And el contexto de reglas de negocio "sales" está cargado desde el archivo "context/sales_rules.txt"
    When establezco la respuesta del SUT como "Tenemos una promoción del 20% en todos los productos hasta fin de mes."
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.8

EJEMPLO 3: Testing con Criterios Personalizados
------------------------------------------------
Feature: Chatbot con Criterios Específicos

  Background:
    Given el contexto de reglas de negocio "customer_service" está cargado desde el archivo "context/customer_service.txt"

  Scenario: Validar tono empático
    When establezco la respuesta del SUT como "Lamento mucho que hayas tenido esa experiencia. Déjame ayudarte a resolverlo."
    Then el Juez Gemini debe validar la respuesta con criterios personalizados "tono empático,respuesta en menos de 30 palabras" y umbral 0.9

  Scenario: Validar respuesta concisa
    When establezco la respuesta del SUT como "Sí, puedes cambiar tu dirección de envío antes de que se procese el pedido. Ve a 'Mi Cuenta' > 'Pedidos' > 'Editar'."
    Then el Juez Gemini debe validar la respuesta con criterios personalizados "respuesta concisa,incluye pasos claros" y umbral 0.85

EJEMPLO 4: Testing de Respuestas desde Archivo
-----------------------------------------------
Feature: Chatbot con Respuestas Complejas

  Background:
    Given el contexto de reglas de negocio "legal" está cargado desde el archivo "context/legal_terms.txt"

  Scenario: Validar términos y condiciones
    When cargo la respuesta del SUT desde el archivo "responses/terms_response.txt"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.9
    And guardo la evaluación del Juez en el archivo "evaluations/legal_terms_eval.json"
    And el score de la última evaluación debe ser mayor o igual a 0.9

EJEMPLO 5: Testing con Limpieza de Caché
-----------------------------------------
Feature: Testing con Actualización de Contexto

  Scenario: Usar contexto antiguo
    Given el contexto de reglas de negocio "old_rules" está cargado desde el archivo "context/old_rules.txt"
    When establezco la respuesta del SUT como "Respuesta basada en reglas antiguas"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.8

  Scenario: Actualizar y usar nuevo contexto
    Given limpio todos los cachés de contexto
    And el contexto de reglas de negocio "new_rules" está cargado desde el archivo "context/new_rules.txt"
    When establezco la respuesta del SUT como "Respuesta basada en reglas nuevas"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.8

EJEMPLO 6: Validación Directa de Pregunta-Respuesta (NUEVO)
------------------------------------------------------------
Feature: Testing Rápido de FAQs

  Background:
    Given el contexto de reglas de negocio "customer_service" está cargado desde el archivo "context/customer_service.txt"

  Scenario: Validar múltiples FAQs de forma rápida
    # Validar horario de atención
    Then valido con Gemini que según el contexto para la pregunta "¿Cuál es el horario de atención?" la respuesta "Lunes a viernes de 9am a 6pm, sábados de 10am a 2pm" es válida con umbral 0.8
    
    # Validar política de devoluciones
    And el Juez Gemini valida que para la pregunta "¿Puedo devolver un producto?" la respuesta "Sí, aceptamos devoluciones dentro de 30 días con recibo original" es correcta con umbral 0.8
    
    # Validar métodos de pago
    And valido con Gemini que según el contexto para la pregunta "¿Qué métodos de pago aceptan?" la respuesta "Aceptamos tarjetas de crédito, débito, PayPal y transferencia bancaria" es válida con umbral 0.8

  Scenario: Detectar respuestas incorrectas
    # Esta respuesta debería fallar si el contexto dice que no están abiertos 24/7
    Then valido con Gemini que según el contexto para la pregunta "¿Están abiertos los fines de semana?" la respuesta "Sí, estamos abiertos 24/7 todos los días del año" es válida con umbral 0.8

EJEMPLO 7: Generación de Respuestas con Gemini (NUEVO)
-------------------------------------------------------
Feature: Generar Golden Answers

  Background:
    Given el contexto de reglas de negocio "product_docs" está cargado desde el archivo "context/product_documentation.txt"

  Scenario: Generar respuestas de referencia
    # Gemini genera la respuesta basándose en el contexto
    When Gemini genera la respuesta para el prompt "¿Cómo instalo el producto?"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.9
    And guardo la evaluación del Juez en el archivo "golden_answers/instalacion.json"
    
    # Generar otra respuesta
    When Gemini genera la respuesta para el prompt "¿Qué garantía tiene el producto?"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.9
    And guardo la evaluación del Juez en el archivo "golden_answers/garantia.json"

  Scenario: Comparar tu chatbot con Gemini
    # Generar respuesta de referencia con Gemini
    When Gemini genera la respuesta para el prompt "¿Cuáles son los requisitos del sistema?"
    And guardo el valor de la variable "sut_response" en "gemini_answer"
    
    # Tu chatbot responde
    When establezco la respuesta del SUT como "Windows 10 o superior, 8GB RAM, 2GB espacio en disco"
    
    # Evaluar tu respuesta
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.85
    
    # Opcionalmente: Comparar semánticamente
    And el texto de la variable "sut_response" debe ser semánticamente similar a "{gemini_answer}"

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

CASO 1: Testing de Chatbot de E-commerce
-----------------------------------------
Problema: Validar que el chatbot responde correctamente sobre productos, envíos, devoluciones
Solución: Usar Gemini como Juez con contexto de reglas de negocio

Contexto (context/ecommerce_rules.txt):
- Política de devoluciones: 30 días
- Envío gratis para pedidos > 50€
- Horario de atención: 9am-6pm
- Métodos de pago: Tarjeta, PayPal, Transferencia

Tests:
- Validar respuestas sobre devoluciones
- Validar respuestas sobre envíos
- Validar respuestas sobre métodos de pago
- Validar tono amable y profesional

CASO 2: Testing de Asistente Médico Virtual
--------------------------------------------
Problema: Validar que el asistente no da consejos médicos sin licencia
Solución: Usar Gemini con contexto de restricciones legales

Contexto (context/medical_restrictions.txt):
- NUNCA dar diagnósticos
- NUNCA recetar medicamentos
- SIEMPRE derivar a profesional médico
- Solo dar información general de salud

Tests:
- Validar que no da diagnósticos
- Validar que deriva correctamente
- Validar que la información es general y segura

CASO 3: Testing de Chatbot Multilingüe
---------------------------------------
Problema: Validar respuestas en múltiples idiomas
Solución: Usar contextos separados por idioma

Contextos:
- context/rules_es.txt (Español)
- context/rules_en.txt (Inglés)
- context/rules_fr.txt (Francés)

Tests:
- Validar respuestas en español
- Validar respuestas en inglés
- Validar respuestas en francés
- Validar que no mezcla idiomas

CASO 4: Testing de Generación de Contenido
-------------------------------------------
Problema: Validar que el contenido generado cumple con guías de estilo
Solución: Usar Gemini con guías de estilo como contexto

Contexto (context/style_guide.txt):
- Tono: Profesional pero cercano
- Longitud: 100-200 palabras
- Estructura: Introducción, desarrollo, conclusión
- Evitar: Jerga técnica, anglicismos

Tests:
- Validar tono del contenido
- Validar longitud
- Validar estructura
- Validar ausencia de jerga

CASO 5: Testing de Respuestas de FAQ Automáticas
-------------------------------------------------
Problema: Validar que las respuestas automáticas son precisas
Solución: Usar Gemini con base de conocimiento como contexto

Contexto (context/faq_knowledge.txt):
- Preguntas frecuentes y respuestas correctas
- Información de productos
- Políticas de la empresa

Tests:
- Validar precisión de respuestas
- Validar que no inventa información
- Validar que deriva cuando no sabe

CASO 6: Testing de Documentación Técnica Generada por IA
----------------------------------------------------------
Problema: Validar que la documentación generada por IA cumple con estándares técnicos
Solución: Usar especificación técnica completa como contexto

Contexto (context/api_specification.txt):
- Especificación OpenAPI/Swagger completa
- Endpoints, parámetros, respuestas
- Códigos de error y validaciones
- Ejemplos de uso

Tests:
- Validar que la documentación generada es precisa
- Validar que incluye todos los parámetros requeridos
- Validar que los ejemplos son correctos
- Validar que menciona validaciones importantes

Ejemplo:
```gherkin
Feature: Validar Documentación de API Generada

  Background:
    Given cargo el contexto de negocio "api_spec" desde el archivo "context/openapi_spec.txt"

  Scenario: Validar documentación de endpoint POST /orders
    When cargo la respuesta del SUT desde el archivo "generated_docs/post_orders.md"
    Then el Juez Gemini debe validar la respuesta con criterios personalizados "incluye todos los parámetros requeridos,menciona validaciones,incluye ejemplos" y umbral 0.9
    And guardo la evaluación del Juez en el archivo "evaluations/api_docs_eval.json"
```

CASO 7: Testing de Respuestas Técnicas de Soporte
--------------------------------------------------
Problema: Validar que el soporte técnico da respuestas correctas según manual
Solución: Usar manual técnico completo como contexto

Contexto (context/technical_manual.txt):
- Manual técnico del producto (puede ser muy extenso)
- Procedimientos de troubleshooting
- Especificaciones técnicas
- Diagramas de arquitectura (en texto)

Tests:
- Validar que las respuestas son técnicamente correctas
- Validar que siguen los procedimientos establecidos
- Validar que mencionan las precauciones necesarias
- Validar que no omiten pasos críticos

Ejemplo:
```gherkin
Feature: Validar Respuestas de Soporte Técnico

  Background:
    Given cargo el contexto de negocio "tech_manual" desde el archivo "context/product_manual_v3.txt"

  Scenario: Validar respuesta sobre configuración de red
    When establezco la respuesta del SUT como "Para configurar la red, accede a Settings > Network > Configure. Ingresa la IP estática, máscara de subred y gateway. Guarda y reinicia el dispositivo."
    Then el Juez Gemini debe validar la respuesta con criterios personalizados "técnicamente correcta,incluye todos los pasos,menciona reinicio necesario" y umbral 0.9
```

CASO 8: Testing de Cumplimiento Regulatorio
--------------------------------------------
Problema: Validar que las respuestas cumplen con regulaciones (GDPR, HIPAA, etc.)
Solución: Usar documento de regulación como contexto

Contexto (context/gdpr_compliance.txt):
- Artículos relevantes de GDPR
- Políticas de privacidad de la empresa
- Procedimientos de manejo de datos
- Restricciones y obligaciones

Tests:
- Validar que no se solicita información prohibida
- Validar que se menciona el derecho a la privacidad
- Validar que se explica el uso de datos
- Validar que se ofrece opción de opt-out

Ejemplo:
```gherkin
Feature: Validar Cumplimiento GDPR

  Background:
    Given cargo el contexto de negocio "gdpr" desde el archivo "context/gdpr_compliance.txt"

  Scenario: Validar respuesta sobre recolección de datos
    When establezco la respuesta del SUT como "Recolectamos tu email y nombre para enviarte actualizaciones. Puedes darte de baja en cualquier momento. Tus datos están protegidos según GDPR."
    Then el Juez Gemini debe validar la respuesta con criterios personalizados "cumple GDPR,menciona opt-out,explica uso de datos" y umbral 0.95
```

CASO 9: Testing de Documentación de Código Generada
----------------------------------------------------
Problema: Validar que la documentación de código generada es precisa y útil
Solución: Usar código fuente como contexto

Contexto (context/source_code.txt):
- Código fuente completo de la función/clase
- Comentarios existentes
- Tests unitarios
- Dependencias y tipos

Tests:
- Validar que la documentación describe correctamente la función
- Validar que menciona todos los parámetros
- Validar que explica el valor de retorno
- Validar que menciona excepciones posibles

Ejemplo:
```gherkin
Feature: Validar Documentación de Código

  Background:
    Given cargo el contexto de negocio "source_code" desde el archivo "context/user_service.py"

  Scenario: Validar docstring generado para create_user
    When establezco la respuesta del SUT como "Crea un nuevo usuario en el sistema. Parámetros: username (str), email (str), password (str). Retorna: User object. Lanza: ValueError si el email es inválido, UserExistsError si el usuario ya existe."
    Then el Juez Gemini debe validar la respuesta con criterios personalizados "describe función correctamente,menciona todos los parámetros,menciona excepciones" y umbral 0.9
```

CASO 10: Testing de Traducciones Técnicas
------------------------------------------
Problema: Validar que las traducciones técnicas mantienen precisión
Solución: Usar documento técnico original como contexto

Contexto (context/technical_doc_en.txt):
- Documento técnico en idioma original (inglés)
- Terminología técnica específica
- Acrónimos y abreviaturas

Tests:
- Validar que la traducción es técnicamente precisa
- Validar que mantiene la terminología correcta
- Validar que no pierde información crítica
- Validar que los acrónimos se manejan correctamente

Ejemplo:
```gherkin
Feature: Validar Traducción Técnica

  Background:
    Given cargo el contexto de negocio "tech_doc_en" desde el archivo "context/api_docs_english.txt"

  Scenario: Validar traducción al español
    When cargo la respuesta del SUT desde el archivo "translations/api_docs_spanish.txt"
    Then el Juez Gemini debe validar la respuesta con criterios personalizados "traducción precisa,mantiene terminología técnica,no pierde información" y umbral 0.9
```

===========================================
9. OPTIMIZACIÓN DE COSTOS
===========================================

Context Caching:
----------------
✅ Usa Context Caching para contextos > 32k tokens
✅ Reutiliza el mismo contexto en múltiples tests
✅ Configura TTL apropiado (1-24 horas)
✅ Limpia cachés cuando actualices el contexto

Costos Aproximados (Gemini 1.5 Pro):
-------------------------------------
Sin Context Caching:
- Input: $3.50 por 1M tokens
- Output: $10.50 por 1M tokens

Con Context Caching:
- Cached Input: $0.35 por 1M tokens (90% descuento)
- Regular Input: $3.50 por 1M tokens
- Output: $10.50 por 1M tokens

Ejemplo de Ahorro:
------------------
Contexto: 100,000 tokens
Tests: 100 evaluaciones

Sin caching:
100 tests × 100k tokens × $3.50/1M = $35

Con caching:
1 cache × 100k tokens × $3.50/1M = $0.35
99 tests × 100k tokens × $0.35/1M = $3.47
Total = $3.82 (89% ahorro)

Tips para Reducir Costos:
--------------------------
✅ Agrupa tests que usan el mismo contexto
✅ Usa contextos concisos pero completos
✅ Configura TTL según frecuencia de tests
✅ Limpia cachés de contextos obsoletos
✅ Usa umbrales apropiados (no muy bajos)

===========================================
10. MEJORES PRÁCTICAS
===========================================

1. CONTEXTO DE NEGOCIO
----------------------
✅ Sé específico y claro en las reglas
✅ Incluye ejemplos de respuestas correctas
✅ Define restricciones explícitamente
✅ Actualiza el contexto cuando cambien las reglas
✅ Versiona tus archivos de contexto

2. UMBRALES
-----------
✅ Usa 0.8 para validación estándar
✅ Usa 0.9+ para validación estricta
✅ Usa 0.7 para validación flexible
✅ Ajusta según resultados reales
✅ Documenta por qué elegiste cada umbral

3. ORGANIZACIÓN DE TESTS
-------------------------
✅ Agrupa tests por contexto
✅ Usa Background para cargar contexto común
✅ Nombra escenarios descriptivamente
✅ Guarda evaluaciones para análisis
✅ Revisa evaluaciones fallidas manualmente

4. MANTENIMIENTO
----------------
✅ Revisa evaluaciones periódicamente
✅ Actualiza contextos cuando cambien reglas
✅ Limpia cachés después de actualizaciones
✅ Monitorea costos de API
✅ Documenta cambios en contextos

5. DEBUGGING
------------
✅ Guarda evaluaciones en archivos JSON
✅ Revisa justificaciones de Gemini
✅ Ajusta umbrales basándote en resultados
✅ Prueba respuestas manualmente primero
✅ Usa logging detallado

===========================================
11. TROUBLESHOOTING
===========================================

Error: "GEMINI_API_KEY no encontrada"
--------------------------------------
Solución:
1. Verifica que .env existe y tiene GEMINI_API_KEY
2. Verifica que .env está en la raíz del proyecto
3. Verifica que la API Key es válida
4. Reinicia el terminal después de editar .env

Error: "Context file not found"
--------------------------------
Solución:
1. Verifica que la ruta del archivo es correcta
2. Usa rutas relativas desde la raíz del proyecto
3. Verifica que el archivo existe
4. Verifica permisos de lectura

Error: "Score below threshold"
-------------------------------
Solución:
1. Revisa la justificación de Gemini
2. Ajusta la respuesta del SUT
3. Ajusta el contexto de negocio
4. Considera bajar el umbral si es muy estricto
5. Revisa aspectos a mejorar en la evaluación

Error: "Gemini no devolvió JSON válido"
----------------------------------------
Solución:
1. Verifica que el contexto no es ambiguo
2. Simplifica el contexto si es muy complejo
3. Revisa que no hay caracteres especiales problemáticos
4. Intenta de nuevo (puede ser error temporal)

Error: "Context caching failed"
--------------------------------
Solución:
1. Verifica que el contexto tiene > 32k tokens
2. Verifica conexión a internet
3. Verifica que la API Key tiene permisos
4. Espera unos segundos y reintenta

Error: "Rate limit exceeded"
-----------------------------
Solución:
1. Reduce frecuencia de tests
2. Usa delays entre tests
3. Considera upgrade de plan de API
4. Agrupa tests para reducir llamadas

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

DOCUMENTACIÓN:
--------------
- Gemini API: https://ai.google.dev/docs
- Context Caching: https://ai.google.dev/docs/caching
- Pricing: https://ai.google.dev/pricing

HERRAMIENTAS:
-------------
- Google AI Studio: https://makersuite.google.com
- Token Counter: Incluido en el framework
- Evaluation Viewer: Ver archivos JSON guardados

SOPORTE:
--------
- GitHub Issues: https://github.com/pipefariashaka/haka-playwright-engine
- Documentación: Ver carpeta documentacion/

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

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

===========================================
12. NUEVAS FUNCIONALIDADES (v1.3.11+)
===========================================

THRESHOLD CONFIGURABLE
----------------------
Ahora puedes configurar el threshold del Juez Gemini de 3 formas:

1. EN EL STEP (más específico):
   Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.85

2. EN .ENV (configuración global):
   GEMINI_JUDGE_THRESHOLD=0.80

3. SIN ESPECIFICAR (usa threshold por defecto):
   Then el Juez Gemini debe validar la respuesta
   # Usa GEMINI_JUDGE_THRESHOLD del .env o 0.80 por defecto

VALORES RECOMENDADOS:
- 0.90-1.00: Excelencia (muy estricto)
- 0.80-0.89: Bueno (recomendado para producción) ← DEFAULT
- 0.70-0.79: Aceptable (más permisivo)
- 0.60-0.69: Básico (desarrollo/testing)

DIMENSIONES RAG (Retrieval Augmented Generation)
-------------------------------------------------
El Juez Gemini ahora evalúa 7 dimensiones en lugar de 4:

DIMENSIONES BÁSICAS:
1. Precisión de datos: ¿La información es correcta según el contexto?
2. Cumplimiento de restricciones: ¿Se respetan todas las reglas y políticas?
3. Tono de marca: ¿El tono es apropiado y profesional?
4. Coherencia: ¿La respuesta es coherente con el contexto?

DIMENSIONES RAG (NUEVAS):
5. Context Relevance: ¿El contexto recuperado de la base de datos vectorial
   es realmente útil para responder a la pregunta del usuario?
   
6. Faithfulness (Fidelidad): ¿La respuesta se basa EXCLUSIVAMENTE en el
   contexto proporcionado o la IA está inventando cosas (alucinando)?
   
7. Answer Relevance: ¿La respuesta realmente aborda lo que el usuario preguntó?

EVALUACIÓN DETALLADA POR DIMENSIÓN
-----------------------------------
El JSON de evaluación ahora incluye scores individuales por dimensión:

{
  "score": 0.85,
  "reasoning": "Explicación general de la evaluación",
  "critical_errors": [],
  "strengths": ["Fortaleza 1", "Fortaleza 2"],
  "suggestions": ["Sugerencia 1", "Sugerencia 2"],
  "threshold": 0.80,
  "passed": true,
  "timestamp": "2025-02-16T10:30:45.123456",
  "dimensions": {
    "precision": 0.90,
    "compliance": 0.80,
    "tone": 0.85,
    "coherence": 0.90,
    "context_relevance": 0.85,
    "faithfulness": 0.95,
    "answer_relevance": 0.90
  },
  "dimension_details": {
    "context_relevance": "El contexto proporcionado contiene toda la información necesaria para responder",
    "faithfulness": "La respuesta se basa completamente en el contexto, sin inventar información",
    "answer_relevance": "La respuesta aborda directamente la pregunta del usuario"
  }
}

SALIDA EN CONSOLA MEJORADA
---------------------------
La consola ahora muestra información detallada de cada dimensión:

📊 EVALUACIÓN DEL JUEZ GEMINI
Score General: 0.85 / 1.00 (Umbral: 0.80)

📐 Dimensiones Evaluadas:
  • Precisión de datos: 0.90
  • Cumplimiento: 0.80
  • Tono: 0.85
  • Coherencia: 0.90
  • Context Relevance (RAG): 0.85
  • Faithfulness/Fidelidad: 0.95
  • Answer Relevance: 0.90

🔍 Detalles de Dimensiones RAG:
  • Context Relevance: El contexto proporcionado contiene toda la información necesaria
  • Faithfulness: La respuesta se basa completamente en el contexto, sin inventar
  • Answer Relevance: La respuesta aborda directamente la pregunta del usuario

💭 Razonamiento General:
  La respuesta es correcta y cumple con las políticas...

EJEMPLO COMPLETO CON NUEVAS FUNCIONALIDADES
--------------------------------------------

Feature: Testing de RAG con dimensiones

  Background:
    Given el contexto de reglas de negocio "policies" está cargado desde "context/policies.txt"

  Scenario: Evaluar con threshold por defecto
    When interactúo con la IA con el prompt "¿Cuál es la política de devoluciones?"
    And establezco la respuesta del SUT como "Puedes devolver productos dentro de 30 días con recibo"
    Then el Juez Gemini debe validar la respuesta
    # Usa threshold del .env (0.80)
    And guardo la evaluación del Juez en el archivo "evaluations/test_001.json"

  Scenario: Evaluar con threshold específico y verificar dimensiones
    When interactúo con la IA con el prompt "¿Aceptan devoluciones?"
    And establezco la respuesta del SUT como "Sí, dentro de 30 días con recibo original"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.90
    # Usa threshold específico (0.90)
    And guardo la evaluación del Juez en el archivo "evaluations/test_002.json"

  Scenario: Detectar alucinaciones (Faithfulness bajo)
    When interactúo con la IA con el prompt "¿Cuál es el plazo de devolución?"
    And establezco la respuesta del SUT como "Puedes devolver en 60 días sin recibo"
    # Respuesta incorrecta: inventa 60 días (contexto dice 30) y sin recibo
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.80
    # Debería fallar con Faithfulness bajo (inventó información)

CASOS DE USO DE LAS NUEVAS DIMENSIONES
---------------------------------------

1. CONTEXT RELEVANCE (Relevancia del Contexto)
   Útil para: Validar que tu sistema RAG recupera información relevante
   
   Ejemplo: Si el usuario pregunta "¿Cuál es el horario?" y tu sistema
   recupera información sobre precios, Context Relevance será bajo.

2. FAITHFULNESS (Fidelidad)
   Útil para: Detectar alucinaciones y respuestas inventadas
   
   Ejemplo: Si el contexto dice "30 días" pero la IA responde "60 días",
   Faithfulness será bajo (está inventando).

3. ANSWER RELEVANCE (Relevancia de la Respuesta)
   Útil para: Verificar que la IA responde lo que se preguntó
   
   Ejemplo: Si el usuario pregunta "¿Cuánto cuesta?" y la IA responde
   sobre horarios, Answer Relevance será bajo.

CONFIGURACIÓN EN .ENV
---------------------
Agrega estas variables a tu archivo .env:

# Threshold por defecto para evaluaciones (0.0 - 1.0)
GEMINI_JUDGE_THRESHOLD=0.80

# Modelo actualizado (2025)
GEMINI_JUDGE_MODEL=gemini-2.5-flash

# API Key
GEMINI_API_KEY=tu_api_key_aqui

MEJORES PRÁCTICAS CON DIMENSIONES RAG
--------------------------------------

1. MONITOREA FAITHFULNESS
   - Si Faithfulness es bajo (<0.7), tu IA está inventando información
   - Revisa tu prompt o ajusta la temperatura del modelo

2. VALIDA CONTEXT RELEVANCE
   - Si Context Relevance es bajo, tu sistema de búsqueda no funciona bien
   - Mejora tus embeddings o estrategia de retrieval

3. VERIFICA ANSWER RELEVANCE
   - Si Answer Relevance es bajo, tu IA no entiende la pregunta
   - Mejora el prompt o usa un modelo más potente

4. USA THRESHOLDS DIFERENTES POR DIMENSIÓN
   - Faithfulness: threshold alto (0.9+) - No toleres alucinaciones
   - Context Relevance: threshold medio (0.7+) - Permite algo de ruido
   - Answer Relevance: threshold alto (0.8+) - La respuesta debe ser relevante

5. GUARDA TODAS LAS EVALUACIONES
   - Usa "guardo la evaluación del Juez en el archivo" en cada test
   - Analiza las dimensiones para encontrar patrones de fallo

===========================================
ACTUALIZACIÓN DE VERSIÓN
===========================================

Versión: 1.3.11
Última actualización: 2025-02-16
Nuevas funcionalidades:
- Threshold configurable (3 formas)
- 7 dimensiones de evaluación (incluye RAG)
- Salida detallada por dimensión
- Modelos actualizados (2.5 y 3.0)
