x4d-devkit 0.48.0rc2__tar.gz → 0.48.0rc3__tar.gz

{x4d_devkit-0.48.0rc2 → x4d_devkit-0.48.0rc3}/PKG-INFO

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

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

@@ -0,0 +1,267 @@
+import copy
+
+import pytest
+
+import hashlib
+
+from tests.image_fixtures import (
+    IMAGE_BYTES as FIXTURE_BYTES,
+    clip_payload as base_clip_payload,
+    line_object,
+)
+from x4d_devkit.image_clip import build_image_identity, parse_image_clip
+from x4d_devkit.image_reference import (
+    IMAGE_INFERENCE_PROTOCOL,
+    IMAGE_REFERENCE_CONTRACT,
+    build_image_model_profile,
+    build_image_prediction_input,
+    image_reference_source,
+    parse_image_model_profile,
+    parse_image_prediction,
+    parse_image_prediction_input,
+    parse_image_reference,
+    parse_image_reference_source,
+)
+
+
+IMAGE_BYTES = b"\xff\xd8\xff" + FIXTURE_BYTES
+
+
+def clip_payload():
+    value = base_clip_payload()
+    value["sample_data"][0]["asset"].update(
+        size=len(IMAGE_BYTES), sha256=hashlib.sha256(IMAGE_BYTES).hexdigest()
+    )
+    value["identity"] = build_image_identity(value)
+    return value
+
+
+def profile():
+    return build_image_model_profile(
+        {
+            "model_name": "test",
+            "model_version": "1",
+            "artifact": {
+                "bucket": "models",
+                "object_key": "enet/1.tar.gz",
+                "object_version": None,
+                "archive_sha256": "a" * 64,
+                "weights_sha256": "b" * 64,
+            },
+            "adapter": "test-v1",
+            "parameters": {},
+            "runtime": "cpu-test",
+        }
+    )
+
+
+def source():
+    return image_reference_source(parse_image_clip(clip_payload()))
+
+
+def request():
+    return build_image_prediction_input(
+        source(),
+        image_id="image_a",
+        view_id="objects",
+        profile_id=profile().to_dict()["profile_id"],
+        image_bytes=IMAGE_BYTES,
+    )
+
+
+def artifact():
+    return {
+        "contract_version": IMAGE_REFERENCE_CONTRACT,
+        "run_id": "ref_1",
+        "source": source().to_dict(),
+        "profile": profile().to_dict(),
+        "view_id": "objects",
+        "coverage": [
+            {
+                "image_id": "image_a",
+                "status": "predicted",
+                "objects": [line_object()],
+                "error": None,
+            }
+        ],
+    }
+
+
+def test_source_and_prediction_never_include_human_data_or_its_revision():
+    value = clip_payload()
+    value["image_annotation"]["objects"] = [line_object()]
+    value["identity"] = build_image_identity(value)
+    with_labels = image_reference_source(parse_image_clip(value))
+    assert with_labels.to_dict() == source().to_dict()
+    assert (
+        not {"image_annotation", "annotation_revision", "completion"}
+        & with_labels.to_dict().keys()
+    )
+    encoded = request().to_dict()
+    assert "image_annotation" not in str(encoded)
+    assert "annotation_revision" not in str(encoded)
+
+
+def test_profile_binds_all_weights_adapter_parameters_and_runtime():
+    value = profile().to_dict()
+    for key in ("model_version", "adapter", "runtime"):
+        changed = copy.deepcopy(value)
+        changed[key] += "new"
+        with pytest.raises(ValueError, match="fingerprint"):
+            parse_image_model_profile(changed)
+    value["parameters"]["threshold"] = 0.7
+    with pytest.raises(ValueError, match="fingerprint"):
+        parse_image_model_profile(value)
+
+
+@pytest.mark.parametrize(
+    "change", ["gt", "digest", "bytes", "size", "schema", "calibration", "view"]
+)
+def test_reject_source_or_prediction_identity_drift(change):
+    value = request().to_dict()
+    if change == "gt":
+        value["objects"] = []
+    if change == "digest":
+        value["image"]["asset"]["sha256"] = "0" * 64
+    if change == "bytes":
+        value["image_base64"] = "!invalid"
+    if change == "size":
+        value["image"]["asset"]["size"] += 1
+    if change == "schema":
+        value["context"]["schema_fingerprint"] = "sha256:" + "0" * 64
+    if change == "calibration":
+        value["calibrated_sensor"]["width"] += 1
+    if change == "view":
+        value["context"]["view_id"] = "semantics"
+    with pytest.raises(ValueError):
+        parse_image_prediction_input(value)
+
+
+def test_source_rejects_revision_drift_and_extra_annotation():
+    value = source().to_dict()
+    value["sample_data"][0]["asset"]["sha256"] = "0" * 64
+    with pytest.raises(ValueError, match="source identity"):
+        parse_image_reference_source(value)
+    value = source().to_dict()
+    value["image_annotation"] = {}
+    with pytest.raises(ValueError):
+        parse_image_reference_source(value)
+
+
+def test_prediction_echo_and_native_geometry_schema_validation():
+    req = request()
+    body = req.to_dict()
+    output = {
+        "protocol_version": IMAGE_INFERENCE_PROTOCOL,
+        "context": body["context"],
+        "profile_id": body["profile_id"],
+        "image_id": "image_a",
+        "objects": [line_object()],
+    }
+    assert parse_image_prediction(output, request=req).to_dict() == output
+    output["objects"][0]["geometry"]["vertices"][0]["x"] = 9000
+    with pytest.raises(ValueError):
+        parse_image_prediction(output, request=req)
+    output["objects"] = []
+    output["profile_id"] = "sha256:" + "0" * 64
+    with pytest.raises(ValueError, match="context"):
+        parse_image_prediction(output, request=req)
+
+
+@pytest.mark.parametrize("state", ["predicted", "empty", "failed", "unprocessed"])
+def test_reference_states_are_explicit_and_not_human_completion(state):
+    value = artifact()
+    row = value["coverage"][0]
+    row["status"] = state
+    if state != "predicted":
+        row["objects"] = []
+    if state == "failed":
+        row["error"] = {"code": "model_failed", "message": "Model execution failed"}
+    parsed = parse_image_reference(value)
+    assert parsed.to_dict() == value
+    assert "completion" not in parsed.to_dict()
+
+
+@pytest.mark.parametrize(
+    "change",
+    [
+        "missing",
+        "duplicate",
+        "foreign-image",
+        "wrong-occupancy",
+        "missing-error",
+        "extra-gt",
+    ],
+)
+def test_reference_rejects_incomplete_or_misleading_coverage(change):
+    value = artifact()
+    if change == "missing":
+        value["coverage"] = []
+    if change == "duplicate":
+        value["coverage"] *= 2
+    if change == "foreign-image":
+        value["coverage"][0]["image_id"] = "foreign"
+    if change == "wrong-occupancy":
+        value["coverage"][0]["status"] = "empty"
+    if change == "missing-error":
+        value["coverage"][0].update(status="failed", objects=[])
+    if change == "extra-gt":
+        value["completion"] = []
+    with pytest.raises(ValueError):
+        parse_image_reference(value)
+
+
+def test_typed_client_pins_source_schema_profile_and_rejects_foreign_results():
+    from x4d_devkit.client.image_references import ImageReferencesAPI
+
+    clip = parse_image_clip(clip_payload())
+    identity = clip.to_dict()["identity"]
+    state = {
+        "run_id": "ref_1",
+        "project_id": clip.to_dict()["meta"]["project_id"],
+        "clip_id": clip.clip_id,
+        "service_id": "curb",
+        "profile_id": profile().to_dict()["profile_id"],
+        "view_id": "objects",
+        "source_revision": identity["source_revision"],
+        "schema_fingerprint": identity["schema_fingerprint"],
+        "status": "completed",
+        "progress": {
+            "total": 1,
+            "processed": 1,
+            "predicted": 1,
+            "empty": 0,
+            "failed": 0,
+            "unprocessed": 0,
+        },
+        "error": None,
+        "created_at": "2026-10-26T00:00:00Z",
+        "completed_at": "2026-10-26T00:01:00Z",
+    }
+
+    class Transport:
+        def post(self, path, *, json):
+            assert path == "/image-references/runs"
+            assert "base_annotation_revision" not in json
+            assert json["idempotency_key"] == "repeat-safe"
+            return state
+
+        def get(self, path, **kwargs):
+            return artifact() if path.endswith("/result") else state
+
+    client = ImageReferencesAPI(Transport())
+    assert (
+        client.create(
+            clip=clip,
+            service_id="curb",
+            profile_id=state["profile_id"],
+            view_id="objects",
+            idempotency_key="repeat-safe",
+        ).to_dict()
+        == state
+    )
+    assert client.result("ref_1").to_dict() == artifact()
+    with pytest.raises(ValueError, match="foreign"):
+        client.result("ref_other")
+    with pytest.raises(ValueError, match="foreign"):
+        client.get("ref_other")

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

{x4d_devkit-0.48.0rc2 → x4d_devkit-0.48.0rc3}/x4d_devkit/client/client.py

@@ -25,6 +25,7 @@ from x4d_devkit.client.dataset_identity import DatasetIdentityAPI
 from x4d_devkit.client.label_schemas import LabelSchemasAPI
 from x4d_devkit.client.image_clips import ImageClipsAPI
 from x4d_devkit.client.image_work_sessions import ImageWorkSessionsAPI
+from x4d_devkit.client.image_references import ImageReferencesAPI
 from x4d_devkit.client.semantic_scene import SemanticSceneAPI
 from x4d_devkit.client.semantic_scene_authoring import (
     SemanticSceneAuthoringWorkSessionsAPI,
@@ -74,6 +75,7 @@ class X4DClient:
         self.clips = ClipsAPI(self)
         self.image_clips = ImageClipsAPI(self)
         self.image_work_sessions = ImageWorkSessionsAPI(self)
+        self.image_references = ImageReferencesAPI(self)
         self.label_schemas = LabelSchemasAPI(self)
         self.semantic_scene = SemanticSceneAPI(self)
         self.semantic_scene_authoring_work_sessions = (

x4d_devkit-0.48.0rc3/x4d_devkit/client/image_references.py

@@ -0,0 +1,147 @@
+"""Explicit native 2D reference runs, independent of human annotation bases."""
+
+from urllib.parse import quote
+
+from x4d_devkit._image_contract import document, fields, identifier, require
+from x4d_devkit.image_clip import ImageClip
+from x4d_devkit.image_reference import parse_image_reference
+
+
+def parse_image_reference_run(value):
+    fields(
+        value,
+        {
+            "run_id",
+            "project_id",
+            "clip_id",
+            "service_id",
+            "profile_id",
+            "view_id",
+            "source_revision",
+            "schema_fingerprint",
+            "status",
+            "progress",
+            "error",
+            "created_at",
+            "completed_at",
+        },
+        "image_reference_run",
+    )
+    identifier(value["run_id"], "run_id")
+    from x4d_devkit._image_contract import integer, text
+    from x4d_devkit.image_clip import _digest
+
+    integer(value["project_id"], "project_id", minimum=1)
+    for key in ("clip_id", "service_id", "view_id"):
+        identifier(value[key], key)
+    for key in ("profile_id", "source_revision", "schema_fingerprint"):
+        _digest(value[key], key)
+    text(value["created_at"], "created_at")
+    if value["completed_at"] is not None:
+        text(value["completed_at"], "completed_at")
+    if value["error"] is not None:
+        fields(value["error"], {"code", "message"}, "error")
+        for key in ("code", "message"):
+            text(value["error"][key], "error." + key)
+    require(
+        value["status"] in {"queued", "running", "completed", "failed", "cancelled"},
+        "invalid run state",
+        "status",
+    )
+    fields(
+        value["progress"],
+        {"processed", "total", "predicted", "empty", "failed", "unprocessed"},
+        "progress",
+    )
+    from x4d_devkit._image_contract import integer
+
+    for key, count in value["progress"].items():
+        integer(count, "progress." + key)
+    p = value["progress"]
+    require(
+        p["processed"] == p["predicted"] + p["empty"] + p["failed"]
+        and p["total"] == p["processed"] + p["unprocessed"],
+        "invalid run counters",
+        "progress",
+    )
+    return document(value)
+
+
+class ImageReferencesAPI:
+    def __init__(self, client):
+        self._client = client
+
+    def create(
+        self,
+        *,
+        clip: ImageClip,
+        service_id: str,
+        profile_id: str,
+        view_id: str,
+        idempotency_key: str,
+    ):
+        require(type(clip) is ImageClip, "expected parsed native Clip", "clip")
+        value = clip.to_dict()
+        request = {
+            "clip_id": clip.clip_id,
+            "service_id": service_id,
+            "profile_id": profile_id,
+            "view_id": view_id,
+            "idempotency_key": idempotency_key,
+            "source_revision": value["identity"]["source_revision"],
+            "schema_fingerprint": value["identity"]["schema_fingerprint"],
+        }
+        result = parse_image_reference_run(
+            self._client.post("/image-references/runs", json=request)
+        )
+        for key, expected in request.items():
+            if key != "idempotency_key":
+                require(
+                    result.to_dict()[key] == expected,
+                    "run request context mismatch",
+                    key,
+                )
+        require(
+            result.to_dict()["project_id"] == value["meta"]["project_id"],
+            "run project context mismatch",
+            "project_id",
+        )
+        return result
+
+    def list(self, *, clip_id: str, page: int = 1, page_size: int = 20) -> dict:
+        identifier(clip_id, "clip_id")
+        value = self._client.get(
+            "/image-references/runs",
+            params={"clip_id": clip_id, "page": page, "page_size": page_size},
+        )
+        fields(value, {"items", "total", "page", "page_size"}, "image_reference_runs")
+        for item in value["items"]:
+            parsed = parse_image_reference_run(item).to_dict()
+            require(parsed["clip_id"] == clip_id, "foreign Clip run", "clip_id")
+        return value
+
+    def get(self, run_id: str):
+        identifier(run_id, "run_id")
+        result = parse_image_reference_run(
+            self._client.get(f"/image-references/runs/{quote(run_id, safe='')}")
+        )
+        require(result.to_dict()["run_id"] == run_id, "foreign run", "run_id")
+        return result
+
+    def result(self, run_id: str):
+        identifier(run_id, "run_id")
+        result = parse_image_reference(
+            self._client.get(f"/image-references/runs/{quote(run_id, safe='')}/result")
+        )
+        require(result.to_dict()["run_id"] == run_id, "foreign reference run", "run_id")
+        return result
+
+    def cancel(self, run_id: str):
+        identifier(run_id, "run_id")
+        result = parse_image_reference_run(
+            self._client.post(
+                f"/image-references/runs/{quote(run_id, safe='')}/cancel", json={}
+            )
+        )
+        require(result.to_dict()["run_id"] == run_id, "foreign run", "run_id")
+        return result