x4d-devkit 0.48.0rc8__tar.gz → 0.49.0__tar.gz

{x4d_devkit-0.48.0rc8 → x4d_devkit-0.49.0}/PKG-INFO

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

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

@@ -308,6 +308,40 @@ def test_typed_client_validates_metadata_then_reads_one_authorized_verified_imag
         assert len(requests) == 3
 
 
+@pytest.mark.parametrize("failure", [None, "source", "descriptor", "origin", "contract"])
+def test_reference_only_read_validates_context_without_requesting_media(failure):
+    value, requests = clip_payload(), []
+
+    def handler(request):
+        requests.append(request)
+        assert request.url.path.endswith("/images/image_a")
+        result = {
+            "contract_version": "x4d-image-asset-reference-v1",
+            "clip_id": "clip_test", "image_id": "image_a",
+            "source_revision": value["identity"]["source_revision"],
+            "asset": dict(value["sample_data"][0]["asset"]),
+            "uri": "/api/v1/files/clips/clip_test/samples/cam_a/10000000020.jpg",
+        }
+        if failure == "source":
+            result["source_revision"] = "sha256:" + "f" * 64
+        elif failure == "descriptor":
+            result["asset"]["size"] += 1
+        elif failure == "origin":
+            result["uri"] = "https://untrusted.example/api/v1/files/private"
+        elif failure == "contract":
+            result["contract_version"] = "other"
+        return httpx.Response(200, json=result)
+
+    with client_for(handler) as client:
+        clip = parse_image_clip(value)
+        if failure:
+            with pytest.raises(ValueError):
+                client.image_clips.get_asset(clip, "image_a")
+        else:
+            assert client.image_clips.get_asset(clip, "image_a")["asset"] == clip.images[0]["asset"]
+        assert len(requests) == 1
+
+
 @pytest.mark.parametrize(
     "failure",
     [

x4d_devkit-0.49.0/tests/test_project_discovery.py

@@ -0,0 +1,264 @@
+from __future__ import annotations
+
+from copy import deepcopy
+
+import pytest
+
+from x4d_devkit.client.projects import ProjectsAPI
+from x4d_devkit.project_discovery import (
+    PROJECT_DISCOVERY_VERSION,
+    ProjectDiscoveryError,
+    project_discovery_query,
+    validate_project_discovery_page,
+    validate_project_image_task,
+)
+
+
+def discovery_page(task_id="a_new_task", *, revision=None, page=1):
+    return {
+        "items": [
+            {
+                "id": 7,
+                "name": "Project",
+                "project_type": "2d",
+                "image_task": {
+                    "status": "registered",
+                    "id": task_id,
+                    "revision": revision or 1,
+                    "title": "Registered title",
+                },
+            }
+        ]
+        if page <= 2
+        else [],
+        "total": 1 if revision else 2,
+        "page": page,
+        "page_size": 1,
+        "discovery": {
+            "contract_version": PROJECT_DISCOVERY_VERSION,
+            "applied_filters": {
+                "image_task_id": task_id,
+                "image_task_revision": revision,
+            },
+            "facets": {
+                "image_task": {
+                    "options": [
+                        {
+                            "id": task_id,
+                            "title": "Registered title",
+                            "project_count": 2,
+                            "revisions": [
+                                {
+                                    "revision": 1,
+                                    "title": "Registered title",
+                                    "project_count": 1,
+                                },
+                                {
+                                    "revision": 2,
+                                    "title": "Registered title",
+                                    "project_count": 1,
+                                },
+                            ],
+                        }
+                    ],
+                    "unresolved_project_count": 1,
+                }
+            },
+        },
+    }
+
+
+class Client:
+    def __init__(self, value):
+        self.value, self.calls = value, []
+
+    def get(self, path, params=None):
+        self.calls.append((path, params))
+        return deepcopy(self.value)
+
+
+def test_new_task_needs_no_business_enum_and_retains_old_call_shape():
+    client = Client(discovery_page("new_after_sdk_release"))
+    result = ProjectsAPI(client).list(
+        1,
+        1,
+        None,
+        "2d",
+        image_task_id="new_after_sdk_release",
+        include_facets=["image_task", "image_task"],
+    )
+    assert result["items"][0]["image_task"]["id"] == "new_after_sdk_release"
+    assert client.calls == [
+        (
+            "/projects",
+            {
+                "page": 1,
+                "page_size": 1,
+                "project_type": "2d",
+                "image_task_id": "new_after_sdk_release",
+                "include_facets": ["image_task"],
+            },
+        )
+    ]
+    old = {"items": [], "total": 0, "page": 1, "page_size": 50}
+    client = Client(old)
+    assert ProjectsAPI(client).list() == old
+    assert client.calls == [("/projects", {"page": 1, "page_size": 50})]
+
+
+@pytest.mark.parametrize(
+    "kwargs",
+    [
+        {"image_task_id": "task"},
+        {"project_type": "3d", "include_facets": ["image_task"]},
+        {"project_type": "2d", "image_task_revision": 1},
+        {"project_type": "2d", "image_task_id": " task"},
+        {"project_type": "2d", "image_task_id": ""},
+        {"project_type": "2d", "image_task_id": "x" * 1025},
+        {"project_type": "2d", "image_task_id": "task", "image_task_revision": True},
+        {"project_type": "2d", "image_task_id": "task", "image_task_revision": 0},
+        {"project_type": "2d", "include_facets": "image_task"},
+        {"project_type": "2d", "include_facets": [""]},
+        {"project_type": "2d", "include_facets": ["private_json"]},
+    ],
+)
+def test_bad_query_is_rejected_before_transport(kwargs):
+    client = Client({})
+    with pytest.raises(ProjectDiscoveryError) as exc:
+        ProjectsAPI(client).list(**kwargs)
+    assert exc.value.code == "invalid_project_discovery_query"
+    assert client.calls == []
+
+
+def test_exact_revision_and_out_of_range_pages():
+    assert (
+        ProjectsAPI(Client(discovery_page(revision=2))).list(
+            page_size=1,
+            project_type="2d",
+            image_task_id="a_new_task",
+            image_task_revision=2,
+        )["total"]
+        == 1
+    )
+    assert (
+        ProjectsAPI(Client(discovery_page(page=3))).list(
+            page=3, page_size=1, project_type="2d", image_task_id="a_new_task"
+        )["items"]
+        == []
+    )
+
+
+def test_facet_scope_ignores_current_task_filter_and_counts_unresolved():
+    value = discovery_page()
+    value["discovery"]["applied_filters"]["image_task_id"] = None
+    value["total"], value["page_size"] = 3, 3
+    value["items"].extend(
+        [
+            {
+                "id": 8,
+                "name": "Another",
+                "project_type": "2d",
+                "image_task": {
+                    "status": "registered",
+                    "id": "a_new_task",
+                    "revision": 2,
+                    "title": "Registered title",
+                },
+            },
+            {
+                "id": 9,
+                "name": "Missing",
+                "project_type": "2d",
+                "image_task": {
+                    "status": "missing",
+                    "id": None,
+                    "revision": None,
+                    "title": None,
+                },
+            },
+        ]
+    )
+    assert (
+        ProjectsAPI(Client(value)).list(
+            page_size=3, project_type="2d", include_facets=["image_task"]
+        )["total"]
+        == 3
+    )
+    value["items"], value["total"] = [], 0
+    value["discovery"]["applied_filters"]["image_task_id"] = "not_registered"
+    assert (
+        ProjectsAPI(Client(value)).list(
+            page_size=3,
+            project_type="2d",
+            image_task_id="not_registered",
+            include_facets=["image_task"],
+        )["items"]
+        == []
+    )
+
+
+@pytest.mark.parametrize(
+    "mutation",
+    [
+        lambda value: value.pop("discovery"),
+        lambda value: value["discovery"].update(contract_version="unknown"),
+        lambda value: value["discovery"]["applied_filters"].update(image_task_id=None),
+        lambda value: value["discovery"]["applied_filters"].update(
+            image_task_revision=True
+        ),
+        lambda value: value["discovery"].update(facets={}),
+        lambda value: value.update(page=2),
+        lambda value: value.update(total=True),
+        lambda value: value.update(total=3),
+        lambda value: value.update(items=[]),
+        lambda value: value["items"][0].update(project_type="3d"),
+        lambda value: value["items"][0]["image_task"].update(id="other"),
+        lambda value: value["items"][0]["image_task"].update(revision=4),
+        lambda value: value["items"][0]["image_task"].update(title="invented"),
+        lambda value: value["discovery"]["facets"]["image_task"]["options"][0].update(
+            project_count=3
+        ),
+        lambda value: value["discovery"]["facets"]["image_task"]["options"][0][
+            "revisions"
+        ].reverse(),
+        lambda value: value["discovery"]["facets"]["image_task"].update(
+            unresolved_project_count=-1
+        ),
+    ],
+)
+def test_old_ignored_filters_and_invalid_response_never_escape_to_ui(mutation):
+    value = discovery_page()
+    mutation(value)
+    with pytest.raises(ProjectDiscoveryError):
+        ProjectsAPI(Client(value)).list(
+            page_size=1,
+            project_type="2d",
+            image_task_id="a_new_task",
+            include_facets=["image_task"],
+        )
+
+
+@pytest.mark.parametrize("status", ["registered", "missing", "invalid", "unavailable"])
+def test_binding_statuses_do_not_fill_defaults(status):
+    value = {"status": status, "id": None, "revision": None, "title": None}
+    if status in {"registered", "unavailable"}:
+        value.update(id="task", revision=1)
+    if status == "registered":
+        value["title"] = "Title"
+    assert validate_project_image_task(value) is value
+    broken = {**value, "revision": False}
+    with pytest.raises(ProjectDiscoveryError):
+        validate_project_image_task(broken)
+
+
+def test_optional_response_extensions_do_not_force_new_clients():
+    value = discovery_page()
+    value["discovery"]["future_optional"] = {"anything": True}
+    value["items"][0]["future_optional"] = "retained"
+    query = project_discovery_query(
+        project_type="2d", image_task_id="a_new_task", include_facets=["image_task"]
+    )
+    assert (
+        validate_project_discovery_page(value, query=query, page=1, page_size=1)
+        is value
+    )

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

{x4d_devkit-0.48.0rc8 → x4d_devkit-0.49.0}/x4d_devkit/client/__init__.py

@@ -30,6 +30,7 @@ from x4d_devkit.client.semantic_scene_authoring import (
     SemanticSceneAuthoringWorkSessionsAPI,
 )
 from x4d_devkit.client.projects import ProjectResolutionError, ProjectsAPI
+from x4d_devkit.project_discovery import ProjectDiscoveryError
 from x4d_devkit.client.reconstruction import (
     ReconstructionAPI,
     StaticRgbMapGeneration,
@@ -67,6 +68,7 @@ __all__ = [
     "PlatformAsset",
     "PlatformAssetReference",
     "ProjectResolutionError",
+    "ProjectDiscoveryError",
     "ProjectsAPI",
     "ReconstructionAPI",
     "RESOLVED_LABEL_SCHEMA_CONTEXT_VERSION",

{x4d_devkit-0.48.0rc8 → x4d_devkit-0.49.0}/x4d_devkit/client/image_clips.py

@@ -7,6 +7,7 @@ from urllib.parse import quote
 
 from x4d_devkit._image_contract import fields, identifier, integer, require
 from x4d_devkit.client.assets import PlatformAsset
+from x4d_devkit.client.assets import _validated_file_uri
 from x4d_devkit.image_clip import ImageClip, parse_image_clip
 
 
@@ -47,22 +48,15 @@ class ImageClipsAPI:
         value = self._client.get(f"/image-clips/{quote(clip_id, safe='')}")
         return parse_image_clip(value, expected_clip_id=clip_id)
 
-    def read_image(
-        self, clip: ImageClip, image_id: str, *, max_bytes: int = 32 * 1024 * 1024
-    ) -> PlatformAsset:
+    def get_asset(self, clip: ImageClip, image_id: str) -> dict:
+        """Validate an authorized reference without downloading original bytes."""
         require(
             type(clip) is ImageClip, "expected a validated native image Clip", "clip"
         )
         identifier(image_id, "image_id")
-        integer(max_bytes, "max_bytes", minimum=1)
         image = next((item for item in clip.images if item["id"] == image_id), None)
         require(image is not None, "image does not belong to this Clip", "image_id")
         expected = image["asset"]
-        require(
-            expected["size"] <= max_bytes,
-            "image exceeds the configured read budget",
-            "image.asset.size",
-        )
         value = self._client.get(
             f"/image-clips/{quote(clip.clip_id, safe='')}/images/{quote(image_id, safe='')}"
         )
@@ -82,12 +76,33 @@ class ImageClipsAPI:
             value["contract_version"] == IMAGE_ASSET_REFERENCE_VERSION
             and value["clip_id"] == clip.clip_id
             and value["image_id"] == image_id
-            and value["source_revision"]
-            == clip.to_dict()["identity"]["source_revision"]
             and value["asset"] == expected,
             "image asset context changed",
             "image_asset",
         )
+        require(
+            value["source_revision"] == clip.to_dict()["identity"]["source_revision"],
+            "image source revision changed",
+            "image_asset.source_revision",
+        )
+        _validated_file_uri(value["uri"], api_url=self._client.api_url)
+        return value
+
+    def read_image(
+        self, clip: ImageClip, image_id: str, *, max_bytes: int = 32 * 1024 * 1024
+    ) -> PlatformAsset:
+        require(type(clip) is ImageClip, "expected a validated native image Clip", "clip")
+        identifier(image_id, "image_id")
+        integer(max_bytes, "max_bytes", minimum=1)
+        image = next((item for item in clip.images if item["id"] == image_id), None)
+        require(image is not None, "image does not belong to this Clip", "image_id")
+        expected = image["asset"]
+        require(
+            expected["size"] <= max_bytes,
+            "image exceeds the configured read budget",
+            "image.asset.size",
+        )
+        value = self.get_asset(clip, image_id)
         asset = self._client.assets.fetch(value["uri"], max_bytes=expected["size"])
         require(
             len(asset.content) == expected["size"]

{x4d_devkit-0.48.0rc8 → x4d_devkit-0.49.0}/x4d_devkit/client/projects.py

@@ -2,8 +2,14 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from collections.abc import Sequence
 from typing import TYPE_CHECKING
 
+from x4d_devkit.project_discovery import (
+    project_discovery_query,
+    validate_project_discovery_page,
+)
+
 if TYPE_CHECKING:
     from x4d_devkit.client.client import X4DClient
 
@@ -27,8 +33,14 @@ class ProjectsAPI:
     def list(
         self, page: int = 1, page_size: int = 50, search: str | None = None,
         project_type: str | None = None,
+        *, image_task_id: str | None = None, image_task_revision: int | None = None,
+        include_facets: Sequence[str] | None = None,
     ) -> dict:
-        """List all projects."""
+        """List accessible Projects, optionally discovering registered image tasks."""
+        query = project_discovery_query(
+            project_type=project_type, image_task_id=image_task_id,
+            image_task_revision=image_task_revision, include_facets=include_facets,
+        )
         params = {"page": page, "page_size": page_size}
         if search:
             params["search"] = search
@@ -36,7 +48,16 @@ class ProjectsAPI:
             if project_type not in {"2d", "3d"}:
                 raise ValueError("project_type must be 2d or 3d")
             params["project_type"] = project_type
-        return self._client.get("/projects", params=params)
+        if query.image_task_id is not None:
+            params["image_task_id"] = query.image_task_id
+        if query.image_task_revision is not None:
+            params["image_task_revision"] = query.image_task_revision
+        if query.include_facets:
+            params["include_facets"] = list(query.include_facets)
+        value = self._client.get("/projects", params=params)
+        if query.enabled:
+            validate_project_discovery_page(value, query=query, page=page, page_size=page_size)
+        return value
 
     def get(self, project_id: int) -> dict:
         """Get a project by ID."""