Saltar a contenido

ADR-006: Arquitectura Completa del Grafo Conversacional

Status

Accepted

Context

A medida que el AI Orchestrator ha evolucionado de un prototipo a un sistema production-ready, hemos tomado múltiples decisiones de diseño que no están completamente documentadas en los ADRs existentes. Este ADR captura la arquitectura completa del grafo conversacional y las decisiones clave que la componen.

Decision

1. State Management con TypedDict + Validación Adicional

Problema: Pydantic models no se integran perfectamente con LangGraph's state management, pero TypedDict carece de validación en tiempo de ejecución.

Solución: Usar TypedDict como base con decoradores de validación adicional (@validated_node).

Trade-offs: - ✅ Mejor integración con LangGraph - ✅ Validación en tiempo de ejecución cuando se necesita
- ❌ Más complejidad que usar solo Pydantic - ❌ Requiere disciplina para aplicar validación

2. Nodos Especializados vs. Single Node Genérico

Problema: ¿Deberíamos tener un nodo genérico que maneje todo o nodos especializados por dominio?

Solución: Implementar nodos especializados (booking_node, faq_node, chitchat_node, etc.).

Trade-offs: - ✅ Separación clara de responsabilidades - ✅ Más fácil de testear y mantener - ✅ Optimización específica por dominio - ❌ Más archivos y coordinación entre nodos - ❌ Complejidad en el routing

3. Validación en Cascada vs. Validación Única

Problema: ¿Validar inputs una vez al inicio o en cada paso del flujo?

Solución: Implementar validación en cascada - cada nodo valida sus inputs específicos.

Trade-offs: - ✅ Mayor robustez contra errores - ✅ Mensajes de error más específicos - ✅ Recuperación más granular - ❌ Ligera sobrecarga de validación - ❌ Código de validación distribuido

4. Dual RAG Strategy para Knowledge Retrieval

Problema: El RAG simple no distingue entre FAQs (respuestas exactas) y chunks (contexto general).

Solución: Implementar estrategia dual: - Primero buscar en FAQs con threshold alto (≥ 0.45) - Si no hay match, buscar en chunks con threshold bajo (≥ 0.38)

Trade-offs: - ✅ Respuestas más precisas para preguntas comunes - ✅ Contexto relevante para preguntas complejas - ❌ Mayor complejidad en la implementación - ❌ Dos llamadas potenciales a Qdrant

5. Anti-Hallucinación con Múltiples Capas

Problema: El LLM puede inventar información o filtrar instrucciones internas.

Solución: Implementar guards en múltiples capas: - System prompt fijo que define identidad - Regex post-procesamiento (_INSTRUCTION_LEAK_RE) - Validación de datos de negocio (nombre no puede ser "nuestro cliente") - Límites estrictos de contexto y tokens

Trade-offs: - ✅ Mayor confiabilidad en producción - ✅ Protección contra jailbreak básico - ❌ Complejidad adicional en el pipeline - ❌ Posible sobre-restricción en casos legítimos

6. Massive Evals como Gatekeeper de Calidad

Problema: Los cambios en prompts o lógica pueden romper comportamientos existentes silenciosamente.

Solución: Implementar Massive Evals (200 escenarios) como requisito obligatorio antes de cualquier PR que toque lógica conversacional.

Trade-offs: - ✅ Confianza extrema en la calidad de producción - ✅ Detección temprana de regresiones - ❌ Tiempo adicional en el proceso de desarrollo - ❌ Mantenimiento del conjunto de tests

Consequences

Positive

  • Sistema extremadamente confiable para producción
  • Claridad en las decisiones de diseño para nuevos desarrolladores
  • Base sólida para expansión a multi-agente
  • Protección contra los errores más comunes en sistemas LLM

Negative

  • Curva de aprendizaje más alta para nuevos miembros del equipo
  • Sobrecarga inicial en el desarrollo de features
  • Complejidad en la coordinación de múltiples componentes
  • ADR-001: Implementación de tools (LangGraph) contra Travel API v1
  • ADR-002: Exposición del orquestador vía FastAPI
  • ADR-003: Fallback Regex en nodo Extractor
  • ADR-004: MemorySaver vs RedisSaver

Implementation Status

  • [x] TimeLiberState con TypedDict + validación
  • [x] Nodos especializados implementados
  • [x] Validación en cascada en booking_node
  • [x] Dual RAG Strategy en faq_node
  • [x] Anti-hallucinación guards implementados
  • [x] Massive Evals framework funcional