x4d-devkit 0.48.0rc7__tar.gz → 0.48.0rc9__tar.gz

{x4d_devkit-0.48.0rc7 → x4d_devkit-0.48.0rc9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.48.0rc7
+Version: 0.48.0rc9
 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.48.0rc7 → x4d_devkit-0.48.0rc9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.48.0rc7"
+version = "0.48.0rc9"
 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.48.0rc7 → x4d_devkit-0.48.0rc9}/tests/test_image_clip.py

@@ -308,6 +308,40 @@ def test_typed_client_validates_metadata_then_reads_one_authorized_verified_imag
         assert len(requests) == 3
 
 
+@pytest.mark.parametrize("failure", [None, "source", "descriptor", "origin", "contract"])
+def test_reference_only_read_validates_context_without_requesting_media(failure):
+    value, requests = clip_payload(), []
+
+    def handler(request):
+        requests.append(request)
+        assert request.url.path.endswith("/images/image_a")
+        result = {
+            "contract_version": "x4d-image-asset-reference-v1",
+            "clip_id": "clip_test", "image_id": "image_a",
+            "source_revision": value["identity"]["source_revision"],
+            "asset": dict(value["sample_data"][0]["asset"]),
+            "uri": "/api/v1/files/clips/clip_test/samples/cam_a/10000000020.jpg",
+        }
+        if failure == "source":
+            result["source_revision"] = "sha256:" + "f" * 64
+        elif failure == "descriptor":
+            result["asset"]["size"] += 1
+        elif failure == "origin":
+            result["uri"] = "https://untrusted.example/api/v1/files/private"
+        elif failure == "contract":
+            result["contract_version"] = "other"
+        return httpx.Response(200, json=result)
+
+    with client_for(handler) as client:
+        clip = parse_image_clip(value)
+        if failure:
+            with pytest.raises(ValueError):
+                client.image_clips.get_asset(clip, "image_a")
+        else:
+            assert client.image_clips.get_asset(clip, "image_a")["asset"] == clip.images[0]["asset"]
+        assert len(requests) == 1
+
+
 @pytest.mark.parametrize(
     "failure",
     [

x4d_devkit-0.48.0rc9/tests/test_image_schema_upgrade.py

@@ -0,0 +1,239 @@
+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 (
+    parse_image_schema_body,
+    parse_image_schema_record,
+    build_image_schema_snapshot,
+)
+from x4d_devkit.image_schema_upgrade import (
+    RECEIPT_CONTRACT,
+    additive_image_schema_changes,
+    image_schema_upgrade_candidate,
+    build_image_schema_upgrade_preview,
+    build_image_schema_upgrade_request,
+    parse_image_schema_upgrade_preview,
+    parse_image_schema_upgrade_request,
+    parse_image_schema_upgrade_receipt,
+)
+from tests.image_fixtures import clip_payload, line_object
+
+
+def target(clip):
+    body = deepcopy(clip["label_schema"]["body"])
+    body["version"] = "1.1.0"
+    body["categories"][0]["attributes"].append(
+        {
+            "id": "optional",
+            "display_name": "Optional",
+            "type": "boolean",
+            "required": False,
+            "scopes": ["object", "segment"],
+            "values": [],
+        }
+    )
+    for category in body["categories"]:
+        for attribute in category["attributes"]:
+            if attribute["type"] == "enum":
+                attribute["values"].append({"id": "extra", "display_name": "Extra"})
+    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 test_additive_upgrade_preserves_complete_human_geometry_ranges_and_completion():
+    clip = clip_payload()
+    clip["image_annotation"]["objects"] = [line_object()]
+    clip["identity"] = build_image_identity(clip)
+    snapshot = target(clip)
+    candidate = image_schema_upgrade_candidate(clip, snapshot).to_dict()
+    assert all(
+        candidate[key] == clip[key]
+        for key in clip
+        if key not in {"label_schema", "identity"}
+    )
+    assert (
+        candidate["identity"]["source_revision"] == clip["identity"]["source_revision"]
+    )
+    assert (
+        candidate["identity"]["annotation_revision"]
+        == clip["identity"]["annotation_revision"]
+    )
+    assert (
+        candidate["identity"]["schema_fingerprint"]
+        != clip["identity"]["schema_fingerprint"]
+    )
+    assert "optional" not in candidate["image_annotation"]["objects"][0]["attributes"]
+    preview = build_image_schema_upgrade_preview(clip, snapshot)
+    assert (
+        parse_image_schema_upgrade_preview(preview.to_dict()).to_dict()
+        == preview.to_dict()
+    )
+    request = build_image_schema_upgrade_request(preview, "explicit-test-key")
+    assert (
+        parse_image_schema_upgrade_request(request.to_dict()).to_dict()
+        == request.to_dict()
+    )
+
+
+@pytest.mark.parametrize(
+    "change",
+    [
+        "same-version",
+        "backwards",
+        "schema-id",
+        "category",
+        "geometry",
+        "view",
+        "attribute-remove",
+        "required",
+        "scope",
+        "enum-meaning",
+        "new-required",
+    ],
+)
+def test_incompatible_reinterpretations_require_a_separate_migration(change):
+    clip = clip_payload()
+    old, new = clip["label_schema"]["body"], target(clip)["body"]
+    if change == "same-version":
+        new["version"] = old["version"]
+    if change == "backwards":
+        new["version"] = "0.1.0"
+    if change == "schema-id":
+        new["schema_id"] = "another"
+    if change == "category":
+        new["categories"].pop()
+    if change == "geometry":
+        new["categories"][0]["geometry_type"] = "box_2d"
+    if change == "view":
+        new["task_views"][0]["display_name"] = "Reinterpreted"
+    if change == "attribute-remove":
+        new["categories"][0]["attributes"].pop(0)
+    if change == "required":
+        new["categories"][0]["attributes"][0]["required"] = True
+    if change == "scope":
+        new["categories"][0]["attributes"][0]["scopes"] = ["object"]
+    if change == "enum-meaning":
+        new["categories"][0]["attributes"][1]["values"][0]["display_name"] = (
+            "Different meaning"
+        )
+    if change == "new-required":
+        new["categories"][0]["attributes"][-1]["required"] = True
+    with pytest.raises(ValueError):
+        additive_image_schema_changes(old, new)
+
+
+@pytest.mark.parametrize(
+    "part",
+    ["digest", "source", "human", "schema", "changes", "foreign-clip", "unknown-field"],
+)
+def test_preview_rejects_tampered_transition_even_with_recomputed_fingerprint(part):
+    clip = clip_payload()
+    value = build_image_schema_upgrade_preview(clip, target(clip)).to_dict()
+    if part == "source":
+        value["after_identity"]["components"]["sample"] = "sha256:" + "a" * 64
+    if part == "human":
+        value["after_identity"]["annotation_revision"] = "sha256:" + "a" * 64
+    if part == "schema":
+        value["target_schema"]["body"]["version"] = "1.2.0"
+    if part == "changes":
+        value["changes"]["added_attributes"] = []
+    if part == "foreign-clip":
+        value["after_identity"]["clip_id"] = "foreign"
+    if part == "unknown-field":
+        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_upgrade_preview(value)
+
+
+def test_typed_image_schema_reads_and_upgrade_verify_the_exact_request():
+    clip = clip_payload()
+    snapshot = target(clip)
+    preview = build_image_schema_upgrade_preview(clip, snapshot).to_dict()
+    record = {
+        "contract_version": "x4d-image-label-schema-record-v1",
+        "status": "active",
+        "body": snapshot["body"],
+        "fingerprint": snapshot["identity"]["fingerprint"],
+    }
+    requests, bad = [], {"enabled": False}
+
+    def handler(request):
+        requests.append(request)
+        path = request.url.path
+        if path == "/api/v1/label-schemas":
+            assert request.url.params["project_type"] == "2d"
+            return httpx.Response(200, json={"items": [record], "total": 1})
+        if path == "/api/v1/projects/7/label-schema":
+            return httpx.Response(
+                200,
+                json={
+                    "contract_version": "x4d-image-project-label-schema-v1",
+                    "project_id": 7,
+                    "label_schema": record,
+                },
+            )
+        if path.startswith("/api/v1/label-schemas/"):
+            return httpx.Response(200, json=record)
+        if path.endswith("/preview"):
+            assert json.loads(request.content) == {
+                "project_id": 7,
+                "clip_id": "clip_test",
+                "target_schema": snapshot["identity"],
+            }
+            return httpx.Response(200, json=preview)
+        body = json.loads(request.content)
+        receipt = {
+            "contract_version": RECEIPT_CONTRACT,
+            "project_id": 7,
+            "clip_id": "clip_test",
+            "idempotency_key": body["idempotency_key"],
+            "preview_fingerprint": preview["preview_fingerprint"],
+            "identity": preview["after_identity"],
+            "changed": True,
+        }
+        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)
+        )
+        assert client.image_schemas.list()["total"] == 1
+        assert (
+            client.image_schemas.get(
+                schema_id=snapshot["identity"]["schema_id"], version="1.1.0"
+            ).body
+            == snapshot["body"]
+        )
+        assert client.image_schemas.get_project(7).to_dict()["project_id"] == 7
+        parsed = client.image_schemas.preview_upgrade(clip=clip, target_schema=snapshot)
+        request = client.image_schemas.upgrade_request(parsed, "explicit-request")
+        receipt = client.image_schemas.commit_upgrade(request)
+        assert (
+            parse_image_schema_upgrade_receipt(receipt.to_dict()).to_dict()["identity"]
+            == preview["after_identity"]
+        )
+        bad["enabled"] = True
+        with pytest.raises(ValueError, match="another request"):
+            client.image_schemas.commit_upgrade(request)

{x4d_devkit-0.48.0rc7 → x4d_devkit-0.48.0rc9}/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.48.0rc7"
+    assert x4d_devkit.__version__ == "0.48.0rc9"
 
 
 def test_loader_exposes_and_enforces_only_current_schema(tmp_path):

{x4d_devkit-0.48.0rc7 → x4d_devkit-0.48.0rc9}/x4d_devkit/client/__init__.py

@@ -42,7 +42,10 @@ 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
+
 __all__ = [
+    "ImageSchemasAPI",
     "ImageWorkSessionsAPI",
     "ImageExportsAPI",
     "CleanBasemapState",

{x4d_devkit-0.48.0rc7 → x4d_devkit-0.48.0rc9}/x4d_devkit/client/client.py

@@ -28,6 +28,7 @@ from x4d_devkit.client.image_clips import ImageClipsAPI
 from x4d_devkit.client.image_work_sessions import ImageWorkSessionsAPI
 from x4d_devkit.client.image_preannotations import ImagePreannotationsAPI
 from x4d_devkit.client.image_exports import ImageExportsAPI
+from x4d_devkit.client.image_schemas import ImageSchemasAPI
 from x4d_devkit.client.semantic_scene import SemanticSceneAPI
 from x4d_devkit.client.semantic_scene_authoring import (
     SemanticSceneAuthoringWorkSessionsAPI,
@@ -80,6 +81,7 @@ class X4DClient:
         self.image_work_sessions = ImageWorkSessionsAPI(self)
         self.image_preannotations = ImagePreannotationsAPI(self)
         self.image_exports = ImageExportsAPI(self)
+        self.image_schemas = ImageSchemasAPI(self)
         self.label_schemas = LabelSchemasAPI(self)
         self.semantic_scene = SemanticSceneAPI(self)
         self.semantic_scene_authoring_work_sessions = (

{x4d_devkit-0.48.0rc7 → x4d_devkit-0.48.0rc9}/x4d_devkit/client/image_clips.py

@@ -7,6 +7,7 @@ from urllib.parse import quote
 
 from x4d_devkit._image_contract import fields, identifier, integer, require
 from x4d_devkit.client.assets import PlatformAsset
+from x4d_devkit.client.assets import _validated_file_uri
 from x4d_devkit.image_clip import ImageClip, parse_image_clip
 
 
@@ -47,22 +48,15 @@ class ImageClipsAPI:
         value = self._client.get(f"/image-clips/{quote(clip_id, safe='')}")
         return parse_image_clip(value, expected_clip_id=clip_id)
 
-    def read_image(
-        self, clip: ImageClip, image_id: str, *, max_bytes: int = 32 * 1024 * 1024
-    ) -> PlatformAsset:
+    def get_asset(self, clip: ImageClip, image_id: str) -> dict:
+        """Validate an authorized reference without downloading original bytes."""
         require(
             type(clip) is ImageClip, "expected a validated native image Clip", "clip"
         )
         identifier(image_id, "image_id")
-        integer(max_bytes, "max_bytes", minimum=1)
         image = next((item for item in clip.images if item["id"] == image_id), None)
         require(image is not None, "image does not belong to this Clip", "image_id")
         expected = image["asset"]
-        require(
-            expected["size"] <= max_bytes,
-            "image exceeds the configured read budget",
-            "image.asset.size",
-        )
         value = self._client.get(
             f"/image-clips/{quote(clip.clip_id, safe='')}/images/{quote(image_id, safe='')}"
         )
@@ -82,12 +76,33 @@ class ImageClipsAPI:
             value["contract_version"] == IMAGE_ASSET_REFERENCE_VERSION
             and value["clip_id"] == clip.clip_id
             and value["image_id"] == image_id
-            and value["source_revision"]
-            == clip.to_dict()["identity"]["source_revision"]
             and value["asset"] == expected,
             "image asset context changed",
             "image_asset",
         )
+        require(
+            value["source_revision"] == clip.to_dict()["identity"]["source_revision"],
+            "image source revision changed",
+            "image_asset.source_revision",
+        )
+        _validated_file_uri(value["uri"], api_url=self._client.api_url)
+        return value
+
+    def read_image(
+        self, clip: ImageClip, image_id: str, *, max_bytes: int = 32 * 1024 * 1024
+    ) -> PlatformAsset:
+        require(type(clip) is ImageClip, "expected a validated native image Clip", "clip")
+        identifier(image_id, "image_id")
+        integer(max_bytes, "max_bytes", minimum=1)
+        image = next((item for item in clip.images if item["id"] == image_id), None)
+        require(image is not None, "image does not belong to this Clip", "image_id")
+        expected = image["asset"]
+        require(
+            expected["size"] <= max_bytes,
+            "image exceeds the configured read budget",
+            "image.asset.size",
+        )
+        value = self.get_asset(clip, image_id)
         asset = self._client.assets.fetch(value["uri"], max_bytes=expected["size"])
         require(
             len(asset.content) == expected["size"]

x4d_devkit-0.48.0rc9/x4d_devkit/client/image_schemas.py

@@ -0,0 +1,115 @@
+"""Separate native image registry reads and explicit admin upgrade adapters."""
+
+from x4d_devkit._image_contract import fields, integer, require
+from x4d_devkit.image_schema import (
+    parse_image_schema_record,
+    parse_image_project_schema,
+)
+from x4d_devkit.image_schema_upgrade import (
+    build_image_schema_upgrade_preview,
+    build_image_schema_upgrade_request,
+    parse_image_schema_upgrade_preview,
+    parse_image_schema_upgrade_request,
+    parse_image_schema_upgrade_receipt,
+)
+from x4d_devkit.label_schema import LabelSchemaBinding
+
+
+class ImageSchemasAPI:
+    def __init__(self, client):
+        self._client = client
+
+    def list(self, *, status=None):
+        params = {"project_type": "2d"}
+        if status is not None:
+            require(
+                status in ("draft", "active", "deprecated"),
+                "Invalid lifecycle filter",
+                "image_schemas.status",
+            )
+            params["status"] = status
+        value = self._client.get("/label-schemas", params=params)
+        fields(value, {"items", "total"}, "image_schemas")
+        require(
+            type(value["items"]) is list,
+            "Expected explicit records",
+            "image_schemas.items",
+        )
+        integer(value["total"], "image_schemas.total")
+        records = [parse_image_schema_record(row) for row in value["items"]]
+        require(
+            value["total"] == len(records)
+            and len({(row.schema_id, row.version) for row in records}) == len(records),
+            "Inconsistent registry list",
+            "image_schemas",
+        )
+        return {
+            "items": [record.to_dict() for record in records],
+            "total": len(records),
+        }
+
+    def get(self, *, schema_id, version):
+        LabelSchemaBinding(schema_id, version)
+        record = parse_image_schema_record(
+            self._client.get(f"/label-schemas/{schema_id}/versions/{version}")
+        )
+        require(
+            (record.schema_id, record.version) == (schema_id, version),
+            "Registry returned another Schema",
+            "image_schemas.identity",
+        )
+        return record
+
+    def get_project(self, project_id):
+        integer(project_id, "project_id", minimum=1)
+        value = parse_image_project_schema(
+            self._client.get(f"/projects/{project_id}/label-schema")
+        )
+        require(
+            value.to_dict()["project_id"] == project_id,
+            "Registry returned another project",
+            "image_schemas.project_id",
+        )
+        return value
+
+    def preview_upgrade(self, *, clip, target_schema):
+        expected = build_image_schema_upgrade_preview(clip, target_schema).to_dict()
+        result = parse_image_schema_upgrade_preview(
+            self._client.post(
+                "/image-schema-upgrades/preview",
+                json={
+                    "project_id": expected["project_id"],
+                    "clip_id": expected["clip_id"],
+                    "target_schema": target_schema["identity"],
+                },
+            )
+        )
+        require(
+            result.to_dict() == expected,
+            "Upgrade preview differs from the exact Clip and target",
+            "image_schemas.preview",
+        )
+        return result
+
+    def commit_upgrade(self, request):
+        body = parse_image_schema_upgrade_request(
+            request.to_dict() if hasattr(request, "to_dict") else request
+        ).to_dict()
+        result = parse_image_schema_upgrade_receipt(
+            self._client.post("/image-schema-upgrades/commit", json=body)
+        )
+        value, preview = result.to_dict(), body["preview"]
+        require(
+            all(
+                value[key] == preview[key]
+                for key in ("project_id", "clip_id", "preview_fingerprint")
+            )
+            and value["idempotency_key"] == body["idempotency_key"]
+            and value["identity"] == preview["after_identity"],
+            "Upgrade receipt belongs to another request",
+            "image_schemas.receipt",
+        )
+        return result
+
+    def upgrade_request(self, preview, idempotency_key):
+        return build_image_schema_upgrade_request(preview, idempotency_key)