scale-forecasting 1.0.0__tar.gz → 1.2.0__tar.gz

scale_forecasting-1.2.0/CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+All notable changes to `scale-forecasting` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+---
+
+## [1.2.0] - 2026-10-14
+
+### Added
+
+- **Open-Weight Zero-Shot Foundation Model Suite (`[models-foundation]` extra; `34 → 37` models, `12 → 13` extras):**
+  - Added `[models-foundation]` (`chronos-forecasting>=2.2`, `timesfm[torch]>=3.0`) in [`pyproject.toml`](./pyproject.toml), separated from `[models-dl]` and composed into `[models]` and `[all]`. All three models run on CPU by default (`hardware = "cpu"`, `gpu_capable = True`) in `scale_forecasting.playground` and across all 5 Python cloud runtimes (`spark`, `ray`, `vertex`, `gce`, `gke`), automatically accelerating on NVIDIA `T4`, `L4`, `A100`, or `A100_80GB` GPUs when `use_gpu = True` or `hardware = "gpu"`:
+    1. **`chronos_bolt`** ([`src/scale_forecasting/models/chronos_bolt.py`](./src/scale_forecasting/models/chronos_bolt.py)): Amazon `ChronosBoltPipeline` (`amazon/chronos-bolt-base` default; `size="small" | "mini" | "tiny"` or `@small` / `@mini` / `@tiny` variant tags), univariate zero-shot inference with native multi-quantile heads (`0.1`–`0.9`), supporting both `local` and `global` batch modes.
+    2. **`chronos2`** ([`src/scale_forecasting/models/chronos2.py`](./src/scale_forecasting/models/chronos2.py)): Amazon `Chronos2Pipeline` (`amazon/chronos-2`), supporting univariate and 3-tier covariates (`future_covariates`, `past_covariates`, `static_covariates`) across `local` and `global` modes (`cross_learning = True` in `global` mode for cross-series group attention).
+    3. **`timesfm_torch`** ([`src/scale_forecasting/models/timesfm_torch.py`](./src/scale_forecasting/models/timesfm_torch.py)): Google `TimesFM 3.0` (`google/timesfm-3.0-pytorch` default via `timesfm3.TimesFM3Forecaster` with native Variate Attention for past, future, and static covariates, plus `version="2.5"` / `timesfm_torch@v2.5` option using `timesfm.TimesFM_2p5_200M_torch` and pure-NumPy in-context Ridge regression), supporting `local` and `global` modes.
+- **BigQuery Managed Alias (`"bq_timesfm"`):**
+  - [`RunConfig._normalize`](./src/scale_forecasting/config.py) and [`models.base_model_name`](./src/scale_forecasting/models/__init__.py) accept `"bq_timesfm"` (and `"bq_timesfm@<tag>"`) as an explicit alias for BigQuery `AI.FORECAST` (`"timesfm"`), normalizing to `"timesfm"` without altering any `run_id`.
+- **Shared-Instance Default for Zero-Shot Foundation Runs (`workers = 1`):**
+  - [`effective_worker_count`](./src/scale_forecasting/engines/vertex_engine.py) keeps `workers = 1` by default when `deep_learning` runs only zero-shot `[models-foundation]` models on `vertex` or `gke` (executing sequentially on a single shared VM/pod with automatic VRAM/RAM cleanup between models), while preserving automatic per-model multi-worker expansion (`1 → len(models)`) when trained `[models-dl]` models are present.
+- **Operational Inventory & Replenishment Policy Translators (`diagnostics.py`, `sdk.py`, `playground.py`, `report.py`, `mcp.py`):**
+  - Added [`compute_inventory_policy()`](./src/scale_forecasting/diagnostics.py) and [`plot_inventory_policy()`](./src/scale_forecasting/diagnostics.py), exported at the top level of `scale_forecasting`, plus `Forecaster.inventory_policy_df(...)` / `Forecaster.plot_inventory_policy(...)`, `PlaygroundRun.inventory_policy_df(...)` / `PlaygroundRun.plot_inventory_policy(...)`, and `BakeOff.inventory_policy_df(...)` / `BakeOff.plot_inventory_policy(...)`.
+  - Translates calibrated forecast distributions (`yhat`, `yhat_lower`, `yhat_upper`) and out-of-fold backtest residuals (`backtest_oof`) into concrete per-SKU replenishment tables across **Continuous Review $(s, S)$** and **Periodic Review $(R, S)$** policies, **Cycle Service Level ($\text{CSL}$)**, **Unit Fill Rate ($\beta$ via inverse standard normal loss $G(z) = \sigma_P^{-1}(1-\beta)\mu_L$)**, and **Newsvendor Critical Fractile ($\alpha^* = c_u / (c_u + c_o)$)** targets, with **AR(1) autocorrelation-adjusted** + **stochastic lead-time ($\sigma_L$)** protection-window uncertainty ($\sigma_P = \sqrt{\sigma_{D,P}^2 + \bar{d}^2 \sigma_L^2}$), **Inventory Position ($IP = \text{on\_hand} + \text{on\_order} - \text{backorders}$)**, **EOQ / lot-sizing (`min_order_qty`, `order_multiple`)**, expected stockout units and holding/stockout cost, and per-SKU `overrides_df` support.
+  - Added a dedicated **"Inventory Policy (ROP / SS)"** interactive tab (`tab-inventory`) and `"inventory_policy"` JSON payload section in [`report.py`](./src/scale_forecasting/report.py) (wired automatically into `Forecaster.export_report()`), plus `include_inventory_policy` and `inventory_params` on the `run_playground` and `review_run` MCP tools in [`mcp.py`](./src/scale_forecasting/mcp.py).
+
+### Changed
+
+- **Cloud Worker Cache & Compilerless CUDA Hardening ([`src/scale_forecasting/models/_foundation_base.py`](./src/scale_forecasting/models/_foundation_base.py)):**
+  - `_ensure_writable_hf_cache()` and `_checkpoint_load_lock()` detect unwritable `$HOME/.cache` directories (such as YARN user `yarn` on Dataproc clusters), redirect `HF_HOME`, `HF_HUB_CACHE`, `TORCH_HOME`, `TRITON_CACHE_DIR`, and `huggingface_hub.constants` / `transformers.utils.hub` cache attributes to `<tempdir>/scale_forecasting_hf_cache`, and serialize concurrent worker weight downloads on the same host via `fcntl.flock`.
+  - `_ensure_torch_runtime_ready()` deregisters PyTorch 2.11's `('bmm', 'CUDA')` Triton JIT outer-product override (`torch._native.triton_utils.deregister_op_overrides()`) when no C compiler (`gcc` / `clang` / `cc`) is on `PATH`, dispatching `aten::bmm` directly to precompiled cuBLAS kernels; [`docker/Dockerfile`](./docker/Dockerfile) also includes `gcc` and `libc6-dev`.
+  - [`src/scale_forecasting/capacity.py`](./src/scale_forecasting/capacity.py) classifies transient GCE subnetwork contention (`400 The resource '.../subnetworks/...' is not ready`) under `_CAPACITY_MARKERS` so concurrent cluster launches automatically retry with backoff.
+
+---
+
+## [1.1.0] - 2026-10-13
+
+### Added
+
+- **BigQuery ML `ARIMA_PLUS_XREG` Exogenous Covariate & `ML.EXPLAIN_FORECAST` Explainability Parity (`native` family):**
+  - `arima_plus` ([`src/scale_forecasting/models/bigquery_native.py`](./src/scale_forecasting/models/bigquery_native.py)) now declares `supports_exog = True`, `supports_future_covariates = True`, and `supports_explainability = True`, and supports `"arima_plus_xreg"` (and `"arima_plus@xreg"`) as a first-class model entry in `RunConfig.models` and `model_params`. When `["arima_plus", "arima_plus_xreg"]` are listed together, `"arima_plus"` is automatically pinned to univariate `ARIMA_PLUS` while `"arima_plus_xreg"` normalizes to `"arima_plus@xreg"` (`ARIMA_PLUS_XREG`) for side-by-side Covariate FVA.
+  - When `features.future_covariates` (`known_future_covariates` / `exog`) is active, [`src/scale_forecasting/engines/bigquery_sql.py`](./src/scale_forecasting/engines/bigquery_sql.py) compiles `CREATE OR REPLACE MODEL ... OPTIONS(model_type = 'ARIMA_PLUS_XREG', ...)` with the exogenous regressors in `SELECT` and passes the future regressor table as the 3rd argument to `ML.FORECAST` and `ML.EXPLAIN_FORECAST`. Univariate configs and `arima_plus@univariate` ablation variants compile byte-identical `model_type = 'ARIMA_PLUS'` SQL.
+  - [`src/scale_forecasting/engines/bigquery_engine.py`](./src/scale_forecasting/engines/bigquery_engine.py) executes `ML.EXPLAIN_FORECAST` (`build_explain_forecast_query` + `extract_bqml_explanations`) to populate **Tier 1** global feature attributions (`forecast_metadata.fit_diagnostics["feature_attributions"]` across `trend`, `seasonal`, `holiday_effect`, and each `attribution_<col>` exogenous regressor) and **Tier 2** per-step forecast attributions (`forecast_predictions.explanations`).
+- **BigQuery `AI.FORECAST` (`timesfm`) Multivariate Covariate Support (`TimesFM 3.0`):**
+  - `timesfm` ([`src/scale_forecasting/models/bigquery_native.py`](./src/scale_forecasting/models/bigquery_native.py)) now declares `supports_exog = True`, `supports_future_covariates = True`, and `supports_past_covariates = True` (bringing `future_covariates`-capable models to 19 and `past_covariates`-capable models to 18).
+  - When `future_covariates` or `past_covariates` are active on `timesfm`, `bigquery_sql.py` automatically targets `model => 'TimesFM 3.0'` with `target_cols => ['y']`, feeding future covariates through the future horizon window and masking past covariates (`CAST(NULL AS FLOAT64)`) across the future window so zero-shot `AI.FORECAST` conditions on historical + future covariates without data leakage. Univariate `timesfm` and `timesfm@univariate` continue to default to `TimesFM 2.5` with `data_col => 'y'`.
+- **`model_params.arima_plus` Options & Multi-Series Guardrails:**
+  - `resolve_arima_plus_params` validates and renders `auto_arima_max_order` (`1..5`), `auto_arima_min_order` (`0..5`), `clean_spikes_and_dips`, `adjust_step_changes`, `decompose_time_series`, `holiday_region` (`str` or `list[str]`), `seasonalities`, `time_series_length_fraction`, `min_time_series_length`, `max_time_series_length`, and `trend_smoothing_window_size` into `CREATE MODEL ... OPTIONS(...)`.
+  - Explicitly rejects `forecast_limit_lower_bound` and `forecast_limit_upper_bound` with a `ConfigError` pointing to `output.floor` and `output.cap`, and rejects manual `auto_arima=False` / `non_seasonal_order` on multi-series `time_series_id_col` panels.
+- **Per-Series `ML.ARIMA_EVALUATE` & `ML.ARIMA_COEFFICIENTS` Diagnostics:**
+  - `bigquery_engine.run` executes `build_arima_evaluate_query` and `build_arima_coefficients_query` (`extract_arima_diagnostics`) on the fitted `ARIMA_PLUS` / `ARIMA_PLUS_XREG` model and populates `forecast_metadata.fit_diagnostics["arima_diagnostics"]` per `ts_id` with `non_seasonal_order` (`[p, d, q]`), `has_drift`, `aic`, `log_likelihood`, `variance`, `seasonal_periods`, `has_holiday_effect`, `has_spikes_and_dips`, `has_step_changes`, `ar_coefficients`, `ma_coefficients`, `intercept_or_drift`, and linear `xreg_weights`.
+- **Universal Time-Series Anomaly & Structural Change-Point Detection Across All 34 Models, 9 Ensembles, and Past Runs (`Forecaster`, `Registry`, `diagnostics.py`, `bigquery_sql.py`):**
+  - Added `build_detect_anomalies_query` (`ML.DETECT_ANOMALIES` for `arima_plus` / `arima_plus@xreg` and `AI.DETECT_ANOMALIES` for `timesfm`), `build_detect_change_points_query` (`ML.DETECT_CHANGE_POINTS` with gap-edge artifact filtering), pure offline `compute_anomalies` and `compute_change_points` ([`src/scale_forecasting/diagnostics.py`](./src/scale_forecasting/diagnostics.py)), and `Forecaster.detect_anomalies_df(...)` / `Forecaster.detect_change_points_df(...)` / `Registry.detect_anomalies_df(...)` / `Registry.detect_change_points_df(...)`.
+  - Adapts across all 34 models (`statistical`, `ml`, `deep_learning`, `automl`, `native`), all 9 ensembles (`ensemble_*`), `model_name="all"`, forward `actuals_df` scoring, model-free `engine="stl"`, and any historical `run_id` in the BigQuery registry without re-fitting.
+- **Semantic Versioning Charter (`MAJOR.MINOR.PATCH`):** Documented the formal versioning policy in [`AGENTS.md`](./AGENTS.md) and [`CONTRIBUTING.md`](./CONTRIBUTING.md) defining `PATCH` (`1.0.x`), `MINOR` (`1.x.0`), and `MAJOR` (`x.0.0`) boundaries and release precheck gates.
+
+### Changed
+
+- **BigQuery Query Cache Prevention (`use_query_cache=False`):** `bigquery_engine._query` now sets `QueryJobConfig(use_query_cache=False)` so `native` wall-clock runtime measurements and fresh forecast queries never hit cached results.
+- **PyPI Long-Description Mermaid Rendering (`hatch-fancy-pypi-readme`):** Configured `[tool.hatch.metadata.hooks.fancy-pypi-readme]` in [`pyproject.toml`](./pyproject.toml) so `README.md` retains its interactive ` ```mermaid ` architecture flowchart on GitHub and MkDocs while substituting the diagram with the high-resolution architecture card (`docs/assets/social_card.png`) in built wheel and sdist `METADATA` for `pypi.org`.
+
+---
+
+## [1.0.0] - 2026-10-12
+
+### Added
+
+- **Declarative Execution Contract (`RunConfig`):** One JSON/dict contract ([`src/scale_forecasting/config.py`](./src/scale_forecasting/config.py)) drives execution across Local CLI, Python SDK (`Forecaster`), Interactive Notebooks, Cloud Composer 3 DAGs (`--emit-airflow`), and Headless Cloud Batch containers, with deterministic content-addressed `run_id` and per-model `model_spec_hash` hashing ([`src/scale_forecasting/registry/ids.py`](./src/scale_forecasting/registry/ids.py)).
+- **34 Forecasting Models Across 5 Families + Multi-Instance `<base_model>@<tag>` Variants:**
+  - `statistical` (`18`): `theta`, `auto_theta`, `holtwinters`, `autoets`, `auto_arima`, `sarimax`, `tbats`, `auto_ces`, `stl_bagging`, `ucm`, `kalman`, `prophet`, `croston` (`classic`, `sba`, `tsb`), `fft`, `naive_mean`, `naive_seasonal`, `naive_drift`, `naive_moving_average`.
+  - `ml` (`5`): `lightgbm`, `xgboost`, `catboost`, `random_forest`, `regression_lags` with both `"recursive"` and `"direct"` multi-step horizon strategies and customizable target `lags`.
+  - `deep_learning` (`5`): `tide`, `tft`, `tsmixer`, `patchtst`, `neuralprophet` across `local`, `global`, and `hybrid` panel regimes.
+  - `automl` (`4`): `vertex_l2l`, `vertex_tide`, `vertex_tft`, `vertex_seq2seq` via Vertex AI Tabular Workflows and managed AutoML training jobs.
+  - `native` (`2`): `arima_plus` and `timesfm` (`AI.FORECAST`) executed natively in BigQuery SQL with SQL-enforced `output` bounds and integer rounding.
+- **21 Evaluation Metrics & Conformal Calibration:** 16 point metrics (`wape`, `smape`, `mape`, `maape`, `ope`, `mae`, `rmse`, `mse`, `rmsle`, `bias`, `mase`, `mase_seasonal`, `rmsse`, `msse`, `r2`, `cv`) and 5 interval metrics (`coverage`, `pinball`, `interval_score`, `interval_width`, `msis`), plus empirical conformal residual calibration ([`src/scale_forecasting/calibration.py`](./src/scale_forecasting/calibration.py)).
+- **7 Google Cloud Compute Runtimes & Per-Family DAG Router:** Parallel per-family job dispatch ([`src/scale_forecasting/dag.py`](./src/scale_forecasting/dag.py)) across Dataproc Serverless / Cluster / Connect (`spark`), Ray on Vertex AI or GKE (`ray`), Vertex AI CustomJob (`vertex`), self-deleting Compute Engine Single-VM (`gce`), GKE Indexed Job (`gke`), Vertex AI AutoML (`vertex_automl`), and BigQuery ML (`bigquery`), supporting CPU and NVIDIA `T4`, `L4`, `A100`, and `A100_80GB` GPUs with BigQuery Storage Read API `[start_id, end_id]` worker sharding and LPT chunk scheduling.
+- **Hierarchical Reconciliation, Smart Ensembles & Two-Tier Explainability:** All 8 Hyndman FPP3 reconciliation methods (`mint_shrink`, `mint_nonneg` active-set non-negative QP, `wls_var`, `wls_struct`, `ols`, `bottom_up`, `top_down`, `middle_out`), 9 ensemble strategies (`mean`, `median`, `trimmed_mean`, `inverse_error`, `champion`, `horizon_specialist`, `nnls`, `ridge`, `xgb`) with `top_k`, `parsimony_margin`, and `variant_policy` (`"all"`, `"best_per_base_model"`, `"primary_only"`), calibrated ensemble prediction intervals, cross-run ensembling (`ensemble_cross_runs`), and two-tier feature attributions (`feature_attributions()` and `explain()`).
+- **Forecaster Decision Workbench (`Phases G.1–G.5`):**
+  - **Physical Bounds & Quantile/Newsvendor Targets (`output`):** Scalar and per-series bounds (`floor`, `cap`, `floor_col`, `cap_col`), integer rounding (`"none"`, `"round"`, `"ceil"`, `"floor"`, `"cumulative_round"`), monotone multi-percentile fans (`output.quantiles`), and Newsvendor asymmetric cost optimization (`underage_cost`, `overage_cost`, `target_quantile`).
+  - **Pre-Fit Data Hygiene & SBC Regime Routing (`data`, `features`):** Grid regularization (`grid_policy`), `trim_leading_zeros`, X-13 `trading_days`, fold-safe outlier despiking (`outlier_policy` / `outlier_handling`), censored stockout recovery (`censored_col`), and Syntetos–Boylan–Croston demand classification (`compute_demand_profile`) with optional `regime_routing`.
+  - **Econometric Diagnostics, Scenarios, Lifecycle Governance & HTML Reports (`diagnostics.py`, `scenarios.py`, `report.py`):** Multi-baseline Forecast Value Added (`compute_fva` with Total, Covariate, Drop-One, and Pooling FVA + Harvey–Leybourne–Newbold modified Diebold–Mariano & Wilcoxon $p$-values), horizon decay (`compute_horizon_decay`), directional bias & Trigg Tracking Signal audits (`compute_bias_report`), AR(1) autocorrelation-aware temporal rollups (`rollup_time`), date-scoped promo/price scenario simulation with revenue impact (`simulate_scenarios`), realized accuracy vs. new actuals (`compute_realized_accuracy`), cross-run revision stability (`compute_revision_stability`), Top-$N$ exception triage queues (`compute_exceptions_queue`), and single-file interactive HTML/JSON executive reports (`export_report`).
+  - **Ablation Ladders & Snapshot-Verified Cross-Run Cell Borrowing (`reuse_prior_runs`):** Declarative `ablation_modes` (`cov_ladder`, `cov_by_tier`, `cov_by_column`, `cov_drop_one`, `scope_ladder`, `transform_ladder`) and server-side BigQuery cell borrowing (`ops.find_reusable_models`, `ops.borrow_model_results`) that skips cloud compute for invariant models.
+- **BigQuery Registry & Analytical SQL Views:** 4 source tables, 5 registry tables (`run_registry`, `run_jobs`, `forecast_metadata`, `forecast_predictions`, `backtest_oof`), and 5 analytical SQL views (`v_model_leaderboard`, `v_model_leaderboard_comparable`, `v_backtest_coverage`, `v_run_summary` with per-job time ledger, and `v_run_jobs`), plus surgical per-cell repair ([`src/scale_forecasting/retry_run.py`](./src/scale_forecasting/retry_run.py)) and `Registry.doctor()`.
+- **Two-Stage Terraform Infrastructure, 11 Notebooks & 42 Live Smoke Configs:** Complete bootstrap + main Terraform modules ([`terraform/`](./terraform/README.md)), 11 interactive notebooks across 4 learning tracks ([`notebooks/`](./notebooks/README.md)), and 42 live-validated smoke configurations + 4 full-breadth multi-runtime verification runs recorded in [`docs/validation.md`](./docs/validation.md).
+- **Agent-First Surfaces (`SKILL.md`, Built-in `stdio` MCP Server, JSON Schema, `llms.txt` & Cloud Shell Tutorial):** Portable Agent Skill ([`skills/scale-forecasting/SKILL.md`](./skills/scale-forecasting/SKILL.md)) with workspace auto-discovery ([`.agents/skills.json`](./.agents/skills.json) and `.agents/skills/scale-forecasting`), zero-extra JSON-RPC 2.0 MCP server ([`src/scale_forecasting/mcp.py`](./src/scale_forecasting/mcp.py)) exposing 7 `forecast://*` resources and 9 tools with `--allow-launch` safety gating, published `RunConfig` JSON Schema ([`docs/schemas/run_config.schema.json`](./docs/schemas/run_config.schema.json)), `llms.txt` / `llms-full.txt`, Google Antigravity [`plugin.json`](./plugin.json) + [`mcp_config.json`](./mcp_config.json), portable [`.mcp.json`](./.mcp.json), [`cloudshell_tutorial.md`](./cloudshell_tutorial.md), and pre-commit zero-drift synthesis ([`src/scale_forecasting/agent_surfaces.py`](./src/scale_forecasting/agent_surfaces.py)).
+
+### Changed
+
+- **Modular Dependency Extras (`pyproject.toml`):** Core `pip install scale-forecasting` installs only the pure offline forecasting layer with zero Google Cloud clients. All Google Cloud SDKs live in `[gcp]`, with composable `[notebook]`, `[spark]`, `[ray]`, `[submit]`, `[models-stats]`, `[models-trees]`, `[models-prophet]`, `[models-dl]`, `[models-automl]`, `[models]`, and `[all]` extras and actionable `MissingExtraError` guidance at every cloud and plotting entry point.
+- **Static Typing, Logging & Test Ratchet:** Added PEP 561 `py.typed` marker with zero `mypy` errors across all 181 source modules, library-safe `NullHandler` logging (`configure_cli_logging` on CLI entry points), widened Ruff lint families (`SIM`, `C4`, `PIE`, `PERF`, `RUF`, `BLE`), and enforced an 85 % offline line-coverage ratchet in CI (`4,960` offline unit tests).
+- **Python 3.11–3.12 Package Support:** `requires-python` widened from `>=3.11,<3.12` to `>=3.11,<3.13` with `3.12` classifiers and a per-interpreter CI `core-install` matrix; the cloud stack stays pinned to `3.11.15` (`.python-version`) for Spark Connect and Ray on Vertex pickle parity ([`docs/version_matrix.md`](./docs/version_matrix.md)). 3.13 waits on the `numpy<2` pin `neuralprophet` still needs.
+- **Per-Job Provisioning vs. Execution Telemetry:** `run_jobs.job_telemetry.$.platform` (`provision_s`, `execute_s`, `total_wall_s`) is stamped from one probe read of each finished Dataproc Serverless batch or Vertex `CustomJob` (`batch_telemetry.platform_phases`), and `v_run_jobs` projects it as `provision_seconds` / `execute_seconds` beside `runtime_seconds`; the Serverless header telemetry carries the same split.
+- **One BigQuery Client Factory:** Every `bigquery.Client(...)` in the package (73 sites) now goes through `registry.tables.bigquery_client`, which guards on `google.cloud.bigquery` alone via the new `errors.require_modules` so an on-cluster worker that never holds the launch clients still reaches the registry, and a core-only install gets the `[gcp]` install line instead of a `ModuleNotFoundError`.
+- **`DataConfig` Identifier Validation:** `source_table` must be `table`, `dataset.table`, or `project.dataset.table` with no backticks, whitespace, or control characters, and `ts_id_col` / `date_col` / `target_col` must be BigQuery column names — checked once at config load, where the values are interpolated into backticked SQL. No field is added, so no `run_id` moves.
+
+### Security
+
+- **HTML Report Hardening (`report.py`):** The inline `EXPLORER_DATA` JSON escapes `<`, `>`, and `&` as `\u003c` / `\u003e` / `\u0026` so a series id containing `</script>` cannot close the script block, and the fan-chart label is HTML-escaped (`escHtml`) before `innerHTML` assignment.
+- **FIPS-Safe Content Addressing:** `code_delivery` tags staged code archives with `hashlib.md5(..., usedforsecurity=False)` (a content-address, not a digest), so staging works on FIPS-enforced hosts.
+
+[Unreleased]: https://github.com/statmike/scale-forecasting/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/statmike/scale-forecasting/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/statmike/scale-forecasting/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/statmike/scale-forecasting/releases/tag/v1.0.0

{scale_forecasting-1.0.0 → scale_forecasting-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scale-forecasting
-Version: 1.0.0
+Version: 1.2.0
 Summary: Time-series forecasting on Google Cloud at any scale: one JSON configuration runs every model family on Dataproc Serverless, Ray, Vertex AI, GKE, Compute Engine, or BigQuery ML and writes forecasts and leaderboards back to BigQuery.
 Project-URL: Homepage, https://github.com/statmike/scale-forecasting
 Project-URL: Documentation, https://statmike.github.io/scale-forecasting/
@@ -10,7 +10,7 @@ Project-URL: Issues, https://github.com/statmike/scale-forecasting/issues
 Author: scale-forecasting contributors
 License: Apache-2.0
 License-File: LICENSE
-Keywords: automl,bigquery,dataproc,forecasting,gke,google-cloud,ray,spark,time-series,timesfm,vertex-ai
+Keywords: automl,bigquery,chronos,dataproc,forecasting,gke,google-cloud,ray,spark,time-series,timesfm,vertex-ai
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -36,6 +36,7 @@ Requires-Dist: statsmodels>=0.14
 Requires-Dist: threadpoolctl>=3.1
 Provides-Extra: all
 Requires-Dist: catboost>=1.2; extra == 'all'
+Requires-Dist: chronos-forecasting>=2.2; extra == 'all'
 Requires-Dist: dataproc-spark-connect<1.0,>=0.7; extra == 'all'
 Requires-Dist: db-dtypes>=1.2; extra == 'all'
 Requires-Dist: google-api-core>=2.19; extra == 'all'
@@ -57,6 +58,7 @@ Requires-Dist: protobuf>=4.25; extra == 'all'
 Requires-Dist: pyspark>=3.5; extra == 'all'
 Requires-Dist: ray[default]>=2.52; extra == 'all'
 Requires-Dist: statsforecast>=2.0; extra == 'all'
+Requires-Dist: timesfm[torch]>=3.0; extra == 'all'
 Requires-Dist: torch<2.14,>=2.13; extra == 'all'
 Requires-Dist: xgboost>=2.0; extra == 'all'
 Provides-Extra: gcp
@@ -71,6 +73,7 @@ Requires-Dist: google-cloud-storage>=2.17; extra == 'gcp'
 Requires-Dist: protobuf>=4.25; extra == 'gcp'
 Provides-Extra: models
 Requires-Dist: catboost>=1.2; extra == 'models'
+Requires-Dist: chronos-forecasting>=2.2; extra == 'models'
 Requires-Dist: db-dtypes>=1.2; extra == 'models'
 Requires-Dist: google-api-core>=2.19; extra == 'models'
 Requires-Dist: google-auth>=2.30; extra == 'models'
@@ -86,6 +89,7 @@ Requires-Dist: neuralprophet>=0.9; extra == 'models'
 Requires-Dist: prophet>=1.1.5; extra == 'models'
 Requires-Dist: protobuf>=4.25; extra == 'models'
 Requires-Dist: statsforecast>=2.0; extra == 'models'
+Requires-Dist: timesfm[torch]>=3.0; extra == 'models'
 Requires-Dist: torch<2.14,>=2.13; extra == 'models'
 Requires-Dist: xgboost>=2.0; extra == 'models'
 Provides-Extra: models-automl
@@ -103,6 +107,9 @@ Provides-Extra: models-dl
 Requires-Dist: neuralforecast>=1.7; extra == 'models-dl'
 Requires-Dist: neuralprophet>=0.9; extra == 'models-dl'
 Requires-Dist: torch<2.14,>=2.13; extra == 'models-dl'
+Provides-Extra: models-foundation
+Requires-Dist: chronos-forecasting>=2.2; extra == 'models-foundation'
+Requires-Dist: timesfm[torch]>=3.0; extra == 'models-foundation'
 Provides-Extra: models-prophet
 Requires-Dist: prophet>=1.1.5; extra == 'models-prophet'
 Provides-Extra: models-stats
@@ -166,45 +173,9 @@ Description-Content-Type: text/markdown
 [![Terraform](https://img.shields.io/badge/Terraform-Two--Stage%20Deploy-7B42BC?style=for-the-badge&logo=terraform&logoColor=white)](https://github.com/statmike/scale-forecasting/blob/main/terraform/README.md)
 [![License](https://img.shields.io/badge/License-Apache%202.0-4E5D6C?style=for-the-badge)](https://github.com/statmike/scale-forecasting/blob/main/LICENSE)
 
-`34 models` · `5 families` · `21 evaluation metrics` · `7 Google Cloud runtimes` · `5 Analytical SQL Views` · `validated at 100k series`
-
-```mermaid
-flowchart LR
-    subgraph IN["Your data in BigQuery"]
-        SRC["Source table<br/>series · timestamps · covariates"]
-    end
-    CFG["One RunConfig (JSON)<br/>what to forecast · horizon · models · metrics"]
-    subgraph ROUTE["Family DAG router"]
-        R["One job per active model family<br/>statistical · ml · deep_learning · automl · native"]
-    end
-    subgraph RUN["Zero-idle compute on Google Cloud (chosen per family)"]
-        S["Dataproc Serverless Spark"]
-        RY["Ray on Vertex AI or GKE"]
-        V["Vertex AI CustomJob"]
-        G["Compute Engine single VM<br/>(self-deleting)"]
-        K["GKE Indexed Job"]
-        A["Vertex AI AutoML and<br/>Tabular Workflows"]
-        B["BigQuery ML<br/>ARIMA_PLUS · AI.FORECAST"]
-    end
-    subgraph OUT["Results back in BigQuery"]
-        REG["5 registry tables<br/>forecasts · backtests · metadata · runs · jobs"]
-        VIEWS["5 analytical views<br/>leaderboard · coverage · run summary"]
-    end
-    USE["Notebooks · Python SDK · Looker · Cloud Composer DAGs"]
-
-    SRC --> CFG --> R
-    R --> S & RY & V & G & K & A & B
-    S & RY & V & G & K & A & B --> REG --> VIEWS --> USE
-
-    classDef data fill:#E8F0FE,stroke:#4285F4,color:#174EA6
-    classDef config fill:#FEF7E0,stroke:#F9AB00,color:#7A5A00
-    classDef route fill:#FCE8E6,stroke:#EA4335,color:#A50E0E
-    classDef compute fill:#E6F4EA,stroke:#34A853,color:#0D652D
-    class SRC,REG,VIEWS,USE data
-    class CFG config
-    class R route
-    class S,RY,V,G,K,A,B compute
-```
+`37 models` · `5 families` · `21 evaluation metrics` · `7 Google Cloud runtimes` · `5 Analytical SQL Views` · `validated at 100k series`
+
+![scale-forecasting architecture](https://raw.githubusercontent.com/statmike/scale-forecasting/main/docs/assets/social_card.png)
 
 ---
 
@@ -212,8 +183,8 @@ flowchart LR
 
 You describe *what* to forecast in one JSON file — the BigQuery table, the horizon, the models, the covariates, and the evaluation metrics. `scale-forecasting` decides *how*: it splits active models into up to five family jobs, dispatches each family in parallel to the Google Cloud runtime you chose for it, scores every model with rolling-origin backtesting and conformal prediction intervals, blends the winners into ensembles, reconciles hierarchical trees, and streams forecasts, leaderboards, and feature attributions back to BigQuery. When the run ends, the compute is gone.
 
-- **Use `scale-forecasting` when** you want to evaluate or operate multiple model families (statistical, gradient-boosted trees, PyTorch deep learning, Vertex AI AutoML, and BigQuery ML) under one schema, one backtest contract, and one BigQuery leaderboard — from a handful of series to 100,000+.
-- **Use a simpler path when** a single SQL query (`AI.FORECAST` or `ARIMA_PLUS` directly in BigQuery) already answers the question; you can still adopt `scale-forecasting` later to benchmark that SQL baseline against 32 Python and AutoML models on the same holdout folds.
+- **Use `scale-forecasting` when** you want to evaluate or operate multiple model families (statistical, gradient-boosted trees, PyTorch deep learning & open-weight foundation models, Vertex AI AutoML, and BigQuery ML) under one schema, one backtest contract, and one BigQuery leaderboard — from a handful of series to 100,000+.
+- **Use a simpler path when** a single SQL query (`AI.FORECAST` or `ARIMA_PLUS` directly in BigQuery) already answers the question; you can still adopt `scale-forecasting` later to benchmark that SQL baseline against 35 Python and AutoML models on the same holdout folds.
 
 ---
 
@@ -314,7 +285,7 @@ Every run is a validated [`RunConfig`](https://github.com/statmike/scale-forecas
 | **Data stays in BigQuery** | Workers read source tables via the BigQuery Storage Read API with contiguous per-worker `[start_id, end_id]` pushdown and stream results back through the Storage Write API. | [`docs/reading_source_data.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/reading_source_data.md) · [`docs/writing_results.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/writing_results.md) |
 | **Compute only while it runs** | Active model families launch in parallel (`dag.py`); fast CPU families tear down immediately while GPU families finish; single-VM GCE enforces triple-redundant self-deletion. | [`docs/runtimes_reference.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/runtimes_reference.md) · [`docs/architecture.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/architecture.md) |
 | **Seven runtimes, one contract** | Run `spark`, `ray`, `vertex`, `gce`, `gke`, `vertex_automl`, and `bigquery` concurrently under one `run_id` across CPU and NVIDIA `T4`, `L4`, `A100`, `A100_80GB` GPUs. | [`docs/runtimes_reference.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/runtimes_reference.md) · [`docs/validation.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/validation.md) |
-| **Managed and open models on one leaderboard** | Benchmark BigQuery ML (`ARIMA_PLUS`, `AI.FORECAST` / `TimesFM`) and Vertex AI AutoML alongside 28 open-source statistical, tree, and deep learning models on identical folds. | [`docs/models_reference.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/models_reference.md) · [`docs/output_schemas.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/output_schemas.md) |
+| **Managed and open models on one leaderboard** | Benchmark BigQuery ML (`ARIMA_PLUS`, `AI.FORECAST` / `timesfm` / `bq_timesfm`) and Vertex AI AutoML alongside 31 open-source statistical, tree, deep learning, and foundation models (`chronos_bolt`, `chronos2`, `timesfm_torch`) on identical folds. | [`docs/models_reference.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/models_reference.md) · [`docs/output_schemas.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/output_schemas.md) |
 | **Governed by construction** | Content-addressed `run_id`, snapshot-pinned reads, 5 registry tables, 5 analytical SQL views, surgical cell repair (`retry_run`), and 42 live-validated smoke configurations. | [`docs/output_schemas.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/output_schemas.md) · [`docs/operations.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/operations.md) · [`docs/validation.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/validation.md) |
 | **Modular install & 1-file extensibility** | `pip install scale-forecasting` has zero Google Cloud dependencies; `[gcp]`, `[spark]`, `[ray]`, `[models]`, and `[all]` are opt-in extras; new models ship in 1 file with no image rebuild. | [`docs/runtime_dependencies.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/runtime_dependencies.md) · [`docs/adding_a_model.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/adding_a_model.md) |
 
@@ -322,17 +293,17 @@ Every run is a validated [`RunConfig`](https://github.com/statmike/scale-forecas
 
 ## What's inside
 
-| Family | Models (`34` total) | Runtimes | Highlights |
+| Family | Models (`37` total) | Runtimes | Highlights |
 | :--- | :--- | :--- | :--- |
 | **`statistical`** (`18`) | `theta`, `auto_theta`, `holtwinters`, `autoets`, `auto_arima`, `sarimax`, `tbats`, `auto_ces`, `stl_bagging`, `ucm`, `kalman`, `prophet`, `croston`, `fft`, `naive_mean`, `naive_seasonal`, `naive_drift`, `naive_moving_average` | `spark`, `ray`, `vertex`, `gce`, `gke` | Fast local baselines, state-space, intermittent demand, and harmonic decomposition. |
 | **`ml`** (`5`) | `lightgbm`, `xgboost`, `catboost`, `random_forest`, `regression_lags` | `spark`, `ray`, `vertex`, `gce`, `gke` | Lag/calendar/exogenous features plus Tier 1 & Tier 2 TreeSHAP / linear / deviation attributions. |
-| **`deep_learning`** (`5`) | `tide`, `tft`, `tsmixer`, `patchtst`, `neuralprophet` | `spark`, `ray`, `vertex`, `gce`, `gke` | `local`, `global`, and `hybrid` panel regimes with fractional or dedicated GPU execution. |
+| **`deep_learning`** (`8`) | `tide`, `tft`, `tsmixer`, `patchtst`, `neuralprophet`, `chronos_bolt`, `chronos2`, `timesfm_torch` | `spark`, `ray`, `vertex`, `gce`, `gke` | Trained PyTorch (`[models-dl]`) and open-weight zero-shot foundation (`[models-foundation]`) models across `local`, `global`, and `hybrid` regimes on CPU or GPU. |
 | **`automl`** (`4`) | `vertex_l2l`, `vertex_tide`, `vertex_tft`, `vertex_seq2seq` | `vertex_automl` | Managed Vertex AI Tabular Workflows & AutoML training jobs with Stage-1 HPO reuse and baseline attributions. |
-| **`native`** (`2`) | `arima_plus`, `timesfm` (`AI.FORECAST`) | `bigquery` | Pure BigQuery SQL execution with zero cluster provisioning. |
+| **`native`** (`2`) | `arima_plus` (`ARIMA_PLUS` / `ARIMA_PLUS_XREG`), `timesfm` / `bq_timesfm` (`AI.FORECAST`) | `bigquery` | Pure BigQuery SQL execution with future covariates (`ARIMA_PLUS_XREG`), `ML.EXPLAIN_FORECAST` attributions, and zero cluster provisioning. |
 
 - **Evaluation, quantiles & calibration:** **21 evaluation metrics** (16 point + 5 interval: `wape`, `smape`, `mape`, `maape`, `ope`, `mae`, `rmse`, `mse`, `rmsle`, `bias`, `mase`, `mase_seasonal`, `rmsse`, `msse`, `r2`, `cv`, `coverage`, `pinball`, `interval_score`, `interval_width`, `msis`), empirical conformal prediction intervals, monotone multi-percentile fans (`output.quantiles` with Chernozhukov rearrangement), and Newsvendor asymmetric cost targets (`underage_cost` / `overage_cost`) ([`docs/metrics_reference.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/metrics_reference.md)).
 - **Hierarchy, smart ensembles & explainability:** All 8 Hyndman FPP3 reconciliation methods (including active-set non-negative `"mint_nonneg"` alongside `mint_shrink`, `wls_var`, `wls_struct`, `ols`, `bottom_up`, `top_down`, `middle_out`), 8 ensemble strategies (`mean`, `median`, `inverse_error`, `champion`, `horizon_specialist`, `nnls`, `ridge`, `xgb`) with `top_k` & `parsimony_margin` pruning and calibrated ensemble intervals, physical bounds (`floor`, `cap`, `cumulative_round`), and two-tier feature attributions (`attributions_df` / `plot_attributions`).
-- **Forecaster workbench, econometrics & executive reports:** Pre-fit data hygiene & SBC demand regime routing (`smooth`, `erratic`, `intermittent`, `lumpy`), Forecast Value Added (`compute_fva`) with Harvey–Leybourne–Newbold (1997) modified Diebold–Mariano $p$-values, lead-time horizon decay, Trigg tracking-signal bias audits, AR(1)-aware time rollups (`rollup_time`), counterfactual promo/price scenario simulation (`simulate_scenarios`), live drift & whipsaw stability scoring, Top-$N$ exception triage (`exceptions_df`), and self-contained interactive HTML/JSON reports (`python -m scale_forecasting.report`) ([`docs/forecaster_workbench.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/forecaster_workbench.md)).
+- **Forecaster workbench, econometrics, inventory policy & executive reports:** Pre-fit data hygiene & SBC demand regime routing (`smooth`, `erratic`, `intermittent`, `lumpy`), Forecast Value Added (`compute_fva`) with Harvey–Leybourne–Newbold (1997) modified Diebold–Mariano $p$-values, lead-time horizon decay, Trigg tracking-signal bias audits, AR(1)-aware time rollups (`rollup_time`) and replenishment policy translators (`compute_inventory_policy` / `inventory_policy_df` for $(s, S)$, $(R, S)$, Fill Rate, and Newsvendor safety stock, reorder point, and EOQ), counterfactual promo/price scenario simulation (`simulate_scenarios`), live drift & whipsaw stability scoring, Top-$N$ exception triage (`exceptions_df`), and self-contained interactive HTML/JSON reports (`python -m scale_forecasting.report`) ([`docs/forecaster_workbench.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/forecaster_workbench.md)).
 
 ---
 
@@ -359,3 +330,6 @@ All notebooks in [`notebooks/`](https://github.com/statmike/scale-forecasting/bl
 ## License
 
 Apache-2.0 — see [`LICENSE`](https://github.com/statmike/scale-forecasting/blob/main/LICENSE).
+
+This is not an officially supported Google product. It is built on Google products and is neither
+endorsed nor supported by Google.

{scale_forecasting-1.0.0 → scale_forecasting-1.2.0}/README.md

@@ -12,7 +12,7 @@
 [![Terraform](https://img.shields.io/badge/Terraform-Two--Stage%20Deploy-7B42BC?style=for-the-badge&logo=terraform&logoColor=white)](https://github.com/statmike/scale-forecasting/blob/main/terraform/README.md)
 [![License](https://img.shields.io/badge/License-Apache%202.0-4E5D6C?style=for-the-badge)](https://github.com/statmike/scale-forecasting/blob/main/LICENSE)
 
-`34 models` · `5 families` · `21 evaluation metrics` · `7 Google Cloud runtimes` · `5 Analytical SQL Views` · `validated at 100k series`
+`37 models` · `5 families` · `21 evaluation metrics` · `7 Google Cloud runtimes` · `5 Analytical SQL Views` · `validated at 100k series`
 
 ```mermaid
 flowchart LR
@@ -58,8 +58,8 @@ flowchart LR
 
 You describe *what* to forecast in one JSON file — the BigQuery table, the horizon, the models, the covariates, and the evaluation metrics. `scale-forecasting` decides *how*: it splits active models into up to five family jobs, dispatches each family in parallel to the Google Cloud runtime you chose for it, scores every model with rolling-origin backtesting and conformal prediction intervals, blends the winners into ensembles, reconciles hierarchical trees, and streams forecasts, leaderboards, and feature attributions back to BigQuery. When the run ends, the compute is gone.
 
-- **Use `scale-forecasting` when** you want to evaluate or operate multiple model families (statistical, gradient-boosted trees, PyTorch deep learning, Vertex AI AutoML, and BigQuery ML) under one schema, one backtest contract, and one BigQuery leaderboard — from a handful of series to 100,000+.
-- **Use a simpler path when** a single SQL query (`AI.FORECAST` or `ARIMA_PLUS` directly in BigQuery) already answers the question; you can still adopt `scale-forecasting` later to benchmark that SQL baseline against 32 Python and AutoML models on the same holdout folds.
+- **Use `scale-forecasting` when** you want to evaluate or operate multiple model families (statistical, gradient-boosted trees, PyTorch deep learning & open-weight foundation models, Vertex AI AutoML, and BigQuery ML) under one schema, one backtest contract, and one BigQuery leaderboard — from a handful of series to 100,000+.
+- **Use a simpler path when** a single SQL query (`AI.FORECAST` or `ARIMA_PLUS` directly in BigQuery) already answers the question; you can still adopt `scale-forecasting` later to benchmark that SQL baseline against 35 Python and AutoML models on the same holdout folds.
 
 ---
 
@@ -160,7 +160,7 @@ Every run is a validated [`RunConfig`](https://github.com/statmike/scale-forecas
 | **Data stays in BigQuery** | Workers read source tables via the BigQuery Storage Read API with contiguous per-worker `[start_id, end_id]` pushdown and stream results back through the Storage Write API. | [`docs/reading_source_data.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/reading_source_data.md) · [`docs/writing_results.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/writing_results.md) |
 | **Compute only while it runs** | Active model families launch in parallel (`dag.py`); fast CPU families tear down immediately while GPU families finish; single-VM GCE enforces triple-redundant self-deletion. | [`docs/runtimes_reference.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/runtimes_reference.md) · [`docs/architecture.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/architecture.md) |
 | **Seven runtimes, one contract** | Run `spark`, `ray`, `vertex`, `gce`, `gke`, `vertex_automl`, and `bigquery` concurrently under one `run_id` across CPU and NVIDIA `T4`, `L4`, `A100`, `A100_80GB` GPUs. | [`docs/runtimes_reference.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/runtimes_reference.md) · [`docs/validation.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/validation.md) |
-| **Managed and open models on one leaderboard** | Benchmark BigQuery ML (`ARIMA_PLUS`, `AI.FORECAST` / `TimesFM`) and Vertex AI AutoML alongside 28 open-source statistical, tree, and deep learning models on identical folds. | [`docs/models_reference.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/models_reference.md) · [`docs/output_schemas.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/output_schemas.md) |
+| **Managed and open models on one leaderboard** | Benchmark BigQuery ML (`ARIMA_PLUS`, `AI.FORECAST` / `timesfm` / `bq_timesfm`) and Vertex AI AutoML alongside 31 open-source statistical, tree, deep learning, and foundation models (`chronos_bolt`, `chronos2`, `timesfm_torch`) on identical folds. | [`docs/models_reference.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/models_reference.md) · [`docs/output_schemas.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/output_schemas.md) |
 | **Governed by construction** | Content-addressed `run_id`, snapshot-pinned reads, 5 registry tables, 5 analytical SQL views, surgical cell repair (`retry_run`), and 42 live-validated smoke configurations. | [`docs/output_schemas.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/output_schemas.md) · [`docs/operations.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/operations.md) · [`docs/validation.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/validation.md) |
 | **Modular install & 1-file extensibility** | `pip install scale-forecasting` has zero Google Cloud dependencies; `[gcp]`, `[spark]`, `[ray]`, `[models]`, and `[all]` are opt-in extras; new models ship in 1 file with no image rebuild. | [`docs/runtime_dependencies.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/runtime_dependencies.md) · [`docs/adding_a_model.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/adding_a_model.md) |
 
@@ -168,17 +168,17 @@ Every run is a validated [`RunConfig`](https://github.com/statmike/scale-forecas
 
 ## What's inside
 
-| Family | Models (`34` total) | Runtimes | Highlights |
+| Family | Models (`37` total) | Runtimes | Highlights |
 | :--- | :--- | :--- | :--- |
 | **`statistical`** (`18`) | `theta`, `auto_theta`, `holtwinters`, `autoets`, `auto_arima`, `sarimax`, `tbats`, `auto_ces`, `stl_bagging`, `ucm`, `kalman`, `prophet`, `croston`, `fft`, `naive_mean`, `naive_seasonal`, `naive_drift`, `naive_moving_average` | `spark`, `ray`, `vertex`, `gce`, `gke` | Fast local baselines, state-space, intermittent demand, and harmonic decomposition. |
 | **`ml`** (`5`) | `lightgbm`, `xgboost`, `catboost`, `random_forest`, `regression_lags` | `spark`, `ray`, `vertex`, `gce`, `gke` | Lag/calendar/exogenous features plus Tier 1 & Tier 2 TreeSHAP / linear / deviation attributions. |
-| **`deep_learning`** (`5`) | `tide`, `tft`, `tsmixer`, `patchtst`, `neuralprophet` | `spark`, `ray`, `vertex`, `gce`, `gke` | `local`, `global`, and `hybrid` panel regimes with fractional or dedicated GPU execution. |
+| **`deep_learning`** (`8`) | `tide`, `tft`, `tsmixer`, `patchtst`, `neuralprophet`, `chronos_bolt`, `chronos2`, `timesfm_torch` | `spark`, `ray`, `vertex`, `gce`, `gke` | Trained PyTorch (`[models-dl]`) and open-weight zero-shot foundation (`[models-foundation]`) models across `local`, `global`, and `hybrid` regimes on CPU or GPU. |
 | **`automl`** (`4`) | `vertex_l2l`, `vertex_tide`, `vertex_tft`, `vertex_seq2seq` | `vertex_automl` | Managed Vertex AI Tabular Workflows & AutoML training jobs with Stage-1 HPO reuse and baseline attributions. |
-| **`native`** (`2`) | `arima_plus`, `timesfm` (`AI.FORECAST`) | `bigquery` | Pure BigQuery SQL execution with zero cluster provisioning. |
+| **`native`** (`2`) | `arima_plus` (`ARIMA_PLUS` / `ARIMA_PLUS_XREG`), `timesfm` / `bq_timesfm` (`AI.FORECAST`) | `bigquery` | Pure BigQuery SQL execution with future covariates (`ARIMA_PLUS_XREG`), `ML.EXPLAIN_FORECAST` attributions, and zero cluster provisioning. |
 
 - **Evaluation, quantiles & calibration:** **21 evaluation metrics** (16 point + 5 interval: `wape`, `smape`, `mape`, `maape`, `ope`, `mae`, `rmse`, `mse`, `rmsle`, `bias`, `mase`, `mase_seasonal`, `rmsse`, `msse`, `r2`, `cv`, `coverage`, `pinball`, `interval_score`, `interval_width`, `msis`), empirical conformal prediction intervals, monotone multi-percentile fans (`output.quantiles` with Chernozhukov rearrangement), and Newsvendor asymmetric cost targets (`underage_cost` / `overage_cost`) ([`docs/metrics_reference.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/metrics_reference.md)).
 - **Hierarchy, smart ensembles & explainability:** All 8 Hyndman FPP3 reconciliation methods (including active-set non-negative `"mint_nonneg"` alongside `mint_shrink`, `wls_var`, `wls_struct`, `ols`, `bottom_up`, `top_down`, `middle_out`), 8 ensemble strategies (`mean`, `median`, `inverse_error`, `champion`, `horizon_specialist`, `nnls`, `ridge`, `xgb`) with `top_k` & `parsimony_margin` pruning and calibrated ensemble intervals, physical bounds (`floor`, `cap`, `cumulative_round`), and two-tier feature attributions (`attributions_df` / `plot_attributions`).
-- **Forecaster workbench, econometrics & executive reports:** Pre-fit data hygiene & SBC demand regime routing (`smooth`, `erratic`, `intermittent`, `lumpy`), Forecast Value Added (`compute_fva`) with Harvey–Leybourne–Newbold (1997) modified Diebold–Mariano $p$-values, lead-time horizon decay, Trigg tracking-signal bias audits, AR(1)-aware time rollups (`rollup_time`), counterfactual promo/price scenario simulation (`simulate_scenarios`), live drift & whipsaw stability scoring, Top-$N$ exception triage (`exceptions_df`), and self-contained interactive HTML/JSON reports (`python -m scale_forecasting.report`) ([`docs/forecaster_workbench.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/forecaster_workbench.md)).
+- **Forecaster workbench, econometrics, inventory policy & executive reports:** Pre-fit data hygiene & SBC demand regime routing (`smooth`, `erratic`, `intermittent`, `lumpy`), Forecast Value Added (`compute_fva`) with Harvey–Leybourne–Newbold (1997) modified Diebold–Mariano $p$-values, lead-time horizon decay, Trigg tracking-signal bias audits, AR(1)-aware time rollups (`rollup_time`) and replenishment policy translators (`compute_inventory_policy` / `inventory_policy_df` for $(s, S)$, $(R, S)$, Fill Rate, and Newsvendor safety stock, reorder point, and EOQ), counterfactual promo/price scenario simulation (`simulate_scenarios`), live drift & whipsaw stability scoring, Top-$N$ exception triage (`exceptions_df`), and self-contained interactive HTML/JSON reports (`python -m scale_forecasting.report`) ([`docs/forecaster_workbench.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/forecaster_workbench.md)).
 
 ---
 
@@ -205,3 +205,6 @@ All notebooks in [`notebooks/`](https://github.com/statmike/scale-forecasting/bl
 ## License
 
 Apache-2.0 — see [`LICENSE`](https://github.com/statmike/scale-forecasting/blob/main/LICENSE).
+
+This is not an officially supported Google product. It is built on Google products and is neither
+endorsed nor supported by Google.

{scale_forecasting-1.0.0 → scale_forecasting-1.2.0}/pyproject.toml

@@ -1,8 +1,8 @@
 [project]
 name = "scale-forecasting"
-version = "1.0.0"
+version = "1.2.0"
 description = "Time-series forecasting on Google Cloud at any scale: one JSON configuration runs every model family on Dataproc Serverless, Ray, Vertex AI, GKE, Compute Engine, or BigQuery ML and writes forecasts and leaderboards back to BigQuery."
-readme = "README.md"
+dynamic = ["readme"]
 # Two different pins, on purpose. `requires-python` is what *the package* installs on: the pure
 # layer (models, metrics, backtests, the playground) and the clients run on 3.11 and 3.12, and the
 # CI `core-install` job proves the bare install on each; 3.13 waits on the numpy<2 pin below (1.26
@@ -26,6 +26,7 @@ keywords = [
     "gke",
     "automl",
     "timesfm",
+    "chronos",
 ]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
@@ -42,7 +43,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 
-# Core dependencies: the pure forecasting layer — config, the 34 model plugins' shared base, the 21
+# Core dependencies: the pure forecasting layer — config, the 37 model plugins' shared base, the 21
 # metrics, features, backtests, calibration, reconciliation, ensembling, HPO, the worker, and the
 # playground. Nothing here talks to a cloud API. A bare `pip install scale-forecasting` is enough to
 # run `python -m scale_forecasting.playground` on synthetic data with no project, no billing, and
@@ -160,8 +161,8 @@ submit = [
 ]
 # Granular model extras for environment agility — install individual model libraries
 # when enterprise environments restrict specific packages, or install `models` for the full suite.
-# 15 of the 34 models run on the core install alone (numpy / scipy / statsmodels / scikit-learn);
-# these extras add the 17 that need a third-party or cloud library, and the two BigQuery ML models
+# 15 of the 37 models run on the core install alone (numpy / scipy / statsmodels / scikit-learn);
+# these extras add the 20 that need a third-party or cloud library, and the two BigQuery ML models
 # need [gcp]. docs/models_reference.md maps each extra to its models.
 models-stats = [
     "statsforecast>=2.0",
@@ -185,6 +186,14 @@ models-dl = [
     # compatibility lets a 12.6-built wheel run on the 535 driver.
     "torch>=2.13,<2.14",
 ]
+# Zero-shot pretrained foundation models (`chronos_bolt`, `chronos2`, `timesfm_torch`). Separated
+# from `models-dl` so users who only want pretrained zero-shot inference (CPU-default, GPU-optional)
+# do not need `neuralprophet` or `neuralforecast`, and vice versa. Both packages depend on `torch`
+# transitively (whose version floor is declared in `models-dl`).
+models-foundation = [
+    "chronos-forecasting>=2.2",
+    "timesfm[torch]>=3.0",
+]
 # The four Vertex AI AutoML models (vertex_l2l / tide / tft / seq2seq) run as Tabular Workflow
 # pipelines or managed training jobs. The Vertex SDK is in [gcp]; this adds the pipeline components
 # the Tabular Workflow path compiles against.
@@ -192,10 +201,10 @@ models-automl = [
     "scale-forecasting[gcp]",
     "google-cloud-pipeline-components>=2.14",
 ]
-# Full optional model suite (statistical + boosted-tree + Prophet + deep-learning + Vertex AutoML),
-# composed from the family extras so every version floor is declared exactly once.
+# Full optional model suite (statistical + boosted-tree + Prophet + deep-learning + foundation +
+# Vertex AutoML), composed from the family extras so every version floor is declared exactly once.
 models = [
-    "scale-forecasting[models-stats,models-trees,models-prophet,models-dl,models-automl]",
+    "scale-forecasting[models-stats,models-trees,models-prophet,models-dl,models-foundation,models-automl]",
 ]
 # Everything: every client, every model library, both on-cluster runtimes, the notebook kernel.
 # This is what `uv sync --all-extras` (CI, `make sync`) resolves to, spelled as one installable name.
@@ -283,9 +292,16 @@ torch = [
 ]
 
 [build-system]
-requires = ["hatchling"]
+requires = ["hatchling", "hatch-fancy-pypi-readme>=24.1"]
 build-backend = "hatchling.build"
 
+[tool.hatch.metadata.hooks.fancy-pypi-readme]
+content-type = "text/markdown"
+fragments = [{ path = "README.md" }]
+substitutions = [
+    { pattern = '```mermaid[\s\S]*?```', replacement = '![scale-forecasting architecture](https://raw.githubusercontent.com/statmike/scale-forecasting/main/docs/assets/social_card.png)' },
+]
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/scale_forecasting"]
 exclude = ["src/scale_forecasting/**/README.md"]
@@ -293,6 +309,7 @@ exclude = ["src/scale_forecasting/**/README.md"]
 [tool.hatch.build.targets.sdist]
 only-include = [
     "src/scale_forecasting",
+    "README.md",
     "CHANGELOG.md",
 ]
 exclude = ["src/scale_forecasting/**/README.md"]
@@ -347,6 +364,9 @@ module = [
     "prophet.*",
     "neuralprophet.*",
     "neuralforecast.*",
+    "chronos.*",
+    "timesfm.*",
+    "timesfm3.*",
     "sklearn.*",
     "google_cloud_pipeline_components.*",
     "kfp.*",

{scale_forecasting-1.0.0 → scale_forecasting-1.2.0}/src/scale_forecasting/__init__.py

@@ -53,7 +53,7 @@ from .settings import Settings
 try:
     __version__: str = _pkg_version("scale-forecasting")
 except PackageNotFoundError:  # pragma: no cover - zip-staged cloud worker without .dist-info
-    __version__ = "1.0.0"
+    __version__ = "1.2.0"
 
 # Lazy (heavy): name -> (module, attribute). Resolved on first access by ``__getattr__`` (PEP 562)
 # so the model modules (statsmodels et al., ~5s) load only when a caller actually reaches for the
@@ -136,9 +136,13 @@ _LAZY: dict[str, tuple[str, str]] = {
     "compute_realized_accuracy": (".diagnostics", "compute_realized_accuracy"),
     "compute_revision_stability": (".diagnostics", "compute_revision_stability"),
     "compute_exceptions_queue": (".diagnostics", "compute_exceptions_queue"),
+    "compute_anomalies": (".diagnostics", "compute_anomalies"),
+    "compute_change_points": (".diagnostics", "compute_change_points"),
+    "compute_inventory_policy": (".diagnostics", "compute_inventory_policy"),
     "rollup_time": (".diagnostics", "rollup_time"),
     "plot_fva": (".diagnostics", "plot_fva"),
     "plot_horizon_decay": (".diagnostics", "plot_horizon_decay"),
+    "plot_inventory_policy": (".diagnostics", "plot_inventory_policy"),
     "apply_scenario_shocks": (".scenarios", "apply_scenario_shocks"),
     "simulate_scenarios": (".scenarios", "simulate_scenarios"),
     "summarize_scenarios": (".scenarios", "summarize_scenarios"),
@@ -172,15 +176,19 @@ if TYPE_CHECKING:  # so IDEs / type-checkers see the lazy names as real imports
     from .agent_surfaces import probe_environment  # noqa: F401
     from .dag import DagNode  # noqa: F401
     from .diagnostics import (  # noqa: F401
+        compute_anomalies,
         compute_bias_report,
+        compute_change_points,
         compute_exceptions_queue,
         compute_fva,
         compute_horizon_decay,
+        compute_inventory_policy,
         compute_realized_accuracy,
         compute_revision_stability,
         diebold_mariano_test,
         plot_fva,
         plot_horizon_decay,
+        plot_inventory_policy,
         rollup_time,
         wilcoxon_pvalue,
     )