Calling 4 Rescue

Evitamos devoluciones en ruta y aseguramos pedidos completos, uniendo la app Tuali con llamadas automáticas de IA, lo que hace que el sistema sea eficaz y sencillo de usar.

Comment

Order 4 Rescue

Sistema de llamadas telefónicas con IA para resolver faltantes en los pedidos de los tenderos. Proyecto construido en el Hack4Her para el reto de Arca Continental.

El problema

Cuando un tendero hace su pedido a Arca y un producto se agota en el centro de distribución, hoy pasan dos cosas malas: o le quitan el producto sin avisarle, o alguien escoge a ciegas el cambio. A escala de miles de tienditas eso no es viable y genera perdidas monetarias, mercancia estancada.

Order 4 Rescue automatiza ese momento. Cuando un producto no está disponible, el sistema decide si hace falta contactar al tendero y, si toca, le hace una llamada con voz natural ofreciéndole los sustitutos que históricamente la gente como él sí acepta. El tendero solo presiona una tecla y su pedido queda actualizado.

Cómo funciona

El flujo de un pedido es así:

  1. Llega un pedido (una lista de SKUs).
  2. Para cada producto se calcula su probabilidad de requerir sustitución con base en el historial. Si pasa el umbral, se marca como "requiere acción".
  3. Se decide el camino:
    • Si el tendero está registrado en Tuali (la app de Arca) → le llega una notificación dentro de la app.
    • Si no está registrado → entra la llamada con IA.
  4. El motor de recomendación arma los sustitutos reales del producto agotado.
  5. Gemini redacta el guion hablado (cálido, en español de México) usando solo esas opciones, sin inventar nada.
  6. ElevenLabs convierte ese texto en voz.
  7. El tendero escucha la llamada y elige con el teclado: reemplazar, escuchar promociones o eliminar el artículo.

La interfaz del frontend simula todo esto en una pantalla estilo iPhone, para que en el demo se vea exactamente cómo recibiría la llamada el tendero.

El cerebro: recomendación por SKU

El motor no recomienda al azar. Para cada producto agotado (A) busca en el historial cuáles han sido sus sustitutos más frecuentes (B) y calcula:

P(B|A) = Frecuencia(A → B) / Total de sustituciones de A

Así, si históricamente cuando se agota la Coca-Cola de litro y medio la gente acepta la versión sin azúcar el 80% de las veces, esa es la primera opción que se ofrece. Todo trabaja por SKU (códigos), porque en el flujo real un pedido es una lista de códigos, no de nombres.

La probabilidad de que un producto requiera sustitución se calcula con qué tan seguido aparece pidiéndose en el historial, normalizado contra el producto más frecuente. Si esa probabilidad supera el umbral (UMBRAL, por defecto 42), el pedido se marca como caso de llamada.

Stack

Backend

  • Python + FastAPI
  • pandas para el análisis del histórico
  • Gemini (gemini-2.5-flash) para generar el guion
  • ElevenLabs (eleven_multilingual_v2) para la voz

Frontend

  • React + Vite
  • Interfaz tipo IVR (estilo iPhone) que simula la llamada

Estructura del proyecto

.
├── api_server.py          # Servidor FastAPI: conecta el backend con el frontend
├── recommender.py         # Motor de recomendación P(B|A) y cálculo de probabilidad
├── gemini_service.py      # Arma las opciones y genera el guion hablado (con fallback)
├── elevenlabs_service.py  # Texto → voz (MP3) vía API REST de ElevenLabs
├── probar_llamada.py      # Script de prueba del flujo de llamada
├── probar_voz.py          # Script de prueba de la voz
├── data/
│   └── Resultados.csv     # Histórico de sustituciones
├── frontend/              # App de React + Vite
├── Requirements.txt
└── README.md

Cómo correrlo

1. Backend

Crea un entorno virtual e instala las dependencias:

python -m venv venv
source venv/bin/activate      # en Windows: venv\Scripts\activate
pip install -r Requirements.txt

Crea un archivo .env en la raíz con tus llaves:

GEMINI_API_KEY=tu_llave_de_gemini
ELEVENLABS_API_KEY=tu_llave_de_elevenlabs
ELEVENLABS_VOICE_ID=id_de_una_voz_en_espanol   # opcional, pero recomendado

Levanta el servidor:

python api_server.py

Queda corriendo en http://localhost:8000.

2. Frontend

En otra terminal:

cd frontend
npm install
npm run dev

Variables de entorno

Variable Para qué sirve ¿Obligatoria?
GEMINI_API_KEY Generar el guion de la llamada No (sin ella se usa el guion de respaldo)
ELEVENLABS_API_KEY Convertir el texto en voz Sí, para el audio
ELEVENLABS_VOICE_ID Elegir una voz en español No, pero la voz por defecto tiene acento

Endpoints principales

Método Ruta Qué hace
GET /api/health Revisa que el servidor esté vivo
GET /api/pedidos Catálogo de pedidos del demo (con/sin Tuali)
GET /api/pedido/{id} Detalle de un pedido y su camino (Tuali o llamada)
GET /api/recomendar/{sku} Sustitutos de un SKU agotado
GET /api/probabilidad/{sku} Probabilidad de requerir sustitución
GET /api/guion/{sku} Guion hablado + botones de un SKU
GET /api/dashboard Productos más propensos a sustitución
GET /api/llamada/demo Pedido de ejemplo completo
POST /api/voz Convierte un texto en audio MP3

Las opciones que escucha el tendero (los botones) se calculan en código a partir de los sustitutos reales. Gemini solo las redacta de forma natural, nunca las inventa.

Hecho en 24 horas durante el Hack4Her, reto de Arca Continental.

Built With

Share this project:

Updates