# Polleo Demand — Demo Bundle
A self-contained demonstration of the Polleo Demand forecasting & S&OP tool.
Every piece of data in this bundle is **synthetic** — 50 fictional SKUs
("DEMO0001 … DEMO0050"), invented categories, fabricated sales history,
made-up KAM names. No real company data is included.
---
## What's in the bundle
```
Demo/
├── README.md ← you are here
├── requirements.txt ← Python dependencies
├── Start_Demo.bat ← Windows one-click launcher
├── start_demo.sh ← macOS / Linux launcher
├── generate_demo_data.py ← (re)generates ./data/* dummy CSVs
├── build_initial_forecast.py ← runs forecast engine on dummy data
├── app.py ← main Streamlit app
├── forecast_engine.py ← StatsForecast + GBR engine
├── update_sales.py ← weekly sales import + clean
├── recalc_uplift_erp.py ← ERP-driven uplift calculator
├── build_erp_promo.py ← builds erp_promo_calendar.csv
├── run_backtest.py ← walk-forward backtest
├── slack_agent.py ← Slack template distribution (disabled in demo)
├── compute_xyz.py ← ABC/XYZ classifier
├── constants.py ← centralised guardrails / thresholds
├── week_utils.py ← ISO-week helpers
├── .streamlit/config.toml ← demo theme (light blue/grey palette)
├── docs/ ← Word documents
│ ├── Demo_Quick_Notes.docx (English — start here)
│ ├── 01_Kratki_Vodic_Workflow.docx (Croatian)
│ ├── 02_Arhitektura_Podataka.docx (Croatian)
│ └── 03_Logika_Forecast_i_Supply.docx (Croatian)
└── data/ ← all dummy CSVs + pre-baked forecast xlsx
```
---
## Requirements
* **Python 3.12** (recommended). Python 3.10 / 3.11 also work.
**Do NOT use 3.14** — `scipy` has no wheels yet.
* ~500 MB free disk for the virtual environment + dependencies.
* Modern browser (Chrome / Edge / Firefox).
* No internet access required after first install.
* No database, no Docker, no cloud setup.
---
## Quick start (Windows)
1. Install Python 3.12 from .
Tick **"Add Python to PATH"** during install.
2. Unzip this bundle anywhere.
3. Double-click **`Start_Demo.bat`**.
4. The first run will:
* install dependencies (~2 min),
* generate dummy CSVs (~5 sec),
* build the initial forecast workbook (~60 sec, only first time),
* open the app in your browser at .
5. Subsequent launches skip setup and start instantly.
The demo uses a light blue/grey theme (set in `.streamlit/config.toml`)
to make it visually distinct from the production tool.
To stop: close the browser tab and press `Ctrl+C` in the launcher window.
## Quick start (macOS / Linux)
```bash
cd Demo
chmod +x start_demo.sh
./start_demo.sh
```
Same behaviour as the Windows launcher.
## Manual install (if the launcher fails)
```bash
python3 -m pip install -r requirements.txt
python3 generate_demo_data.py # writes Demo/data/*.csv
python3 build_initial_forecast.py # writes data/Polleo_Demand_Plan.xlsx
python3 -m streamlit run app.py
```
---
## What you can try
The left sidebar has 15 pages. The most representative tour:
1. **Dashboard** — high-level KPIs across the dummy portfolio.
2. **Update sales** — does nothing destructive in the demo; the
`data/sales_clean.csv` is already there.
3. **Run forecast** — recomputes the 13-week forecast from
`data/sales_clean.csv` using StatsForecast. Takes ~30–60 seconds.
4. **Demand planning** — tier filter (Gold / Silver / Bronze), per-SKU
forecast vs run-rate, planner-factor adjustments.
5. **VP input / MP input** — pre-populated with example KAM commitments.
6. **Revenue** — €-projection chart by category and channel.
7. **Forecast accuracy** — backtest results pre-loaded for the last 8
weeks. Try the "Apply Planner Factor" toggle.
8. **Top 30 watchlist** — the SKUs most likely to break next week.
9. **S&OP meeting** — executive view, end of the cycle.
10. **Supply — Stock projection** — stock × forecast × incoming over
13 weeks. Uses the dummy `stock.csv`, `incoming_supply.csv`,
`supply_master.csv`.
The KAM Inputs / Slack tab is included but **Slack distribution is
disabled** (no token in `data/kam_cm_config.json`). Template generation
and "Combine collected files" still work locally — generate templates,
fill them in Excel, upload them back via the **Base inputs** tab.
---
## Regenerating the dummy data
```bash
python generate_demo_data.py
```
Overwrites everything in `./data/`. Random seed is fixed (42), so the
output is reproducible. Edit the script if you want different SKU
counts, categories, or noise levels.
---
## Anonymisation guarantees
The data generator never reads any external file or environment. All
strings (SKU codes, product names, category names, KAM names, supplier
names) are hard-coded in `generate_demo_data.py`. The 8 categories are
real-world industry buckets (proteins, supplements, fitness gear) but
do not correspond to any specific retailer's catalogue. The 4 KAM
buyer names ("Konzum, Spar, DM, Kaufland") are public retail chains in
the region — replace them in `data/kam_cm_config.json` if even those
should be neutral for your demo audience.
---
## Documentation
The `docs/` folder contains three Croatian-language Word documents:
* **01 — Kratki vodič / Workflow** — what to click, when, why.
* **02 — Arhitektura podataka** — file layouts, pipeline, dependencies.
* **03 — Logika forecast i supply** — model details, guardrails, FA
methodology.
These describe the production system. Everything described there
applies to the demo, except: the demo has no Slack integration,
no real ERP feed, no cost-imputation tool runs. All other pages are
fully functional against the dummy data.
---
## Troubleshooting
| Problem | Fix |
| --- | --- |
| `pip install` fails with scipy error | You're on Python 3.14. Install 3.12 instead. |
| Browser doesn't open | Visit manually. |
| Port 8501 in use | `python -m streamlit run app.py --server.port 8502` |
| "No forecast accuracy data" | Click **Run walk-forward backtest** on the FA page, or `python run_backtest.py`. |
| Want fresh dummy data | Delete `data/`, then run `python generate_demo_data.py`. |
| Slack tab errors | Expected — the demo has no token. Other tabs work. |
---
## Licensing
This demo bundle is **for evaluation only**. Do not redistribute or use
in production without written permission from the project owner.