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

devagent_physical_engine/cli.py

@@ -0,0 +1,392 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import shlex
+import sys
+
+from .doctor import run_doctor
+from .execution import ExecutionMode, ExecutionSupervisor
+from .models import Goal, WorldState
+from .planning import CapabilityPlanner
+from .qualification import run_cross_vendor_smoke
+from .qualification_cli import add_qualification_parsers, run_qualification_command
+from .robots import CATALOG
+from .simulation import DeterministicSimulationBackend
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="devagent-physical")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("doctor", help="Check core Python runtime")
+    sub.add_parser("qualify", help="Run deterministic cross-vendor smoke qualification")
+    add_qualification_parsers(sub)
+
+    setup = sub.add_parser(
+        "setup",
+        help="Configure an explicit system profile; pip installation never changes OS packages",
+    )
+    setup.add_argument("--profile", choices=("ur5e-sim",), required=True)
+    setup.add_argument(
+        "--yes",
+        action="store_true",
+        help="Approve required system package changes non-interactively",
+    )
+    setup.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show checks and required packages without changing the system",
+    )
+    setup.add_argument("--json", action="store_true", help="Emit machine-readable setup result")
+
+    sim = sub.add_parser("simulate", help="Run deterministic non-ROS simulation backend")
+    sim.add_argument("--robot", choices=sorted(CATALOG), default="ur5e")
+    sim.add_argument("--object", default="P17")
+    sim.add_argument("--source", default="conveyor_a")
+    sim.add_argument("--destination", default="cnc_04")
+    sim.add_argument("--inject-collision", action="store_true")
+
+    ros = sub.add_parser("ros", help="ROS 2 / Gazebo integration commands")
+    ros.add_argument("--ros-setup", default="/opt/ros/jazzy/setup.bash")
+    ros.add_argument("--workspace-setup", default=None)
+    ros_sub = ros.add_subparsers(dest="ros_command", required=True)
+
+    ros_sub.add_parser("doctor", help="Check ROS 2 Jazzy and UR simulation dependencies")
+
+    launch = ros_sub.add_parser("launch", help="Launch official UR5e Gazebo + MoveIt visual simulation")
+    launch.add_argument("--world-file", default=None)
+    launch.add_argument("--log-dir", default="~/.devagent/simulation")
+    launch.add_argument("--dry-run", action="store_true")
+
+    acceptance = ros_sub.add_parser("acceptance", help="Run laptop UR5e visual simulation acceptance")
+    acceptance.add_argument("--log-dir", default="~/.devagent/acceptance")
+    acceptance.add_argument("--report", default=None)
+    acceptance.add_argument("--startup-timeout", type=float, default=120.0)
+    acceptance.add_argument("--motion-timeout", type=float, default=90.0)
+    acceptance.add_argument("--keep-open", action="store_true")
+
+    demo = ros_sub.add_parser(
+        "demo",
+        help="Launch Gazebo + MoveIt, move the UR5e, verify motion, and keep the visual open",
+    )
+    demo.add_argument("--log-dir", default="~/.devagent/demo")
+    demo.add_argument("--report", default=None)
+    demo.add_argument("--startup-timeout", type=float, default=120.0)
+    demo.add_argument("--motion-timeout", type=float, default=90.0)
+    demo.add_argument(
+        "--close-after",
+        action="store_true",
+        help="Close Gazebo after a successful demo instead of leaving it visible",
+    )
+
+    trajectory = ros_sub.add_parser(
+        "qualify-trajectory-runtime",
+        help="Qualify only the compiled UR5e trajectory execution/measurement scope",
+    )
+    trajectory.add_argument("--log-dir", default="~/.devagent/trajectory-qualification")
+    trajectory.add_argument("--report", default=None)
+    trajectory.add_argument("--startup-timeout", type=float, default=120.0)
+
+    return parser
+
+
+def _setup_profile(args: argparse.Namespace) -> int:
+    from .ros2 import RosDoctor, SubprocessRosRunner
+    from .setup_profile import (
+        SubprocessSystemRunner,
+        UR5eSimulationSetup,
+        format_setup_plan,
+    )
+
+    def verify_ros_stack() -> bool:
+        try:
+            runner = SubprocessRosRunner(ros_setup="/opt/ros/jazzy/setup.bash")
+            return RosDoctor(runner, ros_setup="/opt/ros/jazzy/setup.bash").run().passed
+        except Exception:
+            return False
+
+    progress = (
+        None
+        if args.json
+        else lambda message: print(message, file=sys.stderr, flush=True)
+    )
+    setup = UR5eSimulationSetup(
+        runner=SubprocessSystemRunner(stream_mutations=not args.json),
+        verifier=verify_ros_stack,
+        progress=progress,
+    )
+    plan = setup.inspect()
+    if not args.json:
+        print(format_setup_plan(plan))
+
+    if not plan.supported:
+        if args.json:
+            print(json.dumps(plan.to_dict(), indent=2))
+        else:
+            print(
+                "Unsupported platform for the qualified UR5e simulation profile; "
+                "no system changes were made."
+            )
+        return 8
+
+    if args.dry_run:
+        if args.json:
+            print(json.dumps(plan.to_dict(), indent=2))
+        else:
+            print("No system changes were made (dry-run).")
+        return 0
+
+    if plan.needs_install and not args.yes:
+        try:
+            answer = input("Install required system packages now? [y/N] ").strip().lower()
+        except EOFError:
+            answer = ""
+        if answer not in {"y", "yes"}:
+            if args.json:
+                print(
+                    json.dumps(
+                        {
+                            "profile": plan.profile,
+                            "passed": False,
+                            "failure_code": "setup_cancelled",
+                        },
+                        indent=2,
+                    )
+                )
+            else:
+                print("Setup cancelled; no system changes were made.")
+            return 7
+
+    result = setup.install(plan)
+    if args.json:
+        print(json.dumps(result.to_dict(), indent=2))
+    elif result.passed:
+        if result.changed_system:
+            print("UR5e simulation profile installed and verified.")
+        else:
+            print("UR5e simulation profile already installed and verified.")
+        print("Next: devagent-physical ros demo")
+    else:
+        print(f"Setup failed closed: {result.failure_code or 'verification_failed'}")
+    return 0 if result.passed else 9
+
+
+def _core_qualify() -> int:
+    summary = run_cross_vendor_smoke()
+    print(
+        json.dumps(
+            {
+                "passed": summary.passed,
+                "violations": summary.violations,
+                "cases": [
+                    {
+                        "robot": case.robot,
+                        "passed": case.passed,
+                        "executed_tasks": case.executed_tasks,
+                        "violations": case.violations,
+                    }
+                    for case in summary.cases
+                ],
+            },
+            indent=2,
+        )
+    )
+    return 0 if summary.passed else 1
+
+
+def _deterministic_simulate(args: argparse.Namespace) -> int:
+    resource = CATALOG[args.robot]()
+    goal = Goal("cli-goal", "load", args.object, args.source, args.destination)
+    graph = CapabilityPlanner().plan(goal, [resource])
+    world = WorldState(facts={"robot_ready", "object_available"})
+    backend = DeterministicSimulationBackend({"T2"} if args.inject_collision else None)
+    report = ExecutionSupervisor().execute(
+        graph, [resource], world, backend, ExecutionMode.SIMULATION
+    )
+    print(
+        json.dumps(
+            {
+                "completed": report.completed,
+                "executed_tasks": report.executed_tasks,
+                "blocked_task": report.blocked_task,
+                "issues": [
+                    {"code": issue.code, "task_id": issue.task_id, "detail": issue.detail}
+                    for issue in report.issues
+                ],
+                "world_facts": sorted(world.facts),
+            },
+            indent=2,
+        )
+    )
+    return 0 if report.completed else 2
+
+
+def _ros_runner(args: argparse.Namespace):
+    from .ros2 import SubprocessRosRunner
+
+    return SubprocessRosRunner(
+        ros_setup=args.ros_setup,
+        workspace_setup=args.workspace_setup,
+    )
+
+
+def _ros_doctor(args: argparse.Namespace) -> int:
+    from .ros2 import RosDoctor
+
+    report = RosDoctor(_ros_runner(args), ros_setup=args.ros_setup).run()
+    for check in report.checks:
+        label = "PASS" if check.passed else ("WARN" if not check.required else "FAIL")
+        print(f"{check.name}: {label} ({check.detail})")
+    return 0 if report.passed else 3
+
+
+def _ros_launch(args: argparse.Namespace) -> int:
+    from datetime import datetime, timezone
+    from .ros2 import UR5eSimulationLauncher, official_ur5e_moveit_command
+
+    command = official_ur5e_moveit_command(world_file=args.world_file)
+    if args.dry_run:
+        print(shlex.join(command))
+        return 0
+
+    log_dir = Path(args.log_dir).expanduser().resolve()
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    log_path = log_dir / f"ur5e-visual-{timestamp}.log"
+    simulation = UR5eSimulationLauncher(_ros_runner(args)).launch(
+        log_path=log_path,
+        world_file=args.world_file,
+    )
+    print(f"UR5e visual simulation started (pid={simulation.process.pid})")
+    print(f"Log: {simulation.log_path}")
+    print("Gazebo + MoveIt/RViz are launched by the official ur_simulation_gz package.")
+    print("Press Ctrl-C to stop.")
+    try:
+        return simulation.process.wait()
+    except KeyboardInterrupt:
+        simulation.stop()
+        return 130
+
+
+def _ros_acceptance(args: argparse.Namespace) -> int:
+    from .ros2 import UR5eLaptopAcceptance
+
+    report = UR5eLaptopAcceptance(
+        _ros_runner(args), ros_setup=args.ros_setup
+    ).run(
+        log_dir=Path(args.log_dir),
+        startup_timeout_s=args.startup_timeout,
+        motion_timeout_s=args.motion_timeout,
+        keep_open=args.keep_open,
+    )
+    report_path = (
+        Path(args.report).expanduser().resolve()
+        if args.report
+        else Path(args.log_dir).expanduser().resolve() / "latest-acceptance.json"
+    )
+    report.write_json(report_path)
+    print(json.dumps(report.to_dict(), indent=2))
+    print(f"Acceptance report: {report_path}")
+    return 0 if report.passed else 4
+
+
+def _ros_demo(args: argparse.Namespace) -> int:
+    from .ros2 import UR5eLaptopAcceptance
+
+    report = UR5eLaptopAcceptance(
+        _ros_runner(args), ros_setup=args.ros_setup
+    ).run(
+        log_dir=Path(args.log_dir),
+        startup_timeout_s=args.startup_timeout,
+        motion_timeout_s=args.motion_timeout,
+        keep_open=not args.close_after,
+    )
+    report_path = (
+        Path(args.report).expanduser().resolve()
+        if args.report
+        else Path(args.log_dir).expanduser().resolve() / "latest-demo.json"
+    )
+    report.write_json(report_path)
+    print(json.dumps(report.to_dict(), indent=2))
+    print(f"Demo report: {report_path}")
+    if report.passed and not args.close_after:
+        print("VISUAL DEMO PASS: Gazebo + MoveIt/RViz remain open so you can inspect the moved UR5e.")
+    elif report.passed:
+        print("VISUAL DEMO PASS: UR5e motion was measured and the simulator was closed cleanly.")
+    return 0 if report.passed else 5
+
+
+def _ros_trajectory_runtime_qualification(args: argparse.Namespace) -> int:
+    from .ros2.qualification import (
+        ur5e_trajectory_runtime_cases,
+        ur5e_trajectory_runtime_twin,
+    )
+    from .ros2.ur5e_adapter import UR5eGazeboAdapter
+    from .trajectory_qualification import TrajectoryRuntimeQualificationRunner
+
+    log_dir = Path(args.log_dir).expanduser().resolve()
+    twin = ur5e_trajectory_runtime_twin()
+    adapter = UR5eGazeboAdapter(
+        _ros_runner(args),
+        ros_setup=args.ros_setup,
+        log_dir=log_dir / "simulation",
+        startup_timeout_s=args.startup_timeout,
+    )
+    report = TrajectoryRuntimeQualificationRunner().run(
+        adapter=adapter,
+        twin=twin,
+        cases=ur5e_trajectory_runtime_cases(twin),
+    )
+    payload = report.to_dict()
+    report_path = (
+        Path(args.report).expanduser().resolve()
+        if args.report
+        else log_dir / "latest-trajectory-runtime.json"
+    )
+    report_path.parent.mkdir(parents=True, exist_ok=True)
+    report_path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps(payload, indent=2))
+    print(f"Trajectory runtime qualification report: {report_path}")
+    return 0 if report.promotion_candidate else 6
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+
+    if args.command == "doctor":
+        checks = run_doctor()
+        for check in checks:
+            print(f"{check.name}: {'PASS' if check.passed else 'FAIL'} ({check.detail})")
+        return 0 if all(check.passed for check in checks) else 1
+
+    if args.command == "qualify":
+        return _core_qualify()
+
+    qualification_code = run_qualification_command(args)
+    if qualification_code is not None:
+        return qualification_code
+
+    if args.command == "setup":
+        return _setup_profile(args)
+
+    if args.command == "simulate":
+        return _deterministic_simulate(args)
+
+    if args.command == "ros":
+        if args.ros_command == "doctor":
+            return _ros_doctor(args)
+        if args.ros_command == "launch":
+            return _ros_launch(args)
+        if args.ros_command == "acceptance":
+            return _ros_acceptance(args)
+        if args.ros_command == "demo":
+            return _ros_demo(args)
+        if args.ros_command == "qualify-trajectory-runtime":
+            return _ros_trajectory_runtime_qualification(args)
+
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

devagent_physical_engine/doctor.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import importlib.util
+import platform
+import sys
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Check:
+    name: str
+    passed: bool
+    detail: str
+
+
+def run_doctor() -> tuple[Check, ...]:
+    return (
+        Check("python", sys.version_info >= (3, 11), platform.python_version()),
+        Check("core_package", importlib.util.find_spec("devagent_physical_engine") is not None, "importable"),
+    )

devagent_physical_engine/engineering_agent.py

@@ -0,0 +1,243 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any, Sequence
+
+from .agent.contracts import AgentEvidence, RoutingPolicy
+from .agent.coordinator import PlanningCoordinationError, PlanningCoordinator, VerifiedPlanArtifact
+from .agent.critic import CriticAgent
+from .agent.evidence import task_graph_to_dict
+from .agent.interpreter import InterpretedEngineeringRequest, RequirementInterpreterAgent
+from .agent.planner import PlannerAgent
+from .engineering_request import Objective, RequestPurpose, TestPreset, ValidatedEngineeringRequest
+from .execution import ExecutionMode, ExecutionSupervisor
+from .models import WorldState
+from .simulation import DeterministicSimulationBackend
+
+
+@dataclass(frozen=True, slots=True)
+class AdaptiveReasoningStrategy:
+    risk_score: int
+    max_revision_rounds: int
+    min_critic_score: float
+    future_physical_candidate_target: int
+    reasons: tuple[str, ...]
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+class AdaptiveReasoningPolicy:
+    """Spend AI calls where engineering risk justifies them.
+
+    v0.7 intentionally optimizes reasoning depth rather than asking an LLM for
+    many superficially different high-level pick/move/place graphs. Physical
+    candidate diversity belongs to the measured motion/simulation layer.
+    """
+
+    def select(self, request: ValidatedEngineeringRequest) -> AdaptiveReasoningStrategy:
+        score = 0
+        reasons: list[str] = []
+
+        if request.purpose is RequestPurpose.COMMISSIONING:
+            score += 3
+            reasons.append("commissioning_intent")
+        elif request.purpose is RequestPurpose.QUALIFY:
+            score += 2
+            reasons.append("qualification_intent")
+        elif request.purpose is RequestPurpose.SIMULATE:
+            score += 1
+            reasons.append("simulation_intent")
+
+        if request.test_preset in {TestPreset.ROBUSTNESS, TestPreset.STRESS}:
+            score += 2
+            reasons.append("high_coverage_test_preset")
+        if request.variation.configured:
+            score += 2
+            reasons.append("physical_variation_requested")
+        if request.faults:
+            score += 2
+            reasons.append("fault_injection_requested")
+        if request.minimum_clearance_mm is not None or request.max_cycle_time_s is not None:
+            score += 1
+            reasons.append("explicit_engineering_threshold")
+        if request.objective is not Objective.BALANCED:
+            score += 1
+            reasons.append("explicit_optimization_objective")
+
+        if score >= 7:
+            return AdaptiveReasoningStrategy(score, 3, 0.85, 7, tuple(reasons))
+        if score >= 4:
+            return AdaptiveReasoningStrategy(score, 2, 0.78, 5, tuple(reasons))
+        return AdaptiveReasoningStrategy(score, 1, 0.70, 3, tuple(reasons))
+
+
+@dataclass(frozen=True, slots=True)
+class SmartEngineeringResult:
+    interpretation: InterpretedEngineeringRequest
+    reasoning_strategy: AdaptiveReasoningStrategy | None = None
+    plan: VerifiedPlanArtifact | None = None
+    deterministic_simulation_completed: bool = False
+    failure_code: str | None = None
+
+    @property
+    def ready_for_twin_simulation(self) -> bool:
+        return (
+            self.interpretation.validated is not None
+            and self.plan is not None
+            and self.deterministic_simulation_completed
+            and self.failure_code is None
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "interpretation": self.interpretation.to_dict(),
+            "reasoning_strategy": (
+                self.reasoning_strategy.to_dict()
+                if self.reasoning_strategy is not None
+                else None
+            ),
+            "deterministic_simulation_completed": self.deterministic_simulation_completed,
+            "physical_qualification": False,
+            "ready_for_twin_simulation": self.ready_for_twin_simulation,
+            "failure_code": self.failure_code,
+            "next_stage": (
+                "validated_twin_and_measured_physics_simulation"
+                if self.ready_for_twin_simulation
+                else None
+            ),
+        }
+        if self.plan is not None:
+            payload["plan"] = {
+                "graph_hash": self.plan.graph_hash,
+                "graph": task_graph_to_dict(self.plan.graph),
+                "revision_rounds": self.plan.revision_rounds,
+                "planner_calls": len(self.plan.planner_evidence),
+                "critic_calls": len(self.plan.critic_evidence),
+                "selection_claim": (
+                    "verified_high_level_plan_only; not yet a measured optimized motion plan"
+                ),
+            }
+        else:
+            payload["plan"] = None
+        return payload
+
+
+class SmartEngineeringAgent:
+    """Natural language -> verified high-level plan -> deterministic model smoke.
+
+    This is deliberately not a physical commissioning claim. The result becomes
+    eligible for the next Twin/ROS stage only after interpretation, deterministic
+    compilation, planner/critic verification, and deterministic model execution
+    all succeed.
+    """
+
+    def __init__(
+        self,
+        interpreter: RequirementInterpreterAgent,
+        planner: PlannerAgent,
+        critic: CriticAgent,
+        *,
+        reasoning_policy: AdaptiveReasoningPolicy | None = None,
+    ) -> None:
+        self.interpreter = interpreter
+        self.planner = planner
+        self.critic = critic
+        self.reasoning_policy = reasoning_policy or AdaptiveReasoningPolicy()
+
+    def run(
+        self,
+        text: str,
+        *,
+        interpreter_policy: RoutingPolicy,
+        planner_policy: RoutingPolicy,
+        critic_policy: RoutingPolicy,
+        follow_ups: Sequence[str] = (),
+    ) -> SmartEngineeringResult:
+        interpreted = self.interpreter.interpret(
+            text,
+            interpreter_policy,
+            follow_ups=follow_ups,
+        )
+        request = interpreted.validated
+        if request is None:
+            return SmartEngineeringResult(
+                interpretation=interpreted,
+                failure_code=interpreted.rejection_code,
+            )
+
+        strategy = self.reasoning_policy.select(request)
+        goal = request.goal()
+        resources = [request.resource()]
+        # Explicit nominal model state, never represented as observed site state.
+        world = WorldState(
+            facts={"robot_ready", "object_available"},
+            values={
+                "state_origin": "devagent_nominal_planning_model",
+                "request_id": request.request_id,
+            },
+        )
+        coordinator = PlanningCoordinator(
+            self.planner,
+            self.critic,
+            max_revision_rounds=strategy.max_revision_rounds,
+            min_accept_score=strategy.min_critic_score,
+        )
+        try:
+            plan = coordinator.create_verified_plan(
+                goal,
+                resources,
+                world,
+                planner_policy,
+                critic_policy,
+                engineering_context=request.to_dict(),
+            )
+        except PlanningCoordinationError as exc:
+            return SmartEngineeringResult(
+                interpretation=interpreted,
+                reasoning_strategy=strategy,
+                failure_code=f"planning_failed:{str(exc).split(':', 1)[0]}",
+            )
+        except Exception as exc:
+            # Never expose provider/internal exception text as customer evidence.
+            return SmartEngineeringResult(
+                interpretation=interpreted,
+                reasoning_strategy=strategy,
+                failure_code=f"planning_failed:{type(exc).__name__}",
+            )
+
+        simulation_world = WorldState(facts=set(world.facts), values=dict(world.values))
+        simulation = ExecutionSupervisor().execute(
+            plan.graph,
+            resources,
+            simulation_world,
+            DeterministicSimulationBackend(),
+            ExecutionMode.SIMULATION,
+        )
+        if not simulation.completed:
+            issue_codes = sorted({issue.code for issue in simulation.issues})
+            return SmartEngineeringResult(
+                interpretation=interpreted,
+                reasoning_strategy=strategy,
+                plan=plan,
+                deterministic_simulation_completed=False,
+                failure_code=(
+                    "deterministic_simulation_failed:"
+                    + (",".join(issue_codes) if issue_codes else "unknown")
+                ),
+            )
+
+        return SmartEngineeringResult(
+            interpretation=interpreted,
+            reasoning_strategy=strategy,
+            plan=plan,
+            deterministic_simulation_completed=True,
+        )
+
+
+def successful_agent_evidence(result: SmartEngineeringResult) -> tuple[AgentEvidence, ...]:
+    items: list[AgentEvidence] = [result.interpretation.evidence]
+    if result.plan is not None:
+        items.extend(result.plan.planner_evidence)
+        items.extend(result.plan.critic_evidence)
+    return tuple(items)