x4d-devkit 0.52.0rc2__tar.gz → 0.53.0rc1__tar.gz

{x4d_devkit-0.52.0rc2 → x4d_devkit-0.53.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.52.0rc2
+Version: 0.53.0rc1
 Summary: Official X-4D external SDK and CLI for datasets, platform APIs, training bridges, and automation
 Author: windzu
 License-Expression: Apache-2.0

{x4d_devkit-0.52.0rc2 → x4d_devkit-0.53.0rc1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.52.0rc2"
+version = "0.53.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.53.0rc1/tests/test_image_schema_migration.py

@@ -0,0 +1,283 @@
+from copy import deepcopy
+import json
+
+import httpx
+import pytest
+
+from x4d_devkit import X4DClient
+from x4d_devkit._image_contract import fingerprint
+from x4d_devkit.image_clip import build_image_identity
+from x4d_devkit.image_schema import (
+    build_image_schema_snapshot,
+    parse_image_schema_body,
+    parse_image_schema_record,
+)
+from x4d_devkit.image_schema_migration import (
+    MAPPING_CONTRACT,
+    ImageSchemaMigrationConflict,
+    build_image_schema_migration_preview,
+    build_image_schema_migration_receipt,
+    build_image_schema_migration_request,
+    image_schema_migration_candidate,
+    migrate_image_annotation,
+    parse_image_schema_migration_mapping,
+    parse_image_schema_migration_preview,
+    parse_image_schema_migration_request,
+)
+from x4d_devkit.image_schema_upgrade import additive_image_schema_changes
+from tests.image_fixtures import clip_payload, line_object
+
+
+def snapshot(body):
+    return build_image_schema_snapshot(
+        parse_image_schema_record(
+            {
+                "contract_version": "x4d-image-label-schema-record-v1",
+                "status": "active",
+                "body": body,
+                "fingerprint": parse_image_schema_body(body).identity.fingerprint,
+            }
+        )
+    )
+
+
+def target(clip, **changes):
+    """Non-additive 2.0.0: whole-line `visible` becomes segment `occluded`,
+    `style` becomes object-only `pattern`, and lines become groupable."""
+    body = deepcopy(clip["label_schema"]["body"])
+    body["version"] = changes.get("version", "2.0.0")
+    body["schema_id"] = changes.get("schema_id", body["schema_id"])
+    line = body["categories"][0]
+    line["groupable"] = True
+    line["attributes"] = [
+        {
+            "id": "occluded",
+            "display_name": "Occluded",
+            "type": "boolean",
+            "required": False,
+            "scopes": ["segment"],
+            "values": [],
+        },
+        {
+            "id": "pattern",
+            "display_name": "Pattern",
+            "type": "enum",
+            "required": False,
+            "scopes": ["object"],
+            "values": [
+                {"id": "a", "display_name": "A"},
+                {"id": "b", "display_name": "B"},
+            ],
+        },
+    ]
+    return snapshot(body)
+
+
+def mapping(*rules):
+    return {"contract_version": MAPPING_CONTRACT, "rules": list(rules)}
+
+
+def rule(scope, attribute_id, value, action):
+    return {
+        "match": {
+            "category_id": "line",
+            "scope": scope,
+            "attribute_id": attribute_id,
+            "value": value,
+        },
+        "action": action,
+    }
+
+
+def with_line(obj=None):
+    clip = clip_payload()
+    clip["image_annotation"]["objects"] = [obj or line_object()]
+    clip["identity"] = build_image_identity(clip)
+    return clip
+
+
+VISIBLE_TO_RANGE = rule(
+    "object", "visible", False, {"kind": "range", "attribute_id": "occluded", "value": True}
+)
+DISCARD_STYLE = rule("segment", "style", "a", {"kind": "discard"})
+
+
+def test_target_is_not_an_additive_upgrade():
+    clip = with_line()
+    with pytest.raises(ValueError):
+        additive_image_schema_changes(clip["label_schema"]["body"], target(clip)["body"])
+
+
+def test_unused_vocabulary_needs_no_rule_and_keeps_the_annotation_bytes():
+    clip = with_line({**line_object(), "attributes": {}, "attribute_ranges": []})
+    candidate, report = image_schema_migration_candidate(clip, target(clip), mapping())
+    result = candidate.to_dict()
+    assert result["image_annotation"] == clip["image_annotation"]
+    assert result["identity"]["annotation_revision"] == clip["identity"]["annotation_revision"]
+    assert result["identity"]["source_revision"] == clip["identity"]["source_revision"]
+    assert result["identity"]["schema_fingerprint"] != clip["identity"]["schema_fingerprint"]
+    assert report == {"changes": [], "removed_ranges": [], "rule_usage": [], "carried_values": 0}
+
+
+def test_every_unrepresentable_occurrence_is_listed_with_its_location():
+    clip = with_line()
+    with pytest.raises(ImageSchemaMigrationConflict) as caught:
+        image_schema_migration_candidate(clip, target(clip), mapping())
+    assert [
+        (row["code"], row["object_id"], row["range_id"], row["attribute_id"], row["value"])
+        for row in caught.value.conflicts
+    ] == [
+        ("value_unmapped", "line_a", None, "visible", False),
+        ("value_unmapped", "line_a", "r0", "style", "a"),
+    ]
+    assert caught.value.details["conflicts"] == caught.value.conflicts
+
+
+def test_explicit_rules_convert_and_discard_while_preserving_identity_and_geometry():
+    clip = with_line()
+    rules = mapping(VISIBLE_TO_RANGE, DISCARD_STYLE)
+    candidate, report = image_schema_migration_candidate(clip, target(clip), rules)
+    result = candidate.to_dict()
+    before, after = clip["image_annotation"]["objects"][0], result["image_annotation"]["objects"][0]
+    assert {k: v for k, v in after.items() if k not in ("attributes", "attribute_ranges")} == {
+        k: v for k, v in before.items() if k not in ("attributes", "attribute_ranges")
+    }
+    assert after["attributes"] == {}
+    [added] = after["attribute_ranges"]
+    assert added["start_vertex_id"] == "p0" and added["end_vertex_id"] == "p1"
+    assert added["attributes"] == {"occluded": True}
+    assert report["removed_ranges"] == [{"object_id": "line_a", "range_id": "r0"}]
+    assert report["rule_usage"] == [1, 1]
+    assert [(c["kind"], c["before"], c["after"]) for c in report["changes"]] == [
+        ("range", False, {"attribute_id": "occluded", "value": True}),
+        ("discard", "a", None),
+    ]
+    for name in ("meta", "sample", "sample_data", "calibrated_sensor"):
+        assert result[name] == clip[name]
+    again, _ = image_schema_migration_candidate(clip, target(clip), rules)
+    assert again.to_dict() == result  # deterministic range IDs
+
+
+def test_draft_annotations_migrate_with_the_same_function():
+    clip = with_line()
+    draft, report = migrate_image_annotation(
+        clip["image_annotation"],
+        target_schema=target(clip)["body"],
+        mapping=mapping(VISIBLE_TO_RANGE, DISCARD_STYLE),
+    )
+    full, _ = image_schema_migration_candidate(
+        clip, target(clip), mapping(VISIBLE_TO_RANGE, DISCARD_STYLE)
+    )
+    assert draft == full.to_dict()["image_annotation"]
+    assert report["rule_usage"] == [1, 1]
+
+
+def test_a_mapped_value_must_be_valid_in_the_target_scope():
+    clip = with_line()
+    bad = rule("segment", "style", "a", {"kind": "set", "attribute_id": "pattern", "value": "a"})
+    with pytest.raises(ImageSchemaMigrationConflict) as caught:
+        image_schema_migration_candidate(clip, target(clip), mapping(VISIBLE_TO_RANGE, bad))
+    assert [row["code"] for row in caught.value.conflicts] == ["mapped_value_invalid"]
+
+
+def test_two_values_cannot_land_on_the_same_attribute():
+    obj = {**line_object(), "attributes": {"visible": False, "style": "b"}, "attribute_ranges": []}
+    clip = with_line(obj)
+    rules = mapping(
+        rule("object", "visible", False, {"kind": "set", "attribute_id": "pattern", "value": "a"}),
+        rule("object", "style", "b", {"kind": "set", "attribute_id": "pattern", "value": "b"}),
+    )
+    with pytest.raises(ImageSchemaMigrationConflict) as caught:
+        image_schema_migration_candidate(clip, target(clip), rules)
+    assert [row["code"] for row in caught.value.conflicts] == ["attribute_collision"]
+
+
+@pytest.mark.parametrize(
+    "rules",
+    [
+        [VISIBLE_TO_RANGE, VISIBLE_TO_RANGE],
+        [rule("segment", "style", "a", {"kind": "range", "attribute_id": "occluded", "value": True})],
+        [rule("object", "visible", False, {"kind": "rename"})],
+        [rule("object", "visible", False, {"kind": "discard", "attribute_id": "x"})],
+        [rule("image", "visible", False, {"kind": "discard"})],
+        [rule("object", "visible", 3, {"kind": "discard"})],
+    ],
+)
+def test_mapping_grammar_is_closed(rules):
+    with pytest.raises(ValueError):
+        parse_image_schema_migration_mapping(mapping(*rules))
+
+
+@pytest.mark.parametrize("change", [{"schema_id": "another"}, {"version": "1.0.0"}])
+def test_migration_keeps_the_schema_id_and_advances_the_version(change):
+    clip = with_line({**line_object(), "attributes": {}, "attribute_ranges": []})
+    with pytest.raises(ValueError):
+        image_schema_migration_candidate(clip, target(clip, **change), mapping())
+
+
+@pytest.mark.parametrize("part", ["digest", "source", "report", "usage", "mapping", "unknown"])
+def test_preview_rejects_tampering_even_with_a_recomputed_fingerprint(part):
+    clip = with_line()
+    value = build_image_schema_migration_preview(
+        clip, target(clip), mapping(VISIBLE_TO_RANGE, DISCARD_STYLE)
+    ).to_dict()
+    if part == "source":
+        value["after_identity"]["components"]["sample"] = "sha256:" + "a" * 64
+    if part == "report":
+        value["report"]["changes"] = []
+        value["report"]["removed_ranges"] = []
+        value["report"]["rule_usage"] = [0, 0]
+    if part == "usage":
+        value["report"]["rule_usage"] = [1]
+    if part == "mapping":
+        value["mapping"]["rules"].append(VISIBLE_TO_RANGE)
+    if part == "unknown":
+        value["automatic_repair"] = True
+    value["preview_fingerprint"] = (
+        "sha256:" + "0" * 64
+        if part == "digest"
+        else fingerprint({k: v for k, v in value.items() if k != "preview_fingerprint"})
+    )
+    with pytest.raises(ValueError):
+        parse_image_schema_migration_preview(value)
+
+
+def test_typed_client_verifies_the_exact_preview_and_receipt():
+    clip = with_line()
+    snap = target(clip)
+    rules = mapping(VISIBLE_TO_RANGE, DISCARD_STYLE)
+    preview = build_image_schema_migration_preview(clip, snap, rules).to_dict()
+    bad = {"enabled": False}
+
+    def handler(request):
+        body = json.loads(request.content)
+        if request.url.path.endswith("/image-schema-migrations/preview"):
+            assert body == {
+                "project_id": 7,
+                "clip_id": "clip_test",
+                "target_schema": snap["identity"],
+                "mapping": rules,
+            }
+            return httpx.Response(200, json=preview)
+        assert request.url.path.endswith("/image-schema-migrations/commit")
+        receipt = build_image_schema_migration_receipt(body).to_dict()
+        if bad["enabled"]:
+            receipt["idempotency_key"] = "other-request"
+        return httpx.Response(200, json=receipt)
+
+    with X4DClient("http://x4d.test", token="test") as client:
+        client._http.close()
+        client._http = httpx.Client(
+            base_url="http://x4d.test", transport=httpx.MockTransport(handler)
+        )
+        parsed = client.image_schemas.preview_migration(
+            clip=clip, target_schema=snap, mapping=rules
+        )
+        request = client.image_schemas.migration_request(parsed, "explicit-migration")
+        assert parse_image_schema_migration_request(request.to_dict())
+        receipt = client.image_schemas.commit_migration(request).to_dict()
+        assert receipt["identity"] == preview["after_identity"]
+        bad["enabled"] = True
+        with pytest.raises(ValueError, match="another request"):
+            client.image_schemas.commit_migration(request)
+    assert build_image_schema_migration_request(parsed, "k").to_dict()["preview"] == preview

{x4d_devkit-0.52.0rc2 → x4d_devkit-0.53.0rc1}/tests/test_sdk_api.py

@@ -11,7 +11,7 @@ from x4d_devkit.eval.matching import MetricData
 
 
 def test_package_version_is_current_release():
-    assert x4d_devkit.__version__ == "0.52.0rc2"
+    assert x4d_devkit.__version__ == "0.53.0rc1"
 
 
 def test_loader_exposes_and_enforces_only_current_schema(tmp_path):

{x4d_devkit-0.52.0rc2 → x4d_devkit-0.53.0rc1}/x4d_devkit/client/image_schemas.py

@@ -1,4 +1,4 @@
-"""Separate native image registry reads and explicit admin upgrade adapters."""
+"""Separate native image registry reads and explicit admin upgrade/migration adapters."""
 
 from x4d_devkit._image_contract import fields, integer, require
 from x4d_devkit.image_schema import (
@@ -12,6 +12,14 @@ from x4d_devkit.image_schema_upgrade import (
     parse_image_schema_upgrade_request,
     parse_image_schema_upgrade_receipt,
 )
+from x4d_devkit.image_schema_migration import (
+    build_image_schema_migration_preview,
+    build_image_schema_migration_receipt,
+    build_image_schema_migration_request,
+    parse_image_schema_migration_preview,
+    parse_image_schema_migration_receipt,
+    parse_image_schema_migration_request,
+)
 from x4d_devkit.label_schema import LabelSchemaBinding
 
 
@@ -113,3 +121,43 @@ class ImageSchemasAPI:
 
     def upgrade_request(self, preview, idempotency_key):
         return build_image_schema_upgrade_request(preview, idempotency_key)
+
+    def preview_migration(self, *, clip, target_schema, mapping):
+        """Server preview must equal the locally computed exact migration."""
+        expected = build_image_schema_migration_preview(
+            clip, target_schema, mapping
+        ).to_dict()
+        result = parse_image_schema_migration_preview(
+            self._client.post(
+                "/image-schema-migrations/preview",
+                json={
+                    "project_id": expected["project_id"],
+                    "clip_id": expected["clip_id"],
+                    "target_schema": target_schema["identity"],
+                    "mapping": expected["mapping"],
+                },
+            )
+        )
+        require(
+            result.to_dict() == expected,
+            "Migration preview differs from the exact Clip, target and mapping",
+            "image_schemas.migration_preview",
+        )
+        return result
+
+    def commit_migration(self, request):
+        body = parse_image_schema_migration_request(
+            request.to_dict() if hasattr(request, "to_dict") else request
+        ).to_dict()
+        result = parse_image_schema_migration_receipt(
+            self._client.post("/image-schema-migrations/commit", json=body)
+        )
+        require(
+            result.to_dict() == build_image_schema_migration_receipt(body).to_dict(),
+            "Migration receipt belongs to another request",
+            "image_schemas.migration_receipt",
+        )
+        return result
+
+    def migration_request(self, preview, idempotency_key):
+        return build_image_schema_migration_request(preview, idempotency_key)