NV-Tesseract Forecasting — transformer-based multivariate time series forecasting with DARR (context-enhanced kNN retrieval), interpretability, and fine-tuning. Use when the user asks to "forecast with NV-Tesseract", "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 or mentions "nv-tesseract-forecasting", "moment_head_512_6hr", or "run8_best_model_cr".
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
NV-Tesseract Forecasting — transformer-based multivariate time series forecasting with DARR (context-enhanced kNN retrieval), interpretability, and fine-tuning. Use when the user asks to "forecast with NV-Tesseract", "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 or mentions "nv-tesseract-forecasting", "moment_head_512_6hr", or "run8_best_model_cr".
license
Apache-2.0
compatibility
Requires Python 3.10+ and uv. CUDA GPU recommended; Apple Silicon (MPS) and CPU supported.
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.
Interpretability PDF report, heatmap PNG, flow + stability charts
uv add matplotlib
Credentials
nvidia/nv-tesseract-forecasting 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/NV-Tesseract
cd NV-Tesseract/forecasting
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 rows for the requested horizon.
{target_column}_forecast
import sys, pandas as pd
sys.path.append("/path/to/NV-Tesseract/forecasting") # clone NV-Tesseract with --branch mainfrom sdk.forecasting import perform_forecasting
df = pd.read_csv("your_data.csv") # must have timestamp + numeric target column
results = perform_forecasting(
df=df,
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
)
# Returns DataFrame: timestamp | {target_column}_forecast (forecast_horizon rows)print(results.head())
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
Pass use_cross_channel=False to use the standard checkpoint:
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 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
forecasting/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 NV-Tesseract checkpoint; --ckpt-init none
trains a fresh head from the base backbone.
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 forecasting/
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
