Zero-shot time series forecasting with Google's TimesFM foundation model. Use for any univariate time series (sales, sensors, energy, vitals, weather) without training a custom model. Supports CSV/DataFrame/array inputs with point forecasts and prediction intervals. Includes a preflight system check

TimesFM Forecasting Choose the model/API first The Python package version is 3.0.2 ; checkpoint versions are separate. Checkpoint Interface Quantile output Usage terms 2.5, 200M timesfm.TimesFM 2p5 200M torch , compile , forecast mean + 9 deciles, median index 5 Apache 2.0 weights; bundled CLI default 3.0, about 330M timesfm3.TimesFM3Forecaster , predict / predict batch 9 deciles, median index 4 Downloaded weights restricted to non commercial, non production use Upstream identifies 3.0 as the latest model. This skill retains 2.5 as its default local workflow because its Apache licensed weights have different usage terms. For 3.0 multivariate targets, past only covariates or Apple MLX, read [references/timesfm3.md](references/timesfm3.md) before adapting code. Authorized Google Cloud services have separate terms; a Cloud entitlement does not change the license of downloaded weights. See the [upstream license notice](https://github.com/google research/timesfm license notice for pretrained weights). Use TimesFM for forecasting an ordered temporal target without task specific model training. It is not a causal effect estimator, clinical detector, or physics based climate model. Zero shot describes fitting; it does not establish absence of benchmark overlap in pretraining or good accuracy in a new domain. Workflow 1. Establish cadence, units, forecast origin, horizon, known at origin covariates, evaluation cutoffs and a naive/seasonal naive baseline. 2. Validate a sorted, unique, regular time grid. Do not dropna() internal gaps: that changes temporal spacing. Reject nonfinite inputs, or explicitly impute inside each training history. Never fill using held out future targets. 3. Run python scripts/check system.py before downloading/loading weights. Its available RAM and cache volume thresholds are heuristics, not a guarantee against OOM. Start with batch size 1; measure actual peak usage. 4. Load the chosen checkpoint with a recorded immutable revision. For 2.5, compile explicit positive context/horizon settings; zero does not mean “use the maximum.” Keep patch rounded context + horizon <=16,384 and horizon <=1,024 when using the continuous quantile head. 5. Forecast, validate shapes/finite values/quantile ordering and export the forecast origin, frequency, configuration and checkpoint revision. 6. Evaluate across rolling origins with preprocessing fitted independently per origin. Report accuracy, interval coverage and interval width by horizon; label quantile intervals nominal until calibrated on relevant data. Installation Run in a separate environment. The commands below target the reviewed release. Shell extras and version constraints must be quoted, particularly in zsh. Use the current [PyTorch installation selector](https://pytorch.org/get started/locally/) for a CUDA wheel matching the host. The 2.5 loader in this release chooses cuda:0 if CUDA exists, otherwise CPU; detecting MPS does not enable MPS inference. Do not use model.to(...) on the wrapper as if it were an nn.Module . For CPU only XReg, install jax and scikit learn alongside the PyTorch profile; the upstream [xreg] extra requests jax[cuda] , which is not appropriate for macOS. Flax is a separate optional backend; it is not required by the bundled scripts. TimesFM 2.5 quick start The checkpoint load examples are illustrative: validation of this refresh used native package code with tiny random models and controlled decode fixtures, without downloading pretrained weights. That verifies mechanics, not accuracy. Set infer is positive=True only for a target domain that is truly nonnegative. A positive observed window does not establish that temperature anomalies, returns or residuals cannot become negative. Monotonic quantiles and a continuous quantile head do not establish interval calibration. CSV helper forecast csv.py validates before loading, sorts dates, rejects duplicate headers/dates, checks the complete regular grid and preserves missing positions. Missing values fail by default; missing interpolate fills only internal gaps, never leading/trailing values. Without date col , row order is assumed to be the regular grid and output uses steps. Numeric IDs must be excluded using value cols . max context controls history truncation; horizon is limited to 1..1,024 for this quantile head workflow. Outputs retain forecast , median , lower 80 , upper 80 , lower 60 , upper 60 . A .metadata.json sidecar records origin, cadence, model revision and config. Old skill releases mislabeled q10 q90/q20 q80 as 90%/80%; migrate old outer 90 to 80 and old inner 80 to 60 simultaneously. Old generated example forecasts were removed because their mapping/provenance was invalid. Covariates and anomaly screening For 2.5 XReg, compile return backcast=True , retain targets and covariates on identical grids and provide dynamic covariates over context and horizon. "xreg + timesfm" fits regression on targets, then forecasts regression residuals. "timesfm + xreg" forecasts first, then fits regression on backcast residuals. The latter needs more than one input patch (32 observations). In package 3.0.2, the implementation returns lists of combined point and quantile forecasts ; an inherited docstring incorrectly describes the second return as XReg only. See [references/api reference.md](references/api reference.md) for the complete call. Quantile exceedances may screen for unusual observations, but even calibrated 80% intervals exclude about 20% of ordinary observations marginally. They do not supply anomaly probabilities, familywise control or validated alarm severity. Retrospective detrended Z scores also differ from prospective anomaly detection. References and examples [API reference](references/api reference.md): 2.5 loader, compile, forecast and XReg contracts. [Output/config](references/output and config.md): all real ForecastConfig fields and interval indexing. [Data preparation](references/data preparation.md): grid, missingness, covariate timing and format recipes. [Workflows](references/workflows.md): held out and rolling origin validation, baseline comparisons. [System requirements](references/system requirements.md): resource checks and backend requirements. [Performance tuning](references/performance tuning.md): measured batch/context tuning. [Examples and validation](references/examples and validation.md): example commands and testing scope. [TimesFM 3.0](references/timesfm3.md): multivariate API, 9 decile layout and usage boundary. Primary review sources: [official source](https://github.com/google research/timesfm), [3.0.2 distribution](https://pypi.org/project/timesfm/3.0.2/), [2.5 model card](https://huggingface.co/google/timesfm 2.5 200m pytorch), [3.0 model card](https://huggingface.co/google/timesfm 3.0 pytorch).

timesfm-forecasting