UPLIFT — MAWSIM

Demand-aware promo planning for Dubai retail. Events, weather, holidays and school calendars drive footfall. MAWSIM forecasts that demand per store zone, lets a bounded agent crew plan promotions and creatives against the forecast, checks every claim against brand and food-advertising rules with citations, and then measures incremental lift rather than clicks.

Built for SP Jain MAIB Term 4, AI 208 AI in Marketing. Owner: Krishna Mathur.

The brand is fictional

SIDRA (سدرة) is an invented Dubai speciality coffee and bakery chain with four locations. It is not a real company, and nothing here is a claim about any real business. The footfall and point-of-sale figures it is planned against are generated by a seeded model in pipeline/footfall.py. FootfallRecord cannot be constructed without simulated=True, the database column is NOT NULL CHECK (simulated = 1), and every API response and every chart says so. A real pilot replaces that dataset with an actual export; nothing else in the system changes.

The chart on the lower right is the argument. Four sites, one axis, evening footfall against apparent temperature. Marina Walk — 54% of its seats outdoors — falls away as the evening heats up. Al Barsha, fully enclosed, barely moves. All four sit in neighbouring ERA5 grid cells, so they get the same weather: what differs is how they respond to it, and that is why demand is forecast per site rather than per brand.

That elasticity is not written into the simulator. It is derived from the seat counts in data/brand/sidra.yaml, so the measured result — Marina Walk 2.4× more temperature-sensitive than Al Barsha, with the ordering across all four sites matching their outdoor share exactly — is emergent rather than assumed. Change the seat counts and it follows.

Captured from a local run against a built database. Regenerate with cd apps/web && node scripts/screenshots.mjs.

Live

Application	https://uplift-mawsim.vercel.app
API	https://mawsim-api.onrender.com — /docs · /healthz
Verify it	LIVE_API_URL=https://mawsim-api.onrender.com LIVE_WEB_URL=https://uplift-mawsim.vercel.app make smoke-live

All fifteen tabs serve measured data. The seven live checks pass: the API answers, no dataset is empty, the page carries the disclaimer, the web app reaches the API across origins, every tab is present, the Security tab carries the red-team result rather than the scorecard alone, and the instance grants no Admin — fail-closed asserted against the real URL rather than inferred from the code.

The API sleeps after fifteen minutes idle, so the first request after a quiet period takes about fifty seconds while the free instance wakes. For a live demo, open /healthz a minute before you start. Every page renders an honest "API unreachable" state in the meantime rather than an empty chart.

What deployment taught the project

Three failures reached production and were caught by things built to catch them.

The database went to /tmp and vanished. Render's build and its runtime are different containers. The four pipelines ran, wrote a complete database, and threw it away. /healthz reported degraded and named all five empty datasets on the first request — which is the entire reason it reports what is loaded rather than only that the process is up.

A global gitignore was hiding a required input. ~/.gitignore_global excludes data/raw/ for every repository on the machine, so the curated events seed was never committed. git status was clean, the file was on disk, and nothing inside the repository revealed it. tests/invariants/test_repo_is_complete.py now asserts that every input the project needs to rebuild itself is tracked.

The forecast endpoint fitted models per request — ninety seconds on a 512 MB instance. The horizon is precomputed at build time and served as data; the endpoint went to 21 ms.

Standing constraints

• Zero paid inference. Ollama (local) → Gemini free tier → Groq free tier → a deterministic stub. Anthropic is present in the provider chain and permanently refuses to serve, so the refusal is visible in the code and covered by a test rather than being an absence someone later "fixes". Budgets are counted in requests, never tokens: the free tiers do not return trustworthy token accounting, and a number the project cannot verify has no business appearing in a report.
• Only free, licensed data. Every source is in docs/datasets.md with its URL, the date it was verified by fetching it, and its licence. The sources that refused are recorded there as prominently as the ones that worked, because which sources refused is part of what shaped the design.
• Every number traces to docs/results/. Not as a promise — tests/test_docs_match_results.py extracts the figures quoted in docs/models.md and fails if they disagree with the JSON that produced them.
• No agent has a side-effect tool. Nothing is published or executed externally. Exporting a campaign is a human action, taken outside this application.

Fifteen tabs, all working

Every tab renders measured output. None is a scaffold.

Group	Tabs
Plan	Season (3D terrain + map) · Forecast · Plan · Segments
Make	Creatives · Brand · Compliance · Panel
Prove	Measure · Experiments · Report
System	Ask · Crew · Data · Security

What is measured, and where

Claim	Evidence	Result
Forecast beats seasonal naive	python scripts/run_phase_b.py	36/36 site-weeks, MAE 28–34% lower — B1
An injected lift is recovered	same	all 5 checks within 2.61 pts of a 5-point tolerance — B4
Segments survive resampling	same	91.8% keep their segment — B2
The allocator finds the optimum	same	KKT marginal spread ~0 — B3
Compliance catches violations in three languages	python scripts/run_phase_c.py	recall 100% worst language, precision 100% — C1
Weather history is complete	python -m pipeline.weather --verify	18,048 hours per site, no gap over 3 h — A4
Islamic dates reproduce UAE observances	python -m pipeline.calendar --verify	all four 2025 observances matched — A5
Events are curated and say so	python -m pipeline.events --verify

Running it

uv sync --extra dev
cd apps/web && npm install && cd ../..
make etl        # build the datasets — weather and events reach the network, cached to data/raw/
uv run python scripts/run_phase_b.py   # forecast, segments, allocator, uplift
uv run python scripts/run_phase_c.py   # compliance and panel
uv run python scripts/build_report.py  # the AI 208 artefact, from docs/results/
uv run python scripts/red_team.py      # 34 attacks against the safety claims
make check      # the green bar: ruff, pytest, contrast, palette, red team, placeholders, typecheck
make e2e        # Playwright; starts both servers itself
make api        # http://localhost:8000/docs
make web        # http://localhost:3000

Layout

Path	What lives there
services/api/	FastAPI service: dataset registry, series endpoints, brand kit loader
pipeline/	The four ETLs — weather, calendar, events, footfall — each with --verify
apps/web/	Next 16 application: fifteen tabs, three languages, two registers
data/brand/sidra.yaml	The single source of truth for the fictional brand
docs/results/	Every measured number, written by a script
docs/datasets.md · docs/models.md	What the data is, what the models are, and why
docs/directions.md	The three design directions that were built, and which one was chosen
docs/artefacts/	The AI 208 report (markdown + docx), deck outline, 15 viva answers, three-minute demo script, and a notebook that re-runs the numbers
scripts/red_team.py	The 34 attacks, run inside make check

Limitations

Stated here rather than discovered by a reader.

• Footfall is generated. No public hourly footfall series exists for any Dubai café. What is not invented is the evaluation: the forecaster is scored against a seasonal-naive baseline on held-out data, and a model that cannot beat "same hour last week" is not used.
• Event dates are placed, not confirmed. Visit Dubai returns 403 to every non-browser client and no redistributable feed exists. The series, venues and calendar windows are real; the dates of a given edition sit inside the established window and carry date_confidence: annual_window.
• Islamic holidays are calculated. u.ae states they are set by moon sighting, so every such row carries one day of uncertainty.
• School breaks are approximate windows. KHDA's calendar page redirects to a host whose certificate does not verify.
• Eight of eleven clauses are cited by section, not quoted. The source documents are verified and the three SIDRA-authored clauses are quoted. The external ones are not, because the Codex PDFs return 403 to any scripted client — the same wall Visit Dubai puts up. Those rules carry clause_verified: false, the generated brand PDF prints "clause unverified" beside each, and no clause text is written from memory. A citation that looks verified and is unsourced is worse than one that admits what it is.
• Weather is a coarse grid. ERA5 at roughly 11 km, so the four sites do not each get their own station.
• Allocator elasticities are assumed. No promotion has run, so there is nothing to fit them to. Every response carries assumed: true.
• Synthetic control cannot fully control for weather here. With four sites and one uniquely weather-elastic, the treated unit is inside the donors' hull on level and outside it on elasticity. The residual bias is measured on a placebo-in-time window and reported rather than absorbed.
• A bearer token is usable by whoever holds it. Admin is proved by a signed token now rather than claimed in a header, but a stateless credential cannot tell its holder from its owner. Lifetimes default to eight hours and /admin/tokens/revoke refuses an id immediately, though that set is process memory and clears on restart.
• Whether the live instance has an Admin is a deployment choice. With no signing secret configured the capability is absent rather than open, and the kill switch cannot be demonstrated against the public URL; /admin/roles answers which state the instance is actually in rather than leaving this paragraph to go stale. Either way an anonymous caller is a Viewer, and the live checks assert that rather than asserting the mode.

Not advice

MAWSIM produces a marketing plan and a compliance opinion for a fictional brand as coursework. It is not legal advice, not regulatory clearance, and not a substitute for real customer research. Its persona panel simulates reactions; it does not observe them.