{"slug": "show-hn-foundationforecast-unified-api-for-time-series-foundation-models", "title": "Show HN: FoundationForecast: unified API for time series foundation models", "summary": "The TimeCopilot team released FoundationForecast, an open-source Python library that wraps multiple time series foundation models behind a single FoundationForecast class with unified forecast, cross_validation and detect_anomalies methods and a three-column unique_id/ds/y data format. The library natively supports known-future covariates on Chronos-2, TimesFM-3, TimeGPT, T0, TimeH2O, TiRex-2 and Timestral, and the team reports a full GIFT-Eval replication of 16 models across 97 dataset configurations each in about 34 GPU-hours for $37, with every model within 2% of its leaderboard MASE/CRPS and TimesFM 3 the most accurate at under $8. Wrappers are regression-tested in CI against official GIFT-Eval and fev-bench submissions, and the library runs on GPU automatically when available.", "body_md": "*The API for the time series foundation era · Forecast · Cross-validation · Anomaly detection*\n\nForecasting 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.\n\nThe 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](https://github.com/TimeCopilot/impermanent) and other benchmarks such as [GIFT-Eval](https://huggingface.co/spaces/Salesforce/GIFT-Eval) and [FEV](https://arxiv.org/abs/2509.26468).\n\nAt 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.\n\n**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. ✨\n\nDeveloped with 💙 by the [TimeCopilot](https://timecopilot.dev/) crew.\n\n``` python\nimport pandas as pd\nfrom foundationforecast import FoundationForecast\nfrom foundationforecast.models import Chronos, Toto\n\ndf = pd.read_csv(\n    \"https://timecopilot.s3.amazonaws.com/public/data/entsoe_4markets_8w.csv\",\n    parse_dates=[\"ds\"],\n)\n\nff = FoundationForecast(\n    models=[\n        Chronos(repo_id=\"amazon/chronos-bolt-tiny\", alias=\"Chronos\"),\n        Toto(context_length=512, alias=\"Toto\"),\n    ]\n)\n\nfcst_df = ff.forecast(df, h=24, level=[90])\ncv_df = ff.cross_validation(df, h=24, level=[90])\nanomalies_df = ff.detect_anomalies(df, level=99)\n\nff.plot(df=df, forecasts_df=fcst_df)\n```\n\nYour 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).\n\n- 📈 **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](https://github.com/TimeCopilot/foundationforecast/blob/main/docs/exogenous-variables.md) and the[example notebook](https://github.com/TimeCopilot/foundationforecast/blob/main/docs/examples/exogenous-variables.ipynb) .\n- 💸 **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](https://github.com/TimeCopilot/foundationforecast/blob/main/experiments/gift-eval/README.md) .\n- 🎯 **Benchmark replication in CI.** Wrappers are regression-tested against official leaderboard submissions:[`experiments/gift-eval`](https://github.com/TimeCopilot/foundationforecast/tree/main/experiments/gift-eval) (GIFT-Eval MASE/CRPS on Modal GPU) and[`experiments/fev-bench`](https://github.com/TimeCopilot/foundationforecast/tree/main/experiments/fev-bench) (fev-bench`test_error` on known-dynamic tasks).[CI](https://github.com/TimeCopilot/foundationforecast/actions/workflows/ci.yaml) re-runs these checks on every change.\n- 🚀 **GPU-native** . Automatically runs on GPU when available, without model-specific device configuration.\n\nEvery 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](https://github.com/TimeCopilot/foundationforecast/blob/main/docs/exogenous-variables.md) (`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](https://huggingface.co/models) on the default Hugging Face repo (or provider terms for hosted APIs). See the note below for production use.\n\nPass any Hugging Face `repo_id` (or local checkpoint path) supported by the underlying model class.\n\n| Provider | Model | Forecast | CV | Anomalies | Intervals | Exogenous | Finetuning | License | \n|---|---|---|---|---|---|---|---|---|\n|  | [Chronos](https://arxiv.org/abs/2403.07815) | ✓ | ✓ | ✓ | ✓ | ✓¶ | ✓ | Apache-2.0 | \n|  | [FlowState](https://arxiv.org/abs/2508.05287) | ✓ | ✓ | ✓ | ✓ |  |  | Apache-2.0 | \n|  | [Moirai](https://arxiv.org/abs/2402.02592) | ✓ | ✓ | ✓ | ✓ |  |  | CC-BY-NC-4.0 | \n|  | [PatchTST-FM](https://arxiv.org/abs/2602.06909) | ✓ | ✓ | ✓ | ✓ |  |  | CC-BY-NC-SA-4.0 | \n|  | [Sundial](https://arxiv.org/abs/2502.00816) | ✓ | ✓ | ✓ | ✓ |  |  | Apache-2.0 | \n|  | [T0](https://huggingface.co/theforecastingcompany/t0-alpha) | ✓ | ✓ | ✓ | ✓ | ✓ |  | Apache-2.0† | \n|  | [Tabby](https://arxiv.org/abs/2609.13956) | ✓ | ✓ | ✓ | ✓ |  |  | CC-BY-NC-4.0 | \n|  | [TabPFN](https://arxiv.org/abs/2501.02945) | ✓ | ✓ | ✓ | ✓ |  |  | TabPFN NC‡ | \n|  | [Tafsut](https://github.com/Tafsut-FM/tafsut) | ✓ | ✓ | ✓ | ✓ |  |  | MIT | \n|  | [TiRex](https://arxiv.org/abs/2505.23719) | ✓ | ✓ | ✓ | ✓ | ✓¶ |  | Community / Apache-2.0 | \n|  | [TimeH2O](https://huggingface.co/h2oai/timeh2o-v1) | ✓ | ✓ | ✓ | ✓ | ✓¶ |  | H2O.ai NC# | \n|  | [TimeGPT](https://arxiv.org/abs/2310.03589) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | Nixtla API§ | \n|  | [TimesFM](https://arxiv.org/abs/2310.10688) | ✓ | ✓ | ✓ | ✓ | ✓¶ |  | Apache-2.0 | \n|  | [Timestral](https://huggingface.co/collections/mistralai/timestral) | ✓ | ✓ | ✓ | ✓ | ✓¶ |  | Modified MIT∥ | \n|  | [Toto](https://arxiv.org/abs/2505.14766) | ✓ | ✓ | ✓ | ✓ |  |  | Apache-2.0 | \n\nLicenses verified against Hugging Face model cards. Check the model card for your `repo_id` when in doubt.\n\n¶ **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](https://github.com/TimeCopilot/foundationforecast/blob/main/docs/exogenous-variables.md#native-exog-by-checkpoint).\n\n## **What this means for production**\n\n- **Apache-2.0** ,**MIT** : generally fine for commercial production (retain notices; T0† is also gated on Hugging Face: accept terms and set`HF_TOKEN` ).\n- **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.\n- **Apache-2.0 / OpenMDW 1.0** (Granite PatchTST-FM r2): commercial-friendly; choose either license per the[model card](https://huggingface.co/ibm-granite/granite-timeseries-patchtst-fm-r2) .\n- **TimesFM 3.0** : weights for`google/timesfm-3.0-pytorch` are[non-commercial](https://huggingface.co/google/timesfm-3.0-pytorch/blob/main/LICENSE) ; TimesFM 1.0–2.5 checkpoints remain Apache-2.0.\n- **TabPFN NC** ‡: TabPFN-2.6+ and TabPFN-3 weights are non-commercial; production requires a[Prior Labs commercial license or API](https://docs.priorlabs.ai/models) . First LOCAL use requires accepting terms at[ux.priorlabs.ai](https://ux.priorlabs.ai) (`TABPFN_TOKEN` ). TabPFN-3 is LOCAL-only today.\n- **Community / Apache-2.0** (TiRex): TiRex 1.0 uses the[NXAI Community License](https://huggingface.co/NX-AI/TiRex/blob/main/LICENSE) (commercial limits for large enterprises); TiRex 2.0 is Apache-2.0.\n- **H2O.ai NC#** (TimeH2O): checkpoint weights are[non-commercial](https://huggingface.co/h2oai/timeh2o-v1) and gated on Hugging Face (accept terms and set`HF_TOKEN` ); inference code is Apache-2.0 via`h2ofm` .\n- **Nixtla API** §: hosted service via`NIXTLA_API_KEY` ; production under[Nixtla terms/pricing](https://www.nixtla.io/docs) , not open weights.\n- **Modified MIT∥** (Timestral): checkpoint weights use Mistral's[Modified MIT license](https://huggingface.co/mistralai/Timestral-209M) (companies above USD 20M monthly revenue need a commercial license from Mistral); inference code is Apache-2.0 via`timecopilot-timestral` .\n\n**FoundationForecast** itself is [Apache-2.0](https://github.com/TimeCopilot/foundationforecast/blob/main/LICENSE) regardless of which model you plug in.\n\nSome models require specific Python versions (e.g. FlowState 3.11-3.13, TabPFN < 3.13, TimeH2O 3.12+). See the [Model Hub](https://github.com/TimeCopilot/foundationforecast/blob/main/docs/model-hub.md) for details and default checkpoints.\n\n## **Example checkpoints & API model IDs**\n\n- **Chronos:**`amazon/chronos-t5-{tiny,mini,small,base,large}` ,`amazon/chronos-bolt-{tiny,mini,small,base}` ,`amazon/chronos-2`\n- **FlowState:**`ibm-research/flowstate` ,`ibm-granite/granite-timeseries-flowstate-r1`\n- **Moirai:**`Salesforce/moirai-{1.0,1.1,2.0}-R-{small,base,large}` ,`Salesforce/moirai-moe-1.0-R-*`\n- **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` )\n- **Sundial:**`thuml/sundial-base-128m`\n- **T0:**`theforecastingcompany/t0-alpha` ,`theforecastingcompany/t0-beta` ,`theforecastingcompany/t0-gamma` (requires`tfc-t0[torch]>=0.6.0` )\n- **Tabby:**`paris-noah/Tabby` (requires`trust_remote_code` ; CC-BY-NC-4.0)\n- **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\n- **Tafsut:**`Tafsut-FM/tafsut-univariate-base`\n- **TiRex:**`NX-AI/TiRex` ,`NX-AI/TiRex-2`\n- **TimeH2O:**`h2oai/timeh2o-v1` ,`h2oai/timeh2o-v1-tiny` (requires`h2ofm>=0.43.0` , Python 3.12+)\n- **TimeGPT:** pass`model=` to`TimeGPT()` , e.g.`timegpt-1` ,[`timegpt-1-long-horizon`](https://www.nixtla.io/docs/forecasting/model-version/longhorizon_model) ,`timegpt-2-mini` ,`timegpt-2` ,`timegpt-2-pro`\n- **TimesFM:**`google/timesfm-{1.0-200m,2.0-500m,2.5-200m,3.0}-pytorch` (3.0 weights are[non-commercial](https://huggingface.co/google/timesfm-3.0-pytorch/blob/main/LICENSE) )\n- **Timestral:**`mistralai/Timestral-{5M,28M,123M,209M}` (requires`timecopilot-timestral>=0.1.0` )\n- **Toto:**`Datadog/Toto-Open-Base-1.0` ,`Datadog/Toto-2.0-{4m,22m,313m,1B,2.5B}`\n\nRecent additions and checkpoints (newest first). See the [changelog](https://github.com/TimeCopilot/foundationforecast/blob/main/docs/changelogs/v0.1.17.md) for full release notes.\n\n| When | What | Checkpoint / detail | \n|---|---|---|\n| Oct 2026 | [**Tabby**](https://huggingface.co/paris-noah/Tabby) | `paris-noah/Tabby` — 99 native quantiles;`trust_remote_code` ; CC-BY-NC-4.0; GIFT-Eval CI ([v0.1.17](https://github.com/TimeCopilot/foundationforecast/blob/main/docs/changelogs/v0.1.17.md) ) | \n| Oct 2026 | [**TimeH2O**](https://huggingface.co/h2oai/timeh2o-v1) | `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](https://github.com/TimeCopilot/foundationforecast/blob/main/docs/changelogs/v0.1.16.md) ) | \n| Oct 2026 | [**Timestral**](https://huggingface.co/collections/mistralai/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](https://github.com/TimeCopilot/foundationforecast/blob/main/docs/changelogs/v0.1.15.md) ) | \n| Oct 2026 | [**T0 gamma**](https://huggingface.co/theforecastingcompany/t0-gamma) | `theforecastingcompany/t0-gamma` — requires`tfc-t0[torch]>=0.6.0` ; GIFT-Eval and fev-bench CI ([v0.1.14](https://github.com/TimeCopilot/foundationforecast/blob/main/docs/changelogs/v0.1.14.md) ) | \n| 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](https://github.com/TimeCopilot/foundationforecast/blob/main/docs/changelogs/v0.1.13.md) ) | \n| 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](https://github.com/TimeCopilot/foundationforecast/blob/main/docs/changelogs/v0.1.11.md) ) | \n| Sep 2026 | **Quantile column naming** | Stable `-q-*` suffixes from`100×q` (≤3 dp`quantiles` , integer`level` only) ([v0.1.10](https://github.com/TimeCopilot/foundationforecast/blob/main/docs/changelogs/v0.1.10.md) ) | \n| Sep 2026 | **Quantile interpolation** | Arbitrary `level` /`quantiles` on fixed-knot models with edge clamping; removed`level=0` sentinel ([v0.1.9](https://github.com/TimeCopilot/foundationforecast/blob/main/docs/changelogs/v0.1.9.md) ) | \n| Sep 2026 | [**Granite PatchTST-FM r2**](https://huggingface.co/ibm-granite/granite-timeseries-patchtst-fm-r2) | `ibm-granite/granite-timeseries-patchtst-fm-r2` — Apache-2.0 / OpenMDW; requires`granite-tsfm>=0.3.9` ([v0.1.8](https://github.com/TimeCopilot/foundationforecast/blob/main/docs/changelogs/v0.1.8.md) ) | \n| Sep 2026 | [**T0 beta**](https://huggingface.co/theforecastingcompany/t0-beta) | `theforecastingcompany/t0-beta` — requires`tfc-t0>=0.5.0` ([v0.1.8](https://github.com/TimeCopilot/foundationforecast/blob/main/docs/changelogs/v0.1.8.md) ) | \n| Sep 2026 | **TiRex-2 zeroshot (GIFT-Eval CI)** | `NX-AI/TiRex-2-gifteval-zs` added to gift-eval replication ([v0.1.8](https://github.com/TimeCopilot/foundationforecast/blob/main/docs/changelogs/v0.1.8.md) ) | \n| Sep 2026 | **Shared panel processing** | Faster multi-model forecasts via reused panel path across forecasters ( [v0.1.8](https://github.com/TimeCopilot/foundationforecast/blob/main/docs/changelogs/v0.1.8.md) ) | \n| Sep 2026 | [**TabPFN-3**](https://arxiv.org/abs/2501.02945) (LOCAL) | `model_path=\"tabpfn-v3-regressor-v3_20260506_timeseries.ckpt\"` ([v0.1.7](https://github.com/TimeCopilot/foundationforecast/blob/main/docs/changelogs/v0.1.7.md) ) | \n\n**Recommended:** [uv](https://docs.astral.sh/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).\n\n```\nuv add foundationforecast\n```\n\nOr with pip:\n\n```\npip install foundationforecast\n```\n\nRequires Python 3.10+. Some models have additional version requirements; see the [Model Hub](https://github.com/TimeCopilot/foundationforecast/blob/main/docs/model-hub.md).\n\nOptional plotting support:\n\n```\nuv add \"foundationforecast[plot]\"\n# or: pip install \"foundationforecast[plot]\"\npython\nimport pandas as pd\nfrom foundationforecast import FoundationForecast\nfrom foundationforecast.models import Chronos, TimesFM\n\nDATA = \"https://timecopilot.s3.amazonaws.com/public/data/electricity_price\"\ndf = pd.read_parquet(f\"{DATA}/train.parquet\")\nX_df = pd.read_parquet(f\"{DATA}/futr_exog.parquet\")\n\nff = FoundationForecast(\n    models=[\n        Chronos(repo_id=\"amazon/chronos-2\", alias=\"Chronos-2\"),\n        TimesFM(repo_id=\"google/timesfm-3.0-pytorch\", alias=\"TimesFM-3\"),\n    ]\n)\n\nfcst_df = ff.forecast(df=df, h=24, X_df=X_df, level=[90])\nff.plot(df=df, forecasts_df=fcst_df)\n```\n\n|  | **FoundationForecast** | **TimeCopilot** | \n|---|---|---|\n| Foundation models (Chronos, Moirai, …) | ✓ | ✓ | \n| Unified forecast / CV / anomaly API | ✓ | ✓ | \n| Statistical & ML baselines |  | ✓ | \n| LLM agent & natural-language queries |  | ✓ | \n| Ensembles & distributed inference |  | ✓ | \n\nUse **FoundationForecast** when you only need foundation models. Use **[TimeCopilot](https://github.com/TimeCopilot/timecopilot)** for the full forecasting agent.\n\nTo reference the software package:\n\n```\n@software{foundationforecast,\n  title = {FoundationForecast: The API for time series foundation models},\n  author = {Garza, Azul and Rosillo, Renée},\n  year = {2026},\n  url = {https://github.com/TimeCopilot/foundationforecast},\n  license = {Apache-2.0},\n}\n```\n\nQuestions, bugs, and contributions:\n\nDeveloped across Salamanca · Mexico City · San Francisco.\n\n**FoundationForecast** is licensed under [Apache License 2.0](https://github.com/TimeCopilot/foundationforecast/blob/main/LICENSE). You may use, modify, and deploy the library in production, including commercial applications.\n\nModel weights and hosted APIs have separate licenses. See the **License** column and production note in [Supported models](#supported-models) above.", "url": "https://wpnews.pro/news/show-hn-foundationforecast-unified-api-for-time-series-foundation-models", "canonical_source": "https://github.com/TimeCopilot/foundationforecast", "published_at": "2026-10-27 12:05:28+00:00", "updated_at": "2026-10-27 12:42:36.639475+00:00", "lang": "en", "topics": ["machine-learning", "ai-tools", "developer-tools", "ai-research"], "entities": ["FoundationForecast", "TimeCopilot", "Chronos", "Toto", "TimesFM 3", "GIFT-Eval", "fev-bench", "Modal"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-foundationforecast-unified-api-for-time-series-foundation-models", "markdown": "https://wpnews.pro/news/show-hn-foundationforecast-unified-api-for-time-series-foundation-models.md", "text": "https://wpnews.pro/news/show-hn-foundationforecast-unified-api-for-time-series-foundation-models.txt", "jsonld": "https://wpnews.pro/news/show-hn-foundationforecast-unified-api-for-time-series-foundation-models.jsonld"}}