devagent-physical-engine 0.10.0__py3-none-any.whl

devagent_physical_engine/trajectory_qualification.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from hashlib import sha256
+import json
+from math import isfinite
+from time import perf_counter
+from typing import Any, Mapping, Sequence
+
+from .physical_motion import MotionExecutionMetrics, PhysicalMotionPlan
+from .robot_platform import QualificationState
+from .simulation_platform import RobotSimulationAdapter
+from .twin import TwinSpec
+
+
+class TrajectoryQualificationError(RuntimeError):
+    pass
+
+
+def _hash(payload: object) -> str:
+    text = json.dumps(
+        payload, sort_keys=True, separators=(",", ":"), allow_nan=False
+    )
+    return sha256(text.encode("utf-8")).hexdigest()
+
+
+@dataclass(frozen=True, slots=True)
+class TrajectoryQualificationCase:
+    case_id: str
+    motion: PhysicalMotionPlan
+    reset_state: Mapping[str, Any]
+    max_tracking_error_rad: float
+
+    def __post_init__(self) -> None:
+        if not self.case_id.strip():
+            raise TrajectoryQualificationError("trajectory_qualification_case_id_required")
+        threshold = float(self.max_tracking_error_rad)
+        if not isfinite(threshold) or threshold <= 0:
+            raise TrajectoryQualificationError("trajectory_tracking_threshold_invalid")
+        try:
+            json.dumps(self.reset_state, sort_keys=True, allow_nan=False)
+        except (TypeError, ValueError) as exc:
+            raise TrajectoryQualificationError(
+                "trajectory_reset_state_not_json_safe"
+            ) from exc
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "case_id": self.case_id,
+            "motion_hash": self.motion.fingerprint,
+            "reset_state": dict(self.reset_state),
+            "max_tracking_error_rad": self.max_tracking_error_rad,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class TrajectoryQualificationResult:
+    case: TrajectoryQualificationCase
+    passed: bool
+    metrics: MotionExecutionMetrics
+    failure_code: str | None
+    duration_ms: float
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = {
+            "case": self.case.to_dict(),
+            "passed": self.passed,
+            "metrics": self.metrics.to_dict(),
+            "failure_code": self.failure_code,
+            "duration_ms": round(self.duration_ms, 6),
+        }
+        payload["evidence_hash"] = _hash(payload)
+        return payload
+
+
+@dataclass(frozen=True, slots=True)
+class TrajectoryQualificationReport:
+    run_id: str
+    adapter_id: str
+    adapter_qualification_at_start: str
+    scope: str
+    total_cases: int
+    passed_cases: int
+    corpus_hash: str
+    promotion_candidate: bool
+    physical_qualification: bool
+    commissioning_qualification: bool
+    results: tuple[TrajectoryQualificationResult, ...]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "run_id": self.run_id,
+            "adapter_id": self.adapter_id,
+            "adapter_qualification_at_start": self.adapter_qualification_at_start,
+            "scope": self.scope,
+            "total_cases": self.total_cases,
+            "passed_cases": self.passed_cases,
+            "corpus_hash": self.corpus_hash,
+            "promotion_candidate": self.promotion_candidate,
+            "physical_qualification": self.physical_qualification,
+            "commissioning_qualification": self.commissioning_qualification,
+            "real_execution_allowed": False,
+            "results": [item.to_dict() for item in self.results],
+        }
+
+
+class TrajectoryRuntimeQualificationRunner:
+    """Qualify only the compiled-trajectory execution/measurement path."""
+
+    def run(
+        self,
+        *,
+        adapter: RobotSimulationAdapter,
+        twin: TwinSpec,
+        cases: Sequence[TrajectoryQualificationCase],
+    ) -> TrajectoryQualificationReport:
+        if not cases:
+            raise TrajectoryQualificationError("trajectory_qualification_empty")
+        if len(cases) > 100:
+            raise TrajectoryQualificationError("trajectory_qualification_case_limit")
+        descriptor = adapter.descriptor
+        if descriptor.qualification not in {
+            QualificationState.EXPERIMENTAL,
+            QualificationState.QUALIFIED,
+        }:
+            raise TrajectoryQualificationError("trajectory_adapter_not_runnable")
+        if twin.robot_profile_key not in descriptor.robot_profile_keys:
+            raise TrajectoryQualificationError("trajectory_adapter_robot_mismatch")
+        for case in cases:
+            if case.motion.robot_profile_key != twin.robot_profile_key:
+                raise TrajectoryQualificationError("trajectory_case_robot_mismatch")
+            if case.motion.twin_hash != twin.fingerprint:
+                raise TrajectoryQualificationError("trajectory_case_twin_hash_mismatch")
+
+        health = adapter.doctor(robot_profile_key=twin.robot_profile_key)
+        if not health.ready:
+            raise TrajectoryQualificationError(
+                f"trajectory_adapter_doctor_failed:{health.code}"
+            )
+
+        results: list[TrajectoryQualificationResult] = []
+        try:
+            adapter.prepare(twin=twin)
+            for case in cases:
+                started = perf_counter()
+                failure: str | None = None
+                try:
+                    adapter.reset(case_id=case.case_id, state=case.reset_state)
+                    metrics = adapter.execute_motion(motion=case.motion)
+                    tracking = metrics.max_tracking_error_rad
+                    passed = (
+                        metrics.success
+                        and tracking is not None
+                        and tracking <= case.max_tracking_error_rad
+                    )
+                    if not passed:
+                        failure = (
+                            "tracking_measurement_missing"
+                            if tracking is None
+                            else "trajectory_runtime_threshold_failed"
+                        )
+                except Exception as exc:
+                    failure = f"trajectory_runner_error:{type(exc).__name__}"
+                    metrics = MotionExecutionMetrics(
+                        success=False,
+                        observed_duration_s=None,
+                        planned_duration_s=case.motion.planned_duration_s,
+                        planned_joint_travel_rad=case.motion.joint_travel_rad,
+                        failure_codes=(failure,),
+                        metrics_origin="trajectory_qualification_runner",
+                    )
+                    passed = False
+                results.append(
+                    TrajectoryQualificationResult(
+                        case=case,
+                        passed=passed,
+                        metrics=metrics,
+                        failure_code=failure,
+                        duration_ms=(perf_counter() - started) * 1000.0,
+                    )
+                )
+        finally:
+            adapter.stop()
+
+        corpus_hash = _hash([case.to_dict() for case in cases])
+        timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
+        passed_cases = sum(item.passed for item in results)
+        return TrajectoryQualificationReport(
+            run_id=f"trajectory-runtime-{timestamp}",
+            adapter_id=descriptor.adapter_id,
+            adapter_qualification_at_start=descriptor.qualification.value,
+            scope="trajectory_runtime_only",
+            total_cases=len(results),
+            passed_cases=passed_cases,
+            corpus_hash=corpus_hash,
+            promotion_candidate=passed_cases == len(results),
+            physical_qualification=False,
+            commissioning_qualification=False,
+            results=tuple(results),
+        )