Tao Artifacts

NVIDIAOfficialCreated by NVIDIA Corporation

Skill
Tool integration
Software development
Apache-2.0
Medium risk
Has scripts

From the author

The contract home for TAO's SDK-free execution pipeline — authoritative JSON Schemas for the four typed artifacts (spec-bundle, job-record, results_dir layout, best_rec) plus the fixed job-status vocabulary and the nested-not-dotted spec rule. Use when authoring or validating a spec-bundle before submit, writing or reading a .tao/jobs job-record, resolving where results land, or consuming AutoML's best_rec.json. Trigger phrases include "validate the spec bundle", "job record schema", "status vocabulary", "results_dir layout", "best_rec schema".

— the description by NVIDIA Corporation

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides the definitive source of truth for the four primary artifacts used in the TAO execution pipeline: spec-bundle, job-record, results_dir layout, and best_rec. It defines the structural requirements, validation schemas, and operational rules necessary for producers and consumers to interact reliably within the TAO ecosystem. By enforcing consistent data formats and state vocabularies, it ensures that model data, job records, and output directories remain interoperable across different execution environments.

What it does

Provides authoritative JSON schemas for validating TAO pipeline artifacts
Defines the fixed vocabulary for job status transitions
Enforces structural rules for spec-bundle configuration and nesting
Specifies the storage-agnostic layout contract for job output directories
Outlines the lifecycle and responsibilities for model-to-platform execution seams

When to use it

When authoring or validating a spec-bundle before job submission
When reading or writing a job-record in the .tao/jobs directory
When resolving the location of job output artifacts
When consuming AutoML best_rec.json files
When debugging pipeline state transitions or artifact inconsistencies

Advantages

Ensures structural consistency across heterogeneous execution platforms
Provides a single source of truth for pipeline data contracts
Simplifies integration between model producers and platform consumers
Standardizes job state reporting for reliable monitoring and polling

Usage examples

“Validate the spec bundle”: The agent uses the provided JSON schema to verify that the spec-bundle configuration adheres to the required nested structure and mode discrimination rules.
“What is the status vocabulary?”: The agent returns the fixed set of job states: PENDING, RUNNING, COMPLETE, ERROR, CANCELED, and UNKNOWN.
“Show me the results_dir layout”: The agent explains the storage-agnostic layout where artifacts are organized by job_id and output_key under the defined results root.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/nvidia/tao-artifacts/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip tao-artifacts.zip -d .agents/skills

Documentation by NVIDIA Corporation

tao-artifacts

Four typed artifacts flow through every TAO job. Their schemas live here and nowhere else — producers (model/data skills) and consumers (platform skills) both validate against this skill's references/.

Artifact	Schema	Produced by → consumed by
spec-bundle	`references/spec_bundle.schema.json`	model/data skill → platform skill (at the submit seam)
job-record	`references/job_record.schema.json`	`scripts/tao_job_record.py` (the ONLY writer) → any re-attaching agent/poller
results_dir layout	`references/results_dir.contract.md`	platform skill at submit → whoever collects outputs
best_rec	`references/best_rec.schema.json`	tao-run-automl adapter → DEFT warm-start

Quick Start — validate an artifact

python - <<'PY'
import json, yaml, jsonschema, pathlib
ref = pathlib.Path("${TAO_SKILL_BANK_PATH:?}/skills/core/tao-artifacts/references")
schema = json.loads((ref / "spec_bundle.schema.json").read_text())
bundle = yaml.safe_load(open("/path/to/bundle.yaml"))   # or a dict built in-context
jsonschema.validate(bundle, schema)                      # raises on violation
print("bundle OK")
PY

Validate the bundle before the verify-before-launch gate; validate a job-record only when debugging (the writer script already enforces the schema).

The two rules the schemas enforce structurally

Nested, not dotted. A spec is a nested dict mirroring the container's config shape — {"train": {"num_epochs": 12}}. Any key containing . at any depth is rejected ({"train.num_epochs": 12} is the #1 authoring mistake). Note the distinction: declared_inputs[].spec_key and gpu_spec_key are dotted/indexed pointers into the spec (dataset.train_data_sources[0].image_dir) — dots are correct there.
Mode discrimination. mode: config requires spec + config_format and a command containing {config_path}, and forbids args. mode: args requires args and forbids spec. There is no other mode.

Optional action lifecycle

Use execution when an action needs more than its primary command. This is the shared model-to-platform seam; do not add a model-specific Docker, Kubernetes, or SLURM renderer merely to carry runtime environment, attestations, post-processing, or helper dependencies.

The producing model/data skill owns environment, ordered pre_commands, ordered post_commands, distributed-launch intent, and completion evidence.
The platform owns container mounts, scheduler/container syntax, task/rank binding, timeouts, log paths, and preservation of the real child exit code.
environment is non-secret. Credential values continue to use the selected platform's secret/sidecar contract and never enter a spec-bundle.
Commands, environment values, and string values in spec may use {config_path}, {job_id}, and {results_dir}. The platform binds them only after the job record has been opened; the job record's results_dir is authoritative over any pre-review display path. Persist hashes of both the producer bundle and the bound runtime config.
supporting_files names checked-in orchestration helpers relative to the producing skill root. The platform stages the closed set, verifies every declared SHA256, and rejects traversal, undeclared siblings, or overwrite of a different bundle. Supporting files orchestrate an action; they must never shadow or patch code inside the selected image.
A torchrun declaration expresses process topology, not SLURM/Kubernetes syntax. Each platform maps it to its native distributed launcher.

Fixed status vocabulary

Every job state anywhere in the pipeline is exactly one of:

PENDING · RUNNING · COMPLETE · ERROR · CANCELED · UNKNOWN

Platform-native sub-states (ImagePullBackOff, PENDING-because-resources, Insufficient-GPU, slurm COMPLETING…) are never new states — they ride in the transition's message field. Terminal = COMPLETE | ERROR | CANCELED. This is what lets the in-turn poll loop and the detached poller share one code path across docker/slurm/kubernetes/brev.

Ordering invariants (enforced at the seam, stated here)

The verify-before-launch gate runs on the spec-bundle, before any job id exists.
tao_job_record.py open writes PENDING + the resolved results_dir first and returns the id — the only handle a launch can use. A submit that skipped the gate has no id, so it cannot launch.
transitions is append-only; .tao/ lives outside every synced results tree.

Files

ATTRIBUTION.mdAdded by AutoGineer909 B
BENCHMARK.md6.9 KiB
LICENSELicence file added by AutoGineer11.2 KiB
SKILL.md5.3 KiB
config/skillspector-baseline.yaml834 B
evals/evals.json903 B
references/best_rec.schema.json2.3 KiB
references/job_record.schema.json3.9 KiB
references/results_dir.contract.md1.6 KiB
references/spec_bundle.schema.json8.0 KiB
references/tests/test_artifact_schemas.pyScript12.9 KiB
skill-card.md4.3 KiB
skill.oms.sig5.9 KiB

references/tests/test_artifact_schemas.py

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

"""Schema tests for the four TAO artifacts.

The spec-bundle cases mirror real skill_info.yaml shapes: the config-mode
bundle is DINO train (nested spec, array-indexed input pointers); the args-mode
bundle is a data-services action. The load-bearing rejections: dotted spec keys
at ANY depth (the #1 authoring mistake), mode cross-contamination, unresolved
image keys, and job-records that skip the results_dir-at-submit invariant.
"""

import copy
import json
from pathlib import Path

import jsonschema
import pytest

REF = Path(__file__).resolve().parents[1]


def load(name):
    return json.loads((REF / name).read_text())


@pytest.fixture(scope="module")
def spec_schema():
    return load("spec_bundle.schema.json")


@pytest.fixture(scope="module")
def record_schema():
    return load("job_record.schema.json")


@pytest.fixture(scope="module")
def best_rec_schema():
    return load("best_rec.schema.json")


def ok(instance, schema):
    jsonschema.validate(instance, schema)


def bad(instance, schema):
    with pytest.raises(jsonschema.ValidationError):
        jsonschema.validate(instance, schema)


# --------------------------------------------------------------------------- #
# spec-bundle fixtures
# --------------------------------------------------------------------------- #

DINO_BUNDLE = {
    "network_arch": "dino",
    "action": "train",
    "image": "nvcr.io/nvidia/tao/tao-toolkit:6.26.3-pyt",  # unpinned: test fixture
    "mode": "config",
    "command": "dino train -e {config_path}",
    "config_format": "yaml",
    "spec": {
        "dataset": {
            "train_data_sources": [
                {
                    "image_dir": "/lustre/fsw/portfolios/data/coco/train2017",
                    "json_file": "/lustre/fsw/portfolios/data/coco/train.json",
                }
            ],
            "batch_size": 4,
        },
        "train": {"num_epochs": 12, "num_gpus": 8, "optim": {"lr": 0.0002}},
    },
    "declared_inputs": [
        {
            "spec_key": "dataset.train_data_sources[0].image_dir",  # dotted POINTER — allowed
            "type": "folder",
            "uri": "lustre:///lustre/fsw/portfolios/data/coco/train2017",
        },
        {
            "spec_key": "train.pretrained_model_path",
            "type": "file",
            "optional": True,
            "uri": "ngc://nvidia/tao/pretrained_dino_nvimagenet:fan_small",
        },
    ],
    "declared_outputs": [{"spec_key": "results_dir", "type": "folder"}],
    "upload_excludes": ["inputs/"],
    "compute_shape": {"gpus": 8, "nodes": 1},
    "gpu_spec_key": "train.num_gpus",
}

ARGS_BUNDLE = {
    "network_arch": "data_services",
    "action": "gap_analysis",
    "image": "nvcr.io/nvidia/tao/tao-toolkit:6.26.3-data-services",  # unpinned: test fixture
    "mode": "args",
    "command": "gap_analysis vcn_aoi",
    "args": ["--results-parquet", "/data/results.parquet", "--top-k", "200"],
    "declared_inputs": [
        {"spec_key": "results_parquet", "type": "file", "uri": "s3://bkt/exp/results.parquet"}
    ],
    "declared_outputs": [{"spec_key": "results_dir", "type": "folder"}],
    "compute_shape": {"gpus": 0, "nodes": 1},
}


# --------------------------------------------------------------------------- #
# spec-bundle: accepts
# --------------------------------------------------------------------------- #

def test_dino_config_bundle_valid(spec_schema):
    ok(DINO_BUNDLE, spec_schema)


def test_args_bundle_valid(spec_schema):
    ok(ARGS_BUNDLE, spec_schema)


def test_declared_output_accepts_safe_relative_path(spec_schema):
    b = copy.deepcopy(ARGS_BUNDLE)
    b["declared_outputs"] = [{"spec_key": "binary_coco", "type": "file",
                              "relative_path": "pseudo_labels/coco.json"}]
    ok(b, spec_schema)


def test_bundle_accepts_model_owned_action_lifecycle(spec_schema):
    b = copy.deepcopy(DINO_BUNDLE)
    b["execution"] = {
        "environment": {
            "PYTHONUNBUFFERED": "1",
            "TAO_JOB_ID": "{job_id}",
        },
        "pre_commands": ["python -m package.runtime_preflight"],
        "post_commands": ["python -m package.verify_results --config {config_path}"],
        "post_scope": "leader",
        "distributed": {
            "launcher": "torchrun",
            "processes_per_node": 8,
            "tasks_per_node": 1,
        },
        "supporting_files": [
            {
                "source": "scripts/checkpoint_action.py",
                "destination": "checkpoint_action.py",
                "sha256": "a" * 64,
            }
        ],
        "completion": {
            "child_exit_code_path": "{results_dir}/child_exit_code",
            "structured_status_path": "{results_dir}/status.json",
            "success_states": ["SUCCESS"],
        },
    }
    ok(b, spec_schema)


def test_bundle_rejects_secret_like_or_unhashed_lifecycle_inputs(spec_schema):
    b = copy.deepcopy(DINO_BUNDLE)
    b["execution"] = {"environment": {"bad-name": "value"}}
    bad(b, spec_schema)

    b = copy.deepcopy(DINO_BUNDLE)
    b["execution"] = {
        "supporting_files": [
            {"source": "scripts/helper.py", "destination": "helper.py"}
        ]
    }
    bad(b, spec_schema)

    b = copy.deepcopy(DINO_BUNDLE)
    b["execution"] = {
        "supporting_files": [
            {
                "source": "../outside.py",
                "destination": "helper.py",
                "sha256": "a" * 64,
            }
        ]
    }
    bad(b, spec_schema)


def test_dotted_pointer_allowed_in_declared_inputs(spec_schema):
    # spec_key is a pointer; dots + [0] indices are correct THERE
    b = copy.deepcopy(DINO_BUNDLE)
    b["declared_inputs"][0]["spec_key"] = "dataset.val_data_sources[0].json_file"
    ok(b, spec_schema)


# --------------------------------------------------------------------------- #
# spec-bundle: the nested-not-dotted rule at every depth
# --------------------------------------------------------------------------- #

def test_reject_top_level_dotted_spec_key(spec_schema):
    b = copy.deepcopy(DINO_BUNDLE)
    b["spec"]["train.num_epochs"] = 12  # the #1 mistake
    bad(b, spec_schema)


def test_reject_nested_dotted_spec_key(spec_schema):
    b = copy.deepcopy(DINO_BUNDLE)
    b["spec"]["train"]["optim.lr"] = 0.001
    bad(b, spec_schema)


def test_reject_dotted_key_inside_array_of_objects(spec_schema):
    b = copy.deepcopy(DINO_BUNDLE)
    b["spec"]["dataset"]["train_data_sources"][0]["image.dir"] = "/x"
    bad(b, spec_schema)


# --------------------------------------------------------------------------- #
# spec-bundle: mode discrimination
# --------------------------------------------------------------------------- #

def test_reject_config_mode_with_args(spec_schema):
    b = copy.deepcopy(DINO_BUNDLE)
    b["args"] = ["--foo"]
    bad(b, spec_schema)


def test_reject_config_mode_missing_config_format(spec_schema):
    b = copy.deepcopy(DINO_BUNDLE)
    del b["config_format"]
    bad(b, spec_schema)


def test_reject_config_command_without_config_path(spec_schema):
    b = copy.deepcopy(DINO_BUNDLE)
    b["command"] = "dino train"
    bad(b, spec_schema)


def test_reject_args_mode_with_spec(spec_schema):
    b = copy.deepcopy(ARGS_BUNDLE)
    b["spec"] = {"train": {"num_epochs": 1}}
    bad(b, spec_schema)


def test_reject_missing_mode(spec_schema):
    b = copy.deepcopy(DINO_BUNDLE)
    del b["mode"]
    bad(b, spec_schema)


# --------------------------------------------------------------------------- #
# spec-bundle: other seam invariants
# --------------------------------------------------------------------------- #

def test_reject_unresolved_image_key(spec_schema):
    b = copy.deepcopy(DINO_BUNDLE)
    b["image"] = "tao_toolkit.pyt"  # a versions.yaml key, not a resolved URI
    bad(b, spec_schema)


def test_reject_declared_input_missing_uri(spec_schema):
    b = copy.deepcopy(DINO_BUNDLE)
    del b["declared_inputs"][0]["uri"]
    bad(b, spec_schema)


def test_reject_empty_declared_outputs(spec_schema):
    b = copy.deepcopy(DINO_BUNDLE)
    b["declared_outputs"] = []
    bad(b, spec_schema)


@pytest.mark.parametrize("path", ["/absolute/coco.json", "../coco.json", "labels/../coco.json"])
def test_reject_unsafe_declared_output_relative_path(spec_schema, path):
    b = copy.deepcopy(ARGS_BUNDLE)
    b["declared_outputs"] = [{"spec_key": "binary_coco", "type": "file",
                              "relative_path": path}]
    bad(b, spec_schema)


def test_reject_zero_nodes(spec_schema):
    b = copy.deepcopy(DINO_BUNDLE)
    b["compute_shape"]["nodes"] = 0
    bad(b, spec_schema)


# --------------------------------------------------------------------------- #
# job-record
# --------------------------------------------------------------------------- #

RECORD = {
    "schema_version": 1,
    "id": "dino-train-a1b2c3",
    "platform": "slurm",
    "backend_ref": None,
    "image": "nvcr.io/nvidia/tao/tao-toolkit:6.26.3-pyt",  # unpinned: test fixture
    "network_arch": "dino",
    "action": "train",
    "results_dir": "/lustre/fsw/portfolios/project/results/dino-train-a1b2c3",
    "storage_tier": "A",
    "upload_excludes": ["inputs/"],
    "submitted_at": "2026-07-09T18:00:00+00:00",
    "transitions": [
        {"ts": "2026-07-09T18:00:00+00:00", "state": "PENDING", "message": "opened", "source": "agent"}
    ],
    "terminal_state": None,
    "redacted": True,
}


def test_job_record_valid_at_open(record_schema):
    ok(RECORD, record_schema)


def test_job_record_valid_terminal_with_retry_chain(record_schema):
    r = copy.deepcopy(RECORD)
    r["backend_ref"] = "4211337"
    r["transitions"].append(
        {"ts": "2026-07-09T19:00:00+00:00", "state": "ERROR", "message": "NODE_FAIL", "source": "poller"}
    )
    r["terminal_state"] = "ERROR"
    r["terminal_write_by"] = "poller"
    r["err_class"] = "ERR_INFRA"
    r["retry_of"] = None
    r["parent_job"] = "automl-exp-7"
    ok(r, record_schema)


def test_job_record_rejects_unknown_state(record_schema):
    r = copy.deepcopy(RECORD)
    r["transitions"][0]["state"] = "QUEUED"  # not in the fixed vocabulary
    bad(r, record_schema)


def test_job_record_rejects_empty_transitions(record_schema):
    r = copy.deepcopy(RECORD)
    r["transitions"] = []
    bad(r, record_schema)


def test_job_record_rejects_missing_results_dir(record_schema):
    r = copy.deepcopy(RECORD)
    del r["results_dir"]
    bad(r, record_schema)
    r["results_dir"] = ""  # empty is as bad as missing
    bad(r, record_schema)


def test_job_record_rejects_unredacted(record_schema):
    r = copy.deepcopy(RECORD)
    r["redacted"] = False
    bad(r, record_schema)


def test_job_record_rejects_bad_tier_and_malformed_platform(record_schema):
    r = copy.deepcopy(RECORD)
    r["storage_tier"] = "D"
    bad(r, record_schema)
    # The schema sees STORED values (the writer normalizes input into canonical
    # kebab-case first) — non-canonical forms fail the pattern, not a registry.
    for malformed in ("Docker", "my platform", "-kratos", "a" * 40):
        r = copy.deepcopy(RECORD)
        r["platform"] = malformed
        bad(r, record_schema)


def test_job_record_platform_is_an_open_set(record_schema):
    """External platform skills (kratos, lepton, ...) record under their own
    slug with no schema edit — install equals register."""
    for external in ("kratos", "lepton", "osmo"):
        r = copy.deepcopy(RECORD)
        r["platform"] = external
        ok(r, record_schema)


# --------------------------------------------------------------------------- #
# best_rec
# --------------------------------------------------------------------------- #

BEST_REC = {
    "schema_version": 1,
    "experiment_id": "automl-exp-7",
    "metric_name": "far_at_100_recall",
    "direction": "minimize",
    "best": {
        "rec_id": "rec_003",
        "score": 0.0012,
        "specs": {"train": {"optim": {"lr": 0.00013}}},
        "observed_budget": {"num_epochs": 10},
        "checkpoint_uri": "/lustre/results/automl-exp-7/rec_003/model_epoch_009_step_01200.pth",
        "checkpoint_epoch": 9,
        "checkpoint_step": 1200,
    },
    "all_recs": [
        {"rec_id": "rec_001", "score": 0.004, "job_id": "dino-train-x1"},
        {"rec_id": "rec_002", "score": None},
        {"rec_id": "rec_003", "score": 0.0012, "job_id": "dino-train-x3"},
    ],
}


def test_best_rec_valid(best_rec_schema):
    ok(BEST_REC, best_rec_schema)


def test_best_rec_rejects_missing_metric_identity(best_rec_schema):
    r = copy.deepcopy(BEST_REC)
    del r["metric_name"]
    bad(r, best_rec_schema)
    r = copy.deepcopy(BEST_REC)
    r["direction"] = "up"
    bad(r, best_rec_schema)


def test_best_rec_rejects_dotted_specs(best_rec_schema):
    r = copy.deepcopy(BEST_REC)
    r["best"]["specs"] = {"train.optim.lr": 0.00013}
    bad(r, best_rec_schema)


def test_best_rec_rejects_missing_observed_budget(best_rec_schema):
    r = copy.deepcopy(BEST_REC)
    del r["best"]["observed_budget"]
    bad(r, best_rec_schema)

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 Python

The author says: Python 3.10+ with jsonschema for validation. No nvidia-tao-sdk.

Security

What our scanner noticed· Medium risk

Large base64-encoded blobs
Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

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-artifacts · commit fce3cca

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE-APACHE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

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-artifacts.zip