Module 1 — Objectives

Budget, Currency, Carve‐out, Seasonality

File: modules/module1.py · Result: Module1Result

Module 1 validates the highest-level campaign inputs and stamps them onto WizardState. Nothing else advances until Module 1 is finalised — a deliberate flow-state constraint enforced by FlowStateError rather than implicit ordering.

Inputs

Field	Required	Notes
selected_objectives	✓	Subset of {aw, en, wt, lg}
total_budget	✓	Positive, ≤ MAX_REASONABLE_BUDGET (1 × 10⁹)
currency	—	One of GBP / USD / EUR
campaign_duration_days	—	Positive integer
goal_value_per_unit	—	{goal: £ per KPI unit}
test_and_learn_pct	—	In [0, 0.5]
seasonality_index	—	{goal: multiplier}, clamped to [0.1, 10.0]

Why goal value weights matter

When empty, system goal weights are derived from priority-frequency across platforms — a rank-based heuristic, useful when unit values aren't known.

When set, weights come from value × expected_productivity — i.e. expected return per £ allocated to that goal. This is utility- weighted optimisation, almost always more defensible than rank counting if you have any sense of what one lead or one impression is worth.

What the test-and-learn reserve does

Skims that fraction off the top of every scenario's budget before the LP sees it. The held-back amount is surfaced separately in the report — never silently merged with the optimised allocation. The LP only optimises (1 − pct) × total; the cap at 0.5 guarantees the LP always has something to allocate.

This matches established strategist practice (10–15% reserved for new audiences or creative tests) and keeps experimentation budget visible rather than buried.

What seasonality_index does

A per-goal multiplier on productivity, applied at two points to keep allocation and forecast aligned:

• Module 5 multiplies r_{p,g} by seasonality_index[g] before the LP runs.
• Module 6 multiplies count-KPI forecasts by the same factor afterwards.

1.0 means no adjustment, >1 means auctions expected to be cheaper than historical, <1 more expensive (December CPM inflation, competitor surge, etc.).