Promote a golden version

A golden dataset version is the frozen, promoted version of a dataset that the platform treats as the evaluation ground truth. Datasets are versioned: each upload or column mapping produces a new DatasetVersion, and every version carries a stage (its position in the lifecycle) and an is_golden flag. Promoting a version sets is_golden = True and moves it to the golden stage; from that point on, evaluation runs that reference the dataset pull rows from the golden version rather than from a draft or in-progress one. Only one version is golden at a time, which is what makes evaluations reproducible — the same golden version yields the same ground truth on every run.

Everything in this section is about text and image (gdi_text_v1 / gdi_image_v1) datasets. An agent-trace dataset (agent_trace_v1) skips this promotion path entirely: landing traces makes that version current automatically, and attaching ground truth hands currency over to the new version it derives — there's no quality gate and no promote() call to make yourself. See Guide: Evaluate an Agent for that flow.

Dataset versions and stages

Each DatasetVersion exposes the following attributes:

Attribute	Meaning
.id	The version's unique identifier
.version	The numeric version, e.g. v3
.stage	The version's position in the lifecycle
.is_golden	Whether this version is the golden one
.row_count	The number of rows in the version

SDK

List a dataset's versions to find the one you want to promote, and read latest_version() to get the most recent version — typically the one you have just uploaded or mapped and intend to promote.

import aip_sdk as aip

aip.init("https://api.trials.aip-v2.resarodev.ai", api_key="<your-api-key>")

dataset = aip.load_dataset("compliance-test-set")

for v in dataset.versions():
    print(v.id, v.version, v.stage, v.is_golden, v.row_count)

latest = dataset.latest_version()

API

Request the same version listing with curl.

curl -sS "$AIP_API_URL/datasets/<dataset_id>/versions" \
  -H "Authorization: Bearer $AIP_TOKEN"

Promoting a version to golden

dataset.promote(version_id) promotes a version to golden. Promotion is gated on data quality: the version's latest quality verdict must be PASS. If the latest verdict is a WARN, a plain promote() is rejected — pass force=True with a reason to acknowledge the warning and promote anyway. Forced promotions are audited. A FAIL, STALE, or NOT_RUN verdict always rejects, even with force=True; run (or re-run) quality checks first in that case. promote() returns the updated version with is_golden = True and the golden stage.

Promotion is an SDK/REST operation.

In the example below, quality checks are re-run first so the verdict is fresh before promoting. If the version is already golden there is nothing to promote; otherwise branch on the quality report's status. Review any WARN findings before accepting them and replace the example reason with the specific warning you accepted. FAIL, STALE, and NOT_RUN stop the workflow. Authentication, network, and other promotion errors propagate without retrying as a forced promotion. Use dataset.demote(version.id) to reverse a promotion when needed.

SDK

report = dataset.run_checks(latest.id, label="pre-promote guard")

if latest.is_golden:
    version = latest
elif report.status == "PASS":
    version = dataset.promote(latest.id)
elif report.status == "WARN":
    version = dataset.promote(
        latest.id,
        force=True,
        reason="Reviewed pre-promote warnings: <specific accepted warning and rationale>.",
    )
else:
    raise RuntimeError(f"Quality verdict {report.status}; resolve the findings and re-run checks before promotion")

print(version.stage, version.is_golden, version.version)

dataset.demote(version.id)

API

The REST equivalents

an optional body to force past a WARN. The first call promotes a version; the second demotes a version from golden.

curl -sS -X POST "$AIP_API_URL/datasets/<dataset_id>/versions/<version_id>/promote" \
  -H "Authorization: Bearer $AIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"force": true, "reason": "Dataset acknowledged for evaluation."}'

curl -sS -X POST "$AIP_API_URL/datasets/<dataset_id>/versions/<version_id>/demote" \
  -H "Authorization: Bearer $AIP_TOKEN"

Downloading a dataset version

dataset.download() returns the dataset's rows as a pandas DataFrame. Under the hood the SDK requests a presigned MinIO URL and streams the file directly from object storage, so downloads do not proxy through the API. By default it returns the latest (golden, once promoted) version; pass file_version="converted" for the platform-normalized file or file_version="original" for the file exactly as uploaded. Downloading is likewise SDK/REST only.

SDK

In the SDK example below, the first call returns the golden rows as a DataFrame and the second returns the file exactly as uploaded.

df_golden = dataset.download()
df_original = dataset.download(file_version="original")

print(len(df_golden), list(df_golden.columns))

API

At the REST level, request the presigned URL and then fetch it. The first endpoint returns a presigned URL for the latest version; the second returns one for a specific version.

curl -sS "$AIP_API_URL/datasets/<dataset_id>/download-url" \
  -H "Authorization: Bearer $AIP_TOKEN"

curl -sS "$AIP_API_URL/datasets/<dataset_id>/versions/<version_id>/download" \
  -H "Authorization: Bearer $AIP_TOKEN"

The response contains a short-lived presigned URL; issue a plain GET against that URL to retrieve the dataset file.