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

devagent_physical_engine/agent/evidence.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from hashlib import sha256
+
+from .structured import canonical_json
+from ..models import TaskGraph
+
+
+def task_graph_to_dict(graph: TaskGraph) -> dict:
+    return {
+        "goal_id": graph.goal_id,
+        "tasks": [
+            {
+                "task_id": task.task_id,
+                "action": task.contract.action.value,
+                "resource_id": task.contract.resource_id,
+                "object_id": task.contract.object_id,
+                "source": task.contract.source,
+                "destination": task.contract.destination,
+                "preconditions": list(task.contract.preconditions),
+                "expected_effects": list(task.contract.expected_effects),
+                "constraints": list(task.contract.constraints),
+                "timeout_ms": task.contract.timeout_ms,
+                "depends_on": list(task.depends_on),
+            }
+            for task in graph.tasks
+        ],
+    }
+
+
+def task_graph_hash(graph: TaskGraph) -> str:
+    return sha256(
+        canonical_json(task_graph_to_dict(graph)).encode("utf-8")
+    ).hexdigest()

devagent_physical_engine/agent/interpreter.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping, Sequence
+
+from .contracts import AgentEvidence, AgentRole, RoutingPolicy
+from .runtime import AgentRuntime, InvocationResult
+from .structured import StructuredOutputError
+from ..engineering_request import (
+    ENGINEERING_REQUEST_SCHEMA,
+    EngineeringRequestCompiler,
+    EngineeringRequestDraft,
+    EngineeringRequestError,
+    RequestAssessment,
+    RequestCompletenessValidator,
+    RequestState,
+    ValidatedEngineeringRequest,
+    parse_engineering_request_draft,
+)
+from ..planning import SUPPORTED_GOAL_ACTIONS
+from ..robots import CATALOG, PROFILE_REGISTRY
+
+
+INTERPRETER_SYSTEM = """You are the DevAgent Engineering Requirement Interpreter.
+Convert the user's natural-language robotic engineering request into the exact structured schema.
+
+Rules:
+1. Extract only information the user explicitly supplied or that is unambiguous from the supplied conversation.
+2. Never invent or silently assume engineering-critical facts such as robot, part, source, destination, payload, dimensions, geometry, tool, clearances, or limits.
+3. If a field is missing, output null. If a field is ambiguous or you are not confident it is exactly what the user meant, include that field name in uncertain_fields. Never choose among multiple plausible values.
+4. Safe system constraints such as collision checking and joint-limit enforcement are owned by deterministic code and must not be invented as user statements.
+5. Normalize units into the schema units only when the conversion is exact. Preserve uncertainty instead of guessing.
+6. 'Fastest' or 'shortest cycle' maps to cycle_time. 'Most robust/reliable' maps to robustness. 'Largest safety margin/clearance' maps to clearance. Otherwise use balanced unless the user explicitly asks for energy.
+7. Use custom test_preset only when the user supplied an exact run count. Otherwise map ordinary wording to quick, engineering, robustness, or stress conservatively.
+8. purpose is commissioning only when the user explicitly asks about onsite readiness, commissioning, deployment confidence, or transfer to the real robot; use qualify for broad qualification/testing, simulate for simulation, otherwise plan.
+9. When a user names a registered robot or alias, emit the canonical robot key supplied in engine_context.robot_profiles. Do not invent a different robot key.
+10. notes may summarize non-critical user statements. Do not put hidden reasoning in notes.
+11. Output only schema fields. The deterministic compiler decides whether the request is supported, complete, or rejected.
+"""
+
+
+@dataclass(frozen=True, slots=True)
+class InterpretedEngineeringRequest:
+    draft: EngineeringRequestDraft
+    assessment: RequestAssessment
+    evidence: AgentEvidence
+    validated: ValidatedEngineeringRequest | None = None
+    rejection_code: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "draft": self.draft.to_dict(),
+            "assessment": self.assessment.to_dict(),
+            "validated": self.validated.to_dict() if self.validated is not None else None,
+            "rejection_code": self.rejection_code,
+            "evidence": {
+                "trace_id": self.evidence.trace_id,
+                "role": self.evidence.role.value,
+                "input_hash": self.evidence.input_hash,
+                "output_hash": self.evidence.output_hash,
+                "selected_provider": self.evidence.selected_provider,
+                "selected_model": self.evidence.selected_model,
+                "attempts": [
+                    {
+                        "provider": attempt.provider,
+                        "model": attempt.model,
+                        "outcome": attempt.outcome,
+                        "error_code": attempt.error_code,
+                        "latency_ms": attempt.latency_ms,
+                        "request_id": attempt.request_id,
+                    }
+                    for attempt in self.evidence.attempts
+                ],
+            },
+        }
+
+
+class RequirementInterpreterAgent:
+    """Natural-language front door with deterministic completeness/compile gates."""
+
+    def __init__(
+        self,
+        runtime: AgentRuntime,
+        *,
+        completeness: RequestCompletenessValidator | None = None,
+        compiler: EngineeringRequestCompiler | None = None,
+    ) -> None:
+        self.runtime = runtime
+        self.completeness = completeness or RequestCompletenessValidator()
+        self.compiler = compiler or EngineeringRequestCompiler(self.completeness)
+
+    def interpret(
+        self,
+        text: str,
+        policy: RoutingPolicy,
+        *,
+        follow_ups: Sequence[str] = (),
+    ) -> InterpretedEngineeringRequest:
+        initial = text.strip()
+        if not initial:
+            raise ValueError("request_text_required")
+        if len(initial) > 16_384:
+            raise ValueError("request_text_too_long")
+        normalized_follow_ups = tuple(item.strip() for item in follow_ups if item.strip())
+        if len(normalized_follow_ups) > 16:
+            raise ValueError("too_many_follow_ups")
+        if any(len(item) > 8_192 for item in normalized_follow_ups):
+            raise ValueError("follow_up_too_long")
+
+        robot_profiles = [
+            {
+                "key": profile.key,
+                "vendor": profile.vendor,
+                "model": profile.model,
+                "aliases": list(profile.aliases),
+            }
+            for profile in PROFILE_REGISTRY.all()
+        ]
+        input_payload = {
+            "conversation": {
+                "initial_request": initial,
+                "follow_ups": list(normalized_follow_ups),
+            },
+            "engine_context": {
+                "known_robot_keys": sorted(CATALOG),
+                "robot_profiles": robot_profiles,
+                "currently_supported_goal_actions": sorted(SUPPORTED_GOAL_ACTIONS),
+                "instruction": (
+                    "Known engine capabilities are context for interpretation only. "
+                    "Map registered aliases to their canonical key. Do not rewrite an "
+                    "unsupported user request into a supported one."
+                ),
+            },
+        }
+
+        def validate(payload: Mapping[str, Any]) -> EngineeringRequestDraft:
+            try:
+                return parse_engineering_request_draft(payload)
+            except EngineeringRequestError as exc:
+                raise StructuredOutputError(str(exc)) from exc
+
+        invocation: InvocationResult = self.runtime.invoke(
+            role=AgentRole.INTERPRETER,
+            system_instruction=INTERPRETER_SYSTEM,
+            input_payload=input_payload,
+            output_schema=ENGINEERING_REQUEST_SCHEMA,
+            policy=policy,
+            validator=validate,
+        )
+        draft = invocation.value
+        assessment = self.completeness.assess(draft)
+        if not assessment.ready:
+            return InterpretedEngineeringRequest(
+                draft=draft,
+                assessment=assessment,
+                evidence=invocation.evidence,
+            )
+
+        try:
+            validated = self.compiler.compile(draft)
+        except EngineeringRequestError as exc:
+            rejection_code = str(exc)
+            rejected = RequestAssessment(
+                state=RequestState.REJECTED,
+                rejection_codes=(rejection_code,),
+                open_items=assessment.open_items,
+            )
+            return InterpretedEngineeringRequest(
+                draft=draft,
+                assessment=rejected,
+                evidence=invocation.evidence,
+                rejection_code=rejection_code,
+            )
+        return InterpretedEngineeringRequest(
+            draft=draft,
+            assessment=assessment,
+            evidence=invocation.evidence,
+            validated=validated,
+        )

devagent_physical_engine/agent/planner.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from .compiler import AGENT_PLAN_SCHEMA, AgentPlanCompiler
+from .contracts import AgentEvidence, AgentRole, RoutingPolicy
+from .runtime import AgentRuntime, InvocationResult
+from .structured import StructuredOutputError, json_safe
+from ..models import Goal, Resource, TaskGraph, WorldState
+from ..planning import PlanningError, SUPPORTED_GOAL_ACTIONS
+from ..verification import DeterministicVerifier
+
+PLANNER_SYSTEM = """You are the DevAgent task planner. Propose only high-level tasks using the requested schema. Never emit raw servo commands, preconditions, effects, safety claims, controller permissions, or motion constraints. The deterministic engine owns those contracts. Unknown state must never be guessed. When validated engineering context is provided, use it to seek a suitable high-level decomposition, but never convert optimization preferences into permission to violate hard constraints."""
+
+
+@dataclass(frozen=True, slots=True)
+class PlannerResult:
+    graph: TaskGraph
+    evidence: AgentEvidence
+
+
+def _resource_payload(resource: Resource) -> dict[str, Any]:
+    return {
+        "resource_id": resource.resource_id,
+        "resource_type": resource.resource_type,
+        "capabilities": sorted(
+            capability.value for capability in resource.capabilities
+        ),
+        "metadata": dict(resource.metadata),
+    }
+
+
+class PlannerAgent:
+    """LLM planner whose proposal is compiled into deterministic contracts."""
+
+    def __init__(
+        self,
+        runtime: AgentRuntime,
+        verifier: DeterministicVerifier | None = None,
+        compiler: AgentPlanCompiler | None = None,
+    ) -> None:
+        self.runtime = runtime
+        self.verifier = verifier or DeterministicVerifier()
+        self.compiler = compiler or AgentPlanCompiler()
+
+    def plan(
+        self,
+        goal: Goal,
+        resources: list[Resource],
+        world: WorldState,
+        policy: RoutingPolicy,
+        *,
+        feedback: tuple[str, ...] = (),
+        engineering_context: Mapping[str, Any] | None = None,
+    ) -> PlannerResult:
+        goal_action = goal.action.strip().lower()
+        if goal_action not in SUPPORTED_GOAL_ACTIONS:
+            raise PlanningError(f"unsupported_goal_action:{goal_action}")
+
+        input_payload = {
+            "goal": {
+                "goal_id": goal.goal_id,
+                "action": goal.action,
+                "object_id": goal.object_id,
+                "source": goal.source,
+                "destination": goal.destination,
+            },
+            "resources": [_resource_payload(resource) for resource in resources],
+            "world": {
+                "facts": sorted(world.facts),
+                "values": dict(world.values),
+            },
+            "feedback": list(feedback),
+        }
+        if engineering_context is not None:
+            input_payload["validated_engineering_context"] = json_safe(engineering_context)
+
+        def validate(payload: Mapping[str, Any]) -> TaskGraph:
+            graph = self.compiler.compile(
+                payload,
+                goal=goal,
+                resources=resources,
+                world=world,
+            )
+            structural = self.verifier.verify_graph(graph, resources)
+            if not structural.passed:
+                detail = ";".join(
+                    f"{issue.code}:{issue.task_id or ''}:{issue.detail}"
+                    for issue in structural.issues
+                )
+                raise StructuredOutputError(
+                    f"deterministic_verification_failed:{detail}"
+                )
+            return graph
+
+        invocation: InvocationResult = self.runtime.invoke(
+            role=AgentRole.PLANNER,
+            system_instruction=PLANNER_SYSTEM,
+            input_payload=input_payload,
+            output_schema=AGENT_PLAN_SCHEMA,
+            policy=policy,
+            validator=validate,
+        )
+        return PlannerResult(invocation.value, invocation.evidence)

devagent_physical_engine/agent/recovery.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .contracts import AgentEvidence, AgentRole, RecoveryAdvice, RoutingPolicy
+from .runtime import AgentRuntime, InvocationResult
+from .structured import RECOVERY_SCHEMA, parse_recovery
+from ..models import WorldState
+
+RECOVERY_SYSTEM = """You are the DevAgent recovery advisor. Recommend only bounded recovery actions: retry, replan, wait, observe, or abort. You cannot issue hardware commands, override interlocks, or bypass deterministic verification. Prefer abort or observe when state is uncertain."""
+
+
+@dataclass(frozen=True, slots=True)
+class RecoveryResult:
+    advice: RecoveryAdvice
+    evidence: AgentEvidence
+
+
+class RecoveryAgent:
+    """Generate bounded recovery advice; never direct hardware commands."""
+
+    def __init__(self, runtime: AgentRuntime) -> None:
+        self.runtime = runtime
+
+    def advise(
+        self,
+        *,
+        task_id: str,
+        issue_codes: tuple[str, ...],
+        world: WorldState,
+        policy: RoutingPolicy,
+    ) -> RecoveryResult:
+        if not task_id.strip():
+            raise ValueError("task_id_required")
+        if not issue_codes:
+            raise ValueError("issue_codes_required")
+
+        input_payload = {
+            "task_id": task_id,
+            "issue_codes": list(issue_codes),
+            "world": {
+                "facts": sorted(world.facts),
+                "values": dict(world.values),
+            },
+        }
+        invocation: InvocationResult = self.runtime.invoke(
+            role=AgentRole.RECOVERY,
+            system_instruction=RECOVERY_SYSTEM,
+            input_payload=input_payload,
+            output_schema=RECOVERY_SCHEMA,
+            policy=policy,
+            validator=parse_recovery,
+        )
+        return RecoveryResult(invocation.value, invocation.evidence)

devagent_physical_engine/agent/routing.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from .contracts import AgentRole, RoutingPolicy, RoutingStrategy
+from ..providers import ModelRegistry, ModelSpec, QualificationStatus
+
+
+class RoutingError(RuntimeError):
+    pass
+
+
+class ModelRouter:
+    """Choose qualified models without coupling agents to a provider SDK."""
+
+    def __init__(self, registry: ModelRegistry) -> None:
+        self.registry = registry
+
+    def candidates(
+        self, role: AgentRole, policy: RoutingPolicy
+    ) -> tuple[ModelSpec, ...]:
+        statuses = (
+            {QualificationStatus.QUALIFIED}
+            if policy.require_qualified
+            else {
+                QualificationStatus.QUALIFIED,
+                QualificationStatus.SIMULATION_ONLY,
+            }
+        )
+
+        specs = [
+            spec
+            for spec in self.registry.all()
+            if spec.status in statuses
+            and spec.supports_structured_output
+            and spec.supports_role(role.value)
+            and spec.quality_score >= policy.min_quality
+        ]
+
+        if policy.strategy is RoutingStrategy.FIXED:
+            specs = [
+                spec
+                for spec in specs
+                if spec.provider == policy.fixed_provider
+                and spec.model == policy.fixed_model
+            ]
+        elif policy.strategy is RoutingStrategy.PRIVATE_ONLY:
+            specs = [spec for spec in specs if spec.private]
+
+        if not specs:
+            raise RoutingError(
+                f"no_eligible_model:{role.value}:{policy.strategy.value}"
+            )
+
+        if policy.strategy is RoutingStrategy.LOWEST_COST:
+            score = lambda spec: (
+                spec.cost_score,
+                spec.quality_score,
+                spec.latency_score,
+            )
+        elif policy.strategy is RoutingStrategy.LOWEST_LATENCY:
+            score = lambda spec: (
+                spec.latency_score,
+                spec.quality_score,
+                spec.cost_score,
+            )
+        else:
+            # AUTO_BEST intentionally prioritizes reasoning quality. Users who prefer
+            # cost or latency can select those explicit strategies instead.
+            score = lambda spec: (
+                0.80 * spec.quality_score
+                + 0.10 * spec.latency_score
+                + 0.10 * spec.cost_score,
+                spec.quality_score,
+                spec.latency_score,
+            )
+
+        return tuple(sorted(specs, key=score, reverse=True))