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

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

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

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

@@ -209,59 +209,3 @@ def test_reference_rejects_incomplete_or_misleading_coverage(change):
         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.0rc3 → 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.0rc3"
+    assert x4d_devkit.__version__ == "0.48.0rc4"
 
 
 def test_loader_exposes_and_enforces_only_current_schema(tmp_path):

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

@@ -25,7 +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.image_preannotations import ImagePreannotationsAPI
 from x4d_devkit.client.semantic_scene import SemanticSceneAPI
 from x4d_devkit.client.semantic_scene_authoring import (
     SemanticSceneAuthoringWorkSessionsAPI,
@@ -75,7 +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.image_preannotations = ImagePreannotationsAPI(self)
         self.label_schemas = LabelSchemasAPI(self)
         self.semantic_scene = SemanticSceneAPI(self)
         self.semantic_scene_authoring_work_sessions = (

x4d_devkit-0.48.0rc4/x4d_devkit/client/image_preannotations.py

@@ -0,0 +1,117 @@
+"""One current native preannotation, with a server-resolved startup model."""
+
+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 (
+    parse_image_preannotation_current,
+    parse_image_preannotation_request,
+    parse_image_preannotation_state,
+)
+
+
+def _context(clip, view_id):
+    require(type(clip) is ImageClip, "expected a parsed native Clip", "clip")
+    value = clip.to_dict()
+    identifier(view_id, "view_id")
+    require(
+        view_id in value["meta"]["view_ids"],
+        "view is not applicable to this Clip",
+        "view_id",
+    )
+    return {
+        "clip_id": clip.clip_id,
+        "project_id": value["meta"]["project_id"],
+        "view_id": view_id,
+        "source_revision": value["identity"]["source_revision"],
+        "schema_fingerprint": value["identity"]["schema_fingerprint"],
+    }
+
+
+def _check(result, context):
+    value = result.to_dict()
+    require(
+        all(value[key] == expected for key, expected in context.items()),
+        "response context mismatch",
+        "context",
+    )
+    return result
+
+
+def _path(clip_id, view_id):
+    identifier(clip_id, "clip_id")
+    identifier(view_id, "view_id")
+    return f"/image-preannotations/clips/{quote(clip_id, safe='')}/views/{quote(view_id, safe='')}"
+
+
+class ImagePreannotationsAPI:
+    def __init__(self, client):
+        self._client = client
+
+    def request(
+        self,
+        *,
+        clip: ImageClip,
+        view_id: str,
+        idempotency_key: str,
+        recompute: bool = False,
+    ):
+        context = _context(clip, view_id)
+        identifier(idempotency_key, "idempotency_key")
+        require(type(recompute) is bool, "expected an explicit boolean", "recompute")
+        body = {key: value for key, value in context.items() if key != "project_id"}
+        body.update(idempotency_key=idempotency_key, recompute=recompute)
+        return _check(
+            parse_image_preannotation_request(
+                self._client.post("/image-preannotations/requests", json=body)
+            ),
+            context,
+        )
+
+    def _read(self, *, clip, view_id, suffix, parser):
+        context = _context(clip, view_id)
+        value = self._client.get(
+            _path(clip.clip_id, view_id) + suffix,
+            params={
+                key: context[key] for key in ("source_revision", "schema_fingerprint")
+            },
+        )
+        return _check(parser(value), context)
+
+    def status(self, *, clip: ImageClip, view_id: str):
+        return self._read(
+            clip=clip,
+            view_id=view_id,
+            suffix="/status",
+            parser=parse_image_preannotation_state,
+        )
+
+    def current(self, *, clip: ImageClip, view_id: str):
+        return self._read(
+            clip=clip,
+            view_id=view_id,
+            suffix="/current",
+            parser=parse_image_preannotation_current,
+        )
+
+    def cancel(self, *, clip_id: str, view_id: str, operation_id: str):
+        identifier(operation_id, "operation_id")
+        value = parse_image_preannotation_state(
+            self._client.post(
+                _path(clip_id, view_id) + "/cancel", json={"operation_id": operation_id}
+            )
+        )
+        data = value.to_dict()
+        require(
+            data["clip_id"] == clip_id and data["view_id"] == view_id,
+            "foreign cancellation scope",
+            "context",
+        )
+        require(
+            data["operation"] is not None
+            and data["operation"]["operation_id"] == operation_id,
+            "foreign cancellation operation",
+            "operation",
+        )
+        return value