x4d-devkit 0.51.0rc3__tar.gz → 0.52.0__tar.gz

{x4d_devkit-0.51.0rc3 → x4d_devkit-0.52.0}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.51.0rc3"
+version = "0.52.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.51.0rc3 → x4d_devkit-0.52.0}/tests/test_annotation_document_hash.py

@@ -4,11 +4,13 @@ import dataclasses
 import hashlib
 import random
 
+import pytest
 import rfc8785
 
 from tests.test_annotation_contract import _annotation
 from x4d_devkit.annotation_contract import (
     ANNOTATION_CONTRACT_VERSION,
+    AnnotationContractError,
     ClipAnnotationDocument,
     build_clip_annotations,
     parse_clip_annotations,
@@ -86,3 +88,24 @@ def test_document_hash_is_not_part_of_document_equality():
     assert built == parsed == plain
     assert "_document_hash" not in {field.name for field in dataclasses.fields(built)}
     assert built.to_dict()["contract_version"] == ANNOTATION_CONTRACT_VERSION
+
+
+def test_parse_reuses_only_documents_this_module_verified():
+    built = build_clip_annotations("clip-a", "base_link", _random_rows(random.Random(3), 4))
+    assert parse_clip_annotations(built) is built
+    assert parse_clip_annotations(parse_clip_annotations(built.to_dict())) is not built
+
+    forged = ClipAnnotationDocument(
+        clip_id=built.clip_id,
+        annotation_frame_id=built.annotation_frame_id,
+        annotation_revision="sha256:" + "0" * 64,
+        annotations=built.annotations,
+    )
+    forged.document_hash()  # caching the hash must not mark the document verified
+    with pytest.raises(AnnotationContractError) as error:
+        parse_clip_annotations(forged)
+    assert error.value.code == "annotation_revision_mismatch"
+
+    replaced = dataclasses.replace(built, annotation_revision="sha256:" + "1" * 64)
+    with pytest.raises(AnnotationContractError):
+        parse_clip_annotations(replaced)

x4d_devkit-0.52.0/tests/test_image_conditional_rules.py

@@ -0,0 +1,328 @@
+"""Closed conditional attribute rules, English terms and description coverage (#220)."""
+
+from __future__ import annotations
+
+import copy
+
+import pytest
+
+from x4d_devkit._image_contract import ImageContractError, fingerprint
+from x4d_devkit.image_clip import build_image_identity, parse_image_clip
+from x4d_devkit.image_schema import parse_image_schema_body
+from tests.image_fixtures import clip_payload, schema_body
+
+
+def enum(attribute_id, values, **extra):
+    return {
+        "id": attribute_id,
+        "display_name": attribute_id,
+        "type": "enum",
+        "required": False,
+        "scopes": ["object"],
+        "values": [{"id": value, "display_name": value} for value in values],
+        **extra,
+    }
+
+
+def boolean(attribute_id):
+    return {
+        "id": attribute_id,
+        "display_name": attribute_id,
+        "type": "boolean",
+        "required": False,
+        "scopes": ["object"],
+        "values": [],
+    }
+
+
+def directions():
+    return {
+        "id": "occlusion_directions",
+        "display_name": "occlusion directions",
+        "type": "enum_set",
+        "required": False,
+        "scopes": ["object"],
+        "values": [
+            {"id": side, "display_name": side} for side in ("top", "bottom", "left", "right")
+        ],
+        "min_items": 1,
+        "max_items": 4,
+    }
+
+
+SIGNAL_RULES = [
+    {
+        "id": "head_facts",
+        "attributes": ["head_type", "occlusion"],
+        "required": ["head_type", "occlusion"],
+    },
+    {
+        "id": "arrow",
+        "when": {"attribute": "head_type", "equals": "arrow"},
+        "attributes": ["arrow_direction"],
+        "required": ["arrow_direction"],
+    },
+    {
+        "id": "damaged",
+        "when": {"attribute": "head_type", "in": ["countdown", "countdown_damaged"]},
+        "attributes": ["digit_unclear"],
+        "required": ["digit_unclear"],
+    },
+    {
+        "id": "digit_countdown",
+        "when": {"attribute": "head_type", "equals": "countdown"},
+        "attributes": ["digit"],
+        "required": ["digit"],
+    },
+    {
+        "id": "digit_damaged_known",
+        "when": {
+            "all": [
+                {"attribute": "head_type", "equals": "countdown_damaged"},
+                {"attribute": "digit_unclear", "equals": False},
+            ]
+        },
+        "attributes": ["digit"],
+        "required": ["digit"],
+    },
+    {
+        "id": "digit_optional_when_unclear",
+        "when": {
+            "all": [
+                {"attribute": "head_type", "equals": "countdown_damaged"},
+                {"attribute": "digit_unclear", "equals": True},
+            ]
+        },
+        "attributes": ["digit"],
+        "required": [],
+    },
+    {
+        "id": "occluded",
+        "when": {"attribute": "occlusion", "equals": True},
+        "attributes": ["occlusion_directions", "occlusion_ratio"],
+        "required": ["occlusion_directions", "occlusion_ratio"],
+    },
+]
+
+
+def signal_category(rules=None):
+    return {
+        "id": "box",
+        "display_name": "Signal head",
+        "geometry_type": "box_2d",
+        "color": "#112233",
+        "attributes": [
+            enum("head_type", ["round", "arrow", "countdown", "countdown_damaged"]),
+            enum("arrow_direction", ["up", "left"]),
+            enum("digit", [str(digit) for digit in range(10)]),
+            boolean("digit_unclear"),
+            boolean("occlusion"),
+            directions(),
+            enum("occlusion_ratio", ["low", "medium", "high"]),
+        ],
+        "rules": copy.deepcopy(SIGNAL_RULES if rules is None else rules),
+    }
+
+
+def body(category=None, description_fields=None):
+    value = schema_body()
+    value["categories"][1] = category or signal_category()
+    if description_fields is not None:
+        value["task_views"][1]["category_ids"] = ["box"]
+        value["task_views"][1]["description_fields"] = description_fields
+    return value
+
+
+def box(object_id, attributes):
+    return {
+        "id": object_id,
+        "image_id": "image_a",
+        "view_id": "objects",
+        "category_id": "box",
+        "geometry": {
+            "geometry_type": "box_2d",
+            "box": {"x_min": 10, "y_min": 20, "x_max": 30, "y_max": 40},
+        },
+        "attributes": attributes,
+        "attribute_ranges": [],
+    }
+
+
+def clip(schema, objects, *, objects_state="complete", descriptions=(), text_state="unprocessed"):
+    value = clip_payload()
+    value["label_schema"]["body"] = schema
+    value["label_schema"]["identity"]["fingerprint"] = fingerprint(schema)
+    value["image_annotation"]["objects"] = objects
+    value["image_annotation"]["descriptions"] = list(descriptions)
+    states = {"objects": objects_state, "semantics": text_state}
+    for row in value["image_annotation"]["completion"]:
+        row["state"] = states[row["view_id"]]
+    value["identity"] = build_image_identity(value)
+    return parse_image_clip(value)
+
+
+def head(**attributes):
+    return box("head_a", {"occlusion": False, **attributes})
+
+
+@pytest.mark.parametrize(
+    "attributes",
+    [
+        {"head_type": "round"},
+        {"head_type": "arrow", "arrow_direction": "left"},
+        {"head_type": "countdown", "digit_unclear": False, "digit": "4"},
+        {"head_type": "countdown_damaged", "digit_unclear": True},
+        {"head_type": "countdown_damaged", "digit_unclear": True, "digit": "9"},
+        {"head_type": "countdown_damaged", "digit_unclear": False, "digit": "9"},
+        {
+            "head_type": "round",
+            "occlusion": True,
+            "occlusion_directions": ["top", "left"],
+            "occlusion_ratio": "medium",
+        },
+    ],
+)
+def test_completed_heads_satisfy_conditional_rules(attributes):
+    clip(body(), [head(**attributes)])
+
+
+@pytest.mark.parametrize(
+    ("attributes", "code", "attribute"),
+    [
+        ({}, "attribute_required_on_completion", "head_type"),
+        ({"head_type": "arrow"}, "attribute_required_on_completion", "arrow_direction"),
+        ({"head_type": "round", "arrow_direction": "up"}, "attribute_not_applicable", "arrow_direction"),
+        ({"head_type": "countdown", "digit_unclear": False}, "attribute_required_on_completion", "digit"),
+        ({"head_type": "countdown_damaged", "digit_unclear": False}, "attribute_required_on_completion", "digit"),
+        ({"head_type": "round", "digit": "3"}, "attribute_not_applicable", "digit"),
+        ({"head_type": "round", "occlusion": True, "occlusion_ratio": "low"}, "attribute_required_on_completion", "occlusion_directions"),
+        ({"head_type": "round", "occlusion_directions": ["top"]}, "attribute_not_applicable", "occlusion_directions"),
+    ],
+)
+def test_completed_heads_reject_missing_or_leftover_facts(attributes, code, attribute):
+    with pytest.raises(ImageContractError) as error:
+        clip(body(), [head(**attributes)])
+    assert error.value.code == code
+    assert error.value.path == f"image_annotation.objects.head_a.attributes.{attribute}"
+
+
+def test_drafts_may_pause_with_missing_or_leftover_facts_but_values_stay_typed():
+    clip(body(), [head(head_type="round", arrow_direction="up")], objects_state="unprocessed")
+    clip(body(), [box("head_a", {})], objects_state="unprocessed")
+    with pytest.raises(ImageContractError):
+        clip(body(), [head(head_type="round", arrow_direction="sideways")], objects_state="unprocessed")
+    with pytest.raises(ImageContractError):  # enum_set bounds apply to drafts too
+        clip(
+            body(),
+            [head(head_type="round", occlusion=True, occlusion_directions=[])],
+            objects_state="unprocessed",
+        )
+
+
+def test_rules_change_the_schema_fingerprint():
+    plain = parse_image_schema_body(body(signal_category(rules=SIGNAL_RULES[:1])))
+    full = parse_image_schema_body(body())
+    assert plain.identity.fingerprint != full.identity.fingerprint
+
+
+def _rule(**change):
+    rule = copy.deepcopy(SIGNAL_RULES[1])
+    rule.update(change)
+    return rule
+
+
+@pytest.mark.parametrize(
+    "rules",
+    [
+        [],
+        [_rule(attributes=["missing"], required=[])],
+        [_rule(required=["head_type"])],
+        [_rule(attributes=["arrow_direction", "arrow_direction"])],
+        [_rule(when={"attribute": "missing", "equals": "arrow"})],
+        [_rule(when={"attribute": "head_type", "equals": "triangle"})],
+        [_rule(when={"attribute": "head_type", "equals": True})],
+        [_rule(when={"attribute": "occlusion", "equals": "true"})],
+        [_rule(when={"attribute": "head_type", "in": []})],
+        [_rule(when={"attribute": "head_type", "in": ["arrow", "arrow"]})],
+        [_rule(when={"attribute": "head_type", "contains": "arrow"})],
+        [_rule(when={"attribute": "occlusion_directions", "equals": "top"})],
+        [_rule(when={"attribute": "head_type", "equals": "arrow", "in": ["arrow"]})],
+        [_rule(when={"all": [{"any": [{"attribute": "head_type", "equals": "arrow"}]}]})],
+        [_rule(when={"all": []})],
+        [_rule(when="head_type == 'arrow'")],
+        [_rule(), _rule()],
+        [
+            _rule(id="a", when={"attribute": "digit", "equals": "1"}, attributes=["arrow_direction"]),
+            _rule(id="b", when={"attribute": "arrow_direction", "equals": "up"}, attributes=["digit"], required=[]),
+        ],
+    ],
+)
+def test_schema_rejects_open_or_inconsistent_rules(rules):
+    with pytest.raises(ImageContractError):
+        parse_image_schema_body(body(signal_category(rules=rules)))
+
+
+def test_governed_attribute_cannot_also_be_always_required():
+    category = signal_category()
+    category["attributes"][1]["required"] = True
+    with pytest.raises(ImageContractError):
+        parse_image_schema_body(body(category))
+
+
+def test_enum_values_may_declare_english_terms():
+    category = signal_category()
+    category["attributes"][0]["values"][0]["term"] = {"singular": "round light", "plural": "round lights"}
+    category["attributes"][2]["values"][0]["term"] = {"singular": "zero"}
+    parse_image_schema_body(body(category))
+    for term in ({"singular": " "}, {"plural": "lights"}, {"singular": "x", "plural": ""}, {"singular": "x", "other": "y"}):
+        category["attributes"][0]["values"][0]["term"] = term
+        with pytest.raises(ImageContractError):
+            parse_image_schema_body(body(category))
+
+
+TEXT_FIELDS = [
+    {"id": "phrase", "display_name": "Phrase", "required": True, "target": "object"},
+    {"id": "caption", "display_name": "Caption", "required": True, "target": "image"},
+]
+
+
+def text(text_id, target, field, value="text"):
+    return {
+        "id": text_id,
+        "image_id": "image_a",
+        "view_id": "semantics",
+        "target_id": target,
+        "fields": {field: value},
+    }
+
+
+def test_completed_description_scope_covers_every_object_and_the_image():
+    schema = body(description_fields=TEXT_FIELDS)
+    objects = [head(head_type="round"), {**head(head_type="round"), "id": "head_b"}]
+    full = [
+        text("p_a", "head_a", "phrase"),
+        text("p_b", "head_b", "phrase"),
+        text("caption", None, "caption"),
+    ]
+    clip(schema, objects, descriptions=full, text_state="complete")
+    clip(schema, objects, descriptions=full[:1], text_state="unprocessed")
+    for missing in range(3):
+        partial = full[:missing] + full[missing + 1 :]
+        with pytest.raises(ImageContractError) as error:
+            clip(schema, objects, descriptions=partial, text_state="complete")
+        assert error.value.code == "description_coverage_incomplete"
+
+
+def test_description_targets_are_unique_and_fields_match_their_target():
+    schema = body(description_fields=TEXT_FIELDS)
+    objects = [head(head_type="round")]
+    with pytest.raises(ImageContractError):  # two phrases for one object
+        clip(schema, objects, descriptions=[text("p1", "head_a", "phrase"), text("p2", "head_a", "phrase")])
+    with pytest.raises(ImageContractError):  # caption field on an object description
+        clip(schema, objects, descriptions=[text("p1", "head_a", "caption")])
+    with pytest.raises(ImageContractError):  # phrase on the image-level description
+        clip(schema, objects, descriptions=[text("c", None, "phrase")])
+    with pytest.raises(ImageContractError):
+        parse_image_schema_body(
+            body(description_fields=[{**TEXT_FIELDS[0], "target": "region"}])
+        )

x4d_devkit-0.52.0/tests/test_image_enum_set.py

@@ -0,0 +1,178 @@
+"""Controlled multi-select (`enum_set`) image attributes (x4d-devkit #223)."""
+
+from __future__ import annotations
+
+import copy
+
+import pytest
+
+from x4d_devkit._image_contract import ImageContractError, fingerprint
+from x4d_devkit.image_clip import build_image_identity, parse_image_clip
+from x4d_devkit.image_schema import parse_image_schema_body
+from x4d_devkit.image_schema_upgrade import additive_image_schema_changes
+from tests.image_fixtures import clip_payload, schema_body
+
+DIRECTIONS = [
+    {"id": "top", "display_name": "上"},
+    {"id": "bottom", "display_name": "下"},
+    {"id": "left", "display_name": "左"},
+    {"id": "right", "display_name": "右"},
+]
+
+
+def directions_attribute(**overrides):
+    attribute = {
+        "id": "occlusion_directions",
+        "display_name": "遮挡方向",
+        "type": "enum_set",
+        "required": False,
+        "scopes": ["object"],
+        "values": copy.deepcopy(DIRECTIONS),
+        "min_items": 0,
+        "max_items": 4,
+    }
+    attribute.update(overrides)
+    return attribute
+
+
+def body_with(attribute):
+    body = schema_body()
+    body["categories"][1]["attributes"] = [attribute]
+    return body
+
+
+def box_object(attributes):
+    return {
+        "id": "box_a",
+        "image_id": "image_a",
+        "view_id": "objects",
+        "category_id": "box",
+        "geometry": {
+            "geometry_type": "box_2d",
+            "box": {"x_min": 10, "y_min": 20, "x_max": 30, "y_max": 40},
+        },
+        "attributes": attributes,
+        "attribute_ranges": [],
+    }
+
+
+def clip_with(attribute, attributes):
+    value = clip_payload()
+    body = body_with(attribute)
+    value["label_schema"]["body"] = body
+    value["label_schema"]["identity"]["fingerprint"] = fingerprint(body)
+    value["image_annotation"]["objects"] = [box_object(attributes)]
+    value["identity"] = build_image_identity(value)
+    return value
+
+
+def test_schema_accepts_bounded_enum_set():
+    parsed = parse_image_schema_body(body_with(directions_attribute()))
+    attribute = parsed.to_dict()["categories"][1]["attributes"][0]
+    assert (attribute["type"], attribute["min_items"], attribute["max_items"]) == ("enum_set", 0, 4)
+
+
+@pytest.mark.parametrize(
+    "change",
+    [
+        {"values": []},
+        {"values": [DIRECTIONS[0], DIRECTIONS[0]]},
+        {"min_items": 2, "max_items": 1},
+        {"max_items": 5},
+        {"max_items": 0},
+        {"min_items": -1},
+        {"min_items": True},
+        {"max_items": 2.0},
+        {"scopes": ["object", "segment"]},
+        "missing-bounds",
+        "bounds-on-enum",
+    ],
+)
+def test_schema_rejects_invalid_enum_set_declarations(change):
+    if change == "missing-bounds":
+        attribute = directions_attribute()
+        del attribute["max_items"]
+    elif change == "bounds-on-enum":
+        attribute = directions_attribute(type="enum")
+    else:
+        attribute = directions_attribute(**change)
+    body = body_with(attribute)
+    if change == {"scopes": ["object", "segment"]}:
+        body["categories"][0]["attributes"].append(attribute)
+        body["categories"][1]["attributes"] = []
+    with pytest.raises(ImageContractError):
+        parse_image_schema_body(body)
+
+
+@pytest.mark.parametrize(
+    "value",
+    [[], ["top"], ["top", "left"], ["top", "bottom", "left", "right"]],
+)
+def test_clip_accepts_declared_order_sets_and_keeps_them_exactly(value):
+    clip = parse_image_clip(clip_with(directions_attribute(), {"occlusion_directions": value}))
+    stored = clip.to_dict()["image_annotation"]["objects"][0]["attributes"]
+    assert stored == {"occlusion_directions": value}
+
+
+def test_missing_and_empty_set_are_distinct_results():
+    missing = parse_image_clip(clip_with(directions_attribute(), {}))
+    empty = parse_image_clip(clip_with(directions_attribute(), {"occlusion_directions": []}))
+    assert (
+        missing.to_dict()["identity"]["annotation_revision"]
+        != empty.to_dict()["identity"]["annotation_revision"]
+    )
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        ["left", "top"],  # not Schema declaration order: never re-sorted silently
+        ["top", "top"],
+        ["up"],
+        "top",
+        "top,left",
+        [1],
+        [None],
+        [["top"]],
+        {"top": True},
+        None,
+        True,
+    ],
+)
+def test_clip_rejects_invalid_set_values_without_coercion(value):
+    with pytest.raises(ImageContractError):
+        parse_image_clip(clip_with(directions_attribute(), {"occlusion_directions": value}))
+
+
+def test_clip_enforces_item_bounds_and_required_presence():
+    bounded = directions_attribute(min_items=1, max_items=2)
+    with pytest.raises(ImageContractError):
+        parse_image_clip(clip_with(bounded, {"occlusion_directions": []}))
+    with pytest.raises(ImageContractError):
+        parse_image_clip(clip_with(bounded, {"occlusion_directions": ["top", "bottom", "left"]}))
+    parse_image_clip(clip_with(bounded, {"occlusion_directions": ["bottom", "right"]}))
+
+    required = directions_attribute(required=True)
+    with pytest.raises(ImageContractError):
+        parse_image_clip(clip_with(required, {}))
+    parse_image_clip(clip_with(required, {"occlusion_directions": []}))
+
+
+def test_schema_upgrade_may_add_values_but_must_keep_existing_order():
+    before = body_with(directions_attribute())
+    after = copy.deepcopy(before)
+    after["version"] = "1.1.0"
+    after["categories"][1]["attributes"][0]["values"].insert(
+        2, {"id": "front", "display_name": "前"}
+    )
+    changes = additive_image_schema_changes(before, after)
+    assert {"category_id": "box", "attribute_id": "occlusion_directions", "value_id": "front"} in changes[
+        "added_enum_values"
+    ]
+
+    reordered = copy.deepcopy(before)
+    reordered["version"] = "1.1.0"
+    values = reordered["categories"][1]["attributes"][0]["values"]
+    values[0], values[1] = values[1], values[0]
+    with pytest.raises(ImageContractError):
+        additive_image_schema_changes(before, reordered)

{x4d_devkit-0.51.0rc3 → x4d_devkit-0.52.0}/tests/test_parse_equivalence.py

@@ -836,9 +836,10 @@ def test_annotation_entry_points_canonicalize_rows_only_once(monkeypatch, entry)
         assert annotation_revision(raw["clip_id"], raw["annotation_frame_id"],
                                    raw["annotations"]) == raw["annotation_revision"]
     # Revision and document hash share one serialization of every row; no call
-    # re-serializes the row list or a complete payload.
+    # re-serializes the row list or a complete payload. A document this module
+    # already verified is returned without serializing anything.
     row_calls = [value for value in calls if isinstance(value, dict)]
-    assert row_calls == raw["annotations"]
+    assert row_calls == ([] if entry == "parsed-document" else raw["annotations"])
     assert all(isinstance(value, str) for value in calls if not isinstance(value, dict))
 
 

{x4d_devkit-0.51.0rc3 → x4d_devkit-0.52.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.51.0rc3"
+    assert x4d_devkit.__version__ == "0.52.0"
 
 
 def test_loader_exposes_and_enforces_only_current_schema(tmp_path):

{x4d_devkit-0.51.0rc3 → x4d_devkit-0.52.0}/x4d_devkit/annotation_contract.py

@@ -38,6 +38,13 @@ _DOCUMENT_FIELDS = {
     "annotations",
 }
 _REVISION_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
+# Set only by build/parse after canonical verification; never by document_hash().
+_VERIFIED_MARK = "_canonical_verified"
+
+
+def _mark_verified(document: "ClipAnnotationDocument", document_hash: str) -> None:
+    object.__setattr__(document, "_document_hash", document_hash)
+    object.__setattr__(document, _VERIFIED_MARK, True)
 _FRAME_ID_RE = re.compile(r"^[a-z][a-z0-9_]{0,63}$")
 
 
@@ -148,7 +155,7 @@ def build_clip_annotations(
         annotation_revision=revision,
         annotations=tuple(canonical),
     )
-    object.__setattr__(document, "_document_hash", document_hash)
+    _mark_verified(document, document_hash)
     return document
 
 
@@ -159,6 +166,9 @@ def parse_clip_annotations(
 
     i_json_checked = False
     if isinstance(value, ClipAnnotationDocument):
+        if value.__dict__.get(_VERIFIED_MARK) is True:
+            # Built or parsed by this module: already canonical and verified.
+            return value
         data = value.to_dict()
     elif isinstance(value, Mapping):
         data = dict(value)
@@ -244,7 +254,7 @@ def parse_clip_annotations(
         annotation_revision=revision,
         annotations=tuple(annotations),
     )
-    object.__setattr__(document, "_document_hash", document_hash)
+    _mark_verified(document, document_hash)
     return document