Changelog

All notable changes to meridian-tools are documented in this file.

The format is based on Keep a Changelog.

[Unreleased]

[0.3.0] — 2026-04-24

Changed

  • CLI single source of truth — runme.py now delegates directly to meridian_tools.cli, removing duplicate root-level argument parsing.
  • Typed runner state — Pipeline orchestration now uses PipelineContext for shared stage state.
  • Shared posterior sampling — Runner posterior sampling keyword mapping is centralized in one helper.
  • Lifecycle comparison schema — Run comparison rows are generated from declarative comparison field descriptors.
  • Meridian compatibility pin — The package pins google-meridian[schema]==1.5.3, and log-likelihood reconstruction refuses unvalidated Meridian versions.
  • Static analysis tooling — Development extras now include mypy, and Ruff enables additional complexity, simplification, and Ruff-specific rule families.

Fixed

  • Optimized Python safety — Validation helpers now use explicit exceptions instead of assert for runtime invariants.
  • Shared confidence validation — Response curve and optimisation configs share one confidence_level validator.
  • Export coercion documentation — NetCDF attribute coercion now documents its input-to-output type mapping.

[0.2.0] — 2026-04-07

Added

  • Docs site build — Hugo-based website documentation under docs-site/, generated from the repository Markdown set by docs-site/build_content.py.
  • Manifest v3 provenance — Explicit input_data_provenance capture for stored runs and lifecycle refresh or compare workflows.
  • Typed failure boundaries — ConfigPreflightError, ValidationExecutionContractError, and PipelineRunFailure distinguish wrapper-owned preflight, validation contract misuse, and post-directory runtime failures.
  • Bounded live verification — An opt-in Meridian real-fit smoke route gated behind MERIDIAN_TOOLS_ENABLE_REAL_FIT=1.
  • Module-path CLI contract — Explicit support and regression coverage for python -m meridian_tools.cli ....

Changed

  • Shared launch flow — meridian-tools and the repo-root runme.py launcher now share one launch flow for config loading, preflight checks, progress reporting, and terminal success or failure output.
  • Packaged demo assets — Bundled demo configs and datasets are resolved from packaged _demo_data, so demo runs work from installed wheels as well as source checkouts.
  • Default demo fit mode — Bundled demos now default to full-sample fits (validation.strategy: none), so loo_summary.json and waic_summary.json are generated by default and 10_validation is recorded as skipped.
  • Refresh contract — Stored-run refresh now reloads from the saved resolved config while preserving the original source config copy in run metadata.
  • Lifecycle compare semantics — Compare now distinguishes legacy runs without dataset provenance from real dataset changes.
  • Documentation layout — Public documentation is reorganised under docs/ into getting-started, guides, reference, concepts, and project sections.

Fixed

  • Structured public entrypoint failures — Missing or invalid config paths in public entrypoints now produce structured failure output instead of raw Python tracebacks unless --traceback is used.
  • Relative-path refresh — Refreshing a stored run with relative data.path input no longer depends on the original source config location remaining present on disk.
  • Partial-run failure reporting — Failed runs that already created an output directory now report the concrete run directory, manifest path, and failing stage through the CLI and runme.py.
  • Docs-site theme resolution — Hugo builds resolve the Relearn theme through a pinned module dependency instead of requiring a local theme checkout.

[0.1.0] — 2026-04-02

Added

  • Typed YAML configuration — Pydantic-validated config with extra="forbid" strictness for all sections: project, data, model_spec, fit, validation, exports, response_curves, optimisation.
  • Staged pipeline runner — Sequential execution through 00_run_metadata, 10_validation, 20_model_fit, 30_model_assessment, 40_decomposition, 60_response_curves, 70_optimisation with manifest persistence after each stage.
  • Validation orchestration — blocked_tail and rolling_origin time-series validation strategies with auto-generated holdout masks. Authored holdout passthrough through model_spec.kwargs.holdout_id.
  • Diagnostics bundling — diagnostics_bundle.json manifest with optional predictive_accuracy.csv and review_summary.json exports.
  • Bayesian model selection — Compatibility-aware LOO and WAIC computation through ArviZ, with automatic log-likelihood reconstruction for fitted Meridian models. Graceful degradation for incompatible runs through structured ModelSelectionError with reason codes.
  • Response curves export — Configurable spend multiplier grid with NetCDF and CSV outputs.
  • Optimisation export — Fixed-budget and relative-budget optimisation with full artefact set including allocation charts.
  • Plot exports — PNG plot artefacts through Altair/vl-convert for model fit, diagnostics, decomposition, response curves, and optimisation stages.
  • Lifecycle management — load_run_record, list_run_records, build_refresh_run_config, compare_run_records for post-run analysis and reproducible refresh workflows.
  • CLI — meridian-tools run and meridian-tools demo subcommands with lightweight imports for fast startup.
  • Bundled demos — timeseries and geo_panel reference workflows with packaged data and configs.
  • Manifest versioning — Support for manifest versions 0, 1, and 2 with backward-compatible deserialisation.
  • Comprehensive test suite — 218 tests across 15 test files covering configuration, validation, pipeline execution, exports, diagnostics, model selection, lifecycle, and demos.