Skip to content

Arquitectura y Flujo de Datos: Protocolo Éxodo

Resumen Operativo

El Protocolo Éxodo es un sistema asincrónico basado en eventos, diseñado para demostrar las capacidades de orquestación de Urania. Desplegado en un entorno VPS Linux, el sistema conecta un frontend inmersivo con agentes cognitivos (Cosmo y Argos) a través de la API oficial de WhatsApp, persistiendo estados conversacionales localmente y delegando el procesamiento de metadatos pesados al ecosistema de Google Cloud.

1. Diagrama de Secuencia del Recluta

El siguiente diagrama detalla el "Happy Path" de un usuario, desde la captura inicial de sus datos en la solicitud de reclutamiento hasta el renderizado final de su estrella en el Mapa Celestial.

sequenceDiagram
    autonumber
    actor Usuario
    participant Portal as Frontend (urania.vision)
    participant DB_P as protocolo_exodo.db
    participant Main as main_cosmo_argos.py
    participant WA as whatsapp_api.py
    participant Memoria as memoria_exodo.db
    participant Cosmo as Agente Cosmo
    participant Argos as Agente Argos
    participant Utils as Cloud Utils

    rect rgb(200, 220, 240)
    Note over Usuario, DB_P: Fase 1: Captura
    Usuario->>Portal: Envía Formulario
    Portal->>DB_P: INSERT fila (datos + contactado=0)
    Portal-->>Usuario: Muestra Código de Acceso
    end

    rect rgb(220, 240, 200)
    Note over DB_P, WA: Fase 2: Orquestación
    Main->>DB_P: SELECT limit 10 WHERE contactado=0
    Main->>WA: Trigger mensaje de bienvenida
    WA->>Usuario: Mensaje WhatsApp 
    WA-->>Main: Status 200 (Enviado)
    Main->>DB_P: UPDATE contactado=1
    end

    rect rgb(240, 220, 200)
    Note over Usuario, Cosmo: Fase 3: Bucle Cognitivo
    Usuario->>WA: Responde Código
    WA->>Main: Webhook (Mensaje entrante)
    Main->>Memoria: Check/Update estado
    Main->>Cosmo: Pasa contexto
    Cosmo-->>Main: Genera consigna (1/7)
    Main->>WA: Envía pregunta
    end

    rect rgb(230, 210, 240)
    Note over Cosmo, Utils: Fase 4: Inferencia
    Cosmo->>Argos: Call con transcript
    Argos-->>Argos: Calcula Taxonomía y Ejes
    Argos->>Utils: radar.py (Boarding Pass)
    Argos->>Utils: storage_utils.py (JSON a GCS)
    end

    rect rgb(240, 240, 210)
    Note over Usuario, Utils: Fase 5: Cierre
    Cosmo->>WA: Envía Assets visuales
    Main->>Utils: drive_api.py (Respaldo Drive)
    Main->>Utils: agent_to_gcs.py (Telemetría)
    end

2. Topología de Componentes Backend

Toda la lógica core opera sobre el VPS de Urania, estructurada en micro-scripts de Python diseñados para manejar alta concurrencia sin bloquear el hilo principal.

2.1 Gestión de Colas y Estado Local

El sistema utiliza bases de datos ligeras locales (.db) para administrar el estado de forma transaccional y rápida:

  • protocolo_exodo.db (Fila de Ingreso): Almacena el payload original del usuario (Afinidad Tech, Blockchain, IA, etc.). Actúa como una cola pasiva. El estado de procesamiento se maneja a través de la bandera contactado (0: En cola, 1: Contactado, -1: Error en Meta).
  • memoria_exodo.db (State Machine Conversacional): Fundamental para la persistencia. Permite que el sistema sea stateless a nivel de memoria RAM, guardando la fase exacta de la evaluación de cada usuario. Evita bucles infinitos y permite retomar conversaciones pausadas.
  • reclutas_fallidos.txt (Dead Letter Queue): Log en texto plano para auditoría rápida de respuestas de error provenientes del endpoint de Meta.

Consideración de Concurrencia

El acceso a las bases .db se gestiona a través de database.py utilizando métodos asincrónicos para evitar bloqueos de escritura cuando múltiples reclutas interactúan simultáneamente con el Webhook de WhatsApp.

2.2 Orquestación Central

  • main_cosmo_argos.py: Es el corazón del sistema. Opera mediante polling (buscando lotes de 10 usuarios con contactado=0) y actúa como enrutador del webhook de respuestas. Administra los handoffs (cambios de contexto) entre el Agente Cosmo y el Agente Argos.

2.3 Agentes Cognitivos

  • Agente Cosmo: Optimizado para interacción conversacional y prompting adaptativo. Su contexto (System Prompt) le indica cómo comportarse durante la entrevista de 7 pasos, evaluando tolerancia al estrés y heurística sin romper la inmersión del jugador.
  • Agente Argos: Optimizado para análisis de datos taxonómicos. No interactúa con el usuario; recibe un bloque de texto estructurado de Cosmo, realiza la inferencia sobre las 5 categorías cognitivas y devuelve un JSON estandarizado para los módulos de renderizado.

2.4 Módulos de Utilidad y Nube

Integración GCS y Drive

Los scripts de esta capa manejan el offloading de archivos pesados y la auditoría, liberando el almacenamiento del VPS local.

  • radar.py: Motor de renderizado. Consume la salida de Argos para componer el Boarding Pass en formato imagen.
  • whatsapp_api.py: Wrapper de la API Graph de Meta para mensajería y multimedia.
  • storage_utils.py & drive_api.py: Empujan metadatos (etiquetas de Argos) al bucket de GCS y resguardan transcripciones completas en Google Drive.
  • agent_to_gcs.py: Script crítico para el modelo de negocio. Sincroniza el gasto de tokens de OpenAI/Gemini con Cloud Storage, permitiendo un análisis preciso del costo de adquisición por usuario (CAC) de la campaña.