TimesFM.rb

Time series forecasting for Ruby using TimesFM (Time Series Foundation Model) from Google Research.

Inspired by prophet-ruby, this gem provides a lightweight Ruby wrapper that spawns a Python CLI process for TimesFM inference.

Features

• Simple API for time series forecasting
• Supports multiple time series inputs
• GPU acceleration support
• Quantile forecasts (optional)
• Context length configuration
• Works with Ruby date/time objects

Installation

Add this line to your application's Gemfile:

gem "timesfm-rb"

Then install the gem:

bundle install

Python Dependencies

TimesFM requires Python with the timesfm package installed. Set up the Python environment:

# Install Python dependencies
bundle exec rake vendor:python

# Or manually
pip install timesfm torch numpy pandas

You can specify a custom Python path via the TIMESFM_PYTHON environment variable:

export TIMESFM_PYTHON=/path/to/python3

Verify the installation:

bundle exec rake check

Usage

Simple Forecasting

require "timesfm"

# Time series as a Hash (Date => value)
series = {
  Date.parse("2024-01-01") => 100,
  Date.parse("2024-01-02") => 150,
  Date.parse("2024-01-03") => 136,
  Date.parse("2024-01-04") => 142,
  Date.parse("2024-01-05") => 158,
}

# Forecast 7 days ahead
result = TimesFM.forecast(series, count: 7)
puts result.forecasts
# => [145.2, 148.5, 151.3, ...]

Advanced API

# Create a forecaster with custom options
forecaster = TimesFM.new(
  model: "google/timesfm-2.5-200m-pytorch",
  context_length: 1024,
  quantiles: true,  # Include quantile forecasts
  gpu: true        # Use GPU acceleration
)

# Forecast with the configured model
result = forecaster.forecast(series, 12)

# Access results
puts result.forecasts           # Point forecasts
puts result.quantile_forecasts  # Quantile forecasts (if enabled)

Multiple Time Series

# Forecast multiple series at once
series_data = [
  [100, 150, 136, 142, 158],
  [50, 60, 55, 70, 65]
]

result = TimesFM.forecast(series_data, count: 7)
puts result.forecast_for(0)  # First series forecast
puts result.forecast_for(1)  # Second series forecast

With Groupdate

Works great with groupdate:

series = Order.group_by_day(:created_at).sum(:total)
result = TimesFM.forecast(series, count: 7)

Configuration Options

Option	Description	Default
model	Model name/path	"google/timesfm-2.5-200m-pytorch"
context_length	Maximum context length	1024
normalize	Normalize inputs	true
quantiles	Include quantile forecasts	false
flip_invariance	Force flip invariance	true
infer_positive	Infer positive values	true
gpu	Use GPU acceleration	false
python_path	Path to Python executable	Auto-detected

Architecture

Ruby gem
├── lib/timesfm/
│   ├── forecaster.rb      # Ruby API (forecast config)
│   └── python_backend.rb  # Spawns Python CLI
├── exe/timesfm-python/
│   ├── timesfm_cli.py     # Python CLI entry point
│   └── requirements.txt   # Python dependencies
└── vendor/                # Optional pre-compiled wheels

The gem spawns a Python subprocess that loads TimesFM and performs inference. Results are passed back via JSON.

Models

Available TimesFM models:

• google/timesfm-2.5-200m-pytorch (recommended, 200M params, 16k context)
• google/timesfm-2.0-500m-pytorch (500M params, 2k context)
• google/timesfm-1.0-200m (original 200M model)

Requirements

• Ruby >= 2.7.0
• Python >= 3.9
• timesfm Python package
• PyTorch or JAX

Development

git clone https://github.com/yourusername/timesfm-rb.git
cd timesfm-rb
bundle install
bundle exec rake vendor:python
bundle exec rake test

License

MIT License - see LICENSE.txt

Credits

• Google Research TimesFM
• prophet-ruby for the architecture inspiration