feat(nucleus): Expose dataset_item_id on exported items, annotations and predictions

[luke-e-schaefer]

Batch exports only ever returned reference_id on the exported item, so keying an exported prediction back to a Nucleus dataset item meant a second lookup.

This is an inconsistency fix, not a new field: the single-item endpoints (/dataset/:id/loc, /refloc, /iloc) already return dataset_item_id, and the public API docs (ApiDocsPage/slices/batch-export.md) already document it in the batch-export response. The batch export was the odd one out.

Pairs with scaleapi PR: luke/nucleus-export-dataset-item-id.

What changed

dataset_item_id now appears everywhere reference_id already does:

• DatasetItem gains the field, wired through from_json — the single deserialization entry point, so every SDK path that returns an item picks it up, not just exports.
• Every Annotation / Prediction subclass gains it (box, line, polygon, keypoints, cuboid, category, multicategory, segmentation). convert_export_payload stamps it down from the item exactly as it already does for reference_id.
• The scene/video export docstring documents it on each track frame.

Read-only semantics

The field is server-assigned, and mirrors how DatasetItem.phash was done:

	behaviour
from_json	populated
locally constructed	None
__eq__	excluded (compare=False)
to_payload	absent — uploads unchanged

The __eq__ exclusion matters: without it, every existing test that compares a locally-built annotation against its round-tripped twin would start failing.

Exports from a backend that doesn't return the field leave it None rather than throwing, so this SDK version is safe against an un-upgraded backend.

Verification

The test suite requires live API keys (conftest.py hard-asserts on NUCLEUS_PYTEST_API_KEY), so it could not be run locally. Verified offline instead by driving convert_export_payload directly:

• every geometry type on both the annotation and prediction paths carries the id
• a local object still compares equal to its round-tripped self
• to_payload output is unchanged
• an item payload with no dataset_item_id yields None everywhere and does not raise

Formatted with the repo-pinned black 23.12.1 (a newer local black introduced unrelated reformatting, which was reverted).

🤖 Generated with Claude Code

Greptile Summary

The PR exposes the server-assigned dataset item ID throughout SDK export objects while preserving existing upload and equality behavior.

• Adds dataset_item_id deserialization to dataset items, annotations, and predictions.
• Propagates item-level IDs through batch-export and single-item response conversion.
• Keeps the field out of upload payloads and positional constructor signatures.
• Adds offline coverage for propagation, backward compatibility, and read-only semantics.
• Updates the package version, changelog, and scene-export documentation.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
nucleus/annotation.py	Adds a shared keyword-only, read-only dataset item ID field and deserializes it across all annotation types.
nucleus/prediction.py	Extends prediction constructors and deserializers with the keyword-only dataset item ID without changing upload payloads.
nucleus/dataset_item.py	Adds the server-assigned ID to dataset-item deserialization while excluding it from equality and serialization.
nucleus/utils.py	Propagates each enclosing item's dataset item ID to converted annotations and predictions for batch and single-item responses.
tests/test_utils.py	Adds offline coverage for ID propagation, absent backend fields, payload exclusion, equality, and keyword-only construction.
nucleus/dataset.py	Documents the dataset item ID available on scene and video track frames.
pyproject.toml	Bumps the client package version from 0.20.1 to 0.20.2.
CHANGELOG.md	Documents the exported dataset item ID and its read-only compatibility semantics.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[API response item] -->|dataset_item_id| B[DatasetItem.from_json]
    A --> C[Response converter]
    C -->|stamp item ID| D[Annotation.from_json]
    C -->|stamp item ID| E[Prediction.from_json]
    B --> F[SDK caller]
    D --> F
    E --> F
    B -. omitted .-> G[to_payload]
    D -. omitted .-> G
    E -. omitted .-> G

Loading

_{Reviews (4): Last reviewed commit: "Merge remote-tracking branch 'origin/mas..." | Re-trigger Greptile}

[edwinpav]

👀

[edwinpav]

Couple comments, aside from that, can / should any unit tests that test these existing functions be made or updated?

[edwinpav]

does the docs comment above (lines 93-122) need to be updated to include this key? Also do we have to fall back to None here, doesn't seem like we do that in the from_json in dataset_item.py

[luke-e-schaefer]

idt the other docstrings list dataset_item_id since it's server-assigned/read-only and not a user-supplied param (idt we document _task_id)