meridian_tools.config

Configuration models and YAML loading for meridian-tools.

Module: meridian_tools.config

Functions

`load_yaml_config`

def load_yaml_config(path: str | Path) -> MeridianToolsConfig

Load and validate a meridian-tools YAML file.

Parameters:

path — Path to the YAML configuration file.

Returns: A validated MeridianToolsConfig instance.

Raises: pydantic.ValidationError if the YAML content does not match the schema.

Example:

from meridian_tools.config import load_yaml_config

config = load_yaml_config("project.yml")
print(config.project.name)
print(config.data.path)
print(config.validation.strategy)

Classes

`MeridianToolsConfig`

class MeridianToolsConfig(BaseModel)

Full YAML configuration for one meridian-tools run. This is the top-level model returned by load_yaml_config.

Attribute	Type	Default
`project`	`ProjectConfig`	`ProjectConfig()`
`data`	`CsvDataConfig`	required
`model_spec`	`ModelSpecConfig`	`ModelSpecConfig()`
`fit`	`FitConfig`	`FitConfig()`
`validation`	`ValidationConfig`	`ValidationConfig()`
`exports`	`ExportsConfig`	`ExportsConfig()`
`response_curves`	`ResponseCurvesConfig	None`
`optimisation`	`OptimisationConfig	None`

`PipelineRunConfig`

@dataclass(frozen=True)
class PipelineRunConfig

Runtime options that sit outside the YAML file. Passed to run_pipeline.

Attribute	Type	Default	Description
`config_path`	`Path`	required	Path to the YAML config file.
`output_dir`	`Path`	`Path("runs")`	Directory for run output.
`run_name`	`str	None`	`None`
`validation_spec`	`ValidationRunSpec	None`	`None`
`apply_run_name_suffix`	`bool`	`True`	Whether to append validation-aware suffixes to the run name.
`source_config_path`	`Path	None`	`None`

`ProjectConfig`

class ProjectConfig(BaseModel)

Attribute	Type	Default
`name`	`str`	`"meridian-project"`

`CsvDataConfig`

class CsvDataConfig(BaseModel)

CSV loader configuration compatible with Meridian’s CsvDataLoader.

Attribute	Type	Default
`path`	`Path`	required
`kpi_type`	`Literal["revenue", "non-revenue"]`	`"revenue"`
`coord_to_columns`	`dict[str, Any]`	required
`media_to_channel`	`dict[str, str]	None`
`media_spend_to_channel`	`dict[str, str]	None`
`reach_to_channel`	`dict[str, str]	None`
`frequency_to_channel`	`dict[str, str]	None`
`rf_spend_to_channel`	`dict[str, str]	None`
`organic_reach_to_channel`	`dict[str, str]	None`
`organic_frequency_to_channel`	`dict[str, str]	None`

`ModelSpecConfig`

class ModelSpecConfig(BaseModel)

Attribute	Type	Default
`kwargs`	`dict[str, Any]`	`{}`

`FitConfig`

class FitConfig(BaseModel)

Sampling configuration for Meridian posterior fitting.

Attribute	Type	Default
`sample_prior_draws`	`PositiveInt	None`
`n_chains`	`PositiveInt	list[PositiveInt]`
`n_adapt`	`PositiveInt`	`500`
`n_burnin`	`PositiveInt`	`500`
`n_keep`	`PositiveInt`	`1000`
`seed`	`int	list[int]
`max_tree_depth`	`PositiveInt`	`10`
`max_energy_diff`	`float`	`500.0`
`unrolled_leapfrog_steps`	`PositiveInt`	`1`
`parallel_iterations`	`PositiveInt`	`10`

`ValidationConfig`

class ValidationConfig(BaseModel)

Validation and holdout orchestration settings.

Attribute	Type	Default
`strategy`	`Literal["none", "blocked_tail", "rolling_origin"]`	`"none"`
`holdout_size`	`PositiveInt	None`
`initial_train_size`	`PositiveInt	None`
`test_size`	`PositiveInt	None`
`step_size`	`PositiveInt	None`
`max_splits`	`PositiveInt	None`

See the validation guide for cross-field validation rules.

`ExportsConfig`

class ExportsConfig(BaseModel)

Attribute	Type	Default
`use_kpi`	`bool`	`False`
`batch_size`	`PositiveInt`	`1000`
`export_predictive_accuracy`	`bool`	`True`
`export_review_summary`	`bool`	`True`
`export_model_selection`	`bool`	`True`
`export_plots`	`bool`	`True`

`ResponseCurvesConfig`

class ResponseCurvesConfig(BaseModel)

Attribute	Type	Default	Constraint
`spend_multipliers`	`list[float]`	required	Non-empty, all `>= 0`
`use_posterior`	`bool`	`True`
`by_reach`	`bool`	`True`
`use_optimal_frequency`	`bool`	`False`
`confidence_level`	`float`	`0.9`	`0 < x < 1`

`OptimisationConfig`

class OptimisationConfig(BaseModel)

Attribute	Type	Default	Constraint
`start_date`	`str`	required	ISO `YYYY-MM-DD`
`end_date`	`str`	required	ISO `YYYY-MM-DD`, `>= start_date`
`budget`	`OptimisationBudgetConfig`	required
`use_posterior`	`bool`	`True`
`use_optimal_frequency`	`bool`	`True`
`confidence_level`	`float`	`0.9`	`0 < x < 1`

`OptimisationBudgetConfig`

class OptimisationBudgetConfig(BaseModel)

Attribute	Type	Default
`mode`	`Literal["fixed_total", "relative_reference_window_total"]`	required
`value`	`PositiveFloat`	required