Φi (fi) es un sistema multiagente de IA para Eurostars Hotels que genera experiencias hiperpersonalizadas para cada huésped en el momento de su reserva. Analiza el historial, el perfil de viaje y los patrones de comportamiento del huésped para entregar itinerarios a medida por email y WhatsApp — de forma proactiva, antes incluso de que llegue al hotel.
- Personalización inmediata al reservar — cuando se envía un ID de huésped, Φi lee su perfil completo (país, edad, historial de estancias, ADR, motivo del viaje, nivel de fidelidad) y genera un itinerario a medida.
- Entrega dual — el itinerario se envía simultáneamente por email HTML con diseño de marca y por WhatsApp con botones interactivos de navegación día a día.
- Progresión multi-día — el huésped pulsa el botón "📅 Ver siguiente día" en WhatsApp cada jornada para recibir el plan del día siguiente, generado en tiempo real por el agente.
- Contacto proactivo — un agente en segundo plano analiza todos los huéspedes cada N horas y envía emails anticipados a quienes se acercan al check-in, están en ventanas estacionales o encajan en patrones de reactivación de fidelidad, sin ningún disparador manual.
- Adaptado al tipo de viaje — los huéspedes de ocio reciben gastronomía + cultura; los de negocios, restaurantes + espacios de coworking. El agente raíz selecciona los subagentes correctos automáticamente.
- Multiidioma — las respuestas se adaptan al país de origen del huésped (ES→español, PT→portugués, IT→italiano, FR→francés, DE→alemán).
φi/
├── main.py # App FastAPI + loop proactivo en background
├── requirements.txt
├── .env # Secretos (nunca subir a git)
├── data/
│ ├── customer_data_200.csv
│ ├── historico.csv
│ └── hotel_data.csv
├── subagents/
│ ├── controller_agent.py # Orquesta saludo + itinerario + envío
│ ├── greeting_agent.py # Saludo personalizado de una línea
│ ├── restaurant_agent.py # Google Places: gastronomía
│ ├── leisure_agent.py # Google Places: turismo y cultura
│ ├── work_agent.py # Google Places: coworkings y cafeterías
│ ├── summary_agent.py # Resumen ejecutivo de sesión
│ ├── proactive_agent.py # Generador de emails proactivos en background
│ └── transport_agent.py
└── utils/
├── data_loader.py # Construye el bloque de contexto del huésped
├── email_sender.py # Gmail SMTP con plantilla HTML
├── whatsapp_sender.py # Twilio Content API con botones de respuesta rápida
├── webhook_server.py # FastAPI webhook para taps de botones WhatsApp
├── session_store.py # Persistencia de sesión multi-día en JSON
└── proactive_rules.py # Lógica de disparadores + detección de patrones
POST /experience ──► controller_agent
{ guest_id } │
├──► greeting_agent → saludo de una línea
│
├──► root_agent (ocio) → itinerario completo
│ ├── restaurant_agent (Google Places)
│ └── leisure_agent (Google Places)
│
├──► root_agent (trabajo) → itinerario de negocios
│ ├── restaurant_agent (Google Places)
│ └── work_agent (Google Places)
│
├──► email_sender → email HTML de marca
└──► whatsapp_sender → día 1 + botón
El huésped pulsa "📅 Ver siguiente día"
└──► Twilio webhook ──► webhook_server
└──► root_agent (fresco) ──► itinerario día N
└──► whatsapp_sender (botón día N+1 o mensaje final)
Background (cada 6h):
proactive_agent ──► analiza todos los huéspedes ──► envía emails anticipados
Todos los agentes funcionan sobre Gemini 2.5 Flash a través de Google Vertex AI usando el Agent Development Kit (ADK) de Google.
- Python 3.10+
- Proyecto de Google Cloud con la API de Vertex AI habilitada y facturación activa
- Google Cloud CLI instalado y autenticado
- Cuenta Gmail con verificación en 2 pasos + App Password
- Cuenta Twilio con sandbox de WhatsApp configurado
ngroko equivalente para exponer el webhook en local
git clone https://github.com/martindios/fi.git
cd fi
python -m venv .venv
source .venv/bin/activatepip install -r requirements.txt
pip install 'google-adk[extensions]'
pip install twilio# Instalar el CLI si no está disponible
# macOS: brew install --cask google-cloud-sdk
# Arch: yay -S google-cloud-cli
gcloud auth login
gcloud auth application-default login
gcloud config set project TU_PROJECT_ID
gcloud auth application-default set-quota-project TU_PROJECT_IDcp .env.example .envEdita el .env:
# Google Cloud / Vertex AI
GOOGLE_CLOUD_PROJECT=tu-proyecto-gcp
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_GENAI_USE_VERTEXAI=true
# Google Places API
GOOGLE_MAPS_API_KEY=AIza...
# Gmail (envío del itinerario)
GMAIL_SENDER=tucuenta@gmail.com
GMAIL_APP_PASSWORD=xxxx xxxx xxxx xxxx
# Twilio (entrega por WhatsApp)
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_WHATSAPP_FROM=whatsapp:+14155238886
# Flags
ENABLE_PROACTIVE=trueuvicorn main:app --reloadEl servidor arranca en http://localhost:8000. Al iniciarse:
- Carga los CSVs de clientes y hoteles en memoria una sola vez.
- Lanza el Agente Proactivo como tarea asyncio en background (si
ENABLE_PROACTIVE=true).
curl -X POST http://localhost:8000/experience \
-H "Content-Type: application/json" \
-d '{"guest_id": "1008922782"}'Respuesta:
{
"status": "ok",
"guest_id": "1008922782",
"message": "Informe generado y enviado correctamente por email y WhatsApp."
}curl http://localhost:8000/healthEl servidor de webhook gestiona los taps de botón de los huéspedes. Twilio necesita una URL pública para enviar los callbacks, por lo que hay que exponer el servidor local.
uvicorn utils.webhook_server:app --host 0.0.0.0 --port 8000docker run --rm -it \
--network host \
-e NGROK_AUTHTOKEN=tu_token_de_ngrok \
ngrok/ngrok:latest http 8000ngrok mostrará una URL pública del tipo https://abc123.ngrok.io.
- Ve a Twilio Console → Messaging → Settings → WhatsApp Sandbox Settings.
- En el campo "When a message comes in" escribe:
https://abc123.ngrok.io/whatsapp/webhook - Guarda. Twilio enviará un POST a tu servidor cada vez que un huésped pulse el botón.
El huésped recibe el WhatsApp del Día 1 → pulsa "📅 Ver siguiente día"
→ Twilio hace POST a /whatsapp/webhook
→ El webhook lee la sesión de session_store.py
→ Genera el itinerario del Día 2 con el root_agent
→ Envía el Día 2 al huésped (con botón Día 3, o mensaje final en el último día)
El loop proactivo arranca automáticamente en background cuando se inicia la app. Cada 6 horas (configurable en utils/proactive_rules.py mediante PROACTIVE_CHECK_INTERVAL_HOURS) evalúa todos los huéspedes y envía emails personalizados anticipados a quienes cumplen algún disparador:
Modo A — reserva activa:
- Check-in dentro de 30 o 7 días
- Ventana estacional (verano, Navidad, Semana Santa, otoño)
- Ocupación del hotel por debajo del 60%
Modo B — sin reserva próxima:
- La temporada habitual de viaje del huésped coincide con una temporada que se acerca
- Candidatos a early-bird o reactivación de fidelidad
Para desactivar el loop proactivo sin detener el resto de la app:
ENABLE_PROACTIVE=false| Método | Ruta | Descripción |
|---|---|---|
POST |
/experience |
Genera y envía el itinerario personalizado para un huésped |
GET |
/health |
Health check |
POST |
/whatsapp/webhook |
Callback de Twilio para taps de botones de WhatsApp |
| Paquete | Uso |
|---|---|
google-adk |
Framework multiagente |
vertexai / google-cloud-aiplatform |
Cliente de Vertex AI |
google-genai |
Tipos compartidos con el ADK |
fastapi + uvicorn |
Servidor REST |
twilio |
Entrega por WhatsApp con Content API |
httpx |
Llamadas a Google Places API |
pandas |
Carga de datos de huéspedes y hoteles |
python-dotenv |
Gestión de variables de entorno |