timesfm-forecasting

What it does

Forecasts univariate time series without training a custom model, returning a point forecast plus prediction intervals. It provides a mechanism to batch-forecast multiple series and supports inputs from CSV, DataFrame, or arrays. It also enforces a preflight system checker to verify RAM, GPU, disk space, Python version, and existing installations before loading the model.

How it works

• Uses TimesFM as a pretrained decoder-only foundation model for zero-shot forecasting.
• Requires a mandatory preflight check via python scripts/check_system.py to ensure resources meet thresholds (RAM, GPU, disk, Python version, and dependencies).
• Installation steps include verifying the system, installing TimesFM with uv pip install timesfm[torch] or pip install timesfm[torch], installing PyTorch for the target hardware, and then importing and querying timesfm to ensure installation succeeded.
• Forecasting is configured with timesfm.ForecastConfig, controlling context length, horizon, input normalization, quantile head usage, quantile crossing fixes, and other stability tweaks.
• Output consists of two arrays: point_forecast (median) and quantile_forecast (10 quantiles) for probabilistic interpretation.
• It supports covariates via forecast_with_covariates() and note that anomaly detection is not built-in but can be inferred from prediction intervals.

When to use it

• When forecasting any univariate time series (sales, demand, sensor, vitals, price, weather) without training a model.
• When probabilistic forecasts with calibrated prediction intervals are required.
• When you have time series of varying length up to the model’s context limits and/or need batch forecasting across many series.
• When you prefer a foundation-model approach over classical ARIMA/ETS parameter tuning.

What it can touch

• The skill interacts with system-level checks and a local Python environment:
  • Executes python scripts/check_system.py to verify resources.
  • Installs Python packages via uv pip install timesfm[torch] or pip install timesfm[torch] and pip install torch>=2.0.0 ....
  • Uses import timesfm and timesfm.TimesFM_2p5_200M_torch.from_pretrained(...) to load the model.
• Forecasting operations use model.forecast() and model.forecast_with_covariates() with inputs as numeric arrays (e.g., 1-D time series).
• Data preparation uses common Python data structures like lists of arrays derived from CSV/DataFrame inputs.

Caveats

• The model weights (~800 MB) are downloaded on first use from HuggingFace and cached; the repository does not store weights.
• TimesFM requires resources above certain thresholds (RAM, VRAM) and the preflight checker enforces this before loading.
• TimesFM does not include built-in anomaly detection; anomaly detection must be derived from quantile intervals (e.g., whether values fall outside 90% CI).
• Multivariate forecasting or time-series classification/clustering is not supported by this dedicated TimesFM workflow; it targets univariate series.