Perishable Replenishment A simple forecast, composed with hard ordering guardrails, that eliminates engineered spoilage without hiding the stockout trade-off

This is the inbound side of the distribution center, and the honest half of the suite. Load building and re-planning work with quantities that are already known. Replenishment does not: a purchase order commits to a vendor before the demand it covers is known. A forecast is genuinely required here. The demonstration is built so the forecast is the least interesting part, and the guardrails around it are the product.

What this demo proves

A deliberately blunt forecast, composed with six committed-purchase-order guardrails, beats a naive order-up-to policy on waste by a wide margin, and it does so without hiding the cost. At seed 42, across every scenario, the guarded plan projects 0 cases of waste while the naive policy spoils thousands of cases of perishables. The guarded plan pays for that with a modest, deliberate stockout risk on the shortest-shelf lines, and it shows that cost plainly rather than burying it. The claim is not "we forecast better." The claim is "composition turns an ordinary forecast into an order you can actually receive, sell, and afford."

The forecast, stated plainly

The forecast (forecast() in grocery_demos/core/replenishment.py) is a trailing 14-day mean, adjusted by a weekday factor. It averages the last fourteen days of unit sales, then scales that average by the forecast day's weekday factor relative to the weekly average. That is the entire model. Any grocer could compute it by hand.

This is a deliberate choice, not a limitation we are hiding:

• The guardrails are the artifact under test. A forecast that is obviously simple makes it unambiguous that the waste reduction comes from the ordering logic, not from a clever predictor.
• A better forecaster is a drop-in replacement. Because the forecast is a single function returning a number, an exponential-smoothing model, a gradient-boosted model, or a full demand-sensing system can replace it without touching a single guardrail. The safety properties do not depend on the forecast being good.

The 90-day demand history the forecast reads (generate_demand_history() in grocery_demos/core/data_gen.py) is seeded and reproducible. Each store and SKU series contains weekly seasonality (a weekday profile that lifts on weekends), occasional promotions (a few days per horizon with a 1.8x to 2.5x uplift), and lognormal noise, with fresh SKUs made noisier than shelf stable ones. The trailing mean deliberately smears all of that together, which is exactly why the guardrails downstream have to catch what the forecast cannot see.

The six guardrails

The guardrails run in a fixed order on every line. The first four are line-local and live in ReplenishmentGuardrails.check_line(); the last two are aggregate (they need vendor totals and DC totals) and are applied by plan_orders() after all lines are computed. Every example below is a real adjustment from a seed 42, normal_week run, taken verbatim from the step trace the API returns.

Rules 1 and 2 push quantities up (toward buildable, shippable units). Rules 3 through 6 push them down or defer them (toward what will actually sell, ship full, and fit through the door). That tension is the whole point: the forecast says "here is demand," and the guardrails answer "here is what you can responsibly commit to."

The waterfall, and why order matters

Each line carries the ordered list of steps it passed through, and the Order Proposal tab renders that as a waterfall: the raw case count entering each rule, the count leaving it, and a plain-language detail sentence. The Ice Bag line above reads as a single story: 32.57 → 33 (whole cases) → 40 (whole pallet layers), and it survives the shelf-life cap because a 127-day frozen shelf life easily covers 40 cases.

Order of application is load-bearing, not cosmetic:

• Rounding before capping. Case-pack and pallet rounding run first so the shelf-life cap and the MOQ check see realistic, buildable quantities rather than fractional cases. Capping a fractional number and then rounding it could push coverage back over the shelf-life limit the cap just enforced.
• Line-local before aggregate. The shelf-life cap (rule 3) and MOQ (rule 4) decide each line's honest quantity before the truck-cube (rule 5) and DC-capacity (rule 6) rules reason about vendor and DC totals. Those aggregate rules can only be fair if the per-line numbers they sum are already final.
• Truck-cube before DC-capacity. Consolidating light vendor POs first changes the total inbound cube that the DC-capacity rule then measures, so rule 5 must settle before rule 6 looks at the day's total.

Because every step records its before and after, the final quantity is never a bare number. It is a traceable sequence of named decisions, which is what makes an order defensible to a buyer, a vendor, or an auditor.

Scenarios and real KPIs

The core forecast and guardrails do not carry a scenario knob; the demo blueprint (grocery_demos/web/replenishment_bp.py) shapes the seeded history into three scenarios by lifting only the trailing window the forecast reads, so every effect is an honest consequence of higher recent sales. normal_week is the unshaped baseline. promo_week lifts the last three days on about a third of lines. heat_wave boosts water, ice cream, frozen novelties, and fresh produce across the trailing window. All figures below are real outputs at seed 42, over 1,813 store-SKU lines.

The naive policy's projected waste climbs as demand heats up (3,179 to 3,485 to 3,969 cases) because a bigger trailing mean tells order-up-to to buy more, and more perishables bought means more spoilage. The guarded plan holds waste at zero in every case, because the shelf-life cap refuses to let coverage exceed what the product can outlive. The naive policy records zero stockout-risk lines in all three scenarios, which sounds ideal until you read the next section.

The honest trade-off

A "stockout-risk line" is a line whose final quantity, on top of on-hand stock, may not cover forecast demand through the vendor lead time before the next replenishment cycle. It is a risk flag, not a guaranteed empty shelf; most of these are short-shelf items where buying enough to be safe would mean buying more than can sell in time. That is precisely the tension perishable buyers manage by hand every day, made explicit and auditable here.

Reading the UI

The live demo at /grocery/replenishment has five tabs: