ci: preview Python 3.14 and 3.15 support

.github/workflows/ci.yaml

@@ -76,6 +76,60 @@ jobs:
       - name: Test import FoundationForecast and Chronos
         run: uv run -- python -c "from foundationforecast import FoundationForecast; from foundationforecast.models import Chronos"
 
+  test-future-python:
+    name: test on ${{ matrix.python-version }} (preview)
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.14", "3.15"]
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+
+    steps:
+      - name: Clone repo
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Free disk space in action runner
+        uses: endersonmenezes/free-disk-space@v3
+        with:
+          remove_android: true
+          remove_dotnet: true
+          remove_haskell: true
+          rm_cmd: "rmz"
+          rmz_version: "3.1.1"
+
+      - name: Cache HuggingFace Models
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/huggingface/hub/
+          key: ${{ runner.os }}-huggingface-future-${{ matrix.python-version }}-${{ hashFiles('**/tests/') }}
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run tests
+        run: uv run pytest
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+          TABPFN_TOKEN: ${{ secrets.TABPFN_TOKEN }}
+
+      - name: Smoke import core foundation models
+        run: |
+          uv run python -c "
+          from foundationforecast import FoundationForecast, Chronos, TimesFM, Timestral
+          import sys
+          if sys.version_info >= (3, 11):
+              from foundationforecast import TiRex
+          "
+
   test-docs:
     name: test docs
     runs-on: ubuntu-latest

AGENTS.md

@@ -55,6 +55,7 @@ uv run --group docs zensical build
 | Job | Purpose |
 | --- | --- |
 | **test** | `uv run pytest` on Python 3.10–3.13; coverage gate (≥80%) on 3.12. Needs `HF_TOKEN` / `TABPFN_TOKEN` for model tests. |
+| **test-future-python** | Same pytest run on **3.14** and **3.15**; `continue-on-error: true` until promoted to required. |
 | **test-docs** | Executable markdown in `docs/` (except changelog files), `README.md`, and Python docstrings via `mktestdocs`. |
 | **build-docs** | `zensical build` (strict) |
 | **lint** | Full `pre-commit` (ruff, mypy on `foundationforecast/` only—`experiments/` excluded) |

docs/contributing.md

@@ -42,6 +42,14 @@ To run **foundationforecast** in your local environment:
 
 ✅ You're ready to start contributing!
 
+## Python 3.14 and 3.15 (preview)
+
+The library installs on **Python 3.10+** (`requires-python = ">=3.10"`). [CI](https://github.com/TimeCopilot/foundationforecast/actions/workflows/ci.yaml) runs a **preview** job on **3.14** and **3.15** (`continue-on-error: true`) to track dependency wheels and the cross-model test suite as CPython and PyTorch move forward.
+
+On **3.14+**, these optional dependencies are **not** installed (upstream caps): `granite-tsfm`, `tfc-t0`, and `timecopilot-uni2ts`. Wrappers gated to **3.11–3.13** (`FlowState`, `PatchTST-FM`, `T0`) and **< 3.13** (`TabPFN`, `Sundial`) stay unavailable by design. Models that typically remain available on 3.14+ include **Chronos**, **TimesFM**, **Timestral**, **TiRex**, **TimeGPT**, **Toto**, and **Tafsut**, subject to `torch` / `transformers` support on that interpreter.
+
+When preview CI is green, we can promote 3.14 (and later 3.15) into the required **test** matrix.
+
 ## Running Tests
 
 ```bash

pyproject.toml

@@ -42,6 +42,7 @@ classifiers = [
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
   "Programming Language :: Python",
   "Topic :: Scientific/Engineering :: Artificial Intelligence",
   "Topic :: Software Development :: Libraries :: Python Modules",

tests/test_package_imports.py

@@ -13,6 +13,7 @@ def test_core_exports_import():
         Moirai,
         TimeGPT,
         TimesFM,
+        Timestral,
         Toto,
     )