Skip to content
Research Agent Skillsby Kalaris Labs
Install
Data Science and MLv1.2AdaptedApache-2.0 license

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.

skills.sh CLI (Recommended)
npx skills add KalarisLabs/research-agent-skills --skill timesfm-forecasting
uvx (Python tool runner)
uvx research-agent-skills install timesfm-forecasting

Documentation & 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:

  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.

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

🔗 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

  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

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-flax
  • google/timesfm-2.0-500m-pytorch (archived)
  • google/timesfm-1.0-200m-pytorch (archived)

Resources

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.