# GUÍA DEFINITIVA: CÓMO CONSTRUIR TU AGENTE INTELIGENTE DUAL
### TAKEOFF ENGINE — ARQUITECTURA DE ALTO RENDIMIENTO

Bienvenido a la guía oficial de diseño y despliegue de agentes en **Takeoff Engine**. Este documento explica paso a paso cómo funciona el sistema, cómo estructurar el comportamiento de tu asistente y cómo opera la arquitectura dual en producción.

---

## 1. DIAGRAMA DE FLUJO: LA ARQUITECTURA DUAL EN ACCIÓN

El sistema no utiliza un único chatbot lento. Opera con un **Sistema Dual Asíncrono**: un agente frontal ultrarrápido para atención humana y un sidecar en segundo plano para estructuración y cálculo del termostato.

```mermaid
flowchart TD
    subgraph CANAL_ENTRADA["Canal de Entrada"]
        USER["Usuario (WhatsApp / Web)"]
        INPUT_MSG["Mensaje (Texto / Audio / Foto)"]
    end

    subgraph INGESTA_DETERMINISTICA["Capa 1: Ingesta Determinística"]
        ROUTER{"Tipo de Mensaje"}
        WHISPER["faster-whisper (:5002) / Groq"]
        VISION["Visión OCR (Comprobantes/PDF)"]
        REGEX["Extracción Regex Local (Tel, Email, DNI)"]
    end

    subgraph MOTOR_DUAL["Capa 2: Motor Dual Asíncrono"]
        direction TB
        subgraph TRACK_1["Track 1: Frontend Conversacional (<1.2s)"]
            FRONT_LLM["Agente Frontal (gpt-4o-mini / Haiku)"]
            STREAM["Streaming de Respuesta Empática"]
        end
        subgraph TRACK_2["Track 2: Extraction Sidecar (Background)"]
            SIDECAR["Extractor Estructurado (Strict JSON)"]
            COLLISION["Resolución de Colisiones (superseded_by)"]
            TERMOSTATO["Cálculo del Termostato (0% - 100%)"]
        end
    end

    subgraph MEMORIA_ESTADO["Capa 3: Memoria y Base de Datos"]
        LEADS_DB[("PostgreSQL: public.leads")]
        SLOTS_DB[("PostgreSQL: public.extracted_data")]
        ROLLING_MEM["Resumen Rodante (cada 10 turnos)"]
    end

    subgraph GUARDRAILS_HANDOFF["Capa 4: Guardrails y Handoff"]
        GUARD_CLOSE{"¿Termostato == 100%?"}
        FORCE_Q["Forzar Siguiente Pregunta Pendiente"]
        HANDOFF["Handoff Humano: Alerta WhatsApp + CRM"]
    end

    %% Flujos
    USER --> INPUT_MSG --> ROUTER
    ROUTER -- "Nota de Voz" --> WHISPER --> REGEX
    ROUTER -- "Documento/Foto" --> VISION --> REGEX
    ROUTER -- "Texto" --> REGEX

    REGEX --> FRONT_LLM
    REGEX --> SIDECAR

    FRONT_LLM --> STREAM --> USER
    SIDECAR --> COLLISION --> SLOTS_DB
    SLOTS_DB --> TERMOSTATO --> LEADS_DB

    FRONT_LLM -. "Verifica Cierre" .-> GUARD_CLOSE
    GUARD_CLOSE -- "Falso Cierre (Termostato < 100%)" --> FORCE_Q --> FRONT_LLM
    GUARD_CLOSE -- "Calificado (Termostato = 100%)" --> HANDOFF

    LEADS_DB -. "Contexto Activo" .-> FRONT_LLM
    ROLLING_MEM -. "Historial Comprimido" .-> FRONT_LLM
```

---

## 2. GUÍA PASO A PASO PARA CONSTRUIR TU AGENTE

### PASO 1: Definir la Identidad y el Canal
* **Nombre del Asistente:** Dale un nombre propio reconocible (ej. *Sofía*, *Carlos Mora*, *Martín Asistente*).
* **Voz y Tono:** Tuteo educado, ejecutivo o cercano. Instrucción estricta: **no usar fórmulas robóticas** (*"Anotado en sistema"*, *"Dato registrado"*).
* **Canales Habilitados:**
  - WhatsApp (vía Evolution API / Baileys).
  - Web Chat embebible (Widget flotante con soporte de micrófono).

---

### PASO 2: Configurar los Slots del Termostato (Checklist de Calificación)
El Termostato mide el porcentaje de avance del lead ($0\%$ a $100\%$). Cada dato que necesitas que el cliente responda es un **slot**:

| Campo Técnico | Pregunta Sugerida al Cliente | Tipo de Dato | Peso (%) | Obligatorio |
| :--- | :--- | :--- | :---: | :---: |
| `nombre_completo` | "¿Con quién tengo el gusto de hablar?" | Texto / Regex | 15% | Sí |
| `telefono_contacto` | "¿A qué número de WhatsApp te podemos contactar?" | Teléfono (Regex) | 20% | Sí |
| `necesidad_principal`| "¿Qué producto o servicio estás buscando hoy?" | Texto libre | 25% | Sí |
| `presupuesto_rango` | "¿Qué rango de inversión tienes contemplado?" | Numérico / Moneda | 20% | Sí |
| `fecha_decision` | "¿Para qué fecha estimada necesitas comenzar?" | Fecha / Rango | 20% | Sí |

> **Regla de Oro:** El Termostato solo llega al 100% cuando **todos los campos obligatorios** tienen un valor confirmado.

---

### PASO 3: Activar la Multimodalidad (Fotos, Audios y Archivos)

#### A. Envío de Fotos de Catálogo (Rentas & E-Commerce):
* Configura la carpeta o galería de productos en el sistema.
* Cuando el cliente pregunta por un producto o inmueble, el agente despacha automáticamente un lote de 3 a 5 fotos de alta resolución con texto explicativo.

#### B. Recepción de Audios (Notas de Voz):
* El motor transcribe la nota de voz a texto plano de inmediato mediante **faster-whisper local** o **Groq Whisper**.
* El agente frontal procesa el mensaje como si fuera texto escrito, sin fricción para el usuario.

#### C. Recepción de Archivos y Documentos:
* Si el cliente envía fotos de su DNI, comprobante de pago o contratos en PDF, el extractor estructurado lee los datos y los asigna automáticamente a los slots del cliente.

---

### PASO 4: Calibrar los Guardrails de Seguridad

1. **Guardrail Anti-Falso Cierre:** Impide que el asistente se despida o diga *"Un asesor te contactará"* si el Termostato no ha alcanzado el 100%. Si intenta cerrar antes de tiempo, el motor inyecta automáticamente la siguiente pregunta pendiente.
2. **Protección PII:** Los números de teléfono, DNI o tarjetas son capturados por filtros locales y jamás se envían en claro a IAs de terceros.
3. **Anti-Fechas Inventadas:** Valida que el año o día citado por la IA figure explícitamente en lo que el cliente escribió.

---

### PASO 5: Handoff y Derivación Comercial

Cuando el Termostato marca $100\%$:
1. Se genera la **Ficha 360 del Lead** con el resumen ejecutivo de la conversación.
2. Se envía una **alerta inmediata por WhatsApp** al asesor comercial con el botón de contacto directo.
3. Se actualiza el estado en el CRM o webhook externo (Chatwoot, n8n, HubSpot).

---
*TAKEOFF Engine — Arquitectura de Agentes de Alto Rendimiento.*
