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

{scale_forecasting-1.2.0 → scale_forecasting-1.3.0}/CHANGELOG.md

@@ -11,6 +11,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.3.0] - 2026-10-16
+
+### Added
+
+- **Glass-Box Auto-Forecaster (`Forecaster.build_config()` & `Forecaster.auto()`, [`auto_policy.py`](./src/scale_forecasting/auto_policy.py)):**
+  - Compiles a profiled time-series panel (or BigQuery source table) into a standard, inspectable [`RunConfig`](./src/scale_forecasting/config.py) (`AutoBlueprint.config`) paired with a structured per-parameter evidence ledger (`AutoBlueprint.rationale_df()`), automatic schema-backed column detection (`detect_panel_columns`), automatic regime classification (`smooth`, `intermittent`, `lumpy`, `erratic` via Syntetos-Boylan `ADI` and $\text{CV}^2$), automatic `log1p` target transform (`skewness >= 1.35`), and 5 series-count scale regimes (`micro`, `small`, `medium`, `large`, `hyperscale` up to 100,000+ series).
+  - Supports 4 observational exposure tiers (`first_light`, `wide_field`, `deep_field`, `survey`) and 4 execution targets (`where="local" | "bigquery" | "cloud_cpu" | "cloud_all"`), plus CLI (`python -m scale_forecasting.main --auto ...`) and MCP (`auto_compile_config` and `run_auto_forecaster` tools in [`mcp.py`](./src/scale_forecasting/mcp.py)).
+- **Multi-Branch Bounded `autofocus` Tournament (`autofocus=True`, `autofocus_mode="dag" | "linear"`):**
+  - Explores up to 3 specialized Pass 2 refinement branches (`pass_2_prune_1`, `pass_2_cov_ablation`, `pass_2_transform_probe`) from Pass 1 telemetry (`leaderboard`, `fva_df`, `bias_report_df`, `horizon_decay_df`, `exceptions_df`), followed by a Pass 3 Synthesis Ensemble that borrows all evaluated models (`reuse_prior_runs=True` with snapshot-fingerprint verification) and fits `horizon_specialist`, `champion`, `nnls`, `ridge`, `ensemble_InverseError`, and `trimmed_mean` stackers.
+  - Enforces a strict **non-degradation ratchet**: returns the branch with the lowest out-of-fold backtest error (`MASE` / `WAPE`) across Pass 1, Pass 2, and Pass 3, guaranteeing zero regret relative to Pass 1.
+- **7-Question Practitioner Assessment (`AutoForecastResult.assessment_df()`), 4-Anchor Baseline Value Ladder (`baseline_value_df()`), and Hierarchy Reconciliation Value (`hierarchy_value_df()`):**
+  - Every `Forecaster.auto()` run answers 7 practitioner trust questions from out-of-fold backtest evidence: (1) Baseline Value (`snaive`, `naive`, `historic_average`, `seasonal_window_average`), (2) Ensemble Parsimony (`parsimony_tolerance_pct`), (3) Covariate FVA & Overfitting Check, (4) Global Pooling vs. Local Independence, (5) Horizon Crossover (`horizon_specialist`), (6) Hierarchy Reconciliation Lift, and (7) Operational Readiness & Exceptions.
+- **20-Panel Synthetic DGP & 9-Dataset Public Open-Data Benchmark Suites ([`benchmarks.py`](./src/scale_forecasting/benchmarks.py)):**
+  - Added 20 ground-truth synthetic Data Generating Process (DGP) panels (`dgp_01` through `dgp_20` across `h`, `D`, `W`, `MS` cadences, intermittent/lumpy demand, structural level breaks, true vs. decoy covariates, and 2/3-level hierarchies) via `load_benchmark()`.
+  - Added on-demand fetchers (`fetch_public_benchmark()`, zero repo data bloat) for 9 real-world open-data benchmarks (`m5_walmart`, `favorita_grocery`, `m4_daily`, `m4_weekly`, `m4_monthly`, `monash_tourism_monthly`, `monash_hospital`, `monash_car_parts`, `etth1`), achieving **9/9 non-negative held-out test MAE lift over `SNaive`** (`+14.92%` mean test lift, `+25.18%` mean OOF FVA).
+- **Dynamic 6-Runtime Live Quota Preflight ([`quota.py`](./src/scale_forecasting/quota.py)) & Empirical 7-Runtime Duration Estimator ([`profiling/duration.py`](./src/scale_forecasting/profiling/duration.py)):**
+  - Live Cloud Quotas / Compute Engine regional quota preflight across all 6 compute-provisioning runtimes (`gce`, `vertex`, `ray`, `spark` cluster & Serverless DCU/shuffle guard, `gke`, `vertex_automl`) with automatic worker cap or machine downgrade before submission.
+  - Empirical duration estimator (`predict_run_duration()`) calibrated against 606 completed cloud jobs (`5.59M` evaluated cells).
+- **Interactive Showcase Notebook 11 ([`notebooks/11_auto_forecaster_and_autofocus.ipynb`](./notebooks/11_auto_forecaster_and_autofocus.ipynb)):**
+  - End-to-end walkthrough of `Forecaster.build_config()`, `Forecaster.auto()`, multi-branch `autofocus`, the 4-Anchor Baseline Value Ladder, and the 7-Question Practitioner Assessment across local and cloud execution.
+
+### Changed
+
+- **Physical Annual (`365.25d`) & Multi-Seasonal Sub-Daily (`24h`/`12h`/`168h`) Fourier Harmonics ([`features.py`](./src/scale_forecasting/features.py)) & Frequency-Matched Lags ([`auto_policy.py`](./src/scale_forecasting/auto_policy.py)):**
+  - [`_fourier_terms()`](./src/scale_forecasting/features.py) now normalizes daily, weekly, monthly, and quarterly timestamps by the physical `365.25`-day year and encodes multi-seasonal diurnal ($24\text{h}$), semi-diurnal ($12\text{h}$), and weekly ($168\text{h}$) harmonics for hourly (`h`/`H`) panels.
+  - [`_frequency_matched_lags()`](./src/scale_forecasting/auto_policy.py) aligns tabular lag depths (`lightgbm`, `catboost`, `xgboost`, `ridge`) with hourly (`[1, 2, 3, 6, 12, 24, 48, 168]`) and monthly (`[1, 2, 3, 6, 12]` / `[1, 2, 3, 6, 12, 24]`) cadences while preserving intermittent/lumpy series.
+- **Leave-One-Fold-Out (LOFO) Out-of-Fold Ensemble Selection & Finite-Sample Conformal Bounds ([`ensembler.py`](./src/scale_forecasting/ensembler.py)):**
+  - [`_compute_oof_ensemble_scores()`](./src/scale_forecasting/ensembler.py) evaluates learned stackers (`nnls`, `ridge`, `xgb`, `ensemble_InverseError`) strictly out-of-fold across backtest folds (`n_folds >= 2`) so in-sample weight fitting cannot win `ensemble_champion`, and [`ensemble_oof_bounds()`](./src/scale_forecasting/ensembler.py) uses finite-sample conformal rank quantiles (`_empirical_quantile`).
+- **Vectorized Local & Spark `applyInPandas` Baseline Fast-Path ([`playground.py`](./src/scale_forecasting/playground.py), [`spark_explode.py`](./src/scale_forecasting/engines/spark_explode.py)) & BigQuery Storage Write API Historical Window Fallback ([`write_api.py`](./src/scale_forecasting/registry/write_api.py)):**
+  - Added vectorized NumPy panel evaluation for baseline models (`naive`, `snaive`, `historic_average`, `seasonal_window_average`) in both local `playground` and Spark `applyInPandas` workers, cutting 100,000-series baseline execution from minutes to `< 2.5s`.
+  - [`write_dataframe_storage_api()`](./src/scale_forecasting/registry/write_api.py) automatically routes tables with partition dates outside BigQuery Storage Write API's `[-3650d, +366d]` streaming window to `load_table_from_dataframe` (Parquet batch load).
+
+---
+
+## [1.2.1] - 2026-10-14
+
+### Added
+
+- **Atomic Version Bump Automation (`make bump VERSION=X.Y.Z`):**
+  - Added [`bump_version()`](./src/scale_forecasting/agent_surfaces.py) (`python -m scale_forecasting.agent_surfaces --bump-version X.Y.Z`) and `make bump VERSION=X.Y.Z` in [`Makefile`](./Makefile) to atomically update all 7 version-locked files ([`pyproject.toml`](./pyproject.toml), [`src/scale_forecasting/__init__.py`](./src/scale_forecasting/__init__.py), [`plugin.json`](./plugin.json), [`skills/scale-forecasting/SKILL.md`](./skills/scale-forecasting/SKILL.md), [`CHANGELOG.md`](./CHANGELOG.md), [`CITATION.cff`](./CITATION.cff), and [`docker/cloudbuild.yaml`](./docker/cloudbuild.yaml)), refresh `uv.lock` and `docker/requirements.txt`, sync the editable `.venv` `.dist-info`, and regenerate all 6 AI agent surface files.
+- **Version-Tagged Runtime Containers (`:vX.Y.Z`) & Launcher $\leftrightarrow$ Worker Version Parity Guard (`code_delivery.py`):**
+  - [`docker/cloudbuild.yaml`](./docker/cloudbuild.yaml) and `make image` in [`Makefile`](./Makefile) now tag and push both `:latest` and `:v<version>` (`:v1.2.1`) to Artifact Registry alongside the content-addressed `venv_archive` tarball.
+  - Added [`verify_version_parity()`](./src/scale_forecasting/code_delivery.py), wired into `spark_explode._stamp_executed_fanout` and `ray_engine._stamp_executed_sizing` (shared across `ray`, `vertex`, `gce`, and `gke`), stamping `launcher` and `worker` `scale_forecasting.__version__` (`$.version`) into `run_registry.job_telemetry` and raising `ConfigError` on mismatch when `SF_STRICT_VERSION_PARITY=1`.
+- **Complete 7-Runtime Provisioning vs. Execution Telemetry (`$.platform`):**
+  - Extended [`batch_telemetry.platform_phases()`](./src/scale_forecasting/batch_telemetry.py) (`_to_epoch_seconds` / `_rfc3339_seconds`) to accept protobuf `Timestamp`, `datetime`, epoch seconds/milliseconds, and RFC 3339 strings, and wired `$.platform` (`provision_s`, `execute_s`, `total_wall_s`) into `RayProbe`, `GceProbe`, `GkeProbe`, and `VertexAutoMLProbe` in [`src/scale_forecasting/probes/runtimes.py`](./src/scale_forecasting/probes/runtimes.py) as well as ephemeral submitters ([`gce_submit.py`](./src/scale_forecasting/gce_submit.py), [`gke_submit.py`](./src/scale_forecasting/gke_submit.py), [`ray_submit.py`](./src/scale_forecasting/ray_submit.py), [`cluster_submit.py`](./src/scale_forecasting/cluster_submit.py), [`automl_submit.py`](./src/scale_forecasting/automl_submit.py)) so `v_run_jobs.provision_seconds` and `execute_seconds` are populated across all compute runtimes.
+- **Cross-Version BigQuery Registry Compatibility Tripwire ([`tests/unit/test_cross_version_resilience.py`](./tests/unit/test_cross_version_resilience.py)):**
+  - Verifies backward and forward compatibility of `Forecaster.from_run_id()`, `ops.match_reusable_models()` & `render_borrow_model_sql()`, `review._assemble_review()` & DataFrame builders, and `diagnostics.py` (`compute_fva`, `compute_inventory_policy`, `compute_anomalies`, `compute_change_points`) across historical `v1.0.0`, `v1.1.0`, and `v1.2.0` registry payloads.
+
+### Changed
+
+- **Interactive Showcase Notebook Refresh ([`notebooks/01_bigquery_native_sql.ipynb`](./notebooks/01_bigquery_native_sql.ipynb) & [`notebooks/08_multi_engine_master_workflow.ipynb`](./notebooks/08_multi_engine_master_workflow.ipynb)):**
+  - Re-executed and persisted `01_bigquery_native_sql.ipynb` (`arima_plus`, `arima_plus_xreg`, `timesfm` `TimesFM 3.0` multivariate, `timesfm@univariate` `TimesFM 2.5`, Covariate FVA, Two-Tier `ML.EXPLAIN_FORECAST` attributions, anomaly/change-point detection, and $(s, S)$ inventory replenishment policy) and `08_multi_engine_master_workflow.ipynb` (4-family parallel DAG with `[models-foundation]` `chronos_bolt`, FVA, TreeSHAP attributions, `v_run_jobs` provisioning telemetry, anomaly/change-point detection, and inventory replenishment policy) against the `v1.2.1` runtime container.
+
+---
+
 ## [1.2.0] - 2026-10-14
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scale-forecasting
-Version: 1.2.0
+Version: 1.3.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/
@@ -205,11 +205,12 @@ import scale_forecasting as sf
 from scale_forecasting import playground
 
 result = playground.run_one(model="theta", horizon=14, backtest=True)
+auto_run = sf.Forecaster.auto(playground.sample_data(n_series=3), tier="first_light", autofocus=True)
 plan = sf.Forecaster.from_file("configs/ensemble_demo.json").dry_run()
-print(result.metrics["wape"], plan.run_id)
+print(result.metrics["wape"], auto_run.leaderboard_df().iloc[0]["model_type"], plan.run_id)
 ```
 
-Continue in [`notebooks/00_model_playground.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/00_model_playground.ipynb) or [Getting started (`docs/getting_started.md`)](https://github.com/statmike/scale-forecasting/blob/main/docs/getting_started.md).
+Continue in [`notebooks/00_model_playground.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/00_model_playground.ipynb), [`notebooks/11_auto_forecaster_and_autofocus.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/11_auto_forecaster_and_autofocus.ipynb), [Auto-forecaster & `autofocus` (`docs/auto_forecaster.md`)](https://github.com/statmike/scale-forecasting/blob/main/docs/auto_forecaster.md), or [Getting started (`docs/getting_started.md`)](https://github.com/statmike/scale-forecasting/blob/main/docs/getting_started.md).
 
 ### Journey 2 — Deploy to your Google Cloud project in 15 minutes
 
@@ -278,6 +279,23 @@ Every run is a validated [`RunConfig`](https://github.com/statmike/scale-forecas
 
 ---
 
+## Write a `RunConfig` by hand — or let the Glass-Box Auto-Forecaster compile & refine it
+
+You can always author a [`RunConfig`](https://github.com/statmike/scale-forecasting/blob/main/docs/configuration_reference.md) JSON file directly and run it with any method in this repository. Or, when starting on a new dataset, let **`Forecaster.build_config()`** and **`Forecaster.auto()`** profile your data (`Forecaster.profile_data()`), compile a standard `RunConfig` across **4 exposure tiers** (`first_light`, `wide_field`, `deep_sky`, `deep_field`), optionally refine it with multi-branch **`autofocus`**, and answer the 7 core questions every forecaster asks (`f.practitioner_assessment_df()`, `f.compare_models()`):
+
+| What Forecasters Care About | Manual Trial-and-Error | Typical Black-Box AutoML | `scale-forecasting` Glass-Box Auto-Forecaster & `autofocus` |
+| :--- | :--- | :--- | :--- |
+| **Transparency & ownership** | Full control, but days of hand-tuning JSON/code across model families. | Swallows your data and hides *why* models or features were picked. | **100% glass-box:** Prints a plain-English rationale table (`bp.explain()`) and saves a standard, editable `RunConfig` JSON you own (`--init-config`). |
+| **User constraints (`[PINNED]`)** | You wire every constraint and fallback by hand. | Take-it-or-leave-it automation; hard to lock specific families or metrics. | **Pin any dial:** Lock `allowed_families`, `models`, `decision_metric`, `n_folds`, `hpo`, `ensemble`, or `max_minutes`; `autofocus` optimizes strictly around your pins. |
+| **Compute & scale awareness (`n_series`)** | You manually size VMs, GPUs, and worker pools for 10 vs. 100k series. | Assumes a single Python machine or a single fixed cluster. | **Co-designs models + 7 cloud runtimes:** Adapts portfolios from `micro` (`<15` series) to `hyperscale` (`25,000+` series) across `local`, `bigquery`, `spark`, `ray`, `vertex`, `gce`, and `gke`. |
+| **Iterative learning & compute reuse** | Re-running a tweak refits every model from scratch. | Runs a single fixed pipeline or brute-forces everything upfront. | **Multi-branch `autofocus` DAG + cell borrowing:** Tests isolated upgrades (`2A` scale/outliers, `2B` feature pruning/horizon, `2C` intermittent/hierarchy/stockouts), **borrows Pass 1's finished models**, and guarantees non-degradation via the **Champion Ratchet**. |
+| **"Earn your complexity" proof** | Easy to overfit noisy features without noticing a simple model was better. | Often crowns a heavy model without proving lift over simple baselines. | **4-anchor Baseline Ladder & 7-Question Assessment:** Benchmarks against seasonal naive, plain univariate (`theta`), and dual-mode foundation baselines (`@univariate` vs. `@global_cov_all`). If a simple univariate model wins, it becomes champion and lists the complex models it beat (`f.baseline_value_df()`, `f.practitioner_assessment_df()`). |
+| **How the policy was built** | Individual intuition and ad-hoc rules of thumb. | Fixed vendor heuristics or slow, costly runtime LLM calls. | **Evolved with AlphaEvolve on Gemini Enterprise (`26.08 -> 74.82` fitness across 20 synthetic DGPs + 9 public benchmarks)** and compiled into deterministic pure Python (**zero LLM calls at runtime**). |
+
+Full guide and interactive notebook: **[Glass-Box Auto-Forecaster & `autofocus` (`docs/auto_forecaster.md`)](https://github.com/statmike/scale-forecasting/blob/main/docs/auto_forecaster.md)** and **[`notebooks/11_auto_forecaster_and_autofocus.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/11_auto_forecaster_and_autofocus.ipynb)**.
+
+---
+
 ## Why Google Cloud for forecasting at any scale
 
 | Pillar | What it means for you | Proof in this repository |
@@ -303,15 +321,16 @@ Every run is a validated [`RunConfig`](https://github.com/statmike/scale-forecas
 
 - **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`).
+- **Glass-box auto-forecaster & multi-branch `autofocus`:** Compile an explained `RunConfig` from any DataFrame or BigQuery table (`Forecaster.build_config()` / `--init-config`) across 4 exposure tiers (`first_light`, `wide_field`, `deep_sky`, `deep_field`) with optional user scope pins and approximate 7-runtime duration/cost estimates (`predict_run_duration`), or run a multi-branch `autofocus=True` tournament (`Forecaster.auto()`) whose pure-Python decision rules were evolved with **AlphaEvolve on Gemini Enterprise** across 20 synthetic ground-truth test panels and 9 public open-data benchmarks ([`docs/auto_forecaster.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/auto_forecaster.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)).
 
 ---
 
-## Learn by doing (11 notebooks across 4 tracks)
+## Learn by doing (12 notebooks across 4 tracks)
 
 All notebooks in [`notebooks/`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/README.md) include committed outputs and one-click **Colab Enterprise** launch links:
 
-- **Track 1 — Local sandbox & plugins (no GCP setup):** [`00_model_playground.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/00_model_playground.ipynb) · [`09_custom_models_and_metrics.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/09_custom_models_and_metrics.ipynb)
+- **Track 1 — Local sandbox, auto-forecaster & plugins (no GCP setup):** [`00_model_playground.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/00_model_playground.ipynb) · [`11_auto_forecaster_and_autofocus.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/11_auto_forecaster_and_autofocus.ipynb) · [`09_custom_models_and_metrics.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/09_custom_models_and_metrics.ipynb)
 - **Track 2 — Cloud runtimes:** [`01_bigquery_native_sql.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/01_bigquery_native_sql.ipynb) · [`02_vertex_and_gce_vms.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/02_vertex_and_gce_vms.ipynb) · [`03_spark_serverless_and_connect.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/03_spark_serverless_and_connect.ipynb) · [`04_ray_on_vertex_gpu.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/04_ray_on_vertex_gpu.ipynb)
 - **Track 3 — Covariates, hierarchy, HPO & ensembles:** [`05_covariates_and_global_models.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/05_covariates_and_global_models.ipynb) · [`06_hierarchical_reconciliation.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/06_hierarchical_reconciliation.ipynb) · [`07_hpo_backtesting_and_ensembles.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/07_hpo_backtesting_and_ensembles.ipynb)
 - **Track 4 — Master multi-engine DAG & operations:** [`08_multi_engine_master_workflow.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/08_multi_engine_master_workflow.ipynb) · [`10_registry_operations_and_scale.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/10_registry_operations_and_scale.ipynb)
@@ -321,7 +340,7 @@ All notebooks in [`notebooks/`](https://github.com/statmike/scale-forecasting/bl
 
 ## Where next
 
-- **Start here:** [Getting started](https://github.com/statmike/scale-forecasting/blob/main/docs/getting_started.md) · [Platform overview](https://github.com/statmike/scale-forecasting/blob/main/docs/overview.md) · [Forecaster workbench](https://github.com/statmike/scale-forecasting/blob/main/docs/forecaster_workbench.md) · [AI agents, skills & MCP](https://github.com/statmike/scale-forecasting/blob/main/docs/agent_and_mcp_guide.md) · [Choosing a runtime](https://github.com/statmike/scale-forecasting/blob/main/docs/choosing_a_runtime.md) · [Cost estimates & controls](https://github.com/statmike/scale-forecasting/blob/main/docs/cost_estimates.md) · [Why Google Cloud](https://github.com/statmike/scale-forecasting/blob/main/docs/why_google_cloud.md) · [FAQ](https://github.com/statmike/scale-forecasting/blob/main/docs/faq.md) · [Glossary](https://github.com/statmike/scale-forecasting/blob/main/docs/glossary.md) · [Documentation map](https://github.com/statmike/scale-forecasting/blob/main/docs/README.md)
+- **Start here:** [Getting started](https://github.com/statmike/scale-forecasting/blob/main/docs/getting_started.md) · [Platform overview](https://github.com/statmike/scale-forecasting/blob/main/docs/overview.md) · [Auto-forecaster & `autofocus`](https://github.com/statmike/scale-forecasting/blob/main/docs/auto_forecaster.md) · [Forecaster workbench](https://github.com/statmike/scale-forecasting/blob/main/docs/forecaster_workbench.md) · [AI agents, skills & MCP](https://github.com/statmike/scale-forecasting/blob/main/docs/agent_and_mcp_guide.md) · [Choosing a runtime](https://github.com/statmike/scale-forecasting/blob/main/docs/choosing_a_runtime.md) · [Cost estimates & controls](https://github.com/statmike/scale-forecasting/blob/main/docs/cost_estimates.md) · [Why Google Cloud](https://github.com/statmike/scale-forecasting/blob/main/docs/why_google_cloud.md) · [FAQ](https://github.com/statmike/scale-forecasting/blob/main/docs/faq.md) · [Glossary](https://github.com/statmike/scale-forecasting/blob/main/docs/glossary.md) · [Documentation map](https://github.com/statmike/scale-forecasting/blob/main/docs/README.md)
 - **Reference:** [Compute runtimes](https://github.com/statmike/scale-forecasting/blob/main/docs/runtimes_reference.md) · [Configuration](https://github.com/statmike/scale-forecasting/blob/main/docs/configuration_reference.md) · [Models & ensembles](https://github.com/statmike/scale-forecasting/blob/main/docs/models_reference.md) · [Evaluation metrics](https://github.com/statmike/scale-forecasting/blob/main/docs/metrics_reference.md) · [Output schemas & views](https://github.com/statmike/scale-forecasting/blob/main/docs/output_schemas.md)
 - **Operate & extend:** [Python SDK (`Forecaster`)](https://github.com/statmike/scale-forecasting/blob/main/docs/using_the_sdk.md) · [Running & reviewing](https://github.com/statmike/scale-forecasting/blob/main/docs/running_and_reviewing.md) · [Operations & repair](https://github.com/statmike/scale-forecasting/blob/main/docs/operations.md) · [Quota & 100k scale](https://github.com/statmike/scale-forecasting/blob/main/docs/quota_and_scale.md) · [System validation ledger](https://github.com/statmike/scale-forecasting/blob/main/docs/validation.md) · [API reference](https://statmike.github.io/scale-forecasting/api/)
 

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

@@ -16,38 +16,40 @@
 
 ```mermaid
 flowchart LR
-    subgraph IN["Your data in BigQuery"]
-        SRC["Source table<br/>series · timestamps · covariates"]
+    subgraph PREP["1. Data, Config & Launch"]
+        direction TB
+        SRC["Your Data (BigQuery or DataFrame)<br/>series · timestamps · covariates · hierarchies"]
+        CFG["Create a Config File (JSON)<br/>Hand-crafted OR use Auto-Forecaster"]
+        LAUNCH["Launch & Orchestrate<br/>SDK · CLI · Notebooks · Airflow · Batch · MCP"]
+        R["Parallel Family DAG Router<br/>Routes active families (1 job or pool per family)<br/>statistical · ml · deep_learning · automl · native"]
+        SRC --> CFG --> LAUNCH --> R
     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"]
+    subgraph RUN["2. Zero-Idle Compute on Google Cloud (Chosen per Family)"]
+        direction LR
+        S["Serverless Spark or Spark Cluster"]
         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"]
+        G["Compute Engine Single VM (Self-Deleting)"]
+        K["GKE (Indexed Job or Ray · Scale-to-Zero)"]
+        A["Vertex AI AutoML & Tabular Workflows"]
+        B["BigQuery ML (CREATE MODEL · 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"]
+    subgraph OUT["3. Governed Results & Trust in BigQuery"]
+        direction TB
+        REG["5 BigQuery Registry Tables<br/>forecasts · backtests · metadata<br/>runs · jobs"]
+        VIEWS["5 Analytical SQL Views<br/>Leaderboards · Backtest Coverage<br/>Run & Job Summaries"]
+        USE["Practitioner Trust & Consumption<br/>7-Question Assessment · FVA Ladder<br/>Attributions · SDK · Looker"]
+        REG --> VIEWS --> USE
     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
+    PREP --> RUN --> OUT
 
-    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
+    classDef data fill:#E8F0FE,stroke:#4285F4,stroke-width:2px,color:#174EA6
+    classDef config fill:#FEF7E0,stroke:#F9AB00,stroke-width:2px,color:#7A5A00
+    classDef route fill:#FCE8E6,stroke:#EA4335,stroke-width:2px,color:#A50E0E
+    classDef compute fill:#E6F4EA,stroke:#34A853,stroke-width:2px,color:#0D652D
     class SRC,REG,VIEWS,USE data
-    class CFG config
+    class CFG,LAUNCH config
     class R route
     class S,RY,V,G,K,A,B compute
 ```
@@ -80,11 +82,12 @@ import scale_forecasting as sf
 from scale_forecasting import playground
 
 result = playground.run_one(model="theta", horizon=14, backtest=True)
+auto_run = sf.Forecaster.auto(playground.sample_data(n_series=3), tier="first_light", autofocus=True)
 plan = sf.Forecaster.from_file("configs/ensemble_demo.json").dry_run()
-print(result.metrics["wape"], plan.run_id)
+print(result.metrics["wape"], auto_run.leaderboard_df().iloc[0]["model_type"], plan.run_id)
 ```
 
-Continue in [`notebooks/00_model_playground.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/00_model_playground.ipynb) or [Getting started (`docs/getting_started.md`)](https://github.com/statmike/scale-forecasting/blob/main/docs/getting_started.md).
+Continue in [`notebooks/00_model_playground.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/00_model_playground.ipynb), [`notebooks/11_auto_forecaster_and_autofocus.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/11_auto_forecaster_and_autofocus.ipynb), [Auto-forecaster & `autofocus` (`docs/auto_forecaster.md`)](https://github.com/statmike/scale-forecasting/blob/main/docs/auto_forecaster.md), or [Getting started (`docs/getting_started.md`)](https://github.com/statmike/scale-forecasting/blob/main/docs/getting_started.md).
 
 ### Journey 2 — Deploy to your Google Cloud project in 15 minutes
 
@@ -153,6 +156,23 @@ Every run is a validated [`RunConfig`](https://github.com/statmike/scale-forecas
 
 ---
 
+## Write a `RunConfig` by hand — or let the Glass-Box Auto-Forecaster compile & refine it
+
+You can always author a [`RunConfig`](https://github.com/statmike/scale-forecasting/blob/main/docs/configuration_reference.md) JSON file directly and run it with any method in this repository. Or, when starting on a new dataset, let **`Forecaster.build_config()`** and **`Forecaster.auto()`** profile your data (`Forecaster.profile_data()`), compile a standard `RunConfig` across **4 exposure tiers** (`first_light`, `wide_field`, `deep_sky`, `deep_field`), optionally refine it with multi-branch **`autofocus`**, and answer the 7 core questions every forecaster asks (`f.practitioner_assessment_df()`, `f.compare_models()`):
+
+| What Forecasters Care About | Manual Trial-and-Error | Typical Black-Box AutoML | `scale-forecasting` Glass-Box Auto-Forecaster & `autofocus` |
+| :--- | :--- | :--- | :--- |
+| **Transparency & ownership** | Full control, but days of hand-tuning JSON/code across model families. | Swallows your data and hides *why* models or features were picked. | **100% glass-box:** Prints a plain-English rationale table (`bp.explain()`) and saves a standard, editable `RunConfig` JSON you own (`--init-config`). |
+| **User constraints (`[PINNED]`)** | You wire every constraint and fallback by hand. | Take-it-or-leave-it automation; hard to lock specific families or metrics. | **Pin any dial:** Lock `allowed_families`, `models`, `decision_metric`, `n_folds`, `hpo`, `ensemble`, or `max_minutes`; `autofocus` optimizes strictly around your pins. |
+| **Compute & scale awareness (`n_series`)** | You manually size VMs, GPUs, and worker pools for 10 vs. 100k series. | Assumes a single Python machine or a single fixed cluster. | **Co-designs models + 7 cloud runtimes:** Adapts portfolios from `micro` (`<15` series) to `hyperscale` (`25,000+` series) across `local`, `bigquery`, `spark`, `ray`, `vertex`, `gce`, and `gke`. |
+| **Iterative learning & compute reuse** | Re-running a tweak refits every model from scratch. | Runs a single fixed pipeline or brute-forces everything upfront. | **Multi-branch `autofocus` DAG + cell borrowing:** Tests isolated upgrades (`2A` scale/outliers, `2B` feature pruning/horizon, `2C` intermittent/hierarchy/stockouts), **borrows Pass 1's finished models**, and guarantees non-degradation via the **Champion Ratchet**. |
+| **"Earn your complexity" proof** | Easy to overfit noisy features without noticing a simple model was better. | Often crowns a heavy model without proving lift over simple baselines. | **4-anchor Baseline Ladder & 7-Question Assessment:** Benchmarks against seasonal naive, plain univariate (`theta`), and dual-mode foundation baselines (`@univariate` vs. `@global_cov_all`). If a simple univariate model wins, it becomes champion and lists the complex models it beat (`f.baseline_value_df()`, `f.practitioner_assessment_df()`). |
+| **How the policy was built** | Individual intuition and ad-hoc rules of thumb. | Fixed vendor heuristics or slow, costly runtime LLM calls. | **Evolved with AlphaEvolve on Gemini Enterprise (`26.08 -> 74.82` fitness across 20 synthetic DGPs + 9 public benchmarks)** and compiled into deterministic pure Python (**zero LLM calls at runtime**). |
+
+Full guide and interactive notebook: **[Glass-Box Auto-Forecaster & `autofocus` (`docs/auto_forecaster.md`)](https://github.com/statmike/scale-forecasting/blob/main/docs/auto_forecaster.md)** and **[`notebooks/11_auto_forecaster_and_autofocus.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/11_auto_forecaster_and_autofocus.ipynb)**.
+
+---
+
 ## Why Google Cloud for forecasting at any scale
 
 | Pillar | What it means for you | Proof in this repository |
@@ -178,15 +198,16 @@ Every run is a validated [`RunConfig`](https://github.com/statmike/scale-forecas
 
 - **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`).
+- **Glass-box auto-forecaster & multi-branch `autofocus`:** Compile an explained `RunConfig` from any DataFrame or BigQuery table (`Forecaster.build_config()` / `--init-config`) across 4 exposure tiers (`first_light`, `wide_field`, `deep_sky`, `deep_field`) with optional user scope pins and approximate 7-runtime duration/cost estimates (`predict_run_duration`), or run a multi-branch `autofocus=True` tournament (`Forecaster.auto()`) whose pure-Python decision rules were evolved with **AlphaEvolve on Gemini Enterprise** across 20 synthetic ground-truth test panels and 9 public open-data benchmarks ([`docs/auto_forecaster.md`](https://github.com/statmike/scale-forecasting/blob/main/docs/auto_forecaster.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)).
 
 ---
 
-## Learn by doing (11 notebooks across 4 tracks)
+## Learn by doing (12 notebooks across 4 tracks)
 
 All notebooks in [`notebooks/`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/README.md) include committed outputs and one-click **Colab Enterprise** launch links:
 
-- **Track 1 — Local sandbox & plugins (no GCP setup):** [`00_model_playground.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/00_model_playground.ipynb) · [`09_custom_models_and_metrics.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/09_custom_models_and_metrics.ipynb)
+- **Track 1 — Local sandbox, auto-forecaster & plugins (no GCP setup):** [`00_model_playground.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/00_model_playground.ipynb) · [`11_auto_forecaster_and_autofocus.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/11_auto_forecaster_and_autofocus.ipynb) · [`09_custom_models_and_metrics.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/09_custom_models_and_metrics.ipynb)
 - **Track 2 — Cloud runtimes:** [`01_bigquery_native_sql.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/01_bigquery_native_sql.ipynb) · [`02_vertex_and_gce_vms.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/02_vertex_and_gce_vms.ipynb) · [`03_spark_serverless_and_connect.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/03_spark_serverless_and_connect.ipynb) · [`04_ray_on_vertex_gpu.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/04_ray_on_vertex_gpu.ipynb)
 - **Track 3 — Covariates, hierarchy, HPO & ensembles:** [`05_covariates_and_global_models.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/05_covariates_and_global_models.ipynb) · [`06_hierarchical_reconciliation.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/06_hierarchical_reconciliation.ipynb) · [`07_hpo_backtesting_and_ensembles.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/07_hpo_backtesting_and_ensembles.ipynb)
 - **Track 4 — Master multi-engine DAG & operations:** [`08_multi_engine_master_workflow.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/08_multi_engine_master_workflow.ipynb) · [`10_registry_operations_and_scale.ipynb`](https://github.com/statmike/scale-forecasting/blob/main/notebooks/10_registry_operations_and_scale.ipynb)
@@ -196,7 +217,7 @@ All notebooks in [`notebooks/`](https://github.com/statmike/scale-forecasting/bl
 
 ## Where next
 
-- **Start here:** [Getting started](https://github.com/statmike/scale-forecasting/blob/main/docs/getting_started.md) · [Platform overview](https://github.com/statmike/scale-forecasting/blob/main/docs/overview.md) · [Forecaster workbench](https://github.com/statmike/scale-forecasting/blob/main/docs/forecaster_workbench.md) · [AI agents, skills & MCP](https://github.com/statmike/scale-forecasting/blob/main/docs/agent_and_mcp_guide.md) · [Choosing a runtime](https://github.com/statmike/scale-forecasting/blob/main/docs/choosing_a_runtime.md) · [Cost estimates & controls](https://github.com/statmike/scale-forecasting/blob/main/docs/cost_estimates.md) · [Why Google Cloud](https://github.com/statmike/scale-forecasting/blob/main/docs/why_google_cloud.md) · [FAQ](https://github.com/statmike/scale-forecasting/blob/main/docs/faq.md) · [Glossary](https://github.com/statmike/scale-forecasting/blob/main/docs/glossary.md) · [Documentation map](https://github.com/statmike/scale-forecasting/blob/main/docs/README.md)
+- **Start here:** [Getting started](https://github.com/statmike/scale-forecasting/blob/main/docs/getting_started.md) · [Platform overview](https://github.com/statmike/scale-forecasting/blob/main/docs/overview.md) · [Auto-forecaster & `autofocus`](https://github.com/statmike/scale-forecasting/blob/main/docs/auto_forecaster.md) · [Forecaster workbench](https://github.com/statmike/scale-forecasting/blob/main/docs/forecaster_workbench.md) · [AI agents, skills & MCP](https://github.com/statmike/scale-forecasting/blob/main/docs/agent_and_mcp_guide.md) · [Choosing a runtime](https://github.com/statmike/scale-forecasting/blob/main/docs/choosing_a_runtime.md) · [Cost estimates & controls](https://github.com/statmike/scale-forecasting/blob/main/docs/cost_estimates.md) · [Why Google Cloud](https://github.com/statmike/scale-forecasting/blob/main/docs/why_google_cloud.md) · [FAQ](https://github.com/statmike/scale-forecasting/blob/main/docs/faq.md) · [Glossary](https://github.com/statmike/scale-forecasting/blob/main/docs/glossary.md) · [Documentation map](https://github.com/statmike/scale-forecasting/blob/main/docs/README.md)
 - **Reference:** [Compute runtimes](https://github.com/statmike/scale-forecasting/blob/main/docs/runtimes_reference.md) · [Configuration](https://github.com/statmike/scale-forecasting/blob/main/docs/configuration_reference.md) · [Models & ensembles](https://github.com/statmike/scale-forecasting/blob/main/docs/models_reference.md) · [Evaluation metrics](https://github.com/statmike/scale-forecasting/blob/main/docs/metrics_reference.md) · [Output schemas & views](https://github.com/statmike/scale-forecasting/blob/main/docs/output_schemas.md)
 - **Operate & extend:** [Python SDK (`Forecaster`)](https://github.com/statmike/scale-forecasting/blob/main/docs/using_the_sdk.md) · [Running & reviewing](https://github.com/statmike/scale-forecasting/blob/main/docs/running_and_reviewing.md) · [Operations & repair](https://github.com/statmike/scale-forecasting/blob/main/docs/operations.md) · [Quota & 100k scale](https://github.com/statmike/scale-forecasting/blob/main/docs/quota_and_scale.md) · [System validation ledger](https://github.com/statmike/scale-forecasting/blob/main/docs/validation.md) · [API reference](https://statmike.github.io/scale-forecasting/api/)
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "scale-forecasting"
-version = "1.2.0"
+version = "1.3.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."
 dynamic = ["readme"]
 # Two different pins, on purpose. `requires-python` is what *the package* installs on: the pure

{scale_forecasting-1.2.0 → scale_forecasting-1.3.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.2.0"
+    __version__ = "1.3.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
@@ -150,6 +150,40 @@ _LAZY: dict[str, tuple[str, str]] = {
     "build_report_payload": (".report", "build_report_payload"),
     "render_html_report": (".report", "render_html_report"),
     "export_report": (".report", "export_report"),
+    # Glass-Box Auto-Forecaster, Duration Predictor & DGP Benchmarks.
+    "EXPOSURE_TIERS": (".auto", "EXPOSURE_TIERS"),
+    "SCALE_REGIMES": (".auto", "SCALE_REGIMES"),
+    "classify_scale_regime": (".auto", "classify_scale_regime"),
+    "select_default_baselines": (".auto", "select_default_baselines"),
+    "select_hierarchy_reconciliation_methods": (
+        ".auto",
+        "select_hierarchy_reconciliation_methods",
+    ),
+    "ConfigBlueprint": (".auto", "ConfigBlueprint"),
+    "AutofocusPassRecord": (".auto", "AutofocusPassRecord"),
+    "NextLoopPreview": (".auto", "NextLoopPreview"),
+    "PanelAutoProfile": (".auto", "PanelAutoProfile"),
+    "inspect_panel_for_auto": (".auto", "inspect_panel_for_auto"),
+    "build_config": (".auto", "build_config"),
+    "auto_forecast": (".auto", "auto_forecast"),
+    "DurationEstimate": (".profiling.duration", "DurationEstimate"),
+    "FamilyDurationBreakdown": (".profiling.duration", "FamilyDurationBreakdown"),
+    "DurationCalibration": (".profiling.duration", "DurationCalibration"),
+    "predict_run_duration": (".profiling.duration", "predict_run_duration"),
+    "calibrate_duration_from_frames": (".profiling.duration", "calibrate_duration_from_frames"),
+    "calibrate_duration_from_registry": (".profiling.duration", "calibrate_duration_from_registry"),
+    "BENCHMARK_NAMES": (".benchmarks", "BENCHMARK_NAMES"),
+    "BenchmarkSpec": (".benchmarks", "BenchmarkSpec"),
+    "BenchmarkDataset": (".benchmarks", "BenchmarkDataset"),
+    "list_benchmarks": (".benchmarks", "list_benchmarks"),
+    "benchmark_catalog": (".benchmarks", "benchmark_catalog"),
+    "load_benchmark": (".benchmarks", "load_benchmark"),
+    "PUBLIC_BENCHMARK_NAMES": (".benchmarks", "PUBLIC_BENCHMARK_NAMES"),
+    "PUBLIC_BENCHMARK_SPECS": (".benchmarks", "PUBLIC_BENCHMARK_SPECS"),
+    "PublicBenchmarkSpec": (".benchmarks", "PublicBenchmarkSpec"),
+    "list_public_benchmarks": (".benchmarks", "list_public_benchmarks"),
+    "public_benchmark_catalog": (".benchmarks", "public_benchmark_catalog"),
+    "fetch_public_benchmark": (".benchmarks", "fetch_public_benchmark"),
 }
 
 __all__ = [
@@ -174,6 +208,34 @@ __all__ = [
 
 if TYPE_CHECKING:  # so IDEs / type-checkers see the lazy names as real imports (re-exported below)
     from .agent_surfaces import probe_environment  # noqa: F401
+    from .auto import (  # noqa: F401
+        EXPOSURE_TIERS,
+        SCALE_REGIMES,
+        AutofocusPassRecord,
+        ConfigBlueprint,
+        NextLoopPreview,
+        PanelAutoProfile,
+        auto_forecast,
+        build_config,
+        classify_scale_regime,
+        inspect_panel_for_auto,
+        select_default_baselines,
+        select_hierarchy_reconciliation_methods,
+    )
+    from .benchmarks import (  # noqa: F401
+        BENCHMARK_NAMES,
+        PUBLIC_BENCHMARK_NAMES,
+        PUBLIC_BENCHMARK_SPECS,
+        BenchmarkDataset,
+        BenchmarkSpec,
+        PublicBenchmarkSpec,
+        benchmark_catalog,
+        fetch_public_benchmark,
+        list_benchmarks,
+        list_public_benchmarks,
+        load_benchmark,
+        public_benchmark_catalog,
+    )
     from .dag import DagNode  # noqa: F401
     from .diagnostics import (  # noqa: F401
         compute_anomalies,
@@ -205,6 +267,14 @@ if TYPE_CHECKING:  # so IDEs / type-checkers see the lazy names as real imports
     from .mcp import McpServer  # noqa: F401
     from .models import get_model, list_models  # noqa: F401
     from .playground import metric_catalog, model_catalog  # noqa: F401
+    from .profiling.duration import (  # noqa: F401
+        DurationCalibration,
+        DurationEstimate,
+        FamilyDurationBreakdown,
+        calibrate_duration_from_frames,
+        calibrate_duration_from_registry,
+        predict_run_duration,
+    )
     from .reconciliation import (  # noqa: F401
         HierarchySpec,
         build_hierarchy,