Machine Learning / Inventory Intelligence
Decisiones de inventario desde datos raw de comercio.
DemandOS convierte registros sintéticos de comercio en forecasts, señales de riesgo, orientación de reposición, diagnósticos y superficies de monitoring. Proveedores, productos, tiendas, pedidos, snapshots de inventario, promociones y órdenes de compra aportan los datos fuente para esas salidas.
Tesis estratégica
El ML se usa para forecasting y diagnóstico. El código determinista gestiona ingesta, validación, contratos de esquema, feature engineering, routing, safety gates y control de efectos. El sistema está diseñado para ser auditable y reproducible: no usa agentes autónomos para decidir compras, contactar proveedores ni crear órdenes de compra.
Resumen del caso
El problema, la respuesta del sistema, la prueba disponible, el valor estratégico y el límite intencional.
Metadatos del proyecto
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 revisables 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: la decisión de producto es hacerlos fiables, inspeccionables y repetibles.
Cada capa derivada se calcula 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.
Raw vs derivado
DemandOS parte de entidades operativas y calcula internamente las superficies de planificación. Ese es el límite de prueba entre datos demo raw y outputs de producto.
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
La superficie de data science organiza resumen de diagnósticos, comparación de modelos, grupos de señales e interpretación de impacto de negocio 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 en la superficie del producto.
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í
El proyecto combina el entrenamiento del modelo con el entorno necesario para revisar sus resultados: 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.
