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

devagent_physical_engine/__init__.py

@@ -0,0 +1,44 @@
+"""DevAgent Smart Physical Engine public contracts."""
+
+from .models import (
+    ActionContract,
+    Capability,
+    Goal,
+    Resource,
+    TaskGraph,
+    TaskNode,
+    WorldState,
+)
+from .physical_motion import JointTrajectoryPoint, MotionExecutionMetrics, PhysicalMotionPlan
+from .robot_platform import (
+    BUILTIN_ROBOT_PROFILES,
+    QualificationState,
+    RobotProfile,
+    RobotProfileRegistry,
+    SimulationTier,
+)
+from .twin import TwinConfidenceLevel, TwinSpec, TwinValidationReport, TwinValidator
+
+__all__ = [
+    "ActionContract",
+    "Capability",
+    "Goal",
+    "Resource",
+    "TaskGraph",
+    "TaskNode",
+    "WorldState",
+    "JointTrajectoryPoint",
+    "MotionExecutionMetrics",
+    "PhysicalMotionPlan",
+    "BUILTIN_ROBOT_PROFILES",
+    "QualificationState",
+    "RobotProfile",
+    "RobotProfileRegistry",
+    "SimulationTier",
+    "TwinConfidenceLevel",
+    "TwinSpec",
+    "TwinValidationReport",
+    "TwinValidator",
+]
+
+__version__ = "0.10.0"

devagent_physical_engine/agent/__init__.py

@@ -0,0 +1,40 @@
+from .compiler import AGENT_PLAN_SCHEMA, AgentPlanCompiler, AgentPlanProposal, AgentTaskProposal
+from .contracts import (
+    AgentRole,
+    CriticDecision,
+    RecoveryDecision,
+    RoutingPolicy,
+    RoutingStrategy,
+)
+from .coordinator import PlanningCoordinator, VerifiedPlanArtifact
+from .critic import CriticAgent
+from .interpreter import InterpretedEngineeringRequest, RequirementInterpreterAgent
+from .planner import PlannerAgent
+from .recovery import RecoveryAgent
+from .routing import ModelRouter
+from .runtime import AgentRuntime, ProviderPool, StructuredModelProvider
+from .semantic import AgentPlanSemanticPolicy
+
+__all__ = [
+    "AGENT_PLAN_SCHEMA",
+    "AgentPlanCompiler",
+    "AgentPlanProposal",
+    "AgentTaskProposal",
+    "AgentPlanSemanticPolicy",
+    "AgentRole",
+    "CriticDecision",
+    "RecoveryDecision",
+    "RoutingPolicy",
+    "RoutingStrategy",
+    "PlanningCoordinator",
+    "VerifiedPlanArtifact",
+    "CriticAgent",
+    "InterpretedEngineeringRequest",
+    "RequirementInterpreterAgent",
+    "PlannerAgent",
+    "RecoveryAgent",
+    "ModelRouter",
+    "AgentRuntime",
+    "ProviderPool",
+    "StructuredModelProvider",
+]

devagent_physical_engine/agent/compiler.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from .semantic import AgentPlanSemanticPolicy
+from .structured import MAX_ITEMS, MAX_TASKS, MAX_TEXT, StructuredOutputError
+from ..models import ActionContract, Capability, Goal, Resource, TaskGraph, TaskNode, WorldState
+from ..planning import PlanningError, SUPPORTED_GOAL_ACTIONS
+
+
+AGENT_PLAN_SCHEMA = {
+    "type": "object",
+    "additionalProperties": False,
+    "required": ["goal_id", "tasks"],
+    "properties": {
+        "goal_id": {"type": "string", "minLength": 1, "maxLength": MAX_TEXT},
+        "tasks": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": MAX_TASKS,
+            "items": {
+                "type": "object",
+                "additionalProperties": False,
+                "required": ["task_id", "action", "resource_id"],
+                "properties": {
+                    "task_id": {"type": "string", "minLength": 1, "maxLength": MAX_TEXT},
+                    "action": {"enum": ["pick", "move", "place"]},
+                    "resource_id": {"type": "string", "minLength": 1, "maxLength": MAX_TEXT},
+                    "object_id": {"type": ["string", "null"], "maxLength": MAX_TEXT},
+                    "source": {"type": ["string", "null"], "maxLength": MAX_TEXT},
+                    "destination": {"type": ["string", "null"], "maxLength": MAX_TEXT},
+                    "depends_on": {
+                        "type": "array",
+                        "maxItems": MAX_ITEMS,
+                        "items": {"type": "string", "minLength": 1, "maxLength": MAX_TEXT},
+                        "uniqueItems": True,
+                    },
+                },
+            },
+        },
+    },
+}
+
+
+@dataclass(frozen=True, slots=True)
+class AgentTaskProposal:
+    task_id: str
+    action: Capability
+    resource_id: str
+    object_id: str | None = None
+    source: str | None = None
+    destination: str | None = None
+    depends_on: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class AgentPlanProposal:
+    goal_id: str
+    tasks: tuple[AgentTaskProposal, ...]
+
+
+def _text(value: Any, name: str, *, required: bool = True) -> str | None:
+    if value is None and not required:
+        return None
+    if not isinstance(value, str):
+        raise StructuredOutputError(f"{name}_must_be_string")
+    normalized = value.strip()
+    if required and not normalized:
+        raise StructuredOutputError(f"{name}_required")
+    if len(normalized) > MAX_TEXT:
+        raise StructuredOutputError(f"{name}_too_long")
+    return normalized
+
+
+def _dependencies(value: Any, name: str) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if not isinstance(value, list):
+        raise StructuredOutputError(f"{name}_must_be_array")
+    if len(value) > MAX_ITEMS:
+        raise StructuredOutputError(f"{name}_too_many_items")
+    result: list[str] = []
+    for item in value:
+        normalized = _text(item, name)
+        if normalized is None:
+            raise StructuredOutputError(f"{name}_required")
+        result.append(normalized)
+    if len(result) != len(set(result)):
+        raise StructuredOutputError(f"{name}_contains_duplicates")
+    return tuple(result)
+
+
+def parse_agent_plan(
+    payload: Mapping[str, Any], *, expected_goal_id: str
+) -> AgentPlanProposal:
+    if not isinstance(payload, Mapping):
+        raise StructuredOutputError("agent_plan_must_be_object")
+    extra = set(payload) - {"goal_id", "tasks"}
+    if extra:
+        raise StructuredOutputError(
+            "agent_plan_unknown_fields:" + ",".join(sorted(extra))
+        )
+
+    goal_id = _text(payload.get("goal_id"), "goal_id")
+    if goal_id != expected_goal_id:
+        raise StructuredOutputError("goal_id_mismatch")
+
+    raw_tasks = payload.get("tasks")
+    if not isinstance(raw_tasks, list):
+        raise StructuredOutputError("tasks_must_be_array")
+    if not raw_tasks:
+        raise StructuredOutputError("tasks_required")
+    if len(raw_tasks) > MAX_TASKS:
+        raise StructuredOutputError("too_many_tasks")
+
+    allowed = {
+        "task_id",
+        "action",
+        "resource_id",
+        "object_id",
+        "source",
+        "destination",
+        "depends_on",
+    }
+    tasks: list[AgentTaskProposal] = []
+    for index, raw in enumerate(raw_tasks):
+        if not isinstance(raw, Mapping):
+            raise StructuredOutputError(f"task_{index}_must_be_object")
+        extra = set(raw) - allowed
+        if extra:
+            raise StructuredOutputError(
+                f"task_{index}_unknown_fields:" + ",".join(sorted(extra))
+            )
+
+        task_id = _text(raw.get("task_id"), f"task_{index}.task_id")
+        resource_id = _text(
+            raw.get("resource_id"), f"task_{index}.resource_id"
+        )
+        action_text = _text(raw.get("action"), f"task_{index}.action")
+        if task_id is None or resource_id is None or action_text is None:
+            raise StructuredOutputError(f"task_{index}_required_field_missing")
+        try:
+            action = Capability(action_text)
+        except ValueError as exc:
+            raise StructuredOutputError(
+                f"task_{index}.unsupported_action:{action_text}"
+            ) from exc
+        if action not in {Capability.PICK, Capability.MOVE, Capability.PLACE}:
+            raise StructuredOutputError(
+                f"task_{index}.action_not_allowed_for_load:{action.value}"
+            )
+
+        tasks.append(
+            AgentTaskProposal(
+                task_id=task_id,
+                action=action,
+                resource_id=resource_id,
+                object_id=_text(
+                    raw.get("object_id"),
+                    f"task_{index}.object_id",
+                    required=False,
+                ),
+                source=_text(
+                    raw.get("source"),
+                    f"task_{index}.source",
+                    required=False,
+                ),
+                destination=_text(
+                    raw.get("destination"),
+                    f"task_{index}.destination",
+                    required=False,
+                ),
+                depends_on=_dependencies(
+                    raw.get("depends_on"), f"task_{index}.depends_on"
+                ),
+            )
+        )
+
+    ids = [task.task_id for task in tasks]
+    if len(ids) != len(set(ids)):
+        raise StructuredOutputError("duplicate_task_id")
+    known = set(ids)
+    for task in tasks:
+        for dependency in task.depends_on:
+            if dependency not in known:
+                raise StructuredOutputError(
+                    f"unknown_dependency:{task.task_id}:{dependency}"
+                )
+            if dependency == task.task_id:
+                raise StructuredOutputError(
+                    f"self_dependency:{task.task_id}"
+                )
+
+    return AgentPlanProposal(goal_id=goal_id, tasks=tuple(tasks))
+
+
+class AgentPlanCompiler:
+    """Compile an untrusted high-level proposal into canonical action contracts.
+
+    The model chooses task decomposition and resource assignment. The engine owns
+    preconditions, effects, motion constraints, and completion semantics.
+    """
+
+    def __init__(
+        self, semantic_policy: AgentPlanSemanticPolicy | None = None
+    ) -> None:
+        self.semantic_policy = semantic_policy or AgentPlanSemanticPolicy()
+
+    def compile(
+        self,
+        payload: Mapping[str, Any],
+        *,
+        goal: Goal,
+        resources: list[Resource],
+        world: WorldState,
+    ) -> TaskGraph:
+        goal_action = goal.action.strip().lower()
+        if goal_action not in SUPPORTED_GOAL_ACTIONS:
+            raise PlanningError(f"unsupported_goal_action:{goal_action}")
+
+        proposal = parse_agent_plan(payload, expected_goal_id=goal.goal_id)
+        counts = Counter(task.action for task in proposal.tasks)
+        for action in (Capability.PICK, Capability.MOVE, Capability.PLACE):
+            if counts[action] != 1:
+                raise StructuredOutputError(
+                    f"invalid_action_count:{action.value}:{counts[action]}"
+                )
+
+        compiled: list[TaskNode] = []
+        for proposed in proposal.tasks:
+            if proposed.action is Capability.PICK:
+                contract = ActionContract(
+                    action=Capability.PICK,
+                    resource_id=proposed.resource_id,
+                    object_id=proposed.object_id,
+                    source=proposed.source,
+                    preconditions=("robot_ready", "object_available"),
+                    expected_effects=("object_gripped",),
+                    constraints=("collision_free", "joint_limits"),
+                )
+            elif proposed.action is Capability.MOVE:
+                contract = ActionContract(
+                    action=Capability.MOVE,
+                    resource_id=proposed.resource_id,
+                    object_id=proposed.object_id,
+                    destination=proposed.destination,
+                    preconditions=("robot_ready", "object_gripped"),
+                    expected_effects=("at_destination",),
+                    constraints=("collision_free", "joint_limits"),
+                )
+            elif proposed.action is Capability.PLACE:
+                contract = ActionContract(
+                    action=Capability.PLACE,
+                    resource_id=proposed.resource_id,
+                    object_id=proposed.object_id,
+                    destination=proposed.destination,
+                    preconditions=("robot_ready", "object_gripped", "at_destination"),
+                    expected_effects=("object_placed", "goal_complete"),
+                    constraints=("collision_free", "joint_limits"),
+                )
+            else:  # pragma: no cover - parser currently prevents this
+                raise StructuredOutputError(
+                    f"unsupported_compiled_action:{proposed.action.value}"
+                )
+
+            compiled.append(
+                TaskNode(
+                    task_id=proposed.task_id,
+                    contract=contract,
+                    depends_on=proposed.depends_on,
+                )
+            )
+
+        graph = TaskGraph(goal_id=proposal.goal_id, tasks=tuple(compiled))
+        graph.topological_order()
+        semantic = self.semantic_policy.verify(goal, graph, resources, world)
+        if not semantic.passed:
+            detail = ";".join(
+                f"{issue.code}:{issue.task_id or ''}:{issue.detail}"
+                for issue in semantic.issues
+            )
+            raise StructuredOutputError(f"semantic_verification_failed:{detail}")
+        return graph

devagent_physical_engine/agent/contracts.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Mapping
+
+
+class AgentRole(str, Enum):
+    INTERPRETER = "interpreter"
+    PLANNER = "planner"
+    CRITIC = "critic"
+    RECOVERY = "recovery"
+
+
+class RoutingStrategy(str, Enum):
+    AUTO_BEST = "auto_best"
+    FIXED = "fixed"
+    LOWEST_COST = "lowest_cost"
+    LOWEST_LATENCY = "lowest_latency"
+    PRIVATE_ONLY = "private_only"
+
+
+class CriticDecision(str, Enum):
+    ACCEPT = "accept"
+    REVISE = "revise"
+    REJECT = "reject"
+
+
+class RecoveryDecision(str, Enum):
+    RETRY = "retry"
+    REPLAN = "replan"
+    WAIT = "wait"
+    OBSERVE = "observe"
+    ABORT = "abort"
+
+
+@dataclass(frozen=True, slots=True)
+class RoutingPolicy:
+    strategy: RoutingStrategy = RoutingStrategy.AUTO_BEST
+    fixed_provider: str | None = None
+    fixed_model: str | None = None
+    max_attempts: int = 3
+    timeout_s: float = 30.0
+    min_quality: float = 0.0
+    require_qualified: bool = True
+
+    def __post_init__(self) -> None:
+        if self.fixed_provider is not None:
+            object.__setattr__(
+                self, "fixed_provider", self.fixed_provider.strip().lower()
+            )
+        if self.fixed_model is not None:
+            object.__setattr__(self, "fixed_model", self.fixed_model.strip())
+
+        if not 1 <= self.max_attempts <= 8:
+            raise ValueError("max_attempts_out_of_range")
+        if not 0.1 <= self.timeout_s <= 120.0:
+            raise ValueError("timeout_s_out_of_range")
+        if not 0.0 <= self.min_quality <= 1.0:
+            raise ValueError("min_quality_out_of_range")
+        if self.strategy is RoutingStrategy.FIXED and (
+            not self.fixed_provider or not self.fixed_model
+        ):
+            raise ValueError("fixed_route_requires_provider_and_model")
+
+
+@dataclass(frozen=True, slots=True)
+class ModelRequest:
+    role: AgentRole
+    system_instruction: str
+    input_payload: Mapping[str, Any]
+    output_schema: Mapping[str, Any]
+    timeout_s: float
+
+    def __post_init__(self) -> None:
+        if not self.system_instruction.strip():
+            raise ValueError("system_instruction_required")
+        if not 0.1 <= self.timeout_s <= 120.0:
+            raise ValueError("request_timeout_out_of_range")
+
+
+@dataclass(frozen=True, slots=True)
+class ModelResponse:
+    provider: str
+    model: str
+    payload: Mapping[str, Any]
+    request_id: str = ""
+    latency_ms: float | None = None
+
+    def __post_init__(self) -> None:
+        if not self.provider.strip() or not self.model.strip():
+            raise ValueError("response_identity_required")
+        if self.latency_ms is not None and self.latency_ms < 0:
+            raise ValueError("response_latency_invalid")
+
+
+@dataclass(frozen=True, slots=True)
+class ModelAttempt:
+    provider: str
+    model: str
+    outcome: str
+    error_code: str = ""
+    latency_ms: float | None = None
+    request_id: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class AgentEvidence:
+    trace_id: str
+    role: AgentRole
+    input_hash: str
+    output_hash: str | None
+    attempts: tuple[ModelAttempt, ...]
+    selected_provider: str | None = None
+    selected_model: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Critique:
+    decision: CriticDecision
+    score: float
+    issues: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class RecoveryAdvice:
+    decision: RecoveryDecision
+    reason: str
+    retry_after_ms: int | None = None

devagent_physical_engine/agent/coordinator.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from .contracts import AgentEvidence, CriticDecision, RoutingPolicy
+from .critic import CriticAgent
+from .evidence import task_graph_hash
+from .planner import PlannerAgent
+from ..models import Goal, Resource, TaskGraph, WorldState
+
+
+class PlanningCoordinationError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class VerifiedPlanArtifact:
+    graph: TaskGraph
+    graph_hash: str
+    planner_evidence: tuple[AgentEvidence, ...]
+    critic_evidence: tuple[AgentEvidence, ...]
+    revision_rounds: int
+
+
+class PlanningCoordinator:
+    """Planner/critic loop with bounded revisions and deterministic plan proof."""
+
+    def __init__(
+        self,
+        planner: PlannerAgent,
+        critic: CriticAgent,
+        *,
+        max_revision_rounds: int = 2,
+        min_accept_score: float = 0.70,
+    ) -> None:
+        if not 0 <= max_revision_rounds <= 4:
+            raise ValueError("max_revision_rounds_out_of_range")
+        if not 0.0 <= min_accept_score <= 1.0:
+            raise ValueError("min_accept_score_out_of_range")
+        self.planner = planner
+        self.critic = critic
+        self.max_revision_rounds = max_revision_rounds
+        self.min_accept_score = min_accept_score
+
+    def create_verified_plan(
+        self,
+        goal: Goal,
+        resources: list[Resource],
+        world: WorldState,
+        planner_policy: RoutingPolicy,
+        critic_policy: RoutingPolicy,
+        *,
+        engineering_context: Mapping[str, Any] | None = None,
+    ) -> VerifiedPlanArtifact:
+        feedback: tuple[str, ...] = ()
+        planner_evidence: list[AgentEvidence] = []
+        critic_evidence: list[AgentEvidence] = []
+
+        for revision in range(self.max_revision_rounds + 1):
+            planned = self.planner.plan(
+                goal,
+                resources,
+                world,
+                planner_policy,
+                feedback=feedback,
+                engineering_context=engineering_context,
+            )
+            planner_evidence.append(planned.evidence)
+
+            reviewed = self.critic.review(
+                goal,
+                planned.graph,
+                resources,
+                world,
+                critic_policy,
+                engineering_context=engineering_context,
+            )
+            critic_evidence.append(reviewed.evidence)
+
+            if (
+                reviewed.critique.decision is CriticDecision.ACCEPT
+                and reviewed.critique.score >= self.min_accept_score
+            ):
+                return VerifiedPlanArtifact(
+                    graph=planned.graph,
+                    graph_hash=task_graph_hash(planned.graph),
+                    planner_evidence=tuple(planner_evidence),
+                    critic_evidence=tuple(critic_evidence),
+                    revision_rounds=revision,
+                )
+
+            if reviewed.critique.decision is CriticDecision.REJECT:
+                raise PlanningCoordinationError(
+                    "critic_rejected_plan:"
+                    + ";".join(reviewed.critique.issues)
+                )
+
+            if reviewed.critique.decision is CriticDecision.ACCEPT:
+                feedback = reviewed.critique.issues or (
+                    f"critic_score_below_threshold:{reviewed.critique.score:.3f}",
+                )
+            else:
+                feedback = reviewed.critique.issues or (
+                    "critic_requested_revision",
+                )
+
+        raise PlanningCoordinationError("revision_budget_exhausted")

devagent_physical_engine/agent/critic.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from .contracts import AgentEvidence, AgentRole, Critique, RoutingPolicy
+from .evidence import task_graph_to_dict
+from .runtime import AgentRuntime, InvocationResult
+from .structured import CRITIQUE_SCHEMA, json_safe, parse_critique
+from ..models import Goal, Resource, TaskGraph, WorldState
+from ..verification import DeterministicVerifier
+
+CRITIC_SYSTEM = """You are the DevAgent planning critic. Review a deterministically valid task plan for efficiency, unnecessary steps, ambiguity, recoverability, robustness, and fit to the validated engineering objective. You are advisory only and cannot mark an unsafe plan safe, weaken hard constraints, invent missing engineering facts, or authorize execution."""
+
+
+@dataclass(frozen=True, slots=True)
+class CriticResult:
+    critique: Critique
+    evidence: AgentEvidence
+
+
+class CriticAgent:
+    """Advisory critic; deterministic verification remains authoritative."""
+
+    def __init__(
+        self,
+        runtime: AgentRuntime,
+        verifier: DeterministicVerifier | None = None,
+    ) -> None:
+        self.runtime = runtime
+        self.verifier = verifier or DeterministicVerifier()
+
+    def review(
+        self,
+        goal: Goal,
+        graph: TaskGraph,
+        resources: list[Resource],
+        world: WorldState,
+        policy: RoutingPolicy,
+        *,
+        engineering_context: Mapping[str, Any] | None = None,
+    ) -> CriticResult:
+        verified = self.verifier.verify_graph(graph, resources)
+        if not verified.passed:
+            raise ValueError("critic_requires_deterministically_valid_plan")
+
+        input_payload = {
+            "goal": {
+                "goal_id": goal.goal_id,
+                "action": goal.action,
+                "object_id": goal.object_id,
+                "source": goal.source,
+                "destination": goal.destination,
+            },
+            "plan": task_graph_to_dict(graph),
+            "world": {
+                "facts": sorted(world.facts),
+                "values": dict(world.values),
+            },
+        }
+        if engineering_context is not None:
+            input_payload["validated_engineering_context"] = json_safe(engineering_context)
+
+        invocation: InvocationResult = self.runtime.invoke(
+            role=AgentRole.CRITIC,
+            system_instruction=CRITIC_SYSTEM,
+            input_payload=input_payload,
+            output_schema=CRITIQUE_SCHEMA,
+            policy=policy,
+            validator=parse_critique,
+        )
+        return CriticResult(invocation.value, invocation.evidence)