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

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

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

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

@@ -0,0 +1,389 @@
+"""Synthetic offline export and typed-client tests; no platform or private media."""
+
+from copy import deepcopy
+from io import BytesIO
+import json
+import tarfile
+
+import httpx
+import pytest
+
+from tests.image_fixtures import IMAGE_BYTES, clip_payload, line_object
+from x4d_devkit import X4DClient
+from x4d_devkit._image_contract import ImageContractError, canonical
+from x4d_devkit.image_clip import build_image_identity
+from x4d_devkit.image_export import (
+    COMPONENTS,
+    DOWNLOAD_CONTRACT,
+    EXPORT_CONTRACT,
+    EXPORT_README,
+    INDEX_CONTRACT,
+    JOB_CONTRACT,
+    PAGE_CONTRACT,
+    PREVIEW_CONTRACT,
+    clip_manifest_entry,
+    human_scope_index,
+    parse_image_export_job,
+    reference_path,
+    sha256,
+    validate_image_export_bundle,
+)
+
+EXPORT_ID = "imexp_" + "a" * 32
+NOW = "2026-10-26T12:00:00+00:00"
+
+
+def contents(*, references=False, state="unprocessed"):
+    clip = clip_payload()
+    if state != "confirmed_empty":
+        clip["image_annotation"]["objects"] = [line_object()]
+    clip["image_annotation"]["completion"][0]["state"] = state
+    clip["identity"] = build_image_identity(clip)
+    cid = clip["meta"]["clip_id"]
+    files = {f"clips/{cid}/{name}.json": canonical(clip[name]) for name in COMPONENTS}
+    files[f"consumption/{cid}/human_scopes.json"] = canonical(human_scope_index(clip))
+    if references:
+        for view in clip["meta"]["view_ids"]:
+            files[reference_path(cid, view)] = canonical(
+                {
+                    "contract_version": "x4d-image-preannotation-current-v1",
+                    "project_id": clip["meta"]["project_id"],
+                    "clip_id": cid,
+                    "view_id": view,
+                    "source_revision": clip["identity"]["source_revision"],
+                    "schema_fingerprint": clip["identity"]["schema_fingerprint"],
+                    "availability": "none",
+                    "published_at": None,
+                    "result_digest": None,
+                    "artifact": None,
+                }
+            )
+    for image in clip["sample_data"]:
+        files[f"clips/{cid}/{image['asset']['path']}"] = IMAGE_BYTES
+    return clip, files
+
+
+def bundle(tmp_path, clip, files, *, references=False, append=None, override=None):
+    cid = clip["meta"]["clip_id"]
+    index = canonical(
+        {
+            "contract_version": INDEX_CONTRACT,
+            "clip_id": cid,
+            "files": [
+                {"path": name, "size": len(raw), "sha256": sha256(raw)}
+                for name, raw in files.items()
+            ],
+        }
+    )
+    manifest = {
+        "contract_version": EXPORT_CONTRACT,
+        "export_id": EXPORT_ID,
+        "project_id": clip["meta"]["project_id"],
+        "created_at": NOW,
+        "include_preannotations": references,
+        "clips": [
+            clip_manifest_entry(clip, captured_at=NOW, file_index_sha256=sha256(index))
+        ],
+    }
+    entries = {
+        "manifest.json": canonical(manifest),
+        "README.md": EXPORT_README,
+        f"indexes/{cid}.json": index,
+        **files,
+    }
+    path = tmp_path / "export.tar"
+    with tarfile.open(path, "w") as archive:
+        for name, raw in entries.items():
+            info = tarfile.TarInfo(f"{EXPORT_ID}/{name}")
+            if override:
+                raw = override(name, raw)
+            info.size = len(raw)
+            archive.addfile(info, BytesIO(raw))
+        if append:
+            info = tarfile.TarInfo(append)
+            info.size = 1
+            archive.addfile(info, BytesIO(b"x"))
+    return path
+
+
+@pytest.mark.parametrize("state", ["unprocessed", "complete", "confirmed_empty"])
+@pytest.mark.parametrize("references", [False, True])
+def test_roundtrip_preserves_native_identity_and_explicit_completion(
+    tmp_path, state, references
+):
+    clip, files = contents(state=state, references=references)
+    result = validate_image_export_bundle(
+        bundle(tmp_path, clip, files, references=references)
+    )
+    assert result["images"] == 1
+    assert result["completion_counts"][state] >= 1
+    assert result["objects"] == (state != "confirmed_empty")
+    if state == "unprocessed":
+        assert result["completion_counts"]["complete"] == 0
+        assert result["completion_counts"]["confirmed_empty"] == 0
+
+
+@pytest.mark.parametrize(
+    "change",
+    [
+        "scope",
+        "scope-extra",
+        "missing",
+        "path",
+        "duplicate",
+        "identity",
+        "prediction-context",
+        "extra",
+    ],
+)
+def test_fail_closed_even_when_attacker_recomputes_transport_hashes(tmp_path, change):
+    clip, files = contents(references=True)
+    cid = clip["meta"]["clip_id"]
+    scope = f"consumption/{cid}/human_scopes.json"
+    append = None
+    if change.startswith("scope"):
+        value = json.loads(files[scope])
+        if change == "scope":
+            value["scopes"][0]["state"] = "complete"
+        else:
+            value["unexpected"] = True
+        files[scope] = canonical(value)
+    if change == "missing":
+        files.pop(scope)
+    if change == "path":
+        files["../escape"] = b"x"
+    if change == "duplicate":
+        append = f"{EXPORT_ID}/{scope}"
+    if change == "identity":
+        value = json.loads(files[f"clips/{cid}/identity.json"])
+        value["annotation_revision"] = "sha256:" + "0" * 64
+        files[f"clips/{cid}/identity.json"] = canonical(value)
+    if change == "prediction-context":
+        name = reference_path(cid, clip["meta"]["view_ids"][0])
+        value = json.loads(files[name])
+        value["source_revision"] = "sha256:" + "0" * 64
+        files[name] = canonical(value)
+    if change == "extra":
+        files[f"clips/{cid}/password.json"] = b"{}"
+    with pytest.raises((ImageContractError, ValueError)):
+        validate_image_export_bundle(
+            bundle(tmp_path, clip, files, references=True, append=append)
+        )
+
+
+def test_corrupt_bytes_and_budget_are_rejected_without_extraction(tmp_path):
+    clip, files = contents()
+    path = bundle(
+        tmp_path,
+        clip,
+        files,
+        override=lambda name, raw: b"z" * len(raw) if name.endswith(".jpg") else raw,
+    )
+    with pytest.raises(ImageContractError, match="SHA256"):
+        validate_image_export_bundle(path)
+    path = bundle(tmp_path, clip, files)
+    with pytest.raises(ImageContractError, match="budget"):
+        validate_image_export_bundle(path, max_json_bytes=10)
+    assert list(tmp_path.iterdir()) == [path]
+
+
+def job(status="queued"):
+    completed = status == "completed"
+    terminal = status in {"completed", "failed", "cancelled"}
+    return {
+        "contract_version": JOB_CONTRACT,
+        "export_id": EXPORT_ID,
+        "project_id": 7,
+        "clip_ids": ["clip_test"],
+        "include_preannotations": False,
+        "status": status,
+        "progress": {
+            "stage": status,
+            "processed": 0,
+            "total": 1,
+            "bytes": 0,
+            "elapsed_s": 0.0,
+            "rate": 0.0,
+            "eta_s": None,
+        },
+        "error": {"code": "test_failure", "message": "Explicit failure"}
+        if status == "failed"
+        else None,
+        "artifact": {"filename": EXPORT_ID + ".tar", "size": 10240, "sha256": "b" * 64}
+        if completed
+        else None,
+        "created_at": NOW,
+        "completed_at": NOW if terminal else None,
+        "can_cancel": not terminal,
+    }
+
+
+@pytest.mark.parametrize(
+    "status",
+    [
+        "queued",
+        "capturing",
+        "packaging",
+        "validating",
+        "uploading",
+        "completed",
+        "failed",
+        "cancelled",
+    ],
+)
+def test_job_states_are_strict(status):
+    assert parse_image_export_job(job(status)).to_dict()["status"] == status
+
+
+@pytest.mark.parametrize(
+    "change",
+    ["error", "artifact", "processed", "bool", "unknown", "terminal", "infinite"],
+)
+def test_invalid_job_states_fail(change):
+    value = job()
+    if change == "error":
+        value["error"] = {"code": "oops", "message": "not failed"}
+    if change == "artifact":
+        value["artifact"] = job("completed")["artifact"]
+    if change == "processed":
+        value["progress"]["processed"] = 2
+    if change == "bool":
+        value["project_id"] = True
+    if change == "unknown":
+        value["model_version"] = "forbidden"
+    if change == "terminal":
+        value["completed_at"] = NOW
+    if change == "infinite":
+        value["progress"]["rate"] = float("inf")
+    with pytest.raises((ImageContractError, ValueError)):
+        parse_image_export_job(value)
+
+
+def test_typed_client_scope_and_ephemeral_download_do_not_forward_credentials():
+    calls = []
+
+    def handler(request):
+        calls.append(request)
+        path = request.url.path
+        if path.endswith("/preview"):
+            return httpx.Response(
+                200,
+                json={
+                    "contract_version": PREVIEW_CONTRACT,
+                    "project_id": 7,
+                    "clip_id": "clip_test",
+                    "include_preannotations": False,
+                    "clip_ids": ["clip_test"],
+                    "excluded": [],
+                    "scope_token": "opaque-token",
+                    "expires_at": NOW,
+                },
+            )
+        if path.endswith("/download-link"):
+            return httpx.Response(
+                200,
+                json={
+                    "contract_version": DOWNLOAD_CONTRACT,
+                    "export_id": EXPORT_ID,
+                    "url": "http://storage.test/bucket/object?signature=private",
+                    "expires_at": NOW,
+                    **job("completed")["artifact"],
+                },
+            )
+        if path == "/api/v1/image-exports" and request.method == "GET":
+            return httpx.Response(
+                200,
+                json={
+                    "contract_version": PAGE_CONTRACT,
+                    "project_id": 7,
+                    "page": 1,
+                    "page_size": 50,
+                    "total": 1,
+                    "items": [job()],
+                },
+            )
+        return httpx.Response(200, json=job())
+
+    client = X4DClient("http://platform.test", token="platform-private-token")
+    client._http = httpx.Client(
+        base_url="http://platform.test",
+        headers={"Authorization": "Bearer platform-private-token"},
+        transport=httpx.MockTransport(handler),
+    )
+    preview = client.image_exports.preview(project_id=7, clip_id="clip_test")
+    created = client.image_exports.create(
+        project_id=7,
+        clip_id="clip_test",
+        scope_token=preview.to_dict()["scope_token"],
+        idempotency_key="key",
+    )
+    assert created.to_dict()["export_id"] == EXPORT_ID
+    assert client.image_exports.list(project_id=7).to_dict()["total"] == 1
+    for action in ("get", "cancel", "retry"):
+        assert (
+            getattr(client.image_exports, action)(EXPORT_ID).to_dict()["export_id"]
+            == EXPORT_ID
+        )
+    assert (
+        client.image_exports.download_link(EXPORT_ID)
+        .to_dict()["url"]
+        .startswith("http://storage.test/")
+    )
+    assert all(request.url.host == "platform.test" for request in calls)
+    assert json.loads(calls[1].content) == {
+        "project_id": 7,
+        "clip_id": "clip_test",
+        "include_preannotations": False,
+        "scope_token": "opaque-token",
+        "idempotency_key": "key",
+    }
+    with pytest.raises(ImageContractError):
+        client.image_exports.preview(project_id=True)
+    client.close()
+
+
+def test_client_rejects_foreign_response():
+    client = X4DClient("http://platform.test")
+    other = deepcopy(job())
+    other["export_id"] = "imexp_" + "c" * 32
+    client._http = httpx.Client(
+        base_url="http://platform.test",
+        transport=httpx.MockTransport(lambda r: httpx.Response(200, json=other)),
+    )
+    with pytest.raises(ImageContractError, match="foreign"):
+        client.image_exports.get(EXPORT_ID)
+    client.close()
+
+
+def test_offline_cli_reports_valid_bundle(tmp_path, capsys):
+    from types import SimpleNamespace
+    from x4d_devkit.cli import cmd_validate_image_export
+
+    clip, files = contents()
+    path = bundle(tmp_path, clip, files)
+    cmd_validate_image_export(
+        SimpleNamespace(path=path, max_json_bytes=64 * 1024 * 1024)
+    )
+    assert json.loads(capsys.readouterr().out)["ok"] is True
+    path.write_bytes(b"invalid tar")
+    with pytest.raises(SystemExit) as error:
+        cmd_validate_image_export(
+            SimpleNamespace(path=path, max_json_bytes=64 * 1024 * 1024)
+        )
+    assert error.value.code == 1
+    assert json.loads(capsys.readouterr().out)["ok"] is False
+
+
+def test_archive_member_history_is_not_retained(tmp_path, monkeypatch):
+    clip, files = contents()
+    path = bundle(tmp_path, clip, files)
+    original = tarfile.TarFile.next
+    history = []
+
+    def measured(archive):
+        history.append(len(archive.members))
+        return original(archive)
+
+    monkeypatch.setattr(tarfile.TarFile, "next", measured)
+    validate_image_export_bundle(path)
+    assert max(history) <= 1

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

{x4d_devkit-0.48.0rc4 → x4d_devkit-0.48.0rc5}/x4d_devkit/cli.py

@@ -414,6 +414,18 @@ def cmd_login(args):
         print(f"Logged in as {username}; token saved to {path}")
 
 
+def cmd_validate_image_export(args):
+    import tarfile
+    from x4d_devkit.image_export import validate_image_export_bundle
+
+    try:
+        summary = validate_image_export_bundle(args.path, max_json_bytes=args.max_json_bytes)
+    except (OSError, ValueError, tarfile.TarError) as exc:
+        print_json({"ok": False, "error": str(exc)})
+        raise SystemExit(1) from exc
+    print_json({"ok": True, "summary": summary})
+
+
 def cmd_validate(args):
     from x4d_devkit.validation import validate_clip
 
@@ -755,6 +767,11 @@ def main():
     p_schemas_project.add_argument("--format", choices=["table", "json"], default="json")
     p_schemas_project.set_defaults(func=cmd_label_schemas_project_get)
 
+    p_image_export = sub.add_parser("validate-image-export", help="Validate a native image export tar offline")
+    p_image_export.add_argument("path")
+    p_image_export.add_argument("--max-json-bytes", type=int, default=64 * 1024 * 1024)
+    p_image_export.set_defaults(func=cmd_validate_image_export)
+
     p_val = sub.add_parser("validate", help="Validate clip directory")
     p_val.add_argument("path", help="Clip directory or parent directory")
     p_val.set_defaults(func=cmd_validate)

{x4d_devkit-0.48.0rc4 → x4d_devkit-0.48.0rc5}/x4d_devkit/client/__init__.py

@@ -10,6 +10,7 @@ from x4d_devkit.client.clip_work_sessions import (
 )
 from x4d_devkit.client.client import X4DClient
 from x4d_devkit.client.image_work_sessions import ImageWorkSessionsAPI
+from x4d_devkit.client.image_exports import ImageExportsAPI
 from x4d_devkit.client.clips import ClipsAPI
 from x4d_devkit.client.dataset_identity import DatasetIdentityAPI
 from x4d_devkit.client.label_schemas import (
@@ -43,6 +44,7 @@ from x4d_devkit.client.test_sets import TestSetsAPI
 
 __all__ = [
     "ImageWorkSessionsAPI",
+    "ImageExportsAPI",
     "CleanBasemapState",
     "AssetsAPI",
     "BagsAPI",

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

@@ -26,6 +26,7 @@ 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.image_exports import ImageExportsAPI
 from x4d_devkit.client.semantic_scene import SemanticSceneAPI
 from x4d_devkit.client.semantic_scene_authoring import (
     SemanticSceneAuthoringWorkSessionsAPI,
@@ -76,6 +77,7 @@ class X4DClient:
         self.image_clips = ImageClipsAPI(self)
         self.image_work_sessions = ImageWorkSessionsAPI(self)
         self.image_preannotations = ImagePreannotationsAPI(self)
+        self.image_exports = ImageExportsAPI(self)
         self.label_schemas = LabelSchemasAPI(self)
         self.semantic_scene = SemanticSceneAPI(self)
         self.semantic_scene_authoring_work_sessions = (

x4d_devkit-0.48.0rc5/x4d_devkit/client/image_exports.py

@@ -0,0 +1,141 @@
+"""Typed invocation of platform-owned native image export capabilities."""
+
+from x4d_devkit._image_contract import identifier, integer, require, text
+from x4d_devkit.image_export import (
+    export_identifier,
+    parse_image_export_download,
+    parse_image_export_job,
+    parse_image_export_page,
+    parse_image_export_preview,
+)
+
+
+class ImageExportsAPI:
+    def __init__(self, client):
+        self._client = client
+
+    def _scope(self, project_id, clip_id, include_preannotations):
+        integer(project_id, "project_id", minimum=1)
+        if clip_id is not None:
+            identifier(clip_id, "clip_id")
+        require(
+            type(include_preannotations) is bool,
+            "expected boolean",
+            "include_preannotations",
+        )
+        return {
+            "project_id": project_id,
+            "clip_id": clip_id,
+            "include_preannotations": include_preannotations,
+        }
+
+    def preview(self, *, project_id, clip_id=None, include_preannotations=False):
+        body = self._scope(project_id, clip_id, include_preannotations)
+        result = parse_image_export_preview(
+            self._client.post("/image-exports/preview", json=body)
+        )
+        value = result.to_dict()
+        require(
+            all(value[key] == item for key, item in body.items()),
+            "foreign preview context",
+            "preview",
+        )
+        return result
+
+    def create(
+        self,
+        *,
+        project_id,
+        scope_token,
+        idempotency_key,
+        clip_id=None,
+        include_preannotations=False,
+    ):
+        body = self._scope(project_id, clip_id, include_preannotations)
+        text(scope_token, "scope_token")
+        text(idempotency_key, "idempotency_key")
+        result = parse_image_export_job(
+            self._client.post(
+                "/image-exports",
+                json={
+                    **body,
+                    "scope_token": scope_token,
+                    "idempotency_key": idempotency_key,
+                },
+            )
+        )
+        value = result.to_dict()
+        require(
+            value["project_id"] == project_id
+            and value["include_preannotations"] == include_preannotations
+            and (clip_id is None or value["clip_ids"] == [clip_id]),
+            "foreign created job",
+            "job",
+        )
+        return result
+
+    def list(self, *, project_id, page=1, page_size=50):
+        for key, value in {
+            "project_id": project_id,
+            "page": page,
+            "page_size": page_size,
+        }.items():
+            integer(value, key, minimum=1)
+        require(page_size <= 100, "page size exceeds 100", "page_size")
+        result = parse_image_export_page(
+            self._client.get(
+                "/image-exports",
+                params={"project_id": project_id, "page": page, "page_size": page_size},
+            )
+        )
+        value = result.to_dict()
+        require(
+            all(
+                value[key] == item
+                for key, item in {
+                    "project_id": project_id,
+                    "page": page,
+                    "page_size": page_size,
+                }.items()
+            ),
+            "foreign export page",
+            "page",
+        )
+        return result
+
+    def get(self, export_id):
+        return self._job(export_id, "get")
+
+    def cancel(self, export_id):
+        return self._job(export_id, "cancel")
+
+    def retry(self, export_id):
+        return self._job(export_id, "retry")
+
+    def _job(self, export_id, action):
+        export_identifier(export_id)
+        path = f"/image-exports/{export_id}"
+        payload = (
+            self._client.get(path)
+            if action == "get"
+            else self._client.post(f"{path}/{action}", json={})
+        )
+        result = parse_image_export_job(payload)
+        require(
+            result.to_dict()["export_id"] == export_id,
+            "foreign export job",
+            "export_id",
+        )
+        return result
+
+    def download_link(self, export_id):
+        export_identifier(export_id)
+        result = parse_image_export_download(
+            self._client.post(f"/image-exports/{export_id}/download-link", json={})
+        )
+        require(
+            result.to_dict()["export_id"] == export_id,
+            "foreign export download",
+            "export_id",
+        )
+        return result