TimesFM 2.5 with covariates restored

Senoni Research fork of Google’s TimesFM.

When TimesFM moved from v1 to 2.5, the upgrade kept the new quantile head and dropped forecast_with_covariates. This fork puts that API back on 2.5 and uses it for inventory planning: service levels, safety stock, and cost-optimal order fractiles.

This is not an official Google product and not a TimesFM release.

• Upstream: google-research/timesfm
• Paper: A decoder-only foundation model for time-series forecasting (ICML 2024)
• Checkpoints: TimesFM on Hugging Face

What was missing

TimesFM v1 could take static and dynamic covariates (store, product group, calendar, promotions) through forecast_with_covariates. The 2.5 rewrite (September 2025) shipped a continuous quantile head and did not carry that method.

Without covariates you get a strong univariate forecast. With them you can condition on known future drivers and still read a full predictive distribution.

What this fork restores

On 4 October 2025 this tree ported the v1 in-context linear regressor onto TimesFM 2.5 and applied the adjustment across the quantile head, not only the point forecast.

point, xreg, quantiles = model.forecast_with_covariates(
    horizon=horizon,
    inputs=series,
    static_categorical_covariates={"store": stores, "department": depts},
    static_numerical_covariates={"mean_demand": means},
    dynamic_categorical_covariates={"month": months, "week_of_year": weeks},
    dynamic_numerical_covariates={"week_index": week_index},
    xreg_mode="xreg + timesfm",
)

quantiles is shape (H, Q) per series, with the covariate adjustment applied at every percentile. That is what inventory policy needs: P63 for a newsvendor critical ratio, P90 for a service-level cap, P90 − P50 as safety stock.

Google later added 2.5 covariate support upstream (28 October 2025). Keep this fork if you want the Senoni port, the quantile-adjusted return value, and the inventory notebooks. Prefer upstream or PyPI for the stock library.

Details: COVARIATES_2P5.md and quantile_covariates.md.

Inventory notes

Artefact	Purpose
quantile.md	Why the 2.5 quantile head maps onto inventory policy
quantile_covariates.md	Same argument with static and dynamic covariates
notebooks/quantile_inventory_demo.ipynb	Synthetic P90 vs median demo
notebooks/quantile_inventory_demo_covariates.ipynb	Same demo with covariates
notebooks/vn2_submission_quantile.ipynb	VN2-style submission on the quantile head
notebooks/vn2_submission_quantile_covariates.ipynb	Same submission with covariates

The VN2 notebooks read from a local ../vn2inventory/data directory. That data is not in this repository.

Companion repos: vn2inventory (demand and orders) and relational-graph (activation / transfer).

Install

git clone https://github.com/senoni-research/timesfm.git
cd timesfm
pip install -e ".[covariates]"

For the stock library without this port:

pip install timesfm

This repository does not publish to PyPI.

Provenance

TimesFM was developed by Google Research. This repository is a Senoni fork of that project. We are not affiliated with Google. License remains Apache 2.0 — see LICENSE and NOTICE.

License

Apache License 2.0.

• TimesFM © Google LLC
• Senoni covariate port, documentation and notebooks © SENONI Research