MarketPulseUK - notice that

Inspiration

Damm's UK sales team operates across dozens of cities and hundreds of events — F1 races, concerts, football fixtures — yet demand planning still relied on gut feel and spreadsheets. We asked: what if a
sales manager could open one tool, see exactly where volume is at risk, understand why, simulate their own decisions, and send a logistics email — all without touching Excel or waiting on a data analyst? MarketPulseUK is that tool.

What it does

MarketPulseUK is a demand intelligence platform for
Damm's UK commercial team. It shows two ML forecasts side by side — a baseline ensemble (Forecast A) and
an event-uplift-adjusted model (Forecast B) — with historic actuals, broken down monthly or weekly. The Locations page maps demand by city with event-driven uplift. The Testing page lets managers toggle which
events Damm actually attends and which promotions it runs, updating a custom forecast in real time so they can stress-test decisions before committing. Dammià, the built-in AI assistant, answers plain-English
questions about forecast drivers, surfaces SHAP explainability charts, and drafts logistics emails with suggested order quantities — all grounded in the live forecast data.

How we built it

• ML pipeline: scikit-learn ensemble model trained on historical volume, enriched with PredictHQ event data (attendance, hospitality spend, category). SHAP values computed for every prediction to power explainability.
  
• Backend: FastAPI + SQLAlchemy serving forecast comparisons, event uplift, scenario simulation, and a chat endpoint. SQLite locally, Supabase PostgreSQL in production.
  
• Frontend: Next.js 14 with Recharts for interactive area charts (stacked forecast layers with bridge
  logic), shadcn/ui components, and a real-time scenario simulator.
  
• AI: OpenAI GPT-4o-mini with a custom retrieval layer — every chat message is grounded in structured forecast context, with intent detection to trigger SHAP charts or email drafts automatically.
  
• Event uplift allocation: proportional to hospitality_spend_usd share per month, letting the
  Testing page compute a clean counterfactual when
  events are deselected.
  

Challenges we ran into

• Event uplift attribution: Splitting Forecast B's
  aggregate uplift back down to individual events, so the scenario simulator could remove one at a time,
  required building a proportional allocation model on top of the ML output.
  
• Chart layering: Recharts stacked areas with a separate dashed ceiling line needed careful SVG
  draw-order management so the tooltip showed the right values without duplicates.
  
• macOS SSL on Python.org installs: OpenAI calls
  failed silently on one team member's machine due to
  missing system certs — diagnosed via URL-level error logging and fixed with a certifi SSL context patch.
  
• Keeping the LLM grounded: Getting Dammià to answer only from actual forecast data, not hallucinate
  numbers, required a tight retrieval layer and
  structured JSON response format.
  

Accomplishments that we're proud of

• A fully working end-to-end scenario simulator:
  toggle events, see the forecast line move down in real time — something the sales team could actually
  use before a planning meeting.
  
• SHAP explainability surfaced through natural
  language — ask "what's driving summer volume?" and
  get signed driver charts, not a wall of text.
  
• The email skill: Dammià can draft a logistics order email with quantities derived from event uplift,
  ready to review and send — closing the loop from
  insight to action.
  
• Clean, production-ready architecture with a real
  database, API contracts between frontend and backend, and a separation between the ML layer and the
  application layer.
  

What we learned

• Event data is incredibly powerful for demand
  forecasting in FMCG — hospitality spend alone explained a large share of summer volume variance.
  
• LLM grounding matters more than model quality: a weaker model that only speaks from structured context beats a smarter one that improvises numbers.
• Scenario simulators need a clear mental model for
  users — the chart direction (line goes down when you remove events, not converges upward) took iteration
  to get right.
  
• Rapid full-stack prototyping is viable in a
  hackathon, but the interface between ML outputs and
  the API layer needs to be locked down early or
  everything downstream shifts.
  

What's next for MarketPulseUK

• Real-time event ingestion: automate PredictHQ pulls so the event calendar and uplift model update weekly without manual data drops.
  
• SKU-level forecasting: the current model operates at total volume — breaking it down to brand and pack size would make the logistics emails actionable without manual translation.
  
• Actuals feedback loop: as sales come in, automatically compare to Forecast A and B, flag
  deviations, and retrain the uplift model on the
  delta.
  
• Promotion effectiveness: the promo simulation currently treats promotions as binary — proper A/B
  data from retail partners would let the model
  quantify ROI per retailer tier.
  
• Mobile-first view for field reps: a stripped-down card view showing city-level status and one-tap email drafting for account managers on the road.
  

Built With

• node.js
• python