YAML Configuration

The pipeline runner reads the same YAML model specification used by build_mmm_from_yaml(...), then adds a small set of runner-specific conventions for data loading, prior-sensitivity planning, optional AI advisor guidance, optional blocked holdout validation, and Stage 70 optimisation.

The reference is split across three pages:

YAML Model Specification covers the core modelling blocks, the named estimator presets, additive effects, holidays and original-scale contribution variables.
YAML Runner Settings covers data loading, Stage 20 fitting, attached inference data, Stage 70 optimisation and Stage 35 blocked holdout validation.
YAML Advanced Blocks covers prior_sensitivity, ai_advisor and the diagnostics gate profile.

This page lists the root keys, the minimal configuration, the runner-only boundary, override precedence and common pitfalls.

Root keys

Key	Required	Documented in	Used for
`data`	Yes	Runner settings	Supply `data.date_column` and dataset paths unless paths are overridden through `PipelineRunConfig`
`target`	Yes	Model specification	Define the target column and business target type
`estimator`	No	Model specification	Declare a named estimator preset; `time_series`, `fe`, and `cre` are currently released
`dimensions`	No	Model specification	Declare panel-dimension columns such as `geo` or `brand`
`media`	Yes	Model specification	Define channel/control columns and transform types
`scaling`	No	Scaling and preprocessing	Configure target/channel scaling rules
`effects`	No	Model specification	Append additive effects in YAML order before `build_model(...)`
`priors`	No	Priors and configuration	Override model-level priors and prefixed transform priors
`fit`	No	Runner settings	Default sampler settings for Stage 20 fitting
`holidays`	No	Model specification	Add holiday events before model build
`original_scale_vars`	No	Model specification	Add original-scale contribution variables before fitting
`inference_data`	No	Runner settings	Attach existing `InferenceData` when the file exists
`prior_sensitivity`	No	Advanced blocks	Write a pre-fit scenario plan for prior robustness checks
`ai_advisor`	No	Advanced blocks	Write privacy-safe AI advisor guidance before model fitting
`validation`	No	Runner settings	Enable optional Stage 35 blocked holdout validation
`optimization`	No	Runner settings	Enable Stage 70 budget optimisation
`diagnostics`	No	Advanced blocks	Override Stage 50 runner diagnostics thresholds
`calibration`	No	Calibration	Post-build calibration under the selected estimator operation gates

Minimal runner config

data:
  dataset_path: dataset.csv
  date_column: date

target:
  column: revenue
  type: revenue

estimator:
  type: time_series

media:
  channels: [channel_1, channel_2]
  adstock:
    type: geometric
    l_max: 4
  saturation:
    type: logistic

fit:
  draws: 1000
  tune: 1000
  chains: 4
  cores: 4
  random_seed: 42

Relative paths in YAML are resolved relative to the YAML file’s directory.

Runner-only blocks

diagnostics is runner-only. The structured pipeline reads it, but build_mmm_from_yaml(...) still validates only the public MMM model schema.

prior_sensitivity and ai_advisor are also runner-only. They are consumed by the structured pipeline before model fitting and stripped before the public MMM YAML builder validates the model specification.

validation is also runner-only. The structured pipeline reads it for Stage 35 blocked holdout scoring, but the public MMM YAML builder never sees it.

Override precedence

For the runner, precedence is:

Setting	Higher precedence	Lower precedence
Combined dataset path	`dataset_path` / `--dataset-path`	`data.dataset_path`
Split CSV paths	`x_path`, `y_path` / `--x-path`, `--y-path`	`data.x_path`, `data.y_path`
Holiday CSV path	`holidays_path` / `--holidays-path`	`holidays.path`
Sampler settings	`PipelineRunConfig` or CLI overrides	`fit`
Target column for CSV loading	`target_column` / `--target-column`	`target.column`, then `"y"`
Diagnostics thresholds	`diagnostics.thresholds`	retained Stage 50 defaults

Common pitfalls

Using Parquet paths in the pipeline data block. The runner data loader reads CSV only.
Providing only one of data.x_path or data.y_path.
Mixing the preferred horizon-based optimization.budget block with the legacy per-period optimization.total_budget field.
Assuming diagnostics is part of the public MMM builder schema. It is a runner-only block.
Assuming inference_data.path skips Stage 20 fitting. It does not.
Forgetting that relative paths are resolved from the YAML file directory, not from the shell working directory.