> This page is for Structured Data Models. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/sdgm/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/sdgm/_mcp/server. # Kumo Forecast > Multivariate time series forecasting with optional retrieval from history, in the Kumo-TS library. > **Runs in Kumo-TS** > > Kumo Forecast is part of the [Kumo-TS](https://github.com/NVIDIA/Kumo-TS) library, not SDM. > [Install the Kumo-Forecast package](/sdgm/structured-data-models/installation#install-kumo-ts-for-time-series) 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 | Property | Value | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | Entry point | `perform_forecasting(df, config=ForecastingConfig(...), context_df=None)` | | Package | Kumo-TS `Kumo-Forecast` 1.0.0, Python 3.10 or later | | Input | A pandas DataFrame with a timestamp column, a target column, and optional numeric covariates | | Output | A DataFrame with future timestamps and a `_forecast` column | | History and horizon | Reads the last `seq_len` rows (default 512). Predicts 72 steps directly and extends longer horizons autoregressively. | | Devices | CUDA, Apple MPS, or CPU, chosen automatically | | Weights | [nvidia/Kumo-Forecast](https://huggingface.co/nvidia/Kumo-Forecast), Apache-2.0, about 1.4 GB | | Reference | [Memory-Augmented Forecasting: Scalability and Generalization Across Temporal Domains](https://ieeexplore.ieee.org/abstract/document/11402442) | ## 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.](/sdgm/_fern-files/_img/945e7bf679f07472344181436c861380745cf50a1fac2e52aad8c2cd0cca7ff4.webp) 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. ```python 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`** ```text title="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](https://github.com/NVIDIA/Kumo-TS/blob/main/Kumo-Forecast/README.md#interpretability). ## 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](https://huggingface.co/nvidia/Kumo-Forecast). ## Fine-Tuning Fine-tune on your own CSV with [examples/finetune_example.py](https://github.com/NVIDIA/Kumo-TS/blob/main/Kumo-Forecast/examples/finetune_example.py). ## Learn More * [Kumo-Forecast SDK reference](https://github.com/NVIDIA/Kumo-TS/blob/main/Kumo-Forecast/sdk/README.md) * [Hugging Face model card](https://huggingface.co/nvidia/Kumo-Forecast) * [Memory-Augmented Forecasting paper](https://ieeexplore.ieee.org/abstract/document/11402442)