Skip to main content

aip_sdk.attach_ground_truth

aip_sdk.attach_ground_truth(version_id: str, file: str | Path | None = None, *, rows: Mapping[str, Mapping[str, Sequence[str]]] | None = None, data: bytes | None = None, filename: str | None = None, client: APIClient | None = None) -> TraceGroundTruthVersion

Attach ground truth to a landed trace version, deriving a new version from it.

Supply the ground truth exactly one way: file (a path to a .csv/.json/ .jsonl file), rows (an in-memory mapping), or data (raw bytes, which needs filename so the platform can read the format from its extension).

The base version is never mutated — the returned dataset_version_id is a new version carrying the ground truth, and it takes over as the version metrics score when the base was that version. Evaluation targets defined on the base are carried across with new IDs, reported per target in migrated_partitions.

Retries must re-submit against the same version_id as the first attempt: replay is keyed on the base, so re-uploading the same file against the version it just derived is a different request that merges to a no-op and still derives a version. Record the returned dataset_version_id as the result rather than using it as the next upload target.

Parameters

  • version_id str: Dataset version to attach the ground truth to.
  • file str | Path | None: Path to the ground-truth file, keyed by session_id (or trace_id).
  • rows Mapping[str, Mapping[str, Sequence[str]]] | None: Ground truth as identifier -> column -> values, serialised for you.
  • data bytes | None: Ground-truth file content, for a file you have already read or built.
  • filename str | None: Name for data, whose extension selects the format. Required with data and rejected with file/rows.
  • client APIClient | None: Optional API client.

Returns

Raises

  • InvalidArgumentError: If the ground truth is supplied more than one way or not at all, filename is missing or misplaced, a rows value is not a list of strings, the file cannot be read, or the format is not one of GROUND_TRUTH_FILE_SUFFIXES.
  • AuthError: If credentials are missing or invalid.
  • ForbiddenError: If the caller lacks editor rights on the version's workspace.
  • NotFoundError: If the dataset version does not exist.
  • UnprocessableEntityError: If the platform rejects the file — over the size limit, malformed, or keyed against identifiers this version does not have.
  • ResponseParseError: If the platform's response does not match this SDK version.