Skip to main content

ADR-0201: Navin Enterprise Sales Forecasting and Inventory Management Agent, retail product layer above the Control Plane

  • Status: proposed
  • Date: 2026-11-05
  • Use case: UC-12 (agent_uses_cases/12_Retail_Prevision_Ventes_Gestion_Stocks.md)
  • Product: navin-enterprise-retail-previsions-stocks/ (package navin_previsions, schema previsions, API 8484, Redis 6405, web 3485 served by the generic shell of ADR-0180)
  • Links: ADR-0174 (memory), ADR-0176 (generic modules), ADR-0180 (frontend shell), OPA package eai.retail_previsions (deploy/policies/opa/retail_previsions.rego), OpenFGA fragment deploy/policies/openfga/products/retail-previsions-stocks.fga, contracts contracts/v1/retail-previsions-stocks-action-request.schema.json and contracts/v1/retail-previsions-stocks-copilot-event.schema.json, Manager template navin-retail-previsions-stocks-agent (not published).

Context​

A retailer wants forecasts per SKU, store and day or week, explicit stock policies, replenishment proposals that respect MOQ, pack size, lead time, capacity, budget and expiry, and an allocation of a limited central stock, without ever letting a language model order. The brief asks to reuse the forecasting engine of the Business Analytics Agent; that agent is not built in the repository.

Decision​

  1. Local forecasting engine behind the ForecastEngine interface (navin-enterprise-retail-previsions-stocks/backend/src/navin_previsions/previsions/forecast.py): deterministic baseline methods (naive, seasonal naive, moving averages 4 and 8, simple exponential smoothing 0.2 and 0.5), selection by rolling-origin backtest (WAPE, then MAE, then the simplest), empirical intervals from the backtest residuals. Pure Python and Decimal, no new dependency. The Business Analytics engine will replace it by implementing the same interface, without changing the API or the schema.
  2. Every forecast stores engine, method and version, training window, horizon, granularity, interval, backtest errors and quality flags; it is returned with certainty: estimate_not_certain. Stock-out, closure or outage days are censored (never zero demand); a driver decided after the forecast date is excluded; a WAPE on zero actuals is undefined.
  3. Stock positions come from the sources with their date; an unconfirmed planned receipt is not stock. Replenishment is a simulation; a request becomes an order only through the Action Gateway with maker-checker and ERP confirmation (unknown_pending_confirmation otherwise).
  4. State machine of the planning cycle as data (409 invalid_transition, 412 on a stale If-Match). A second human approves a forecast, an override, a policy and an order.
  5. Generic modules copied and adapted from the UC-09 model product (no cross-product import).

Consequences​

  • Positive: autonomous product, isolated by RLS and tested; replaceable engine; no certainty displayed.
  • Negative: baseline methods only (promotions not modelled); sandbox connectors; acceptance on synthetic data.