foundationforecast 0.1.11

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.

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

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/air_passengers.csv",
)

ff = FoundationForecast(models=[Chronos(), Toto(context_length=256)])

fcst_df = ff.forecast(df, h=12, freq="MS", level=[90])
cv_df = ff.cross_validation(df, h=12, freq="MS", level=[90])
anomalies_df = ff.detect_anomalies(df, freq="MS", level=99)

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.

Highlights

• 🎯 Reproducible by design. FoundationForecast implementations are regression-tested against official GIFT-Eval submissions to ensure they continue to reproduce their benchmark behavior. CI automatically re-runs experiments/gift-eval on Modal GPU and verifies MASE and CRPS against Hugging Face reference CSVs for every change.
• 🚀 GPU-native. Automatically runs on GPU when available, without model-specific device configuration.

Supported models

Every model supports forecast, cross-validation, and anomaly detection through the same API. Intervals means prediction intervals via level or quantile forecasts. Exog/Covariates 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.

	Model	Forecast	CV	Anomalies	Intervals	Exog/Covariates	Finetuning	License
	Chronos	✓	✓	✓	✓	✓¶	✓	Apache-2.0
	FlowState	✓	✓	✓	✓			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†
	TabPFN	✓	✓	✓	✓			TabPFN NC‡
	Tafsut	✓	✓	✓	✓			MIT
	TiRex	✓	✓	✓	✓	✓¶		Community / Apache-2.0
	TimeGPT	✓	✓	✓	✓	✓	✓	Nixtla API§
	TimesFM	✓	✓	✓	✓	✓¶		Apache-2.0
	Toto	✓	✓	✓	✓			Apache-2.0

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

¶ Exog/Covariates (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); TiRex-2 (NX-AI/TiRex-2 and other TiRex-2-* checkpoints, not TiRex 1.0). 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.

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

News

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

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

Relationship to TimeCopilot

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.