A transparent analytics path from data contracts to budget decisions.
The project is structured as a reusable Python package plus a Streamlit analyst interface, with clear, independently testable boundaries between source validation, model diagnostics, evidence calibration, and budget planning. That separation is what makes the methodology legible and the engine reusable.
Current workflow
Source Contracts
Weekly schema, connector templates, CSV validation, and source diagnostics.
Modelling Layer
Baseline econometrics, MMM transformations, holdouts, uncertainty, and Bayesian priors.
Evidence Layer
Lift-test uploads, quality scoring, approved-only calibration, and experiment-informed priors.
Planning Layer
Response curves, profit-aware scenarios, constrained optimisation, and executive summaries.
Reusable code structure
| Module | Responsibility |
|---|---|
data/connectors.py |
Connector templates and validation for commerce, analytics, paid media, CRM, affiliate, influencer, display, and external-control exports. |
data/assembly.py |
Connector-to-weekly assembly into the MMM-ready schema. |
data/diagnostics.py |
Source coverage and data-quality checks for assembled connector data. |
analytics.py |
Dashboard KPIs, channel summaries, promotion summaries, and readiness checks. |
modeling.py |
Baseline econometric model and holdout diagnostics. |
mmm.py |
Adstock, saturation, MMM foundation model, contribution, ROI, and response curves. |
uncertainty.py and bayesian.py |
Coefficient simulation, posterior intervals, priors, and predictive diagnostics. |
calibration.py |
Lift-test templates, evidence governance, and experiment calibration. |
budget.py |
Budget scenarios, gross-margin planning, and constrained allocation optimisation. |
governance.py |
Recommendation readiness gates for model fit, profit impact, spend movement, history, and evidence. |
reporting.py |
Deterministic executive summaries, caveats, downloadable reports, and machine-readable run manifests. |
artifacts.py |
Local artifact registry for persisted reports, manifests, CRM readouts, launch calendars, and learning records. |
Deployment shape
GitHub Pages
Static product documentation site served from the docs/ folder.
Streamlit Community Cloud
Interactive dashboard entrypoint at streamlit_app.py.
GitHub Actions
Automated Ruff linting and Pytest checks on push and pull request.
Out of scope
This is a reference implementation, not a hosted product. A real deployment on private company data would need authentication, role-based access, governed storage, warehouse connectors, and release provenance. All of that is deliberately left out here.
Where the modelling lives
Transformations
Geometric adstock and Hill saturation in mmm.py, with time-aware holdout validation.
Uncertainty
Coefficient Monte Carlo in uncertainty.py and a conjugate Bayesian layer in bayesian.py.
Calibration
Geo-lift / conversion-lift evidence, quality scoring, and calibration factors in calibration.py.
Decisions
Marginal, constrained budget optimisation in budget.py and readiness gates in governance.py.
methodology.md documents the methodology behind each of these: adstock, saturation, priors, holdout and geo-lift calibration, and how each is validated.