feat(patchtst-fm): family guide for IBM and Granite r1 checkpoints

docs/changelogs/index.md

@@ -2,6 +2,7 @@
 
 Welcome to the TimeCopilot Changelog. Here, you will find a comprehensive list of all the changes, updates, and improvements made to the TimeCopilot project. This section is designed to keep you informed about the latest features, bug fixes, and enhancements as we continue to develop and refine the TimeCopilot experience. Stay tuned for regular updates and feel free to explore the details of each release below.
 
+- [v0.0.35](v0.0.35.md)
 - [v0.0.34](v0.0.34.md)
 - [v0.0.33](v0.0.33.md)
 - [v0.0.32](v0.0.32.md)

docs/changelogs/v0.0.35.md

@@ -0,0 +1,36 @@
+### Features
+
+* **PatchTST-FM family checkpoints**: Document and compare IBM Research and Granite PatchTST-FM releases via the existing `PatchTSTFM` class (`foundationforecast>=0.1.8`, `granite-tsfm>=0.3.8`). Pass `repo_id` to select the checkpoint:
+
+    - `ibm-research/patchtst-fm-r1` (default) — [CC-BY-NC-SA-4.0](https://huggingface.co/ibm-research/patchtst-fm-r1) (non-commercial research weights)
+    - `ibm-granite/granite-timeseries-patchtst-fm-r1` — [Apache-2.0](https://huggingface.co/ibm-granite/granite-timeseries-patchtst-fm-r1)
+    - `ibm-granite/granite-timeseries-patchtst-fm-r2` — [Apache-2.0](https://huggingface.co/ibm-granite/granite-timeseries-patchtst-fm-r2) / [OpenMDW 1.0](https://openmdw.ai/license/1-0/) (dual-licensed; commercial-friendly)
+
+    ```python
+    import pandas as pd
+    from timecopilot.models.foundation.patchtst_fm import PatchTSTFM
+
+    df = pd.read_csv(
+        "https://timecopilot.s3.amazonaws.com/public/data/air_passengers.csv",
+        parse_dates=["ds"],
+    )
+
+    model = PatchTSTFM(
+        repo_id="ibm-granite/granite-timeseries-patchtst-fm-r2",
+        alias="Granite-PatchTST-FM-r2",
+        context_length=2048,
+    )
+    fcst_df = model.forecast(df, h=12, freq="MS", level=[80, 90])
+    ```
+
+    **License note:** Only the IBM Research checkpoint (`ibm-research/patchtst-fm-r1`) is non-commercial ([CC-BY-NC-SA-4.0](https://huggingface.co/ibm-research/patchtst-fm-r1)). Granite PatchTST-FM r1 and r2 use permissive open licenses suitable for commercial use (see model cards above).
+
+* **PatchTST-FM family notebook**: Added [`patchtst-fm-family` example notebook](../examples/patchtst-fm-family.ipynb) comparing IBM Research `patchtst-fm-r1` with Granite `patchtst-fm-r1` and `patchtst-fm-r2`, including prediction intervals and evaluation metrics.
+
+### Dependencies
+
+* Bumped `foundationforecast` from `>=0.1.7` to `>=0.1.8` (Granite PatchTST-FM r2 via `granite-tsfm>=0.3.8`).
+
+---
+
+**Full Changelog**: https://github.com/TimeCopilot/timecopilot/compare/v0.0.34...v0.0.35

docs/examples/index.md

@@ -29,6 +29,7 @@ For model API details, see the [Model Hub](../model-hub.md).
 | [Compare Foundation Models](ts-foundation-models-comparison-quickstart.ipynb) | Benchmark multiple foundation models side by side | Python 3.10+; GPU optional |
 | [Chronos Family](chronos-family.ipynb) | Forecast with Chronos 1.x and 2.x checkpoints | Python 3.10+ |
 | [TimesFM Family](timesfm-family.ipynb) | Forecast with TimesFM 1.0, 2.0, 2.5, and 3.0 with prediction intervals | Python 3.10+ |
+| [PatchTST-FM Family](patchtst-fm-family.ipynb) | Forecast with IBM Research PatchTST-FM r1 and Granite PatchTST-FM r1/r2 | Python 3.11–3.13; GPU recommended |
 | [TabPFN Family](tabpfn-family.ipynb) | Forecast with TabPFN-2 and TabPFN-3 with prediction intervals | Python 3.10–3.12; `TABPFN_TOKEN` for LOCAL |
 | [TiRex Family](tirex-family.ipynb) | Forecast with TiRex 1.0 and 2.0 | Python 3.11+ |
 | [Toto Family](toto-family.ipynb) | Forecast with Toto 1.0 and 2.0 | Python 3.10+ |

docs/model-hub.md

@@ -48,7 +48,7 @@ TimeCopilot provides a unified interface to state-of-the-art foundation models f
 - [Chronos](api/models/foundation/models.md#timecopilot.models.foundation.chronos) ([arXiv:2403.07815](https://arxiv.org/abs/2403.07815))
 - [FlowState](api/models/foundation/models.md#timecopilot.models.foundation.flowstate) ([arXiv:2508.05287](https://arxiv.org/abs/2508.05287)) 
 - [Moirai](api/models/foundation/models.md#timecopilot.models.foundation.moirai) ([arXiv:2402.02592](https://arxiv.org/abs/2402.02592))
-- [PatchTST-FM](api/models/foundation/models.md#timecopilot.models.foundation.patchtst_fm) ([arXiv:2602.06909](https://arxiv.org/abs/2602.06909))
+- [PatchTST-FM](api/models/foundation/models.md#timecopilot.models.foundation.patchtst_fm) ([arXiv:2602.06909](https://arxiv.org/abs/2602.06909); `ibm-research/patchtst-fm-r1` [NC](https://huggingface.co/ibm-research/patchtst-fm-r1), `ibm-granite/granite-timeseries-patchtst-fm-r1`, `ibm-granite/granite-timeseries-patchtst-fm-r2`) — Python 3.11–3.13
 - [Sundial](api/models/foundation/models.md#timecopilot.models.foundation.sundial) ([arXiv:2502.00816](https://arxiv.org/pdf/2502.00816))
 - [T0](api/models/foundation/models.md#timecopilot.models.foundation.t0) ([model card](https://huggingface.co/theforecastingcompany/t0-alpha))
 - [TabPFN](api/models/foundation/models.md#timecopilot.models.foundation.tabpfn) ([arXiv:2501.02945](https://arxiv.org/abs/2501.02945); TabPFN-2 default, TabPFN-3 via `model_path`; [NC license](https://docs.priorlabs.ai/models))

mkdocs.yml

@@ -37,6 +37,7 @@ nav:
           - Family Guides:
               - Chronos: examples/chronos-family.ipynb
               - TimesFM: examples/timesfm-family.ipynb
+              - PatchTST-FM: examples/patchtst-fm-family.ipynb
               - TiRex: examples/tirex-family.ipynb
               - TabPFN: examples/tabpfn-family.ipynb
               - Toto: examples/toto-family.ipynb
@@ -63,6 +64,7 @@ nav:
       - experiments/fev.md
   - Changelogs:
       - changelogs/index.md
+      - changelogs/v0.0.35.md
       - changelogs/v0.0.34.md
       - changelogs/v0.0.33.md
       - changelogs/v0.0.32.md

pyproject.toml

@@ -69,7 +69,7 @@ dependencies = [
   "catboost>=1.2.10",
   "datasets>=4.1.1",
   "fire",
-  "foundationforecast>=0.1.7",
+  "foundationforecast>=0.1.8",
   "fsspec>=2025.9.0",
   "huggingface-hub>=0.36.2,<2.0",
   "hydra-core>=1.3.2",
@@ -96,6 +96,7 @@ dependencies = [
   "scipy<=1.15.3",
   "statsforecast>=2.0.2",
   "tensorboard>=2.20.0",
+  "torch>=2.10,<2.11 ; python_full_version >= '3.11'",
   "torchmetrics>=1.8.2",
   "transformers>=4.41,<6 ; python_full_version < '3.13'",
   "transformers>=4.48,<6 ; python_full_version >= '3.13'",
@@ -108,7 +109,7 @@ license = "MIT"
 name = "timecopilot"
 readme = "README.md"
 requires-python = ">=3.10"
-version = "0.0.34"
+version = "0.0.35"
 
 [project.optional-dependencies]
 distributed = [

tests/models/conftest.py

@@ -164,7 +164,23 @@ def disable_mps_session(monkeypatch):
             alias="FlowState-Granite",
         )
     )
-    models.append(PatchTSTFM(context_length=2_048))
+    models.append(PatchTSTFM(context_length=2_048, batch_size=32))
+    models.append(
+        PatchTSTFM(
+            repo_id="ibm-granite/granite-timeseries-patchtst-fm-r1",
+            alias="Granite-PatchTST-FM-r1",
+            context_length=2_048,
+            batch_size=32,
+        )
+    )
+    models.append(
+        PatchTSTFM(
+            repo_id="ibm-granite/granite-timeseries-patchtst-fm-r2",
+            alias="Granite-PatchTST-FM-r2",
+            context_length=2_048,
+            batch_size=32,
+        )
+    )
 
 if sys.version_info < (3, 13):
     from contextlib import contextmanager

tests/models/utils/test_forecaster.py

@@ -78,9 +78,10 @@ def test_prepare_level_and_quantiles_with_levels():
 @pytest.mark.parametrize(
     "quantiles,expected_level",
     [
-        ([0.1, 0.5, 0.9], [0, 80]),
-        ([0.1, 0.5, 0.2, 0.9], [0, 60, 80]),
-        ([0.5], [0]),
+        # foundationforecast>=0.1.8: q=0.5 is the point forecast, not a level band
+        ([0.1, 0.5, 0.9], [80]),
+        ([0.1, 0.5, 0.2, 0.9], [60, 80]),
+        ([0.5], None),
     ],
 )
 def test_prepare_level_and_quantiles_with_quantiles(quantiles, expected_level):