Tao Finetune Kumo Forecast

NVIDIAOfficialCreated by NVIDIA Corporation

Skill
Tool integration
Data and AI
Apache-2.0
Medium risk

From the author

Kumo-Forecast — transformer-based multivariate time series forecasting with DARR (context-enhanced kNN retrieval), interpretability, and fine-tuning. Use when the user asks to "forecast with Kumo-Forecast", "run forecasting inference", "use perform_forecasting", "DARR mode", "context-enhanced forecasting", "lag horizon attribution", "interpretability", "fine-tune forecasting", "fine-tune forecasting with automl", "hyper-parameter optimization with forecasting", or mentions "kumo-forecast", "moment_head_512_6hr", or "run8_best_model_cr".

— the description by NVIDIA Corporation

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

Kumo-Forecast provides a robust framework for multivariate time series forecasting using transformer-based models. It supports standard inference, context-enhanced kNN retrieval (DARR mode) for improved accuracy, and a model-agnostic interpretability framework that generates detailed diagnostic reports. The skill includes fine-tuning capabilities to adapt pretrained models to specific domains, supporting both standard and cross-channel architectures. It is designed for integration with AutoML workflows for hyperparameter optimization.

What it does

Performs multivariate time series forecasting using transformer-based models.
Enables DARR (context-enhanced kNN retrieval) to blend direct predictions with historical context.
Provides model-agnostic interpretability, including lag-horizon attribution and semantic flow analysis.
Supports fine-tuning of forecasting heads on custom datasets with optional cross-channel layer adaptation.
Integrates with AutoML runners for hyperparameter optimization of training and inference parameters.
Generates diagnostic reports and visualizations for model performance and stability.

When to use it

When you need to perform multivariate time series forecasting on structured data.
When you want to improve forecast accuracy by leveraging historical context via DARR.
When you require interpretability features to understand model predictions and lag-horizon dependencies.
When you need to adapt a pretrained forecasting model to a specific domain through fine-tuning.
When you are setting up hyperparameter optimization for forecasting models.

Advantages

Leverages powerful transformer backbones with pretrained weights.
Flexible inference modes including standard and context-enhanced retrieval.
Comprehensive interpretability tools for diagnostic analysis.
Supports fine-tuning with configurable encoder/embedder freezing.
AutoML-ready for efficient hyperparameter search.

Usage examples

“Forecast with Kumo-Forecast using my sensor data.”: The agent will execute the perform_forecasting function using your CSV data and the default Kumo-Forecast checkpoint to generate a forecast DataFrame.
“Run DARR mode forecasting with my historical context.”: The agent will use the provided context_df to build a kNN memory and blend it with the direct model prediction based on your specified alpha and k parameters.
“Fine-tune Kumo-Forecast on my custom dataset.”: The agent will initiate a training run using your CSV, adapting the forecasting head to your data while optionally using cross-channel attention.
“Explain the interpretability features of Kumo-Forecast.”: The agent will describe how to enable interpretability mode to generate lag-horizon attribution, semantic flow, and trajectory stability reports.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/nvidia/tao-finetune-kumo-forecast/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip tao-finetune-kumo-forecast.zip -d .agents/skills

Documentation by NVIDIA Corporation

Kumo-Forecast

Transformer-based multivariate time series forecasting using self-supervised pretraining on diverse temporal data. Three inference modes: standard (direct forecast), DARR (context-enhanced kNN retrieval blending), and interpretability (latent trajectory extraction, semantic flow, lag×horizon attribution, trajectory stability, and diagnostic ratios — full explanation bundle with PDF report). Fine-tuning adapts the forecasting head — and optionally the cross-channel layer — to your domain.

Source code: https://github.com/NVIDIA/Kumo-TS Pretrained weights: https://huggingface.co/nvidia/Kumo-Forecast

External dependencies

Dependency	Purpose	Install
Python 3.10+	Runtime	https://www.python.org/downloads/
uv	Package + environment manager	`pip install uv`
CUDA toolkit (optional)	GPU acceleration	https://developer.nvidia.com/cuda-downloads
matplotlib (optional)	Interpretability PDF report, heatmap PNG, flow + stability charts	`uv add matplotlib`

Credentials

nvidia/Kumo-Forecast is a public repo — no token required for downloading weights. If you hit a 401/403 (gated access or license not accepted) or a 504 on first download, see the Known pitfalls section.

Quick start

git clone --branch main --single-branch https://github.com/NVIDIA/Kumo-TS Kumo-TS
cd Kumo-TS/Kumo-Forecast
uv sync --group dev
uv pip install -e .          # editable install — required for clean sdk.* imports

# Standard inference (auto-downloads weights from HF on first run, no auth needed)
uv run python sdk/quick_example.py

Inference

Import and call perform_forecasting from sdk/forecasting.py. It auto-downloads weights, standardizes input, runs autoregressive rollout for long horizons, and returns a DataFrame with {target_column}_forecast rows for the requested horizon.

import sys, pandas as pd
sys.path.append("/path/to/Kumo-TS/Kumo-Forecast")  # clone Kumo-TS with --branch main
from sdk.forecasting import ForecastingConfig, perform_forecasting

df = pd.read_csv("your_data.csv")   # must have timestamp + numeric target column

config = ForecastingConfig(
    timestamp_column="timestamp",    # parseable datetime column
    target_column="target",          # primary target to forecast
    seq_len=512,                     # input context length (rows consumed)
    forecast_horizon=72,             # steps ahead to predict (max 512)
    model_horizon=72,                # native model horizon; change when using custom weights
    standardizer_pkl="standardizer.pkl",   # auto-downloaded from HF if missing
    ckpt="run8_best_model_cr.pt",          # auto-downloaded; see Checkpoints table
)
results = perform_forecasting(df=df, config=config)
# Returns DataFrame: timestamp | {target_column}_forecast  (forecast_horizon rows)
print(results.head())

For regular inference, put forecasting arguments in YAML and pass the file as config. Start from the fully commented template in sdk/forecasting_inference_config.yaml.

inference:
  # Number of historical rows consumed for the input context window.
  seq_len: 512
  # Number of future rows to predict.
  forecast_horizon: 72
  # Native horizon used when training the checkpoint.
  model_horizon: 72
  # Enable cross-channel attention for multivariate forecasting.
  use_cross_channel: true

results = perform_forecasting(df=df, config="sdk/forecasting_inference_config.yaml")

The YAML can be flat or use a top-level inference: section inside a larger TAO/AutoML spec. Unknown keys raise ValueError.

Checkpoints

File	Mode	Downloaded when
`run8_best_model_cr.pt`	Default (cross-channel on)	`use_cross_channel=True` (default)
`moment_head_512_6hr.pt`	Standard (no cross-channel)	`use_cross_channel=False`
`standardizer.pkl`	Both	Always

Set use_cross_channel=False in ForecastingConfig or YAML to use the standard checkpoint:

results = perform_forecasting(df=df, config=ForecastingConfig(use_cross_channel=False))

DARR mode (context-enhanced forecasting)

Supply context_df to enable DARR: the SDK builds a kNN memory from historical windows and blends direct predictions with retrieved neighbors (alpha * direct + (1 - alpha) * kNN).

context_df = pd.read_csv("historical_data.csv")   # needs ≥ seq_len + model_horizon rows

config = ForecastingConfig(
    forecast_horizon=72,
    alpha=0.2,                  # 0.2 = 20% direct, 80% kNN (default: 0.01)
    k=64,                       # number of nearest neighbors
    temperature=0.05,           # kNN softmax temperature
)
results = perform_forecasting(df=df, config=config, context_df=context_df)

Context and input datasets do not need identical columns — the SDK aligns to common features and warns when columns differ. Both must share timestamp_column and target_column.

Interpretability

Set interpretability=True to activate the Model-Agnostic Interpretability Framework. It produces localized, horizon-specific, time-aware explanations — including lag×horizon attribution, semantic flow, trajectory stability, diagnostic ratios, and (for multivariate inputs) channel-axis attribution and coupling analysis.

For the full parameter reference, output bundle, and component descriptions, see Kumo-Forecast/README.md.

Fine-tuning

Fine-tune the forecasting head (encoder/embedder frozen by default) on your own time series. --ckpt-init auto warm-starts from the published Kumo-Forecast checkpoint; --ckpt-init none trains a fresh head from the base backbone.

cd /path/to/Kumo-TS/Kumo-Forecast
# Without cross-channel (uses moment_head_512_6hr.pt)
uv run python examples/finetune_example.py \
  --csv /path/to/timeseries.csv \
  --timestamp-col timestamp \
  --target-cols target \
  --seq-len 512 --forecast-horizon 72 \
  --epochs 5 --batch-size 8 --lr 1e-4 \
  --output-dir artifacts/finetune_my_data

# With cross-channel layer (uses run8_best_model_cr.pt)
uv run python examples/finetune_example.py \
  --csv /path/to/timeseries.csv \
  --timestamp-col timestamp \
  --target-cols sensor_1,sensor_2,sensor_3 \
  --use-cross-channel --cross-channel-heads 8 \
  --epochs 5 \
  --output-dir artifacts/finetune_cross_channel

Fine-tuning arguments

Argument	Default	Description
`--run-config`	—	YAML config from AutoMLRunner (`{config_path}`). CLI flags override file values.
`--csv`	required*	Single CSV split temporally into train/val
`--train-csv`	required*	Training CSV (mutually exclusive with `--csv`)
`--val-csv`	—	Validation CSV when `--train-csv` is used
`--timestamp-col`	`timestamp`	Datetime column to exclude from features
`--target-cols`	all numeric	Comma-separated columns to forecast
`--model-name`	`AutonLab/MOMENT-1-large`	Backbone model identifier
`--ckpt-init`	`auto`	`auto` = published Kumo-Forecast weights; `none` = fresh head; or path to `.pt`
`--standardizer-init`	`standardizer.pkl`	Standardizer pickle used when `--ckpt-init auto`
`--repo-id`	`nvidia/Kumo-Forecast`	HuggingFace repo for auto-download
`--seq-len`	`512`	Input context length
`--forecast-horizon`	`72`	Steps ahead to predict
`--stride`	`forecast_horizon`	Sliding window stride (`None` → horizon)
`--val-ratio`	`0.1`	Validation fraction when `--csv` is used
`--test-ratio`	`0.0`	Test holdout fraction when `--csv` is used
`--no-standardize`	false	Disable per-dataset standardization
`--epochs`	`5`	Training epochs
`--batch-size`	`8`	Per-GPU batch size
`--lr`	`1e-4`	AdamW learning rate (OneCycleLR scheduler)
`--weight-decay`	`0.0`	AdamW weight decay
`--head-dropout`	`0.1`	Forecasting head dropout
`--max-norm`	`5.0`	Gradient norm clip
`--num-workers`	`0`	DataLoader workers
`--seed`	`13`	Random seed
`--output-dir`	`artifacts/finetune`	Output directory
`--local-files-only`	false	Do not download backbone weights from HuggingFace
`--unfreeze-encoder`	false	Train the transformer encoder too
`--unfreeze-embedder`	false	Train the patch embedder too
`--use-cross-channel`	false	Add cross-channel attention layer
`--cross-channel-heads`	`8`	Attention heads in cross-channel layer
`--cross-channel-dropout`	`0.1`	Dropout in the cross-channel layer
`--num-gpus`	all available	Number of GPUs for DDP fine-tuning; set `1` to force single-GPU

*One of --csv or --train-csv is required.

Inference with fine-tuned checkpoint

config = ForecastingConfig(
    timestamp_column="timestamp",
    target_column="target",
    seq_len=512,
    forecast_horizon=72,
    model_horizon=72,
    standardizer_pkl="artifacts/finetune_my_data/standardizer.pkl",
    ckpt="artifacts/finetune_my_data/best_model.pt",
    use_cross_channel=False,   # set True if trained with --use-cross-channel
)
results = perform_forecasting(df=df, config=config)

Data requirements

Property	Requirement
Rows	≥ `seq_len` (default 512) for inference; validation split must also have ≥ `seq_len + forecast_horizon` rows
Columns	`timestamp` + one or more numeric columns; NULLs filled with zeros automatically
Timestamp	Parseable by pandas; no NULLs; uniform frequency inferred from mode of diffs
Target	Must be numeric; NULLs filled with zeros
`forecast_horizon`	Max 512 steps; beyond model's native 72 triggers autoregressive rollout
DARR context	≥ `seq_len + model_horizon` rows; must share timestamp + target columns with input

Output structure

Inference (standard / DARR):

DataFrame: timestamp | {target_column}_forecast   (forecast_horizon rows)

Fine-tuning (--output-dir artifacts/finetune_my_data):

artifacts/finetune_my_data/
├── best_model.pt            # checkpoint with lowest validation MSE
├── standardizer.pkl         # normalization statistics for this dataset
├── finetune_metadata.json   # model config, channels, best epoch, all args
├── metrics.json             # scalar summary: {"val_mse": float, "val_mae": float} — consumed by AutoML runner
└── epoch_metrics.json       # per-epoch list: [{epoch, train_mse, val_mse, val_mae}, ...]

Hardware

Tier	Setup	Notes
Minimum	1× CPU	Functional; slow for long horizons
Recommended	1× NVIDIA GPU (≥8 GB VRAM)	Strongly recommended for fine-tuning
Apple Silicon	MPS	Auto-detected; on par with CPU for this workload
Multi-GPU fine-tuning	2+× NVIDIA GPUs	Auto DDP via `--num-gpus` (defaults to all visible GPUs)

AutoML (HPO: hyperparameter optimization)

This skill is AutoML-enabled for both fine-tuning and DARR inference. When an HPO request arrives, route it through tao-skill-bank:tao-run-automl with this model's skill_dir.

Read references/automl.md when the user asks for AutoML/HPO setup, tunable parameters, runner examples, inference trial scripts, DARR HPO, or AutoML result handoff details.

Known pitfalls

Symptom	Cause	Fix
`ModuleNotFoundError: backbone`	Editable install missing	Run `uv pip install -e .` from `Kumo-Forecast/`
`HfHubHTTPError: 401` / `403`	Model license not accepted or gated fork	Accept license on HF repo page; or `huggingface-cli login`
`504` / timeout on first weight download	HF CDN throttles unauthenticated requests — public repos are still subject to this on first download	Set `export HUGGINGFACE_HUB_TOKEN="$HF_TOKEN"` before running; authenticated requests use a more reliable CDN path
`ValueError: DataFrame has X rows but seq_len requires Y`	Input too short	Provide ≥ `seq_len` (512) rows or reduce `--seq-len`
`ValueError: forecast_horizon must be <= 512`	Horizon too large	Split into multiple `perform_forecasting` calls
`ValueError: No common numeric columns` (DARR)	Context has no overlapping features	Ensure context shares ≥ 1 numeric column with input
`ValueError: Context DataFrame has X rows but requires Y`	Context too small	Context needs ≥ `seq_len + model_horizon` rows
`Interpretability PDF skipped: matplotlib not installed`	Missing optional dep	`uv add matplotlib` or use `interpretability_output="json"`
`ValueError: No training windows` (finetune)	Data too short for windows	Reduce `--seq-len` / `--forecast-horizon`, or increase dataset size
Stale environment errors mentioning `backbone` package	Old lock file	`uv cache clean && uv sync --group dev`

Files

ATTRIBUTION.mdAdded by AutoGineer948 B
BENCHMARK.md7.2 KiB
LICENSELicence file added by AutoGineer11.2 KiB
SKILL.md13.5 KiB
config/skillspector-baseline.yaml834 B
evals/evals.json1.2 KiB
references/automl.md14.7 KiB
references/skill_info.yaml1.5 KiB
references/spec_template_inference_hpo.yaml1.4 KiB
references/spec_template_train.yaml642 B
schemas/inference_hpo.schema.json6.0 KiB
schemas/train.schema.json10.2 KiB
skill-card.md4.7 KiB
skill.oms.sig6.2 KiB

references/automl.md

Forecasting AutoML Details

Read this reference when the user asks for Kumo-Forecast AutoML/HPO setup, tunable parameters, runner examples, inference trial scripts, DARR HPO, or AutoML result handoff details.

AutoML overview
Fine-tuning AutoML
Inference HPO
Basic mode
DARR mode

AutoML (HPO: hyperparameter optimization)

This skill is AutoML-enabled for both fine-tuning and DARR inference. When an HPO request arrives, route it through tao-skill-bank:tao-run-automl with this model's skill_dir.

Note: VirtualEnvSDK and python_script execution require the AutoML control-plane dependencies managed by tao-run-automl. Construct the SDK as VirtualEnvSDK(venv_path=..., work_dir=...) -- see that skill's Runner Construction section and skills/applications/tao-run-automl/references/automl-runner-configuration.md section "VirtualEnvSDK (containerless venv runs)". Always pass work_dir=; the default is a hidden state directory under $HOME, and each fine-tuning trial writes roughly 1.4 GB of checkpoint there. This model reference lists Kumo-Forecast search spaces, overrides, and trial payloads.

Fine-tuning AutoML

AutoML minimizes val_mse (and also reports val_mae) by tuning 5 training hyperparameters. Epochs, architecture flags, and data paths are fixed as spec overrides — not searched.

Parameter	Spec key	Default	Search range
Learning rate	`train.lr`	`1e-4`	`[1e-6, 1e-3]` log
Batch size	`train.batch_size`	`8`	`[4, 64]` int
Head dropout	`train.head_dropout`	`0.1`	`[0.0, 0.5]`
Weight decay	`train.weight_decay`	`0.0`	`[0.0, 0.01]`
Gradient clip	`train.max_norm`	`5.0`	`[1.0, 10.0]`

Fixed (not searched): train.epochs, model.seq_len, model.forecast_horizon, model.use_cross_channel, model.ckpt_init, dataset.*, train.seed, train.output_dir.

use_cross_channel is a user choice before HPO — it switches both the pretrained checkpoint (run8_best_model_cr.pt vs moment_head_512_6hr.pt) and the model architecture. Bayesian search across these two would compare incomparable weight initializations.

Fair comparison rule: perform_forecasting defaults to use_cross_channel=True (loads run8_best_model_cr.pt). If you compare pretrained inference against a finetuned checkpoint, both must use the same base. Either:
Finetune with --use-cross-channel (warm-starts from run8_best_model_cr.pt) and run inference with use_cross_channel=True (default), or
Run inference with use_cross_channel=False and finetune without --use-cross-channel (warm-starts from moment_head_512_6hr.pt, the finetune default).
Mixing architectures — cross-channel pretrained vs standard finetuned — conflates model quality with architectural differences and makes the comparison uninterpretable.

from pathlib import Path

forecasting_dir = Path("/path/to/Kumo-TS/Kumo-Forecast")
skill_dir = Path("/path/to/tao-skill-bank/skills/models/tao-finetune-kumo-forecast")

# Build sdk + runner per tao-run-automl section "Runner Construction":
# sdk = VirtualEnvSDK(venv_path=<venv>, work_dir=<scratch>)  # work_dir is not optional in practice

result = runner.run(
    automl_settings={
        "algorithm":                  "bayesian",
        "metric":                     "val_mse",
        "direction":                  "minimize",
        "automl_max_recommendations": 5,
    },
    # spec_overrides MUST use dotted keys.
    spec_overrides={
        "dataset.csv":            "/path/to/timeseries.csv",
        "dataset.timestamp_col":  "timestamp",
        "dataset.val_ratio":      0.1,
        "model.forecast_horizon": 72,
        "model.seq_len":          512,
        "model.use_cross_channel": False,
        "train.epochs":           10,
        "train.num_epochs":       10,
        "train.output_dir":       "automl_workspace/finetune/trials",
    },
    workspace_path="automl_workspace/finetune",
    execution={
        "type":          "python_script",
        "script":        str(forecasting_dir / "examples/finetune_example.py"),
        "args":          ["--run-config", "{config_path}"],
        "cwd":           str(forecasting_dir),
        "config_format": "yaml",
    },
)

best = result["best"]
print(f"Best val_mse: {best['metric_value']}")
print(f"Best specs:   {best['specs']}")
# best['specs'] uses the same dotted keys as spec_overrides.
# The best checkpoint lives in the VirtualEnvSDK managed job directory, not in train.output_dir.
# If locating it via glob, scope to result['history'] rec_ids and sort by metrics.json val_mse
# to avoid accidentally picking up a checkpoint from a prior experiment with lower val_mse.

Inference HPO

AutoML can search inference parameters against a ground-truth eval window. Hold back the last forecast_horizon rows as ground truth; the trial script runs inference and writes MSE and MAE to metrics.json. Two modes are supported — use whichever matches your setup.

The trial scripts below are generated by the agent — they are not shipped with Kumo-TS. Save the template anywhere and point execution.script at it.

Basic mode (tune model parameters)

Use when you have no context history for DARR. Tunes parameters that affect the model's direct forecast quality.

Parameter	Spec key	Default	Search range
Context length	`hpo.seq_len`	`512`	`[128, 256, 512]` ordered_int
Cross-channel	`hpo.use_cross_channel`	`false`	`[true, false]` categorical
Attention heads	`hpo.cross_channel_heads`	`8`	`[4, 8, 16]` ordered_int
Head dropout	`hpo.cross_channel_dropout`	`0.1`	`[0.0, 0.1, 0.2]`

Trial script template (basic):

"""Single basic inference HPO trial — called by the AutoML runner with --run-config {config_path}."""
import argparse, json, sys
from dataclasses import replace
from pathlib import Path
import yaml, pandas as pd
import numpy as np

FORECASTING_DIR = Path("/path/to/Kumo-TS/Kumo-Forecast")  # adjust to actual clone path
sys.path.insert(0, str(FORECASTING_DIR))

from sdk.forecasting import load_forecasting_config, perform_forecasting

def main():
    p = argparse.ArgumentParser()
    p.add_argument("--run-config", required=True)
    args = p.parse_args()

    cfg = yaml.safe_load(Path(args.run_config).read_text())
    ds  = cfg["dataset"]
    inf = cfg["hpo"]
    out = Path(cfg.get("train", {}).get("output_dir", "artifacts/inference_hpo"))
    out.mkdir(parents=True, exist_ok=True)

    df = pd.read_csv(ds["csv"], parse_dates=[ds.get("timestamp_col", "timestamp")])
    df = df.set_index(ds.get("timestamp_col", "timestamp"))
    target_cols = [c.strip() for c in ds["target_cols"].split(",")] if ds.get("target_cols") else None

    horizon = inf["forecast_horizon"]
    if horizon <= 0 or horizon >= len(df):
        raise ValueError(f"hpo.forecast_horizon must be in [1, {len(df) - 1}], got {horizon}")
    df_input  = df.iloc[:-horizon]
    df_actual = df.iloc[-horizon:]

    forecast_config = replace(load_forecasting_config(args.run_config), return_all_channels=True)
    result = perform_forecasting(df=df_input, config=forecast_config)

    # Align predictions to actuals by column name, not position.
    if target_cols:
        wanted_pred_cols = [f"{c}_forecast" for c in target_cols]
        missing = [c for c in wanted_pred_cols if c not in result.columns]
        if missing:
            raise ValueError(f"target_cols columns not found in predictions: {missing}")
        preds       = result[wanted_pred_cols].values[:horizon]
        actual_vals = df_actual[target_cols].values[:horizon]
    else:
        pred_cols   = [c for c in result.columns if c.endswith("_forecast")]
        actual_cols = [c.replace("_forecast", "") for c in pred_cols]
        preds       = result[pred_cols].values[:horizon]
        actual_vals = df_actual[actual_cols].values[:horizon]

    val_mse = float(np.mean((preds - actual_vals) ** 2))
    val_mae = float(np.mean(np.abs(preds - actual_vals)))

    (out / "metrics.json").write_text(json.dumps({"val_mse": val_mse, "val_mae": val_mae}))
    print(f"seq_len={inf.get('seq_len', 512)}  use_cross_channel={inf.get('use_cross_channel', False)}"
          f"  cross_channel_heads={inf.get('cross_channel_heads', 8)}  MSE={val_mse:.6f}  MAE={val_mae:.6f}")

if __name__ == "__main__":
    main()

Running basic inference HPO:

result = runner.run(
    automl_settings={
        "algorithm":                  "bayesian",
        "metric":                     "val_mse",
        "direction":                  "minimize",
        "automl_max_recommendations": 12,
    },
    spec_overrides={
        "dataset.csv":                "/path/to/eval_data.csv",
        "dataset.timestamp_col":      "timestamp",
        "dataset.target_cols":        "target",
        "hpo.forecast_horizon": 72,
        "train.output_dir":           "automl_workspace/basic_hpo/trials",
    },
    hyperparameters={
        "hpo.seq_len":               {"type": "ordered_int", "values": [128, 256, 512]},
        "hpo.use_cross_channel":     {"type": "categorical", "values": [True, False]},
        "hpo.cross_channel_heads":   {"type": "ordered_int", "values": [4, 8, 16]},
        "hpo.cross_channel_dropout": {"type": "uniform",     "min": 0.0, "max": 0.2},
    },
    workspace_path="automl_workspace/basic_hpo",
    execution={
        "type":          "python_script",
        "script":        "/path/to/basic_inference_hpo_trial.py",
        "args":          ["--run-config", "{config_path}"],
        "cwd":           str(forecasting_dir),
        "config_format": "yaml",
    },
)

best = result["best"]
print(f"Best val_mse: {best['metric_value']}")
print(f"Best params: seq_len={best['specs']['hpo.seq_len']}  "
      f"use_cross_channel={best['specs']['hpo.use_cross_channel']}  "
      f"cross_channel_heads={best['specs']['hpo.cross_channel_heads']}")

DARR mode (tune blending parameters)

Use when you have a context history CSV. Tunes the three kNN blending parameters that control how much weight the retrieval signal gets versus the model's direct forecast.

Parameter	Spec key	Default	Search range
Blend weight	`hpo.alpha`	`0.01`	`[0.001, 0.5]`
kNN count	`hpo.k`	`64`	`[8, 16, 32, 64, 128]` ordered_int
Temperature	`hpo.temperature`	`0.05`	`[0.01, 0.5]`

Trial script template (DARR):

"""Single DARR inference HPO trial — called by the AutoML runner with --run-config {config_path}."""
import argparse, json, sys
from dataclasses import replace
from pathlib import Path
import yaml, pandas as pd
import numpy as np

FORECASTING_DIR = Path("/path/to/Kumo-TS/Kumo-Forecast")  # adjust to actual clone path
sys.path.insert(0, str(FORECASTING_DIR))

from sdk.forecasting import load_forecasting_config, perform_forecasting

def main():
    p = argparse.ArgumentParser()
    p.add_argument("--run-config", required=True)
    args = p.parse_args()

    cfg = yaml.safe_load(Path(args.run_config).read_text())
    ds  = cfg["dataset"]
    inf = cfg["hpo"]
    out = Path(cfg.get("train", {}).get("output_dir", "artifacts/inference_hpo"))
    out.mkdir(parents=True, exist_ok=True)

    df = pd.read_csv(ds["csv"], parse_dates=[ds.get("timestamp_col", "timestamp")])
    df = df.set_index(ds.get("timestamp_col", "timestamp"))
    target_cols = [c.strip() for c in ds["target_cols"].split(",")] if ds.get("target_cols") else None

    horizon = inf["forecast_horizon"]
    if horizon <= 0 or horizon >= len(df):
        raise ValueError(f"hpo.forecast_horizon must be in [1, {len(df) - 1}], got {horizon}")
    df_input  = df.iloc[:-horizon]
    df_actual = df.iloc[-horizon:]

    context_df = pd.read_csv(ds["context_csv"], parse_dates=[ds.get("timestamp_col", "timestamp")])
    context_df = context_df.set_index(ds.get("timestamp_col", "timestamp"))

    forecast_config = replace(load_forecasting_config(args.run_config), return_all_channels=True)
    result = perform_forecasting(df=df_input, config=forecast_config, context_df=context_df)

    # Align predictions to actuals by column name, not position.
    if target_cols:
        wanted_pred_cols = [f"{c}_forecast" for c in target_cols]
        missing = [c for c in wanted_pred_cols if c not in result.columns]
        if missing:
            raise ValueError(f"target_cols columns not found in predictions: {missing}")
        preds       = result[wanted_pred_cols].values[:horizon]
        actual_vals = df_actual[target_cols].values[:horizon]
    else:
        pred_cols   = [c for c in result.columns if c.endswith("_forecast")]
        actual_cols = [c.replace("_forecast", "") for c in pred_cols]
        preds       = result[pred_cols].values[:horizon]
        actual_vals = df_actual[actual_cols].values[:horizon]

    val_mse = float(np.mean((preds - actual_vals) ** 2))
    val_mae = float(np.mean(np.abs(preds - actual_vals)))

    (out / "metrics.json").write_text(json.dumps({"val_mse": val_mse, "val_mae": val_mae}))
    print(f"alpha={inf['alpha']}  k={inf['k']}  temp={inf['temperature']}  MSE={val_mse:.6f}  MAE={val_mae:.6f}")

if __name__ == "__main__":
    main()

Running DARR inference HPO:

result = runner.run(
    automl_settings={
        "algorithm":                  "bayesian",
        "metric":                     "val_mse",
        "direction":                  "minimize",
        "automl_max_recommendations": 8,
    },
    spec_overrides={
        "dataset.csv":                "/path/to/eval_data.csv",
        "dataset.context_csv":        "/path/to/context_history.csv",
        "dataset.timestamp_col":      "timestamp",
        "dataset.target_cols":        "target",
        "hpo.forecast_horizon": 72,
        "hpo.seq_len":          512,
        "hpo.use_cross_channel": False,
        "train.output_dir":           "automl_workspace/darr_hpo/trials",
    },
    hyperparameters={
        "hpo.alpha":       {"type": "uniform",     "min": 0.001, "max": 0.5},
        "hpo.k":           {"type": "ordered_int", "values": [8, 16, 32, 64, 128]},
        "hpo.temperature": {"type": "uniform",     "min": 0.01,  "max": 0.5},
    },
    workspace_path="automl_workspace/darr_hpo",
    execution={
        "type":          "python_script",
        "script":        "/path/to/darr_inference_hpo_trial.py",
        "args":          ["--run-config", "{config_path}"],
        "cwd":           str(forecasting_dir),
        "config_format": "yaml",
    },
)

best = result["best"]
print(f"Best val_mse: {best['metric_value']}")
print(f"Best DARR params: alpha={best['specs']['hpo.alpha']}  "
      f"k={best['specs']['hpo.k']}  temp={best['specs']['hpo.temperature']}")

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Declares allowed tools, Needs a command-line tool, Needs Python

The author says: Requires Python 3.10+ and uv. CUDA GPU recommended; Apple Silicon (MPS) and CPU supported.

Security

What our scanner noticed· Medium risk

Large base64-encoded blobs
Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

NVIDIA Corporation

Publisher

NVIDIA (Official)

Source

NVIDIA/skills · skills/tao-finetune-kumo-forecast · commit fce3cca

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE-APACHE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by NVIDIA Corporation or NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download tao-finetune-kumo-forecast.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by NVIDIA Corporation

Kumo-Forecast

External dependencies

Credentials

Quick start

Inference

Checkpoints

DARR mode (context-enhanced forecasting)

Interpretability

Fine-tuning

Fine-tuning arguments

Inference with fine-tuned checkpoint

Data requirements

Output structure

Hardware

AutoML (HPO: hyperparameter optimization)

Known pitfalls

Files

references/automl.md

Forecasting AutoML Details

Contents

AutoML (HPO: hyperparameter optimization)

Fine-tuning AutoML

Inference HPO

Basic mode (tune model parameters)

DARR mode (tune blending parameters)

Requirements and compatibility

Security

Attribution and licence

Related skills

Pytorch Lightning

Aeon

Umap Learn

Scikit Learn

Shap

Pufferlib

Download ZIP