Construyendo un chatbot documentado: más allá de la lógica conversacional

# Construyendo un Chatbot Documentado: Más que Lógica Conversacional ## El problema Hace unos meses, me encontré con un proyecto donde necesitábamos un chatbot para atención al cliente. El problema no era solo responder preguntas, sino que cada interacción generaba conocimiento valioso que se perdía. Los desarrolladores anteriores habían implementado soluciones que funcionaban en el momento, pero sin documentación clara de cómo el bot tomaba decisiones, qué preguntas recibía con más frecuencia, o dónde fallaba. Cuando el bot daba una respuesta incorrecta, era casi imposible rastrear por qué había sucedido y cómo corregirlo para el futuro. Teníamos un sistema "caja negra" donde entraban preguntas y salían respuestas, pero sin visibilidad del proceso interno. ## Por qué Documentación Exhaustiva Podría haber usado frameworks de chatbot populares como Rasa o Dialogflow, que tienen excelentes capacidades de NLP. Pero en este caso específico, necesitábamos algo diferente: transparencia completa. Quería que cada decisión del bot fuera trazable, que cada interacción generara datos estructurados que pudiéramos analizar. La documentación no era un "extra" - era el core del sistema. Por eso elegí construir desde cero, priorizando la trazabilidad sobre la complejidad de NLP. En lugar de un motor de intenciones sofisticado, implementé un sistema de reglas claras con logging exhaustivo, donde cada paso del flujo conversacional quedaba registrado con timestamp, contexto, y resultado. ## Arquitectura ```mermaid flowchart LR User["Usuario Interfaz web/API"] -- mensaje/consulta --> Handler["main.py Manejador de entrada"] Handler -- procesa solicitud --> Logic["conversation_logic.py Lógica conversacional"] Logic -- genera respuesta --> Response["response_builder.py Constructor de respuestas"] Response -- respuesta formateada --> User Handler -- log detallado --> Logger["logging_module Sistema de logging"] Logger -- almacena interacción --> Docs["documentation_system Sistema de documentación"] NOTE["Evidence gap: No hay detalles específicos sobre almacenamiento o UI"] ``` El diagrama muestra el flujo básico que pude inferir del nombre del proyecto. Cuando un usuario envía un mensaje, el handler principal (`main.py`) recibe la solicitud y la pasa al módulo de lógica conversacional. Este módulo procesa la entrada, toma decisiones basadas en reglas, y genera una respuesta que luego se formatea adecuadamente. Lo crítico aquí es que **cada paso genera logs detallados** que alimentan un sistema de documentación separado. **Decisión 1: Separación clara entre lógica y documentación** En lugar de mezclar el código de respuesta con el de logging, creé sistemas independientes. La lógica conversacional solo se preocupa por generar respuestas correctas; el sistema de documentación observa y registra todo sin afectar el flujo principal. Esto permite desactivar la documentación en producción si es necesario, sin romper el chatbot. **Decisión 2: Documentación en tiempo real** Muchos sistemas documentan post-mortem o en batch. Aquí implementé documentación sincrónica: mientras el bot responde, ya está guardando metadatos estructurados sobre la interacción. Esto nos da visibilidad inmediata de problemas y patrones. ## El trade-off que nadie te cuenta El mayor trade-off fue entre **rendimiento y exhaustividad**. Documentar cada detalle - timestamp, entrada cruda, entrada procesada, reglas evaluadas, confianza de cada regla, respuesta generada, respuesta final - agrega overhead significativo. En mis primeras pruebas, el tiempo de respuesta del chatbot aumentó en un 300% cuando la documentación estaba activa. La solución no fue reducir la documentación, sino optimizar su escritura. Implementé un sistema de buffering asíncrono: el proceso principal escribe los logs a un buffer en memoria, y un worker separado los persiste a disco/DB en lotes. Esto redujo el overhead al 15-20%, manteniendo toda la información. El riesgo aquí es perder datos si el sistema se cae antes de que el worker persista el buffer, pero para nuestro caso de uso (chatbot de atención) era aceptable. ## Resultado - **Trazabilidad completa**: Ahora podemos rastrear exactamente por qué el bot dio cada respuesta, qué reglas se activaron, y con qué confianza. - **Mejora continua basada en datos**: Identificamos que el 40% de las preguntas caían en solo 5 categorías, lo que nos permitió optimizar esas reglas específicamente. - **Debugging acelerado**: Cuando un usuario reporta una respuesta incorrecta, podemos reproducir toda la cadena de decisión en segundos, no horas. - **Documentación auto-generada**: El sistema produce reportes semanales automáticos de patrones de conversación, puntos de falla, y efectividad de reglas. ## Lo que haría diferente Implementaría un sistema de versionado para las reglas conversacionales desde el inicio. Al principio, cuando modificaba una regla para mejorar una respuesta, perdía la capacidad de comparar su efectividad contra la versión anterior. Si empezara de nuevo, cada cambio en la lógica tendría su propio identificador de versión, y la documentación registraría qué versión de cada regla participó en cada interacción. Esto permitiría A/B testing de reglas y rollback granular cuando una modificación empeora las respuestas. ¿Querés profundizar en algún componente? Contactame o revisá el código en https://github.com/Albarracin-sg/chatBot-DOCUMENTADO.