x4d-devkit 0.22.0rc2__tar.gz → 0.23.0rc1__tar.gz

{x4d_devkit-0.22.0rc2 → x4d_devkit-0.23.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.22.0rc2
+Version: 0.23.0rc1
 Summary: Official X-4D external SDK and CLI for datasets, platform APIs, training bridges, and automation
 Author: windzu
 License-Expression: Apache-2.0
@@ -66,7 +66,7 @@ Design decisions for this boundary are tracked in GitHub issues, starting with:
 ## Installation
 
 ```bash
-pip install x4d-devkit==0.22.0rc2
+pip install x4d-devkit==0.23.0rc1
 ```
 
 Devkit is released independently as an immutable wheel. X-4D, XPoints, and
@@ -105,7 +105,10 @@ validation boundary.
 Shared validation rules for platform submit, X-Points preflight, local clip
 validation, and training consumers are documented in
 [docs/shared-contract-validation.md](docs/shared-contract-validation.md).
-Portable export producers and consumers share the exact `0.11` manifest
+The Dataset 0.12 single-file annotation authority, semantic revision, and
+derived track views are documented in
+[docs/annotation-contract.md](docs/annotation-contract.md).
+Portable export producers and consumers share the exact `0.12` manifest
 parser documented in
 [docs/export-bundle-contract.md](docs/export-bundle-contract.md).
 `examples/current_state_identity_consumers.py` provides an offline downstream
@@ -119,7 +122,7 @@ Included:
   workflows such as clip listing/download, screening preview, model/checkpoint
   registration, status queries, and capability discovery.
 - Strict validation of `x4d-training-identity-v1` manifests.
-- Strict producer-option and manifest parsing for export bundle `0.11`.
+- Strict producer-option and manifest parsing for export bundle `0.12`.
 - External inference service wrappers for third-party model-serving projects.
 
 Excluded:
@@ -233,7 +236,7 @@ comparison = compare_project_label_schema_snapshot(stored_snapshot, current)
 assert comparison.status == "same"
 ```
 
-The native `0.11` clip stores only the immutable identity in
+The native `0.12` clip stores only the immutable identity in
 `meta.label_schema`. It must not contain `label_schema.json`. The complete
 registry record is explicit runtime context for `ClipLoader`, `validate_clip`,
 conversion, and work-session parsing; its identity must exactly match
@@ -296,7 +299,6 @@ try:
     response = client.clip_work_sessions.submit_annotations(
         manifest=manifest,
         annotations=manifest.annotations,
-        instances=manifest.instances,
     )
     print(response["annotation_revision"])
 except WorkSessionConflictError as exc:

{x4d_devkit-0.22.0rc2 → x4d_devkit-0.23.0rc1}/README.md

@@ -23,7 +23,7 @@ Design decisions for this boundary are tracked in GitHub issues, starting with:
 ## Installation
 
 ```bash
-pip install x4d-devkit==0.22.0rc2
+pip install x4d-devkit==0.23.0rc1
 ```
 
 Devkit is released independently as an immutable wheel. X-4D, XPoints, and
@@ -62,7 +62,10 @@ validation boundary.
 Shared validation rules for platform submit, X-Points preflight, local clip
 validation, and training consumers are documented in
 [docs/shared-contract-validation.md](docs/shared-contract-validation.md).
-Portable export producers and consumers share the exact `0.11` manifest
+The Dataset 0.12 single-file annotation authority, semantic revision, and
+derived track views are documented in
+[docs/annotation-contract.md](docs/annotation-contract.md).
+Portable export producers and consumers share the exact `0.12` manifest
 parser documented in
 [docs/export-bundle-contract.md](docs/export-bundle-contract.md).
 `examples/current_state_identity_consumers.py` provides an offline downstream
@@ -76,7 +79,7 @@ Included:
   workflows such as clip listing/download, screening preview, model/checkpoint
   registration, status queries, and capability discovery.
 - Strict validation of `x4d-training-identity-v1` manifests.
-- Strict producer-option and manifest parsing for export bundle `0.11`.
+- Strict producer-option and manifest parsing for export bundle `0.12`.
 - External inference service wrappers for third-party model-serving projects.
 
 Excluded:
@@ -190,7 +193,7 @@ comparison = compare_project_label_schema_snapshot(stored_snapshot, current)
 assert comparison.status == "same"
 ```
 
-The native `0.11` clip stores only the immutable identity in
+The native `0.12` clip stores only the immutable identity in
 `meta.label_schema`. It must not contain `label_schema.json`. The complete
 registry record is explicit runtime context for `ClipLoader`, `validate_clip`,
 conversion, and work-session parsing; its identity must exactly match
@@ -253,7 +256,6 @@ try:
     response = client.clip_work_sessions.submit_annotations(
         manifest=manifest,
         annotations=manifest.annotations,
-        instances=manifest.instances,
     )
     print(response["annotation_revision"])
 except WorkSessionConflictError as exc:

{x4d_devkit-0.22.0rc2 → x4d_devkit-0.23.0rc1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.22.0rc2"
+version = "0.23.0rc1"
 description = "Official X-4D external SDK and CLI for datasets, platform APIs, training bridges, and automation"
 readme = "README.md"
 license = "Apache-2.0"

x4d_devkit-0.23.0rc1/tests/test_annotation_contract.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+import copy
+
+import pytest
+
+from x4d_devkit.annotation_contract import (
+    ANNOTATION_CONTRACT_VERSION,
+    AnnotationContractError,
+    annotation_revision,
+    build_clip_annotations,
+    derive_annotation_views,
+    parse_clip_annotations,
+)
+
+
+def _annotation(
+    token: str,
+    sample: str,
+    instance: str = "instance-0",
+    category: str = "car",
+) -> dict:
+    return {
+        "annotation_token": token,
+        "sample_token": sample,
+        "instance_token": instance,
+        "category": category,
+        "bbox_3d": {
+            "translation": {"x": 1.0, "y": 2.0, "z": 3.0},
+            "size": {"length": 4.0, "width": 2.0, "height": 1.5},
+            "rotation": {"qx": 0.0, "qy": 0.0, "qz": 0.0, "qw": 1.0},
+        },
+        "num_lidar_pts": 5,
+        "velocity": None,
+        "attributes": {},
+    }
+
+
+def _samples() -> list[dict]:
+    return [
+        {"sample_token": "sample-0", "timestamp_us": 100},
+        {"sample_token": "sample-1", "timestamp_us": 200},
+    ]
+
+
+def test_build_and_parse_annotation_document_is_canonical_and_order_independent():
+    later = _annotation("annotation-1", "sample-1")
+    earlier = _annotation("annotation-0", "sample-0")
+
+    first = build_clip_annotations("clip-0", [later, earlier])
+    second = build_clip_annotations("clip-0", [earlier, later])
+
+    assert first == second
+    assert first.annotation_revision == annotation_revision(
+        "clip-0", [later, earlier]
+    )
+    assert first.to_dict() == {
+        "contract_version": ANNOTATION_CONTRACT_VERSION,
+        "clip_id": "clip-0",
+        "annotation_revision": first.annotation_revision,
+        "annotations": [earlier, later],
+    }
+    assert parse_clip_annotations(first.to_dict()) == first
+
+
+@pytest.mark.parametrize(
+    ("mutation", "code"),
+    [
+        (lambda doc: doc.update(extra=True), "invalid_annotation_document"),
+        (
+            lambda doc: doc.update(contract_version="x4d-clip-annotations-v0"),
+            "invalid_annotation_contract_version",
+        ),
+        (
+            lambda doc: doc.update(annotation_revision="sha256:BAD"),
+            "invalid_annotation_revision",
+        ),
+        (
+            lambda doc: doc["annotations"][0].update(category="truck"),
+            "annotation_revision_mismatch",
+        ),
+        (
+            lambda doc: doc["annotations"].reverse(),
+            "noncanonical_annotation_order",
+        ),
+        (
+            lambda doc: doc["annotations"][0].update(prev=None),
+            "invalid_annotation_shape",
+        ),
+        (
+            lambda doc: doc["annotations"][0].pop("velocity"),
+            "invalid_annotation_shape",
+        ),
+    ],
+)
+def test_parse_annotation_document_fails_closed(mutation, code):
+    raw = build_clip_annotations(
+        "clip-0",
+        [
+            _annotation("annotation-0", "sample-0"),
+            _annotation("annotation-1", "sample-1"),
+        ],
+    ).to_dict()
+    mutation(raw)
+
+    with pytest.raises(AnnotationContractError) as exc:
+        parse_clip_annotations(raw)
+
+    assert exc.value.code == code
+
+
+def test_derive_annotation_views_uses_sample_time_not_input_order():
+    later = _annotation("annotation-a", "sample-1")
+    earlier = _annotation("annotation-z", "sample-0")
+
+    views = derive_annotation_views([later, earlier], _samples())
+    linked = {row["annotation_token"]: row for row in views.annotations}
+
+    assert linked["annotation-z"]["prev"] is None
+    assert linked["annotation-z"]["next"] == "annotation-a"
+    assert linked["annotation-a"]["prev"] == "annotation-z"
+    assert linked["annotation-a"]["next"] is None
+    assert views.instance_rows() == [
+        {
+            "instance_token": "instance-0",
+            "category": "car",
+            "num_annotations": 2,
+            "first_annotation_token": "annotation-z",
+            "last_annotation_token": "annotation-a",
+        }
+    ]
+
+
+def test_derive_annotation_views_returns_defensive_copies():
+    views = derive_annotation_views(
+        [_annotation("annotation-0", "sample-0")],
+        _samples(),
+    )
+    rows = views.annotation_rows()
+    rows[0]["category"] = "truck"
+
+    assert views.annotations[0]["category"] == "car"
+
+
+def test_annotation_documents_and_derived_views_are_recursively_immutable():
+    source = _annotation("annotation-0", "sample-0")
+    document = build_clip_annotations("clip-0", [source])
+    views = derive_annotation_views([source], _samples())
+
+    source["category"] = "truck"
+    assert document.annotations[0]["category"] == "car"
+    with pytest.raises(TypeError):
+        document.annotations[0]["bbox_3d"]["translation"]["x"] = 99.0
+    with pytest.raises(TypeError):
+        views.instances[0]["category"] = "truck"
+
+
+@pytest.mark.parametrize(
+    ("annotations", "samples", "code"),
+    [
+        (
+            [
+                _annotation("annotation-0", "sample-0"),
+                _annotation("annotation-1", "sample-1", category="truck"),
+            ],
+            _samples(),
+            "instance_category_mismatch",
+        ),
+        (
+            [_annotation("annotation-0", "missing")],
+            _samples(),
+            "annotation_sample_not_found",
+        ),
+        (
+            [
+                _annotation("annotation-0", "sample-0"),
+                _annotation("annotation-1", "sample-1"),
+            ],
+            [
+                {"sample_token": "sample-0", "timestamp_us": 100},
+                {"sample_token": "sample-1", "timestamp_us": 100},
+            ],
+            "ambiguous_instance_order",
+        ),
+    ],
+)
+def test_derive_annotation_views_rejects_ambiguous_tracks(
+    annotations, samples, code
+):
+    with pytest.raises(AnnotationContractError) as exc:
+        derive_annotation_views(copy.deepcopy(annotations), copy.deepcopy(samples))
+
+    assert exc.value.code == code

{x4d_devkit-0.22.0rc2 → x4d_devkit-0.23.0rc1}/tests/test_boundary.py

@@ -73,15 +73,19 @@ def test_top_level_exports_only_stable_sdk_surface():
 
     assert set(x4d_devkit.__all__) == {
         "__version__",
+        "ANNOTATION_CONTRACT_VERSION",
         "Annotation",
+        "AnnotationContractError",
         "AssetRef",
         "CalibratedSensor",
         "ClipContractValidationError",
+        "ClipAnnotationDocument",
         "ClipLoader",
         "ClipMeta",
         "ClipWorkSessionManifest",
         "COORDINATE_CONTRACT_VERSION",
         "EgoPose",
+        "DerivedAnnotationViews",
         "EXPORT_BUNDLE_SCHEMA_VERSION",
         "ExportBundleClip",
         "ExportBundleContractError",
@@ -101,12 +105,16 @@ def test_top_level_exports_only_stable_sdk_surface():
         "WorkSessionCompareResult",
         "X4DClient",
         "compare_work_session",
+        "annotation_revision",
+        "build_clip_annotations",
+        "derive_annotation_views",
         "generate_ego_pose_token",
         "generate_token",
         "get_build_info",
         "get_training_coordinate_contract",
         "materialize_work_session_clip",
         "parse_clip_work_session",
+        "parse_clip_annotations",
         "parse_export_bundle_manifest",
         "parse_export_options",
         "validate_clip",