Grocery Logistics Demonstration Suite Constraint-verified planning for distribution center operations
This suite demonstrates one architectural idea across three operating decisions a grocery distribution network makes every day: machine learning proposes, a composable rule engine verifies, and every decision ships with a complete, auditable explanation. The three demos cover the outbound, inbound, and execution sides of a DC:
Load Building
Outbound, with known orders. Every trailer load is checked against six hard constraints before departure and carries a proof certificate. A cube-only baseline shows what goes wrong without verification.
Perishable Replenishment
Inbound, where demand really is unknown. A deliberately simple forecast is composed with six ordering guardrails; every order line shows the waterfall of adjustments that produced its final quantity.
Disruption Re-Planning
Execution. A reefer fails or a road closes mid-day; only the affected loads are rebuilt, in milliseconds, and the new plan is re-verified end to end. Untouched loads are provably untouched.
Why the suite is shaped this way
Outbound logistics does not have a demand-uncertainty problem. By the time a trailer is loaded, orders are picked, staged, and known to the case. Pretending otherwise makes a demo easy to dismiss. So each demo puts the uncertainty, and the value, where it actually lives:
| Decision | What is known | What the system adds |
|---|---|---|
| Load building (outbound) | Order quantities, exactly | Proof that every load satisfies temperature zoning, weight, stacking, delivery windows, driver hours, and unload access before the truck moves |
| Replenishment (inbound) | Demand history only; purchase orders commit before demand is known | Forecast composed with hard guardrails (shelf life, case pack, vendor minimums, truck cube, DC capacity) and a per-line audit trail |
| Re-planning (execution) | The committed plan, plus a disruption | Selective re-planning that provably leaves unaffected loads untouched and re-verifies everything it changed |
The shared synthetic world
All three demos run on one seeded, reproducible model of a regional grocery network
(grocery_demos/core/data_gen.py):
- One regional DC and ~36 stores with coordinates, delivery windows (morning, afternoon, all-day), unload times, and a few tight-dock stores.
- ~120 SKUs with a temperature class (frozen, refrigerated, ambient), a crush class (sturdy to fragile: bread, eggs, chips), case cube and weight, shelf life, case pack, and pallet geometry.
- A fleet of 15 multi-temp trailers, each with three fixed compartments (frozen 550 ft³, refrigerated 900 ft³, ambient 1500 ft³) and a 43,000 lb payload limit.
- Order scenarios for load building (
weekday,weekend_peak,holiday_surge,frozen_promo) and 90-day demand histories with weekly seasonality, promotions, and noise for replenishment.
Everything is generated from a seed: the same seed always produces the same network, the same orders, and the same plan. There is no hidden state and no wall-clock dependence, which is what makes the certificates reproducible.
The architecture in one paragraph
A planner (Clarke-Wright savings routing for loads, a forecast for orders) proposes; a constraint engine composed of independent, named rules verifies every proposal and returns the complete rule trace, pass or fail, with the measured value and the limit; rejected proposals are logged with the rule that blocked them; and accepted plans are issued a certificate: the full enumeration of every rule evaluated, its numbers, and a hash of the inputs. The optimizer is never trusted; it is checked. A better optimizer or a better forecaster drops in without touching the safety layer, and the safety layer's guarantees do not depend on either being good.
What the demos claim, and what they do not
KPI glossary
| KPI | Meaning |
|---|---|
| Cube utilization | Filled compartment volume / available compartment volume, averaged over trailers in the plan |
| Windows met | Share of stops whose simulated arrival falls inside the store's delivery window |
| Naive violations | Loads from the cube-only baseline that fail at least one of the six constraints |
| Rejected merges | Route consolidations the verified builder refused, each logged with the blocking rule and numbers |
| Projected waste | Ordered cases expected to exceed shelf life before they can sell through |
| Stockout-risk lines | Order lines whose final quantity may not cover forecast demand until the next cycle |
| Re-plan latency | Wall-clock milliseconds to rebuild and re-verify the affected loads after a disruption |
Running the demos
Each demo page has a scenario picker and a Run button; results render entirely from the JSON returned by the demo's API. All three are deterministic per seed, so a walkthrough rehearsed at seed 42 will reproduce exactly in front of an audience.