DammBridge UK

DammBridge UK is a local, privacy-safe commercial planning demo for Damm's UK business. It cleans the provided UK sales and promotion workbooks, forecasts and recommends ranked actions.

Comment

DammBridge UK Report

Executive Summary

DammBridge UK is a local, privacy-safe commercial planning demo for Damm's UK business. It cleans the provided UK sales and promotion workbooks, forecasts May-December 2026, compares the forecast against a 2025 target baseline, explains the drivers, and recommends ranked actions with expected recovered hectolitres and GBP impact.

The project is designed for a live hackathon demo: it has a TypeScript dashboard, a FastAPI backend, a deterministic local analyst fallback, and an optional Hugging Face-powered Commercial Copilot.

Business Problem

Damm needs a way to answer four practical questions for the UK market:

  1. How much volume are we likely to sell from May to December 2026?
  2. Where are we above or below target?
  3. Why are those deviations happening?
  4. Which commercial actions should we take first?

The demo turns this into one workflow:

forecast -> target gap -> driver explanation -> ranked action -> expected recovered Hl and GBP

Data And Privacy

Raw Damm files are never committed to Git. They stay on the local machine and are read from DAMM_RAW_DATA_DIR.

Expected private files:

  • UK DATA.xlsx
  • Damm Trade Plan - promotions.xlsx

The processing step:

  • filters to the UK using the customer dimension, mainly Cod. Pais == GB
  • joins customer and material dimensions using cleaned codes
  • removes non-positive-HL rows from demand modeling so returns/credits do not create negative demand
  • anonymizes customer and retailer names
  • aggregates outputs to segment level before display

The dashboard hides target-0 rows in forecast-vs-target visuals because those rows do not have a meaningful budget baseline.

System Architecture

Raw workbooks
  -> marketpulse prepare
  -> marketpulse enrich
  -> marketpulse train
  -> marketpulse forecast
  -> marketpulse recommend
  -> marketpulse impact
  -> FastAPI + TypeScript dashboard

Main modules:

  • src/marketpulse/data_pipeline.py: workbook loading, UK filtering, joins, anonymization, aggregation
  • src/marketpulse/enrichment.py: bank holidays, weather proxy, CPI, trends, sports, festivals
  • src/marketpulse/forecasting.py: transparent forecast engine and validation
  • src/marketpulse/recommendations.py: ranked commercial action logic
  • src/marketpulse/impact.py: gross-price-per-HL value estimates and scenario simulation
  • src/marketpulse/web_api.py: FastAPI backend and Copilot endpoint
  • frontend/: polished TypeScript dashboard

Forecast Method

The model is intentionally explainable rather than black-box. For each channel, subchannel, and brand segment:

forecast_volume = max(0, base_volume * promo_multiplier * external_multiplier)

Base volume blends prior-year seasonality and recent momentum:

base_volume = (0.60 * same_month_last_year + 0.40 * recent_3_month_average) * seasonal_factor

Promotion uplift is learned by brand from observed sales behavior and bounded to avoid unrealistic claims. External context includes UK bank holidays, London weather proxy, CPI pressure, sports events, festivals, and Google Trends fallback.

Gross Price And GBP Impact

The organizer guidance is used directly:

gross_price_per_hl = gross_sales / hectolitres_sold

For segment outputs, DammBridge uses:

gross_price_per_hl = sum(gross_sales) / sum(hl)

This weighted method avoids the distortion of averaging row-level prices equally. GBP impact is then:

estimated_gross_value = hectolitres * gross_price_per_hl

Validation And Results

The model is validated on January-April 2026 actuals.

Metric Result Meaning
Monthly WAPE 16.5% Four monthly totals; best number for commercial planning discussions
Segment WAPE 33.6% 204 channel x subchannel x brand rows; disclosed for transparency

Current generated May-December 2026 outputs:

Metric Value
Forecast total 685,761 Hl
Forecast gross value GBP 158M
Gap vs 2025 target +234,368 Hl (+52%)
Ranked recommendations 20
Below-target segment pockets 66
Best scenario recovery 2,291 Hl / GBP 465k

The headline +52% is the full generated forecast. The dashboard also filters out target-0 rows for budget-comparable visuals, so some displayed KPI totals can be lower by design.

Recommendation Engine

Recommendations are created from below-target segments. The score prioritizes:

  • size of the negative gap
  • expected recoverability
  • missing promotion calendar coverage
  • price pressure
  • external demand context

The generated actions are intentionally practical: fill a promotion gap, upweight an existing promotion, review price architecture, shift demand creation earlier, or focus sales execution on a weak segment.

Commercial Copilot

The Commercial Copilot answers questions from compact anonymized context. It never sends raw workbooks, customer names, or retailer names.

Behavior:

  • without HF_TOKEN: deterministic local analyst mode
  • with HF_TOKEN: Hugging Face chat-completions route using HF_MODEL, defaulting to Qwen 2.5 72B Instruct
  • if Hugging Face fails: graceful fallback to local analyst mode

Limitations

  • The target is a proxy: same segment and same month in 2025, because no separate official budget file was provided.
  • Historical sales are monthly, so weekly pacing is an allocation view rather than true weekly forecasting.
  • External future signals such as sports and festivals are curated assumptions, not guaranteed outcomes.
  • GBP values are gross-value decision proxies, not final audited finance numbers.

Why This Is Demo-Ready

DammBridge UK is not just a dashboard. It is a reproducible decision system: local data loading, explainable forecasting, documented assumptions, ranked actions, financial impact, an interactive simulator, and a Commercial Copilot. The demo can be run end-to-end from raw files on another machine using the README setup instructions.

Built With

Share this project:

Updates