docs(examples): update covariates demo API snippet to TimesFM 2.5

[evanclan]

Summary

The demonstrate_api() helper in the covariates example prints a snippet titled "TIMESFM COVARIATES API (TimesFM 2.5)" but shows the removed v1 API. This finishes the v1→2.5 example migration started by the maintainer in 6ed1d8a ("Update global-temperature example to use TimesFM 2.5 API") and addresses the v1-API breakage reported in #423.

Problem

timesfm-forecasting/examples/covariates-forecasting/demo_covariates.py (in demonstrate_api()) prints:

import timesfm
hparams   = timesfm.TimesFmHparams(backend="cpu", per_core_batch_size=32, horizon_len=12)
ckpt      = timesfm.TimesFmCheckpoint(huggingface_repo_id="google/timesfm-2.5-200m-pytorch")
model     = timesfm.TimesFm(hparams=hparams, checkpoint=ckpt)

But src/timesfm/__init__.py only exports ForecastConfig, TimesFM_2p5_200M_torch, and TimesFM_2p5_200M_flax. TimesFmHparams / TimesFmCheckpoint / TimesFm no longer exist in the 2.5 package, so a user copy-pasting this "2.5" snippet hits AttributeError: module 'timesfm' has no attribute 'TimesFmHparams' — exactly the class of breakage called out in #423 ("the old v1 API … no longer exists in the installed package").

Solution

Replace the loading lines with the real 2.5 API, mirroring the pattern the maintainer used when migrating the sibling example in 6ed1d8a (from_pretrained(...) + model.compile(ForecastConfig(...))). Also corrected the trailing shape comment to note that the 10 quantile columns are [mean, q10, …, q90] in 2.5 (the same column-layout change 6ed1d8a documented), and dropped the horizon_len wording that belonged to the v1 hparams object.

import timesfm

model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
    "google/timesfm-2.5-200m-pytorch",
    torch_compile=False,
)
model.compile(timesfm.ForecastConfig(
    max_context=512,
    max_horizon=12,
    normalize_inputs=True,
    use_continuous_quantile_head=True,
    fix_quantile_crossing=True,
))

The forecast_with_covariates(...) call below was already correct and is unchanged.

Out of scope

The same removed-v1-API pattern still appears in examples/anomaly-detection/detect_anomalies.py, examples/global-temperature/generate_animation_data.py, and examples/global-temperature/README.md. Those are executable scripts / a generated report whose committed output artifacts would need regenerating with a model run, so I left them out of this docs-only snippet fix to keep the change reviewable. Happy to follow up on them in a separate PR.

Test plan

• python -m py_compile timesfm-forecasting/examples/covariates-forecasting/demo_covariates.py passes.
• Verified TimesFM_2p5_200M_torch, ForecastConfig, and from_pretrained are the current public API in src/timesfm/__init__.py and that the new snippet matches 6ed1d8a + timesfm-forecasting/references/api_reference.md.
• CI to confirm the rest.

Related

• Two fixes were needed in the example script #423 — report that the examples use the removed v1 API
• 6ed1d8a — prior commit migrating the global-temperature example to the 2.5 API (this PR extends it to the covariates example)

Made with Cursor

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.