timesfm-forecasting
Performs zero-shot time-series forecasting with Google's TimesFM, including regular-grid CSV preparation, quantile forecasts, XReg covariates, and held-out evaluation. Uses the Apache-licensed TimesFM 2.5 checkpoint by default and documents the distinct TimesFM 3.0 multivariate API and weight-license requirements.
- Installs
- 2K
- Last 24h
- +13
- Trending rank
- #7722
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/k-dense-ai/scientific-agent-skills --skill timesfm-forecasting- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads timesfm-forecasting automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
TimesFM Forecasting
Choose the model/API first
The Python package version is 3.0.2; checkpoint versions are separate.
| Checkpoint | Interface | Quantile output | Usage terms |
|---|---|---|---|
| 2.5, 200M | timesfm.TimesFM_2p5_200M_torch, compile, forecast | mean + 9 deciles, median index 5 | Apache-2.0 weights; bundled CLI default |
| 3.0, about 330M | timesfm3.TimesFM3Forecaster, predict / predict_batch | 9 deciles, median index 4 | Downloaded weights restricted to non-commercial, non-production use |
Upstream identifies 3.0 as the latest model. This skill retains 2.5 as its default local workflow because its Apache-licensed weights have different usage terms. For 3.0 multivariate targets, past-only covariates or Apple MLX, read references/timesfm3.md before adapting code. Authorized Google Cloud services have separate terms; a Cloud entitlement does not change the license of downloaded weights. See the upstream license notice.
Use TimesFM for forecasting an ordered temporal target without task-specific model training. It is not a causal effect estimator, clinical detector, or physics-based climate model. Zero-shot describes fitting; it does not establish absence of benchmark overlap in pretraining or good accuracy in a new domain.
Workflow
- Establish cadence, units, forecast origin, horizon, known-at-origin covariates, evaluation cutoffs and a naive/seasonal-naive baseline.
- Validate a sorted, unique, regular time grid. Do not
dropna()internal gaps: that changes temporal spacing. Reject nonfinite inputs, or explicitly impute inside each training history. Never fill using held-out future targets. - Run
python scripts/check_system.pybefore downloading/loading weights. Its available-RAM and cache-volume thresholds are heuristics, not a guarantee against OOM. Start with batch size 1; measure actual peak usage. - Load the chosen checkpoint with a recorded immutable revision. For 2.5, compile explicit positive context/horizon settings; zero does not mean “use the maximum.” Keep patch-rounded context + horizon <=16,384 and horizon <=1,024 when using the continuous quantile head.
- Forecast, validate shapes/finite values/quantile ordering and export the forecast origin, frequency, configuration and checkpoint revision.
- Evaluate across rolling origins with preprocessing fitted independently per origin. Report accuracy, interval coverage and interval width by horizon; label quantile intervals nominal until calibrated on relevant data.
Installation
Run in a separate environment. The commands below target the reviewed release. Shell extras and version constraints must be quoted, particularly in zsh.
uv venv .venv-timesfm
uv pip install --python .venv-timesfm/bin/python "timesfm[torch]==3.0.2" numpy pandas
.venv-timesfm/bin/python scripts/check_system.py
Use the current PyTorch installation selector
for a CUDA wheel matching the host. The 2.5 loader in this release chooses
cuda:0 if CUDA exists, otherwise CPU; detecting MPS does not enable MPS
inference. Do not use model.to(...) on the wrapper as if it were an nn.Module.
For CPU-only XReg, install jax and scikit-learn alongside the PyTorch profile;
the upstream [xreg] extra requests jax[cuda], which is not appropriate for macOS.
Flax is a separate optional backend; it is not required by the bundled scripts.
from importlib.metadata import version
import timesfm
print(version("timesfm")) # package has no guaranteed timesfm.__version__
assert hasattr(timesfm, "TimesFM_2p5_200M_torch")
TimesFM 2.5 quick start
The checkpoint-load examples are illustrative: validation of this refresh used native package code with tiny random models and controlled decode fixtures, without downloading pretrained weights. That verifies mechanics, not accuracy.
import numpy as np
import timesfm
model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
"google/timesfm-2.5-200m-pytorch",
revision="1d952420fba87f3c6dee4f240de0f1a0fbc790e3",
torch_compile=False, # avoid compilation startup during an initial smoke run
)
model.compile(timesfm.ForecastConfig(
max_context=512, max_horizon=128, per_core_batch_size=1,
normalize_inputs=True, use_continuous_quantile_head=True,
force_flip_invariance=True, infer_is_positive=False,
fix_quantile_crossing=True,
))
histories = [np.sin(np.linspace(0, 20, 200)).astype(np.float32)]
# 2.5 may append dummy series to its input list during batching; pass a fresh list.
point, q = model.forecast(horizon=24, inputs=list(histories))
assert point.shape == (1, 24) and q.shape == (1, 24, 10)
assert np.isfinite(q).all() and np.all(np.diff(q[..., 1:], axis=-1) >= 0)
assert np.allclose(point, q[..., 5])
lower_80, upper_80 = q[..., 1], q[..., 9] # q10-q90: nominal 80% PI
lower_60, upper_60 = q[..., 2], q[..., 8] # q20-q80: nominal 60% PI
Set infer_is_positive=True only for a target domain that is truly nonnegative.
A positive observed window does not establish that temperature anomalies,
returns or residuals cannot become negative. Monotonic quantiles and a
continuous quantile head do not establish interval calibration.
CSV helper
python scripts/forecast_csv.py monthly_sales.csv \
--date-col date --freq MS --value-cols sales,revenue \
--horizon 12 --batch-size 1 --nonnegative --output forecasts.csv
forecast_csv.py validates before loading, sorts dates, rejects duplicate
headers/dates, checks the complete regular grid and preserves missing positions.
Missing values fail by default; --missing interpolate fills only internal gaps,
never leading/trailing values. Without --date-col, row order is assumed to be
the regular grid and output uses steps. Numeric IDs must be excluded using
--value-cols. --max-context controls history truncation; --horizon is limited
to 1..1,024 for this quantile-head workflow.
Outputs retain forecast, median, lower_80, upper_80, lower_60, upper_60.
A .metadata.json sidecar records origin, cadence, model revision and config.
Old skill releases mislabeled q10-q90/q20-q80 as 90%/80%; migrate old outer
*_90 to *_80 and old inner *_80 to *_60 simultaneously. Old generated
example forecasts were removed because their mapping/provenance was invalid.
Covariates and anomaly screening
For 2.5 XReg, compile return_backcast=True, retain targets and covariates on
identical grids and provide dynamic covariates over context and horizon.
"xreg + timesfm" fits regression on targets, then forecasts regression residuals.
"timesfm + xreg" forecasts first, then fits regression on backcast residuals.
The latter needs more than one input patch (32 observations). In package 3.0.2,
the implementation returns lists of combined point and quantile forecasts;
an inherited docstring incorrectly describes the second return as XReg-only.
See references/api_reference.md for the complete call.
Quantile exceedances may screen for unusual observations, but even calibrated 80% intervals exclude about 20% of ordinary observations marginally. They do not supply anomaly probabilities, familywise control or validated alarm severity. Retrospective detrended Z scores also differ from prospective anomaly detection.
References and examples
- API reference: 2.5 loader, compile, forecast and XReg contracts.
- Output/config: all real ForecastConfig fields and interval indexing.
- Data preparation: grid, missingness, covariate timing and format recipes.
- Workflows: held-out and rolling-origin validation, baseline comparisons.
- System requirements: resource checks and backend requirements.
- Performance tuning: measured batch/context tuning.
- Examples and validation: example commands and testing scope.
- TimesFM 3.0: multivariate API, 9-decile layout and usage boundary.
Primary review sources: official source, 3.0.2 distribution, 2.5 model card, 3.0 model card.
FAQ
What does the timesfm-forecasting skill do?
Performs zero-shot time-series forecasting with Google's TimesFM, including regular-grid CSV preparation, quantile forecasts, XReg covariates, and held-out evaluation. Uses the Apache-licensed TimesFM 2.5 checkpoint by default and documents the distinct TimesFM 3.0 multivariate API and weight-license requirements.
How do I install timesfm-forecasting?
Run npx skills add https://github.com/k-dense-ai/scientific-agent-skills --skill timesfm-forecasting in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/timesfm-forecasting/ (personal) or .claude/skills/timesfm-forecasting/ (project).
Which AI agents can use timesfm-forecasting?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is timesfm-forecasting safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains timesfm-forecasting?
It is published by k-dense-ai in k-dense-ai/scientific-agent-skills. It has 1,961 recorded installs.
More from k-dense-ai/scientific-agent-skills
scientific-writing
k-dense-ai/scientific-agent-skills
Drafts, revises, and audits scientific manuscripts or reports with explicit evidence provenance, reporting-guideline coverage, authorship accountability, confidentiality controls, and local consistency checks. Use for manuscript sections, references, declarations, tables, figures, or submission preparation when scientific accuracy and traceability matter.
scientific-visualization
k-dense-ai/scientific-agent-skills
Creates and audits truthful, accessible, publication-ready scientific figures with Matplotlib, Seaborn, or Plotly. Use it for figure design, multi-panel layouts, uncertainty and missing-data displays, color/contrast review, image metadata validation, and journal export planning.
scientific-critical-thinking
k-dense-ai/scientific-agent-skills
Evaluates scientific claims and evidence quality. Applies to experimental design validity, biases and confounders, statistical interpretation, evidence grading frameworks (GRADE, Cochrane Risk of Bias), and teaching critical analysis. Supports evidence appraisal and identifying flaws; formal peer review writing belongs to peer-review.
literature-review
k-dense-ai/scientific-agent-skills
Conducts systematic, scoping, and narrative literature reviews using PubMed, arXiv, bioRxiv, Semantic Scholar, and other appropriate sources. Use for research synthesis, reproducible literature searches, screening, citation checking, or preparing Markdown and PDF reviews. Tracks search coverage, records versus studies, and evidence limitations; supports meta-analysis planning but does not supply a meta-analysis engine.
scientific-brainstorming
k-dense-ai/scientific-agent-skills
Facilitates evidence-aware scientific ideation with independent generation, structured discussion, explicit assumptions, transparent evaluation, adversarial review, and decision logs. Use for early-stage research brainstorming or prioritizing candidate directions; hand off empirical validation, study design, ethics or regulatory review, and clinical questions to appropriate experts or skills.
statistical-analysis
k-dense-ai/scientific-agent-skills
Guided statistical analysis for research data - test selection, assumption checking, effect sizes, power analysis, Bayesian alternatives, and APA-formatted reporting. Use whenever a user wants to compare groups, test a hypothesis, analyze experimental or survey data, check statistical assumptions, compute required sample sizes, or write up results - even if they never name a specific test. Covers t-tests, ANOVA, chi-square, correlation, regression, non-parametric and Bayesian methods. For low-level model APIs, see the statsmodels and pymc skills.
Popular backend & apis skills
find-skills
vercel-labs/skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.