KumoForecast#

class sdm.models.KumoForecast(cross_channel: bool = True, pretrained: bool = True, device: device | str | None = None)#

Bases: ICLModel

The time series forecasting foundation model from the “Memory-Augmented Forecasting: Scalability and Generalization Across Temporal Domains” paper.

../../_images/kumo_forecast_light.png

KumoForecast is a time-series foundation model for multivariate forecasting, with optional historical covariates. Architecturally, it combines patch-based time-series embeddings with a MOMENT transformer encoder and a pretrained forecasting head. Optional cross-channel mixing lets forecasts use dependencies between variates after temporal encoding. The forecasting head predicts the native up to 72-step horizon directly from a 512-step history. Forecast horizons beyond 72 steps are extended autoregressively.

For longer observation histories, Domain-Aware Representation and Retrieval (DARR) can augment the direct forecast with patterns retrieved from historical data. Set alpha < 1 to retrieve similar historical windows using nearest neighbors and blend their observed continuations with the direct forecast.

Within the ICLModel protocol, KumoForecast treats rows as ordered time steps. In a default forward pass, x_context contains past-only historical covariates, y_context contains one or more past target series, and x_query has no columns. The number of query rows determines the forecast horizon.

Parameters:

  • cross_channel (bool) – Whether to mix variates after encoding.

  • pretrained (bool) – Whether to load the pretrained checkpoint.

  • device (torch.device | str | None) – The device.

Additional Forward Parameters:

  • alpha (float) – Blend weight between direct and retrieved forecasts. 1.0 uses only the direct forecast, 0.0 uses only retrieval. (default: 1.0)

  • k (int) – Maximum number of historical neighbors to retrieve. (default: 64)

  • temperature (float | None) – Softmax temperature for weighting retrieved neighbors. (default: 0.05)

Capabilities#

Supported Input Semantic Types

numerical

Supported Target Semantic Types

numerical

Supported Prediction Tasks

regression

Multi-Target Support

✅

Context-only Column Support

✅

Related Table Support

❌

Default Recipe#

Recipe(
  features=Standardize(),
  target=Standardize(),
  output=AverageEstimators(),
)