===========================================
REFERENCIA RÁPIDA - GEMINI COMO JUEZ
Framework Hakalab - Evaluación de IA Generativa
===========================================

CONFIGURACIÓN RÁPIDA
====================

1. Obtener API Key: https://makersuite.google.com/app/apikey

2. Configurar .env:
   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

3. Instalar dependencia:
   pip install google-genai>=0.1.0

STEPS DISPONIBLES (20 VARIANTES)
=================================

GESTIÓN DE CONTEXTO (6 variantes)
----------------------------------

✅ Cargar Contexto de Negocio:
   cargo el contexto de negocio "{context_name}" desde el archivo "{file_path}"
   que el contexto de reglas de negocio "{context_name}" está cargado desde el archivo "{file_path}"
   I load business context "{context_name}" from file "{file_path}"

✅ Cambiar Contexto Activo:
   cambio al contexto de negocio "{context_name}"
   I switch to business context "{context_name}"

✅ Limpiar Cachés:
   limpio todos los cachés de contexto
   I clear all context caches

INTERACCIÓN CON EL SUT (6 variantes)
-------------------------------------

✅ Interactuar con el SUT:
   interactúo con la IA con el prompt "{user_query}"
   envío el prompt "{user_query}" a la IA
   I interact with SUT using query "{user_query}"

✅ Establecer Respuesta del SUT:
   establezco la respuesta del SUT como "{response_text}"
   la respuesta del SUT es "{response_text}"
   I set SUT response as "{response_text}"

✅ Cargar Respuesta desde Archivo:
   cargo la respuesta del SUT desde el archivo "{file_path}"
   I load SUT response from file "{file_path}"

EVALUACIÓN CON GEMINI (6 variantes)
------------------------------------

✅ 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}

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

✅ 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}

GENERACIÓN DE RESPUESTAS (2 variantes)
---------------------------------------

✅ Generar Respuesta con Gemini (NUEVO):
   Gemini genera la respuesta para el prompt "{user_query}"
   I generate response with Gemini for prompt "{user_query}"

GESTIÓN DE RESULTADOS (4 variantes)
------------------------------------

✅ Guardar Evaluación:
   guardo la evaluación del Juez en el archivo "{file_path}"
   I save evaluation to file "{file_path}"

✅ Verificar Score Mínimo:
   el score de la última evaluación debe ser mayor o igual a {min_score}
   evaluation score should be at least {min_score}

EJEMPLO BÁSICO
==============

Feature: Testing de Chatbot

  Background:
    Given cargo el contexto de negocio "support" desde el archivo "context/support_rules.txt"

  Scenario: Validar respuesta sobre horario
    When establezco la respuesta del SUT como "Nuestro horario es de 9am a 6pm"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.8

EJEMPLO CON MÚLTIPLES CONTEXTOS
================================

Feature: Testing Multicontexto

  Scenario: Soporte técnico
    Given cargo el contexto de negocio "tech" desde el archivo "context/tech_support.txt"
    When establezco la respuesta del SUT como "Para resetear tu contraseña..."
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.85

  Scenario: Ventas
    Given cambio al contexto de negocio "sales"
    And cargo el contexto de negocio "sales" desde el archivo "context/sales_rules.txt"
    When establezco la respuesta del SUT como "Tenemos una promoción del 20%..."
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.8

EJEMPLO CON CRITERIOS PERSONALIZADOS
=====================================

Feature: Testing con Criterios Específicos

  Background:
    Given cargo el contexto de negocio "empathy" desde el archivo "context/empathy_rules.txt"

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

EJEMPLO CON VALIDACIÓN DIRECTA (NUEVO)
=======================================

Feature: Validación Directa de Pregunta-Respuesta

  Background:
    Given cargo el contexto de negocio "support" desde el archivo "context/support_rules.txt"

  Scenario: Validar múltiples FAQs
    # Validar horario
    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
    
    # Validar devoluciones
    And el Juez Gemini valida que para la pregunta "¿Aceptan devoluciones?" la respuesta "Sí, dentro de 30 días con recibo" 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 "Tarjetas y PayPal" es válida con umbral 0.8

EJEMPLO CON GENERACIÓN DE RESPUESTAS (NUEVO)
=============================================

Feature: Generación Automática de Respuestas

  Background:
    Given cargo el contexto de negocio "support" desde el archivo "context/support_rules.txt"

  Scenario: Generar Golden Answers
    # Gemini genera la respuesta basándose en el contexto
    When Gemini genera la respuesta para 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.9
    And guardo la evaluación del Juez en el archivo "golden_answers/horario.json"

EJEMPLO CON RESPUESTAS DESDE ARCHIVO
=====================================

Feature: Testing con Respuestas Complejas

  Background:
    Given cargo el contexto de negocio "legal" 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_eval.json"
    And el score de la última evaluación debe ser mayor o igual a 0.9

EJEMPLO CON LIMPIEZA DE CACHÉ
==============================

Feature: Testing con Actualización de Contexto

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

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

TIPOS DE DOCUMENTOS QUE PUEDES USAR COMO CONTEXTO
==================================================

✅ **Documentos Técnicos**:
   - Especificaciones de API (OpenAPI, Swagger, GraphQL)
   - Documentación técnica de productos
   - Manuales de usuario y administrador
   - Guías de arquitectura y diseño
   - Diagramas de flujo (en texto)
   - Código fuente con comentarios

✅ **Documentos de Negocio**:
   - Políticas de la empresa
   - Reglas de negocio
   - Términos y condiciones
   - Políticas de privacidad
   - Contratos y acuerdos
   - Procedimientos operativos estándar (SOP)

✅ **Documentos de Conocimiento**:
   - Base de conocimiento (KB) completa
   - FAQs extensas
   - Guías de estilo y tono de marca
   - Glosarios de términos técnicos
   - Wikis internas

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

✅ **Documentos de Producto**:
   - Catálogos de productos completos
   - Fichas técnicas detalladas
   - Especificaciones de características
   - Comparativas de productos
   - Hojas de datos (datasheets)

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

VENTAJAS DE USAR DOCUMENTOS TÉCNICOS COMO CONTEXTO
===================================================

1. **Validación Precisa**: Gemini puede validar respuestas contra especificaciones exactas
2. **Context Caching**: Documentos grandes (>32k tokens) se cachean automáticamente
3. **Ahorro de Costos**: Cache reduce costos hasta 90% para documentos extensos
4. **Consistencia**: Mismo contexto para todos los tests
5. **Versionado**: Puedes versionar tus documentos de contexto
6. **Reutilización**: Un documento puede usarse para múltiples tests

EJEMPLO: API SPECIFICATION COMO CONTEXTO
=========================================

# context/api_specification.txt

API REST de E-commerce v2.0

ENDPOINT: POST /api/orders
Request Body:
{
  "customer_id": "string (UUID, required)",
  "items": [{"product_id": "UUID", "quantity": "int", "price": "float"}],
  "shipping_address": {...},
  "payment_method": "enum ['credit_card', 'paypal']"
}

Response 201:
{
  "order_id": "UUID",
  "status": "enum ['pending', 'confirmed']",
  "total": "float"
}

VALIDACIONES:
- customer_id debe existir
- quantity debe ser > 0
- price debe coincidir con precio actual

Feature: Validar Documentación de API

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

  Scenario: Validar documentación generada
    When establezco la respuesta del SUT como "Para crear una orden, envía POST a /api/orders con customer_id, items y payment_method..."
    Then el Juez Gemini debe validar la respuesta con umbral 0.85

EJEMPLO: MANUAL TÉCNICO COMO CONTEXTO
======================================

# context/technical_manual.txt

MANUAL TÉCNICO - SISTEMA DE INVENTARIO v3.5

MÓDULO: Gestión de Stock

Actualización Automática:
- Venta: Reduce stock
- Devolución: Incrementa stock
- Recepción: Incrementa según albarán

Reglas:
- Stock mínimo: 10 unidades (alerta)
- Stock máximo: 1000 unidades (bloqueo)
- Reorden automático: < stock mínimo + 20%

Alertas:
- CRÍTICA: Stock = 0
- ALTA: Stock < mínimo
- MEDIA: Stock < seguridad

Feature: Validar Documentación Técnica

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

  Scenario: Validar explicación de stock
    When establezco la respuesta del SUT como "El stock se actualiza en ventas y devoluciones. Alerta cuando < 10 unidades..."
    Then el Juez Gemini debe validar la respuesta con umbral 0.85

UMBRALES RECOMENDADOS
======================

0.9 - 1.0  : Excelencia (validación estricta)
0.8 - 0.89 : Bueno (validación estándar) ⭐ RECOMENDADO
0.7 - 0.79 : Aceptable (validación flexible)
< 0.7      : Insuficiente

CONTEXT CACHING
===============

✅ Automático para contextos > 32,000 tokens
✅ Reduce costos hasta 90%
✅ Cache válido por 1 hora (configurable)
✅ Reutiliza el mismo contexto en múltiples tests

Sin caching:
- Input: $3.50 por 1M tokens

Con caching:
- Cached Input: $0.35 por 1M tokens (90% descuento)

ESTRUCTURA DE EVALUACIÓN JSON
==============================

{
  "score": 0.85,
  "reasoning": "Explicación detallada de la evaluación",
  "critical_errors": ["Error 1", "Error 2"],
  "strengths": ["Fortaleza 1", "Fortaleza 2"],
  "suggestions": ["Sugerencia 1", "Sugerencia 2"],
  "threshold": 0.8,
  "passed": true,
  "timestamp": "2026-02-12T10:30:00"
}

CASOS DE USO PRINCIPALES
=========================

1. Testing de Chatbots
   - Validar respuestas contra reglas de negocio
   - Verificar tono y estilo de marca
   - Asegurar cumplimiento de políticas

2. Evaluación de LLMs
   - Validar calidad de respuestas de GPT, Claude, etc.
   - Comparar diferentes modelos
   - Testing de prompts

3. Testing de Contenido Generado
   - Validar guías de estilo
   - Verificar tono de marca
   - Asegurar calidad de contenido

4. Validación de Restricciones
   - Asegurar que no se comparte información sensible
   - Verificar que no se dan consejos médicos/legales
   - Validar derivación correcta

5. Testing Multilingüe
   - Validar respuestas en múltiples idiomas
   - Verificar que no se mezclan idiomas
   - Asegurar calidad de traducciones

6. Validación de Documentación Técnica ⭐ NUEVO
   - Validar documentación de APIs generada por IA
   - Verificar precisión de documentación de código
   - Validar traducciones técnicas
   - Asegurar que la documentación cumple con estándares

7. Testing de Soporte Técnico ⭐ NUEVO
   - Validar respuestas técnicas contra manuales
   - Verificar procedimientos de troubleshooting
   - Asegurar que se siguen los pasos correctos
   - Validar que no se omiten precauciones

8. Validación de Cumplimiento Regulatorio ⭐ NUEVO
   - Verificar cumplimiento GDPR, HIPAA, etc.
   - Validar que se respetan políticas de privacidad
   - Asegurar que se mencionan derechos del usuario
   - Verificar que se explica el uso de datos

9. Testing de Especificaciones de API ⭐ NUEVO
   - Validar que respuestas cumplen con OpenAPI/Swagger
   - Verificar que se mencionan todos los parámetros
   - Validar ejemplos de uso
   - Asegurar que se documentan validaciones

10. Validación de Código Generado ⭐ NUEVO
    - Validar docstrings generados por IA
    - Verificar que se documentan parámetros y retornos
    - Asegurar que se mencionan excepciones
    - Validar que la documentación es útil

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

✅ Sé específico en el contexto de negocio
✅ Incluye ejemplos de respuestas correctas
✅ Define restricciones explícitamente
✅ Usa umbrales apropiados (0.8 para estándar)
✅ Agrupa tests que usan el mismo contexto
✅ Guarda evaluaciones para análisis
✅ Limpia cachés después de actualizar contextos
✅ Versiona tus archivos de contexto

TROUBLESHOOTING RÁPIDO
=======================

Error: "GEMINI_API_KEY no encontrada"
→ Verifica que .env existe y tiene la API Key

Error: "Context file not found"
→ Verifica que la ruta del archivo es correcta

Error: "Score below threshold"
→ Revisa la justificación de Gemini
→ Ajusta la respuesta del SUT o el contexto
→ Considera bajar el umbral si es muy estricto

Error: "Gemini no devolvió JSON válido"
→ Simplifica el contexto si es muy complejo
→ Intenta de nuevo (puede ser error temporal)

Error: "Rate limit exceeded"
→ Reduce frecuencia de tests
→ Usa delays entre tests

RECURSOS
=========

Documentación Completa: GUIA_TESTING_GEMINI_COMPLETA.txt
Ejemplos: hakalab_framework/examples/gemini_evaluation_example.feature
Gemini API: https://ai.google.dev/docs
Context Caching: https://ai.google.dev/docs/caching
Pricing: https://ai.google.dev/pricing

===========================================
FIN DE LA REFERENCIA RÁPIDA
===========================================

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

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

THRESHOLD CONFIGURABLE
----------------------
# Opción 1: En el step
Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.85

# Opción 2: En .env
GEMINI_JUDGE_THRESHOLD=0.80

# Opción 3: Sin especificar (usa .env o default 0.80)
Then el Juez Gemini debe validar la respuesta

DIMENSIONES RAG
---------------
El Juez ahora evalúa 7 dimensiones:

BÁSICAS:
1. Precisión de datos
2. Cumplimiento
3. Tono
4. Coherencia

RAG (NUEVAS):
5. Context Relevance: ¿El contexto recuperado es útil?
6. Faithfulness: ¿La respuesta se basa solo en el contexto?
7. Answer Relevance: ¿La respuesta aborda la pregunta?

EVALUACIÓN DETALLADA
--------------------
El JSON ahora incluye:
{
  "score": 0.85,
  "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": "Explicación...",
    "faithfulness": "Explicación...",
    "answer_relevance": "Explicación..."
  }
}

EJEMPLO RÁPIDO
--------------
Feature: RAG Testing
  Background:
    Given el contexto de reglas de negocio "policies" está cargado desde "context/policies.txt"

  Scenario: Test con threshold por defecto
    When interactúo con la IA con el prompt "¿Política de devoluciones?"
    And establezco la respuesta del SUT como "30 días con recibo"
    Then el Juez Gemini debe validar la respuesta
    And guardo la evaluación del Juez en el archivo "evaluations/test.json"

MODELOS ACTUALIZADOS (2025)
----------------------------
✅ gemini-2.5-pro (mejor calidad)
✅ gemini-2.5-flash (recomendado)
✅ gemini-2.5-flash-lite (más rápido)
✅ gemini-3-pro-preview (experimental)

❌ gemini-1.5-pro (deprecado)
❌ gemini-1.5-flash (deprecado)

CONFIGURACIÓN .ENV
------------------
GEMINI_API_KEY=tu_key
GEMINI_JUDGE_MODEL=gemini-2.5-flash
GEMINI_JUDGE_THRESHOLD=0.80
GEMINI_CACHE_THRESHOLD=32000
