Machine Learning / Inventory Intelligence
Inventory decisions from raw commerce data.
DemandOS converts raw synthetic commerce records into forecasts, risk signals, reorder guidance, diagnostics, and monitoring surfaces. Suppliers, products, stores, orders, inventory snapshots, promotions, and purchase orders provide the source data for those outputs.
Strategic thesis
ML is used for forecasting and diagnostics. Deterministic code handles ingestion, validation, schema contracts, feature engineering, routing, safety gates, and side-effect control. The system is designed to be auditable and reproducible: it does not use autonomous agents to make purchasing decisions, contact suppliers, or create purchase orders.
Case Snapshot
The problem, the system response, the available proof, the strategic value, and the intentional boundary.
Project metadata
Problem
Retail and ecommerce teams often work from fragmented records: catalogs, stores, orders, inventory snapshots, suppliers, promotions, and purchase orders. A conventional dashboard can explain what happened, but it rarely connects those records to forecasts, model quality, stockout risk, and reviewable replenishment decisions.
Can a credible ML workflow turn commerce records into inventory guidance without real customer data or seeded dashboard outputs?
Product objective
The goal was to build a working loop that starts with raw operational data, evaluates models, and ends in reviewable guidance while keeping the system safe and non-autonomous.
Architecture decision
Models handle forecasting and diagnostics. Ingestion, validation, routing, schema contracts, safety gates, and side-effect control remain deterministic. The steps are known; the product decision is to make them reliable, inspectable, and repeatable.
Every derived layer is computed and persisted before the next stage consumes it.
Data pipeline
DemandOS does not seed final KPIs, precomputed forecasts, risk scores, or recommendations. It starts from synthetic operational entities and calculates every downstream layer.
Counts validated in a small-mode demo run; they may change after reseeding.
Raw vs derived
DemandOS starts from operational entities and computes planning surfaces internally. This is the proof boundary between raw demo data and product outputs.
Forecasting and ML layer
Baselines provide a transparent comparison point. The global model uses scikit-learn and demand, inventory, calendar, promotion, price, and lifecycle features. Its outputs feed stockout risk and reorder guidance.
Seasonal naive and moving averages establish readable references. The ML model is not forced to win.
Global model over product/store series, trained on a feature matrix that excludes future information.
Temporal split, non-negative predictions, persisted metrics, and p10/p90 bands documented as heuristics.
Weighted total error as a percentage of aggregated actual demand.
Mean absolute error between observed demand and forecast.
Metric that penalizes large misses more strongly.
Shows whether the model tends to over- or under-forecast demand.
In this prototype, WAPE is a directional quality signal. A high WAPE is not hidden: the interface explains that the forecast is useful as a demo planning signal, not as a production-calibrated model.
ML Insights
The data-science surface organizes summary diagnostics, model comparison, signal groups, and business-impact interpretation without mutating the database.
/api/data-science/summary/api/data-science/forecast-diagnostics/api/data-science/model-comparison/api/data-science/feature-signals/api/data-science/business-impactThe five endpoints are read-only: they explain the system and its outputs, but do not run training, pipelines, or state changes.
Feature engineering
Signals describe information used by the model or associated with demand patterns. They are not presented as causal relationships.
Lags and rolling windows before the target day.
Calendar, weekday, and temporal patterns.
Price, cost, margin, and recent changes.
Promotional exposure and observed lift in the data.
Available inventory, stockout flag, and days of supply.
Product age and maturity stage.
Store, category, and sales-channel signals.
Risk and recommendations
Risk combines predicted demand, current inventory, inbound supply, lead time, supplier reliability, safety stock, and estimated lost sales. Recommendations are internal review guidance: never real purchase orders.
Visible output from a validated demo run; values can change after rebuilding the dataset.
Monitoring
Compares recent model metrics and data health against prior runs with documented states and thresholds, without turning a demo into an overclaim.
Scenario planning
Scenarios are stored separately, labeled as simulated, and never alter canonical risk or recommendation tables.
Extensions
Validates raw entities, rejects derived lags, forecasts, scores, and recommendations, limits files to 2 MB, and writes audit records.
Stubs only validate configuration shape. Dry runs do not call APIs, store credentials, or perform live synchronization.
Dashboard walkthrough
Screenshots come from the public demo and show calculated synthetic data across the product surface.
Deployment architecture
A Vercel project serves Next.js and a Python FastAPI function under /api/*. Neon Postgres keeps state, and browser calls are same-origin.
Next.js interface and same-origin calls
Frontend + FastAPI function in serverless mode
Persistence for data, runs, and outputs
Synthetic scale compatible with demo limits
A larger system would move backend, workers, and model artifacts to dedicated infrastructure. The prototype assumes serverless limits, ephemeral artifacts, and free-tier constraints.
Reliability and validation
Credibility does not depend on one screenshot. It depends on data contracts, tests, safety checks, and validation against the public deployment.
An earlier backend count was higher because it included untracked duplicate copies. The public case uses the clean count of unique tests.
Safety boundary
Read-only public endpoints are available. Write and control actions are API-key protected, and the prototype does not cross into external actions.
Result
DemandOS demonstrates an end-to-end workflow: raw ingestion, validation, feature engineering, forecasting, model diagnostics, risk and recommendations, monitoring, scenarios, deployment, and publication discipline.
Portfolio ML work is stronger when the model lives inside a reliable workflow for ingestion, validation, features, evaluation, explainability, safety, and deployment.
Limits
What I learned
The project combined model training with the environment needed to review its outputs: data contracts, validation, leakage-safe features, interpretable metrics, observability, safety boundaries, and an interface that helps decide what to review first.
