===========================================
REFERENCIA RÁPIDA - STEPS NLP
Framework Hakalab - Procesamiento de Lenguaje Natural
===========================================

Esta guía proporciona una referencia rápida de todos los steps NLP disponibles
en el framework, organizados por funcionalidad.

===========================================
ÍNDICE RÁPIDO
===========================================

1. Extracción de Entidades (NER)
2. Resumen Automático
3. Traducción Automática
4. Generación de Texto
5. Análisis de Toxicidad
6. Extracción de Keywords
7. Clustering de Textos
8. Question Answering (QA)
9. Análisis de Sentimiento
10. Clasificación de Texto
11. Detección de Idioma
12. Búsqueda Semántica

===========================================
1. EXTRACCIÓN DE ENTIDADES (NER)
===========================================

Extrae personas, organizaciones, lugares y otras entidades de un texto.

STEPS:
------
Then extraigo las entidades del texto "{text}" y las guardo en "{var_name}"
Then el texto "{text}" debe contener la entidad "{entity}" de tipo "{entity_type}"

TIPOS DE ENTIDADES:
------------------
- PER: Personas (Juan García, María López)
- ORG: Organizaciones (Microsoft, Google)
- LOC: Lugares (Madrid, España)
- MISC: Misceláneo (otros tipos)

EJEMPLO:
--------
Then extraigo las entidades del texto "Juan García trabaja en Microsoft en Madrid" y las guardo en "entidades"
# Resultado: {"PER": ["Juan García"], "ORG": ["Microsoft"], "LOC": ["Madrid"]}

Then el texto "Juan trabaja en Microsoft" debe contener la entidad "Microsoft" de tipo "ORG"


===========================================
2. RESUMEN AUTOMÁTICO
===========================================

Genera resúmenes automáticos de textos largos.

STEPS:
------
Then resumo el texto "{text}" y lo guardo en "{var_name}"
Then resumo el texto "{text}" con longitud máxima de {max_length} palabras y lo guardo en "{var_name}"

EJEMPLO:
--------
Then resumo el texto "${articulo_largo}" y lo guardo en "resumen"
Then resumo el texto "${articulo}" con longitud máxima de 50 palabras y lo guardo en "resumen_corto"


===========================================
3. TRADUCCIÓN AUTOMÁTICA
===========================================

Traduce textos entre diferentes idiomas.

IDIOMAS SOPORTADOS:
------------------
- es: Español
- en: Inglés
- fr: Francés
- de: Alemán
- pt: Portugués

STEPS:
------
Then traduzco el texto "{text}" de "{source_lang}" a "{target_lang}" y lo guardo en "{var_name}"
Then el texto "{text}" traducido de "{source_lang}" a "{target_lang}" debe ser semánticamente similar a "{expected}"

EJEMPLO:
--------
Then traduzco el texto "Hello world" de "en" a "es" y lo guardo en "traduccion"
# Resultado: "Hola mundo"

Then el texto "Hello world" traducido de "en" a "es" debe ser semánticamente similar a "Hola mundo"


===========================================
4. GENERACIÓN DE TEXTO
===========================================

Genera texto automáticamente basado en un prompt.

STEPS:
------
Then genero texto a partir del prompt "{prompt}" y lo guardo en "{var_name}"
Then genero texto a partir del prompt "{prompt}" con longitud máxima de {max_length} palabras y lo guardo en "{var_name}"

EJEMPLO:
--------
Then genero texto a partir del prompt "Escribe un mensaje de bienvenida" y lo guardo en "mensaje"
Then genero texto a partir del prompt "Responde amablemente" con longitud máxima de 30 palabras y lo guardo en "respuesta"


===========================================
5. ANÁLISIS DE TOXICIDAD
===========================================

Detecta contenido ofensivo, tóxico o inapropiado.

STEPS:
------
Then el texto "{text}" no debe ser tóxico
Then el texto "{text}" debe ser tóxico
Then calculo la toxicidad del texto "{text}" y la guardo en "{var_name}"

EJEMPLO:
--------
Then el texto "Gracias por tu ayuda" no debe ser tóxico
Then el texto "${comentario_usuario}" no debe ser tóxico
Then calculo la toxicidad del texto "${comentario}" y la guardo en "nivel_toxicidad"


===========================================
6. EXTRACCIÓN DE KEYWORDS
===========================================

Identifica las palabras clave más importantes de un texto.

STEPS:
------
Then extraigo las keywords del texto "{text}" y las guardo en "{var_name}"
Then extraigo {num_keywords} keywords del texto "{text}" y las guardo en "{var_name}"

EJEMPLO:
--------
Then extraigo las keywords del texto "${articulo}" y las guardo en "palabras_clave"
Then extraigo 10 keywords del texto "${documento}" y las guardo en "tags"
# Resultado: ["python", "programación", "desarrollo", ...]


===========================================
7. CLUSTERING DE TEXTOS
===========================================

Agrupa textos similares en clusters automáticamente.

STEPS:
------
Then agrupo los textos "{texts}" en {num_clusters} clusters y guardo el resultado en "{var_name}"

FORMATO DE TEXTOS:
-----------------
Separados por comas: "texto1,texto2,texto3"

EJEMPLO:
--------
Then agrupo los textos "Error de red,Fallo de conexión,Datos incorrectos" en 2 clusters y guardo el resultado en "grupos"
# Resultado: {"cluster_0": ["Error de red", "Fallo de conexión"], "cluster_1": ["Datos incorrectos"]}


===========================================
8. QUESTION ANSWERING (QA)
===========================================

Responde preguntas basándose en un contexto dado.

STEPS:
------
Then respondo la pregunta "{question}" basándome en el contexto "{context}" y guardo la respuesta en "{var_name}"

EJEMPLO:
--------
Then respondo la pregunta "¿Cuál es la capital?" basándome en el contexto "Francia es un país. París es su capital." y guardo la respuesta en "respuesta"
# Resultado: "París"

Then respondo la pregunta "¿Cuál es la fecha de vencimiento?" basándome en el contexto "${documento}" y guardo la respuesta en "fecha"


===========================================
9. ANÁLISIS DE SENTIMIENTO
===========================================

Analiza el sentimiento (positivo, negativo, neutral) de textos.

SENTIMIENTOS:
------------
- positivo: Connotación positiva
- negativo: Connotación negativa
- neutral: Sin carga emocional clara

STEPS:
------
Then el sentimiento del texto "{text}" debe ser "{sentiment}"
Then el sentimiento de la variable "{var_name}" debe ser "{sentiment}"

EJEMPLO:
--------
Then el sentimiento del texto "Me encanta este producto" debe ser "positivo"
Then el sentimiento de la variable "comentario" debe ser "negativo"


===========================================
10. CLASIFICACIÓN DE TEXTO
===========================================

Clasifica textos en categorías personalizadas usando similitud semántica.

STEPS:
------
Then clasifico el texto "{text}" en las categorías "{categories}" y guardo el resultado en "{var_name}"
Then el texto "{text}" debe pertenecer a la categoría "{expected_category}" de "{categories}"

FORMATO DE CATEGORÍAS:
---------------------
Separadas por comas: "categoria1,categoria2,categoria3"

EJEMPLO:
--------
Then clasifico el texto "Error de conexión" en las categorías "error,éxito,advertencia" y guardo el resultado en "tipo"
# Resultado: "error"

Then el texto "Operación exitosa" debe pertenecer a la categoría "éxito" de "error,éxito,advertencia"


===========================================
11. DETECCIÓN DE IDIOMA
===========================================

Detecta el idioma de un texto usando similitud semántica.

IDIOMAS SOPORTADOS:
------------------
- español
- inglés
- portugués
- francés
- alemán

STEPS:
------
Then detecto el idioma del texto "{text}" y lo guardo en "{var_name}"
Then el idioma del texto "{text}" debe ser "{expected_language}"

EJEMPLO:
--------
Then detecto el idioma del texto "Hello world" y lo guardo en "idioma"
# Resultado: "inglés"

Then el idioma del texto "Hola mundo" debe ser "español"


===========================================
12. BÚSQUEDA SEMÁNTICA
===========================================

Encuentra el texto más similar a una consulta en una lista de opciones.

STEPS:
------
Then busco el texto más similar a "{query}" en la lista "{options}" y lo guardo en "{var_name}"

FORMATO DE OPCIONES:
-------------------
Separadas por comas: "opcion1,opcion2,opcion3"

EJEMPLO:
--------
Then busco el texto más similar a "problema de red" en la lista "error de conexión,fallo de servidor,datos incorrectos" y lo guardo en "resultado"
# Resultado: "error de conexión"


===========================================
COMPARACIÓN MÚLTIPLE
===========================================

Compara un texto con múltiples referencias y muestra todas las similitudes.

STEPS:
------
Then comparo el texto "{text}" con múltiples referencias "{references}" y muestro las similitudes

FORMATO DE REFERENCIAS:
----------------------
Separadas por comas: "ref1,ref2,ref3"

EJEMPLO:
--------
Then comparo el texto "Pago exitoso" con múltiples referencias "Pago aprobado,Transacción completada,Pago procesado" y muestro las similitudes
# Muestra similitud con cada referencia


===========================================
EJEMPLOS DE FLUJOS COMPLETOS
===========================================

FLUJO 1: Análisis Completo de Ticket
------------------------------------
Scenario: Procesar ticket de soporte
  Given uso la configuración semántica por defecto
  When extraigo el texto del ticket en "ticket"
  
  # Extraer información
  Then extraigo las entidades del texto "${ticket}" y las guardo en "entidades"
  Then extraigo 5 keywords del texto "${ticket}" y las guardo en "temas"
  
  # Analizar contenido
  Then detecto el idioma del texto "${ticket}" y lo guardo en "idioma"
  Then el sentimiento de la variable "ticket" debe ser "negativo"
  Then el texto de la variable "ticket" no debe ser tóxico
  
  # Clasificar y resumir
  Then clasifico el texto "${ticket}" en las categorías "técnico,producto,facturación" y guardo el resultado en "departamento"
  Then resumo el texto "${ticket}" con longitud máxima de 50 palabras y lo guardo en "resumen"


FLUJO 2: Moderación de Comentario
---------------------------------
Scenario: Moderar comentario de usuario
  Given uso la configuración semántica por defecto
  When extraigo el comentario en "comentario"
  
  # Validaciones
  Then detecto el idioma del texto "${comentario}" y lo guardo en "idioma"
  Then el texto de la variable "comentario" no debe ser tóxico
  Then el sentimiento de la variable "comentario" debe ser "positivo"
  
  # Si pasa, aprobar comentario


FLUJO 3: Respuesta Automática FAQ
---------------------------------
Scenario: Responder pregunta automáticamente
  Given uso la configuración semántica por defecto
  When el usuario pregunta "¿Cuál es el horario?"
  
  # Buscar respuesta
  Then respondo la pregunta "${pregunta}" basándome en el contexto "${faq_documento}" y guardo la respuesta en "respuesta_base"
  
  # Generar respuesta personalizada
  Then genero texto a partir del prompt "Reformula de manera amable: ${respuesta_base}" y lo guardo en "respuesta_final"
  
  # Validar
  Then el sentimiento de la variable "respuesta_final" debe ser "positivo"


FLUJO 4: Testing de Localización
--------------------------------
Scenario: Validar traducciones
  Given uso la configuración semántica por defecto
  When extraigo el texto en inglés en "texto_en"
  
  # Traducir a español
  Then traduzco el texto "${texto_en}" de "en" a "es" y lo guardo en "texto_es"
  Then el texto de la variable "texto_es" debe ser semánticamente similar a "Operación exitosa"
  
  # Traducir a francés
  Then traduzco el texto "${texto_en}" de "en" a "fr" y lo guardo en "texto_fr"
  Then el texto de la variable "texto_fr" debe ser semánticamente similar a "Opération réussie"


FLUJO 5: Organización de Documentos
-----------------------------------
Scenario: Clasificar documentos
  Given uso la configuración semántica por defecto
  When extraigo todos los documentos en "documentos"
  
  # Extraer keywords
  Then extraigo 5 keywords del texto "${documento_1}" y las guardo en "keywords_1"
  
  # Agrupar similares
  Then agrupo los textos "${documentos}" en 5 clusters y guardo el resultado en "grupos"
  
  # Clasificar
  Then clasifico el texto "${documento_1}" en las categorías "legal,técnico,comercial" y guardo el resultado en "categoria"


===========================================
TIPS Y MEJORES PRÁCTICAS
===========================================

1. CONFIGURACIÓN INICIAL
------------------------
✅ Siempre inicia con: Given uso la configuración semántica por defecto
✅ Configura el modelo una sola vez al inicio del test
✅ Reutiliza el mismo modelo para múltiples validaciones

2. MANEJO DE VARIABLES
----------------------
✅ Usa variables para almacenar resultados intermedios
✅ Combina resultados de múltiples steps
✅ Usa ${variable} para referenciar variables guardadas

3. VALIDACIONES
--------------
✅ Combina validaciones NLP con validaciones tradicionales
✅ Usa validación semántica para contenido dinámico
✅ Usa validación exacta para IDs, códigos, números

4. PERFORMANCE
-------------
✅ Los modelos se descargan una sola vez (~5GB)
✅ Usa textos apropiados (no muy cortos ni muy largos)
✅ Considera usar GPU para procesamiento intensivo

5. DEBUGGING
-----------
✅ Usa "muestro en consola" para ver resultados
✅ Revisa los logs para ajustar umbrales
✅ Valida manualmente algunos casos

===========================================
REQUISITOS
===========================================

DEPENDENCIAS:
------------
- transformers>=4.30.0
- torch>=2.0.0
- sentence-transformers>=2.2.0
- keybert>=0.8.0
- scikit-learn>=1.3.0

INSTALACIÓN:
-----------
pip install hakalab-framework[full]

SISTEMA:
-------
- RAM: Mínimo 8GB (recomendado 16GB)
- Disco: ~5GB para modelos
- GPU: Opcional (acelera 10-50x)
- Internet: Primera descarga de modelos

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

DOCUMENTACIÓN:
-------------
- Guía completa: GUIA_VALIDACION_SEMANTICA_IA.txt
- Ejemplos: semantic_nlp_example.feature
- Casos de uso: Ver secciones 17-18 de la guía

SOPORTE:
-------
- GitHub Issues: https://github.com/hakalab/hakalab-framework
- Documentación oficial: Ver carpeta documentacion/

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

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