scale-forecasting

Enterprise time-series forecasting on Google Cloud — from 10 series on a laptop to 100,000+ in BigQuery, with one JSON configuration and no idle compute.

37 models · 5 families · 21 evaluation metrics · 7 Google Cloud runtimes · 5 Analytical SQL Views · validated at 100k series

What you just found

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 & 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.

Three ways to start

Journey 1 — Try it locally in 5 minutes (no cloud, no credentials)

Install the pure offline package (or clone the repo and run uv sync) to fit models, run backtests, and inspect metrics in memory on your machine:

pip install scale-forecasting
python -m scale_forecasting.playground --list
python -m scale_forecasting.playground --model theta --backtest --horizon 14

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"], auto_run.leaderboard_df().iloc[0]["model_type"], plan.run_id)

Continue in notebooks/00_model_playground.ipynb, notebooks/11_auto_forecaster_and_autofocus.ipynb, Auto-forecaster & autofocus (docs/auto_forecaster.md), or Getting started (docs/getting_started.md).

Journey 2 — Deploy to your Google Cloud project in 15 minutes

Provision the BigQuery dataset, Cloud Storage buckets, least-privilege service accounts, VPC networking, container image, Colab Enterprise runtime template, and 100,000-series seed dataset with two Terraform stages:

cd terraform/bootstrap && terraform init
terraform apply -var="project_id=YOUR_PROJECT_ID" -var="billing_account=YOUR_BILLING_ID"

cd ../main && terraform init
terraform apply -var="project_id=YOUR_PROJECT_ID"

Estimated cost & ongoing services: One-time provisioning (Cloud Build image build + Dataproc Serverless 100k seed batch) costs an estimated ~$0.15–$0.50. At rest, datasets, buckets, VPC networking, and service accounts have no running compute cost (only standard Cloud Storage and BigQuery storage rates for stored bytes). Forecast runs bill only while batches, VMs, pods, or queries execute. Always-on disclosure: Cloud Composer 3 (create_composer = false by default) and standing GKE clusters incur continuous hourly charges while provisioned. See docs/deploying_on_gcp.md and terraform/README.md.

Journey 3 — Run 100,000+ series on Google Cloud

Launch any declarative configuration from the CLI, Python SDK, or a generated Cloud Composer 3 DAG:

# Run directly from the CLI or stage native gcloud / kubectl / bq / ray commands
python -m scale_forecasting.main --config configs/ensemble_demo.json
python -m scale_forecasting.main --config configs/spark_serverless_100k.json --emit-airflow dags/sf_100k.py

Full operator loop: Running and reviewing (docs/running_and_reviewing.md) and Platform overview (docs/overview.md).

AI agents, portable skills & built-in MCP server

scale-forecasting is ready out of the box for Google Antigravity (agy CLI & IDE), Claude Code, Cursor, VS Code Copilot, and Windsurf — shipping a portable SKILL.md (auto-discovered via .agents/skills.json), an Antigravity plugin.json + mcp_config.json, a built-in MCP server (python -m scale_forecasting.mcp), a Draft 2020-12 RunConfig JSON Schema, and llms.txt / llms-full.txt compiled directly from code (make agent-surfaces):

# Probe installed extras, available models, and SF_* readiness:
python -m scale_forecasting.agent_surfaces --probe-env

# Launch Google Antigravity CLI (auto-discovers .agents/skills/ & AGENTS.md) or register MCP:
agy
claude mcp add scale-forecasting -- python3 -m scale_forecasting.mcp

Full setup and architectural guide: AI Agents, Portable Skills & Built-in MCP Server (docs/agent_and_mcp_guide.md).

One configuration, every engine

Every run is a validated RunConfig (such as configs/ensemble_demo.json). To move a model family between Dataproc Serverless, Ray, Vertex AI CustomJob, Compute Engine, or GKE, change compute.families.<family>.runtime — nothing else:

{
  "run_name": "hybrid_stacked_ensemble",
  "data": {"source_table": "source_series_iceberg", "series_limit": 100, "horizon": 14},
  "models": ["theta", "holtwinters", "xgboost", "arima_plus"],
  "compute": {
    "families": {
      "statistical": {"runtime": "spark"},
      "ml": {"runtime": "spark"}
    }
  },
  "backtest": {"enabled": true, "scheme": "expanding", "n_folds": 3, "decision_metric": "wape"},
  "ensemble": {"enabled": true, "strategies": ["mean", "inverse_error", "nnls", "xgb"]}
}

Write a RunConfig by hand — or let the Glass-Box Auto-Forecaster compile & refine it

You can always author a RunConfig 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()):

Full guide and interactive notebook: Glass-Box Auto-Forecaster & autofocus (docs/auto_forecaster.md) and notebooks/11_auto_forecaster_and_autofocus.ipynb.

Why Google Cloud for forecasting at any scale

What's inside

• 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).
• 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).
• 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).

Learn by doing (12 notebooks across 4 tracks)

All notebooks in notebooks/ include committed outputs and one-click Colab Enterprise launch links:

• Track 1 — Local sandbox, auto-forecaster & plugins (no GCP setup): 00_model_playground.ipynb · 11_auto_forecaster_and_autofocus.ipynb · 09_custom_models_and_metrics.ipynb
• Track 2 — Cloud runtimes: 01_bigquery_native_sql.ipynb · 02_vertex_and_gce_vms.ipynb · 03_spark_serverless_and_connect.ipynb · 04_ray_on_vertex_gpu.ipynb
• Track 3 — Covariates, hierarchy, HPO & ensembles: 05_covariates_and_global_models.ipynb · 06_hierarchical_reconciliation.ipynb · 07_hpo_backtesting_and_ensembles.ipynb
• Track 4 — Master multi-engine DAG & operations: 08_multi_engine_master_workflow.ipynb · 10_registry_operations_and_scale.ipynb
• Team lab: Hands-on workshop guide (docs/workshop.md)

Where next

• Start here: Getting started · Platform overview · Auto-forecaster & autofocus · Forecaster workbench · AI agents, skills & MCP · Choosing a runtime · Cost estimates & controls · Why Google Cloud · FAQ · Glossary · Documentation map
• Reference: Compute runtimes · Configuration · Models & ensembles · Evaluation metrics · Output schemas & views
• Operate & extend: Python SDK (Forecaster) · Running & reviewing · Operations & repair · Quota & 100k scale · System validation ledger · API reference

License

Apache-2.0 — see LICENSE.

This is not an officially supported Google product. It is built on Google products and is neither endorsed nor supported by Google.