Skill

Pass

Audit score 90

timesfm-forecasting

k-dense-ai/scientific-agent-skills

Zero-shot time series forecasting with Google's TimesFM foundation model—no training required.

What is timesfm-forecasting?

TimesFM is a pretrained decoder-only foundation model for univariate time series forecasting. Feed it any time series (sales, sensors, energy, weather, vitals) and get point forecasts with calibrated prediction intervals instantly. Use when you need probabilistic forecasts without training a custom model.

Forecasts any univariate time series zero-shot without training
Returns point forecasts and calibrated quantile prediction intervals (10th–90th percentile bands)
Handles time series of any length from 1 to 16,384 context points
Supports batch forecasting of hundreds or thousands of series efficiently
Includes mandatory preflight system checker to verify RAM, GPU, and disk before loading the model
Supports exogenous variables (covariates) through optional xreg mode

How to install timesfm-forecasting

npx skills add https://github.com/k-dense-ai/scientific-agent-skills --skill timesfm-forecasting

Prerequisites

Python 3.10 or later
4 GB RAM minimum (2 GB will block; 2–4 GB will warn)
2 GB free disk space for model weights (~800 MB download)
PyTorch 2.0+ installed for your hardware (CUDA, CPU, or Apple Silicon)
Run `python scripts/check_system.py` before first use (mandatory)

Claude Code

Cursor

Windsurf

Cline

How to use timesfm-forecasting

1.Run the preflight system checker: `python scripts/check_system.py`
2.Install TimesFM: `uv pip install timesfm[torch]`
3.Install PyTorch for your hardware (CUDA, CPU, or MPS)
4.Load the model: `model = timesfm.TimesFM_2p5_200M_torch.from_pretrained("google/timesfm-2.5-200m-pytorch")`
5.Compile with forecast config: `model.compile(timesfm.ForecastConfig(...))`
6.Call `model.forecast(horizon=N, inputs=[array1, array2, ...])` to get point and quantile forecasts
7.Optionally use `forecast_with_covariates()` to include exogenous variables

Use cases

Good for

Forecast monthly sales or demand without building a custom ARIMA model
Generate probabilistic energy consumption forecasts for grid planning
Detect anomalies in sensor data by flagging values outside the 90% prediction interval
Batch-forecast thousands of product SKUs or regional metrics simultaneously
Forecast weather-dependent metrics (e.g., ice cream sales) with optional weather covariates

Who it's for

Data scientists and analysts who need quick probabilistic forecasts
Operations teams forecasting demand, inventory, or resource usage
Engineers monitoring sensor or system metrics
Anyone avoiding the complexity of hand-tuning statistical models

timesfm-forecasting FAQ

Do I need to train the model on my data?

No. TimesFM is a zero-shot foundation model—it works out of the box on any univariate time series without training.

What hardware do I need?

Minimum 4 GB RAM (2–4 GB will work but with warnings). GPU with 2+ GB VRAM is optional but recommended for speed. Always run the preflight checker first.

Can I use this for multivariate forecasting or causal analysis?

No. TimesFM handles univariate series only. For multivariate vector autoregression or Granger causality, use statsmodels instead.

How do I detect anomalies with TimesFM?

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.

What if I need to include external variables like price or holidays?

TimesFM 2.5+ supports exogenous variables through forecast_with_covariates(). Install with `timesfm[xreg]` and pass dynamic or static covariates.

Full instructions (SKILL.md)

Source of truth, from k-dense-ai/scientific-agent-skills.

name: timesfm-forecasting description: 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. allowed-tools: Read Write Edit Bash license: Apache-2.0 license metadata: version: "1.2" skill-author: Clayton Young / Superior Byte Works, LLC (@borealBytes) skill-version: 1.0.0

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 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

references/output_and_config.md: reading the point forecast and the 10 quantile bands, deriving prediction intervals, and every ForecastConfig field.
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_size by 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.py first.
Forgetting model.compile() → RuntimeError: Model is not compiled. Must call compile() before forecast().
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_size on 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=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