Module 3 — Historical KPIs

File: modules/module3.py

For each (platform, goal) active in Module 2, Module 3 collects:

• platform_budgets[platform] — £ historically spent
• platform_kpis[platform][var] — value per canonical KPI variable
• module3_data[platform]["historical_days"] — days of history
• module3_data[platform]["kpi_observations"][var] — list of period-by-period observations (optional, drives data-driven confidence bands)

The "canonical KPI variable" for each (platform, goal) comes from core/kpi_config.py. See KPI-Catalogue for the full table.

Two entry paths

Manual — form fields per KPI. Use when you have summary numbers from a spreadsheet or your head.

CSV import — for every supported platform, drop the platform's standard export file. The parser sniffs encoding, delimiter, and totals rows; composes canonical KPIs from raw columns with a documented rationale per platform; returns a CSVParseResult with parsed values and a per-component audit trail. See CSV-Import-Reference.

What historical_days controls

This number is the engine's prior on how trustworthy each platform's data is. Two downstream effects:

1. Shrinkage in Module 5. Short-history platforms are pulled toward the cross-platform mean (James-Stein-style). A 7-day history gets less weight on its own productivity than a 365-day history.
2. Confidence bands in Module 6. When no kpi_observations exist, the band defaults to 0.30 × √(30 / historical_days). A 90-day history yields a ~17% band; 7 days yields ~62%.

What kpi_observations are

Per-period values (e.g. weekly leads for the last 12 weeks). When ≥3 observations exist for a KPI, Module 6 uses the actual sample CV as the forecast band — the engine prefers true noise over a heuristic. This is the only path to a band tighter than the window-scaled prior.