Estudio de caso / IA aplicada · Asistencia operativa
MAX Assistant
Conocimiento empresarial convertido en ayuda operativa.
Asistente web/PWA para repartidores que separa conversaciones, recuperación de conocimiento, decisiones, generación y herramientas operativas.
- Tecnologías utilizadas
- Angular PWA · NestJS · TypeScript · PostgreSQL · Prisma · pgvector · OpenAI · TypeSafe / Jev · Chatwoot · Docker
El problema
Los repartidores necesitan procedimientos y contexto operativo sin depender de preguntas repetidas a encargados. Un asistente útil debe usar conocimiento aprobado, respetar permisos y escalar cuando la información disponible no alcanza.
Mi participación
Desarrollo una PWA Angular y un backend NestJS independiente. Diseño Knowledge, Conversation Core, retrieval híbrido y contratos aislados de decisión y generación, junto con autenticación, controles de costes e integración operativa del MVP.
Qué permite hacer
Conversaciones con identidad y continuidad
Sesión propia del Assistant sobre autenticación de repartidores y conversaciones privadas. Los mensajes tienen orden e identidad idempotente; el usuario mantiene el contexto cuando la atención pasa a un operador humano mediante Chatwoot.
Conocimiento aprobado y recuperable
Knowledge organiza procedimientos, condiciones, prohibiciones y criterios de escalado. Artículos versionados se fragmentan e indexan mediante embeddings; la búsqueda combina señales lexicales y vectoriales en PostgreSQL/pgvector.
Ayuda con límites operativos
El orquestador compone clasificación, retrieval y generación con contexto acotado. Las herramientas del MVP consultan datos autorizados de envíos; no modifican la operación. Insuficiencia de contexto y escalado humano tienen rutas explícitas.
Cómo encajan las piezas
La PWA se comunica con una API propia, separada de AMXpress Core. Conversation Core conserva conversaciones y mensajes; Knowledge mantiene el contenido oficial. DecisionProvider clasifica la ruta, el Retriever obtiene evidencia y GenerationProvider redacta sobre ese contexto. El orquestador controla herramientas de lectura y handoff mediante adapters. Chatwoot se aísla con su propia base de datos y Redis en Docker.
- Angular PWAJWT · mensajes idempotentesConversation Core
- Orquestador → DecisionProviderClasificación · sin permisos ni accionesRuta validada
- Knowledge / pgvectorEvidencia aprobada · contexto acotadoRetriever → GenerationProvider
- OrquestadorLectura autorizada / escalado humanoTools / Chatwoot
Decisiones de ingeniería
Recuperar, decidir y generar por separado
Una consulta operativa no debe resolverse con una llamada libre al modelo. La decisión estructurada elige una ruta, retrieval aporta evidencia y generación redacta sobre ella. El orquestador valida contratos y resultados en cada etapa; la clasificación no concede permisos ni ejecuta herramientas por sí sola.
Versionar el conocimiento y conservar restricciones
Knowledge separa borrador, aprobación e indexación. La búsqueda híbrida fusiona rankings lexicales y vectoriales con RRF y conserva versiones y referencias. Los fragmentos mantienen condiciones, prohibiciones y escalado; antes de publicar una respuesta se revalida que la evidencia siga vigente.
Mantener autoridad y continuidad en backend
Conversation Core conserva propietario, secuencia e identidad de los mensajes; las ejecuciones registran etapas y consumo. El backend impone permisos, límites y timeouts, y reserva las herramientas del MVP a consultas autorizadas de sólo lectura. Evidencia insuficiente y escalado humano tienen rutas explícitas: ni el modelo ni el canal de atención sustituyen la autoridad del sistema.
Dificultades resueltas
Concurrencia en conversaciones
Conversation Core controla creación por propietario, secuencia y carreras entre cierre y mensajes. Una clave repetida sólo recupera el mismo mensaje del mismo propietario; un contenido distinto produce conflicto.
Evaluar antes de prometer autonomía
Decisión y generación se evalúan por separado con contratos, datasets y límites explícitos. Referencias válidas no prueban corrección semántica. El producto reserva la atención humana para consultas que no puede resolver con evidencia suficiente.
Capacidades demostrables
IA integrada a un sistema operativo
Conversaciones, versiones de Knowledge y metadata de los providers permiten seguir la evidencia utilizada en cada etapa.
Límites visibles y control humano
La consulta operativa es de sólo lectura. La insuficiencia de evidencia conduce a abstención o escalado; precisión, ahorro y autonomía requieren evaluación del producto final.