Grocery Merchandising · Agentic Planning System · v1.0

Grocery Merchandising — Agentic Planning System

End-to-end AI-driven merchandising knowledge graph covering assortment, pricing & promotions, and replenishment — from category planning and vendor sourcing through in-store availability, perishable freshness management, and DSD compliance.

9
Domains
44
Entities
9
Flow Models
8
Segments
14
Agents
32
KPIs
11
Tabs
Intent
Ontology
Flow Models
Forecast Hierarchy
Net Requirements
Agent Pipeline
Inference Rules
Product Segments
Relationships
Knowledge Graph
KPIs & Metrics
Business Intent → Ontology Translation
// agent.input.business_intent
"Increase Sales"
submitted_by: category_director  ·  scope: Staples · Q4 2025  ·  horizon: 13 weeks  ·  phase: in-quarter planning & execution
01 · Input
Business Intent
Vague natural-language goal from a human
→
02 · Map
Ontology
Decompose into shopping missions, levers, entities & attributes
→
03 · Reason
Data Understanding
Apply merchandising rules and operational constraints to act
What this tab shows. "Increase Sales" is too vague for an agent to act on. This tab unpacks what it actually means in a grocery merchandising context, decomposes it into the levers a retailer can pull, binds each lever to specific entities and attributes already defined in the Ontology tab, and grounds every lever in business rules with realistic limits. Every other tab in this knowledge graph — Forecast Hierarchy, Flow Models, Net Requirements, Inference Rules, and KPIs — exists to serve this intent. This tab is where the chain begins.
Decomposition · Two Buckets, Six Levers
🛒
More Shoppers
New Trips & Banner Acquisition
Attract shoppers who are not yet visiting regularly — through new store formats, price credibility on key value items, and promotional events that pull footfall. Lever-set focused on broadening reach and winning the first visit on each mission type.
A1
Store format & network expansion · new stores, new formats, and new geographies extend physical reach to underserved catchments.
A2
KVI price credibility · competitive pricing on key value items anchors first-visit perception — not cheapest, but credible on the items shoppers benchmark.
A3
Promotional pull & circular reach · weekly circular, loyalty offers, and digital coupons that drive trip generation from lapsed and new shoppers.
🔁
More From Each Shopper
Basket Size · Frequency · Conversion
Once a shopper is in the store or on the app, four levers determine whether they find what they need, buy more than they planned, and come back more often. Highest ROI is usually retention, but every lever compounds across the full shopping year.
B1
Availability · on-shelf availability and zero out-of-stocks — every missed item on a planned shop is a lost sale and a loyalty dent.
B2
Assortment & range · carry the right SKUs in the right pack sizes; range gaps and format mismatches push the whole basket to competitors.
B3
Fresh quality & meal solutions · fresh categories are the primary reason shoppers choose one banner over another — freshness wins repeat visits.
B4
Promotions & basket-building · well-timed, well-stocked promotions grow basket size and trip frequency; poorly executed ones just leak margin.
B5
DSD & vendor compliance · vendor-managed categories (Coke, Frito-Lay, bread) must stay in-stock — retailer shadow benchmarking holds them accountable.
B6
Waste & margin control · avoiding over-ordering, shrink, and markdown leakage protects the P&L that funds investment in the other levers.
Mental Model · The Sales Identity
Sales = Trips × BasketSize × Availability × Frequency
Trips
Unique shopper visits per period — driven by store network, KVI price credibility, and promotional pull from circulars and digital offers.
BasketSize
Items × unit price per visit — driven by assortment completeness, cross-category ranging, and promotional mechanics that grow the transaction.
Availability
Probability a desired item is in-stock when the shopper arrives — the supply chain's direct, measurable contribution to sales.
Frequency
Repeat visits per shopper per month — earned through fresh quality, promo cadence, and consistent execution across every mission type.
Every initiative the agent considers must map cleanly to one of these four variables. If a proposed action doesn't move at least one of Trips, BasketSize, Availability, or Frequency, it isn't a valid response to the "Increase Sales" intent — and the agent should reject or escalate it.
Lever → Ontology Binding
A2
Price & Value Perception — KVI Credibility
moves: Trips ↑ · Frequency ↑
Ontology entities
PricePoint Product (SKU) PromotionEvent SalesHistory
Key attributes
regular_price promo_price promo_type was_on_promo (SalesHistory)
Diagnostic metrics
KVI price index vs competitor set
Price perception score by banner
Basket abandonment rate on price-sensitive SKUs
Repeat visit rate for KVI shoppers
A3
Promotions & Circular Pull — Driving New Trip Generation
moves: Trips ↑ · BasketSize ↑
Ontology entities
PromotionEvent CalendarEvent StoreDemandForecast PurchaseOrder
Key attributes
expected_uplift_pct start_date / end_date promo_type demand_multiplier (CalendarEvent)
Diagnostic metrics
Incremental trips driven by circular feature
Promo OOS rate on day 1 of event
Promo stock pre-build arrival vs event start
Post-promo excess inventory days
B1
Availability — Zero Out-of-Stocks on Every Mission Type
moves: Availability ↑ · Trips ↑ (loyalty retention)
Ontology entities
InventoryPosition NetRequirement TransferOrder ReplenishmentPolicy StoreDemandForecast
Key attributes
on_hand_qty days_of_supply safety_stock_days reorder_point flow_model
Diagnostic metrics
OOS rate by store × SKU × day
Days of supply vs safety stock target
Lost sales estimate from OOS events
DC-to-Store fill rate on Transfer Orders
B2
Assortment & Range — Right Products, Right Store Format
moves: BasketSize ↑ · Trips ↑ (destination categories)
Ontology entities
Product (SKU) Category ProductSegment PlanogramSlot Store
Key attributes
velocity_class aisle_code facings capacity_units format_type (Store)
Diagnostic metrics
SKU productivity (revenue per facing)
Range gap rate vs competitor benchmark
Category penetration by store format
Planogram compliance rate
B3
Fresh Quality & Meal Solutions — Freshness-First Replenishment
moves: Trips ↑ · Frequency ↑ (banner differentiation)
Ontology entities
ProductSegment InventoryPosition ColdChainEvent StoreDemandForecast
Key attributes
shelf_life_days code_date_earliest is_perishable shrink_rate_pct storage_temp_range
Diagnostic metrics
Gross waste rate % by fresh segment
Average days of supply vs shelf life
Cold chain exception incidents
Fresh OOS rate vs dry OOS rate
B4
Promotions & Basket-Building — In-Store Execution & Uplift
moves: BasketSize ↑ · Frequency ↑
Ontology entities
PromotionEvent StoreDemandForecast NetRequirement PricePoint
Key attributes
expected_uplift_pct promo_price channel (PromotionEvent) was_on_promo (SalesHistory)
Diagnostic metrics
Uplift realisation % vs planned uplift
Basket size lift during promo weeks
Cross-category attachment rate on feature items
Markdown rate post-promo (waste signal)
B5
DSD & Vendor Compliance — Shadow Benchmark Enforcement
moves: Availability ↑ · Frequency ↑ (trust in stock)
Ontology entities
DSDDelivery VendorScorecard DSDShadowForecast DSD-ShadowForecastAgent
Key attributes
units_delivered recommended_order_qty oos_incidents overstock_incidents fill_rate_pct
Diagnostic metrics
DSD OOS risk score per vendor
DSD waste risk score per vendor
Shadow forecast vs actual variance %
VendorScorecard composite (fill + OOS + waste)
B6
Waste & Margin Control — Protecting the P&L That Funds Everything Else
moves: BasketSize ↑ (maintained margin) · Availability ↑ (prevents write-off gaps)
Ontology entities
ProductSegment InventoryPosition SalesHistory MarkdownAgent
Key attributes
shrink_rate_pct markdown_threshold_pct code_date_earliest units_written_off
Diagnostic metrics
Gross waste rate % (fresh < 2%, frozen < 0.5%)
Markdown rate as % of regular revenue
Inventory turns by segment
GMROI (gross margin return on inventory)
Business Rules & Realistic Constraints
📅
Delivery Window Constraint
// Cannot order outside delivery schedule
IF NetRequirement(store).net_qty > 0
AND TODAY NOT IN Store.delivery_days_of_week
THEN DEFER TO next_delivery_window
AND ExceptionAgent.alert IF urgency=HIGH
Stores receive deliveries on fixed days of the week. Net requirements calculated between windows must be deferred — or expedited as an exception — based on urgency and days-of-supply remaining.
Binds: Store.delivery_days_of_week · ReplenishmentPolicy.lead_time_days
📦
Inner Pack Rounding
// Orders must round to case/inner pack
IF NetRequirement.net_qty > 0
THEN OrderQty =
  CEIL( net_qty / inner_pack_size )
       * inner_pack_size
Grocery orders are fulfilled in full cases or inner packs — fractional unit ordering is not possible. Rounding up can temporarily increase days-of-supply above target, which must be accounted for in safety stock calculations.
Binds: Product.pack_size · ReplenishmentPolicy.min_order_qty
❄️
Shelf Life Cap on Order Quantity
// Perishables: cap days of supply
IF Product.is_perishable = true
THEN MAX_DOS = Product.shelf_life_days
             * 0.60  // 60% shelf life rule
IF OrderQty > MAX_DOS * daily_velocity
THEN REDUCE OrderQty to MAX_DOS cap
Perishable orders are capped at 60% of shelf life to ensure adequate customer-facing code date on receipt. Over-ordering fresh categories directly drives shrink and waste write-off.
Binds: Product.shelf_life_days · InventoryPosition.code_date_earliest
🏷️
Promo Pre-Build Window
// Promo stock must arrive before event
IF PromotionEvent.start_date - TODAY
   <= DC_to_Store_lead_time_days
THEN TRIGGER early_promo_order
AND uplift_qty = baseline_forecast
     * expected_uplift_pct / 100
Promotional inventory must be ordered far enough in advance that DC-to-Store transit completes before the event start. Promo orders placed inside the lead-time window will arrive late and result in Day 1 OOS events.
Binds: PromotionEvent.expected_uplift_pct · StoreDemandForecast · PurchaseOrder
🚚
DSD — No Retailer PO Issued
// DSD = vendor owns replenishment
IF Product.dsd_flag = true
THEN SKIP TO/PO generation
AND DSD-ShadowForecastAgent
    .generate_benchmark(sku, store)
AND DSDMonitorAgent.track_delivery
DSD products — Coca-Cola, Frito-Lay, Pepsi, bread — are replenished by the vendor, not the retailer. The system generates a shadow forecast benchmark and scores vendor delivery performance without issuing any orders.
Binds: DSDDelivery · DSDShadowForecast · VendorScorecard · DSDSupplierContract
🧮
DC Allocation Lock — Prevents Double-Netting
// DC available = OH minus committed TOs
IF TransferOrder.status = APPROVED
THEN DC.allocated_qty += TO.requested_qty
AND DC.available_qty =
    on_hand - allocated_qty
Once a Transfer Order is approved, the DC immediately locks that quantity from its available balance. This prevents the DC from promising the same inventory to multiple stores — the most common source of short-fill events in two-tier replenishment.
Binds: InventoryPosition.allocated_qty · TransferOrder · NetRequirement (DC)
💲
Markdown Floor — Margin Protection
// Markdowns cannot breach gross margin floor
IF proposed_promo_price
   < PricePoint.regular_price * 0.70
AND Category.margin_floor_pct > 0
THEN REJECT markdown_event
AND MarkdownAgent.escalate(HumanBuyer)
Promotional pricing and clearance markdowns cannot breach the category-level gross margin floor. Discounts deeper than 30% off regular price require human buyer approval regardless of inventory pressure — protecting P&L from automated over-discounting.
Binds: PricePoint.promo_price · PromotionEvent · MarkdownAgent
📉
Low-Velocity SKU — Delist Gate
// Underperforming SKUs flagged for review
IF SalesHistory.units_sold (rolling 12w)
   < Category.velocity_class_threshold
AND Product.is_perishable = false
THEN FLAG sku FOR assortment_review
AND SUSPEND auto_replenishment
Dry grocery SKUs that fall below the minimum velocity threshold for their category for 12 consecutive weeks are flagged for assortment review and suspended from automatic replenishment. This prevents the system from re-ordering dead stock and frees planogram space for higher-productivity alternatives.
Binds: SalesHistory · Category.velocity_class · PlanogramSlot · ReplenishmentPolicy
Agent Trace · How the Intent Becomes a Merchandising Action
Scenario: Promotional Mission — Weekly Circular Feature Going Live in 48 Hours
A promoted pasta sauce brand is featured in this week's circular with a 25% price reduction. The agent traces the intent through the knowledge graph — spanning pricing, forecasting, inventory, and replenishment — to ensure the promotion lands with full availability.
1
PricePoint entity updated — promo price activated
PromotionEvent record created: promo_type = TPR (Temporary Price Reduction), regular_price = $3.49, promo_price = $2.62 (25% off), start_date = Thursday, end_date = Wednesday +7d. Margin check: discount = 25% — below 30% floor, no escalation required.
PromotionEvent.promo_id: PE-2024-1142  |  expected_uplift_pct: 180%  |  margin_check: PASS
2
Store-ForecastAgent applies promotional uplift to StoreDemandForecast
Baseline forecast = 22 units/day. PromotionEvent uplift multiplier = 2.8× (calibrated from 4 prior events on this SKU + category). Promo forecast = 62 units/day for 7 days = 434 units. CalendarEvent check: no overlap. WeatherSignal: neutral.
promo_forecast_units: 434 total across event window  |  confidence_interval: ±18%
3
InventoryAgent calculates net requirement including promo uplift
GrossNeed = 434 (promo forecast) + 55 (safety stock). on_hand = 48. in_transit = 0. on_order TOs = 0. NetNeed = 441 → rounds up to 444 (inner pack = 6). Pre-build order must arrive by Wednesday — 48 hours from now.
promo_net_qty: 444 units (74 cases)  |  required_by: Wednesday 00:00 — URGENT
4
TransferAgent checks DC available_qty against pre-build requirement
DC #3 has 310 units on hand; allocated_qty = 90 (committed to other stores' regular TOs); available_qty = 220. 444 needed but only 220 available — DC SHORT. ExceptionAgent fires HIGH severity alert. OrderingAgent checks open POs: vendor PO due Friday (after event start) — insufficient.
dc_available: 220 units — SHORT by 224  |  severity: HIGH · promo OOS risk
5
OrchestratorAgent escalates to HumanBuyer — promo availability at risk
Partial TO created for 220 units (available DC stock). OrchestratorAgent raises escalation: 224 units short, vendor PO cannot arrive before promo day 1. Human buyer options: expedite vendor shipment, source from alternate DC, or reduce circular feature quantity. AgentDecision logged with full promo context.
TransferOrder: TO-2024-94822 · 220 units · ETA Wednesday 05:00
Escalation: OPEN · 224 unit shortfall · HumanBuyer action required
All
Product
Store & Network
Inventory & Net Requirements
Supply Chain & Sourcing
Demand & Forecast
Agents
Merch Planning
Pricing & Promotions
External Signals
ProductProduct (SKU) · Category · ProductSegment · PricePoint · drives flow model, shelf life, and replenishment policy
🛒
Product (SKU)
Core Entity · Perishable & Non-Perishable · All Flow Models
sku_idupc_codenamebrandshelf_life_daysstorage_temp_rangeis_perishablepack_sizesegment_idflow_modeldsd_flag
Relations
─belongs_to→Category
─classified_in→ProductSegment
─sourced_from→Supplier
─substituted_by→Product (alternate)
🏷️
Category
Taxonomy · Hierarchy · Governs Replenishment Rules
category_idnamedept_nameaisle_codetemp_zonevelocity_class
Relations
─parent_of→Category (sub)
─governs→ReplenishmentPolicy
📦
ProductSegment
Classification · Drives Flow Model, Lead Times & Safety Stock
segment_idnametemp_zonemax_shelf_life_daystypical_vendor_lead_daystypical_dc_store_lead_daysdefault_safety_stock_daysdefault_flow_modelmarkdown_threshold_pctshrink_rate_pct
Relations
─classifies→Product[]
─shapes→ReplenishmentPolicy
💲
PricePoint
Temporal · Regular & Promotional Pricing
price_idregular_pricepromo_priceeffective_dateexpiry_datepromo_type
Relations
─applies_to→Product
─influences→StoreDemandForecast
Merch PlanningCategoryPlan · AssortmentPlan · PromotionPlan · RangePlanogram · Quarter-level planning objects that govern assortment, range, and promotional calendar
📂
CategoryPlan
Planning · Quarter-Level · Category Financial Targets
plan_idcategory_idquarterrevenue_targetunits_targetplanned_sku_counttarget_gross_margin_pctplanned_promo_weeksshrink_budget_pctplan_status
Relations
─governs→Category (financial targets, SKU count)
─drives→AssortmentPlan
─contains→PromotionPlan (calendar)
📋
AssortmentPlan
Planning · SKU Range per Store Format · Governs Which Products Trade Where
plan_idcategory_idstore_formatquarterplanned_sku_countcore_sku_ids[]seasonal_sku_ids[]delist_sku_ids[]new_sku_ids[]plan_status
Relations
─applies_to→Store (by format)
─governs→Product[] (which SKUs trade in which formats)
─constrains→ReplenishmentPolicy (only active assortment SKUs auto-replenish)
🗓️
PromotionPlan
Planning · Quarterly Promo Calendar · Circular + Digital + In-Store
plan_idcategory_idquarterpromo_weeks[]featured_sku_ids[]total_promo_budgetexpected_uplift_pctchannelplan_status
Relations
─instantiates→PromotionEvent (week-level)
─informs→StoreDemandForecast (uplift layer)
─requires→Inventory pre-build at DC + Store
🖼️
RangePlanogram
Spatial · Store Format · Shelf Layout & Facing Allocation
planogram_idcategory_idstore_formateffective_datesku_facings{}shelf_sections[]capacity_unitsreset_frequency
Relations
─references→AssortmentPlan
─constrains→PlanogramSlot (per SKU)
─informs→ReplenishmentPolicy (min display qty)
Pricing & PromotionsPricingState · MarkdownEvent · CompetitorPriceSignal · In-season pricing actions and perishable clearance events
💰
PricingState
Current · Per SKU × Store · Active Price with Effective Window
state_idsku_idstore_idcurrent_priceprice_typeeffective_fromeffective_topromo_event_idmarkdown_depth_pct
Relations
─overrides→PricePoint (regular price)
─created_by→PricingAgent
─modifies→StoreDemandForecast (price elasticity)
📉
MarkdownEvent
Action · Perishable Clearance · Code-Date or Overstock Triggered
event_idsku_idstore_idmarkdown_depth_pcttrigger_reasondays_of_supply_at_triggershelf_life_remaining_dayscreated_atcreated_by_agent
Relations
─created_by→MarkdownAgent
─updates→PricingState
─logged_in→AgentDecision
🔎
CompetitorPriceSignal
External Data · KVI Benchmarking · Weekly Competitive Scan
signal_idsku_idcompetitor_idcompetitor_priceour_priceprice_gap_pctis_kviscanned_date
Relations
─informs→PricingAgent
─flags→PricePoint (KVI credibility check)
Store & NetworkStore · ReplenishmentPolicy · PlanogramSlot · Consumer-facing stocking point and shelf constraints
🏪
Store
Stocking Point · Consumer-Facing · All Flow Models
store_idbanner_nameaddressformat_typesq_footageserved_by_dc_iddelivery_days_of_weekorder_cycle_dayscutoff_time
Relations
─has_inventory→InventoryPosition
─served_by→DistributionCenter
─receives→TransferOrder
─receives→DSDDelivery
─located_in→MarketArea
📋
ReplenishmentPolicy
Rule · Per SKU × Stocking Point · Flow-Model Specific
policy_idreorder_pointorder_up_to_levelmin_order_qtysafety_stock_dayslead_time_daysflow_modelstocking_point_typereview_cycle_days
Relations
─applied_to→Product × StockingPoint
─derived_from→StoreDemandForecast | DCReplenishForecast
🗂️
PlanogramSlot
Spatial · Store · Shelf Capacity Constraint
slot_idaisleshelf_levelfacingscapacity_unitsdisplay_type
Relations
─assigned_to→Product
─constrains→InventoryPosition (store)
Inventory & Net RequirementsDistributionCenter · InventoryPosition · NetRequirement · Two-tier stock position and derived order quantities
🏭
DistributionCenter
Stocking Point · Intermediate · Warehouse & Cross-Dock Capable
dc_idregioncapacity_palletstemp_zonescross_dock_capablestore_ids_served[]vendor_lead_time_avgorder_cycle_daysdelivery_schedule
Relations
─has_inventory→InventoryPosition
─serves→Store[]
─receives_from→Supplier (via PO)
─ships_via→TransferOrder
📊
InventoryPosition
State · Both Stocking Points · OH + IT + OO + Allocated
inv_idon_hand_qtyin_transit_qtyon_order_qtyallocated_qtyavailable_qtystocking_point_typedays_of_supplycode_date_earliestflow_modelshrink_ratelast_updated
Relations
─for_sku→Product
─at→Store | DistributionCenter
─feeds→NetRequirement
⚖️
NetRequirement
Derived · Both Stocking Points · Gross Forecast minus All Commitments
nr_idstocking_point_idstocking_point_typesku_idgross_requirementless_on_handless_in_transitless_on_orderless_allocatednet_qtycalculated_at
Relations
─derived_from→Forecast + InventoryPosition
─triggers (store)→TransferOrder
─triggers (DC)→PurchaseOrder
Supply Chain & SourcingSupplier · PO · TO · DSDDelivery · Contracts · ColdChainEvent · VendorScorecard · All order and delivery transactions
🏭
Supplier
Partner · Warehouse or DSD · Reliability Scored
supplier_idnametierreliability_scorelead_time_distmin_order_valuesupplier_typedsd_flagships_to_dcships_direct_to_store
Relations
─supplies→Product
─ships_to→DistributionCenter | Store
─has_contract→PurchaseContract | DSDSupplierContract
📄
PurchaseOrder
Transaction · Vendor → DC · F-01 Warehouse Flow
po_idstatuscreated_atexpected_deliverytotal_valuedestination_dc_idflow_modelcreated_by_agentapproval_status
Relations
─ordered_from→Supplier
─destined_to→DistributionCenter (F-01 only)
─generated_from→NetRequirement (DC)
🔄
TransferOrder
Transaction · DC → Store · Daily Replenishment Pull
to_idsource_dc_iddest_store_idstatusrequested_qtyfilled_qtyshort_qtycreated_atexpected_arrivalgenerated_by_agent
Relations
─sourced_from→DistributionCenter
─destined_to→Store
─generated_from→NetRequirement (Store)
─reduces→DC allocated_qty
🚚
DSDDelivery
Transaction · Supplier → Store · Vendor-Managed · F-02 Flow
delivery_iddsd_supplier_idstore_iddelivery_dateasn_receivedpod_scannedinvoice_idunits_deliveredunits_refusedroute_id
Relations
─from→Supplier (DSD)
─to→Store
─governed_by→DSDSupplierContract
─benchmarked_by→DSDShadowForecast
📃
PurchaseContract
Agreement · Warehouse Suppliers · MOQ & SLA
contract_idstart_dateend_datecommitted_volumeprice_breaksservice_level_target
Relations
─constrains→PurchaseOrder
─covers→Product[]
🤝
DSDSupplierContract
Agreement · DSD Suppliers · OOS Penalty & VMI Terms
contract_iddsd_supplier_idstore_ids[]delivery_frequencyservice_level_targetoos_penalty_clausescan_based_tradingvendor_managed_inventory
Relations
─governs→DSDDelivery
─monitored_by→DSDMonitorAgent
─informed_by→VendorScorecard (renewal)
❄️
ColdChainEvent
Quality Event · Temp Excursion · Triggers Inventory Write-Down
event_idstocking_point_idsku_ids_affected[]temp_reading_fduration_minsseverityinventory_written_off
Relations
─affects→InventoryPosition
─triggers→NetRequirement recalc
🏆
VendorScorecard
Performance · DSD Supplier · OOS & Waste Risk Scored
scorecard_iddsd_supplier_idstore_idsku_idperiod_startperiod_endactual_units_deliveredrecommended_unitsvariance_pctoos_incidentsoverstock_incidentsfill_rate_pctwaste_risk_scoreshared_with_vendor
Relations
─scores→Supplier (DSD)
─derived_from→DSDShadowForecast + DSDDelivery
─informs→DSDSupplierContract (renewal)
Demand & ForecastStoreDemandForecast → DCReplenishForecast · SalesHistory · PromotionEvent · CalendarEvent · DSDShadowForecast
📈
StoreDemandForecast
Prediction · Tier 1 · SKU × Store × Day · Drives TransferOrders
forecast_idsku_idstore_idhorizon_dayspredicted_consumer_unitsconfidence_intervalmodel_versionmape_recent
Relations
─feeds→NetRequirement (store)
─rolls_up_to→DCReplenishmentForecast
─adjusted_for→PromotionEvent, WeatherSignal, CalendarEvent
🏭
DCReplenishmentForecast
Prediction · Tier 2 · SKU × DC × Day · Drives PurchaseOrders
forecast_idsku_iddc_idhorizon_daysprojected_to_demandorder_pattern_adjustmentmodel_version
Relations
─feeds→NetRequirement (DC)
─derived_from→StoreDemandForecast[] + order behavior
─drives→PurchaseOrder (via OrderingAgent)
📜
SalesHistory
Time Series · POS · OOS & Promo Flagged
txn_dateunits_soldrevenuewas_on_promowas_ooschannel
Relations
─feeds→StoreDemandForecast
─for→Product × Store
🎯
PromotionEvent
Event · Uplift Modifier · Requires Inventory Pre-Build
promo_idtypestart_dateend_dateexpected_uplift_pctchannel
Relations
─boosts→StoreDemandForecast
─requires→InventoryBuild at DC + Store
📅
CalendarEvent
Temporal Context · Holiday & Local Event · Demand Multiplier
event_idevent_typedatedemand_multiplieraffected_categories
Relations
─modifies→StoreDemandForecast
─scoped_to→MarketArea
💾
ForecastDataStore
Integration · ML Engine Output · Read by Forecast & DSD Agents
store_idsku_idforecast_datehorizon_dayspredicted_unitsconfidence_lowconfidence_highmodel_versionrefresh_cadencewritten_at
Relations
─read_by→Store-ForecastAgent
─read_by→DSD-ShadowForecastAgent
─written_by→External ML Engine (existing)
📊
DSDShadowForecast
Prediction · DSD Benchmark · Retailer-Generated Independent Forecast
forecast_idsku_idstore_idhorizon_dayspredicted_unitsrecommended_order_qtyreorder_pointsafety_stock_dayssource_forecast_idgenerated_at
Relations
─derived_from→ForecastDataStore
─benchmarks→DSDDelivery
─feeds→VendorScorecard
AgentsOrchestratorAgent coordinates 13 specialist agents across category planning, pricing, forecasting, ordering, DSD monitoring, perishable clearance, and exception management
🧠
OrchestratorAgent
Agent · Control Plane · Coordinates All Sub-Agents
agent_idpriority_queueescalation_ruleshuman_in_loop_triggers
Relations
─coordinates→All Sub-Agents
─escalates_to→HumanBuyer
📈
Store-ForecastAgent
Agent · Tier 1 · Store Demand Forecast from POS + Signals
agent_idscope: storemodel_typeaccuracy_mapelast_retrain_date
Relations
─produces→StoreDemandForecast
─consumes→SalesHistory, ForecastDataStore, Signals
🏭
DC-ForecastAgent
Agent · Tier 2 · DC Replenishment Forecast + Order Lump Adjustment
agent_idscope: dcmodel_typeaccuracy_mape
Relations
─produces→DCReplenishmentForecast
─derived_from→StoreDemandForecast[] + store order patterns
📦
OrderingAgent
Agent · PO Generation · Vendor → DC
agent_idapproval_thresholdauto_approve_limitscope: DC→Vendor
Relations
─creates→PurchaseOrder (Vendor→DC)
─reads→NetRequirement (DC)
🔄
TransferAgent
Agent · TO Generation · DC → Store · Availability Check
agent_idscope: DC→Storedc_availability_checkpartial_fill_logic
Relations
─creates→TransferOrder (DC→Store)
─reads→NetRequirement (Store)
─checks→InventoryPosition (DC) available_qty
🔍
DSDMonitorAgent
Agent · DSD Compliance · OOS & Invoice Monitoring
agent_idoos_sensitivityservice_level_thresholdinvoice_match_rules
Relations
─monitors→DSDDelivery, DSDSupplierContract
─flags→OOS incidents, invoice mismatches
⚠️
ExceptionAgent
Agent · Anomaly Detection · Both Stocking Points
agent_idalert_thresholdsoos_sensitivityoverstock_threshold
Relations
─monitors→InventoryPosition (both tiers)
─triggers→AgentDecision, escalation
🕵️
DSD-ShadowForecastAgent
Agent · DSD Benchmark · Reads ForecastDataStore for DSD SKUs
agent_idscope: DSD SKUs onlyrefresh_cadencescoring_window_daysoos_threshold_daysoverstock_threshold_pct
Relations
─reads→ForecastDataStore
─produces→DSDShadowForecast
─produces→VendorScorecard
💲
PricingAgent
Agent · KVI Price Monitoring & Markdown Execution
agent_idkvi_gap_threshold_pctmarkdown_floor_pctprice_elasticity_modelreview_cadence_days
Relations
─monitors→CompetitorPriceSignal vs PricePoint
─creates→PricingState (KVI adjustments)
─creates→MarkdownEvent (perishable clearance)
─escalates_to→HumanBuyer (deep markdown or KVI breach)
📋
AssortmentAgent
Agent · Range Optimisation & SKU Productivity Review
agent_idvelocity_thresholdreview_cadence_weeksnew_sku_trial_weeksformat_range_model
Relations
─reviews→AssortmentPlan vs SalesHistory (SKU productivity)
─flags→low-velocity SKUs for delist consideration
─recommends→RangePlanogram updates
─escalates_to→HumanBuyer (delist / new SKU decision)
🎯
PromoPlanAgent
Agent · Promotional Calendar Execution & Uplift Monitoring
agent_idpre_build_lead_daysuplift_modelpost_promo_bleed_window_daysroi_threshold
Relations
─activates→PromotionEvent from PromotionPlan
─triggers→Inventory pre-build NetRequirement at DC + Store
─monitors→Actual uplift vs expected_uplift_pct
─escalates_to→HumanBuyer (Day-1 promo OOS or under-performance)
💰
MarkdownAgent
Agent · Perishable Clearance · Code-Date & Overstock Triggered
agent_idshelf_life_threshold_pctmarkdown_cascade_stepsmargin_floor_pctreview_cadence_hours
Relations
─monitors→InventoryPosition.days_of_supply vs shelf_life
─creates→MarkdownEvent (progressive cascade)
─suspends→ReplenishmentPolicy during clearance
─escalates_to→HumanBuyer (margin floor breach)
📡
SignalAgent
Agent · External Data Ingestion · Continuous Feed
agent_idsignal_sources[]refresh_cadenceanomaly_threshold
Relations
─ingests→WeatherSignal, MarketSignal, CompetitorPriceSignal
─writes→KG signal entities on each refresh cycle
─alerts→ExceptionAgent on anomaly detection
📝
AgentDecision
Audit Log · Immutable · Every Agent Action with Full Rationale
decision_idagent_refdecision_typerationaleconfidence_scoretimestampoutcomehuman_reviewed
Relations
─made_by→Agent
─references→NetRequirement | Forecast
─results_in→PurchaseOrder | TransferOrder
External SignalsWeatherSignal · MarketSignal · MarketArea · Feed store demand forecasts and supplier risk scoring
🌦️
WeatherSignal
External Data · Severe Weather Demand Multiplier by Category
signal_iddateconditiontemp_fseverity_level
Relations
─modifies→StoreDemandForecast
─scoped_to→MarketArea
📰
MarketSignal
External Data · Commodity Prices · Supply Disruption Risk
signal_idsourcesignal_typecommoditysupply_disruption
Relations
─impacts→Supplier reliability_score
─triggers→DCReplenishmentForecast adjustment
🗺️
MarketArea
Geography · Demographics · Competitor Density · Demand Context
area_idregion_namedemographicscompetitor_density
Relations
─contains→Store[]
─shapes→StoreDemandForecast
Product
Store
DC
Supply Chain
Demand/Forecast
Agents
External Signals
Merch Planning
Pricing & Promos
Filter:

Drag nodes · Hover for details · Click to highlight connections · Filter buttons above

Ontological Relationships
SubjectPredicateObjectCardinalityPriorityNotes
Flow Models

The nine flows below cover the full grocery operating cycle — from quarterly category planning through daily store replenishment and perishable clearance. Flows F-01 to F-05 govern physical inventory movement. Flows F-06 to F-09 govern merchandising decisions that shape what is stocked, how it is priced, and how promotions are executed.

Supply Chain Flows — Physical Inventory Movement
F-01
Warehouse Replenishment
Vendor → DC → Store · Dominant model for dry, frozen, dairy, HBC and GM. Two stocking points, two order types, two independent net requirement calculations.
VENDORSupplierPurchaseOrderDISTRIBUTIONCENTERStocking PointTransferOrderSTOREStocking PointNetReq = DC Fcst − OH − IT − OO − AllocNetReq = Store Fcst − OH − IT − OO
Order Types
PurchaseOrder (Vendor→DC)TransferOrder (DC→Store)
Lead Times
Vendor→DC: 2–7dDC→Store: 1–2d
Agents
DC-ForecastAgentStore-ForecastAgentOrderingAgentTransferAgent
Netting
DC: nets allocated qtyStore: nets open TOs
F-02
Direct Store Delivery (DSD)
Supplier manages replenishment to shelf · Coke, Frito-Lay, Pepsi, bread/bakery brands, beer/wine · Retailer benchmarks via shadow forecast
DSD SUPPLIERCoke · Frito-LayOwns replenishmentDSD Deliverybypasses DCDC bypassedentirelySTOREReceiving scanShadow ForecastVendorScorecard
Key distinction: Retailer does NOT generate POs or TOs for DSD SKUs. The system produces a shadow forecast & recommended order quantity for every DSD SKU as an independent benchmark. Deliveries are scored on OOS risk (under-delivery) and waste/markdown risk (over-delivery). Both scores feed the VendorScorecard used in contract negotiations. Agent roles: DSD-ShadowForecastAgent (benchmark) + DSDMonitorAgent (compliance).
Order Ownership
Supplier-generatedRoute-scheduledNo retailer PO
Retailer Touchpoints
ASN receiptPOD scanInvoice matchOOS monitor
Agents
DSD-ShadowForecastAgentDSDMonitorAgentExceptionAgent
Net Req
None — supplier owns
F-03
Cross-Dock / Flow-Through
Vendor → DC (transit only, pre-allocated) → Store · Fresh produce, promo pre-build, short-shelf-life categories where DC stocking would create spoilage risk
VENDORDC CROSS-DOCKNo inventory heldSort→Load→ShipSTOREDC = in-transit only — pre-allocated to stores before PO issued
DC Inventory
In-transit onlyPre-allocated to stores
Net Req
Store only — no DC on-hand
Agents
OrderingAgentTransferAgent
Use Cases
Fresh producePromo pre-buildShort shelf-life dairy
F-04
Direct-to-Store (Retailer-Ordered)
Vendor → Store · Retailer issues PO · Bulky items, local/specialty suppliers, categories where DC adds no value · DC bypassed entirely
VENDORLocal/SpecialtyPO · Direct Delivery (DC bypassed)STOREReceiving dock
vs DSD
Retailer issues PORetailer owns decision
Net Req
Store only
Agents
Store-ForecastAgentOrderingAgent
Categories
Bulky beveragesLocal bakeriesPeat & garden
F-05
Transfer Order — DC to Store (Daily Pull)
Store net requirement triggers a TO against available (unallocated) DC inventory. Most common daily replenishment event. Upstream PO is a separate, independent process triggered by the DC net requirement.
DC INVENTORYon_hand − allocated= available_qtyDC checks available balance before filling TOTransferOrderIN-TRANSITDC→Store 1–2dSTORE INVENTORYon_hand+ in_transit (this TO)+ on_order (open TOs)TransferAgentre-evaluates
Trigger
Store net req > 0DC available_qty > 0
DC Balance Check
on_hand − allocated open TOs = available
Agents
TransferAgentExceptionAgent (DC short)
Short DC
Partial fill + OOS alertTriggers PO expedite
Merchandising Flows — Planning, Pricing & In-Season Execution
F-06
Assortment Review & Range Reset QUARTERLY
CategoryPlan → AssortmentAgent reviews SKU productivity → delist / new-line recommendations → RangePlanogram updated → store reset scheduled. Runs quarterly ahead of each trading period; outputs feed into the next quarter's PromotionPlan and ReplenishmentPolicy activation.
CATEGORY PLAN SKU count target Revenue target Margin target + SalesHistory ASSORTMENT AGENT Velocity scoring Delist / ADD flags RANGE DECISIONS AssortmentPlan updated Delist SKUs flagged New lines approved Human buyer gate STORE RESET RangePlanogram updated ReplenishmentPolicy reset PlanogramSlot re-allocated Store team notified
Input Entities
CategoryPlan (SKU count, revenue, margin targets)SalesHistory (rolling 12-week velocity)AssortmentPlan (current active range)
Output Entities
AssortmentPlan (revised — delist / new-line)RangePlanogram (facing re-allocation)ReplenishmentPolicy (activate / suspend per SKU)
Agents
AssortmentAgentOrchestratorAgent (buyer gate)
Decision Rules
12w velocity < threshold & non-perishable → delist candidate (R-013)New SKU trial: 8-week evaluation windowAll delist/add decisions require human buyer approval
Ontology note. This flow runs quarterly rather than continuously. Its outputs — an updated AssortmentPlan and RangePlanogram — are the formal inputs to the next quarter's promotional planning and store replenishment activation. The SKU-level delist gate (R-013) fires continuously in the background, but the actual range change is batched into this flow to coordinate with store resets and supplier notice periods.
F-07
KVI Price & Competitive Response WEEKLY
CompetitorPriceSignal → PricingAgent benchmarks KVI shelf prices → gap above threshold triggers review → PricingState updated → KVI Price Index monitored. Runs weekly on a defined KVI basket; non-KVI pricing follows the PromotionPlan cadence only.
COMPETITOR PRICE SIGNAL Competitor price Our shelf price is_kvi = true PRICING AGENT Gap vs threshold Margin floor check Auto or escalate PRICE DECISION Gap < threshold → hold Gap ≤ 5% → auto-match Gap > 5% → buyer gate Margin floor enforced PRICING STATE PricingState updated KVI Price Index tracked PricePoint reference kept AgentDecision logged
Input Entities
CompetitorPriceSignal (weekly KVI scan)PricePoint (our regular shelf price)Category.margin_floor_pct
Output Entities
PricingState (revised shelf price)AgentDecision (log of price action with rationale)KVI Price Index (M-04 KPI updated)
Agents
PricingAgentOrchestratorAgent (buyer gate for large gaps)
Decision Rules (R-014)
price_gap_pct > kvi_gap_threshold → flag for reviewAuto-adjust only within ±3% margin floor headroomLarger adjustments → HumanBuyer approval
Scope boundary. This flow applies only to KVI SKUs (is_kvi = true in CompetitorPriceSignal). Non-KVI pricing changes are driven by PromotionPlan (F-06) or MarkdownEvent (F-07). This separation prevents the pricing engine from competing with its own promotional calendar or inadvertently breaching promo commitments already made to vendors.
F-08
Promotional Circular Execution IN-SEASON
PromotionPlan → PromoPlanAgent activates PromotionEvent → pre-build triggered at DC + Store → shelf price updated via PricingState → uplift monitored in real-time. PromoPlanAgent tracks actual vs planned uplift and escalates Day-1 OOS to buyer immediately.
PROMOTION PLAN Category + week Featured SKUs Expected uplift PROMO PLAN AGENT Activate event Trigger pre-build INVENTORY PRE-BUILD NetRequirement DC + Store PRICING STATE Promo price activated LIVE PROMO Shelf price live Stock pre-built Uplift monitored Day-1 OOS alert PromoPlanAgent re-evaluates
Input Entities
PromotionPlan (category + week + SKUs)StoreDemandForecast (baseline)InventoryPosition (both tiers)
Output Entities
PromotionEvent (activated)PricingState (promo price live)NetRequirement (pre-build at DC + Store)AgentDecision (uplift monitoring log)
Agents
PromoPlanAgentPricingAgentStore-ForecastAgent (uplift layer)ExceptionAgent (Day-1 OOS)
Trigger
Promo start date − pre_build_lead_days reacheduplift_pct > 0.15 in PromotionPlan
Escalation
Day-1 promo OOS > 3% → HumanBuyer alertActual uplift < 50% of plan → buyer review
Ontology note. Every PromotionEvent carries a promo_id traceable back through PromotionPlan to the original CategoryPlan. This gives full attribution of whether promotional spend converted to sales uplift — enabling post-event category reviews that feed back into next quarter’s PromotionPlan calibration.
F-09
Perishable Markdown & Waste Prevention DAILY
Code-date proximity or excess days-of-supply triggers MarkdownAgent → MarkdownEvent → PricingState updated → velocity re-forecast → waste prevented. MarkdownAgent applies a progressive discount cascade calibrated to remaining shelf life, not a flat clearance price.
STORE INVENTORY days_of_supply > shelf_life × 60% threshold is_perishable = true MarkdownAgent evaluates code-date vs days-of-supply daily MarkdownEvent PRICE REDUCTION Depth ↑ velocity Progressive cascade OUTCOME Units sold (no waste) PricingState updated Replen suspended AgentDecision logged MarkdownAgent re-evaluates
Trigger Conditions
days_of_supply > shelf_life_days × 0.60is_perishable = trueInventoryPosition.on_hand > min_display_qty
Output Entities
MarkdownEvent (depth + trigger reason)PricingState (reduced price active)ReplenishmentPolicy.SUSPEND (avoid re-order)
Agents
MarkdownAgent (PricingAgent)ExceptionAgent (waste alert)Store-ForecastAgent (velocity re-forecast)
Progressive Cascade
Day 1–2: 15% off → velocity checkDay 3: 25% off if still elevatedDay 4: 40% off (floor: margin floor rule)Breach floor → HumanBuyer escalation
Guard Rails
Margin floor (R-004): max 30% off without buyer approvalReplenishment auto-suspended on markdown trigger
Grocery vs fashion distinction. Fashion uses markdown to clear end-of-season stock over weeks. Grocery markdown operates daily, driven by code-date proximity rather than seasonal lifecycle — a fresh produce item may go through the full cascade in 2 days. The trigger is a formula against shelf life, not a lifecycle phase flag. DSD over-deliveries that create waste risk are scored in the VendorScorecard separately; this flow covers retailer-owned stocking points only.
Flow Model Comparison
FlowTypeCadenceOrder / ActionKey AgentsTypical Categories
F-01 WarehouseSupply ChainDailyPO + TransferOrderDC-ForecastAgent, OrderingAgent, TransferAgentDry, Frozen, Dairy, HBC, GM
F-02 DSDSupply ChainPer routeSupplier-generatedDSDMonitorAgent, DSD-ShadowForecastAgentBeverages, chips, bread, beer
F-03 Cross-DockSupply ChainDailyPO (pre-alloc)OrderingAgent, TransferAgentFresh produce, promo pre-build
F-04 Direct-StoreSupply ChainWeeklyPO to storeStore-ForecastAgent, OrderingAgentBulky beverages, local suppliers
F-05 Transfer OrderSupply ChainDailyTransferOrderTransferAgent, ExceptionAgentAll warehouse-stocked SKUs
F-06 Assortment ReviewMerchandisingQuarterlyAssortmentPlan + PlanogramAssortmentAgent, OrchestratorAgentAll categories
F-07 KVI Price ResponseMerchandisingWeeklyPricingState updatePricingAgent, OrchestratorAgentKVI basket (is_kvi = true)
F-08 Promo ExecutionMerchandisingPer eventPricingState + pre-build NRPromoPlanAgent, PricingAgent, ExceptionAgentAll promoted SKUs
F-09 Perishable MarkdownMerchandisingDailyMarkdownEvent + PricingStateMarkdownAgent, ExceptionAgentFresh, Bakery, Meat, Dairy
Net Requirements by Stocking Point
🏪
Store Net Requirement
STOCKING POINT · CONSUMER-FACING · DAILY CALCULATION
// Gross need over order horizon (horizon capped to shelf life for perishables) GrossNeed = SUM( StoreForecast[t..t+h] ) * PromotionUpliftFactor // 1.0 base; >1.0 if PromotionEvent active + SafetyStock( lead_time, demand_σ ) // Net out all committed inventory NetNeed = GrossNeed - on_hand_store - in_transit_from_dc // shipped TOs not yet received - on_order_open_tos // approved TOs not yet shipped OrderQty = MAX( NetNeed, 0 ) rounded to inner_pack_size // Guard: if ReplenishmentPolicy.status = SUSPENDED (markdown or post-promo) // THEN OrderQty = 0 regardless of NetNeed
StoreForecast[t..t+h]+ML demand over horizon — horizon = min(lead_time, shelf_life_days) for perishables
PromotionUpliftFactor×Applied when PromotionEvent is active — sourced from PromotionPlan.expected_uplift_pct
SafetyStock+Buffer calibrated by segment — 1–2d fresh, 7–14d dry grocery
on_hand_store−Physical stock at store (adjusted for code-date shrink on perishables)
in_transit_from_dc−Shipped TOs not yet received at store
on_order_open_tos−Approved TOs not yet dispatched from DC
→ TransferOrder Qty=Sent to DC if available_qty > 0 and policy not SUSPENDED
🏭
DC Net Requirement
STOCKING POINT · INTERMEDIATE · DAILY CALCULATION
// DC forecast covers vendor lead time + store lead time + buffer GrossNeed = SUM( DC_Forecast[t..t+vendor_lt] ) + PromoPreBuildQty // added 14d before event if uplift > 15% + SafetyStock( vendor_lt_σ, demand_σ ) // Net out entire DC pipeline including allocated NetNeed = GrossNeed - on_hand_dc - in_transit_from_vendor // shipped POs - on_order_open_pos // confirmed POs - allocated_to_stores // committed to open TOs PO_Qty = MAX( NetNeed, min_order_qty )
DC_Forecast[t..t+vlt]+Projected TO demand — horizon = vendor_lt + store_lt + buffer
PromoPreBuildQty+Added by PromoPlanAgent when event start ≤ 14 days away (R-015)
SafetyStock+Buffer for vendor lead time variability — calibrated per segment
on_hand_dc−Physical inventory in DC
in_transit_from_vendor−Shipped POs not yet at DC
on_order_open_pos−Confirmed POs not yet shipped by vendor
allocated_to_stores−DC on-hand committed to open TOs — prevents double-netting
→ PurchaseOrder Qty=Sent to vendor if net_qty > 0 and no open PO covers gap
⚠ Temporal Coupling: The DC must look ahead far enough to cover both the vendor lead time and the downstream store replenishment cycle. If a store needs product in 2 days and vendor lead time is 5 days, the DC needed to trigger a PO at least 7 days ago. DC forecast horizon = vendor_lead_time + max_store_lead_time + safety_buffer. These two forecasting clocks must be synchronized in the orchestration layer. For promo events, an additional pre-build window of 14 days is added on top of the normal DC horizon (R-015).
Merchandising Adjustments to Net Requirements
🎯 Promotional Pre-Build
When PromotionEvent.start_date − NOW() ≤ 14 days and uplift_pct > 0.15, PromoPlanAgent adds a pre-build quantity to both Store and DC gross requirements. Store target is uplifted by (1 + uplift) × 1.2; DC target is the sum of store pre-builds × 1.1. This fires as a direct injection into NetRequirement, not as a forecast change.
Agent: PromoPlanAgent · Rule: R-015 · Entities: PromotionPlan → PromotionEvent → NetRequirement
📉 Perishable Markdown Suspension
When days_of_supply > shelf_life × 0.6 on a perishable SKU, MarkdownAgent fires a MarkdownEvent and simultaneously sets ReplenishmentPolicy.status = SUSPENDED. While suspended, OrderQty is forced to 0 regardless of the net requirement calculation — preventing the system from re-ordering stock that is already being cleared.
Agent: MarkdownAgent · Rule: R-004 · Entities: InventoryPosition → MarkdownEvent → ReplenishmentPolicy
⏸ Post-Promo Bleed-Down
Immediately after a promotion ends, if store days_of_supply > safety_stock × 2, ReplenishmentPolicy is paused for the bleed-down window. This prevents the system from ordering into the post-promo demand trough — particularly dangerous for perishables where excess stock will trigger a markdown cascade within days.
Agent: PromoPlanAgent + ExceptionAgent · Rule: R-016 · Entities: PromotionEvent → ReplenishmentPolicy.PAUSE
📋 Assortment Gate
Net Requirements are only calculated for SKUs where AssortmentPlan.status = ACTIVE. Delisted SKUs, seasonal SKUs outside their quarter, and trial SKUs under evaluation have their ReplenishmentPolicy suspended — the netting formula never fires. This is the primary gate that connects range decisions to the replenishment engine.
Agent: AssortmentAgent · Rule: R-013, R-017 · Entities: AssortmentPlan → ReplenishmentPolicy → NetRequirement
🔴 DSD — No Net Requirement
DSD SKUs never generate a NetRequirement. The supplier owns replenishment. The retailer's system produces a DSDShadowForecast as an independent benchmark, but this does not feed into the netting engine — it is used solely for VendorScorecard scoring and contract negotiations. DSD SKUs are explicitly excluded from the ReplenishmentPolicy loop.
Agent: DSD-ShadowForecastAgent (benchmark only) · Entities: DSDShadowForecast → VendorScorecard (not → NetRequirement)
❄️ Cold Chain Write-Down
When a ColdChainEvent of CRITICAL severity occurs for more than 30 minutes, affected units are immediately written off from InventoryPosition.on_hand. This directly reduces the deduction side of the netting formula, causing NetNeed to spike upward — triggering an emergency replenishment order and OOS alert in the same cycle.
Agent: ExceptionAgent · Rule: R-008 · Entities: ColdChainEvent → InventoryPosition write-down → NetRequirement recalc
Inventory Pipeline States
StateAt StoreAt DCNetted?Set ByNotes
on_hand✓✓Yes (−)Receiving scan / SOH countPhysical stock in building. Adjusted for code-date shrink on perishables
in_transitFrom DCFrom VendorYes (−)TO / PO dispatchShipped but not yet received. Counts as committed supply
on_orderOpen TOsOpen POsYes (−)TransferAgent / OrderingAgentConfirmed, not yet shipped. Prevents duplicate orders
allocatedN/ACommitted to TOsDC only (−)TransferAgent on TO approvalDC on-hand reserved for open store TOs — prevents double-fill
available_qtyOH+IT+OOOH−Alloc+IT+OODerivedCalculatedTrue available balance. DC formula differs — allocated deducted from OH only
shrink / wasteYesMinorAdj to OHSegment policy / ColdChainEventSegment-specific % reduction applied to on-hand. Code-date write-downs immediate
promo_uplift+GrossNeed+GrossNeedYes (+)PromoPlanAgentUplift factor applied to gross requirement when PromotionEvent is active (R-015)
policy_suspendedOrderQty = 0N/AOverrideMarkdownAgent / PromoPlanAgentForces OrderQty to 0 regardless of NetNeed — active during markdown or post-promo bleed-down
assortment_inactiveNo calcNo calcGatedAssortmentAgentNetRequirement not calculated — SKU delisted, out-of-season, or under trial
Forecast Hierarchy
TIER 1 — STORE LEVEL
Store Demand Forecast
Per-SKU, per-store prediction of end consumer demand. Drives TransferOrder generation from DC.
granularity: SKU × Store × Dayhorizon: 1–28 daysinputs: POS, promo, weather, holidaysdrives: TransferOrderagent: Store-ForecastAgent
Roll up + adjust for store ordering behavior↓
DC Forecast Derivation
DC_Forecast[sku, dc, t] = SUM( StoreOrderForecast[sku, s, t] for s in DC.serves ) + adjusted for store order_cycle_rounding + adjusted for store min_order_quantities + adjusted for store_ordering_day_pattern + DC-level safety_stock_layer
The DC forecast is not a simple sum of store forecasts. Fixed order days and case-pack rounding create demand lumps at the DC that must be modeled explicitly.
↓
TIER 2 — DC LEVEL
DC Replenishment Forecast
Projects total outbound Transfer Order volume over a horizon covering vendor lead time. Drives Purchase Order generation.
granularity: SKU × DC × Dayhorizon: vendor_lt + store_lt + bufferdrives: PurchaseOrderagent: DC-ForecastAgent
↓Net requirements at DC → PO generated
OUTPUT
Purchase Order → Vendor
Generated by OrderingAgent from DC net requirements. Subject to contract constraints, MOQ, and vendor lead time windows.
created_by: OrderingAgentconstrained_by: PurchaseContractupdates: in_transit_from_vendor at DC
Why Two Separate Forecasts?
  • Store forecast drives when to transfer from DC; DC forecast drives when to buy from vendor
  • Horizons differ — store = store lead time; DC = vendor lead time
  • Store order lumping distorts DC-visible demand — must model explicitly
  • DC and store safety stocks independently calibrated by segment
  • DSD products have no DC forecast and no DC net requirements
Forecast Horizons by Segment
Dry GroceryStore 7d · DC 14–21d
FrozenStore 7d · DC 14–21d
Fresh ProduceStore 2–3d · DC 3–5d
Dairy / DeliStore 3–5d · DC 7–10d
BakeryStore 1–2d · DC 2–3d
Meat / SeafoodStore 2–4d · DC 5–7d
DSD – Shadow Forecast & Vendor Scoring
Retailer generates an independent shadow forecast and recommended order quantity for every DSD SKU by reading from the ForecastDataStore (existing ML engine output). No PO or TO is issued — the forecast is a benchmark only.
OOS risk score: vendor under-delivered vs recommendation   Waste/markdown score: vendor over-delivered vs recommendation. Both dimensions feed VendorScorecard, shared internally and with the DSD vendor.
Product Segments
Agent Pipeline — Quarterly Planning, Weekly Execution & Daily Operations
QUARTERLY PLANNING — Stages 01–03
WEEKLY EXECUTION — Stages 04–06
DAILY OPERATIONS — Stages 07–10
01
Category & Range Planning
AssortmentAgent scores SKU velocity against CategoryPlan targets. Computes revenue-per-active-SKU, flags low performers for delist, and identifies white-space gaps where the range is under-indexed vs basket data. RangePlanogram updated. Runs quarterly ahead of each trading period.
AssortmentAgentOrchestratorAgent
02
Competitive & Category Insights
PricingAgent benchmarks the KVI basket against CompetitorPriceSignal and computes a KVI Price Index per category. SignalAgent ingests MarketSignal for commodity and supply disruption risk. Outputs feed quarterly promo planning and set the price guardrails for Stage 03.
PricingAgentSignalAgent
03
Promotional Planning
PromoPlanAgent builds the quarter's PromotionPlan: selects featured SKUs per week, sets expected uplift, calculates pre-build inventory requirements at both DC and Store, and gates each event by margin ROI and promo dependency rules. OrchestratorAgent arbitrates conflicts between pricing depth and margin floor.
PromoPlanAgentPricingAgentOrchestratorAgent
04
Signal Ingestion
SignalAgent collects POS streams, weather alerts, promo uplift actuals, DSD ASNs, supplier disruption flags, and in-week competitor price changes into the KG. All downstream stages read from this refreshed signal layer.
SignalAgentETL
05
Store Forecast
Store-ForecastAgent reads pre-computed forecasts from the ForecastDataStore and layers promo uplift (from PromotionPlan), weather multipliers, and calendar event factors. Perishable horizons are capped to shelf life. MAPE drift beyond threshold triggers model retrain flag.
Store-ForecastAgentForecastDataStore
06
DC Forecast & Pricing
DC-ForecastAgent rolls up store forecasts into DC-level TO demand, adjusted for case-pack rounding, fixed order days, and promo pre-build volumes. In parallel, PricingAgent activates any in-week KVI price adjustments and publishes updated PricingState to store systems.
DC-ForecastAgentPricingAgent
07
Net Requirements
At each stocking point, net gross forecast against on-hand, in-transit, on-order, and (DC only) allocated inventory. MarkdownAgent concurrently evaluates perishable days-of-supply against the 60% shelf-life threshold and fires markdown cascade where triggered.
TransferAgentOrderingAgentExceptionAgentMarkdownAgent
08
Order Generation
TransferAgent creates DC→Store TOs from store net requirements, checking DC available_qty before committing. OrderingAgent creates Vendor→DC POs from DC net requirements, constrained by MOQ and PurchaseContract. DSD-ShadowForecastAgent scores vendor deliveries and updates VendorScorecards.
TransferAgentOrderingAgentDSD-ShadowForecastAgentDSDMonitorAgent
09
Human Review & Execution
High-value POs, deep markdowns, KVI price changes above auto-threshold, delist recommendations, and promo Day-1 OOS alerts escalate to the human buyer. Approved actions are transmitted: POs via EDI, TOs to DC pick, markdown events to store pricing systems.
OrchestratorAgentHumanBuyerEDI Gateway
10
Learning Loop
Actuals close the loop across all cadences: promo uplift actuals calibrate the PromotionPlan uplift model; vendor fill rates update Supplier reliability scores; OOS and waste events retune safety stock parameters; markdown timing outcomes refine the perishable cascade thresholds; forecast MAPE drift triggers model retraining.
Store-ForecastAgentDC-ForecastAgentPromoPlanAgentAssortmentAgent
Agent Responsibilities — Planning, Execution & Operations
StageCadenceAgentRole in Grocery ContextKey OutputsGates & Triggers
01QuarterlyAssortmentAgentSKU velocity scoring, delist flagging, white-space gap identification, range resetAssortmentPlan, RangePlanogram, delist flags12w velocity < threshold → delist candidate (R-013)
02QuarterlyPricingAgentKVI basket benchmarking vs competitor; sets price guardrails for promo planningKVI Price Index, CompetitorPriceSignal review, price floorprice_gap_pct > threshold → buyer escalation (R-014)
03QuarterlyPromoPlanAgentBuilds promotional calendar; calculates pre-build volumes; gates events by margin ROIPromotionPlan, pre-build NetRequirement, PromoCalendaruplift_pct > 0.15 → pre-build trigger · ROI gate
04WeeklySignalAgentIngests POS, weather, DSD ASNs, competitor prices, supplier disruption flagsWeatherSignal, MarketSignal, CompetitorPriceSignalContinuous ingest; anomaly → ExceptionAgent alert
05WeeklyStore-ForecastAgentApplies promo uplift, weather, and calendar layers over ML engine base forecastStoreDemandForecast (per SKU × Store × Day)MAPE > 20% × 3 periods → retrain flag (R-010)
06WeeklyDC-ForecastAgentRolls up store forecasts; adjusts for case-pack rounding and fixed order daysDCReplenishmentForecast (per SKU × DC × Day)Horizon = vendor_lt + store_lt + buffer
06WeeklyPricingAgentActivates in-week KVI price adjustments; publishes updated PricingState to storesPricingState (KVI adjustments), AgentDecision logAuto ≤ 3% gap; > 3% → HumanBuyer gate
07DailyMarkdownAgentEvaluates perishable days-of-supply vs shelf-life threshold daily; fires progressive cascadeMarkdownEvent, PricingState update, ReplenishmentPolicy suspenddays_of_supply > shelf_life × 0.6 & is_perishable (R-004)
07DailyExceptionAgentAnomaly detection on OOS, overstock, and cold-chain events at both stocking pointsOOS Alert, ExceptionRecord, cold-chain write-down triggerOOS > 2% warehouse / > 3% DSD → alert escalation
08DailyTransferAgentCreates DC→Store TOs from store net requirements; checks DC available_qty before commitTransferOrder, AgentDecisionnet_qty > 0 & DC available_qty > 0 (R-001)
08DailyOrderingAgentCreates Vendor→DC POs from DC net requirements; enforces MOQ and contract constraintsPurchaseOrder, AgentDecisionnet_qty > 0 & no open PO covers gap (R-002)
08DailyDSDMonitorAgentMonitors DSD delivery compliance vs contract; flags OOS and invoice mismatchesComplianceRecord, OOS alert, invoice exceptionunits_delivered = 0 & stock < 2d supply (R-006)
08DailyDSD-ShadowForecastAgentReads ForecastDataStore for DSD SKUs; scores deliveries vs shadow recommendation; updates VendorScorecardDSDShadowForecast, VendorScorecard (OOS + waste scores)Under-delivery > 10% → OOS score · Over-delivery > 15% → waste score
—AllOrchestratorAgentSequences all agents, resolves conflicts between pricing and promo depth, manages human escalation workflowPlanVersion, ApprovalWorkflow, AgentDecision logConfidence < threshold · value > limit · conflict resolution
Inference Rules
KPI Framework: 32 metrics across four tiers — Merchandising (assortment, pricing & promo execution), Technical (forecast & agent quality), Operational (replenishment & DSD), and Business / Financial (P&L and working capital). Every KPI carries a named agent owner, target, and cadence. Every KPI is sliceable by Category, Store Format, Vendor / Supplier, and Supply Chain Flow. DSD performance and promotional events are filter values within each applicable KPI.
Show: Slice by:
Merchandising Merchandising Assortment productivity, promotional execution, pricing competitiveness
Tier 1 Technical System health, model accuracy, data pipeline integrity
Tier 2 Operational Supply chain execution, order accuracy, fill rates, service levels
Tier 3 Business / Financial Consumer impact, inventory economics, vendor value, P&L influence
KPI Slice Dimensions
DimensionValuesExample CutPrimary Use
Supply Chain FlowF-01 / F-02 / F-03 / F-04 / F-05OOS Rate for DSD (F-02) vs Warehouse (F-01)Benchmark supplier-managed vs retailer-managed flows
Product SegmentFresh / Frozen / Dairy / Dry / Bakery / Meat / HBC / GMWaste % for Fresh vs FrozenCalibrate safety stock and markdown thresholds by perishability
Vendor / Suppliersupplier_id, dsd_flag, tierFill Rate for Coca-Cola DSD vs private label warehouseContract negotiations, supplier tiering, compliance scoring
Store / Market Areastore_id, banner, market_area_id, format_typeAssortment productivity by format (superstore vs convenience)Format-appropriate ranging and planogram decisions
Quarter / Promo Weekquarter, promo_week, promotion_idPromo uplift realisation vs plan by promotion eventPromotional effectiveness review and future promo calibration