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

devagent_physical_engine/physical_motion.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from hashlib import sha256
+import json
+from math import isfinite
+import re
+from typing import Any, Mapping
+
+
+class PhysicalMotionError(ValueError):
+    pass
+
+
+_SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
+
+
+def _finite_tuple(values: tuple[float, ...], *, field_name: str) -> tuple[float, ...]:
+    converted = tuple(float(value) for value in values)
+    if any(not isfinite(value) for value in converted):
+        raise PhysicalMotionError(f"{field_name}_non_finite")
+    return converted
+
+
+@dataclass(frozen=True, slots=True)
+class JointTrajectoryPoint:
+    positions_rad: tuple[float, ...]
+    time_from_start_s: float
+    velocities_rad_s: tuple[float, ...] = ()
+    accelerations_rad_s2: tuple[float, ...] = ()
+
+    def __post_init__(self) -> None:
+        positions = _finite_tuple(self.positions_rad, field_name="positions")
+        if not positions:
+            raise PhysicalMotionError("trajectory_point_positions_required")
+        time_s = float(self.time_from_start_s)
+        if not isfinite(time_s) or time_s < 0:
+            raise PhysicalMotionError("trajectory_point_time_invalid")
+        velocities = _finite_tuple(self.velocities_rad_s, field_name="velocities")
+        accelerations = _finite_tuple(
+            self.accelerations_rad_s2, field_name="accelerations"
+        )
+        if velocities and len(velocities) != len(positions):
+            raise PhysicalMotionError("trajectory_velocity_size_mismatch")
+        if accelerations and len(accelerations) != len(positions):
+            raise PhysicalMotionError("trajectory_acceleration_size_mismatch")
+        object.__setattr__(self, "positions_rad", positions)
+        object.__setattr__(self, "time_from_start_s", time_s)
+        object.__setattr__(self, "velocities_rad_s", velocities)
+        object.__setattr__(self, "accelerations_rad_s2", accelerations)
+
+
+@dataclass(frozen=True, slots=True)
+class PhysicalMotionPlan:
+    """Executable motion contract produced only after high-level verification.
+
+    The contract intentionally contains no vendor motion language. Adapters
+    consume canonical joint trajectories in radians/seconds. A high-level
+    TaskGraph is not executable by a physical simulator until a motion planner
+    has produced this object.
+    """
+
+    motion_id: str
+    robot_profile_key: str
+    joint_names: tuple[str, ...]
+    points: tuple[JointTrajectoryPoint, ...]
+    source_graph_hash: str
+    planner_id: str
+    twin_hash: str
+    constraints: tuple[str, ...] = ()
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        for name, value in (
+            ("motion_id", self.motion_id),
+            ("robot_profile_key", self.robot_profile_key),
+            ("source_graph_hash", self.source_graph_hash),
+            ("planner_id", self.planner_id),
+            ("twin_hash", self.twin_hash),
+        ):
+            if not value.strip():
+                raise PhysicalMotionError(f"{name}_required")
+        if not _SHA256_RE.fullmatch(self.source_graph_hash):
+            raise PhysicalMotionError("source_graph_hash_invalid")
+        if not _SHA256_RE.fullmatch(self.twin_hash):
+            raise PhysicalMotionError("twin_hash_invalid")
+        if not self.joint_names or any(not name.strip() for name in self.joint_names):
+            raise PhysicalMotionError("joint_names_required")
+        if len(set(self.joint_names)) != len(self.joint_names):
+            raise PhysicalMotionError("duplicate_joint_name")
+        if len(self.points) < 2:
+            raise PhysicalMotionError("trajectory_requires_two_points")
+        if not isinstance(self.metadata, Mapping):
+            raise PhysicalMotionError("motion_metadata_must_be_mapping")
+        if any(not constraint.strip() for constraint in self.constraints):
+            raise PhysicalMotionError("empty_motion_constraint")
+
+        previous = -1.0
+        for point in self.points:
+            if len(point.positions_rad) != len(self.joint_names):
+                raise PhysicalMotionError("trajectory_joint_count_mismatch")
+            if point.time_from_start_s <= previous:
+                raise PhysicalMotionError("trajectory_time_not_strictly_increasing")
+            previous = point.time_from_start_s
+        if self.points[0].time_from_start_s != 0.0:
+            raise PhysicalMotionError("trajectory_first_point_must_start_at_zero")
+        if self.points[-1].time_from_start_s <= 0.0:
+            raise PhysicalMotionError("trajectory_duration_invalid")
+
+        try:
+            json.dumps(self.metadata, sort_keys=True, allow_nan=False)
+        except (TypeError, ValueError) as exc:
+            raise PhysicalMotionError("motion_metadata_not_json_safe") from exc
+
+    @property
+    def planned_duration_s(self) -> float:
+        return self.points[-1].time_from_start_s
+
+    @property
+    def joint_travel_rad(self) -> float:
+        total = 0.0
+        previous = self.points[0].positions_rad
+        for point in self.points[1:]:
+            total += sum(abs(a - b) for a, b in zip(previous, point.positions_rad))
+            previous = point.positions_rad
+        return total
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "motion_id": self.motion_id,
+            "robot_profile_key": self.robot_profile_key,
+            "joint_names": list(self.joint_names),
+            "points": [asdict(point) for point in self.points],
+            "source_graph_hash": self.source_graph_hash,
+            "planner_id": self.planner_id,
+            "twin_hash": self.twin_hash,
+            "constraints": list(self.constraints),
+            "metadata": dict(self.metadata),
+        }
+
+    @property
+    def fingerprint(self) -> str:
+        payload = json.dumps(
+            self.to_dict(), sort_keys=True, separators=(",", ":"), allow_nan=False
+        )
+        return sha256(payload.encode("utf-8")).hexdigest()
+
+
+@dataclass(frozen=True, slots=True)
+class MotionExecutionMetrics:
+    """Metrics directly observed or explicitly unavailable after one execution."""
+
+    success: bool
+    observed_duration_s: float | None
+    planned_duration_s: float
+    planned_joint_travel_rad: float
+    measured_joint_travel_rad: float | None = None
+    max_tracking_error_rad: float | None = None
+    path_length_m: float | None = None
+    min_clearance_m: float | None = None
+    final_tcp_error_m: float | None = None
+    energy_proxy: float | None = None
+    planner_retries: int | None = None
+    trajectory_retries: int | None = None
+    failure_codes: tuple[str, ...] = ()
+    metrics_origin: str = "measured_physical_simulation"
+
+    def __post_init__(self) -> None:
+        if not self.metrics_origin.strip():
+            raise PhysicalMotionError("metrics_origin_required")
+        for name in (
+            "observed_duration_s",
+            "planned_duration_s",
+            "planned_joint_travel_rad",
+            "measured_joint_travel_rad",
+            "max_tracking_error_rad",
+            "path_length_m",
+            "min_clearance_m",
+            "final_tcp_error_m",
+            "energy_proxy",
+        ):
+            value = getattr(self, name)
+            if value is None:
+                continue
+            numeric = float(value)
+            if not isfinite(numeric) or numeric < 0:
+                raise PhysicalMotionError(f"metric_invalid:{name}")
+        for name in ("planner_retries", "trajectory_retries"):
+            value = getattr(self, name)
+            if value is not None and value < 0:
+                raise PhysicalMotionError(f"metric_invalid:{name}")
+        if any(not code.strip() for code in self.failure_codes):
+            raise PhysicalMotionError("empty_motion_failure_code")
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)

devagent_physical_engine/planning.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .models import ActionContract, Capability, Goal, Resource, TaskGraph, TaskNode
+
+
+class PlanningError(RuntimeError):
+    pass
+
+
+SUPPORTED_GOAL_ACTIONS = frozenset({"load"})
+
+
+@dataclass(slots=True)
+class CapabilityPlanner:
+    """Deterministic reference planner; AI planners must emit the same verified TaskGraph schema."""
+
+    def plan(self, goal: Goal, resources: list[Resource]) -> TaskGraph:
+        action = goal.action.strip().lower()
+        if action not in SUPPORTED_GOAL_ACTIONS:
+            raise PlanningError(f"unsupported_goal_action:{action}")
+
+        arm = next(
+            (
+                resource
+                for resource in resources
+                if all(
+                    resource.supports(capability)
+                    for capability in (Capability.PICK, Capability.PLACE, Capability.MOVE)
+                )
+            ),
+            None,
+        )
+        if arm is None:
+            raise PlanningError("no_resource_supports_pick_place")
+
+        return TaskGraph(
+            goal.goal_id,
+            (
+                TaskNode(
+                    "T1",
+                    ActionContract(
+                        Capability.PICK,
+                        arm.resource_id,
+                        goal.object_id,
+                        source=goal.source,
+                        preconditions=("robot_ready", "object_available"),
+                        expected_effects=("object_gripped",),
+                        constraints=("collision_free", "joint_limits"),
+                    ),
+                ),
+                TaskNode(
+                    "T2",
+                    ActionContract(
+                        Capability.MOVE,
+                        arm.resource_id,
+                        goal.object_id,
+                        destination=goal.destination,
+                        preconditions=("robot_ready", "object_gripped"),
+                        expected_effects=("at_destination",),
+                        constraints=("collision_free", "joint_limits"),
+                    ),
+                    depends_on=("T1",),
+                ),
+                TaskNode(
+                    "T3",
+                    ActionContract(
+                        Capability.PLACE,
+                        arm.resource_id,
+                        goal.object_id,
+                        destination=goal.destination,
+                        preconditions=("robot_ready", "object_gripped", "at_destination"),
+                        expected_effects=("object_placed", "goal_complete"),
+                        constraints=("collision_free", "joint_limits"),
+                    ),
+                    depends_on=("T2",),
+                ),
+            ),
+        )

devagent_physical_engine/preexecution_contract.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+import json
+import re
+from typing import Any, Mapping
+
+_SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
+
+
+@dataclass(frozen=True, slots=True)
+class PreExecutionVerification:
+    """Evidence binding a collision/path check to one exact motion and Twin.
+
+    ``continuous_collision_check`` is intentionally explicit. A sampled state
+    validity sweep can be useful engineering evidence, but it cannot silently be
+    treated as continuous path verification for commissioning qualification.
+    """
+
+    verified: bool
+    method: str
+    motion_hash: str
+    twin_hash: str
+    materialization_hash: str | None
+    continuous_collision_check: bool
+    sample_count: int = 0
+    failure_codes: tuple[str, ...] = ()
+    evidence: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.method.strip():
+            raise ValueError("preexecution_method_required")
+        for name in ("motion_hash", "twin_hash"):
+            if not _SHA256_RE.fullmatch(getattr(self, name)):
+                raise ValueError(f"preexecution_{name}_invalid")
+        if self.materialization_hash is not None and not _SHA256_RE.fullmatch(
+            self.materialization_hash
+        ):
+            raise ValueError("preexecution_materialization_hash_invalid")
+        if self.sample_count < 0:
+            raise ValueError("preexecution_sample_count_invalid")
+        if any(not code.strip() for code in self.failure_codes):
+            raise ValueError("preexecution_failure_code_empty")
+        if not isinstance(self.evidence, Mapping):
+            raise ValueError("preexecution_evidence_must_be_mapping")
+        try:
+            json.dumps(self.evidence, sort_keys=True, allow_nan=False)
+        except (TypeError, ValueError) as exc:
+            raise ValueError("preexecution_evidence_not_json_safe") from exc
+        if self.verified and self.failure_codes:
+            raise ValueError("verified_preexecution_cannot_have_failure_codes")
+
+    @property
+    def commissioning_usable(self) -> bool:
+        return (
+            self.verified
+            and self.continuous_collision_check
+            and not self.failure_codes
+            and self.materialization_hash is not None
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = asdict(self)
+        payload["commissioning_usable"] = self.commissioning_usable
+        return payload

devagent_physical_engine/provider_adapters/__init__.py

@@ -0,0 +1,22 @@
+from .anthropic import AnthropicProvider
+from .common import (
+    ProviderAuthenticationError,
+    ProviderCallDiagnostics,
+    ProviderRateLimited,
+    ProviderRequestError,
+)
+from .factory import PROVIDER_NAMES, create_provider
+from .gemini import GeminiProvider
+from .openai import OpenAIProvider
+
+__all__ = [
+    "AnthropicProvider",
+    "GeminiProvider",
+    "OpenAIProvider",
+    "ProviderAuthenticationError",
+    "ProviderCallDiagnostics",
+    "ProviderRateLimited",
+    "ProviderRequestError",
+    "PROVIDER_NAMES",
+    "create_provider",
+]

devagent_physical_engine/provider_adapters/anthropic.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from ..agent.contracts import ModelRequest, ModelResponse
+from ..agent.runtime import ProviderError, ProviderProtocolError, ProviderUnavailable
+from .common import (
+    DiagnosticsStore,
+    ProviderCallDiagnostics,
+    classify_provider_exception,
+    model_matches,
+    parse_json_object,
+    provider_schema,
+    request_input,
+    require_api_key,
+    safe_token_count,
+)
+
+
+class AnthropicProvider:
+    provider_name = "anthropic"
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        max_output_tokens: int = 4096,
+        client_factory: Callable[..., Any] | None = None,
+        schema_transform: Callable[[dict[str, Any]], dict[str, Any]] | None = None,
+    ) -> None:
+        if not 256 <= max_output_tokens <= 65536:
+            raise ValueError("max_output_tokens_out_of_range")
+        self._api_key = api_key
+        self._max_output_tokens = max_output_tokens
+        self._client_factory = client_factory
+        self._schema_transform = schema_transform
+        self._diagnostics = DiagnosticsStore()
+
+    def diagnostics(self, request_id: str) -> ProviderCallDiagnostics | None:
+        return self._diagnostics.get(request_id)
+
+    def _client_and_schema_transform(
+        self, timeout_s: float
+    ) -> tuple[Any, Callable[[dict[str, Any]], dict[str, Any]] | None]:
+        key = require_api_key(self._api_key, "ANTHROPIC_API_KEY")
+        if self._client_factory is not None:
+            return (
+                self._client_factory(api_key=key, timeout=timeout_s, max_retries=0),
+                self._schema_transform,
+            )
+        try:
+            import anthropic
+        except ImportError as exc:
+            raise ProviderUnavailable("sdk_not_installed:anthropic") from exc
+        transform = self._schema_transform or getattr(anthropic, "transform_schema", None)
+        return (
+            anthropic.Anthropic(api_key=key, timeout=timeout_s, max_retries=0),
+            transform,
+        )
+
+    def generate(self, request: ModelRequest, *, model: str) -> ModelResponse:
+        try:
+            client, transform = self._client_and_schema_transform(request.timeout_s)
+            schema = provider_schema(request.output_schema)
+            if transform is not None:
+                schema = transform(schema)
+            response = client.messages.create(
+                model=model,
+                max_tokens=self._max_output_tokens,
+                system=request.system_instruction,
+                messages=[{"role": "user", "content": request_input(request)}],
+                output_config={"format": {"type": "json_schema", "schema": schema}},
+            )
+        except Exception as exc:
+            if isinstance(exc, ProviderError):
+                raise
+            raise classify_provider_exception(exc) from exc
+
+        request_id = str(getattr(response, "id", "") or "")
+        if not request_id:
+            raise ProviderProtocolError("provider_request_id_missing")
+        resolved_model = str(getattr(response, "model", "") or "")
+        if not model_matches(model, resolved_model):
+            raise ProviderProtocolError("response_model_identity_mismatch")
+
+        text = None
+        for block in getattr(response, "content", ()) or ():
+            if getattr(block, "type", None) == "text" and getattr(block, "text", None):
+                text = block.text
+                break
+        payload = parse_json_object(text)
+
+        usage = getattr(response, "usage", None)
+        input_tokens = safe_token_count(getattr(usage, "input_tokens", None))
+        output_tokens = safe_token_count(getattr(usage, "output_tokens", None))
+        total_tokens = (
+            input_tokens + output_tokens
+            if input_tokens is not None and output_tokens is not None
+            else None
+        )
+        self._diagnostics.record(
+            ProviderCallDiagnostics(
+                request_id=request_id,
+                provider=self.provider_name,
+                requested_model=model,
+                resolved_model=resolved_model or model,
+                input_tokens=input_tokens,
+                output_tokens=output_tokens,
+                total_tokens=total_tokens,
+            )
+        )
+        return ModelResponse(self.provider_name, model, payload, request_id=request_id)

devagent_physical_engine/provider_adapters/common.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+from collections import OrderedDict
+from copy import deepcopy
+from dataclasses import dataclass
+import json
+import os
+from threading import Lock
+from typing import Any, Mapping
+
+from ..agent.contracts import ModelRequest
+from ..agent.runtime import (
+    ProviderError,
+    ProviderProtocolError,
+    ProviderTimeout,
+    ProviderUnavailable,
+)
+from ..agent.structured import canonical_json, json_safe, redact_sensitive
+
+
+class ProviderAuthenticationError(ProviderError):
+    code = "provider_authentication_error"
+
+
+class ProviderRateLimited(ProviderError):
+    code = "provider_rate_limited"
+
+
+class ProviderRequestError(ProviderError):
+    code = "provider_request_error"
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderCallDiagnostics:
+    request_id: str
+    provider: str
+    requested_model: str
+    resolved_model: str
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    total_tokens: int | None = None
+
+
+class DiagnosticsStore:
+    """Bounded, thread-safe metadata store. Never stores prompts or credentials."""
+
+    def __init__(self, *, max_entries: int = 256) -> None:
+        if not 8 <= max_entries <= 4096:
+            raise ValueError("diagnostics_max_entries_out_of_range")
+        self._max_entries = max_entries
+        self._lock = Lock()
+        self._items: OrderedDict[str, ProviderCallDiagnostics] = OrderedDict()
+
+    def record(self, diagnostics: ProviderCallDiagnostics) -> None:
+        if not diagnostics.request_id:
+            return
+        with self._lock:
+            self._items[diagnostics.request_id] = diagnostics
+            self._items.move_to_end(diagnostics.request_id)
+            while len(self._items) > self._max_entries:
+                self._items.popitem(last=False)
+
+    def get(self, request_id: str) -> ProviderCallDiagnostics | None:
+        with self._lock:
+            return self._items.get(request_id)
+
+
+def require_api_key(explicit: str | None, *env_names: str) -> str:
+    if explicit and explicit.strip():
+        return explicit.strip()
+    for name in env_names:
+        value = os.getenv(name)
+        if value and value.strip():
+            return value.strip()
+    raise ProviderAuthenticationError("credential_missing")
+
+
+def model_matches(requested: str, resolved: str | None) -> bool:
+    """Accept an exact model or a provider-resolved dated version of an alias."""
+    if not resolved:
+        return True
+    requested = requested.strip()
+    resolved = resolved.strip()
+    if requested == resolved:
+        return True
+    return resolved.startswith(requested + "-")
+
+
+def parse_json_object(text: Any) -> Mapping[str, Any]:
+    if not isinstance(text, str) or not text.strip():
+        raise ProviderProtocolError("provider_output_text_missing")
+    try:
+        value = json.loads(text)
+    except (TypeError, json.JSONDecodeError) as exc:
+        raise ProviderProtocolError("provider_output_invalid_json") from exc
+    if not isinstance(value, Mapping):
+        raise ProviderProtocolError("provider_output_must_be_object")
+    return value
+
+
+def request_input(request: ModelRequest) -> str:
+    return canonical_json(
+        {
+            "agent_role": request.role.value,
+            "input": json_safe(redact_sensitive(request.input_payload)),
+        }
+    )
+
+
+_UNSUPPORTED_SCHEMA_KEYS = {
+    "minLength",
+    "maxLength",
+    "minimum",
+    "maximum",
+    "exclusiveMinimum",
+    "exclusiveMaximum",
+    "multipleOf",
+    "minItems",
+    "maxItems",
+    "uniqueItems",
+    "pattern",
+    "format",
+}
+
+
+def provider_schema(schema: Mapping[str, Any]) -> dict[str, Any]:
+    """Return a constrained-decoding schema; core validation remains authoritative.
+
+    Provider structured-output implementations support slightly different JSON
+    Schema subsets. Numeric/string/array constraints are intentionally stripped
+    here and enforced again by DevAgent's deterministic parser/compiler.
+    """
+    source = deepcopy(dict(schema))
+
+    def clean(value: Any) -> Any:
+        if isinstance(value, list):
+            return [clean(item) for item in value]
+        if not isinstance(value, dict):
+            return value
+        result: dict[str, Any] = {}
+        for key, item in value.items():
+            if key in _UNSUPPORTED_SCHEMA_KEYS:
+                continue
+            result[key] = clean(item)
+        if result.get("type") == "object" or "properties" in result:
+            result["additionalProperties"] = False
+        return result
+
+    return clean(source)
+
+
+def classify_provider_exception(exc: BaseException) -> ProviderError:
+    """Map SDK exceptions to stable cross-provider error codes without leaking text."""
+    status = getattr(exc, "status_code", None)
+    if status is None:
+        status = getattr(exc, "code", None)
+    try:
+        status_int = int(status) if status is not None else None
+    except (TypeError, ValueError):
+        status_int = None
+
+    name = type(exc).__name__.lower()
+    if status_int in {401, 403} or "auth" in name or "permission" in name:
+        return ProviderAuthenticationError("provider_authentication_failed")
+    if status_int == 429 or "ratelimit" in name or "rate_limit" in name:
+        return ProviderRateLimited("provider_rate_limited")
+    if status_int in {408, 504} or "timeout" in name:
+        return ProviderTimeout("provider_timeout")
+    if status_int is not None and 400 <= status_int < 500:
+        return ProviderRequestError("provider_request_rejected")
+    if (
+        (status_int is not None and status_int >= 500)
+        or "connection" in name
+        or "unavailable" in name
+    ):
+        return ProviderUnavailable("provider_unavailable")
+    return ProviderUnavailable("provider_unavailable")
+
+
+def safe_token_count(value: Any) -> int | None:
+    if value is None or isinstance(value, bool):
+        return None
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return None
+    return parsed if parsed >= 0 else None

devagent_physical_engine/provider_adapters/factory.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .anthropic import AnthropicProvider
+from .gemini import GeminiProvider
+from .openai import OpenAIProvider
+
+PROVIDER_NAMES = ("openai", "anthropic", "gemini")
+
+
+def create_provider(name: str, *, api_key: str | None = None, **kwargs: Any):
+    normalized = name.strip().lower()
+    if normalized == "openai":
+        return OpenAIProvider(api_key, **kwargs)
+    if normalized in {"anthropic", "claude"}:
+        return AnthropicProvider(api_key, **kwargs)
+    if normalized in {"gemini", "google"}:
+        return GeminiProvider(api_key, **kwargs)
+    raise ValueError(f"unsupported_provider:{normalized}")