x4d-devkit 0.55.1__tar.gz → 0.56.0rc1__tar.gz

{x4d_devkit-0.55.1/x4d_devkit.egg-info → x4d_devkit-0.56.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.55.1
+Version: 0.56.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.55.1 → x4d_devkit-0.56.0rc1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.55.1"
+version = "0.56.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.56.0rc1/tests/test_image_external_predictions.py

@@ -0,0 +1,529 @@
+"""Reference v2 producers/scores and external prediction publishing (#245)."""
+
+import copy
+import json
+import math
+import re
+
+import httpx
+import pytest
+
+from tests.image_fixtures import schema_record
+from tests.test_image_reference import artifact, clip_payload, profile
+from x4d_devkit import X4DClient
+from x4d_devkit.image_clip import build_image_identity, parse_image_clip
+from x4d_devkit.image_preannotation import (
+    EXTERNAL_CONTRACT,
+    EXTERNAL_RECEIPT_CONTRACT,
+    build_image_external_reference,
+    parse_image_preannotation_external,
+    parse_image_preannotation_external_receipt,
+)
+from x4d_devkit.image_reference import (
+    IMAGE_REFERENCE_CONTRACT,
+    image_reference_source,
+    parse_image_reference,
+    prediction_object_id,
+)
+from x4d_devkit.image_schema import (
+    build_image_schema_snapshot,
+    parse_image_schema_body,
+    parse_image_schema_record,
+)
+
+
+def required_clip_payload():
+    """Box category with a human-required enum attribute and two images."""
+    payload = clip_payload()
+    record = schema_record()
+    box = next(row for row in record["body"]["categories"] if row["id"] == "box")
+    box["attributes"] = [
+        {
+            "id": "kind",
+            "display_name": "Kind",
+            "type": "enum",
+            "required": True,
+            "scopes": ["object"],
+            "values": [
+                {"id": "bin", "display_name": "Bin"},
+                {"id": "bag", "display_name": "Bag"},
+            ],
+        }
+    ]
+    record["fingerprint"] = parse_image_schema_body(
+        record["body"]
+    ).identity.fingerprint
+    payload["label_schema"] = build_image_schema_snapshot(
+        parse_image_schema_record(record)
+    )
+    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)
+    return payload
+
+
+def box(image_id, ordinal, attributes=None):
+    return {
+        "id": prediction_object_id(image_id, ordinal),
+        "image_id": image_id,
+        "view_id": "objects",
+        "category_id": "box",
+        "geometry": {
+            "geometry_type": "box_2d",
+            "box": {"x_min": 10, "y_min": 20, "x_max": 40.5, "y_max": 60},
+        },
+        "attributes": {} if attributes is None else attributes,
+        "attribute_ranges": [],
+    }
+
+
+def coverage():
+    first = box("image_a", 0)
+    return [
+        {
+            "image_id": "image_a",
+            "status": "predicted",
+            "objects": [first, box("image_a", 1, {"kind": "bag"})],
+            "scores": {first["id"]: 0.91},
+            "error": None,
+        },
+        {
+            "image_id": "image_b",
+            "status": "empty",
+            "objects": [],
+            "scores": {},
+            "error": None,
+        },
+    ]
+
+
+def required_context():
+    payload = required_clip_payload()
+    return {
+        "clip_id": payload["meta"]["clip_id"],
+        "project_id": payload["meta"]["project_id"],
+        "view_id": "objects",
+        "source_revision": payload["identity"]["source_revision"],
+        "schema_fingerprint": payload["identity"]["schema_fingerprint"],
+    }
+
+
+def external_request():
+    return {
+        **required_context(),
+        "contract_version": EXTERNAL_CONTRACT,
+        "idempotency_key": "publish_1",
+        "producer": {"kind": "external", "name": "litter-vlm", "version": "2026.11"},
+        "coverage": coverage(),
+    }
+
+
+def required_source():
+    return image_reference_source(parse_image_clip(required_clip_payload()))
+
+
+def test_prediction_object_id_is_deterministic_and_canonical():
+    first = prediction_object_id("image_a", 0)
+    assert first == prediction_object_id("image_a", 0)
+    assert first != prediction_object_id("image_a", 1)
+    assert first != prediction_object_id("image_b", 0)
+    assert re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}", first)
+    assert re.fullmatch(
+        r"[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}",
+        prediction_object_id("image_a", 2**53 - 1),
+    )
+    for image_id, ordinal in (("image_a", -1), ("image_a", True), ("", 0)):
+        with pytest.raises(ValueError):
+            prediction_object_id(image_id, ordinal)
+
+
+def test_service_and_external_artifacts_are_valid_v2():
+    value = artifact()
+    assert IMAGE_REFERENCE_CONTRACT == "x4d-image-reference-v2"
+    assert parse_image_reference(value).to_dict() == value
+    value["producer"] = {"kind": "external", "name": "converter", "version": "1"}
+    assert parse_image_reference(value).to_dict() == value
+
+
+@pytest.mark.parametrize(
+    "change",
+    [
+        "v1_contract",
+        "v1_profile_field",
+        "unknown_kind",
+        "external_with_profile",
+        "service_with_name",
+        "long_name",
+        "blank_version",
+        "missing_scores",
+    ],
+)
+def test_reference_rejects_v1_and_inexact_producers(change):
+    value = artifact()
+    if change == "v1_contract":
+        value["contract_version"] = "x4d-image-reference-v1"
+    elif change == "v1_profile_field":
+        value["profile"] = value.pop("producer")["profile"]
+    elif change == "unknown_kind":
+        value["producer"]["kind"] = "human"
+    elif change == "external_with_profile":
+        value["producer"] = {
+            "kind": "external",
+            "name": "x",
+            "version": "1",
+            "profile": profile().to_dict(),
+        }
+    elif change == "service_with_name":
+        value["producer"]["name"] = "x"
+    elif change == "long_name":
+        value["producer"] = {"kind": "external", "name": "n" * 129, "version": "1"}
+    elif change == "blank_version":
+        value["producer"] = {"kind": "external", "name": "n", "version": " "}
+    else:
+        del value["coverage"][0]["scores"]
+    with pytest.raises(ValueError):
+        parse_image_reference(value)
+
+
+@pytest.mark.parametrize(
+    "scores",
+    [
+        {"line_b": 0.5},
+        {"line_a": True},
+        {"line_a": "0.5"},
+        {"line_a": None},
+        [],
+    ],
+)
+def test_reference_rejects_invalid_scores(scores):
+    value = artifact()
+    value["coverage"][0]["scores"] = scores
+    with pytest.raises(ValueError):
+        parse_image_reference(value)
+
+
+@pytest.mark.parametrize("score", [math.inf, -math.inf, math.nan])
+def test_reference_rejects_non_finite_scores(score):
+    value = artifact()
+    value["coverage"][0]["scores"] = {"line_a": score}
+    with pytest.raises(ValueError):
+        parse_image_reference(value)
+
+
+def test_reference_accepts_raw_integer_and_negative_scores_and_partial_keys():
+    value = artifact()
+    for scores in ({"line_a": -3}, {"line_a": 12}, {}):
+        value["coverage"][0]["scores"] = scores
+        assert parse_image_reference(value).to_dict() == value
+
+
+@pytest.mark.parametrize("state", ["empty", "failed", "unprocessed"])
+def test_scores_are_only_for_predicted_rows(state):
+    value = artifact()
+    value["coverage"][0].update(status=state, objects=[], scores={"line_a": 0.5})
+    if state == "failed":
+        value["coverage"][0]["error"] = {"code": "failed", "message": "Failed"}
+    with pytest.raises(ValueError, match="scores"):
+        parse_image_reference(value)
+
+
+def test_candidates_may_omit_human_required_attributes_only():
+    value = build_image_external_reference(
+        external_request(), source=required_source(), run_id="ext_1"
+    ).to_dict()
+    assert value["coverage"][0]["objects"][0]["attributes"] == {}
+    # Human formal validation still requires the attribute.
+    human = required_clip_payload()
+    human["image_annotation"]["objects"] = [box("image_a", 0)]
+    human["image_annotation"]["completion"][0]["state"] = "complete"
+    human["identity"] = build_image_identity(human)
+    with pytest.raises(ValueError, match="required"):
+        parse_image_clip(human)
+    human["image_annotation"]["completion"][0]["state"] = "unprocessed"
+    human["identity"] = build_image_identity(human)
+    with pytest.raises(ValueError, match="required"):
+        parse_image_clip(human)
+
+
+@pytest.mark.parametrize(
+    "attributes", [{"kind": "crate"}, {"kind": True}, {"colour": "red"}]
+)
+def test_candidates_keep_attribute_values_and_scopes_strict(attributes):
+    request = external_request()
+    request["coverage"][0]["objects"][0]["attributes"] = attributes
+    with pytest.raises(ValueError):
+        build_image_external_reference(
+            request, source=required_source(), run_id="ext_1"
+        )
+
+
+def test_duplicate_object_ids_are_rejected_within_and_across_images():
+    request = external_request()
+    rows = request["coverage"]
+    rows[0]["objects"][1]["id"] = rows[0]["objects"][0]["id"]
+    with pytest.raises(ValueError, match="duplicate"):
+        parse_image_preannotation_external(request)
+    request = external_request()
+    rows = request["coverage"]
+    moved = copy.deepcopy(rows[0]["objects"][0])
+    moved["image_id"] = "image_b"
+    rows[1].update(status="predicted", objects=[moved])
+    with pytest.raises(ValueError, match="duplicate"):
+        parse_image_preannotation_external(request)
+    value = build_image_external_reference(
+        external_request(), source=required_source(), run_id="ext_1"
+    ).to_dict()
+    value["coverage"][1].update(
+        status="predicted", objects=[moved], scores={}
+    )
+    with pytest.raises(ValueError, match="duplicate"):
+        parse_image_reference(value)
+
+
+def test_external_request_and_build_round_trip():
+    request = external_request()
+    assert parse_image_preannotation_external(request).to_dict() == request
+    parsed = parse_image_preannotation_external(request)
+    built = build_image_external_reference(
+        parsed, source=required_source(), run_id="ext_1"
+    ).to_dict()
+    assert built == {
+        "contract_version": IMAGE_REFERENCE_CONTRACT,
+        "run_id": "ext_1",
+        "source": required_source().to_dict(),
+        "producer": request["producer"],
+        "view_id": "objects",
+        "coverage": request["coverage"],
+    }
+    assert (
+        build_image_external_reference(
+            request, source=required_source().to_dict(), run_id="ext_1"
+        ).to_dict()
+        == built
+    )
+
+
+@pytest.mark.parametrize(
+    "change",
+    [
+        "unprocessed",
+        "all_failed",
+        "service_producer",
+        "no_coverage",
+        "wrong_contract",
+        "bad_key",
+        "duplicate_image",
+        "extra_field",
+        "failed_without_error",
+    ],
+)
+def test_external_request_is_strict(change):
+    value = external_request()
+    failed = {"code": "model_failed", "message": "Model failed"}
+    if change == "unprocessed":
+        value["coverage"][1]["status"] = "unprocessed"
+    elif change == "all_failed":
+        for row in value["coverage"]:
+            row.update(status="failed", objects=[], scores={}, error=failed)
+    elif change == "service_producer":
+        value["producer"] = {"kind": "service", "profile": profile().to_dict()}
+    elif change == "no_coverage":
+        value["coverage"] = []
+    elif change == "wrong_contract":
+        value["contract_version"] = "x4d-image-preannotation-external-v0"
+    elif change == "bad_key":
+        value["idempotency_key"] = "bad key"
+    elif change == "duplicate_image":
+        value["coverage"][1]["image_id"] = "image_a"
+    elif change == "extra_field":
+        value["run_id"] = "chosen"
+    else:
+        value["coverage"][1]["status"] = "failed"
+    with pytest.raises(ValueError):
+        parse_image_preannotation_external(value)
+
+
+@pytest.mark.parametrize(
+    "change", ["clip", "project", "source", "schema", "view", "order", "missing"]
+)
+def test_build_rejects_context_mismatch_and_wrong_image_order(change):
+    value = external_request()
+    if change == "clip":
+        value["clip_id"] = "other_clip"
+    elif change == "project":
+        value["project_id"] = 99
+    elif change == "source":
+        value["source_revision"] = "sha256:" + "0" * 64
+    elif change == "schema":
+        value["schema_fingerprint"] = "sha256:" + "0" * 64
+    elif change == "view":
+        value["view_id"] = "other_view"
+    elif change == "order":
+        value["coverage"].reverse()
+    else:
+        value["coverage"].pop()
+    with pytest.raises(ValueError):
+        build_image_external_reference(
+            value, source=required_source(), run_id="ext_1"
+        )
+    with pytest.raises(ValueError):
+        build_image_external_reference(
+            external_request(), source=required_source(), run_id="bad run"
+        )
+
+
+def operation(status="completed"):
+    return {
+        "operation_id": "op_ext",
+        "status": status,
+        "progress": progress(status),
+        "error": None,
+        "created_at": "2026-11-09T00:00:00Z",
+        "completed_at": "2026-11-09T00:00:01Z",
+        "can_cancel": False,
+    }
+
+
+def progress(status="completed"):
+    failed = 1 if status == "partial" else 0
+    return {
+        "total": 2,
+        "processed": 2,
+        "predicted": 1,
+        "empty": 1 - failed,
+        "failed": failed,
+        "unprocessed": 0,
+    }
+
+
+def external_receipt(status="completed", disposition="published"):
+    return {
+        **required_context(),
+        "contract_version": EXTERNAL_RECEIPT_CONTRACT,
+        "disposition": disposition,
+        "operation": operation(status),
+        "result": {
+            "availability": "ready" if status == "completed" else "partial",
+            "digest": "sha256:" + "a" * 64,
+            "published_at": "2026-11-09T00:00:01Z",
+            "coverage": progress(status),
+        },
+    }
+
+
+@pytest.mark.parametrize(
+    "status,disposition",
+    [("completed", "published"), ("partial", "replayed")],
+)
+def test_external_receipt_valid(status, disposition):
+    value = external_receipt(status, disposition)
+    assert parse_image_preannotation_external_receipt(value).to_dict() == value
+
+
+@pytest.mark.parametrize(
+    "change",
+    [
+        "disposition",
+        "contract",
+        "running",
+        "failed",
+        "cancellable",
+        "availability_mismatch",
+        "stale",
+        "coverage_mismatch",
+        "extra",
+    ],
+)
+def test_external_receipt_rejects_inconsistent_states(change):
+    value = external_receipt()
+    if change == "disposition":
+        value["disposition"] = "created"
+    elif change == "contract":
+        value["contract_version"] = "x4d-image-preannotation-request-v1"
+    elif change == "running":
+        value["operation"].update(status="running", completed_at=None, can_cancel=True)
+    elif change == "failed":
+        value["operation"].update(
+            status="failed", error={"code": "x", "message": "Failed"}
+        )
+    elif change == "cancellable":
+        value["operation"]["can_cancel"] = True
+    elif change == "availability_mismatch":
+        value = external_receipt("partial")
+        value["result"]["availability"] = "ready"
+        value["result"]["coverage"] = progress("completed")
+    elif change == "stale":
+        value["result"] = {
+            "availability": "stale",
+            "digest": None,
+            "published_at": None,
+            "coverage": None,
+        }
+    elif change == "coverage_mismatch":
+        value["result"]["coverage"]["predicted"] = 2
+        value["result"]["coverage"]["empty"] = 0
+    else:
+        value["artifact"] = None
+    with pytest.raises(ValueError):
+        parse_image_preannotation_external_receipt(value)
+
+
+def test_typed_client_publish_external_round_trip():
+    calls = []
+    foreign = False
+
+    def handler(request):
+        calls.append(request)
+        body = json.loads(request.content)
+        assert body == external_request()
+        value = external_receipt()
+        if foreign:
+            value["source_revision"] = "sha256:" + "0" * 64
+        return httpx.Response(200, json=value)
+
+    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(required_clip_payload())
+        api = client.image_preannotations
+        arguments = dict(
+            clip=clip,
+            view_id="objects",
+            idempotency_key="publish_1",
+            producer_name="litter-vlm",
+            producer_version="2026.11",
+            coverage=coverage(),
+        )
+        assert api.publish_external(**arguments).to_dict() == external_receipt()
+        foreign = True
+        with pytest.raises(ValueError, match="context"):
+            api.publish_external(**arguments)
+        sent = len(calls)
+        invalid = copy.deepcopy(arguments)
+        invalid["coverage"][1]["status"] = "unprocessed"
+        with pytest.raises(ValueError):
+            api.publish_external(**invalid)
+        with pytest.raises(ValueError):
+            api.publish_external(**{**arguments, "view_id": "semantics_x"})
+        assert len(calls) == sent
+    assert calls[0].method == "POST"
+    assert calls[0].url.path == (
+        "/api/v1/image-preannotations/clips/clip_test/views/objects/external"
+    )

{x4d_devkit-0.55.1 → x4d_devkit-0.56.0rc1}/tests/test_image_preannotation.py

@@ -117,7 +117,7 @@ def test_current_is_separate_from_human_revision_and_is_a_detached_snapshot():
 
 def test_successful_zero_detection_is_ready_and_never_human_completion():
     value = current()
-    value["artifact"]["coverage"][0].update(status="empty", objects=[])
+    value["artifact"]["coverage"][0].update(status="empty", objects=[], scores={})
     value["result_digest"] = fingerprint(value["artifact"])
     result = parse_image_preannotation_current(value).to_dict()
     assert result["availability"] == "ready"
@@ -171,6 +171,7 @@ def test_partial_output_has_complete_failed_scopes_without_old_fill():
             "image_id": "image_b",
             "status": "failed",
             "objects": [],
+            "scores": {},
             "error": {"code": "invalid_image", "message": "Image failed"},
         }
     )
@@ -183,7 +184,10 @@ def test_partial_output_has_complete_failed_scopes_without_old_fill():
         parse_image_preannotation_current(value)
     value["availability"] = "partial"
     value["artifact"]["coverage"][0].update(
-        status="failed", objects=[], error={"code": "failed", "message": "Image failed"}
+        status="failed",
+        objects=[],
+        scores={},
+        error={"code": "failed", "message": "Image failed"},
     )
     value["result_digest"] = fingerprint(value["artifact"])
     with pytest.raises(ValueError, match="successes"):
@@ -222,6 +226,7 @@ def test_reject_wrong_current_context_geometry_or_selectors(change):
         value["artifact"]["coverage"][0].update(
             status="failed",
             objects=[],
+            scores={},
             error={"code": "failed", "message": "Image failed"},
         )
         value["result_digest"] = fingerprint(value["artifact"])

{x4d_devkit-0.55.1 → x4d_devkit-0.56.0rc1}/tests/test_image_reference.py

@@ -74,13 +74,14 @@ def artifact():
         "contract_version": IMAGE_REFERENCE_CONTRACT,
         "run_id": "ref_1",
         "source": source().to_dict(),
-        "profile": profile().to_dict(),
+        "producer": {"kind": "service", "profile": profile().to_dict()},
         "view_id": "objects",
         "coverage": [
             {
                 "image_id": "image_a",
                 "status": "predicted",
                 "objects": [line_object()],
+                "scores": {"line_a": 0.875},
                 "error": None,
             }
         ],
@@ -175,6 +176,7 @@ def test_reference_states_are_explicit_and_not_human_completion(state):
     row["status"] = state
     if state != "predicted":
         row["objects"] = []
+        row["scores"] = {}
     if state == "failed":
         row["error"] = {"code": "model_failed", "message": "Model execution failed"}
     parsed = parse_image_reference(value)
@@ -202,9 +204,9 @@ def test_reference_rejects_incomplete_or_misleading_coverage(change):
     if change == "foreign-image":
         value["coverage"][0]["image_id"] = "foreign"
     if change == "wrong-occupancy":
-        value["coverage"][0]["status"] = "empty"
+        value["coverage"][0].update(status="empty", scores={})
     if change == "missing-error":
-        value["coverage"][0].update(status="failed", objects=[])
+        value["coverage"][0].update(status="failed", objects=[], scores={})
     if change == "extra-gt":
         value["completion"] = []
     with pytest.raises(ValueError):

{x4d_devkit-0.55.1 → x4d_devkit-0.56.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.55.1"
+    assert x4d_devkit.__version__ == "0.56.0rc1"
 
 
 def test_loader_exposes_and_enforces_only_current_schema(tmp_path):

{x4d_devkit-0.55.1 → x4d_devkit-0.56.0rc1}/x4d_devkit/client/image_preannotations.py

@@ -5,7 +5,10 @@ from urllib.parse import quote
 from x4d_devkit._image_contract import identifier, require
 from x4d_devkit.image_clip import ImageClip
 from x4d_devkit.image_preannotation import (
+    EXTERNAL_CONTRACT,
     parse_image_preannotation_current,
+    parse_image_preannotation_external,
+    parse_image_preannotation_external_receipt,
     parse_image_preannotation_request,
     parse_image_preannotation_state,
 )
@@ -69,6 +72,46 @@ class ImagePreannotationsAPI:
             context,
         )
 
+    def publish_external(
+        self,
+        *,
+        clip: ImageClip,
+        view_id: str,
+        idempotency_key: str,
+        producer_name: str,
+        producer_version: str,
+        coverage: list,
+    ):
+        """Publish external model predictions as the current preannotation.
+
+        ``coverage`` has one row per Clip image in source order; see
+        ``x4d-image-preannotation-external-v1``. The request is validated
+        locally before it is sent, and the platform replaces the current result
+        atomically.
+        """
+        context = _context(clip, view_id)
+        body = parse_image_preannotation_external(
+            {
+                **context,
+                "contract_version": EXTERNAL_CONTRACT,
+                "idempotency_key": idempotency_key,
+                "producer": {
+                    "kind": "external",
+                    "name": producer_name,
+                    "version": producer_version,
+                },
+                "coverage": coverage,
+            }
+        ).to_dict()
+        return _check(
+            parse_image_preannotation_external_receipt(
+                self._client.post(
+                    _path(clip.clip_id, view_id) + "/external", json=body
+                )
+            ),
+            context,
+        )
+
     def _read(self, *, clip, view_id, suffix, parser):
         context = _context(clip, view_id)
         value = self._client.get(