Skip to content

Agents

polars_ts.supply_chain_agents.agents

Agents for supply-chain demand sensing and inventory coordination.

  • :class:DemandSensingAgent — fuse POS, social, weather, and event signals.
  • :class:PromotionEffectAgent — estimate and apply promotion lift.
  • :class:InventoryAgent — inventory-aware base-stock reorder policy.
  • :class:EchelonCoordinatorAgent — multi-echelon order propagation.

DemandSensingAgent

Fuse a baseline demand forecast with external demand signals.

Each signal is a fractional uplift path (e.g. a normalised social-buzz or event index); the sensed demand is baseline * (1 + sum_i w_i * signal_i) floored at zero. This is the multi-source fusion step (POS baseline + social / weather / events), and baseline may originate from a foundation-model forecast for context-aware sensing.

Parameters

weights Mapping signal_name -> weight. Signals absent from this mapping default to weight 1.0.

sense(baseline, signals=None)

Return the signal-fused sensed demand for baseline.

PromotionEffectAgent

Estimate multiplicative promotion lift and apply it to a forecast.

The lift is a difference-in-means estimate — mean sales on promoted periods versus non-promoted — a lightweight causal-style contrast (see the causal inference module, T1-5, for confounder-adjusted alternatives).

estimate(sales, promo_flags)

Return the multiplicative lift (promo_mean / base_mean) - 1.

apply(forecast, promo_schedule, lift)

Scale forecast by lift on periods flagged in promo_schedule.

InventoryAgent

Inventory-aware base-stock (order-up-to) reorder policy.

Parameters

lead_time Replenishment lead time in steps. safety_factor Service-level multiplier (z) applied to lead-time demand std.

reorder(demand_forecast, on_hand)

Return the reorder decision for the coming lead-time window.

Returns

dict order_up_to, safety_stock, order_qty and a boolean stockout_risk (as 0.0 / 1.0).

EchelonCoordinatorAgent

Propagate orders up a multi-echelon chain (store -> DC -> factory).

Each echelon smooths downstream orders with an exponential filter; the coordinator also reports the bullwhip ratio (order variance amplification from the bottom to the top echelon).

Parameters

n_echelons Number of echelons above the demand source. smoothing Exponential smoothing factor in [0, 1] applied at each echelon (1 = pass-through, lower = more smoothing / less bullwhip).

coordinate(demand)

Return per-echelon order series and the bullwhip ratio.