Documentación de proyecto
Asistente Consular Digital (Botsito-1)
- Categoría
- Proyecto académico
- Stack técnico
- Node.js, Express, RAG / TF-IDF, Whisper, Llama 4 Scout, PII Redaction
Resumen
Botsito-1 es un asistente conversacional con inteligencia artificial pensado para la Embajada de Panamá en España, orientado a resolver dudas sobre trámites consulares: pasaportes, visados, poderes, autenticaciones, registro civil y citas.
Objetivo
Facilitar y agilizar la atención consular digital, respondiendo consultas ciudadanas de forma automática, precisa y accesible en distintos formatos.
Arquitectura general
Construido en Node.js y Express, con un diseño funcional organizado por responsabilidad única en vez de una estructura MVC clásica: un módulo orquesta el flujo de cada mensaje, y módulos separados se encargan de la búsqueda de información (RAG), la extracción de texto de documentos, la comunicación con el modelo de lenguaje, el análisis de sentimiento, las sesiones en memoria, la seguridad, y el aprendizaje de patrones de uso.
Expone nueve endpoints: creación de sesión, envío de mensajes de chat, subida de archivos, envío de audio, sugerencias de temas, feedback del usuario, verificación de estado del servicio, y un grupo de rutas de administración protegidas para gestionar la base de conocimiento.
Sistema RAG con TF-IDF
La búsqueda de información no usa embeddings ni una base de datos vectorial: es un motor de recuperación por TF-IDF (frecuencia de término / frecuencia inversa de documento) implementado íntegramente en el proyecto, sin dependencias externas de aprendizaje automático.
Cada documento oficial se corta en fragmentos de 1800 caracteres con 250 de solape entre fragmentos consecutivos. Ese tamaño fue ajustado deliberadamente: con fragmentos más pequeños, listas largas de requisitos (trámites con diez o más puntos) quedaban cortadas a la mitad y el asistente solo veía una parte de la lista al responder.
La consulta del usuario se normaliza (minúsculas, sin tildes) y se compara contra los fragmentos indexados por similitud de coseno. Además, el sistema incluye un diccionario de sinónimos coloquiales, aplicado únicamente a la consulta del usuario y nunca al texto oficial indexado, para no alterar el contenido de las fuentes pero sí adaptarse a cómo la gente pregunta en lenguaje cotidiano en vez de vocabulario legal exacto.
Cuando un fragmento relevante tiene vecinos inmediatos dentro del mismo documento, esos vecinos se agregan también al contexto: esto evita que un fragmento "del medio" de una lista larga quede fuera de los resultados por baja similitud aislada, y que la respuesta salga con un hueco en medio de una lista de requisitos. Los fragmentos finales se reordenan según su posición original en el documento, no por similitud, para que las listas conserven su orden natural.
La redacción final de la respuesta la genera un modelo de lenguaje grande a través de una API compatible con el estándar de OpenAI (actualmente Groq, con Llama 3.3 de 70 mil millones de parámetros), configurable por variables de entorno sin tocar código.
Entrada y salida multimodal
El asistente acepta mensajes de voz: el navegador graba el audio, se transcribe con Whisper (large-v3-turbo) y el texto resultante entra al mismo flujo de procesamiento que un mensaje escrito.
También acepta imágenes de documentos: se codifican y se envían a un modelo de visión (llama-4-scout) que extrae el texto visible y describe brevemente el documento, integrándose al mismo mecanismo que procesa archivos adjuntos (PDF, Word, texto).
Análisis de sentimiento y adaptación de estilo
El análisis de sentimiento es un mecanismo léxico en español, sin llamadas a un modelo de IA: compara el mensaje del usuario contra listas de palabras y frases positivas y negativas para clasificarlo como positivo, negativo o neutral. Ese resultado se usa para instruir el tono de la respuesta del modelo de lenguaje (por ejemplo, responder con más empatía ante frustración) y para detectar frustración sostenida a lo largo de la conversación, lo que hace que el asistente priorice sugerir contacto con un asesor humano.
El aprendizaje de estilo ocurre en dos niveles. A nivel de sesión, el sistema detecta si el usuario tiende a escribir mensajes breves o a usar un trato formal, y ajusta el estilo de respuesta en consecuencia; esta información vive solo en memoria y se descarta al cerrar la sesión. A nivel agregado, se lleva un contador anónimo (sin datos personales) de cuántas sesiones fueron breves o formales en general, usado únicamente como punto de partida para usuarios nuevos que todavía no han dado señales propias; las señales del usuario actual siempre tienen prioridad sobre ese promedio global.
Panel de administración
El acceso se controla con un token compartido, comparado en el servidor con un método resistente a ataques de temporización. Desde el panel se puede listar, subir y eliminar los documentos oficiales que forman la base de conocimiento, y forzar un reindexado, todo en caliente y sin reiniciar el servidor. El panel también muestra estadísticas de uso agregadas y anónimas: volumen de consultas, fragmentos indexados, escalaciones a un asesor, proporción de sentimiento negativo y tasa de feedback positivo.
Seguridad y privacidad
El sistema no persiste conversaciones ni archivos: las sesiones viven solo en memoria con expiración automática, y cualquier archivo o audio que el usuario suba se procesa y se elimina del disco inmediatamente después.
Los datos sensibles que pudieran aparecer en un mensaje (pasaportes, DNI o NIE español, cédula panameña, correos, teléfonos) se enmascaran mediante expresiones regulares antes de escribirse en los registros del servidor. Es una protección específicamente sobre los logs, no un filtro que revise la respuesta final que recibe el usuario; esa parte depende de una instrucción explícita en las reglas del asistente, que le indica no repetir datos sensibles que el usuario comparta.
Toda la API está limitada a 30 peticiones por minuto por dirección IP, y el servidor aplica cabeceras de seguridad HTTP con una política de contenido restrictiva.
Pruebas
El proyecto incluye dos suites de pruebas basadas en aserciones nativas de Node, sin un framework de testing externo. Una simula el modelo de lenguaje para poder probar la lógica del sistema de forma aislada y reproducible: búsqueda RAG, sinónimos, análisis de sentimiento, flujo completo del asistente, manejo de documentos adjuntos con memoria de conversación, aislamiento entre sesiones de distintos usuarios, y seguridad. La otra ejecuta pruebas de integración HTTP contra el servidor real en marcha: sesiones, subida de archivos, feedback, y el panel de administración completo, incluyendo el límite de peticiones por minuto.
Decisiones técnicas
- TF-IDF en vez de embeddings o una base de datos vectorial, evitando dependencias de aprendizaje automático y el costo de un servicio externo de embeddings.
- Reintentos solo ante el error HTTP 429 (demasiadas peticiones), con espera creciente entre cada intento, para no reintentar fallos que un reintento no resolvería.
- Temperatura baja pero no nula en el modelo de lenguaje: las respuestas necesitan ser consistentes al listar requisitos de un trámite, pero completamente en cero sonaría mecánico.
- El modelo de lenguaje responde en un formato JSON estructurado (respuesta, si necesita escalarse a un asesor, y datos de verificación), con una ruta de respaldo a texto plano si ese formato falla al interpretarse.
Estado actual
El proyecto está en desarrollo y aún no publicado formalmente. La base de conocimiento activa actualmente consiste en un instructivo oficial del Registro Civil panameño, y está pensada para ampliarse con más documentos oficiales desde el panel de administración a medida que el proyecto avance.