NV-Tesseract AD Diffusion

Diffusion-based anomaly detection and fine-tuning for multivariate time series. The model reconstructs randomly masked segments and scores each timestep by MAE between reconstruction and original signal; adaptive thresholding (SCS or MACS) converts scores to binary labels.

Source code: https://github.com/NVIDIA/NV-Tesseract Pretrained weights: https://huggingface.co/nvidia/nv-tesseract-ad-diffusion

For the most up-to-date usage information, refer to the README files in the NV-Tesseract repository:

• ad_diffusion/README.md — full SDK reference, model architecture, and API docs
• ad_diffusion/examples/datasets/README.md — dataset format, synthetic data generation, and CSV conventions

External dependencies

Credentials

nvidia/nv-tesseract-ad-diffusion is a public repo — no token required for downloading weights. If you ever hit a 401/403 (gated access or private fork) 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/ad_diffusion
uv sync                              # install dependencies (one-time)

# Inference — synthetic data, auto-downloads weights from HF on first run
uv run python examples/quick_example.py

# Inference — your own CSV
uv run python examples/quick_example.py \
  --model-path final_model.pth \
  --config-path curriculum_medium.yaml \
  --dataset-path /path/to/data.csv

# Pre-download weights only (warm the cache before going offline)
uv run python examples/quick_example.py --download-weights

# Fine-tune on your own normal-behavior data
uv run python examples/finetune_example.py \
  --csv /path/to/normal_training_data.csv \
  --timestamp-col timestamp \
  --label-col is_anomaly \
  --epochs 20 \
  --output-dir artifacts/finetune_my_data

Inference

Use perform_anomaly_analysis_with_diffusion in sdk/anomaly_analysis.py. It validates input, auto-dispatches across all visible GPUs, applies adaptive thresholding (SCS or MACS), and returns the original DataFrame with Anomaly (0/1) and MAE columns appended.

import sys, pandas as pd
sys.path.append("/path/to/NV-Tesseract/ad_diffusion")  # clone NV-Tesseract with --branch main
from sdk.anomaly_analysis import perform_anomaly_analysis_with_diffusion

df = pd.read_csv("your_data.csv")

# The API raises ValueError on non-numeric columns — drop timestamp, IDs, and labels first.
df = df.select_dtypes(include="number")

results = perform_anomaly_analysis_with_diffusion(
    df=df,
    threshold_strategy="scs",       # "scs" (fast) or "macs" (adaptive)
    model_path=None,                 # None → auto-download final_model.pth from HF
    config_path=None,                # None → auto-download curriculum_medium.yaml from HF
    nsample=15,                      # diffusion samples per window; ↑ accuracy, ↑ latency
    preprocess_model_dir=None,       # optional preprocessing model directory
)
# results columns: Anomaly (0/1), MAE (float), plus all original columns
print(results[["Anomaly", "MAE"]].describe())

Inference CLI reference

Fine-tuning

Fine-tune on your own data. The training CSV should contain mostly normal behavior. Validate the pretrained model on your domain before fine-tuning.

uv run python examples/finetune_example.py \
  --csv /path/to/normal_data.csv \
  --val-csv /path/to/val_data.csv \   # optional; otherwise --val-ratio splits --csv
  --pretrained-model final_model.pth \
  --epochs 20 --batch-size 16 --lr 1e-5 \
  --output-dir artifacts/finetune_my_data

Fine-tuning arguments

Running inference with a fine-tuned checkpoint

results = perform_anomaly_analysis_with_diffusion(
    df=df,
    threshold_strategy="scs",
    model_path="artifacts/finetune_my_data/best_finetuned_model.pth",
    config_path="artifacts/finetune_my_data/finetune_config.yaml",
    nsample=15,
)

AutoML (HPO: hyperparameter optimization)

This skill supports AutoML for fine-tuning HPO and labeled inference HPO 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, VirtualEnvSDK setup, config flow, window-length constraints, inference trial scripts, or AutoML result handoff details.

Data requirements

timestamp,sensor_1,sensor_2,sensor_3
2024-01-01 00:00:00,0.42,1.10,-0.33
...

Pass only numeric feature columns to the inference API — it raises ValueError on non-numeric columns rather than dropping them. Use df.select_dtypes(include="number") or drop by name before calling. Fine-tuning handles this via --timestamp-col, --label-col, and --drop-cols CLI args.

Output structure

Inference (examples/quick_example.py):

examples/datasets/
└── anomaly_results.csv      # original columns + Anomaly (0/1) + MAE

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

artifacts/finetune_my_data/
├── best_finetuned_model.pth     # checkpoint with lowest validation loss
├── final_finetuned_model.pth    # checkpoint from last epoch
├── metrics.json                 # scalar for AutoML: {"val_loss": <best>}
├── epoch_metrics.json           # per-epoch log: [{"epoch": N, "train_loss": …, "val_loss": …}]
└── finetune_config.yaml         # config used during training (for reproducibility)

Model configuration (curriculum_medium.yaml)

Hardware

Known pitfalls