Toto 2.0 Forecasting Pipeline

DIMER-oriented zero-shot probabilistic forecasting wrapper for Datadog Toto 2.0, initially pinned to the Toto-2.0-2.5B checkpoint. The wrapper normalizes multivariate target input, nine quantile outputs, q=0.5 median forecasts, chronological evaluation, and provenance.

Upstream alignment

• Model: Datadog/Toto-2.0-2.5B
• Revision: 51a2812bbe449437c01b79c0e425ed578f335f5b
• Runtime package: toto-2==2.0.0
• Weight license: Apache-2.0
• Weight format: SafeTensors
• Current Toto 2.0 capability: zero-shot multivariate forecasting with nine quantiles
• Not claimed: Toto 2.0 fine-tuning or exogenous-variable support; upstream says these are planned rather than currently available

Public API

from toto_forecasting_pipeline import TotoForecastPipeline

pipe = TotoForecastPipeline.from_pretrained(device="cuda")
result = pipe.forecast(
    [1, 2, 3, 4] * 32,
    horizon=24,
    decode_block_size=768,
)
print(result["median"])

decode_block_size must be None or a positive multiple of the model patch size (32 for this checkpoint). None requests a single forward-pass decode; the tutorial uses 768 explicitly. Upstream patches the context in blocks of patch_size, so the wrapper left-pads any context whose length is not a multiple of it with masked (unobserved) positions — the upstream scaler and patch embedding are mask-aware, so the pads carry no signal (upstream's own GluonTS adapter truncates to a patch multiple instead); a context shorter than one patch is rejected; the applied context_padding and patch_size are returned with every result. The 2.5B checkpoint is treated as a GPU release-reference path even though the API allows callers to choose another device explicitly.

Weights layout

weights/toto-2.0-2.5b/
  dimer-base-manifest.json   # modelId, revision, per-file bytes + sha256 (verified on every load)
  config.json                # Toto2ModelConfig fields read by Toto2Model.from_pretrained(<dir>)
  model.safetensors          # 9817176960 bytes, git-ignored and not kept locally (SafeTensors)

from_pretrained() calls stage_missing_files() then verify_snapshot() and refuses to load if any file is missing or its SHA-256 differs from the manifest; allow_download=True fetches only the absent manifest entries at revision 51a2812bbe449437c01b79c0e425ed578f335f5b. Without a snapshot directory the same flag falls back to upstream Toto2Model.from_pretrained(MODEL_ID, revision=...); the default is to refuse. The manifest was written from the Hub API (LFS size + SHA-256 for the checkpoint, the small files hashed locally); the 9.8 GB checkpoint is intentionally not stored here. To stage it by hand: hf download Datadog/Toto-2.0-2.5B --revision 51a2812bbe449437c01b79c0e425ed578f335f5b --local-dir weights/toto-2.0-2.5b.

Tutorial

tutorials/toto_forecasting_colab.ipynb is declared TASK-INFERENCE under DIMER Notebook Specification 1.1 and is standalone (§3.6): generated by tools/build_notebook.py, it carries the package's three modules, model identity, manifest digests and runtime pins, so the exported notebook runs without this repository (parity enforced by tests/test_notebook_parity.py). Its default path generates a deterministic two-variate synthetic series in code, withholds the final horizon chronologically, surfaces the pipeline ceilings, resolves the pinned 9.8 GB checkpoint through the public API on a CUDA GPU, forecasts with the q=0.5 median as the point forecast (decode_block_size=768, mask-aware padding to a patch multiple), scores mae/rmse/interval_coverage against a last-value baseline through evaluation_report, validates raw BYOD CSV headers before pandas ingestion, and exports JSON plus an aligned CSV. BYOD is optional and gated off by default. See tutorials/README.md for the registry and docs/release-verification.md for the release gate.

Release status

Candidate. Static/unit checks do not constitute clean-runtime notebook evidence. The 2.5B checkpoint is heavyweight; a clean supported GPU execution record of the standalone notebook for the exact PR/release revision is required before release-grade promotion. The earlier local pre-flight run recorded in docs/release-verification.md executed the previous (repository-installing) notebook and does not cover the standalone carrier or the manifest-verified snapshot path.

AI Assistance Disclosure

This repository’s code and accompanying documentation were developed with generative AI assistance for code development and technical writing under maintainer direction. The maintainer remains responsible for reviewing the implementation, validating results, and making release decisions. AI assistance does not constitute independent verification, provider endorsement, or release approval.