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 Overview TimesFM (Time Series Foundation Model) is a pretrained decoder only foundation model developed by Google Research for time series forecasting. It works zero shot — feed it any univariate time series and it returns point forecasts with calibrated quantile prediction intervals, no training required. This skill wraps TimesFM for safe, agent friendly local inference. It includes a mandatory preflight system checker that verifies RAM, GPU memory, and disk space before the model is ever loaded so the agent never crashes a user's machine. Key numbers : TimesFM 2.5 uses 200M parameters (~800 MB on disk, ~1.5 GB in RAM on CPU, ~1 GB VRAM on GPU). The archived v1/v2 500M parameter model needs ~32 GB RAM. Always run the system checker first. When to Use This Skill Use this skill when: Forecasting any univariate time series (sales, demand, sensor, vitals, price, weather) You need zero shot forecasting without training a custom model You want probabilistic forecasts with calibrated prediction intervals (quantiles) You have time series of any length (the model handles 1–16,384 context points) You need to batch forecast hundreds or thousands of series efficiently You want a foundation model approach instead of hand tuning ARIMA/ETS parameters Do not use this skill when: You need classical statistical models with coefficient interpretation → use statsmodels You need time series classification or clustering → use aeon You need multivariate vector autoregression or Granger causality → use statsmodels Your data is tabular (not temporal) → use scikit learn Note on Anomaly Detection : TimesFM does not have built in anomaly detection, but you can use the quantile forecasts as prediction intervals — values outside the 90% CI (q10–q90) are statistically unusual. See the examples/anomaly detection/ directory for a full example. ⚠️ Mandatory Preflight: System Requirements Check CRITICAL — ALWAYS run the system checker before loading the model for the first time. This script checks: 1. Available RAM — warns if below 4 GB, blocks if below 2 GB 2. GPU availability — detects CUDA/MPS devices and VRAM 3. Disk space — verifies room for the ~800 MB model download 4. Python version — requires 3.10+ 5. Existing installation — checks if timesfm and torch are installed Note: Model weights are NOT stored in this repository . TimesFM weights (~800 MB) download on demand from HuggingFace on first use and cache in ~/.cache/huggingface/ . The preflight checker ensures sufficient resources before any download begins. Hardware Requirements by Model Version Model Parameters RAM (CPU) VRAM (GPU) Disk Context TimesFM 2.5 (recommended) 200M ≥ 4 GB ≥ 2 GB ~800 MB up to 16,384 TimesFM 2.0 (archived) 500M ≥ 16 GB ≥ 8 GB ~2 GB up to 2,048 TimesFM 1.0 (archived) 200M ≥ 8 GB ≥ 4 GB ~800 MB up to 2,048 Recommendation : Always use TimesFM 2.5 unless you have a specific reason to use an older checkpoint. It is smaller, faster, and supports 8× longer context. 🔧 Installation Step 1: Verify System (always first) Step 2: Install TimesFM Step 3: Install PyTorch for Your Hardware Step 4: Verify Installation 🎯 Quick Start Minimal Example (5 Lines) Forecast from CSV Forecast with Covariates (XReg) TimesFM 2.5+ supports exogenous variables through forecast with covariates() . Requires timesfm[xreg] . Covariate Type Description Example dynamic numerical Time varying numeric price, temperature, promotion spend dynamic categorical Time varying categorical holiday flag, day of week static numerical Per series numeric store size, account age static categorical Per series categorical store type, region, product category XReg Modes: "xreg + timesfm" (default): TimesFM forecasts first, then XReg adjusts residuals "timesfm + xreg" : XReg fits first, then TimesFM forecasts residuals See examples/covariates forecasting/ for a complete example with synthetic retail data. Anomaly Detection (via Quantile Intervals) TimesFM does not have built in anomaly detection, but the quantile forecasts naturally provide prediction intervals that can detect anomalies: Severity Condition Interpretation Normal Inside 80% CI Expected behavior Warning Outside 80% CI Unusual but possible Critical Outside 90% CI Statistically rare (< 10% probability) See examples/anomaly detection/ for a complete example with visualization. Output, Configuration, Workflows, and Tuning [references/output and config.md](references/output and config.md): reading the point forecast and the 10 quantile bands, deriving prediction intervals, and every ForecastConfig field. [references/workflows.md](references/workflows.md): the standard forecast sequence, many series forecasting from a wide CSV, and backtesting with interval coverage. [references/performance tuning.md](references/performance tuning.md): GPU and TF32 setup, per core batch size by available memory, and memory management. [references/examples and validation.md](references/examples and validation.md): runnable examples, the quality checklist, common mistakes, and regression checks. 🔗 Integration with Other Skills With statsmodels Use statsmodels for classical models (ARIMA, SARIMAX) as a comparison baseline : With matplotlib / scientific visualization Plot forecasts with prediction intervals as publication quality figures. With exploratory data analysis Run EDA on the time series before forecasting to understand trends, seasonality, and stationarity. 📚 Available Scripts scripts/check system.py Mandatory preflight checker. Run before first model load. Output example: scripts/forecast csv.py End to end CSV forecasting with automatic system check. 📖 Reference Documentation Detailed guides in references/ : File Contents references/system requirements.md Hardware tiers, GPU/CPU selection, memory estimation formulas references/api reference.md Full ForecastConfig docs, from pretrained options, output shapes references/data preparation.md Input formats, NaN handling, CSV loading, covariate setup Common Pitfalls 1. Not running system check → model load crashes on low RAM machines. Always run check system.py first. 2. Forgetting model.compile() → RuntimeError: Model is not compiled . Must call compile() before forecast() . 3. Not setting normalize inputs=True → unstable forecasts for series with large values. 4. Using v1/v2 on machines with < 32 GB RAM → use TimesFM 2.5 (200M params) instead. 5. Not setting fix quantile crossing=True → quantiles may not be monotonic (q10 q50). 6. Huge per core batch size on small GPU → CUDA OOM. Start small, increase. 7. Passing 2 D arrays → TimesFM expects a list of 1 D arrays , not a 2 D matrix. 8. Forgetting torch.set float32 matmul precision("high") → slower inference on Ampere+ GPUs. 9. Not handling NaN in output → edge cases with very short series. Always check np.isnan(point).any() . 10. Using infer is positive=True for series that can be negative → clamps forecasts at zero. Set False for temperature, returns, etc. Model Versions Version Params Context Quantile Head Frequency Flag Status 2.5 200M 16,384 ✅ Continuous (30M) ❌ Removed Latest 2.0 500M 2,048 ✅ Fixed buckets ✅ Required Archived 1.0 200M 2,048 ✅ Fixed buckets ✅ Required Archived Hugging Face checkpoints: google/timesfm 2.5 200m pytorch (recommended) google/timesfm 2.5 200m flax google/timesfm 2.0 500m pytorch (archived) google/timesfm 1.0 200m pytorch (archived) Resources Paper : [A Decoder Only Foundation Model for Time Series Forecasting](https://arxiv.org/abs/2310.10688) (ICML 2024) Repository : https://github.com/google research/timesfm Hugging Face : https://huggingface.co/collections/google/timesfm release 66e4be5fdb56e960c1e482a6 Google Blog : https://research.google/blog/a decoder only foundation model for time series forecasting/ BigQuery Integration : https://cloud.google.com/bigquery/docs/timesfm model

timesfm-forecasting