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

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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.41.0rc1"
+version = "0.41.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.41.0rc1 → x4d_devkit-0.41.0rc2}/tests/test_preannotation_client.py

@@ -50,7 +50,7 @@ def _service() -> dict:
 
 def _run(*, status: str = "queued", reused: bool = False) -> dict:
     succeeded = status == "succeeded"
-    return {
+    result = {
         "run_id": "preann-run-1",
         "request_identity": _digest("a"),
         "project_id": 7,
@@ -76,7 +76,34 @@ def _run(*, status: str = "queued", reused: bool = False) -> dict:
         "created_at": "2026-08-18T08:00:00Z",
         "updated_at": "2026-08-18T08:02:00Z",
         "reused": reused,
+        "attempt_number": 1,
+        "attempt_count": 1,
+        "latest_attempt_id": "preann-run-1",
+        "is_latest_attempt": True,
+        "retry_of_run_id": None,
     }
+    result["attempts"] = [
+        {
+            key: copy.deepcopy(result[key])
+            for key in (
+                "run_id",
+                "attempt_number",
+                "retry_of_run_id",
+                "status",
+                "progress",
+                "error",
+                "candidate_id",
+                "temporal_workflow_id",
+                "actor_id",
+                "started_at",
+                "completed_at",
+                "cancellation_requested_at",
+                "created_at",
+                "updated_at",
+            )
+        }
+    ]
+    return result
 
 
 def _portable_candidate() -> dict:
@@ -144,7 +171,10 @@ def test_control_plane_uses_typed_service_run_cancel_and_candidate_contracts():
         requests.append(request)
         if request.url.path == "/api/v1/preannotation/services":
             return httpx.Response(200, json=[_service()])
-        if request.url.path == "/api/v1/preannotation/runs" and request.method == "POST":
+        if (
+            request.url.path == "/api/v1/preannotation/runs"
+            and request.method == "POST"
+        ):
             return httpx.Response(202, json=_run())
         if request.url.path == "/api/v1/preannotation/runs" and request.method == "GET":
             return httpx.Response(200, json=[_run(status="succeeded")])
@@ -172,9 +202,7 @@ def test_control_plane_uses_typed_service_run_cancel_and_candidate_contracts():
             profile_id="centerpoint-track-v1",
             config={"score_threshold": 0.4},
         )
-        runs = client.preannotation.list_runs(
-            project_id=7, clip_id="clip-1", limit=10
-        )
+        runs = client.preannotation.list_runs(project_id=7, clip_id="clip-1", limit=10)
         fetched = client.preannotation.get_run("preann-run-1")
         cancellation = client.preannotation.cancel_run("preann-run-1")
         candidate = client.preannotation.get_candidate(_digest("d"))
@@ -260,3 +288,72 @@ def test_create_run_rejects_non_i_json_config_before_request():
                 profile_id="centerpoint-track-v1",
                 config={"threshold": float("nan")},
             )
+
+
+def _retried_run():
+    previous = _run(status="failed")["attempts"][0]
+    result = _run(status="succeeded")
+    result.update(
+        run_id="preann-run-2",
+        attempt_number=2,
+        attempt_count=2,
+        latest_attempt_id="preann-run-2",
+        retry_of_run_id="preann-run-1",
+    )
+    result["attempts"] = [
+        previous,
+        {key: copy.deepcopy(result[key]) for key in previous},
+    ]
+    return result
+
+
+def test_retry_history_round_trip_and_historical_run():
+    payload = _retried_run()
+    parsed = PlatformPreannotationRun.model_validate(payload)
+    assert parsed.attempt_count == 2
+    assert parsed.attempts[0].status == PlatformPreannotationRunStatus.FAILED
+    assert parsed.attempts[1].candidate_id == parsed.candidate_id
+    assert (
+        PlatformPreannotationRun.model_validate_json(parsed.model_dump_json()) == parsed
+    )
+    payload.update(payload["attempts"][0])
+    payload["is_latest_attempt"] = False
+    old = PlatformPreannotationRun.model_validate(payload)
+    assert old.run_id == "preann-run-1" and old.latest_attempt_id == "preann-run-2"
+    payload["attempts"] = []
+    assert PlatformPreannotationRun.model_validate(payload).attempt_count == 2
+
+
+@pytest.mark.parametrize(
+    "field,value",
+    [
+        ("attempt_count", 1),
+        ("attempt_number", 1),
+        ("attempt_number", True),
+        ("latest_attempt_id", "preann-missing"),
+        ("is_latest_attempt", False),
+        ("is_latest_attempt", 1),
+        ("retry_of_run_id", None),
+        ("attempts", [_run(status="failed")["attempts"][0]]),
+    ],
+)
+def test_inconsistent_attempt_identity_is_rejected(field, value):
+    payload = _retried_run()
+    payload[field] = value
+    with pytest.raises(ValidationError):
+        PlatformPreannotationRun.model_validate(payload)
+
+
+@pytest.mark.parametrize("mutation", ["unknown", "link", "order", "state"])
+def test_malformed_attempt_history_is_rejected(mutation):
+    payload = _retried_run()
+    if mutation == "unknown":
+        payload["attempts"][0]["unknown_field"] = True
+    elif mutation == "link":
+        payload["attempts"][1]["retry_of_run_id"] = "another-run"
+    elif mutation == "order":
+        payload["attempts"].reverse()
+    else:
+        payload["attempts"][1]["progress"]["stage"] = "different-state"
+    with pytest.raises(ValidationError):
+        PlatformPreannotationRun.model_validate(payload)

{x4d_devkit-0.41.0rc1 → x4d_devkit-0.41.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.41.0rc1"
+    assert x4d_devkit.__version__ == "0.41.0rc2"
 
 
 def test_loader_exposes_and_enforces_only_current_schema(tmp_path):

{x4d_devkit-0.41.0rc1 → x4d_devkit-0.41.0rc2}/x4d_devkit/client/preannotation.py

@@ -86,7 +86,53 @@ class PlatformPreannotationService(_ControlPlaneModel):
         return value
 
 
-class PlatformPreannotationRun(_ControlPlaneModel):
+class PlatformPreannotationRunAttempt(_ControlPlaneModel):
+    """One immutable attempt identity and its current execution state."""
+
+    run_id: str
+    attempt_number: int = Field(ge=1, strict=True)
+    retry_of_run_id: str | None
+    status: PlatformPreannotationRunStatus
+    progress: PreannotationRunProgress
+    error: PreannotationRunError | None
+    candidate_id: str | None
+    temporal_workflow_id: str
+    actor_id: int | None = Field(gt=0, strict=True)
+    started_at: datetime | None
+    completed_at: datetime | None
+    cancellation_requested_at: datetime | None
+    created_at: datetime
+    updated_at: datetime
+
+    @field_validator("run_id", "retry_of_run_id", mode="before")
+    @classmethod
+    def validate_attempt_id(cls, value: Any, info: Any) -> str | None:
+        if value is None and info.field_name == "retry_of_run_id":
+            return None
+        return _protocol_token(value, path="preannotation attempt identifier")
+
+    @field_validator("candidate_id", mode="before")
+    @classmethod
+    def validate_attempt_candidate(cls, value: Any) -> str | None:
+        return None if value is None else _sha256(value, path="attempt.candidate_id")
+
+    @field_validator("temporal_workflow_id", mode="before")
+    @classmethod
+    def validate_attempt_workflow(cls, value: Any) -> str:
+        return _canonical_string(value, path="attempt.temporal_workflow_id")
+
+    @model_validator(mode="after")
+    def validate_attempt_result(self) -> "PlatformPreannotationRunAttempt":
+        if (self.status == PlatformPreannotationRunStatus.SUCCEEDED) != (
+            self.candidate_id is not None
+        ):
+            raise ValueError("only succeeded attempts must contain candidate_id")
+        if (self.attempt_number == 1) != (self.retry_of_run_id is None):
+            raise ValueError("only the first attempt has no retry predecessor")
+        return self
+
+
+class PlatformPreannotationRun(PlatformPreannotationRunAttempt):
     """One durable X-4D preannotation run."""
 
     run_id: str
@@ -99,6 +145,10 @@ class PlatformPreannotationRun(_ControlPlaneModel):
     profile_id: str
     pipeline_identity: str
     checkpoint_identity: str
+    attempt_count: int = Field(ge=1, strict=True)
+    latest_attempt_id: str
+    is_latest_attempt: bool = Field(strict=True)
+    attempts: list[PlatformPreannotationRunAttempt]
     status: PlatformPreannotationRunStatus
     progress: PreannotationRunProgress
     error: PreannotationRunError | None
@@ -117,7 +167,9 @@ class PlatformPreannotationRun(_ControlPlaneModel):
     def validate_project_id(cls, value: Any) -> int:
         return _positive_int(value, path="preannotation run.project_id")
 
-    @field_validator("run_id", "service_id", "profile_id", mode="before")
+    @field_validator(
+        "run_id", "service_id", "profile_id", "latest_attempt_id", mode="before"
+    )
     @classmethod
     def validate_protocol_id(cls, value: Any) -> str:
         return _protocol_token(value, path="preannotation run identifier")
@@ -169,9 +221,48 @@ class PlatformPreannotationRun(_ControlPlaneModel):
     def succeeded_run_has_candidate(self) -> "PlatformPreannotationRun":
         if self.status == PlatformPreannotationRunStatus.SUCCEEDED:
             if self.candidate_id is None:
-                raise ValueError("succeeded preannotation run must contain candidate_id")
+                raise ValueError(
+                    "succeeded preannotation run must contain candidate_id"
+                )
         elif self.candidate_id is not None:
-            raise ValueError("only a succeeded preannotation run may contain candidate_id")
+            raise ValueError(
+                "only a succeeded preannotation run may contain candidate_id"
+            )
+        return self
+
+    @model_validator(mode="after")
+    def validate_attempt_history(self) -> "PlatformPreannotationRun":
+        if self.attempt_number > self.attempt_count:
+            raise ValueError("attempt_number must not exceed attempt_count")
+        if self.is_latest_attempt != (self.attempt_number == self.attempt_count):
+            raise ValueError("latest attempt flag disagrees with attempt count")
+        if self.is_latest_attempt != (self.run_id == self.latest_attempt_id):
+            raise ValueError("latest attempt flag disagrees with run identity")
+        # The list endpoint explicitly omits expansion; detail includes history.
+        if not self.attempts:
+            return self
+        if len(self.attempts) != self.attempt_count:
+            raise ValueError("attempt_count must match complete attempt history")
+        ids = [attempt.run_id for attempt in self.attempts]
+        if len(set(ids)) != len(ids) or self.run_id not in ids:
+            raise ValueError("attempt history must uniquely contain this run")
+        for number, attempt in enumerate(self.attempts, 1):
+            predecessor = None if number == 1 else ids[number - 2]
+            if (
+                attempt.attempt_number != number
+                or attempt.retry_of_run_id != predecessor
+            ):
+                raise ValueError(
+                    "attempt history must be ordered with exact retry links"
+                )
+        if self.latest_attempt_id != ids[-1] or self.is_latest_attempt != (
+            self.run_id == self.latest_attempt_id
+        ):
+            raise ValueError("latest attempt identity disagrees with history")
+        current = self.attempts[ids.index(self.run_id)]
+        for field in PlatformPreannotationRunAttempt.model_fields:
+            if getattr(current, field) != getattr(self, field):
+                raise ValueError(f"current attempt disagrees with history: {field}")
         return self
 
 
@@ -384,13 +475,17 @@ class PreannotationAPI:
         payload = self._get("/preannotation/runs", params=params)
         if type(payload) is not list:
             raise TypeError("preannotation runs response must be a list")
-        results = tuple(PlatformPreannotationRun.model_validate(item) for item in payload)
+        results = tuple(
+            PlatformPreannotationRun.model_validate(item) for item in payload
+        )
         if any(
             item.project_id != project_id
             or (clip_id is not None and item.clip_id != clip_id)
             for item in results
         ):
-            raise ValueError("preannotation runs response is outside the requested scope")
+            raise ValueError(
+                "preannotation runs response is outside the requested scope"
+            )
         return results
 
     def get_run(self, run_id: str) -> PlatformPreannotationRun:
@@ -401,7 +496,9 @@ class PreannotationAPI:
             self._get(f"/preannotation/runs/{run_id}")
         )
         if result.run_id != run_id:
-            raise ValueError("preannotation run response identity does not match request")
+            raise ValueError(
+                "preannotation run response identity does not match request"
+            )
         return result
 
     def cancel_run(self, run_id: str) -> PlatformPreannotationCancellation:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.41.0rc1
+Version: 0.41.0rc2
 Summary: Official X-4D external SDK and CLI for datasets, platform APIs, training bridges, and automation
 Author: windzu
 License-Expression: Apache-2.0