- Allow model wrapper constructors (__init__) to accept and ignore extra keyword arguments (e.g. proxies) passed by huggingface_hub during from_pretrained.
- Implement load_checkpoint for TimesFM_2p5_200M_torch and TimesFM_2p5_200M_flax to restore weights from local paths.
- Fix slicing bug in PyTorch's forecast_naive to correctly slice the time/horizon dimension ([:, :horizon, :]) instead of quantiles.
- Add unit tests in tests/test_model_loading.py covering local checkpoint loading, hub compatibility, and prediction shape correctness.
Remove the custom peft/ directory (LoRA/DoRA adapters, trainer, data
pipeline) in favor of a lightweight fine-tuning example that uses the
standard HuggingFace Transformers + PEFT ecosystem.
The new example at timesfm-forecasting/examples/finetuning/ demonstrates
LoRA fine-tuning via TimesFm2_5ModelForPrediction and the peft library,
based on the approach by @kashif at HuggingFace.
- Remove peft/ (8 files)
- Add timesfm-forecasting/examples/finetuning/finetune_lora.py
- Add timesfm-forecasting/examples/finetuning/README.md
- Update README.md to reference new example
- Clean up .gitignore (remove peft_checkpoints/)
- Initialize LoRA parameters on the same device as the base linear layer
- Load adapter weights directly to the model device instead of hardcoded CPU
- Slice XReg linear regression outputs to match the specified sequence lengths
- Replace batch-wide covariate normalization with per-input normalization
in create_covariate_matrix to prevent cross-input scale leakage.
- Refactor BatchedInContextXRegLinear.fit to solve ridge regression
per instance rather than as a single global matrix solve, avoiding
cross-contamination between batched inputs.
- Truncate JAX regression outputs to the actual train/test lengths
after the padded matrix multiply, fixing shape mismatches for
non-power-of-2 horizons (e.g. horizon=24 was returning 32 elements).
- Add Apr. 2026 update entry for PEFT pipeline, unit tests, and community fixes
- Replace 'under construction' numbered list with checklist of completed items:
Flax model, covariate support, docs/examples, PEFT pipeline, unit tests
Apply changes from PR #391 by @MarcoGorworworelli:
- Fix train_gen() to iterate in proper batch_size chunks instead of
yielding all time series at once when permute=False
- Add test_data_loader.py to verify batch boundaries
Apply changes from PR #393 by @MarcoGorworworelli:
- Normalize covariates per-input instead of batch-wide to prevent
each input's result from depending on batch composition
- Fit separate ridge regressions per time series instead of a single
batched regression, preventing cross-series data leakage
- Applied to both src/timesfm/utils/xreg_lib.py and v1/src/timesfm/xreg_lib.py
Apply changes from PR #396 by @shahrukhx01:
- Fix typo 'complied' -> 'compiled' in ForecastConfig docstrings
- Replace bare print() with logging.info() in load_checkpoint()
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)
Rajat Sen