timesfm-forecasting
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 checker script to verify RAM/GPU before first use.
Install this skill
Works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and 70+ other harnesses.
npx skills add KalarisLabs/research-agent-skills --skill timesfm-forecastinguvx research-agent-skills install timesfm-forecastingDocumentation & Instructions
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.
python scripts/check_system.py
This script checks:
- Available RAM — warns if below 4 GB, blocks if below 2 GB
- GPU availability — detects CUDA/MPS devices and VRAM
- Disk space — verifies room for the ~800 MB model download
- Python version — requires 3.10+
- Existing installation — checks if
timesfmandtorchare 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.
flowchart TD
accTitle: Preflight System Check
accDescr: Decision flowchart showing the system requirement checks that must pass before loading TimesFM.
start["🚀 Run check_system.py"] --> ram{"RAM ≥ 4 GB?"}
ram -->|"Yes"| gpu{"GPU available?"}
ram -->|"No (2-4 GB)"| warn_ram["⚠️ Warning: tight RAM<br/>CPU-only, small batches"]
ram -->|"No (< 2 GB)"| block["🛑 BLOCKED<br/>Insufficient memory"]
warn_ram --> disk
gpu -->|"CUDA / MPS"| vram{"VRAM ≥ 2 GB?"}
gpu -->|"CPU only"| cpu_ok["✅ CPU mode<br/>Slower but works"]
vram -->|"Yes"| gpu_ok["✅ GPU mode<br/>Fast inference"]
vram -->|"No"| cpu_ok
gpu_ok --> disk{"Disk ≥ 2 GB free?"}
cpu_ok --> disk
disk -->|"Yes"| ready["✅ READY<br/>Safe to load model"]
disk -->|"No"| block_disk["🛑 BLOCKED<br/>Need space for weights"]
classDef ok fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
classDef warn fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
classDef block fill:#fee2e2,stroke:#dc2626,stroke-width:2px,color:#7f1d1d
classDef neutral fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937
class ready,gpu_ok,cpu_ok ok
class warn_ram warn
class block,block_disk block
class start,ram,gpu,vram,disk neutral
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)
python scripts/check_system.py
Step 2: Install TimesFM
# Using uv (recommended by this repo)
uv pip install timesfm[torch]
# For JAX/Flax backend (faster on TPU/GPU)
uv pip install timesfm[flax]
Step 3: Install PyTorch for Your Hardware
# CUDA 12.1 (NVIDIA GPU)
uv pip install torch>=2.0.0 --index-url https://download.pytorch.org/whl/cu121
# CPU only
uv pip install torch>=2.0.0 --index-url https://download.pytorch.org/whl/cpu
# Apple Silicon (MPS)
uv pip install torch>=2.0.0 # MPS support is built-in
Step 4: Verify Installation
import timesfm
import numpy as np
print(f"TimesFM version: {timesfm.__version__}")
print("Installation OK")
🎯 Quick Start
Minimal Example (5 Lines)
import torch, numpy as np, timesfm
torch.set_float32_matmul_precision("high")
model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
"google/timesfm-2.5-200m-pytorch"
)
model.compile(timesfm.ForecastConfig(
max_context=1024, max_horizon=256, normalize_inputs=True,
use_continuous_quantile_head=True, force_flip_invariance=True,
infer_is_positive=True, fix_quantile_crossing=True,
))
point, quantiles = model.forecast(horizon=24, inputs=[
np.sin(np.linspace(0, 20, 200)), # any 1-D array
])
# point.shape == (1, 24) — median forecast
# quantiles.shape == (1, 24, 10) — 10th–90th percentile bands
Forecast from CSV
import pandas as pd, numpy as np
df = pd.read_csv("monthly_sales.csv", parse_dates=["date"], index_col="date")
# Convert each column to a list of arrays
inputs = [df[col].dropna().values.astype(np.float32) for col in df.columns]
point, quantiles = model.forecast(horizon=12, inputs=inputs)
# Build a results DataFrame
for i, col in enumerate(df.columns):
last_date = df[col].dropna().index[-1]
future_dates = pd.date_range(last_date, periods=13, freq="MS")[1:]
forecast_df = pd.DataFrame({
"date": future_dates,
"forecast": point[i],
"lower_80": quantiles[i, :, 2], # 20th percentile
"upper_80": quantiles[i, :, 8], # 80th percentile
})
print(f"\n--- {col} ---")
print(forecast_df.to_string(index=False))
Forecast with Covariates (XReg)
TimesFM 2.5+ supports exogenous variables through forecast_with_covariates(). Requires timesfm[xreg].
# Requires: uv pip install timesfm[xreg]
point, quantiles = model.forecast_with_covariates(
inputs=inputs,
dynamic_numerical_covariates={"price": price_arrays},
dynamic_categorical_covariates={"holiday": holiday_arrays},
static_categorical_covariates={"region": region_labels},
xreg_mode="xreg + timesfm", # or "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:
point, q = model.forecast(horizon=H, inputs=[values])
# 90% prediction interval
lower_90 = q[0, :, 1] # 10th percentile
upper_90 = q[0, :, 9] # 90th percentile
# Detect anomalies: values outside the 90% CI
actual = test_values # your holdout data
anomalies = (actual < lower_90) | (actual > upper_90)
# Severity levels
is_warning = (actual < q[0, :, 2]) | (actual > q[0, :, 8]) # outside 80% CI
is_critical = anomalies # outside 90% CI
| 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.
# Requires: uv pip install timesfm[xreg]
point, quantiles = model.forecast_with_covariates(
inputs=inputs,
dynamic_numerical_covariates={"temperature": temp_arrays},
dynamic_categorical_covariates={"day_of_week": dow_arrays},
static_categorical_covariates={"region": region_labels},
xreg_mode="xreg + timesfm", # or "timesfm + xreg"
)
Output, Configuration, Workflows, and Tuning
- references/output_and_config.md: reading the point
forecast and the 10 quantile bands, deriving prediction intervals, and every
ForecastConfigfield. - references/workflows.md: the standard forecast sequence, many-series forecasting from a wide CSV, and backtesting with interval coverage.
- references/performance_tuning.md: GPU and TF32
setup,
per_core_batch_sizeby available memory, and memory management. - 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:
# TimesFM forecast
tfm_point, tfm_q = model.forecast(horizon=H, inputs=[values])
# statsmodels ARIMA forecast
from statsmodels.tsa.arima.model import ARIMA
arima = ARIMA(values, order=(1,1,1)).fit()
arima_forecast = arima.forecast(steps=H)
# Compare
print(f"TimesFM MAE: {np.mean(np.abs(actual - tfm_point[0])):.2f}")
print(f"ARIMA MAE: {np.mean(np.abs(actual - arima_forecast)):.2f}")
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.
python scripts/check_system.py
Output example:
=== TimesFM System Requirements Check ===
[RAM] Total: 32.0 GB | Available: 24.3 GB ✅ PASS
[GPU] NVIDIA RTX 4090 | VRAM: 24.0 GB ✅ PASS
[Disk] Free: 142.5 GB ✅ PASS
[Python] 3.12.1 ✅ PASS
[timesfm] Installed (2.5.0) ✅ PASS
[torch] Installed (2.4.1+cu121) ✅ PASS
VERDICT: ✅ System is ready for TimesFM 2.5 (GPU mode)
Recommended: per_core_batch_size=128
scripts/forecast_csv.py
End-to-end CSV forecasting with automatic system check.
python scripts/forecast_csv.py input.csv \
--horizon 24 \
--date-col date \
--value-cols sales,revenue \
--output forecasts.csv
📖 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
- Not running system check → model load crashes on low-RAM machines. Always run
check_system.pyfirst. - Forgetting
model.compile()→RuntimeError: Model is not compiled. Must callcompile()beforeforecast(). - Not setting
normalize_inputs=True→ unstable forecasts for series with large values. - Using v1/v2 on machines with < 32 GB RAM → use TimesFM 2.5 (200M params) instead.
- Not setting
fix_quantile_crossing=True→ quantiles may not be monotonic (q10 > q50). - Huge
per_core_batch_sizeon small GPU → CUDA OOM. Start small, increase. - Passing 2-D arrays → TimesFM expects a list of 1-D arrays, not a 2-D matrix.
- Forgetting
torch.set_float32_matmul_precision("high")→ slower inference on Ampere+ GPUs. - Not handling NaN in output → edge cases with very short series. Always check
np.isnan(point).any(). - Using
infer_is_positive=Truefor series that can be negative → clamps forecasts at zero. Set False for temperature, returns, etc.
Model Versions
timeline
accTitle: TimesFM Version History
accDescr: Timeline of TimesFM model releases showing parameter counts and key improvements.
section 2024
TimesFM 1.0 : 200M params, 2K context, JAX only
TimesFM 2.0 : 500M params, 2K context, PyTorch + JAX
section 2025
TimesFM 2.5 : 200M params, 16K context, quantile head, no frequency indicator
| 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-flaxgoogle/timesfm-2.0-500m-pytorch(archived)google/timesfm-1.0-200m-pytorch(archived)
Resources
- Paper: A Decoder-Only Foundation Model for Time-Series Forecasting (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
Related skills
aeon: This skill should be used for time series machine learning tasks including classification, regression, clustering, forecasting, anomaly det…statsmodels: Statistical models library for Python.segment-anything-model: Foundation model for image segmentation with zero-shot transfer.
Trigger Prompts & Evaluation Corpus
These evaluation prompts test that the agent correctly selects timesfm-forecasting for relevant tasks and leaves it out for near misses.
Should trigger (3)
- should trigger
“Forecast the next 30 days from this daily series, no training please.”
expects Uses TimesFM zero-shot: runs the check_system.py preflight, loads TimesFM 2.5, compiles with ForecastConfig, and forecasts horizon=30. Returns point forecasts and quantile intervals, and passes a list of 1-D arrays.
- should trigger
“I have hourly_power.csv with a 'load_kw' column, about 20k hourly readings from a campus substation. I'm on a laptop with 8 GB RAM and no GPU. Can you predict the next 48 hours with an uncertainty band? I hit a 'Model is not compiled' RuntimeError last time I tried a pretrained forecaster.”
expects Runs scripts/check_system.py first and notes that 8 GB RAM is enough for the 200M TimesFM 2.5 model on CPU. Explains that model.compile(ForecastConfig(...)) must be called before forecast(), and that the context is capped at 16,384 points, so the series is truncated to the most recent values. Sets normalize_inputs=True and fix_quantile_crossing=True, forecasts horizon=48, and derives the q10–q90 interval from the quantile output. Checks the output for NaN.
- should trigger
“We log blood glucose from 300 patients every 5 minutes in a wide CSV, one column per patient. I don't have time to fit a model per patient, but I need a 2-hour-ahead forecast for each of them, plus a way to flag readings that look abnormally off from what was expected.”
expects Recommends a pretrained zero-shot foundation model (TimesFM) and batch-forecasts all columns as a list of 1-D arrays. Horizon is 24 steps at 5-minute resolution. Uses infer_is_positive carefully, and flags anomalies as values outside the quantile prediction intervals (for example outside q10–q90 as critical). Runs the preflight check first.
Near misses (2)
- near miss
“I need to fit a SARIMAX model on monthly unemployment data with an exogenous interest rate variable and interpret the coefficients and their p-values. Which skill should I use and how do I do it?”
expects Does not use TimesFM. Directs to statsmodels for SARIMAX with exogenous regressors, coefficient estimates, and significance tests, since the user wants interpretable classical model parameters.
- near miss
“I have labeled accelerometer recordings of different activities and want to train a time series classifier to predict the activity label, and also cluster the unlabeled ones.”
expects Does not use TimesFM, which is a forecasting model. Recommends the aeon skill for time series classification and clustering, e.g. ROCKET or k-means with DTW.