===========================================
EJEMPLOS DEL FRAMEWORK HAKALAB
===========================================

Esta carpeta contiene ejemplos completos de uso del framework Hakalab,
incluyendo archivos de configuración, esquemas, payloads y features de ejemplo.

===========================================
ESTRUCTURA DE DIRECTORIOS
===========================================

examples/
├── context/                    # Archivos de contexto para Gemini
│   ├── customer_service_rules.txt    # Reglas de servicio al cliente
│   ├── tech_support_rules.txt        # Reglas de soporte técnico
│   └── api_specification_example.txt # Especificación de API (ejemplo) ⭐ NUEVO
│
├── schemas/                    # Esquemas JSON Schema (Draft 7)
│   ├── user_schema.json       # Esquema de usuario
│   ├── order_schema.json      # Esquema de orden
│   └── error_schema.json      # Esquema de error
│
├── expected/                   # Respuestas esperadas para comparación
│   └── user_123.json          # Respuesta esperada de usuario
│
├── payloads/                   # Cuerpos de peticiones (request bodies)
│   ├── create_user.json       # Payload para crear usuario
│   └── create_order.json      # Payload para crear orden
│
├── responses/                  # Respuestas guardadas (para debugging)
│   └── (archivos generados durante tests)
│
├── *.feature                   # Archivos de ejemplo de features
│   ├── semantic_validation_example.feature
│   ├── semantic_advanced_example.feature
│   ├── semantic_nlp_example.feature
│   ├── api_testing_advanced_example.feature
│   ├── gemini_evaluation_example.feature
│   └── gemini_technical_docs_example.feature ⭐ NUEVO
│
└── README_EXAMPLES.txt         # Este archivo

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

FEATURES:
---------

1. semantic_validation_example.feature
   - Validación semántica básica
   - Configuración de modelos y umbrales
   - Validación de similitud de textos
   - Casos de uso: Validación de respuestas de LLM

2. semantic_advanced_example.feature
   - Análisis de sentimiento
   - Clasificación de texto
   - Detección de idioma
   - Búsqueda semántica
   - Casos de uso: Análisis de feedback, moderación

3. semantic_nlp_example.feature
   - Extracción de entidades (NER)
   - Resumen automático
   - Traducción automática
   - Generación de texto
   - Análisis de toxicidad
   - Extracción de keywords
   - Clustering de textos
   - Question Answering
   - Casos de uso: Procesamiento de tickets, FAQs automáticas

4. api_testing_advanced_example.feature
   - Validación con JSON Schema
   - Comparación con archivos
   - Validación de tipos y patrones
   - Validación de arrays
   - Flujos completos de CRUD
   - Casos de uso: Testing robusto de APIs REST

5. gemini_evaluation_example.feature
   - Testing de chatbots con Gemini como Juez
   - Evaluación con múltiples contextos
   - Criterios personalizados de evaluación
   - Respuestas desde archivos
   - Limpieza de cachés
   - Casos de uso: Validación de LLMs, chatbots, contenido generado

6. gemini_technical_docs_example.feature ⭐ NUEVO
   - Validación de documentación técnica generada por IA
   - Validación de especificaciones de API (OpenAPI/Swagger)
   - Validación de respuestas de soporte técnico
   - Validación de traducciones técnicas
   - Validación de guías de migración
   - Casos de uso: Documentación de APIs, manuales técnicos, cumplimiento

ARCHIVOS DE CONTEXTO (GEMINI):
-------------------------------

1. customer_service_rules.txt
   - Reglas de servicio al cliente
   - Políticas de atención
   - Ejemplos de respuestas correctas
   - Usado en: gemini_evaluation_example.feature

2. tech_support_rules.txt
   - Reglas de soporte técnico
   - Procedimientos de troubleshooting
   - Restricciones de seguridad
   - Usado en: gemini_evaluation_example.feature

3. api_specification_example.txt ⭐ NUEVO
   - Especificación completa de API REST
   - Endpoints, parámetros, validaciones
   - Códigos de error y ejemplos
   - Usado en: gemini_technical_docs_example.feature

ESQUEMAS JSON SCHEMA:
---------------------

1. user_schema.json
   - Esquema completo de usuario
   - Incluye: id, name, email, age, roles, profile
   - Validaciones: tipos, formatos, rangos, required

2. order_schema.json
   - Esquema de orden de e-commerce
   - Incluye: items, shipping_address, totales
   - Validaciones: arrays, objetos anidados, rangos

3. error_schema.json
   - Esquema de respuestas de error
   - Incluye: code, message, details
   - Validaciones: estructura de errores estándar

PAYLOADS:
---------

1. create_user.json
   - Payload para crear usuario
   - Incluye todos los campos requeridos
   - Ejemplo de estructura válida

2. create_order.json
   - Payload para crear orden
   - Incluye items y dirección de envío
   - Ejemplo de estructura compleja

RESPUESTAS ESPERADAS:
---------------------

1. user_123.json
   - Respuesta esperada de GET /users/123
   - Incluye todos los campos del usuario
   - Usado para comparación en tests

===========================================
CÓMO USAR LOS EJEMPLOS
===========================================

1. COPIAR ESTRUCTURA A TU PROYECTO
-----------------------------------

Copia la estructura de directorios a tu proyecto:

tu_proyecto/
├── schemas/
├── expected/
├── payloads/
└── responses/

2. ADAPTAR ESQUEMAS
-------------------

Modifica los esquemas JSON Schema según tu API:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "TuObjeto",
  "type": "object",
  "required": ["campo1", "campo2"],
  "properties": {
    "campo1": {"type": "string"},
    "campo2": {"type": "integer"}
  }
}

3. CREAR PAYLOADS
-----------------

Crea archivos JSON con los datos de prueba:

{
  "nombre": "Valor de prueba",
  "campo": "Otro valor"
}

4. USAR EN FEATURES
-------------------

Referencia los archivos en tus features:

Scenario: Crear usuario
  When cargo JSON del archivo "payloads/create_user.json" y envío POST a "/api/users" guardando respuesta en variable "response"
  Then verifico que el JSON de respuesta API coincide con el esquema del archivo "schemas/user_schema.json"

===========================================
EJEMPLOS POR CASO DE USO
===========================================

CASO 1: Validación de API REST
-------------------------------
Ver: api_testing_advanced_example.feature
- Validación con esquemas
- Comparación con archivos
- Validación de tipos y patrones

CASO 2: Validación Semántica
-----------------------------
Ver: semantic_validation_example.feature
- Validación de respuestas de LLM
- Textos dinámicos
- Mensajes multilingües

CASO 3: Análisis de Texto
--------------------------
Ver: semantic_advanced_example.feature
- Análisis de sentimiento
- Clasificación de texto
- Detección de idioma

CASO 4: Procesamiento NLP
--------------------------
Ver: semantic_nlp_example.feature
- Extracción de entidades
- Resumen automático
- Traducción
- Question Answering

CASO 5: Testing de Chatbots con IA
-----------------------------------
Ver: gemini_evaluation_example.feature
- Validación de respuestas de chatbots
- Evaluación de LLMs (GPT, Claude, etc.)
- Validación de contenido generado
- Testing multilingüe

CASO 6: Validación de Documentación Técnica ⭐ NUEVO
-----------------------------------------------------
Ver: gemini_technical_docs_example.feature
- Validación de documentación de APIs generada por IA
- Verificación de especificaciones técnicas (OpenAPI/Swagger)
- Validación de respuestas de soporte técnico
- Validación de traducciones técnicas
- Validación de guías de migración y cambios de versión

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

1. ORGANIZACIÓN
---------------
✅ Mantén esquemas versionados (user_schema_v1.json, user_schema_v2.json)
✅ Usa nombres descriptivos para archivos
✅ Agrupa archivos por funcionalidad o módulo
✅ Documenta cambios en esquemas

2. MANTENIMIENTO
----------------
✅ Actualiza esquemas cuando cambie la API
✅ Mantén payloads sincronizados con esquemas
✅ Revisa respuestas esperadas periódicamente
✅ Limpia archivos de responses/ después de debugging

3. REUTILIZACIÓN
----------------
✅ Crea esquemas base y extiéndelos
✅ Usa $ref para referenciar esquemas comunes
✅ Reutiliza payloads en múltiples tests
✅ Mantén esquemas DRY (Don't Repeat Yourself)

4. VERSIONADO
-------------
✅ Versiona esquemas junto con el código
✅ Usa control de versiones (Git) para todos los archivos
✅ Documenta cambios en CHANGELOG
✅ Mantén compatibilidad hacia atrás cuando sea posible

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

DOCUMENTACIÓN:
--------------
- GUIA_API_TESTING_NotebookLM.txt - Guía completa de API testing
- GUIA_VALIDACION_SEMANTICA_IA.txt - Guía de validación semántica
- GUIA_TESTING_GEMINI_COMPLETA.txt - Guía completa de Gemini como Juez ⭐ NUEVO
- REFERENCIA_RAPIDA_API_TESTING.txt - Referencia rápida de steps
- REFERENCIA_RAPIDA_NLP.txt - Referencia rápida de NLP
- REFERENCIA_RAPIDA_GEMINI.txt - Referencia rápida de Gemini ⭐ NUEVO

HERRAMIENTAS:
-------------
- JSON Schema Validator: https://jsonschemavalidator.net
- JSON Diff: https://jsondiff.com
- Regex Tester: https://regex101.com
- JSON Formatter: https://jsonformatter.org

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

===========================================
FIN DEL README
===========================================

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