Add TimesFM 2.5: First Foundation Model Integration

[nehalecky]

Add TimesFM 2.5: First Foundation Model Integration

Fixes #2359

Summary

This PR integrates TimesFM 2.5, Google Research's foundation model for time series forecasting, as the first foundation model in Darts. TimesFM 2.5 is a 200M parameter decoder-only transformer trained on 100 billion time points, enabling zero-shot forecasting without training.

Implementation

Core Changes:

• New darts/models/forecasting/foundation/ package containing:
  • TimesFMModel: Main model class extending GlobalForecastingModel
  • FoundationForecastingModel: Base class included as foundation for the full suite of foundation models (Chronos 2, etc.)
  • Device utilities and PEFT infrastructure included as foundation for future fine-tuning research
• Integration with existing Darts workflows (historical_forecasts, backtest, metrics)
• Lazy loading pattern - downloads google/timesfm-2.5-200m-pytorch automatically on first use

Testing:

• 25 unit tests covering construction, fit, predict, and edge cases
• All tests passing
• Test coverage for zero-shot prediction, batch forecasting, and multivariate component selection

Documentation:

• User guide at docs/userguide/foundation_models.md:
  • Introduction to Time Series Foundation Models (TSFMs)
  • Distinction between covariates (temporal causality) and few-shot examples (pattern templates)
  • API design decisions explained
  • Installation and usage examples
• Tutorial notebook at examples/25-TimesFM-foundation-model.ipynb
• Updated CHANGELOG and INSTALL guide

Key Features

• Zero-shot forecasting: Predict immediately without training
• Device support: CPU, CUDA, MPS (Apple Silicon) with automatic detection
• Univariate forecasting: Experimentally verified as univariate-only
• Context length: Configurable up to 1,536 points (must be multiple of 32)
• Flexible horizons: Any prediction length supported

Technical Decisions

Why GlobalForecastingModel?
TimesFM 2.5 extends GlobalForecastingModel rather than a custom base class to ensure compatibility with existing Darts utilities and workflows. The FoundationForecastingModel base class is included as foundation for the full suite of foundation models (Chronos 2 and others) that may require different patterns.

Why does fit() exist?
For API compatibility with Darts utilities that require fit() before predict(). Currently, the method validates inputs and loads the model but doesn't perform training (pre-trained weights remain frozen). In future implementations, fit() can be overloaded to support fine-tuning using parameter-efficient techniques like LoRA through the PEFT ecosystem, maintaining the familiar Darts API while enabling state-of-the-art adaptation workflows.

Lazy loading:
Calling predict() without fit() automatically loads the model, enabling pure zero-shot workflows.

Performance

Zero-shot on Air Passengers dataset: MAPE 6.59% (no training required)

Comparison: TimesFM (6.59%) outperforms fitted ExponentialSmoothing (8.10%) despite never seeing the series before.

Installation

# Using pip
pip install "darts[timesfm]"

# Using uv (recommended for faster installation)
uv pip install "darts[timesfm]"

See INSTALL.md for detailed installation instructions.

Future Work

This establishes patterns for integrating additional foundation models mentioned in #2359:

• Chronos 2 (Amazon Science) - multivariate, covariate support, probabilistic forecasts
• Other models as they become available

The FoundationForecastingModel base class and PEFT utilities are included as foundations for integrating the full suite of foundation models and enabling future fine-tuning research, but are not currently exposed to users.

Breaking Changes

None - purely additive feature.

Known Limitations

• Univariate only (multivariate support requires future models)
• No covariate support
• Zero-shot inference only (fine-tuning infrastructure exists for future research)
• Maximum context length: 1,536 points

---

Acknowledgments and Future Collaboration

Thank you to the Darts maintainers for building such an excellent library. This integration represents a first contribution in bringing foundation model capabilities to the time series community, and I'm excited to collaborate on future enhancements.

Related community requests:

• #2933 - Chronos 2 integration request (October 2025)
• #2359 - Foundation models tracking (April 2024)

Happy to contribute to additional foundation model integrations and continue improving this implementation based on maintainer and community feedback. The patterns established here are designed to make future integrations straightforward while maintaining Darts' excellent API design principles.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[dennisbader]

Hi @nehalecky and thanks for giving this a go 🚀 Before reviewing, I would actually like to take a step back and think about how we want to do this properly in Darts. We have started a discussion in #2933, feel free to join and share your feedback :)

[nehalecky]

Hi @dennisbader! I'm closing out this PR in favor of the new implementation at #2942 that addresses the design discussion from #2933.

The new approach evolved from this TimesFM-only implementation into a unified foundation models architecture with a FoundationForecastingModel base class. It now includes both TimesFM 2.5 and Chronos 2, with working support for multivariate forecasting, covariates, and PEFT/LoRA fine-tuning. The implementation addresses all the architectural concerns raised in the #2933 discussion - lazy loading for CI/CD, dual-path fit() for dimensionality tracking, mock-based testing, and comprehensive documentation.

The full design document is at https://gist.github.com/nehalecky/4807ffe147321914387858dd4633c5c7 and I've posted details in the issue thread at #2933 (comment).

Looking forward to your feedback on the unified architecture!

[nehalecky]

Superseded by #2942