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://mp-staging.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

BENCHMARK.md

Skill Benchmark: tao-finetune-kumo-forecast

✅ Overall verdict: PASS — Recommended for publication

Publication Recommendation

Recommended for publication based on the completed evaluation evidence in this report.

Evaluation Metadata

Skill: tao-finetune-kumo-forecast
Evaluation date: 2026-10-16
Evaluator version: 1.5.6
Agents: Claude Code (aws/anthropic/bedrock-claude-opus-4-8), Codex (openai/openai/gpt-5.5)
Tasks: 1 evaluation tasks (1 positive)
Dataset digest: sha256:0d71ed10c27977b5a628fe06b3c1102a02f08586ca0b039cfff6943258746a23 (skill-evaluator-dataset-snapshot/1)
Attempts per task: 1
Environment: k8s-sandbox
Tier 2 evidence: required for publication
Tier 3 evidence: required for publication

Each task attempt ran in its own isolated sandbox pod.

What This Report Answers

The three-tier evaluation checks whether the skill:

is safe to use;
produces correct answers;
is discovered and activated when needed;
helps the agent complete the user's goal and expected workflow; and
avoids wasted skill and tool usage.

Results at a Glance

Measure	Claude Code (Baseline → Skill Uplift)	Codex (Baseline → Skill Uplift)
Overall	94.4% — baseline ran, but no comparable score was available; uplift unavailable	62.3% — baseline ran, but no comparable score was available; uplift unavailable
Security	100.0% → 100.0% (±0.0 points)	100.0% → 100.0% (±0.0 points)
Correctness	0.0% → 100.0% (+100.0 points)	20.0% → 60.0% (+40.0 points)
Discoverability	100.0% — baseline ran, but no comparable score was available; uplift unavailable	0.0% — baseline ran, but no comparable score was available; uplift unavailable
Effectiveness	16.7% → 100.0% (+83.3 points)	26.7% → 53.3% (+26.6 points)
Efficiency	72.2% — baseline ran, but no comparable score was available; uplift unavailable	99.5% → 98.4% (-1.1 points)

How to read this table: baseline is the same task attempted without the target skill. Scores are rounded to one decimal; threshold-adjacent values use additional precision so their displayed band matches the verdict. Uplift is derived from those displayed scores and shown in percentage points.

Example: 47.0% → 92.0% (+45.0 points) means the skill-assisted run scored 92.0%, 45.0 percentage points above its 47.0% no-skill baseline.

A partial dimension was calculated from only the available configured signals; review the detailed report before relying on it.

Token Usage

Actual Tier 3 execution usage is reported for every observed agent/case pair and both conditions.

Agent	Dataset case	With skill	Without skill	Delta	Change	Coverage
claude-code	All cases	99,362	30,248	+69,114	+228.49%	skill 1/1; base 1/1
claude-code	tao-finetune-kumo-forecast-basic	99,362	30,248	+69,114	+228.49%	skill 1/1; base 1/1
codex	All cases	14,242	13,984	+258	+1.84%	skill 1/1; base 1/1
codex	tao-finetune-kumo-forecast-basic	14,242	13,984	+258	+1.84%	skill 1/1; base 1/1
ALL AGENTS	Dataset aggregate	113,604	44,232	+69,372	+156.84%	skill 2/2; base 2/2

Prompt tokens include cached reads, so total tokens are prompt + completion (cached is not added twice). The Efficiency score uses (prompt - cached) + completion. N/A means the relevant trajectory counters were not available; coverage is never estimated.

Tier Status

Tier	Purpose	Status	Evidence
Tier 1	Static validation	PASSED WITH OBSERVATIONS	11 validator(s); 17 finding(s)
Tier 2	Semantic deduplication	PASSED WITH OBSERVATIONS	2 validator(s); 2 finding(s)
Tier 3	Live agent evaluation	PASS	2 agent(s); 1 task(s)

Findings and Observations

<details> <summary>Show detailed findings and successful checks</summary>

HIGH DUPLICATE/duplicate: Duplicate content found within references/automl.md: "#### Basic mode (tune model parameters)" in references/automl.md (lines 154-166) vs "#### DARR mode (tune blending parameters)" in references/automl.md (lines 271-283) (references/automl.md:154)
MEDIUM QUALITY/quality_correctness: SKILL_SPEC recommended field missing: 'metadata.tags' (skills/models/tao-finetune-kumo-forecast/SKILL.md)
MEDIUM SCHEMA/frontmatter_field_placement: Root field 'tags' is ignored; use 'metadata.tags' (skills/models/tao-finetune-kumo-forecast/SKILL.md)
MEDIUM SCHEMA/folder_hierarchy: Unexpected nesting depth for general skill (skills/models/tao-finetune-kumo-forecast)
MEDIUM SCHEMA/body_recommended_section: Missing recommended section: '## Instructions' (skills/models/tao-finetune-kumo-forecast/SKILL.md)
14 additional finding(s) are available in the full evaluation artifacts.

</details>

Scoring Methodology

<details> <summary>Show dimension definitions, source signals, and thresholds</summary>

Dimension	Question	Scored signals
Security	Is it safe to use?	`security` (100%)
Correctness	Is the answer correct?	`accuracy` (100%)
Discoverability	Was the right skill loaded when needed?	`skill_execution` (100%)
Effectiveness	Did the skill help complete the task?	`goal_accuracy` (50%) + `behavior_check` (50%)
Efficiency	Did it avoid wasted tool calls and token usage?	`skill_efficiency` (50%) + `token_efficiency` (50%)

Dimension bands: PASS at 50% or above; NEUTRAL from 40% to below 50%; FAIL below 40%.
Overall Tier 3 lift: PASS at +5 points or more; FAIL at -10 points or less; values between those bands are NEUTRAL.
Overall verdict: PASS only when every configured dimension passes for at least one supported agent. Lift is reported as diagnostic evidence and does not override this gate.
The 50% attempt pass threshold is a separate per-task gate; it is not the dimension pass threshold.
Effectiveness is the equal-weight mean of goal completion (goal_accuracy) and expected workflow adherence (behavior_check).
Efficiency is 50% tool-call productivity (the backward-compatible skill_efficiency wire id) and 50% token_efficiency. Positive-case skill routing is scored under Discoverability, not Efficiency; a negative case without a routing target is N/A. N/A sources are omitted, remaining weights are renormalized, and the dimension is marked partial.

Signals present in this run:

security (Security): unsafe operations, secret leakage, and unauthorized access.
skill_execution (Skill Execution): whether the expected skill was selected, decoys were avoided, and the workflow executed.
skill_efficiency (Tool Productivity): tool-call productivity (legacy wire id; routing is scored under Discoverability).
accuracy (Accuracy): final-answer correctness against the reference answer.
goal_accuracy (Goal Accuracy): whether the user's goal was achieved.
behavior_check (Behavior Check): whether the expected workflow behavior was followed.
token_efficiency (Token Efficiency): actual uncached prompt plus completion usage (50% of Efficiency).

</details>

Freshness

Regenerate this benchmark when the skill, evaluation dataset, target agent/model, evaluator version, environment, or scoring policy changes.

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-08

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