Nebluna Analytics

Descripción del Proyecto

Nebluna Analytics pronostica la demanda diaria de cafeterías. Subes un CSV con el histórico de ventas, eliges cuántos días quieres ver hacia adelante y obtienes un pronóstico con su banda de confianza y las métricas de error del modelo.

El punto del proyecto no era el modelo —Prophet son unas cuantas líneas de código—. El punto era todo lo que lo rodea: sacar un modelo de series de tiempo de un notebook y ponerlo detrás de una API REST, en un contenedor, sobre infraestructura administrada, con una interfaz que el dueño de un negocio realmente pueda operar.

El Problema

Las ventas diarias de una cafetería no son planas. Tienen un ritmo semanal (los fines de semana suben, los lunes caen), una deriva estacional más lenta a lo largo del año y ruido del día a día encima. Pedir insumos contra el promedio de la semana pasada significa comprar de más en los días tranquilos y quedarse corto en los ocupados.

Prophet encaja bien con esta forma de datos: descompone la serie en componentes de tendencia y estacionalidad, tolera huecos y valores atípicos y —algo importante para un usuario de negocio— produce intervalos de incertidumbre interpretables en lugar de un solo número.

Arquitectura

El sistema está dividido en tres piezas que se pueden desplegar y escalar por separado.

Capa de Modelo

DataProcessor se encarga de la carga, validación y limpieza: verifica el contrato date / sales, exige un mínimo de 30 días de historia y normaliza el dataframe a la forma que Prophet espera. DemandForecaster envuelve el modelo en sí — el entrenamiento, la reserva de la cola de la serie para evaluación y la generación de fechas futuras con límites de confianza del 95%.

Capa de API

Un servicio en FastAPI expone cuatro endpoints:

• GET /health — verificación de vida para Cloud Run
• POST /api/v1/upload — recibe un CSV, entrena el modelo y devuelve métricas de ajuste
• POST /api/v1/forecast — genera n días hacia adelante, opcionalmente con intervalos de confianza
• GET /api/v1/stats — estadísticas resumen del dataset cargado

Peticiones y respuestas están tipadas con esquemas Pydantic, lo que significa que la documentación OpenAPI se genera a partir de las mismas definiciones contra las que el servicio valida. Los errores se propagan mediante una jerarquía de excepciones propia, así un CSV mal formado devuelve un mensaje útil en vez de un stack trace.

Capa de Dashboard

Una app en Streamlit consume la API y organiza la salida en tres pestañas —Historical, Forecast y Metrics— con gráficas interactivas de Plotly. La barra lateral concentra los controles: carga del CSV, un slider de horizonte de 7 a 90 días y un toggle para los intervalos de confianza.

Evaluación

El modelo se evalúa sobre una cola reservada de la serie y no sobre los datos con los que se ajustó. Tres métricas se muestran en el dashboard, cada una respondiendo a una pregunta distinta:

• MAE — error promedio en pesos, el número con el que razonar al dimensionar un pedido
• MAPE — el mismo error como porcentaje, comparable entre negocios de distinto tamaño
• RMSE — castiga más los errores grandes, lo que delata a un modelo que casi siempre acierta pero de vez en cuando falla feo

Mostrar las tres en la interfaz es deliberado: un pronóstico presentado sin su error es una adivinanza con una gráfica encima.

Despliegue

La API está contenerizada y corre en GCP Cloud Run, construida para arm64 y amd64 para que la misma imagen funcione en una laptop con Apple Silicon y en la infraestructura de Google. Cloud Build maneja el CI/CD desde cloudbuild.yaml, y una alerta de presupuesto limita el gasto mensual.

Las dependencias fueron un problema aparte. Prophet se apoya en extensiones C de NumPy y Pandas que son frágiles cuando se mezclan paquetes de conda y pip en el mismo entorno. El proyecto lo resuelve trazando una línea dura: conda para desarrollo local, donde los binarios precompilados son confiables, y pip dentro de la imagen de Docker, donde lo son los wheels de Linux. La regla está documentada en el README para que el entorno siga siendo reproducible.

Pruebas

Las pruebas unitarias cubren tanto el pipeline de procesamiento de datos como los endpoints de la API —fallos de validación, entradas mal formadas y el camino feliz— ejecutadas con pytest.