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".
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
