Skip to content

Getting Started

Jump to bottom
Hoda Rezvanjoo edited this page May 28, 2026 · 1 revision

Local install

git clone https://github.com/Hoda834/digital-budget-optimisation-engine.git
cd digital-budget-optimisation-engine
pip install -r requirements.txt
streamlit run app.py

The app opens at http://localhost:8501. PuLP ships with the CBC solver, so no separate solver install is needed. Python 3.11 is the tested target (runtime.txt); 3.10+ generally works but isn't CI-tested.

Cloud version

Hosted at https://digital-budget-optimisation-engine.streamlit.app/. It deploys from main; pushes redeploy automatically. If you see a stale error after a fix has merged, use Manage app → Reboot app and hard-refresh.

Your first plan in two minutes

  1. Objectives & budget. Pick one or more objectives, enter a budget (e.g. £50,000), enter a campaign duration in days. Skip the advanced boxes the first time.
  2. Platforms. Tick 3–5 platforms. For each, drag the active objectives into priority 1 / 2 — this tells the engine "Facebook is best for engagement, second-best for awareness."
  3. Historical KPIs. Either type in budget + KPI values per platform, or upload the platform's standard CSV export. One row per platform-goal pair you selected.
  4. Policy. Leave defaults to start. Optional: per-platform minimum spend, per-goal minimum budget.
  5. Run. You'll get a results report with three scenarios, a recommended split, forecasts with confidence bands, a confidence score, and a Plan A / Plan B comparison.

Verifying the install without the UI

PYTHONPATH=. python tests/behavioural_check.py

Runs ~10 realistic end-to-end scenarios (B2B SaaS, leads-only, engagement-only, with and without goal values, with and without test-and-learn reserve, with and without seasonality) and prints the full M1→M7 output for each. If this passes, the engine works; if the UI breaks afterward, the bug is in app.py, not the core.

pip install pytest && pytest -q

Runs the full 141-case suite in ~30 seconds. The same command runs on every push and PR via GitHub Actions.

Repository layout

Path Purpose
app.py Streamlit UI + wizard orchestration
core/wizard_state.py Single source of truth for user inputs
core/kpi_config.py Built-in + custom platform KPI catalogue
core/csv_import.py CSV parsing + KPI composition
modules/module1..7.py One module per decision layer
docs/ Long-form design notes
tests/ pytest suite + behavioural smoke check

Clone this wiki locally