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

devagent_physical_engine/twin_builder.py

@@ -0,0 +1,309 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from enum import Enum
+from typing import Any, Mapping
+
+from .engineering_request import ValidatedEngineeringRequest
+from .robot_platform import RobotProfileRegistry
+from .twin import (
+    ControllerModel,
+    EvidenceOrigin,
+    EvidenceValue,
+    FrameTransform,
+    GeometryKind,
+    GeometrySpec,
+    Pose3D,
+    RealityCalibrationEvidence,
+    SensorSpec,
+    ToolSpec,
+    TwinEntity,
+    TwinSpec,
+    TwinValidationReport,
+    TwinValidator,
+    UncertaintyModel,
+    evidence_summary,
+)
+
+
+class TwinBuildState(str, Enum):
+    NEEDS_INFORMATION = "needs_information"
+    READY_FOR_PLANNING = "ready_for_planning"
+    READY_FOR_PHYSICS = "ready_for_physics"
+    REALITY_CALIBRATED = "reality_calibrated"
+    INVALID = "invalid"
+
+
+@dataclass(frozen=True, slots=True)
+class TwinInformationRequest:
+    code: str
+    question: str
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class TwinBuildInputs:
+    """Customer/site information already known to DevAgent.
+
+    The builder intentionally has no implicit dimensions, frames, TCP, physics,
+    or latency defaults. Unknown engineering-critical data remains unknown.
+    """
+
+    robot_base_pose: Pose3D | None = None
+    entities: tuple[TwinEntity, ...] = ()
+    tool: ToolSpec | None = None
+    frames: tuple[FrameTransform, ...] = ()
+    sensors: tuple[SensorSpec, ...] = ()
+    controller: ControllerModel = ControllerModel()
+    uncertainty: UncertaintyModel = UncertaintyModel()
+    reality: RealityCalibrationEvidence = RealityCalibrationEvidence()
+    metadata: Mapping[str, Any] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class TwinBuildResult:
+    twin: TwinSpec
+    validation: TwinValidationReport
+    state: TwinBuildState
+    information_requests: tuple[TwinInformationRequest, ...]
+    evidence_origins: Mapping[str, int]
+
+    @property
+    def planning_allowed(self) -> bool:
+        return self.state in {
+            TwinBuildState.READY_FOR_PLANNING,
+            TwinBuildState.READY_FOR_PHYSICS,
+            TwinBuildState.REALITY_CALIBRATED,
+        }
+
+    @property
+    def physics_allowed(self) -> bool:
+        return self.state in {
+            TwinBuildState.READY_FOR_PHYSICS,
+            TwinBuildState.REALITY_CALIBRATED,
+        }
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "state": self.state.value,
+            "twin_id": self.twin.twin_id,
+            "twin_hash": self.validation.twin_hash,
+            "validation": self.validation.to_dict(),
+            "information_requests": [
+                {
+                    "code": item.code,
+                    "question": item.question,
+                    "reason": item.reason,
+                }
+                for item in self.information_requests
+            ],
+            "evidence_origins": dict(self.evidence_origins),
+            "planning_allowed": self.planning_allowed,
+            "physics_allowed": self.physics_allowed,
+            "physical_qualification": False,
+            "real_execution_allowed": False,
+        }
+
+
+_QUESTIONS: dict[str, tuple[str, str]] = {
+    "robot_base_pose_missing": (
+        "Where is the robot base frame located in the cell?",
+        "The base transform is required to evaluate reach, collision, and path geometry.",
+    ),
+    "missing_source_entity": (
+        "Please provide the source geometry and pose.",
+        "The requested pickup/source location is not represented in the twin.",
+    ),
+    "missing_destination_entity": (
+        "Please provide the destination geometry and pose.",
+        "The requested destination is not represented in the twin.",
+    ),
+    "missing_workpiece_entity": (
+        "Please provide the workpiece geometry and initial pose.",
+        "The part being manipulated must be represented to qualify physical motion.",
+    ),
+    "entity_pose_missing": (
+        "Please provide the missing entity pose or import calibrated cell geometry.",
+        "Enabled collision geometry cannot be placed correctly without a pose.",
+    ),
+    "entity_geometry_unknown": (
+        "Please provide dimensions or CAD/mesh geometry for the missing entity.",
+        "Collision and reachability qualification require usable geometry.",
+    ),
+    "tool_not_specified": (
+        "Which tool or gripper is mounted on the robot?",
+        "The tool changes collision geometry, TCP, reachability, and payload behavior.",
+    ),
+    "tool_tcp_missing": (
+        "What is the calibrated TCP of the selected tool?",
+        "Motion planning must use the real tool center point rather than an invented one.",
+    ),
+    "tool_geometry_unknown": (
+        "Please provide tool dimensions or CAD/mesh geometry.",
+        "Unknown tool collision geometry limits geometric qualification.",
+    ),
+    "physics_evidence_incomplete": (
+        "Please provide workpiece mass/contact data and controller timing/speed information for physics qualification.",
+        "Planning geometry is available, but the twin does not yet contain enough physical evidence for a physics-level claim.",
+    ),
+    "possible_unit_mismatch": (
+        "Please confirm the imported dimensions and their units.",
+        "An unusually large dimension may indicate a millimetre/metre conversion error; DevAgent will not plan through it until confirmed.",
+    ),
+    "unknown_pose_frame": (
+        "Please provide the missing coordinate-frame transform.",
+        "A pose references a frame that is not connected to the twin frame graph.",
+    ),
+    "unknown_parent_frame": (
+        "Please provide the missing parent-frame transform.",
+        "The frame graph is incomplete and cannot be used for geometric planning.",
+    ),
+}
+
+_RECOVERABLE_INFORMATION_CODES = frozenset(
+    {
+        "robot_base_pose_missing",
+        "missing_source_entity",
+        "missing_destination_entity",
+        "missing_workpiece_entity",
+        "entity_pose_missing",
+        "entity_geometry_unknown",
+        "tool_tcp_missing",
+        "possible_unit_mismatch",
+        "unknown_pose_frame",
+        "unknown_parent_frame",
+    }
+)
+
+
+class TwinBuilder:
+    """Assemble a twin from explicit evidence and validate what it can claim."""
+
+    def __init__(self, robot_profiles: RobotProfileRegistry) -> None:
+        self.robot_profiles = robot_profiles
+        self.validator = TwinValidator(robot_profiles)
+
+    @staticmethod
+    def _apply_request_payload(
+        request: ValidatedEngineeringRequest,
+        entities: tuple[TwinEntity, ...],
+    ) -> tuple[TwinEntity, ...]:
+        """Carry an explicitly supplied request payload into the workpiece model.
+
+        This is not a guessed physics parameter. It preserves provenance as
+        USER_DECLARED and never overwrites a more specific supplied mass.
+        Friction/contact data remain unknown until separately provided.
+        """
+
+        if request.payload_kg is None:
+            return entities
+        output: list[TwinEntity] = []
+        for entity in entities:
+            if entity.entity_id != request.object_id:
+                output.append(entity)
+                continue
+            if entity.physics.mass_kg.value is not None:
+                output.append(entity)
+                continue
+            physics = replace(
+                entity.physics,
+                mass_kg=EvidenceValue(
+                    request.payload_kg,
+                    EvidenceOrigin.USER_DECLARED,
+                    source_ref=request.request_id,
+                ),
+            )
+            output.append(replace(entity, physics=physics))
+        return tuple(output)
+
+    def build(
+        self,
+        request: ValidatedEngineeringRequest,
+        inputs: TwinBuildInputs,
+        *,
+        twin_id: str | None = None,
+    ) -> TwinBuildResult:
+        profile = self.robot_profiles.resolve(request.robot_key)
+
+        entities = self._apply_request_payload(request, tuple(inputs.entities))
+        twin = TwinSpec(
+            twin_id=twin_id or f"TWIN-{request.request_id[4:]}",
+            robot_profile_key=profile.key,
+            robot_base_pose=inputs.robot_base_pose,
+            entities=entities,
+            source_entity_id=request.source,
+            destination_entity_id=request.destination,
+            workpiece_entity_id=request.object_id,
+            tool=inputs.tool,
+            frames=tuple(inputs.frames),
+            sensors=tuple(inputs.sensors),
+            controller=inputs.controller,
+            uncertainty=inputs.uncertainty,
+            reality=inputs.reality,
+            metadata=dict(inputs.metadata or {}),
+        )
+        validation = self.validator.validate(twin, request=request)
+
+        error_codes = {issue.code for issue in validation.errors}
+        if error_codes and not error_codes.issubset(_RECOVERABLE_INFORMATION_CODES):
+            state = TwinBuildState.INVALID
+        elif error_codes:
+            state = TwinBuildState.NEEDS_INFORMATION
+        elif validation.reality_calibrated:
+            state = TwinBuildState.REALITY_CALIBRATED
+        elif validation.ready_for_physics:
+            state = TwinBuildState.READY_FOR_PHYSICS
+        elif validation.ready_for_planning:
+            state = TwinBuildState.READY_FOR_PLANNING
+        else:
+            state = TwinBuildState.NEEDS_INFORMATION
+
+        information_requests = self._questions_for(validation)
+        return TwinBuildResult(
+            twin=twin,
+            validation=validation,
+            state=state,
+            information_requests=information_requests,
+            evidence_origins=evidence_summary(twin),
+        )
+
+    @staticmethod
+    def _questions_for(
+        validation: TwinValidationReport,
+    ) -> tuple[TwinInformationRequest, ...]:
+        result: list[TwinInformationRequest] = []
+        seen: set[str] = set()
+        for issue in validation.issues:
+            if issue.code in seen:
+                continue
+            template = _QUESTIONS.get(issue.code)
+            if template is None:
+                continue
+            seen.add(issue.code)
+            result.append(TwinInformationRequest(issue.code, *template))
+        return tuple(result)
+
+
+def conceptual_entity(
+    entity_id: str,
+    entity_type: str,
+    *,
+    pose: Pose3D | None = None,
+) -> TwinEntity:
+    """Explicit placeholder helper for UI/import staging.
+
+    A conceptual entity is intentionally UNKNOWN geometry and therefore cannot
+    pass geometric planning validation. It is useful for representing what the
+    user named while DevAgent asks for dimensions/CAD instead of inventing them.
+    """
+
+    return TwinEntity(
+        entity_id=entity_id,
+        entity_type=entity_type,
+        pose=pose,
+        geometry=GeometrySpec(
+            GeometryKind.UNKNOWN,
+            EvidenceOrigin.UNKNOWN,
+            collision_geometry=False,
+        ),
+    )