================================================================================
CONCEPTOS DE IA EN EL FRAMEWORK - GUÍA PARA PRINCIPIANTES
================================================================================

Este documento explica conceptualmente cómo funcionan las dos tecnologías de IA
que usa el framework: Sentence Transformers (validación semántica local) y 
Google Gemini (IA generativa en la nube).

================================================================================
PARTE 1: SENTENCE TRANSFORMERS - VALIDACIÓN SEMÁNTICA LOCAL
================================================================================

## ¿QUÉ ES?

Sentence Transformers es una librería de Python que convierte texto en 
"embeddings" (vectores numéricos) para comparar el significado de textos.

Piensa en ello como un "traductor de texto a números" que captura el SIGNIFICADO
de las palabras, no solo las palabras exactas.

## ¿CÓMO FUNCIONA?

1. EMBEDDINGS (Vectores de Significado)
   - Convierte cada texto en una lista de números (vector)
   - Textos con significado similar tienen vectores similares
   - Ejemplo:
     * "Hola mundo" → [0.2, 0.8, 0.1, 0.5, ...]
     * "Hello world" → [0.3, 0.7, 0.2, 0.4, ...]
     * Estos vectores son similares porque el significado es similar

2. SIMILITUD DE COSENO
   - Compara dos vectores para ver qué tan similares son
   - Resultado: número entre 0.0 y 1.0
     * 1.0 = Textos idénticos en significado
     * 0.75-0.89 = Alta similitud (recomendado para QA)
     * 0.0 = Textos completamente diferentes

3. PROCESO COMPLETO
   Texto 1: "Tu solicitud fue aprobada"
      ↓ (modelo transforma)
   Vector 1: [0.2, 0.8, 0.1, ...]
      ↓
   Similitud de Coseno ← Compara → Vector 2: [0.3, 0.7, 0.2, ...]
      ↓                                  ↑ (modelo transforma)
   Score: 0.87                    Texto 2: "Gracias, tu solicitud fue exitosa"


## MODELOS DISPONIBLES

El framework usa modelos pre-entrenados de Sentence Transformers:

1. paraphrase-multilingual-MiniLM-L12-v2 (RECOMENDADO - DEFAULT)
   - Multilingüe (español, inglés, etc.)
   - Balanceado entre velocidad y precisión
   - Tamaño: ~420MB
   - Velocidad: Rápido
   - Uso: Testing general en múltiples idiomas

2. paraphrase-multilingual-mpnet-base-v2
   - Multilingüe
   - Más preciso pero más lento
   - Tamaño: ~1GB
   - Velocidad: Moderado
   - Uso: Cuando necesitas máxima precisión

3. all-MiniLM-L6-v2
   - Solo inglés
   - Muy rápido
   - Tamaño: ~80MB
   - Velocidad: Muy rápido
   - Uso: Testing en inglés con alta velocidad

4. all-mpnet-base-v2
   - Solo inglés
   - Más preciso
   - Tamaño: ~420MB
   - Velocidad: Moderado
   - Uso: Testing en inglés con alta precisión

## UMBRALES DE SIMILITUD

El umbral determina qué tan similares deben ser los textos para pasar la validación:

0.90 - 1.00  →  Textos casi idénticos
               Ejemplo: "Hola" vs "Hola!"
               Uso: Validaciones muy estrictas

0.75 - 0.89  →  Alta similitud semántica (RECOMENDADO PARA QA)
               Ejemplo: "Tu solicitud fue aprobada" vs "Gracias, tu solicitud fue exitosa"
               Uso: Testing de aplicaciones (default: 0.75)

0.60 - 0.74  →  Similitud moderada
               Ejemplo: "Buen día" vs "Hola, ¿cómo estás?"
               Uso: Validaciones más flexibles

0.40 - 0.59  →  Similitud baja
               Ejemplo: "Hola" vs "Adiós"
               Uso: Detectar temas relacionados

0.00 - 0.39  →  Textos diferentes
               Ejemplo: "Hola" vs "El cielo es azul"
               Uso: Validar que textos NO son similares


## VENTAJAS DE SENTENCE TRANSFORMERS

✅ FUNCIONA OFFLINE
   - No necesita internet
   - No necesita API keys
   - No hay costos por uso

✅ RÁPIDO
   - Procesa textos en milisegundos
   - Ideal para testing automatizado

✅ PRIVADO
   - Los datos no salen de tu máquina
   - No se envían a servicios externos

✅ CONSISTENTE
   - Siempre da el mismo resultado para los mismos textos
   - Perfecto para CI/CD

✅ MULTILINGÜE
   - Entiende múltiples idiomas
   - Puede comparar textos en diferentes idiomas

## LIMITACIONES

❌ NO ENTIENDE CONTEXTO COMPLEJO
   - Solo compara significado superficial
   - No entiende reglas de negocio complejas

❌ NO GENERA TEXTO
   - Solo compara textos existentes
   - No puede crear respuestas nuevas

❌ REQUIERE DESCARGA INICIAL
   - Primera vez descarga el modelo (~420MB)
   - Después funciona offline

## CASOS DE USO EN EL FRAMEWORK

1. Validar mensajes de usuario
   - "Tu pedido fue enviado" ≈ "Gracias, tu orden está en camino"

2. Validar respuestas de API
   - Verificar que el mensaje de error es similar al esperado

3. Validar textos en elementos web
   - Verificar que un botón dice algo similar a "Continuar"

4. Testing de chatbots
   - Validar que las respuestas son semánticamente correctas

5. Validación flexible
   - Cuando el texto exacto puede variar pero el significado debe ser el mismo


================================================================================
PARTE 2: GOOGLE GEMINI - IA GENERATIVA EN LA NUBE
================================================================================

## ¿QUÉ ES?

Google Gemini es un modelo de IA generativa (LLM - Large Language Model) que:
- Entiende y genera texto
- Razona sobre información compleja
- Puede actuar como "juez" para evaluar respuestas

Es como tener un experto humano que lee tus reglas de negocio y evalúa si
las respuestas de tu aplicación son correctas.

## ¿CÓMO FUNCIONA?

1. CONTEXTO DE NEGOCIO
   - Le das a Gemini tus reglas de negocio (archivo .txt)
   - Gemini lee y entiende las reglas
   - Ejemplo: Políticas de devolución, guías de atención al cliente, etc.

2. RESPUESTA A EVALUAR
   - Le das la respuesta que generó tu aplicación
   - Gemini compara la respuesta contra las reglas

3. EVALUACIÓN COMO JUEZ
   - Gemini analiza si la respuesta:
     * Es precisa según las reglas
     * Cumple con las restricciones
     * Tiene el tono apropiado
     * Es coherente con el contexto
   
4. RESULTADO
   - Score de 0.0 a 1.0
   - Razonamiento detallado
   - Lista de errores críticos
   - Sugerencias de mejora

## PROCESO COMPLETO

Archivo de Reglas: "Devoluciones permitidas dentro de 30 días"
      ↓
Gemini lee y entiende el contexto
      ↓
Tu App responde: "Puedes devolver en 45 días"
      ↓
Gemini evalúa: "INCORRECTO - La política dice 30 días, no 45"
      ↓
Score: 0.3 (bajo) + Explicación detallada


## MODELOS DISPONIBLES (ACTUALIZADOS 2025)

⚠️ IMPORTANTE: Los modelos 1.5 (gemini-1.5-pro, gemini-1.5-flash) están 
DEPRECADOS y ya NO funcionan. Usa los modelos 2.0, 2.5 o 3.0.

MODELOS RECOMENDADOS:

1. gemini-2.5-pro (RECOMENDADO PARA PRODUCCIÓN)
   - Modelo más potente y estable
   - Mejor razonamiento y thinking
   - Contexto: hasta 1 millón de tokens
   - Velocidad: Moderado
   - Costo: Medio
   - Uso: Evaluaciones complejas, reglas de negocio extensas
   - Estado: Stable (producción)

2. gemini-2.5-flash (RECOMENDADO PARA TESTING)
   - Mejor balance precio-rendimiento
   - Buen razonamiento
   - Contexto: hasta 1 millón de tokens
   - Velocidad: Rápido
   - Costo: Bajo
   - Uso: Testing general, CI/CD, evaluaciones frecuentes
   - Estado: Stable (producción)

3. gemini-2.5-flash-lite (MÁS ECONÓMICO)
   - Modelo más rápido y barato
   - Razonamiento básico
   - Contexto: hasta 1 millón de tokens
   - Velocidad: Muy rápido
   - Costo: Muy bajo
   - Uso: Alto volumen, evaluaciones simples
   - Estado: Stable (producción)

4. gemini-3-pro-preview (EXPERIMENTAL - MÁS AVANZADO)
   - Modelo más inteligente disponible
   - Razonamiento avanzado
   - Contexto: hasta 1 millón de tokens
   - Velocidad: Moderado
   - Costo: Alto
   - Uso: Casos complejos que requieren máxima inteligencia
   - Estado: Preview (experimental)

5. gemini-3-flash-preview (EXPERIMENTAL - RÁPIDO)
   - Balance entre velocidad e inteligencia
   - Contexto: hasta 1 millón de tokens
   - Velocidad: Rápido
   - Costo: Medio
   - Uso: Testing con capacidades avanzadas
   - Estado: Preview (experimental)

MODELOS DEPRECADOS (NO USAR):
❌ gemini-1.5-pro → Error 404
❌ gemini-1.5-pro-002 → Error 404
❌ gemini-1.5-flash → Error 404
❌ gemini-1.5-flash-002 → Error 404

## CONTEXT CACHING (OPTIMIZACIÓN DE TOKENS)

Gemini tiene una característica especial llamada "Context Caching" que ahorra
tokens y dinero cuando usas el mismo contexto múltiples veces.

¿CÓMO FUNCIONA?

Sin Context Caching:
  Test 1: Envías 50,000 tokens de reglas + pregunta → Pagas 50,000 tokens
  Test 2: Envías 50,000 tokens de reglas + pregunta → Pagas 50,000 tokens
  Test 3: Envías 50,000 tokens de reglas + pregunta → Pagas 50,000 tokens
  Total: 150,000 tokens

Con Context Caching:
  Test 1: Envías 50,000 tokens de reglas (se cachean) + pregunta → Pagas 50,000 tokens
  Test 2: Reutiliza caché + pregunta → Pagas solo la pregunta (~100 tokens)
  Test 3: Reutiliza caché + pregunta → Pagas solo la pregunta (~100 tokens)
  Total: ~50,200 tokens (¡66% de ahorro!)

CUÁNDO SE USA:

El framework automáticamente decide:
- Si tu archivo de reglas tiene >= 32,000 tokens → Usa Context Caching
- Si tu archivo de reglas tiene < 32,000 tokens → Usa System Instruction (sin caché)

Puedes cambiar el umbral con la variable de entorno:
  GEMINI_CACHE_THRESHOLD=50000

DURACIÓN DEL CACHÉ:

- El caché dura 1 hora por defecto
- Después de 1 hora, se crea un nuevo caché
- Perfecto para suites de testing que corren en minutos


## VENTAJAS DE GEMINI

✅ RAZONAMIENTO COMPLEJO
   - Entiende reglas de negocio complejas
   - Puede evaluar múltiples criterios
   - Detecta inconsistencias sutiles

✅ GENERA EXPLICACIONES
   - Te dice POR QUÉ algo está mal
   - Da sugerencias de mejora
   - Identifica errores críticos

✅ FLEXIBLE
   - Puede evaluar cualquier tipo de contenido
   - Se adapta a diferentes dominios
   - Entiende contexto de negocio

✅ MULTILINGÜE NATIVO
   - Entiende múltiples idiomas naturalmente
   - Puede evaluar respuestas en cualquier idioma

✅ GENERA RESPUESTAS DE REFERENCIA
   - Puede crear "golden answers" para comparar
   - Útil para testing de RAG (Retrieval Augmented Generation)

## LIMITACIONES

❌ REQUIERE INTERNET
   - Necesita conexión para funcionar
   - No funciona offline

❌ REQUIERE API KEY
   - Necesitas cuenta de Google Cloud
   - Debes configurar GEMINI_API_KEY

❌ TIENE COSTO
   - Pagas por tokens procesados
   - Aunque Context Caching reduce mucho el costo

❌ PUEDE SER LENTO
   - Depende de la red
   - Más lento que Sentence Transformers

❌ NO ES DETERMINÍSTICO
   - Puede dar respuestas ligeramente diferentes
   - Aunque con temperature=0.1 es muy consistente


## CASOS DE USO EN EL FRAMEWORK

1. EVALUACIÓN DE CHATBOTS
   - Cargas las reglas de atención al cliente
   - Gemini evalúa si las respuestas del chatbot son correctas

2. TESTING DE RAG (Retrieval Augmented Generation)
   - Comparas tu IA vs Gemini
   - Verificas que tu IA responde similar a Gemini

3. VALIDACIÓN DE POLÍTICAS
   - Verificas que las respuestas cumplen con políticas de la empresa
   - Detectas violaciones de reglas de negocio

4. GENERACIÓN DE RESPUESTAS DE REFERENCIA
   - Gemini genera la respuesta "correcta" según tus reglas
   - Usas esa respuesta como baseline para comparar

5. EVALUACIÓN MULTI-CRITERIO
   - Evalúas precisión, tono, coherencia, cumplimiento
   - Obtienes feedback detallado

6. TESTING DE DOCUMENTACIÓN TÉCNICA
   - Verificas que la documentación es precisa
   - Detectas inconsistencias o errores

## CONFIGURACIÓN NECESARIA

Para usar Gemini necesitas:

1. API KEY de Google
   - Obtener en: https://aistudio.google.com/app/apikey
   - Configurar en .env:
     GEMINI_API_KEY=tu_api_key_aqui

2. Modelo (opcional)
   - Por defecto usa: gemini-2.5-pro (actualizado 2025)
   - Cambiar en .env:
     GEMINI_JUDGE_MODEL=gemini-2.5-flash
     
   ⚠️ NO uses modelos 1.5 (deprecados):
     ❌ gemini-1.5-pro → Error 404
     ❌ gemini-1.5-flash → Error 404

3. Umbral de Caching (opcional)
   - Por defecto: 32,000 tokens
   - Cambiar en .env:
     GEMINI_CACHE_THRESHOLD=50000


================================================================================
PARTE 3: COMPARACIÓN - ¿CUÁNDO USAR CADA UNO?
================================================================================

## SENTENCE TRANSFORMERS vs GEMINI

┌─────────────────────┬──────────────────────┬──────────────────────┐
│ CARACTERÍSTICA      │ SENTENCE TRANSFORMERS│ GEMINI               │
├─────────────────────┼──────────────────────┼──────────────────────┤
│ Tipo                │ NLP Local            │ LLM en la Nube       │
│ Conexión            │ Offline              │ Requiere Internet    │
│ Velocidad           │ Muy rápido (ms)      │ Moderado (segundos)  │
│ Costo               │ Gratis               │ Pago por uso         │
│ Privacidad          │ 100% local           │ Datos en la nube     │
│ Razonamiento        │ Básico (similitud)   │ Complejo (LLM)       │
│ Explicaciones       │ No                   │ Sí, detalladas       │
│ Genera texto        │ No                   │ Sí                   │
│ Contexto complejo   │ No                   │ Sí                   │
│ Multilingüe         │ Sí                   │ Sí                   │
│ Determinístico      │ Sí                   │ Casi (con temp=0.1)  │
│ Setup               │ pip install          │ API Key + pip install│
└─────────────────────┴──────────────────────┴──────────────────────┘

## CUÁNDO USAR SENTENCE TRANSFORMERS

✅ Validaciones simples de similitud
   "¿Este mensaje es similar a este otro?"

✅ Testing rápido y frecuente
   CI/CD, testing automatizado continuo

✅ Sin presupuesto para APIs
   Proyectos con costo cero

✅ Datos sensibles
   Información que no puede salir de tu infraestructura

✅ Offline/Sin internet
   Ambientes sin conexión externa

✅ Validaciones de UI
   Verificar textos en botones, mensajes, etc.

EJEMPLO:
  Verificar que el mensaje de éxito dice algo similar a "Operación exitosa"
  → Usa Sentence Transformers (rápido, simple, offline)


## CUÁNDO USAR GEMINI

✅ Evaluación de reglas de negocio complejas
   "¿Esta respuesta cumple con nuestras 50 políticas de atención?"

✅ Testing de chatbots/IA
   Evaluar si las respuestas son correctas según documentación

✅ Necesitas explicaciones detalladas
   Quieres saber POR QUÉ algo falló

✅ Evaluación multi-criterio
   Precisión + Tono + Coherencia + Cumplimiento

✅ Generación de respuestas de referencia
   Crear "golden answers" para comparar

✅ Testing de RAG
   Comparar tu IA vs Gemini como baseline

✅ Contexto extenso
   Tienes documentación de 100+ páginas que Gemini debe entender

EJEMPLO:
  Verificar que el chatbot responde correctamente según 50 páginas de políticas
  → Usa Gemini (razonamiento complejo, contexto extenso, explicaciones)

## COMBINANDO AMBOS

Puedes usar ambos en el mismo proyecto:

ESTRATEGIA HÍBRIDA:

1. Sentence Transformers para validaciones rápidas
   - Mensajes de UI
   - Validaciones simples de API
   - Tests de regresión frecuentes

2. Gemini para validaciones complejas
   - Evaluación de chatbots
   - Cumplimiento de políticas
   - Testing de IA generativa

EJEMPLO DE SUITE DE TESTS:

  Scenario: Validación rápida de UI
    Then el texto del botón debe ser semánticamente similar a "Continuar"
    # ↑ Usa Sentence Transformers (rápido, offline)

  Scenario: Validación de chatbot
    Given el contexto de reglas de negocio "policies" está cargado desde "policies.txt"
    When interactúo con la IA con el prompt "¿Puedo devolver un producto?"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.85
    # ↑ Usa Gemini (razonamiento complejo, contexto extenso)


================================================================================
PARTE 4: CONCEPTOS CLAVE DE IA PARA ENTENDER
================================================================================

## EMBEDDINGS (Vectores de Significado)

¿QUÉ SON?
  Representación numérica del significado de un texto.
  
ANALOGÍA:
  Imagina que cada palabra/frase tiene una "huella digital" numérica.
  Textos con significado similar tienen huellas similares.

EJEMPLO VISUAL:
  "Perro" → [0.8, 0.2, 0.1, 0.9, ...]
  "Gato"  → [0.7, 0.3, 0.1, 0.8, ...]  ← Similar a "Perro"
  "Carro" → [0.1, 0.9, 0.8, 0.2, ...]  ← Muy diferente

DIMENSIONES:
  Los embeddings tienen cientos de dimensiones (números).
  Ejemplo: paraphrase-multilingual-MiniLM-L12-v2 usa 384 dimensiones.

## SIMILITUD DE COSENO

¿QUÉ ES?
  Medida matemática de qué tan similares son dos vectores.

ANALOGÍA:
  Imagina dos flechas en el espacio.
  - Si apuntan en la misma dirección → Similitud alta (cercano a 1.0)
  - Si apuntan en direcciones opuestas → Similitud baja (cercano a 0.0)

FÓRMULA (no necesitas memorizarla):
  similitud = (A · B) / (||A|| × ||B||)
  
  Donde:
  - A y B son los vectores (embeddings)
  - · es el producto punto
  - ||A|| es la magnitud del vector A

RESULTADO:
  Número entre -1.0 y 1.0, pero en NLP usualmente entre 0.0 y 1.0

## TOKENS

¿QUÉ SON?
  Unidades básicas de texto que los modelos de IA procesan.

REGLA APROXIMADA:
  1 token ≈ 4 caracteres en inglés
  1 token ≈ 0.75 palabras en inglés
  1 token ≈ 3-4 caracteres en español

EJEMPLOS:
  "Hola" → 1 token
  "Hola mundo" → 2 tokens
  "¿Cómo estás?" → 3-4 tokens
  "anticonstitucionalísimamente" → 5-6 tokens

POR QUÉ IMPORTAN:
  - Gemini cobra por tokens procesados
  - Context Caching ahorra tokens
  - Límites de contexto se miden en tokens


## LLM (Large Language Model)

¿QUÉ ES?
  Modelo de IA entrenado con billones de palabras para entender y generar texto.

EJEMPLOS:
  - GPT (OpenAI)
  - Gemini (Google)
  - Claude (Anthropic)
  - LLaMA (Meta)

CAPACIDADES:
  - Entender lenguaje natural
  - Generar texto coherente
  - Razonar sobre información
  - Seguir instrucciones
  - Responder preguntas

LIMITACIONES:
  - Puede "alucinar" (inventar información)
  - No tiene conocimiento en tiempo real (hasta su fecha de entrenamiento)
  - Puede ser sesgado
  - No es determinístico al 100%

## TEMPERATURE (Temperatura)

¿QUÉ ES?
  Parámetro que controla la "creatividad" del modelo.

VALORES:
  0.0 → Muy determinístico, siempre elige la opción más probable
  0.1 → Casi determinístico (usado para evaluación)
  0.7 → Balanceado (usado para generación)
  1.0 → Creativo
  2.0 → Muy creativo, impredecible

EN EL FRAMEWORK:
  - Evaluación (Juez): temperature=0.1 (consistente)
  - Generación: temperature=0.7 (natural pero controlado)

## SYSTEM INSTRUCTION

¿QUÉ ES?
  Instrucciones que le das al modelo sobre cómo debe comportarse.

ANALOGÍA:
  Es como darle un "rol" al modelo antes de empezar la conversación.

EJEMPLO:
  System Instruction: "Eres un auditor de calidad estricto"
  
  Resultado: El modelo actuará como auditor en todas sus respuestas.

EN EL FRAMEWORK:
  - Se usa para contextos pequeños (< 32k tokens)
  - Define el rol del modelo (Juez, Generador, etc.)

## CONTEXT WINDOW (Ventana de Contexto)

¿QUÉ ES?
  Cantidad máxima de tokens que el modelo puede procesar a la vez.

ANALOGÍA:
  Es como la "memoria de trabajo" del modelo.

EJEMPLOS:
  - gemini-1.5-pro: 2 millones de tokens (~1.5 millones de palabras)
  - gemini-1.5-flash: 1 millón de tokens (~750k palabras)

IMPLICACIONES:
  - Puedes darle documentos muy largos
  - Puede "recordar" toda la conversación
  - Perfecto para evaluar contra documentación extensa


## RAG (Retrieval Augmented Generation)

¿QUÉ ES?
  Técnica donde un modelo de IA busca información relevante antes de responder.

PROCESO:
  1. Usuario hace una pregunta
  2. Sistema busca información relevante en documentos
  3. Sistema envía pregunta + información al LLM
  4. LLM genera respuesta basada en la información

ANALOGÍA:
  Es como un estudiante que consulta sus apuntes antes de responder un examen.

EJEMPLO:
  Pregunta: "¿Cuál es la política de devoluciones?"
  
  RAG:
  1. Busca en documentos: "Devoluciones permitidas dentro de 30 días"
  2. Envía a LLM: Pregunta + Documento encontrado
  3. LLM responde: "Puedes devolver productos dentro de 30 días"

EN EL FRAMEWORK:
  Gemini puede actuar como baseline para comparar tu sistema RAG.

## PROMPT ENGINEERING

¿QUÉ ES?
  Arte de escribir instrucciones efectivas para modelos de IA.

PRINCIPIOS:
  1. Ser específico y claro
  2. Dar ejemplos cuando sea posible
  3. Definir el formato de salida deseado
  4. Establecer restricciones

EJEMPLO MALO:
  "Evalúa esta respuesta"

EJEMPLO BUENO:
  "Actúa como auditor de calidad. Evalúa esta respuesta contra las políticas
   proporcionadas. Responde en JSON con: score (0-1), reasoning, errors."

EN EL FRAMEWORK:
  Los prompts ya están optimizados, pero puedes personalizarlos.

## DETERMINISMO vs NO-DETERMINISMO

DETERMINÍSTICO:
  Siempre da el mismo resultado para la misma entrada.
  Ejemplo: Sentence Transformers

NO-DETERMINÍSTICO:
  Puede dar resultados ligeramente diferentes.
  Ejemplo: LLMs como Gemini

CÓMO HACER MÁS DETERMINÍSTICO:
  - Usar temperature=0.0 o 0.1
  - Usar seed (si el modelo lo soporta)
  - Prompts muy específicos

EN EL FRAMEWORK:
  - Sentence Transformers: 100% determinístico
  - Gemini con temp=0.1: ~95% consistente


================================================================================
PARTE 5: EJEMPLOS PRÁCTICOS PASO A PASO
================================================================================

## EJEMPLO 1: VALIDACIÓN SEMÁNTICA SIMPLE

ESCENARIO:
  Quieres verificar que un mensaje de éxito es correcto, pero el texto exacto
  puede variar.

CÓDIGO:
  ```gherkin
  Scenario: Validar mensaje de éxito
    Given uso la configuración semántica por defecto
    When hago click en el botón "Enviar"
    Then el texto del elemento "Mensaje" con identificador "$.success_msg" debe ser semánticamente similar a "Tu solicitud fue procesada exitosamente"
  ```

QUÉ PASA:
  1. Framework carga modelo: paraphrase-multilingual-MiniLM-L12-v2
  2. Establece umbral: 0.75
  3. Obtiene texto del elemento: "Gracias, tu solicitud fue exitosa"
  4. Calcula embeddings de ambos textos
  5. Calcula similitud de coseno: 0.87
  6. Compara: 0.87 >= 0.75 → ✅ PASS

RESULTADO:
  Test pasa porque los textos son semánticamente similares, aunque no idénticos.

## EJEMPLO 2: EVALUACIÓN CON GEMINI

ESCENARIO:
  Tienes un chatbot de soporte y quieres verificar que responde correctamente
  según tus políticas de empresa.

ARCHIVO: context/politicas_soporte.txt
  ```
  POLÍTICAS DE SOPORTE AL CLIENTE
  
  1. Devoluciones: Permitidas dentro de 30 días con recibo
  2. Reembolsos: Procesados en 5-7 días hábiles
  3. Tono: Siempre amigable y profesional
  4. Restricción: Nunca prometer plazos menores a los oficiales
  ```

CÓDIGO:
  ```gherkin
  Scenario: Validar respuesta del chatbot
    Given el contexto de reglas de negocio "soporte" está cargado desde el archivo "context/politicas_soporte.txt"
    When interactúo con la IA con el prompt "¿Puedo devolver un producto?"
    And establezco la respuesta del SUT como "Claro, puedes devolver cualquier producto en 60 días"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.8
  ```

QUÉ PASA:
  1. Framework carga políticas en Gemini
  2. Envía prompt y respuesta a Gemini
  3. Gemini evalúa:
     - Precisión: ❌ Dice 60 días pero política dice 30 días
     - Tono: ✅ Amigable
     - Restricción: ❌ Promete más de lo permitido
  4. Gemini devuelve:
     ```json
     {
       "score": 0.3,
       "reasoning": "La respuesta es incorrecta. La política permite 30 días, no 60.",
       "critical_errors": ["Plazo incorrecto: 60 días vs 30 días permitidos"],
       "suggestions": ["Corregir a 30 días", "Mencionar requisito de recibo"]
     }
     ```
  5. Compara: 0.3 < 0.8 → ❌ FAIL

RESULTADO:
  Test falla con explicación detallada de por qué está mal.


## EJEMPLO 3: CONTEXT CACHING EN ACCIÓN

ESCENARIO:
  Tienes 100 páginas de documentación técnica (60,000 tokens) y quieres hacer
  50 tests diferentes contra esa documentación.

ARCHIVO: context/documentacion_tecnica.txt (60,000 tokens)

CÓDIGO:
  ```gherkin
  Scenario Outline: Validar múltiples respuestas
    Given el contexto de reglas de negocio "docs" está cargado desde el archivo "context/documentacion_tecnica.txt"
    When Gemini genera la respuesta para el prompt "<pregunta>"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.85
    
    Examples:
      | pregunta                          |
      | ¿Cómo instalar el producto?       |
      | ¿Cuáles son los requisitos?       |
      | ¿Cómo hacer backup?               |
      | ... (47 preguntas más)            |
  ```

QUÉ PASA:

SIN CONTEXT CACHING:
  Test 1: 60,000 tokens (docs) + 100 tokens (pregunta) = 60,100 tokens
  Test 2: 60,000 tokens (docs) + 100 tokens (pregunta) = 60,100 tokens
  ...
  Test 50: 60,000 tokens (docs) + 100 tokens (pregunta) = 60,100 tokens
  
  TOTAL: 3,005,000 tokens
  COSTO: ~$3.00 USD (aproximado)

CON CONTEXT CACHING (automático porque 60k > 32k):
  Test 1: 60,000 tokens (docs se cachean) + 100 tokens = 60,100 tokens
  Test 2: Caché reutilizado + 100 tokens = 100 tokens
  Test 3: Caché reutilizado + 100 tokens = 100 tokens
  ...
  Test 50: Caché reutilizado + 100 tokens = 100 tokens
  
  TOTAL: 65,000 tokens
  COSTO: ~$0.07 USD (aproximado)
  
  AHORRO: 97.8% 🎉

RESULTADO:
  Framework automáticamente usa Context Caching y ahorra tokens/dinero.

## EJEMPLO 4: COMBINANDO AMBAS TECNOLOGÍAS

ESCENARIO:
  Suite de tests completa con validaciones rápidas y complejas.

CÓDIGO:
  ```gherkin
  Feature: Testing completo de aplicación
  
    Background:
      Given uso la configuración semántica por defecto
      And el contexto de reglas de negocio "policies" está cargado desde "context/policies.txt"
  
    # Tests rápidos con Sentence Transformers
    Scenario: Validar UI
      When navego a "https://app.com"
      Then el texto del botón "Login" debe ser semánticamente similar a "Iniciar sesión"
      And el texto del título debe ser semánticamente similar a "Bienvenido"
      # ↑ Rápido, offline, determinístico
  
    # Tests complejos con Gemini
    Scenario: Validar chatbot
      When interactúo con la IA con el prompt "¿Cuál es su política de privacidad?"
      Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.85
      # ↑ Razonamiento complejo, contexto extenso
  
    # Validación de API con Sentence Transformers
    Scenario: Validar respuesta de API
      When realizo una petición GET a "https://api.com/status"
      Then el campo "message" de la respuesta debe ser semánticamente similar a "Servicio operativo"
      # ↑ Rápido, sin costo
  ```

RESULTADO:
  - Tests de UI: Milisegundos, sin costo
  - Tests de chatbot: Segundos, con costo mínimo (Context Caching)
  - Tests de API: Milisegundos, sin costo
  
  Suite completa: Rápida, económica, y completa.


================================================================================
PARTE 6: PREGUNTAS FRECUENTES (FAQ)
================================================================================

## SENTENCE TRANSFORMERS

P: ¿Necesito internet para usar Sentence Transformers?
R: Solo la primera vez para descargar el modelo (~420MB). Después funciona 
   completamente offline.

P: ¿Puedo usar Sentence Transformers en CI/CD?
R: Sí, es perfecto para CI/CD. Es rápido, determinístico y sin costos.

P: ¿Qué tan preciso es?
R: Muy preciso para similitud semántica. Con umbral 0.75 detecta correctamente
   textos similares en ~95% de los casos.

P: ¿Funciona en español?
R: Sí, los modelos multilingües (paraphrase-multilingual-*) funcionan 
   excelente en español.

P: ¿Puedo comparar textos en diferentes idiomas?
R: Sí, los modelos multilingües pueden comparar "Hello" vs "Hola" y detectar
   que son similares.

P: ¿Cómo cambio el modelo?
R: En tu .env:
   SEMANTIC_MODEL=paraphrase-multilingual-mpnet-base-v2

P: ¿Cómo cambio el umbral?
R: En tu .env:
   SEMANTIC_THRESHOLD=0.85
   
   O en el test:
   Given establezco el umbral de similitud semántica en 0.85

P: ¿Qué pasa si el modelo no está descargado?
R: Se descarga automáticamente la primera vez. Toma 1-2 minutos.

## GEMINI

P: ¿Necesito pagar para usar Gemini?
R: Sí, pero Google ofrece créditos gratis para empezar. Context Caching reduce
   mucho el costo.

P: ¿Cómo obtengo una API Key?
R: Ve a https://aistudio.google.com/app/apikey y crea una key gratis.

P: ¿Cuánto cuesta?
R: Depende del modelo y uso. Ejemplo con gemini-1.5-pro:
   - Input: $0.00125 por 1k tokens
   - Output: $0.005 por 1k tokens
   - Cache hit: $0.0003125 por 1k tokens (75% descuento)
   
   Con Context Caching, 1000 tests pueden costar ~$1-5 USD.

P: ¿Gemini es determinístico?
R: No 100%, pero con temperature=0.1 es muy consistente (~95%).

P: ¿Puedo usar Gemini offline?
R: No, requiere internet y conexión a la API de Google.

P: ¿Mis datos son privados?
R: Google procesa los datos pero según sus políticas no los usa para 
   entrenar modelos. Lee: https://ai.google.dev/gemini-api/terms

P: ¿Qué modelo debo usar?
R: Para empezar: gemini-2.5-flash (balanceado y económico)
   Para velocidad: gemini-2.5-flash-lite (más rápido y barato)
   Para precisión máxima: gemini-2.5-pro (más inteligente)
   Experimental: gemini-3-pro-preview (lo más avanzado)
   
   ⚠️ NO uses modelos 1.5 (deprecados desde 2025)

P: ¿Cómo funciona Context Caching?
R: Gemini guarda tu contexto (reglas de negocio) por 1 hora. Si haces múltiples
   tests en esa hora, solo pagas el contexto una vez.

P: ¿Cuándo se activa Context Caching?
R: Automáticamente cuando tu archivo de contexto tiene >= 32,000 tokens.
   Puedes cambiar el umbral con GEMINI_CACHE_THRESHOLD en .env.

P: ¿Puedo usar múltiples contextos?
R: Sí, puedes cargar varios contextos y cambiar entre ellos:
   Given el contexto "policies" está cargado desde "policies.txt"
   And el contexto "tech_docs" está cargado desde "docs.txt"
   When cambio al contexto de reglas de negocio "tech_docs"

P: ¿Gemini entiende español?
R: Sí, Gemini es multilingüe nativo y funciona excelente en español.


================================================================================
PARTE 7: MEJORES PRÁCTICAS
================================================================================

## SENTENCE TRANSFORMERS

✅ USA UMBRAL 0.75 PARA TESTING GENERAL
   Es el balance perfecto entre flexibilidad y precisión.

✅ USA UMBRAL 0.85+ PARA VALIDACIONES CRÍTICAS
   Cuando el texto debe ser muy similar.

✅ USA UMBRAL 0.60-0.70 PARA VALIDACIONES FLEXIBLES
   Cuando permites más variación en el texto.

✅ DESCARGA EL MODELO UNA VEZ
   En CI/CD, cachea el modelo para no descargarlo en cada build.

✅ USA MODELOS MULTILINGÜES
   Aunque tu app esté en español, usa modelos multilingües por si acaso.

❌ NO USES PARA VALIDACIONES EXACTAS
   Si necesitas texto exacto, usa comparación de strings normal.

❌ NO USES PARA CONTEXTO COMPLEJO
   Si necesitas entender reglas de negocio, usa Gemini.

## GEMINI

✅ USA CONTEXT CACHING PARA SUITES DE TESTS
   Si vas a hacer múltiples tests con el mismo contexto.

✅ ORGANIZA TUS ARCHIVOS DE CONTEXTO
   Separa por dominio: policies.txt, tech_docs.txt, faq.txt

✅ USA TEMPERATURE=0.1 PARA EVALUACIÓN
   Más consistente y determinístico.

✅ ESCRIBE CONTEXTOS CLAROS Y ESTRUCTURADOS
   Usa títulos, listas, secciones claras.

✅ ESTABLECE UMBRALES REALISTAS
   - 0.9+ → Excelencia
   - 0.8-0.89 → Bueno
   - 0.7-0.79 → Aceptable
   - < 0.7 → Necesita mejora

✅ REVISA LOS ERRORES CRÍTICOS
   Gemini te dice exactamente qué está mal.

❌ NO PONGAS INFORMACIÓN SENSIBLE EN EL CONTEXTO
   Aunque Google no entrena con tus datos, evita secretos.

❌ NO USES PARA VALIDACIONES SIMPLES
   Si Sentence Transformers puede hacerlo, úsalo (más rápido y barato).

❌ NO IGNORES EL REASONING
   Lee por qué Gemini dio ese score, aprenderás mucho.

## COMBINANDO AMBOS

✅ USA SENTENCE TRANSFORMERS PRIMERO
   Para validaciones rápidas y frecuentes.

✅ USA GEMINI PARA CASOS COMPLEJOS
   Cuando necesitas razonamiento o contexto extenso.

✅ ESTRUCTURA TUS TESTS POR VELOCIDAD
   Tests rápidos (Sentence Transformers) primero,
   Tests lentos (Gemini) después.

✅ CACHEA CONTEXTOS DE GEMINI
   Carga el contexto una vez en Background, úsalo en múltiples Scenarios.

✅ MONITOREA COSTOS
   Revisa tu uso de Gemini en Google Cloud Console.


================================================================================
PARTE 8: TROUBLESHOOTING (SOLUCIÓN DE PROBLEMAS)
================================================================================

## SENTENCE TRANSFORMERS

PROBLEMA: "ModuleNotFoundError: No module named 'sentence_transformers'"
SOLUCIÓN: Instala la librería:
  pip install sentence-transformers

PROBLEMA: "Model download is slow"
SOLUCIÓN: Es normal la primera vez. El modelo se descarga una sola vez.
  Puedes pre-descargarlo:
  python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('paraphrase-multilingual-MiniLM-L12-v2')"

PROBLEMA: "Tests fallan con similitud 0.74 pero umbral es 0.75"
SOLUCIÓN: Ajusta el umbral a 0.70 o revisa si los textos realmente son similares.
  A veces textos que parecen similares no lo son semánticamente.

PROBLEMA: "Similitud es muy baja (0.3) pero los textos parecen similares"
SOLUCIÓN: Verifica que:
  1. Estás usando un modelo multilingüe si los textos están en español
  2. Los textos realmente tienen el mismo significado
  3. No hay errores de ortografía que afecten el embedding

PROBLEMA: "El modelo usa mucha RAM"
SOLUCIÓN: Los modelos grandes (mpnet) usan más RAM. Usa modelos pequeños (MiniLM)
  o aumenta la RAM disponible.

## GEMINI

PROBLEMA: "ValueError: GEMINI_API_KEY no encontrada"
SOLUCIÓN: Configura tu API key en .env:
  GEMINI_API_KEY=tu_api_key_aqui

PROBLEMA: "Error 404: models/gemini-1.5-flash is not found"
SOLUCIÓN: Los modelos 1.5 están deprecados. Usa modelos 2.5 o 3.0:
  En .env cambia:
  GEMINI_JUDGE_MODEL=gemini-2.5-flash
  
  Modelos válidos:
  - gemini-2.5-pro (recomendado)
  - gemini-2.5-flash (rápido y económico)
  - gemini-2.5-flash-lite (más barato)
  - gemini-3-pro-preview (experimental)

PROBLEMA: "Error 429: Resource exhausted"
SOLUCIÓN: Has excedido tu cuota. Opciones:
  1. Espera unos minutos (límite de rate)
  2. Aumenta tu cuota en Google Cloud Console
  3. Usa Context Caching para reducir tokens

PROBLEMA: "Error 400: Invalid argument"
SOLUCIÓN: Verifica que:
  1. Tu API key es válida
  2. El modelo existe (gemini-1.5-pro-002, no gemini-1.5-pro)
  3. El contexto no excede el límite de tokens

PROBLEMA: "Gemini no devolvió respuesta (posible bloqueo de seguridad)"
SOLUCIÓN: Gemini bloqueó la respuesta por seguridad. Opciones:
  1. Revisa si tu contexto tiene contenido sensible
  2. Reformula el prompt
  3. Usa un modelo diferente

PROBLEMA: "Context Cache expired"
SOLUCIÓN: Normal después de 1 hora. Se creará un nuevo caché automáticamente.

PROBLEMA: "Gemini da scores inconsistentes"
SOLUCIÓN: Reduce temperature a 0.0 o 0.1 para más consistencia.

PROBLEMA: "Costos muy altos"
SOLUCIÓN: 
  1. Verifica que Context Caching esté activo (archivos > 32k tokens)
  2. Usa gemini-2.0-flash-exp (más barato)
  3. Reduce el tamaño de tus contextos
  4. Agrupa tests para reutilizar caché

PROBLEMA: "Error parseando JSON de Gemini"
SOLUCIÓN: A veces Gemini devuelve JSON con markdown. El framework lo limpia
  automáticamente, pero si falla:
  1. Verifica que el prompt pide JSON explícitamente
  2. Usa temperature=0.1
  3. Revisa los logs para ver qué devolvió Gemini


================================================================================
PARTE 9: RECURSOS ADICIONALES
================================================================================

## DOCUMENTACIÓN DEL FRAMEWORK

Para aprender a USAR estas tecnologías en el framework, consulta:

1. GUIA_VALIDACION_SEMANTICA_IA.txt
   - Guía completa de validación semántica
   - Todos los steps disponibles
   - Ejemplos prácticos

2. INICIO_RAPIDO_VALIDACION_SEMANTICA.txt
   - Tutorial rápido para empezar
   - Configuración básica
   - Primeros tests

3. GUIA_TESTING_GEMINI_COMPLETA.txt
   - Guía completa de Gemini
   - Context Caching
   - Evaluación como Juez
   - RAG testing

4. REFERENCIA_RAPIDA_GEMINI.txt
   - Referencia rápida de steps
   - Configuración
   - Ejemplos comunes

5. REFERENCIA_RAPIDA_GEMINI_AVANZADO.txt
   - Técnicas avanzadas
   - Optimización de costos
   - Casos de uso complejos

## DOCUMENTACIÓN EXTERNA

SENTENCE TRANSFORMERS:
  - Sitio oficial: https://www.sbert.net/
  - Modelos disponibles: https://www.sbert.net/docs/pretrained_models.html
  - GitHub: https://github.com/UKPLab/sentence-transformers

GOOGLE GEMINI:
  - Documentación: https://ai.google.dev/gemini-api/docs
  - Precios: https://ai.google.dev/pricing
  - API Key: https://aistudio.google.com/app/apikey
  - Context Caching: https://ai.google.dev/gemini-api/docs/caching

CONCEPTOS DE IA:
  - Embeddings: https://platform.openai.com/docs/guides/embeddings
  - LLMs: https://en.wikipedia.org/wiki/Large_language_model
  - RAG: https://www.promptingguide.ai/techniques/rag
  - Prompt Engineering: https://www.promptingguide.ai/

## COMUNIDAD Y SOPORTE

Si tienes preguntas o problemas:
  1. Revisa esta documentación primero
  2. Consulta los ejemplos en hakalab_framework/examples/
  3. Revisa los tests en testing/
  4. Contacta al equipo de desarrollo del framework


================================================================================
PARTE 10: RESUMEN EJECUTIVO
================================================================================

## EN POCAS PALABRAS

SENTENCE TRANSFORMERS:
  - QUÉ: Compara significado de textos usando matemáticas
  - CÓMO: Convierte texto en números (embeddings) y calcula similitud
  - CUÁNDO: Validaciones simples, rápidas, offline
  - COSTO: Gratis
  - VELOCIDAD: Milisegundos
  - EJEMPLO: "Tu pedido fue enviado" ≈ "Gracias, tu orden está en camino"

GOOGLE GEMINI:
  - QUÉ: IA que entiende reglas de negocio y evalúa respuestas
  - CÓMO: Lee tus políticas y actúa como juez experto
  - CUÁNDO: Evaluaciones complejas, contexto extenso
  - COSTO: Pago por uso (~$1-5 por 1000 tests con caching)
  - VELOCIDAD: Segundos
  - EJEMPLO: Evalúa si chatbot responde según 100 páginas de políticas

## DECISIÓN RÁPIDA

¿Necesitas validar texto simple?
  → Sentence Transformers

¿Necesitas evaluar contra reglas de negocio complejas?
  → Gemini

¿Necesitas ambos?
  → Usa ambos (rápido para lo simple, complejo para lo importante)

## CONFIGURACIÓN MÍNIMA

SENTENCE TRANSFORMERS:
  1. pip install sentence-transformers
  2. Listo (se descarga modelo automáticamente)

GEMINI:
  1. pip install google-genai
  2. Obtén API key: https://aistudio.google.com/app/apikey
  3. En .env: GEMINI_API_KEY=tu_key
  4. Listo

## PRIMER TEST

SENTENCE TRANSFORMERS:
  ```gherkin
  Scenario: Mi primer test semántico
    Given uso la configuración semántica por defecto
    Then el texto "Hola mundo" debe ser semánticamente similar a "Hello world"
  ```

GEMINI:
  ```gherkin
  Scenario: Mi primer test con Gemini
    Given el contexto de reglas de negocio "test" está cargado desde el archivo "context/rules.txt"
    When establezco la respuesta del SUT como "Esta es mi respuesta"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.8
  ```

================================================================================
FIN DEL DOCUMENTO
================================================================================

Este documento te ha explicado conceptualmente cómo funcionan las dos 
tecnologías de IA en el framework. Para aprender a USARLAS en tus tests,
consulta las guías prácticas mencionadas en la Parte 9.

¡Feliz testing con IA! 🚀

Última actualización: 2025
Versión: 1.0
