TimeCopilot/foundationforecast

---

Why?

Forecasting and time series have entered their foundation era. But, just like in the LLM space, different models bring different inductive biases and perform differently across domains, datasets, and even horizons.

The world already uses different LLMs for different use cases. We're seeing the same thing in forecasting: there is no single model that dominates everywhere. Results change with the data distribution and forecasting horizon, as we've seen in Impermanent and other benchmarks such as GIFT-Eval and FEV.

At the same time, every lab also ships its own API, dependencies, data conventions, and learning curve. That fragmentation makes foundation models hard to compare fairly, and even harder to use together in production, especially when you need exogenous variables (covariates): holidays, prices, weather, or other features known over the forecast horizon, each with its own input format.

FoundationForecast removes that friction: one FoundationForecast class, one data format, and the same methods: forecast, cross_validation, and detect_anomalies, across time series foundation models—including known-future covariates on supported checkpoints. ✨

Developed with 💙 by the TimeCopilot crew.

---

Quick example

import pandas as pd
from foundationforecast import FoundationForecast
from foundationforecast.models import Chronos, Toto

df = pd.read_csv(
    "https://timecopilot.s3.amazonaws.com/public/data/entsoe_4markets_8w.csv",
    parse_dates=["ds"],
)

ff = FoundationForecast(
    models=[
        Chronos(repo_id="amazon/chronos-bolt-tiny", alias="Chronos"),
        Toto(context_length=512, alias="Toto"),
    ]
)

fcst_df = ff.forecast(df, h=24, level=[90])
cv_df = ff.cross_validation(df, h=24, level=[90])
anomalies_df = ff.detect_anomalies(df, level=99)

ff.plot(df=df, forecasts_df=fcst_df)

Your DataFrame needs three columns: unique_id, ds, and y. For best results, ensure ds is a proper datetime dtype (e.g., pass parse_dates=["ds"] when reading) or an ISO-8601 string so sorting is correct; cross-validation/anomaly detection will also convert ds to datetime internally where needed. If you omit freq, it is inferred from regular timestamps in ds (pass freq= when intervals are irregular).

---

Highlights

• 📐 Conformal prediction intervals. Use ConformalIntervals to calibrate any model's level / quantiles from point-forecast errors, with optional finite-sample correction; see the guide and example notebook.

• 📈 Exogenous variables (covariates). Pass known-future features with X_df on forecast() (and exog columns in df for cross_validation()). Native support on Chronos-2, TimesFM-3, TimeGPT, T0, TimeH2O, TiRex-2, and Timestral; see Exogenous variables and the example notebook.

• 💸 Full GIFT-Eval replication for $37. 16 models, 97 dataset configurations each, in about 34 GPU-hours, every model with an official submission within 2% of its leaderboard MASE/CRPS. TimesFM 3 is the most accurate, for under $8. Read the writeup.

• 🎯 Benchmark replication in CI. Wrappers are regression-tested against official leaderboard submissions: experiments/gift-eval (GIFT-Eval MASE/CRPS on Modal GPU) and experiments/fev-bench (fev-bench test_error on known-dynamic tasks). CI re-runs these checks on every change.

• 🚀 GPU-native. Automatically runs on GPU when available, without model-specific device configuration.

• 🔮 Prophet adapter. Swap Prophet() for FoundationProphet(model=Chronos()) in existing Prophet pipelines: fit, make_future_dataframe, predict, plot and Prophet's diagnostics keep working, with any foundation model underneath. Install with foundationforecast[prophet]; see the guide and example notebook.

  

---

Supported models

Every model supports forecast, cross-validation, and anomaly detection through the same API. Intervals means prediction intervals via level or quantile forecasts. Exogenous marks native known-future exog (X_df on forecast(), exog columns in df for cross_validation()) for that wrapper when using a supported checkpoint; see ¶. Finetuning marks models that can adapt to your data at inference time. License is the weight/checkpoint license on the default Hugging Face repo (or provider terms for hosted APIs). See the note below for production use.

Pass any Hugging Face repo_id (or local checkpoint path) supported by the underlying model class.

Provider	Model	Forecast	CV	Anomalies	Intervals	Exogenous	Finetuning	License
	Chronos	✓	✓	✓	✓	✓¶	✓	Apache-2.0
	FlowState	✓	✓	✓	✓			Apache-2.0
	Kumo-Forecast	✓	✓	✓	✓‡‡			Apache-2.0
	Moirai	✓	✓	✓	✓			CC-BY-NC-4.0
	PatchTST-FM	✓	✓	✓	✓			CC-BY-NC-SA-4.0
	Sundial	✓	✓	✓	✓			Apache-2.0
	T0	✓	✓	✓	✓	✓		Apache-2.0†
	Tabby	✓	✓	✓	✓			CC-BY-NC-4.0
	TabPFN	✓	✓	✓	✓			TabPFN NC‡
	Tafsut	✓	✓	✓	✓			MIT
	TiRex	✓	✓	✓	✓	✓¶		Community / Apache-2.0
	TimeH2O	✓	✓	✓	✓	✓¶		H2O.ai NC#
	TimeGPT	✓	✓	✓	✓	✓	✓	Nixtla API§
	TimesFM	✓	✓	✓	✓	✓¶		Apache-2.0
	Timestral	✓	✓	✓	✓	✓¶		Modified MIT∥
	Toto	✓	✓	✓	✓			Apache-2.0

‡‡ Intervals (conformal only): Kumo is a point forecaster; level / quantiles require prediction_intervals=ConformalIntervals(...) and otherwise raise a ValueError. See Conformal prediction.

Licenses verified against Hugging Face model cards. Check the model card for your repo_id when in doubt.

¶ Exogenous (native): Chronos with repo_id containing chronos-2 (e.g. amazon/chronos-2); TimesFM with google/timesfm-3.0-pytorch; TimeGPT; T0 (theforecastingcompany/t0-alpha, t0-beta, t0-gamma); TimeH2O (h2oai/timeh2o-v1, not -tiny); TiRex-2 (NX-AI/TiRex-2 and other TiRex-2-* checkpoints, not TiRex 1.0); Timestral (mistralai/Timestral-*). Other hub models and other checkpoints in those families do not accept X_df under default exog_strategy. Set exog_strategy=False to ignore horizon exog in mixed FoundationForecast runs. See Exogenous variables.

What this means for production

• Apache-2.0, MIT: generally fine for commercial production (retain notices; T0† is also gated on Hugging Face: accept terms and set HF_TOKEN).
• CC-BY-NC-4.0 (Moirai, Tabby), CC-BY-NC-SA-4.0 (PatchTST-FM r1 checkpoints): non-commercial only; not for revenue-generating production without a separate agreement from the rights holder.
• Apache-2.0 / OpenMDW 1.0 (Granite PatchTST-FM r2): commercial-friendly; choose either license per the model card.
• TimesFM 3.0: weights for google/timesfm-3.0-pytorch are non-commercial; TimesFM 1.0–2.5 checkpoints remain Apache-2.0.
• TabPFN NC‡: TabPFN-2.6+ and TabPFN-3 weights are non-commercial; production requires a Prior Labs commercial license or API. First LOCAL use requires accepting terms at ux.priorlabs.ai (TABPFN_TOKEN). TabPFN-3 is LOCAL-only today.
• Community / Apache-2.0 (TiRex): TiRex 1.0 uses the NXAI Community License (commercial limits for large enterprises); TiRex 2.0 is Apache-2.0.
• H2O.ai NC# (TimeH2O): checkpoint weights are non-commercial and gated on Hugging Face (accept terms and set HF_TOKEN); inference code is Apache-2.0 via h2ofm.
• Nixtla API§: hosted service via NIXTLA_API_KEY; production under Nixtla terms/pricing, not open weights.
• Modified MIT∥ (Timestral): checkpoint weights use Mistral's Modified MIT license (companies above USD 20M monthly revenue need a commercial license from Mistral); inference code is Apache-2.0 via timecopilot-timestral.

FoundationForecast itself is Apache-2.0 regardless of which model you plug in.

Some models require specific Python versions (e.g. FlowState 3.11-3.13, TabPFN < 3.13, TimeH2O 3.12+). See the Model Hub for details and default checkpoints.

Example checkpoints & API model IDs

• Chronos: amazon/chronos-t5-{tiny,mini,small,base,large}, amazon/chronos-bolt-{tiny,mini,small,base}, amazon/chronos-2
• FlowState: ibm-research/flowstate, ibm-granite/granite-timeseries-flowstate-r1
• Kumo: nvidia/Kumo-Forecast (point forecasts; requires timecopilot-kumo-forecast>=0.1.0)
• Moirai: Salesforce/moirai-{1.0,1.1,2.0}-R-{small,base,large}, Salesforce/moirai-moe-1.0-R-*
• PatchTST-FM: ibm-research/patchtst-fm-r1, ibm-granite/granite-timeseries-patchtst-fm-r1, ibm-granite/granite-timeseries-patchtst-fm-r2 (r2 requires granite-tsfm>=0.3.9)
• Sundial: thuml/sundial-base-128m
• T0: theforecastingcompany/t0-alpha, theforecastingcompany/t0-beta, theforecastingcompany/t0-gamma (requires tfc-t0[torch]>=0.6.0)
• Tabby: paris-noah/Tabby (requires trust_remote_code; CC-BY-NC-4.0)
• TabPFN: default tabpfn-v2-regressor-2noar4o2.ckpt; TabPFN-3 via model_path="tabpfn-v3-regressor-v3_20260506_timeseries.ckpt" (LOCAL, TABPFN_TOKEN); or CLIENT mode with a Prior Labs API token
• Tafsut: Tafsut-FM/tafsut-univariate-base
• TiRex: NX-AI/TiRex, NX-AI/TiRex-2
• TimeH2O: h2oai/timeh2o-v1, h2oai/timeh2o-v1-tiny (requires h2ofm>=0.43.0, Python 3.12+)
• TimeGPT: pass model= to TimeGPT(), e.g. timegpt-1, timegpt-1-long-horizon, timegpt-2-mini, timegpt-2, timegpt-2-pro
• TimesFM: google/timesfm-{1.0-200m,2.0-500m,2.5-200m,3.0}-pytorch (3.0 weights are non-commercial)
• Timestral: mistralai/Timestral-{5M,28M,123M,209M} (requires timecopilot-timestral>=0.1.0)
• Toto: Datadog/Toto-Open-Base-1.0, Datadog/Toto-2.0-{4m,22m,313m,1B,2.5B}

---

News

Recent additions and checkpoints (newest first). See the changelog for full release notes.

When	What	Checkpoint / detail
Nov 2026	Kumo-Forecast	nvidia/Kumo-Forecast — NVIDIA's ~340M zero-shot forecaster; point forecasts only (use prediction_intervals=ConformalIntervals(...) for intervals); 512-step context, 72-step native horizon with autoregressive rollout; requires timecopilot-kumo-forecast>=0.1.0 (v0.1.20)
Nov 2026	Prophet adapter	FoundationProphet(model=...) — swap any foundation model into an existing Prophet pipeline (fit, predict, plot, diagnostics); install with foundationforecast[prophet] (v0.1.19)
Nov 2026	Conformal prediction	ConformalIntervals / prediction_intervals= — CV-calibrated level / quantiles from point-forecast errors; works on every model (v0.1.18)
Oct 2026	Tabby	paris-noah/Tabby — 99 native quantiles; trust_remote_code; CC-BY-NC-4.0; GIFT-Eval CI (v0.1.17)
Oct 2026	TimeH2O	h2oai/timeh2o-v1, h2oai/timeh2o-v1-tiny — requires h2ofm>=0.43.0 (Python 3.12+); native X_df; GIFT-Eval and fev-bench CI (v0.1.16)
Oct 2026	Timestral	mistralai/Timestral-{5M,28M,123M,209M} — requires timecopilot-timestral>=0.1.0; native X_df; GIFT-Eval and fev-bench CI (v0.1.15)
Oct 2026	T0 gamma	theforecastingcompany/t0-gamma — requires tfc-t0[torch]>=0.6.0; GIFT-Eval and fev-bench CI (v0.1.14)
Oct 2026	GIFT-Eval replication for $37	16 models on the full benchmark, each official submission matched within 2% MASE/CRPS; new Experiments docs section (v0.1.13)
Oct 2026	Known-future exog (X_df)	Native covariates on Chronos-2, TimesFM-3, TimeGPT, T0-beta, TiRex-2; fev-bench CI (v0.1.11)
Sep 2026	Quantile column naming	Stable -q-* suffixes from 100×q (≤3 dp quantiles, integer level only) (v0.1.10)
Sep 2026	Quantile interpolation	Arbitrary level / quantiles on fixed-knot models with edge clamping; removed level=0 sentinel (v0.1.9)
Sep 2026	Granite PatchTST-FM r2	ibm-granite/granite-timeseries-patchtst-fm-r2 — Apache-2.0 / OpenMDW; requires granite-tsfm>=0.3.9 (v0.1.8)
Sep 2026	T0 beta	theforecastingcompany/t0-beta — requires tfc-t0>=0.5.0 (v0.1.8)
Sep 2026	TiRex-2 zeroshot (GIFT-Eval CI)	NX-AI/TiRex-2-gifteval-zs added to gift-eval replication (v0.1.8)
Sep 2026	Shared panel processing	Faster multi-model forecasts via reused panel path across forecasters (v0.1.8)
Sep 2026	TabPFN-3 (LOCAL)	model_path="tabpfn-v3-regressor-v3_20260506_timeseries.ckpt" (v0.1.7)

---

Installation

Recommended: uv installs fast, locks dependencies reproducibly, and matches how this repo is developed and tested (especially useful with heavy ML stacks like torch and transformers).

uv add foundationforecast

Or with pip:

pip install foundationforecast

Requires Python 3.10+. Some models have additional version requirements; see the Model Hub.

Optional plotting support:

uv add "foundationforecast[plot]"
# or: pip install "foundationforecast[plot]"

Optional Prophet adapter:

uv add "foundationforecast[prophet]"
# or: pip install "foundationforecast[prophet]"

---

Exogenous variables quick example

import pandas as pd
from foundationforecast import FoundationForecast
from foundationforecast.models import Chronos, TimesFM

DATA = "https://timecopilot.s3.amazonaws.com/public/data/electricity_price"
df = pd.read_parquet(f"{DATA}/train.parquet")
X_df = pd.read_parquet(f"{DATA}/futr_exog.parquet")

ff = FoundationForecast(
    models=[
        Chronos(repo_id="amazon/chronos-2", alias="Chronos-2"),
        TimesFM(repo_id="google/timesfm-3.0-pytorch", alias="TimesFM-3"),
    ]
)

fcst_df = ff.forecast(df=df, h=24, X_df=X_df, level=[90])
ff.plot(df=df, forecasts_df=fcst_df)

---

Relationship to TimeCopilot

	FoundationForecast	TimeCopilot
Foundation models (Chronos, Moirai, …)	✓	✓
Unified forecast / CV / anomaly API	✓	✓
Statistical & ML baselines		✓
LLM agent & natural-language queries		✓
Ensembles & distributed inference		✓

Use FoundationForecast when you only need foundation models. Use TimeCopilot for the full forecasting agent.

---

Citation

To reference the software package:

@software{foundationforecast,
  title = {FoundationForecast: The API for time series foundation models},
  author = {Garza, Azul and Rosillo, Renée},
  year = {2026},
  url = {https://github.com/TimeCopilot/foundationforecast},
  license = {Apache-2.0},
}

---

Community

Questions, bugs, and contributions:

• Discord
• Issues
• Contributing

Developed across Salamanca · Mexico City · San Francisco.

---

License

FoundationForecast is licensed under Apache License 2.0. You may use, modify, and deploy the library in production, including commercial applications.

Model weights and hosted APIs have separate licenses. See the License column and production note in Supported models above.