Skip to navigation
Models

Kumo Forecast

View as Markdown
Runs in Kumo-TS

Kumo Forecast is part of the Kumo-TS library, not SDM. Install the Kumo-Forecast package before running the example.

Kumo Forecast predicts future values of a time series from its history. It combines a pretrained transformer encoder with an optional retrieval step that blends in the continuations of similar past windows.

At a Glance

PropertyValue
Entry pointperform_forecasting(df, config=ForecastingConfig(...), context_df=None)
PackageKumo-TS Kumo-Forecast 1.0.0, Python 3.10 or later
InputA pandas DataFrame with a timestamp column, a target column, and optional numeric covariates
OutputA DataFrame with future timestamps and a <target>_forecast column
History and horizonReads the last seq_len rows (default 512). Predicts 72 steps directly and extends longer horizons autoregressively.
DevicesCUDA, Apple MPS, or CPU, chosen automatically
Weightsnvidia/Kumo-Forecast, Apache-2.0, about 1.4 GB
ReferenceMemory-Augmented Forecasting: Scalability and Generalization Across Temporal Domains

When to Use It

  • Your rows are ordered time steps and you want the next N values.
  • You have one or more related signals (covariates) observed alongside the target.
  • You have a long archive of past data that may contain similar patterns: use DARR retrieval.

Shape Your Data

  • timestamp_column: evenly spaced timestamps. The forecast continues at the same frequency.
  • target_column: the series to forecast.
  • Other numeric columns are used as covariates automatically.
  • Provide at least seq_len rows.

How It Works

Kumo Forecast architecture: an input layer with multivariate time series data and input masking, an embedding layer with patch and positional embeddings, a transformer encoder, and an output head for forecasting.

Kumo Forecast combines patch-based embeddings with a pretrained transformer encoder and a forecasting head. Cross-channel attention (on by default, use_cross_channel=True) lets the forecast use dependencies between the target and its covariates.

Retrieval from History (DARR)

Domain-Aware Representation and Retrieval finds windows in an archive that resemble the latest window and blends their observed continuations with the direct forecast. Pass the archive as context_df. alpha weights the direct forecast (alpha * direct + (1 - alpha) * retrieved; default 0.01), k sets the number of neighbors (default 64), and temperature sets how sharply they are weighted (default 0.05).

Match the retrieval stride to your seasonality

Archive windows are indexed every context_stride rows, which defaults to the 72-step model horizon. For hourly data with a daily cycle, every window then ends at the same hour of day, and retrieved continuations are out of phase with the forecast. Set context_stride=1, or a value that is not a multiple of your cycle length. In a synthetic hourly test, this cut the retrieval-only error from 23.87 to 9.52 MAE.

Example

Run this script with uv run from the Kumo-TS/Kumo-Forecast directory. The first run downloads the weights into the working directory.

import numpy as np
import pandas as pd
from sdk.forecasting import ForecastingConfig, perform_forecasting
hours = 600  # at least seq_len (512) rows of history
t = np.arange(hours)
noise = np.random.default_rng(0).normal(scale=2.0, size=hours)
df = pd.DataFrame({
    "timestamp": pd.date_range("2025-01-01", periods=hours, freq="h"),
    "load": 100 + 20 * np.sin(2 * np.pi * t / 24) + noise,
})
config = ForecastingConfig(
    timestamp_column="timestamp",
    target_column="load",
    forecast_horizon=72,
)
if __name__ == "__main__":  # required: Kumo-TS starts worker processes
    forecast = perform_forecasting(df=df, config=config)
    print(forecast.shape)
    print(forecast.head(3))
Expected output
(72, 2)
            timestamp  load_forecast
0 2025-01-26 00:00:00      99.367966
1 2025-01-26 01:00:00     104.372635
2 2025-01-26 02:00:00     109.092796

The output has one row per forecast hour, continuing the input timestamps. Inference took about 2 seconds on an Apple laptop GPU after the weights were cached; the first run downloads about 1.4 GB.

Use a main guard in scripts

Kumo-Forecast loads data in worker processes. On macOS and Windows, those workers import your script again, so keep the model call under if __name__ == "__main__":. Without it, DARR fails with DataLoader worker ... exited unexpectedly.

Explain a Forecast

Set interpretability=True in ForecastingConfig to write lag and feature attributions per horizon step, as JSON, CSV, and a PDF report (the PDF needs matplotlib). See the interpretability reference.

Inputs and Limits

  • At least seq_len rows; fewer raises DataFrame has N rows but seq_len requires at least 512 rows.
  • Missing target values are filled with zeros.
  • For DARR, context_df needs the same timestamp and target columns, at least one shared covariate, and at least seq_len + max(72, forecast_horizon) rows. Set context_stride to match your seasonality (see above).
  • DARR does not always beat the direct forecast. Compare both on a held-out window of your own data.
  • Weight files are written to the paths in standardizer_pkl and ckpt, which default to the working directory.

For model size and training details, see the Hugging Face model card.

Fine-Tuning

Fine-tune on your own CSV with examples/finetune_example.py.

Learn More