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

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

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

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

@@ -0,0 +1,380 @@
+import copy
+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, parse_image_clip
+from x4d_devkit.image_preannotation import (
+    CURRENT_CONTRACT,
+    STATE_CONTRACT,
+    REQUEST_CONTRACT,
+    SERVICE_CONTRACT,
+    parse_image_preannotation_current,
+    parse_image_preannotation_state,
+    parse_image_preannotation_request,
+    parse_image_preannotation_service,
+    parse_preannotation_operation,
+)
+from x4d_devkit.image_reference import IMAGE_INFERENCE_PROTOCOL, image_reference_source
+from tests.test_image_reference import artifact, clip_payload, profile
+from tests.image_fixtures import line_object
+
+
+def context():
+    value = clip_payload()
+    return {
+        "clip_id": value["meta"]["clip_id"],
+        "project_id": value["meta"]["project_id"],
+        "view_id": "objects",
+        "source_revision": value["identity"]["source_revision"],
+        "schema_fingerprint": value["identity"]["schema_fingerprint"],
+    }
+
+
+def progress():
+    return {
+        "total": 1,
+        "processed": 0,
+        "predicted": 0,
+        "empty": 0,
+        "failed": 0,
+        "unprocessed": 1,
+    }
+
+
+def operation():
+    return {
+        "operation_id": "op_1",
+        "status": "running",
+        "progress": progress(),
+        "error": None,
+        "created_at": "2026-10-26T00:00:00Z",
+        "completed_at": None,
+        "can_cancel": True,
+    }
+
+
+def current():
+    result = artifact()
+    return {
+        **context(),
+        "contract_version": CURRENT_CONTRACT,
+        "availability": "ready",
+        "published_at": "2026-10-26T00:01:00Z",
+        "result_digest": fingerprint(result),
+        "artifact": result,
+    }
+
+
+def state():
+    return {
+        **context(),
+        "contract_version": STATE_CONTRACT,
+        "service_state": "ready",
+        "result": {
+            "availability": "ready",
+            "digest": current()["result_digest"],
+            "published_at": current()["published_at"],
+            "coverage": {
+                "total": 1,
+                "processed": 1,
+                "predicted": 1,
+                "empty": 0,
+                "failed": 0,
+                "unprocessed": 0,
+            },
+        },
+        "operation": operation(),
+    }
+
+
+def receipt():
+    return {
+        **context(),
+        "contract_version": REQUEST_CONTRACT,
+        "disposition": "created",
+        "operation": operation(),
+    }
+
+
+def test_current_is_separate_from_human_revision_and_is_a_detached_snapshot():
+    value = current()
+    parsed = parse_image_preannotation_current(value)
+    value["artifact"]["coverage"][0]["objects"].clear()
+    assert parsed.to_dict()["artifact"]["coverage"][0]["objects"]
+    assert "annotation_revision" not in parsed.to_dict()
+    human = clip_payload()
+    human["image_annotation"]["objects"] = [line_object()]
+    human["identity"] = build_image_identity(human)
+    assert (
+        image_reference_source(parse_image_clip(human)).to_dict()
+        == artifact()["source"]
+    )
+
+
+def test_successful_zero_detection_is_ready_and_never_human_completion():
+    value = current()
+    value["artifact"]["coverage"][0].update(status="empty", objects=[])
+    value["result_digest"] = fingerprint(value["artifact"])
+    result = parse_image_preannotation_current(value).to_dict()
+    assert result["availability"] == "ready"
+    assert result["artifact"]["coverage"][0]["status"] == "empty"
+    assert "completion" not in result["artifact"]
+
+
+@pytest.mark.parametrize("availability", ["none", "stale"])
+def test_absence_is_explicit_and_cannot_carry_an_old_artifact(availability):
+    value = {
+        **context(),
+        "contract_version": CURRENT_CONTRACT,
+        "availability": availability,
+        "published_at": None,
+        "result_digest": None,
+        "artifact": None,
+    }
+    assert parse_image_preannotation_current(value).to_dict() == value
+    value["artifact"] = artifact()
+    with pytest.raises(ValueError):
+        parse_image_preannotation_current(value)
+
+
+def test_partial_output_has_complete_failed_scopes_without_old_fill():
+    payload = clip_payload()
+    sample = copy.deepcopy(payload["sample"][0])
+    sample.update(
+        id="sample_b",
+        timestamp={"sec": 11, "nanosec": 20},
+        image_ids={"cam_a": "image_b"},
+    )
+    payload["sample"].append(sample)
+    image = copy.deepcopy(payload["sample_data"][0])
+    image.update(
+        id="image_b", sample_id="sample_b", timestamp={"sec": 11, "nanosec": 20}
+    )
+    image["asset"]["path"] = "samples/cam_a/11000000020.jpg"
+    payload["sample_data"].append(image)
+    payload["image_annotation"]["completion"] += [
+        {"image_id": "image_b", "view_id": view, "state": "unprocessed"}
+        for view in payload["meta"]["view_ids"]
+    ]
+    payload["identity"] = build_image_identity(payload)
+    value = current()
+    value["artifact"]["source"] = image_reference_source(
+        parse_image_clip(payload)
+    ).to_dict()
+    value["source_revision"] = payload["identity"]["source_revision"]
+    value["artifact"]["coverage"].append(
+        {
+            "image_id": "image_b",
+            "status": "failed",
+            "objects": [],
+            "error": {"code": "invalid_image", "message": "Image failed"},
+        }
+    )
+    value["availability"] = "partial"
+    value["result_digest"] = fingerprint(value["artifact"])
+    parsed = parse_image_preannotation_current(value).to_dict()
+    assert parsed["artifact"]["coverage"][1]["objects"] == []
+    value["availability"] = "ready"
+    with pytest.raises(ValueError):
+        parse_image_preannotation_current(value)
+    value["availability"] = "partial"
+    value["artifact"]["coverage"][0].update(
+        status="failed", objects=[], error={"code": "failed", "message": "Image failed"}
+    )
+    value["result_digest"] = fingerprint(value["artifact"])
+    with pytest.raises(ValueError, match="successes"):
+        parse_image_preannotation_current(value)
+
+
+@pytest.mark.parametrize(
+    "change",
+    [
+        "digest",
+        "source",
+        "view",
+        "project",
+        "missing_image",
+        "extra_choice",
+        "all_failed",
+        "unknown_availability",
+    ],
+)
+def test_reject_wrong_current_context_geometry_or_selectors(change):
+    value = current()
+    if change == "digest":
+        value["result_digest"] = "sha256:" + "0" * 64
+    elif change == "source":
+        value["source_revision"] = "sha256:" + "0" * 64
+    elif change == "view":
+        value["view_id"] = "semantics"
+    elif change == "project":
+        value["project_id"] = 99
+    elif change == "missing_image":
+        value["artifact"]["coverage"] = []
+    elif change == "extra_choice":
+        value["model_version"] = "latest"
+    elif change == "all_failed":
+        value["availability"] = "partial"
+        value["artifact"]["coverage"][0].update(
+            status="failed",
+            objects=[],
+            error={"code": "failed", "message": "Image failed"},
+        )
+        value["result_digest"] = fingerprint(value["artifact"])
+    else:
+        value["availability"] = {}
+    with pytest.raises(ValueError):
+        parse_image_preannotation_current(value)
+
+
+@pytest.mark.parametrize(
+    "change",
+    [
+        "timestamp",
+        "boolean_count",
+        "bad_count",
+        "terminal_time",
+        "terminal_cancel",
+        "partial_without_success",
+        "unknown_state",
+    ],
+)
+def test_operation_state_is_strict(change):
+    value = operation()
+    if change == "timestamp":
+        value["created_at"] = "yesterday"
+    elif change == "boolean_count":
+        value["progress"]["processed"] = True
+    elif change == "bad_count":
+        value["progress"]["processed"] = 1
+    elif change == "terminal_time":
+        value["status"] = "failed"
+    elif change == "terminal_cancel":
+        value.update(status="cancelled", completed_at="2026-10-26T00:01:00Z")
+    elif change == "partial_without_success":
+        value.update(
+            status="partial", completed_at="2026-10-26T00:01:00Z", can_cancel=False
+        )
+    else:
+        value["status"] = {}
+    with pytest.raises(ValueError):
+        parse_preannotation_operation(value)
+
+
+def test_state_keeps_existing_result_available_during_or_after_failed_rerun():
+    value = state()
+    assert parse_image_preannotation_state(value).to_dict() == value
+    value["operation"].update(
+        status="failed",
+        completed_at="2026-10-26T00:01:00Z",
+        can_cancel=False,
+        error={"code": "service_unavailable", "message": "Service failed"},
+    )
+    assert (
+        parse_image_preannotation_state(value).to_dict()["result"]["availability"]
+        == "ready"
+    )
+    value["result"]["availability"] = "none"
+    with pytest.raises(ValueError):
+        parse_image_preannotation_state(value)
+
+
+def test_receipt_rejects_model_choice_and_available_creating_work():
+    value = receipt()
+    assert parse_image_preannotation_request(value).to_dict() == value
+    value["profile_id"] = profile().to_dict()["profile_id"]
+    with pytest.raises(ValueError):
+        parse_image_preannotation_request(value)
+    value = receipt()
+    value["disposition"] = "available"
+    with pytest.raises(ValueError):
+        parse_image_preannotation_request(value)
+
+
+def test_service_is_ready_with_one_model_and_explicit_task_outputs():
+    value = {
+        "contract_version": SERVICE_CONTRACT,
+        "protocol_version": IMAGE_INFERENCE_PROTOCOL,
+        "status": "ready",
+        "service_name": "synthetic",
+        "service_version": "test",
+        "task_ids": ["test_objects"],
+        "model": profile().to_dict(),
+        "outputs": [{"category_id": "line", "geometry_type": "polyline_2d"}],
+        "max_concurrent_tasks": 1,
+    }
+    assert parse_image_preannotation_service(value).to_dict() == value
+    value["task_ids"] *= 2
+    with pytest.raises(ValueError):
+        parse_image_preannotation_service(value)
+    value["task_ids"] = ["test_objects"]
+    value["models"] = [profile().to_dict()]
+    with pytest.raises(ValueError):
+        parse_image_preannotation_service(value)
+
+
+def test_typed_client_resolves_no_model_or_history_and_rejects_foreign_current():
+    calls = []
+    foreign = False
+
+    def handler(request):
+        calls.append(request)
+        if request.method == "POST" and request.url.path.endswith("/requests"):
+            body = json.loads(request.content)
+            assert set(body) == {
+                "clip_id",
+                "view_id",
+                "source_revision",
+                "schema_fingerprint",
+                "idempotency_key",
+                "recompute",
+            }
+            return httpx.Response(200, json=receipt())
+        if request.url.path.endswith("/current"):
+            value = current()
+            if foreign:
+                value["clip_id"] = "foreign"
+            return httpx.Response(200, json=value)
+        if request.url.path.endswith("/cancel"):
+            assert json.loads(request.content) == {"operation_id": "op_1"}
+        return httpx.Response(200, json=state())
+
+    with X4DClient("https://platform.test") as client:
+        client._http.close()
+        client._http = httpx.Client(
+            base_url="https://platform.test", transport=httpx.MockTransport(handler)
+        )
+        clip = parse_image_clip(clip_payload())
+        api = client.image_preannotations
+        assert not hasattr(client, "image_references")
+        assert (
+            api.request(
+                clip=clip, view_id="objects", idempotency_key="request_1"
+            ).to_dict()
+            == receipt()
+        )
+        assert api.current(clip=clip, view_id="objects").to_dict() == current()
+        assert api.status(clip=clip, view_id="objects").to_dict() == state()
+        assert (
+            api.cancel(
+                clip_id=clip.clip_id, view_id="objects", operation_id="op_1"
+            ).to_dict()
+            == state()
+        )
+        foreign = True
+        with pytest.raises(ValueError):
+            api.current(clip=clip, view_id="objects")
+        with pytest.raises(TypeError):
+            api.request(
+                clip=clip,
+                view_id="objects",
+                idempotency_key="request_1",
+                profile_id="forbidden",
+            )
+    for call in calls:
+        assert "image-references" not in call.url.path
+        assert "annotation_revision" not in str(call.url)

x4d_devkit-0.48.0rc4/tests/test_image_reference.py

@@ -0,0 +1,211 @@
+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)

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

{x4d_devkit-0.48.0rc2 → x4d_devkit-0.48.0rc4}/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_preannotations import ImagePreannotationsAPI
 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_preannotations = ImagePreannotationsAPI(self)
         self.label_schemas = LabelSchemasAPI(self)
         self.semantic_scene = SemanticSceneAPI(self)
         self.semantic_scene_authoring_work_sessions = (