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

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

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

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

@@ -0,0 +1,228 @@
+import copy
+
+import httpx
+import pytest
+
+from x4d_devkit import X4DClient
+from x4d_devkit.client import WorkSessionConflictError
+from x4d_devkit.image_clip import build_image_identity
+from x4d_devkit.image_work_session import (
+    IMAGE_SUBMIT_RECEIPT_VERSION,
+    IMAGE_WORK_SESSION_VERSION,
+    build_image_submit,
+    image_candidate,
+    parse_image_submit,
+    parse_image_submit_receipt,
+    parse_image_work_session,
+)
+from tests.image_fixtures import clip_payload, line_object
+
+
+def session():
+    return parse_image_work_session(
+        {"contract_version": IMAGE_WORK_SESSION_VERSION, "clip": clip_payload()}
+    )
+
+
+def candidate():
+    annotation = session().clip.to_dict()["image_annotation"]
+    annotation["objects"] = [line_object()]
+    annotation["completion"][0]["state"] = "complete"
+    return annotation
+
+
+def receipt(annotation=None):
+    ws = session()
+    value = image_candidate(ws.clip, annotation or candidate()).to_dict()
+    return {
+        "contract_version": IMAGE_SUBMIT_RECEIPT_VERSION,
+        "project_id": value["meta"]["project_id"],
+        "clip_id": value["meta"]["clip_id"],
+        **{
+            key: value["identity"][key]
+            for key in (
+                "source_revision",
+                "schema_fingerprint",
+                "annotation_revision",
+                "clip_revision",
+            )
+        },
+        "changed": True,
+        "projection_state": "ready",
+    }
+
+
+def client(handler):
+    value = X4DClient("https://platform.test", token="private")
+    value._http.close()
+    value._http = httpx.Client(
+        base_url="https://platform.test", transport=httpx.MockTransport(handler)
+    )
+    return value
+
+
+def test_complete_candidate_preserves_source_schema_other_views_and_stable_ranges():
+    ws = session()
+    request = build_image_submit(ws, candidate()).to_dict()
+    parsed = parse_image_submit(request)
+    assert parsed.to_dict()["image_annotation"] == candidate()
+    value = image_candidate(ws.clip, candidate()).to_dict()
+    assert (
+        value["identity"]["source_revision"]
+        == ws.clip.to_dict()["identity"]["source_revision"]
+    )
+    assert value["identity"]["schema_fingerprint"] == request["base_schema_fingerprint"]
+    assert (
+        value["image_annotation"]["objects"][0]["attribute_ranges"]
+        == line_object()["attribute_ranges"]
+    )
+    assert ws.clip.to_dict()["image_annotation"]["objects"] == []
+    request["image_annotation"]["objects"].clear()
+    assert parsed.to_dict()["image_annotation"]["objects"]
+
+
+@pytest.mark.parametrize(
+    "change",
+    [
+        "version",
+        "extra",
+        "image-version",
+        "invalid-clip",
+        "missing-range",
+        "missing-scope",
+        "foreign-object",
+    ],
+)
+def test_strict_session_and_candidate_rejection(change):
+    value = session().to_dict()
+    if change == "version":
+        value["contract_version"] = "x4d-clip-work-session-v10"
+    elif change == "extra":
+        value["ready"] = True
+    elif change == "image-version":
+        value["clip"]["meta"]["schema_version"] = "0.18"
+    elif change == "invalid-clip":
+        value["clip"]["identity"]["clip_revision"] = "sha256:" + "0" * 64
+    else:
+        ann = candidate()
+        if change == "missing-range":
+            ann["objects"][0]["attribute_ranges"][0]["start_vertex_id"] = "missing"
+        elif change == "missing-scope":
+            ann["completion"].pop()
+        else:
+            ann["objects"][0]["image_id"] = "foreign"
+        with pytest.raises(ValueError):
+            build_image_submit(session(), ann)
+        return
+    with pytest.raises(ValueError):
+        parse_image_work_session(value)
+
+
+@pytest.mark.parametrize(
+    "key",
+    [
+        "contract_version",
+        "project_id",
+        "clip_id",
+        "base_source_revision",
+        "base_schema_fingerprint",
+        "base_annotation_revision",
+        "image_annotation",
+    ],
+)
+def test_request_rejects_missing_fields_and_no_coercion(key):
+    value = build_image_submit(session(), candidate()).to_dict()
+    del value[key]
+    with pytest.raises(ValueError):
+        parse_image_submit(value)
+
+
+def test_typed_open_submit_and_exact_retry_request():
+    requests = []
+
+    def handler(req):
+        import json
+
+        requests.append(json.loads(req.content))
+        return httpx.Response(
+            200,
+            json=session().to_dict() if req.url.path.endswith("open") else receipt(),
+        )
+
+    with client(handler) as c:
+        ws = c.image_work_sessions.open(project_id=7, clip_id="clip_test")
+        accepted = c.image_work_sessions.submit(
+            manifest=ws, image_annotation=candidate()
+        )
+        assert accepted.to_dict() == receipt()
+        c.image_work_sessions.submit(manifest=ws, image_annotation=candidate())
+    assert (
+        requests[1]
+        == requests[2]
+        == build_image_submit(session(), candidate()).to_dict()
+    )
+
+
+@pytest.mark.parametrize(
+    "key",
+    [
+        "project_id",
+        "clip_id",
+        "source_revision",
+        "schema_fingerprint",
+        "annotation_revision",
+        "clip_revision",
+        "changed",
+        "projection_state",
+    ],
+)
+def test_typed_client_rejects_unrelated_or_invalid_receipt(key):
+    value = receipt()
+    value[key] = {
+        "project_id": 8,
+        "clip_id": "foreign",
+        "changed": 1,
+        "projection_state": "done",
+    }.get(key, "sha256:" + "0" * 64)
+    with client(lambda req: httpx.Response(200, json=value)) as c:
+        with pytest.raises(ValueError):
+            c.image_work_sessions.submit(
+                manifest=session(), image_annotation=candidate()
+            )
+
+
+def test_conflict_is_structured_and_no_unvalidated_candidate_is_sent():
+    conflict = {"annotation_revision": {"base": "old", "current": "new"}}
+    with client(
+        lambda req: httpx.Response(
+            409,
+            json={
+                "detail": {
+                    "code": "work_session_conflict",
+                    "extra": {"conflicts": conflict},
+                }
+            },
+        )
+    ) as c:
+        with pytest.raises(WorkSessionConflictError) as exc:
+            c.image_work_sessions.submit(
+                manifest=session(), image_annotation=candidate()
+            )
+        assert exc.value.conflicts == conflict
+    with client(lambda req: pytest.fail("invalid candidate reached transport")) as c:
+        ann = copy.deepcopy(candidate())
+        ann["completion"] = []
+        with pytest.raises(ValueError):
+            c.image_work_sessions.submit(manifest=session(), image_annotation=ann)
+
+
+def test_receipt_and_session_reject_invalid_identity_types():
+    value = receipt()
+    value["project_id"] = True
+    with pytest.raises(ValueError):
+        parse_image_submit_receipt(value)
+    value = session().to_dict()
+    value["clip"]["sample_data"][0]["width"] = 10
+    value["clip"]["identity"] = build_image_identity(value["clip"])
+    with pytest.raises(ValueError):
+        parse_image_work_session(value)

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

{x4d_devkit-0.48.0rc1 → x4d_devkit-0.48.0rc2}/x4d_devkit/client/__init__.py

@@ -9,6 +9,7 @@ from x4d_devkit.client.clip_work_sessions import (
     WorkSessionConflictError,
 )
 from x4d_devkit.client.client import X4DClient
+from x4d_devkit.client.image_work_sessions import ImageWorkSessionsAPI
 from x4d_devkit.client.clips import ClipsAPI
 from x4d_devkit.client.dataset_identity import DatasetIdentityAPI
 from x4d_devkit.client.label_schemas import (
@@ -41,6 +42,7 @@ from x4d_devkit.client.services import ServicesAPI
 from x4d_devkit.client.test_sets import TestSetsAPI
 
 __all__ = [
+    "ImageWorkSessionsAPI",
     "CleanBasemapState",
     "AssetsAPI",
     "BagsAPI",

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

@@ -24,6 +24,7 @@ from x4d_devkit.client.clips import ClipsAPI
 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.semantic_scene import SemanticSceneAPI
 from x4d_devkit.client.semantic_scene_authoring import (
     SemanticSceneAuthoringWorkSessionsAPI,
@@ -72,6 +73,7 @@ class X4DClient:
         self.reconstruction = ReconstructionAPI(self)
         self.clips = ClipsAPI(self)
         self.image_clips = ImageClipsAPI(self)
+        self.image_work_sessions = ImageWorkSessionsAPI(self)
         self.label_schemas = LabelSchemasAPI(self)
         self.semantic_scene = SemanticSceneAPI(self)
         self.semantic_scene_authoring_work_sessions = (

x4d_devkit-0.48.0rc2/x4d_devkit/client/image_work_sessions.py

@@ -0,0 +1,80 @@
+"""Typed whole-Clip image authoring with verified acceptance receipts."""
+
+import httpx
+
+from x4d_devkit._image_contract import require
+from x4d_devkit.client.clip_work_sessions import WorkSessionConflictError, _error_detail
+from x4d_devkit.image_work_session import (
+    ImageWorkSession,
+    build_image_submit,
+    image_candidate,
+    parse_image_submit_receipt,
+    parse_image_work_session,
+)
+
+
+class ImageWorkSessionsAPI:
+    def __init__(self, client):
+        self._client = client
+
+    def open(self, *, project_id: int, clip_id: str) -> ImageWorkSession:
+        from x4d_devkit._image_contract import identifier, integer
+
+        integer(project_id, "project_id", minimum=1)
+        identifier(clip_id, "clip_id")
+        value = parse_image_work_session(
+            self._client.post(
+                "/image-work-sessions/open",
+                json={"project_id": project_id, "clip_id": clip_id},
+            )
+        )
+        context = value.base_identity()
+        require(
+            context["project_id"] == project_id and context["clip_id"] == clip_id,
+            "image session belongs to another project/Clip",
+            "image_work_session.clip.meta",
+        )
+        return value
+
+    def submit(self, *, manifest: ImageWorkSession | dict, image_annotation: dict):
+        session = (
+            manifest
+            if type(manifest) is ImageWorkSession
+            else parse_image_work_session(manifest)
+        )
+        request = build_image_submit(session, image_annotation).to_dict()
+        candidate = image_candidate(session.clip, image_annotation).to_dict()
+        try:
+            response = self._client.post("/image-work-sessions/submit", json=request)
+        except httpx.HTTPStatusError as exc:
+            detail = _error_detail(exc)
+            if (
+                isinstance(detail, dict)
+                and detail.get("code") == "work_session_conflict"
+            ):
+                raise WorkSessionConflictError(
+                    detail.get("message") or "Image work-session baseline is stale",
+                    conflicts=(detail.get("extra") or {}).get("conflicts", {}),
+                    status_code=exc.response.status_code,
+                ) from exc
+            raise
+        receipt = parse_image_submit_receipt(response)
+        result = receipt.to_dict()
+        for key in ("project_id", "clip_id"):
+            require(
+                result[key] == request[key],
+                "receipt belongs to another context",
+                "receipt." + key,
+            )
+        for key in (
+            "source_revision",
+            "schema_fingerprint",
+            "annotation_revision",
+            "clip_revision",
+        ):
+            require(
+                result[key] == candidate["identity"][key],
+                "receipt does not accept the submitted candidate",
+                "receipt." + key,
+            )
+        return receipt

x4d_devkit-0.48.0rc2/x4d_devkit/image_work_session.py

@@ -0,0 +1,161 @@
+"""Native image authoring grammar, independent of platform storage and 3D."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from x4d_devkit._image_contract import (
+    ImageDocument,
+    canonical,
+    document,
+    fields,
+    identifier,
+    integer,
+    require,
+)
+from x4d_devkit.image_clip import (
+    ImageClip,
+    _digest,
+    build_image_identity,
+    parse_image_clip,
+)
+
+
+IMAGE_WORK_SESSION_VERSION = "x4d-image-work-session-v1"
+IMAGE_SUBMIT_VERSION = "x4d-image-submit-v1"
+IMAGE_SUBMIT_RECEIPT_VERSION = "x4d-image-submit-receipt-v1"
+_BASE_KEYS = {
+    "base_source_revision",
+    "base_schema_fingerprint",
+    "base_annotation_revision",
+}
+
+
+class ImageWorkSession(ImageDocument):
+    @property
+    def clip(self) -> ImageClip:
+        return parse_image_clip(self.to_dict()["clip"])
+
+    def base_identity(self) -> dict:
+        clip = self.to_dict()["clip"]
+        identity = clip["identity"]
+        return {
+            "project_id": clip["meta"]["project_id"],
+            "clip_id": clip["meta"]["clip_id"],
+            "base_source_revision": identity["source_revision"],
+            "base_schema_fingerprint": identity["schema_fingerprint"],
+            "base_annotation_revision": identity["annotation_revision"],
+        }
+
+
+def parse_image_work_session(value: Any) -> ImageWorkSession:
+    canonical(value)
+    fields(value, {"contract_version", "clip"}, "image_work_session")
+    require(
+        value["contract_version"] == IMAGE_WORK_SESSION_VERSION,
+        "unsupported image work-session version",
+        "image_work_session.contract_version",
+    )
+    parse_image_clip(value["clip"])
+    return document(value, ImageWorkSession)
+
+
+def image_candidate(clip: ImageClip, image_annotation: Any) -> ImageClip:
+    """Validate one complete replacement in its exact immutable source context."""
+    require(type(clip) is ImageClip, "expected a validated image Clip", "clip")
+    value = clip.to_dict()
+    value["image_annotation"] = image_annotation
+    value["identity"] = build_image_identity(value)
+    return parse_image_clip(value)
+
+
+def parse_image_submit(value: Any) -> ImageDocument:
+    canonical(value)
+    fields(
+        value,
+        {"contract_version", "project_id", "clip_id", "image_annotation", *_BASE_KEYS},
+        "image_submit",
+    )
+    require(
+        value["contract_version"] == IMAGE_SUBMIT_VERSION,
+        "unsupported image submit version",
+        "image_submit.contract_version",
+    )
+    integer(value["project_id"], "image_submit.project_id", minimum=1)
+    identifier(value["clip_id"], "image_submit.clip_id")
+    for key in _BASE_KEYS:
+        _digest(value[key], "image_submit." + key)
+    fields(
+        value["image_annotation"],
+        {"contract_version", "clip_id", "objects", "descriptions", "completion"},
+        "image_submit.image_annotation",
+    )
+    require(
+        value["image_annotation"]["clip_id"] == value["clip_id"],
+        "candidate belongs to another Clip",
+        "image_submit.image_annotation.clip_id",
+    )
+    return document(value)
+
+
+def build_image_submit(
+    manifest: ImageWorkSession | dict, image_annotation: Any
+) -> ImageDocument:
+    session = (
+        manifest
+        if type(manifest) is ImageWorkSession
+        else parse_image_work_session(manifest)
+    )
+    candidate = image_candidate(session.clip, image_annotation)
+    return parse_image_submit(
+        {
+            "contract_version": IMAGE_SUBMIT_VERSION,
+            **session.base_identity(),
+            "image_annotation": candidate.to_dict()["image_annotation"],
+        }
+    )
+
+
+def parse_image_submit_receipt(value: Any) -> ImageDocument:
+    canonical(value)
+    fields(
+        value,
+        {
+            "contract_version",
+            "project_id",
+            "clip_id",
+            "source_revision",
+            "schema_fingerprint",
+            "annotation_revision",
+            "clip_revision",
+            "changed",
+            "projection_state",
+        },
+        "image_submit_receipt",
+    )
+    require(
+        value["contract_version"] == IMAGE_SUBMIT_RECEIPT_VERSION,
+        "unsupported image receipt version",
+        "image_submit_receipt.contract_version",
+    )
+    integer(value["project_id"], "image_submit_receipt.project_id", minimum=1)
+    identifier(value["clip_id"], "image_submit_receipt.clip_id")
+    for key in (
+        "source_revision",
+        "schema_fingerprint",
+        "annotation_revision",
+        "clip_revision",
+    ):
+        _digest(value[key], "image_submit_receipt." + key)
+    require(
+        type(value["changed"]) is bool,
+        "changed must be boolean",
+        "image_submit_receipt.changed",
+    )
+    require(
+        type(value["projection_state"]) is str
+        and value["projection_state"] in {"ready", "pending"},
+        "invalid projection state",
+        "image_submit_receipt.projection_state",
+    )
+    return document(value)

{x4d_devkit-0.48.0rc1 → x4d_devkit-0.48.0rc2}/x4d_devkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.48.0rc1
+Version: 0.48.0rc2
 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.0rc1 → x4d_devkit-0.48.0rc2}/x4d_devkit.egg-info/SOURCES.txt

@@ -26,6 +26,7 @@ tests/test_export_bundle.py
 tests/test_image_clip.py
 tests/test_image_geometry.py
 tests/test_image_review.py
+tests/test_image_work_session.py
 tests/test_inference_input.py
 tests/test_inference_schemas.py
 tests/test_inference_service.py
@@ -77,6 +78,7 @@ x4d_devkit/image_clip.py
 x4d_devkit/image_geometry.py
 x4d_devkit/image_review.py
 x4d_devkit/image_schema.py
+x4d_devkit/image_work_session.py
 x4d_devkit/json_contract.py
 x4d_devkit/label_schema.py
 x4d_devkit/lidar_materialization.py
@@ -109,6 +111,7 @@ x4d_devkit/client/clips.py
 x4d_devkit/client/dataset_identity.py
 x4d_devkit/client/image_clips.py
 x4d_devkit/client/image_review.py
+x4d_devkit/client/image_work_sessions.py
 x4d_devkit/client/label_schemas.py
 x4d_devkit/client/preannotation.py
 x4d_devkit/client/projects.py