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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.52.0rc2
+Version: 0.53.0rc2
 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.0rc2}/pyproject.toml

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

@@ -0,0 +1,161 @@
+"""Typed image Schema authoring against a strict in-memory registry."""
+
+from copy import deepcopy
+import hashlib
+import json
+
+import httpx
+import pytest
+
+from x4d_devkit import X4DClient
+from x4d_devkit._image_contract import canonical
+from x4d_devkit.image_schema import parse_image_schema_body
+from tests.image_fixtures import schema_body
+
+
+def etag(value):
+    return '"sha256:' + hashlib.sha256(canonical(value)).hexdigest() + '"'
+
+
+class Registry:
+    def __init__(self):
+        self.rows = {}
+        self.project = None
+        self.tamper = None
+
+    def record(self, body, status):
+        return {
+            "contract_version": "x4d-image-label-schema-record-v1",
+            "status": status,
+            "body": body,
+            "fingerprint": parse_image_schema_body(body).identity.fingerprint,
+        }
+
+    def reply(self, value, status=200):
+        if self.tamper:
+            value = self.tamper(deepcopy(value))
+        return httpx.Response(status, json=value, headers={"ETag": etag(value)})
+
+    def __call__(self, request):
+        path = request.url.path.removeprefix("/api/v1")
+        body = json.loads(request.content) if request.content else None
+        match = request.headers.get("If-Match")
+        if path == "/image-schemas/validate":
+            return httpx.Response(200, json=self.record(body["body"], "draft"))
+        if path == "/label-schemas" and request.method == "POST":
+            key = (body["body"]["schema_id"], body["body"]["version"])
+            self.rows[key] = self.record(body["body"], "draft")
+            return self.reply(self.rows[key], 201)
+        if path.startswith("/label-schemas/"):
+            _, _, schema_id, _, version, *action = path.split("/")
+            row = self.rows[(schema_id, version)]
+            if request.method == "GET":
+                return self.reply(row)
+            if match != etag(row):
+                return httpx.Response(412, json={"detail": "changed"})
+            if request.method == "DELETE":
+                del self.rows[(schema_id, version)]
+                return httpx.Response(204)
+            if action == ["publish"]:
+                row["status"] = "active"
+            elif action == ["deprecate"]:
+                row["status"] = "deprecated"
+            else:
+                row["body"] = body["body"]
+                row["fingerprint"] = parse_image_schema_body(body["body"]).identity.fingerprint
+            return self.reply(row)
+        if path == "/projects/7/label-schema":
+            if request.method == "PUT":
+                if match != etag(self.project):
+                    return httpx.Response(412, json={"detail": "changed"})
+                self.project = {**self.project, "label_schema": self.rows[(body["schema_id"], body["version"])]}
+            return self.reply(self.project)
+        raise AssertionError(path)
+
+
+@pytest.fixture
+def setup():
+    registry = Registry()
+    with X4DClient("http://x4d.test", token="test") as client:
+        client._http.close()
+        client._http = httpx.Client(base_url="http://x4d.test", transport=httpx.MockTransport(registry))
+        yield client.image_schemas, registry
+
+
+def draft_body(version="2.0.0"):
+    body = schema_body()
+    body["version"] = version
+    return body
+
+
+def test_draft_update_publish_and_bind_round_trip(setup):
+    api, registry = setup
+    body = draft_body()
+    assert api.validate(body).to_dict()["status"] == "draft"
+    entry = api.create_draft(body)
+    assert entry.record.to_dict()["status"] == "draft"
+    edited = deepcopy(body)
+    edited["description"] = "Edited draft"
+    entry = api.update_draft(edited, etag=entry.etag)
+    assert entry.record.body["description"] == "Edited draft"
+    assert api.get_entry(schema_id="test_image", version="2.0.0") == entry
+    entry = api.publish(entry)
+    assert entry.record.to_dict()["status"] == "active"
+    registry.project = {
+        "contract_version": "x4d-image-project-label-schema-v1",
+        "project_id": 7,
+        "label_schema": registry.record(schema_body(), "active"),
+    }
+    project = api.get_project_entry(7)
+    bound = api.bind_project(project, schema_id="test_image", version="2.0.0")
+    assert bound.value.to_dict()["label_schema"]["body"]["version"] == "2.0.0"
+    deprecated = api.deprecate(entry, reason="replaced")
+    assert deprecated.record.to_dict()["status"] == "deprecated"
+
+
+def test_stale_etag_is_rejected_by_the_server(setup):
+    api, _ = setup
+    first = api.create_draft(draft_body())
+    api.update_draft({**draft_body(), "description": "one"}, etag=first.etag)
+    with pytest.raises(httpx.HTTPStatusError):
+        api.update_draft({**draft_body(), "description": "two"}, etag=first.etag)
+
+
+def test_delete_draft_needs_the_current_etag(setup):
+    api, registry = setup
+    entry = api.create_draft(draft_body())
+    api.delete_draft(entry)
+    assert registry.rows == {}
+
+
+def test_invalid_body_never_reaches_the_server(setup):
+    api, registry = setup
+    body = draft_body()
+    body["categories"][0]["geometry_type"] = "circle"
+    with pytest.raises(ValueError):
+        api.create_draft(body)
+    assert registry.rows == {}
+
+
+@pytest.mark.parametrize("field", ["status", "body"])
+def test_a_response_for_another_record_or_lifecycle_is_rejected(setup, field):
+    api, registry = setup
+    entry = api.create_draft(draft_body())
+
+    def tamper(value):
+        if field == "status":
+            value["status"] = "draft"
+        else:
+            value["body"]["description"] = "something else"
+            value["fingerprint"] = parse_image_schema_body(value["body"]).identity.fingerprint
+        return value
+
+    registry.tamper = tamper
+    with pytest.raises(ValueError, match="another Schema"):
+        api.publish(entry)
+
+
+def test_a_weak_or_missing_etag_is_refused_locally(setup):
+    api, _ = setup
+    with pytest.raises(ValueError, match="strong ETag"):
+        api.update_draft(draft_body(), etag="W/\"x\"")

{x4d_devkit-0.52.0rc2 → x4d_devkit-0.53.0rc2}/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.0rc2"
 
 
 def test_loader_exposes_and_enforces_only_current_schema(tmp_path):

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

@@ -43,9 +43,15 @@ from x4d_devkit.client.reconstruction import (
 from x4d_devkit.client.services import ServicesAPI
 from x4d_devkit.client.test_sets import TestSetsAPI
 
-from x4d_devkit.client.image_schemas import ImageSchemasAPI
+from x4d_devkit.client.image_schemas import (
+    ImageProjectSchemaEntry,
+    ImageSchemaEntry,
+    ImageSchemasAPI,
+)
 
 __all__ = [
+    "ImageProjectSchemaEntry",
+    "ImageSchemaEntry",
     "ImageSchemasAPI",
     "ImageWorkSessionsAPI",
     "ImageExportsAPI",

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

@@ -173,6 +173,22 @@ class X4DClient:
         resp.raise_for_status()
         return parse_i_json(resp.content, path=f"POST {self._url(path)} response")
 
+    def put(self, path: str, **kwargs):
+        resp = self._http.put(self._url(path), **kwargs)
+        resp.raise_for_status()
+        return parse_i_json(resp.content, path=f"PUT {self._url(path)} response")
+
+    def exchange(self, method: str, path: str, **kwargs):
+        """One request returning ``(strict JSON or None for 204, ETag or None)``."""
+        resp = self._http.request(method, self._url(path), **kwargs)
+        resp.raise_for_status()
+        value = (
+            parse_i_json(resp.content, path=f"{method} {self._url(path)} response")
+            if resp.content
+            else None
+        )
+        return value, resp.headers.get("ETag")
+
     def delete(self, path: str, **kwargs):
         resp = self._http.delete(self._url(path), **kwargs)
         resp.raise_for_status()