Supported Scenario Surface

Use ammm.scenarios for statistical scenario planning. ammm does not include a dashboard, UI launcher or dashboard compatibility facade.

Entry points

Entry pointPurpose
ScenarioPlanner(mmm)Evaluate scenarios against a fitted model
load_planner_run_context(results_dir)Rebuild a saved fitted run
WorkspaceServicePersist drafts, evaluations and revisions locally
run_scenario_recipe(...)Evaluate and retain a versioned recipe
python -m ammm.scenarios --results-dir <run> --recipe <yaml>Run a recipe from the command line

The statistical implementation is also exposed through ammm.scenario_planner.

PanelMMM.compute_incrementality(...) is a separate historical Python API. It does not add scenario recipe fields, payload fields, cache entries or workspace records.

Estimator restrictions

Time-series scenarios support historical, manual and fixed-budget optimised plans where the corresponding operation contracts are met. FE and CRE support historical and manual media-contribution scenarios for complete fitted-unit panels. They do not support unseen units, calibration or fixed-budget optimisation. CRE interventions retain the fitted between-unit summaries. Named RE remains release-gated.

See the estimator support matrix.

Fitted-run inputs

Version 3.3.2 requires a fitted run created with the current model identity. Use the original release for earlier saved runs. See the upgrade guide and saved-model checks before reconnecting an application to retained runs.

A saved run needs run_manifest.json and its fit-stage idata artefact. The loader reconstructs the scenario model only from the retained fitted model. It does not read the dataset or rebuild the graph from configuration. A missing or incompatible retained model fails before scenario evaluation; ammm never falls back to mutable external training inputs.

Configuration is retained as provenance and workflow context. The loader reports it in this order:

  1. 00_run_metadata/config.resolved.yaml.
  2. 00_run_metadata/config.original.yaml.
  3. The copied configuration under 00_run_metadata/.
  4. The manifest’s original config_path.

External data paths in those files do not affect a complete retained fit. A complete run with in-run metadata and its fit artefact remains usable after the original dataset or configuration has moved or been removed.

External application contract

A retained recipe writes scenario_payload.json. Consumers must:

  1. Validate contract_version against SCENARIO_CONTRACT_VERSION.
  2. Preserve totals, channels, contributions_over_time, allocations and metadata.
  3. Check the validation record, estimator manifest and artefact checksums.
  4. Preserve the declared scale, horizon, history policy and estimand.
  5. Describe FE/CRE results as posterior media contributions. They are not total outcomes, profits, causal identification evidence or model approval.

The library owns the statistical contract. The separate wrapper owns presentation, authentication, deployment and application persistence.

Local workspace persistence

Path under a fitted runContents
scenario_planner/workspaces/Workspace records and manifests
scenario_planner/cache/Evaluation cache
scenario_planner/exports/Retained export bundles
scenario_planner/recipes/Immutable recipe evidence

WorkspaceService runs synchronously by default. Its job interfaces allow custom orchestration; the library does not provide a hosted job service.