PEFTTrainer with production-grade training loop:
- PyTorch DDP multi-GPU via torchrun
- Mixed-precision training (fp16/bf16) with GradScaler
- Gradient checkpointing for long contexts
- Cosine-with-warmup LR schedule
- MSE loss + optional pinball quantile loss (9 channels)
- Early stopping on validation loss
- Adapter-only checkpointing (safetensors)
- W&B logging (rank-0 only)
- Differentiable training forward that replicates the 2.5
patch -> RevIN -> transformer -> output-head -> un-RevIN path
Sliding-window dataset that produces (context, mask, target) tuples:
- Accepts list of arrays, long-format, or wide-format DataFrames
- Context length auto-rounded to multiple of patch_len (32)
- Left-pads short series with proper masking
- Configurable stride for window overlap
- Add context limit rationale to system_requirements.md with memory formula
- Update SKILL.md to include XReg/covariates in description and usage sections
- Add dataset-aware memory estimation to check_system.py with new CLI args
- Document memory estimation in api_reference.md with Mermaid diagram
- Add dataset preflight section to SKILL.md with examples
Resolves review comments about:
- How context limits (512/1024) were determined
- Including XReg mode description in skill documentation
Bonus enhancement: Dataset preflight checking prevents OOM before loading data.
Short pointer for agents working directly in this repo.
Points to timesfm-forecasting/SKILL.md and provides
install commands for the first-party Agent Skill.
Add a self-contained AI agent skill for TimesFM that teaches coding
agents (Claude Code, OpenCode, Cursor, Codex) how to use the TimesFM
API correctly — safe model loading, zero-shot forecasting, covariate
workflows, anomaly detection, and the most common pitfalls.
Files added:
- AGENTS.md — auto-loaded skill document (root of repo)
- claude-skill/scripts/check_system.py — mandatory preflight RAM/GPU/disk checker
- claude-skill/scripts/forecast_csv.py — CLI wrapper for CSV forecasting
- claude-skill/references/ — ForecastConfig API ref, data prep, HW reqs
- claude-skill/examples/global-temperature/ — basic forecast + PNG/GIF pipeline
- claude-skill/examples/anomaly-detection/ — two-phase detrend+Z-score + quantile PI
- claude-skill/examples/covariates-forecasting/ — forecast_with_covariates() XReg demo
- .gitattributes — Git LFS rules for PNG/GIF binary outputs
Contributed by Clayton Young / Superior Byte Works LLC (@borealBytes)
Apache 2.0 — same license as this repository
1. Masked variance calculation (lines 95-107): Changed from the numerically unstable E[X²] - E[X]² formula to the stable centered formula E[(X-μ)²]
2. Sigma clamping (line 609): Changed from torch.where(sigma < tolerance, 1.0, sigma) to torch.clamp(sigma, min=tolerance)
darkpowerxo