Machine Learning / Inventory Intelligence
Sistema de machine learning para previsión de demanda, riesgo de stockout y recomendaciones internas de reposición.
DemandOS convierte datos operativos sintéticos —productos, tiendas, pedidos, inventario, promociones y proveedores— en features leakage-safe, forecasts, métricas de modelo, riesgos de stockout y recomendaciones de reposición. Está desplegado como prototipo público en Vercel con Neon Postgres y no ejecuta compras reales ni acciones externas.
Project Snapshot
Problema
Retail y ecommerce dependen de registros fragmentados: catálogos, tiendas, pedidos, snapshots de inventario, proveedores, promociones y órdenes de compra. Un dashboard convencional explica qué ocurrió, pero rara vez conecta esos datos con forecasts, calidad de modelo, riesgo de stockout y decisiones de reposición.
¿Puede un workflow creíble de ML convertir registros de comercio en orientación de inventario sin usar datos reales de clientes ni fingir outputs de dashboard?
Objetivo de producto
El objetivo fue construir un ciclo funcional que empezara en datos operativos brutos, evaluara modelos y terminara en orientación revisable, manteniendo el sistema seguro y no autónomo.
Decisión de arquitectura
Los modelos se usan para forecasting y diagnóstico. Ingesta, validación, routing, contratos de esquema, puertas de seguridad y control de efectos permanecen deterministas. Los pasos ya son conocidos: aquí la fiabilidad importa más que la autonomía.
Cada capa derivada se calcula dentro del pipeline y persiste antes de que la siguiente etapa la consuma.
Data pipeline
DemandOS no siembra KPIs finales, forecasts precalculados, scores de riesgo ni recomendaciones. Parte de entidades operativas sintéticas y calcula todas las capas posteriores.
Conteos validados en una ejecución demo small-mode; pueden cambiar después de reseedear.
Forecasting y capa ML
Los baselines ofrecen un punto de comparación transparente. El modelo global usa scikit-learn y features de demanda, inventario, calendario, promoción, precio y ciclo de vida. Sus outputs alimentan riesgo de stockout y orientación de reposición.
Seasonal naive y medias móviles establecen referencias legibles. El modelo ML no está obligado a ganar.
Modelo global sobre series producto/tienda, entrenado con una matriz de features que excluye información futura.
Split temporal, predicciones no negativas, métricas persistidas y bandas p10/p90 documentadas como heurísticas.
Error total ponderado como porcentaje de la demanda real agregada.
Error absoluto medio entre demanda observada y forecast.
Métrica que penaliza con más fuerza los fallos grandes.
Indica si el modelo tiende a sobreestimar o infraestimar demanda.
En este prototipo, WAPE funciona como señal direccional de calidad. Un WAPE alto no se oculta: la interfaz explica que el forecast es útil como señal demo de planificación, no como modelo calibrado para producción.
ML Insights
Sprint 15 añadió resumen de data science, diagnósticos, comparación de modelos, grupos de señales e interpretación de impacto de negocio. La página ML Insights organiza estas lecturas sin mutar la base de datos.
/api/data-science/summary/api/data-science/forecast-diagnostics/api/data-science/model-comparison/api/data-science/feature-signals/api/data-science/business-impactLos cinco endpoints son read-only: explican el sistema y sus resultados, pero no ejecutan entrenamiento, pipeline ni cambios de estado.
Feature engineering
Las señales describen información usada por el modelo o asociada con patrones de demanda. No se presentan como relaciones causales.
Lags y ventanas móviles anteriores al día objetivo.
Calendario, día de semana y patrones temporales.
Precio, coste, margen y cambios recientes.
Exposición promocional y lift observado en los datos.
Inventario disponible, stockout flag y días de suministro.
Edad del producto y etapa de madurez.
Señales de tienda, categoría y canal de venta.
Riesgo y reposición
El riesgo combina demanda prevista, inventario actual, suministro entrante, lead time, fiabilidad del proveedor, safety stock y ventas perdidas estimadas. Las recomendaciones son orientación interna para revisión: nunca órdenes de compra reales.
Salida visible en una ejecución demo validada; los valores pueden variar después de reconstruir el dataset.
Monitoring
Compara métricas recientes de modelo y salud de datos frente a ejecuciones anteriores mediante estados y umbrales documentados, sin convertir una demo en una afirmación estadística compleja.
Scenario planning
Los escenarios se guardan por separado, se etiquetan como simulados y nunca alteran las tablas canónicas de riesgo o recomendaciones.
Extensiones
Valida entidades raw, rechaza lags, forecasts, scores y recomendaciones derivados, limita archivos a 2 MB y escribe registros de auditoría.
Los stubs validan únicamente la forma de configuración. El dry-run no llama APIs, no almacena credenciales y no existe sincronización live.
Dashboard walkthrough
Las capturas proceden de la demo pública y muestran datos sintéticos calculados. La captura específica de ML Insights queda pendiente en el repositorio fuente.
Deployment architecture
Un proyecto Vercel sirve Next.js y una función Python FastAPI bajo /api/*. Neon Postgres conserva el estado y las llamadas del navegador son same-origin.
Interfaz Next.js y llamadas same-origin
Frontend + función FastAPI en modo serverless
Persistencia de datos, runs y outputs
Escala sintética compatible con límites de demo
Un sistema mayor migraría backend, workers y artefactos de modelo a infraestructura dedicada. El prototipo asume límites serverless, artefactos efímeros y restricciones de free tier.
Fiabilidad y evaluación
La credibilidad no depende de una captura aislada, sino de contratos de datos, pruebas, checks de seguridad y validación contra el despliegue público.
El conteo backend anterior era mayor porque incluía copias duplicadas no trackeadas. El caso público utiliza el conteo limpio de tests únicos.
Safety boundary
Los endpoints públicos de lectura están disponibles. Las acciones de escritura y control se protegen con API key, y el prototipo no cruza el límite hacia acciones externas.
Resultado
DemandOS demuestra un workflow end-to-end: ingesta raw, validación, feature engineering, forecasting, diagnóstico de modelos, riesgo y recomendaciones, monitoring, escenarios, despliegue y disciplina de publicación.
El trabajo de portfolio con ML es más fuerte cuando el modelo vive dentro de un workflow fiable de ingesta, validación, features, evaluación, explicabilidad, seguridad y despliegue.
Limitaciones
Qué aprendí
Lo más importante del proyecto no fue solo entrenar un modelo. Fue construir el entorno que hace que un modelo sea usable: contratos de datos, validación, features sin leakage, métricas interpretables, observabilidad, límites de seguridad y una interfaz que ayuda a decidir qué revisar primero.
