inventory_demand_planning v1.0.0

name: inventory_demand_planning description: Forecast demand and set inventory policy from sales history: safety stock, reorder points, EOQ, min/max levels, and order recommendations. Use when deciding what to order, how much, when to reorder, or how to model seasonality, promotions, and demand variability.

Inventory Demand Planning

Purpose

Turn sales history into buy decisions. Given per-SKU demand history, produce a defensible forecast plus the inventory policy that follows from it: how much buffer to hold (safety stock), when to reorder (reorder point), how much to order (EOQ / min-max), and which SKUs deserve attention first (ABC/XYZ). The point is teaching the math, not hiding it: every number in the output traces back to a formula an analyst can check in a spreadsheet.

Workflow

1. Inspect the history. Get daily or weekly units sold per SKU. You need at least 4 periods per SKU; 20+ is comfortable. Note the cadence (daily vs weekly vs monthly) because lead time and period length must use the same unit.

1. Clean before fitting. Strip promotional spikes, one-time bulk orders, stockout-censored days (zero sales caused by being out of stock, not by no demand), and data errors from the baseline. Fit the baseline to normal demand. Promos get their own layer: see references/seasonality-and-promos.md.

1. Forecast each SKU. Use bin/forecast_plan.py: it backtests naive, 4-period moving average, single exponential smoothing (alpha 0.2), and optionally seasonal decomposition on recent history, then keeps the method with the lowest MAPE. Method guidance:

• Stable demand: 4-period moving average.
• Gradual drift: exponential smoothing (alpha 0.1-0.3; higher alpha chases noise, lower reacts slowly).
• Repeating cycle (weekly, monthly, holiday): multiplicative seasonal decomposition with --season-length.
• Externally driven demand (price changes, weather, events): add regression features; validate on out-of-time data, not out-of-sample.

1. Convert forecast to policy. The CLI does this per SKU:

• Safety stock = Z x sd(daily demand) x sqrt(lead time). Z: 1.28 at 90% service, 1.645 at 95%, 1.96 at 97.5%, 2.33 at 99%.
• Reorder point = (avg daily demand x lead time) + safety stock.
• EOQ = sqrt((2 x annual demand x ordering cost) / holding cost per unit per year).
• Min = reorder point; Max = reorder point + EOQ. Round order quantities to vendor case packs or MOQs.
• Periodic-review alternative (fixed vendor delivery days): review every R periods, order up to S = avg demand over (R + lead time) + safety stock for that horizon.

1. Rank before calculating. Apply ABC (value: top ~80% of spend = A, next ~15% = B, rest = C) by annual demand x unit cost, and XYZ (variability: X = stable, Y = mixed, Z = erratic) by coefficient of variation. High-value erratic items (AZ) get the modeling effort; low-value stable items (CX) get a rule of thumb. See references/abc-xyz-segmentation.md.

1. Decide against inventory position. Reorder off inventory position (on-hand + on-order - backorders), never on-hand alone. The CLI takes on_hand and on_order columns and flags ORDER vs OK accordingly.

Output Contract

Running the CLI returns, per SKU:

• forecast method selected (backtested MAPE shown), forecast daily demand, avg and sd of daily demand
• safety stock, reorder point, EOQ, min and max levels
• inventory position, action (ORDER/OK), recommended order quantity
• variability class (X/Y/Z) and ABC class when unit cost is supplied

Every number must be reproducible from the inputs plus the formulas above. If the backtest MAPE is above ~50%, say the fit is poor and ask for more or cleaner history instead of shipping a plan off noise.

Operating Rules

• Never invent demand numbers, lead times, costs, or service levels. Every input to the model must come from the user, their data, or be explicitly labeled as an assumption.
• The sqrt(lead time) safety-stock formula assumes daily demands are roughly independent. If demand is strongly autocorrelated, say so and widen the buffer.
• Excel equivalents for hand checks: =NORM.S.INV(service_level) for Z, =STDEV.S(range) for sd, =SQRT(lead_time). Full formula table in references/spreadsheet-formulas.md.
• Chasing "never stock out" is expensive: 95% to 99% service raises safety stock about 41%. Show the cost of the service level, don't default to 99%.
• Forecasting a promo week off promo-contaminated history double-counts. Strip promos from the baseline, estimate lift separately (see references).
• When a SKU's history is too thin or too noisy for a credible forecast, report that plainly instead of padding the model.