Versioning & Changelog
The MMM Framework is at version 0.1.0 — a pre-1.0 release. The mathematical foundations and core API are intentionally stable, but the surface area is still evolving. This page tracks where we are and what to expect.
Pre-1.0: read before depending
Public API may have backwards-incompatible changes between minor versions until 1.0.
Pin a specific version (mmm-framework==0.1.0) for production use, and
review the release notes before upgrading. Once 1.0 ships, the framework will follow
semantic versioning strictly.
API Stability by Module
Different parts of the framework have matured at different rates. Use this as a guide for what to depend on:
Core modeling
BayesianMMMMMMResults/PredictionResults- Builders (
ModelConfigBuilder, etc.) config(Pydantic dataclasses)- Adstock, saturation, seasonality, trend transforms
MFFLoader/ data loading
Active surface
reporting(charts, extractors, generator)analysis(counterfactual, marginal)serialization(MMMSerializer)- FastAPI endpoints (
api/) - React frontend (
frontend/)
Subject to change
mmm_extensions(NestedMMM, MultivariateMMM, CombinedMMM)dag_model_builder- Excel config workflow
- Streamlit UI (legacy)
Versioning Policy
Until 1.0:
- Patch (
0.1.x) — bug fixes, doc updates, internal refactors. Safe to upgrade. - Minor (
0.x.0) — new features. May contain breaking changes to experimental modules. Stable APIs preserved on a best-effort basis with deprecation warnings where possible. - Major (
x.0.0) — reserved for the 1.0 release, which will lock in the public API contract.
After 1.0, the project will follow SemVer strictly: patches are bug fixes only, minors add backward-compatible features, and majors are reserved for breaking changes.
Release Notes
For ongoing release tracking, see the GitHub Releases page. The history below summarises the current version.
First public release of the MMM Framework. Includes:
- Bayesian MMM core (
BayesianMMM) extending PyMC-Marketing with hierarchical specs, configurable adstock/saturation, and reproducible model serialization - Fluent builders for model, channel, and variable configuration
- MFF (Master Flat File) data loader with validation
- Counterfactual and marginal analysis utilities
- HTML report generator with Plotly charts and design-token theming
- Extension models (NestedMMM, MultivariateMMM, CombinedMMM) — experimental
- FastAPI service + ARQ worker for async job execution
- React (TypeScript) frontend; legacy Streamlit UI retained
- Sphinx-generated API reference + this static documentation site
Contributing
Bug reports, feature requests, and pull requests are welcome on GitHub. Please open an issue before submitting a substantial PR so we can discuss scope.
For questions about the methodology, the FAQ is a good starting point; for the underlying math, the Bayesian Workflow and Causal Inference guides cover most of the foundations.