Show HN: FoundationForecast: unified API for time series foundation models

The API for the time series foundation era · Forecast · Cross-validation · Anomaly detection

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.

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

• 📈 Exogenous variables (covariates). Pass known-future features with**X_df** on forecast() (and exog columns indf forcross_validation() ). Native support on Chronos-2, TimesFM-3, TimeGPT, T0, TimeH2O, TiRex-2, and Timestral; seeExogenous variables and theexample 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 thewriteup .
• 🎯 Benchmark replication in CI. Wrappers are regression-tested against official leaderboard submissions:experiments/gift-eval (GIFT-Eval MASE/CRPS on Modal GPU) andexperiments/fev-bench (fev-benchtest_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.

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.

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 setHF_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 themodel card .
• TimesFM 3.0 : weights forgoogle/timesfm-3.0-pytorch arenon-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 aPrior Labs commercial license or API . First LOCAL use requires accepting terms atux.priorlabs.ai (TABPFN_TOKEN ). TabPFN-3 is LOCAL-only today.
• Community / Apache-2.0 (TiRex): TiRex 1.0 uses theNXAI Community License (commercial limits for large enterprises); TiRex 2.0 is Apache-2.0.
• H2O.ai NC# (TimeH2O): checkpoint weights arenon-commercial and gated on Hugging Face (accept terms and setHF_TOKEN ); inference code is Apache-2.0 viah2ofm .
• Nixtla API §: hosted service viaNIXTLA_API_KEY ; production underNixtla terms/pricing , not open weights.
• Modified MIT∥ (Timestral): checkpoint weights use Mistral'sModified MIT license (companies above USD 20M monthly revenue need a commercial license from Mistral); inference code is Apache-2.0 viatimecopilot-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
• 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 requiresgranite-tsfm>=0.3.9 )
• Sundial:thuml/sundial-base-128m
• T0:theforecastingcompany/t0-alpha ,theforecastingcompany/t0-beta ,theforecastingcompany/t0-gamma (requirestfc-t0[torch]>=0.6.0 )
• Tabby:paris-noah/Tabby (requirestrust_remote_code ; CC-BY-NC-4.0)
• TabPFN: defaulttabpfn-v2-regressor-2noar4o2.ckpt ; TabPFN-3 viamodel_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 (requiresh2ofm>=0.43.0 , Python 3.12+)
• TimeGPT: passmodel= toTimeGPT() , 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 arenon-commercial )
• Timestral:mistralai/Timestral-{5M,28M,123M,209M} (requirestimecopilot-timestral>=0.1.0 )
• Toto:Datadog/Toto-Open-Base-1.0 ,Datadog/Toto-2.0-{4m,22m,313m,1B,2.5B}

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

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]"
python
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)

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

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},
}

Questions, bugs, and contributions:

Developed across Salamanca · Mexico City · San Francisco.

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.