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

devagent_physical_engine/agent/runtime.py

@@ -0,0 +1,270 @@
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor, TimeoutError as FutureTimeout
+from dataclasses import dataclass
+from hashlib import sha256
+from time import monotonic
+from typing import Any, Callable, Mapping, Protocol, TypeVar
+from uuid import uuid4
+
+from .contracts import (
+    AgentEvidence,
+    AgentRole,
+    ModelAttempt,
+    ModelRequest,
+    ModelResponse,
+    RoutingPolicy,
+)
+from .routing import ModelRouter, RoutingError
+from .structured import (
+    JsonSafetyError,
+    StructuredOutputError,
+    canonical_json,
+    json_safe,
+    redact_sensitive,
+)
+from ..providers import ModelSpec
+
+T = TypeVar("T")
+
+
+class ProviderError(RuntimeError):
+    code = "provider_error"
+
+
+class ProviderTimeout(ProviderError):
+    code = "provider_timeout"
+
+
+class ProviderUnavailable(ProviderError):
+    code = "provider_unavailable"
+
+
+class ProviderProtocolError(ProviderError):
+    code = "provider_protocol_error"
+
+
+class StructuredModelProvider(Protocol):
+    @property
+    def provider_name(self) -> str: ...
+
+    def generate(
+        self, request: ModelRequest, *, model: str
+    ) -> ModelResponse: ...
+
+
+class ProviderPool:
+    """Registry of connected provider implementations.
+
+    The pool stores provider objects only. API keys remain the provider adapter's
+    responsibility and are intentionally not copied into evidence records.
+    """
+
+    def __init__(self) -> None:
+        self._providers: dict[str, StructuredModelProvider] = {}
+
+    def register(self, provider: StructuredModelProvider) -> None:
+        name = provider.provider_name.strip().lower()
+        if not name:
+            raise ValueError("provider_name_required")
+        if name in self._providers:
+            raise ValueError(f"duplicate_provider:{name}")
+        self._providers[name] = provider
+
+    def get(self, name: str) -> StructuredModelProvider:
+        key = name.strip().lower()
+        try:
+            return self._providers[key]
+        except KeyError as exc:
+            raise ProviderUnavailable(f"provider_not_connected:{key}") from exc
+
+
+@dataclass(frozen=True, slots=True)
+class InvocationResult:
+    value: Any
+    evidence: AgentEvidence
+
+
+class AgentRuntimeError(RuntimeError):
+    def __init__(self, message: str, evidence: AgentEvidence) -> None:
+        super().__init__(message)
+        self.evidence = evidence
+
+
+def _hash(value: Any) -> str:
+    return sha256(canonical_json(value).encode("utf-8")).hexdigest()
+
+
+class AgentRuntime:
+    """Bounded structured-output runtime with fallback and audit evidence.
+
+    Provider calls run behind a wall-clock guard. Provider adapters must also
+    configure their own network timeout. Error details from one provider are
+    never forwarded to another provider; retries receive only stable internal
+    error codes.
+    """
+
+    def __init__(self, router: ModelRouter, pool: ProviderPool) -> None:
+        self.router = router
+        self.pool = pool
+
+    @staticmethod
+    def _generate_with_timeout(
+        provider: StructuredModelProvider,
+        request: ModelRequest,
+        model: str,
+    ) -> ModelResponse:
+        executor = ThreadPoolExecutor(
+            max_workers=1, thread_name_prefix="devagent-provider"
+        )
+        future = executor.submit(provider.generate, request, model=model)
+        try:
+            return future.result(timeout=request.timeout_s)
+        except FutureTimeout as exc:
+            future.cancel()
+            raise ProviderTimeout(
+                f"provider_timeout_after:{request.timeout_s}s"
+            ) from exc
+        finally:
+            executor.shutdown(wait=False, cancel_futures=True)
+
+    def invoke(
+        self,
+        *,
+        role: AgentRole,
+        system_instruction: str,
+        input_payload: Mapping[str, Any],
+        output_schema: Mapping[str, Any],
+        policy: RoutingPolicy,
+        validator: Callable[[Mapping[str, Any]], T],
+    ) -> InvocationResult:
+        trace_id = uuid4().hex
+        try:
+            normalized_input = json_safe(redact_sensitive(input_payload))
+        except JsonSafetyError as exc:
+            evidence = AgentEvidence(trace_id, role, "invalid", None, ())
+            raise AgentRuntimeError(
+                f"agent_input_not_json_safe:{exc}", evidence
+            ) from exc
+
+        input_hash = _hash(normalized_input)
+        attempts: list[ModelAttempt] = []
+        feedback_code = ""
+
+        try:
+            candidates = self.router.candidates(role, policy)
+        except RoutingError as exc:
+            evidence = AgentEvidence(trace_id, role, input_hash, None, ())
+            raise AgentRuntimeError(str(exc), evidence) from exc
+
+        for attempt_index in range(policy.max_attempts):
+            spec: ModelSpec = candidates[attempt_index % len(candidates)]
+            payload = dict(normalized_input)
+            if feedback_code:
+                payload["retry_context"] = {
+                    "attempt": attempt_index + 1,
+                    "previous_error": feedback_code,
+                }
+
+            request = ModelRequest(
+                role=role,
+                system_instruction=system_instruction,
+                input_payload=payload,
+                output_schema=output_schema,
+                timeout_s=policy.timeout_s,
+            )
+            started = monotonic()
+            request_id = ""
+
+            try:
+                provider = self.pool.get(spec.provider)
+                response = self._generate_with_timeout(
+                    provider, request, spec.model
+                )
+                if not isinstance(response, ModelResponse):
+                    raise ProviderProtocolError(
+                        "provider_must_return_model_response"
+                    )
+
+                request_id = response.request_id
+                latency_ms = (
+                    response.latency_ms
+                    if response.latency_ms is not None
+                    else (monotonic() - started) * 1000
+                )
+                if (
+                    response.provider.strip().lower() != spec.provider
+                    or response.model.strip() != spec.model
+                ):
+                    raise ProviderProtocolError(
+                        "response_model_identity_mismatch"
+                    )
+                if not isinstance(response.payload, Mapping):
+                    raise ProviderProtocolError(
+                        "response_payload_must_be_object"
+                    )
+
+                value = validator(response.payload)
+                output_hash = _hash(response.payload)
+                attempts.append(
+                    ModelAttempt(
+                        spec.provider,
+                        spec.model,
+                        "success",
+                        latency_ms=latency_ms,
+                        request_id=request_id,
+                    )
+                )
+                evidence = AgentEvidence(
+                    trace_id=trace_id,
+                    role=role,
+                    input_hash=input_hash,
+                    output_hash=output_hash,
+                    attempts=tuple(attempts),
+                    selected_provider=spec.provider,
+                    selected_model=spec.model,
+                )
+                return InvocationResult(value, evidence)
+
+            except (StructuredOutputError, ProviderError) as exc:
+                latency_ms = (monotonic() - started) * 1000
+                error_code = (
+                    "structured_output_invalid"
+                    if isinstance(exc, StructuredOutputError)
+                    else exc.code
+                )
+                feedback_code = error_code
+                attempts.append(
+                    ModelAttempt(
+                        spec.provider,
+                        spec.model,
+                        "failed",
+                        error_code,
+                        latency_ms,
+                        request_id,
+                    )
+                )
+            except Exception:
+                latency_ms = (monotonic() - started) * 1000
+                feedback_code = "unexpected_provider_error"
+                attempts.append(
+                    ModelAttempt(
+                        spec.provider,
+                        spec.model,
+                        "failed",
+                        feedback_code,
+                        latency_ms,
+                        request_id,
+                    )
+                )
+
+        evidence = AgentEvidence(
+            trace_id=trace_id,
+            role=role,
+            input_hash=input_hash,
+            output_hash=None,
+            attempts=tuple(attempts),
+        )
+        raise AgentRuntimeError(
+            f"agent_attempts_exhausted:{role.value}:{feedback_code}", evidence
+        )

devagent_physical_engine/agent/semantic.py

@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+
+from ..models import Capability, Goal, Resource, TaskGraph, WorldState
+from ..planning import SUPPORTED_GOAL_ACTIONS
+from ..verification import VerificationIssue, VerificationResult
+
+
+PHYSICAL_ACTIONS = frozenset({Capability.PICK, Capability.MOVE, Capability.PLACE})
+LOAD_ACTIONS = frozenset({Capability.PICK, Capability.MOVE, Capability.PLACE, Capability.WAIT})
+REQUIRED_PHYSICAL_CONSTRAINTS = frozenset({"collision_free", "joint_limits"})
+
+ALLOWED_EFFECTS: dict[Capability, frozenset[str]] = {
+    Capability.PICK: frozenset({"object_gripped"}),
+    Capability.MOVE: frozenset({"at_destination"}),
+    Capability.PLACE: frozenset({"object_placed", "goal_complete"}),
+    Capability.WAIT: frozenset(),
+}
+
+REQUIRED_EFFECTS: dict[Capability, frozenset[str]] = {
+    Capability.PICK: frozenset({"object_gripped"}),
+    Capability.MOVE: frozenset({"at_destination"}),
+    Capability.PLACE: frozenset({"object_placed", "goal_complete"}),
+    Capability.WAIT: frozenset(),
+}
+
+REQUIRED_PRECONDITIONS: dict[Capability, frozenset[str]] = {
+    Capability.PICK: frozenset({"robot_ready", "object_available"}),
+    Capability.MOVE: frozenset({"robot_ready", "object_gripped"}),
+    Capability.PLACE: frozenset({"robot_ready", "object_gripped", "at_destination"}),
+    Capability.WAIT: frozenset(),
+}
+
+
+class AgentPlanSemanticPolicy:
+    """Fail-closed semantic envelope for AI-generated V0.2 plans.
+
+    The structural verifier proves that resources and capabilities exist. This
+    policy additionally proves that a model cannot invent arbitrary effects,
+    omit baseline motion constraints, or satisfy its own ungrounded
+    preconditions. V0.2 intentionally supports one canonical ``load`` workflow;
+    broader task domains must add an explicit policy instead of weakening this
+    one.
+    """
+
+    def verify(
+        self,
+        goal: Goal,
+        graph: TaskGraph,
+        resources: list[Resource],
+        world: WorldState,
+    ) -> VerificationResult:
+        issues: list[VerificationIssue] = []
+        goal_action = goal.action.strip().lower()
+
+        if goal_action not in SUPPORTED_GOAL_ACTIONS:
+            issues.append(
+                VerificationIssue(
+                    "unsupported_goal_action",
+                    detail=goal_action,
+                )
+            )
+            return VerificationResult(False, issues)
+
+        if graph.goal_id != goal.goal_id:
+            issues.append(
+                VerificationIssue(
+                    "goal_id_mismatch",
+                    detail=f"expected={goal.goal_id};actual={graph.goal_id}",
+                )
+            )
+
+        try:
+            ordered = graph.topological_order()
+        except ValueError as exc:
+            issues.append(
+                VerificationIssue("invalid_task_graph", detail=str(exc))
+            )
+            return VerificationResult(False, issues)
+
+        resource_map = {resource.resource_id: resource for resource in resources}
+        action_counts = Counter(task.contract.action for task in ordered)
+
+        for action in (Capability.PICK, Capability.MOVE, Capability.PLACE):
+            if action_counts[action] != 1:
+                issues.append(
+                    VerificationIssue(
+                        "invalid_action_count",
+                        detail=f"{action.value}:{action_counts[action]}",
+                    )
+                )
+
+        children: dict[str, set[str]] = defaultdict(set)
+        parents: dict[str, set[str]] = defaultdict(set)
+        for task in ordered:
+            for dependency in task.depends_on:
+                children[dependency].add(task.task_id)
+                parents[task.task_id].add(dependency)
+
+        def ancestors(task_id: str) -> set[str]:
+            discovered: set[str] = set()
+            pending = list(parents.get(task_id, set()))
+            while pending:
+                current = pending.pop()
+                if current in discovered:
+                    continue
+                discovered.add(current)
+                pending.extend(parents.get(current, set()))
+            return discovered
+
+        grounded_facts = set(world.facts)
+        completion_tasks: list[str] = []
+        physical_resource_ids: set[str] = set()
+        action_task_ids: dict[Capability, list[str]] = defaultdict(list)
+
+        for task in ordered:
+            contract = task.contract
+            action = contract.action
+            action_task_ids[action].append(task.task_id)
+
+            if action not in LOAD_ACTIONS:
+                issues.append(
+                    VerificationIssue(
+                        "action_not_allowed_for_goal",
+                        task.task_id,
+                        action.value,
+                    )
+                )
+                continue
+
+            if contract.resource_id not in resource_map:
+                issues.append(
+                    VerificationIssue(
+                        "unknown_resource",
+                        task.task_id,
+                        contract.resource_id,
+                    )
+                )
+
+            if action in PHYSICAL_ACTIONS:
+                physical_resource_ids.add(contract.resource_id)
+                constraints = set(contract.constraints)
+                missing_constraints = REQUIRED_PHYSICAL_CONSTRAINTS - constraints
+                for constraint in sorted(missing_constraints):
+                    issues.append(
+                        VerificationIssue(
+                            "required_constraint_missing",
+                            task.task_id,
+                            constraint,
+                        )
+                    )
+
+            required_preconditions = REQUIRED_PRECONDITIONS.get(action, frozenset())
+            preconditions = set(contract.preconditions)
+            for precondition in sorted(required_preconditions - preconditions):
+                issues.append(
+                    VerificationIssue(
+                        "required_precondition_missing",
+                        task.task_id,
+                        precondition,
+                    )
+                )
+
+            for precondition in contract.preconditions:
+                if precondition not in grounded_facts:
+                    issues.append(
+                        VerificationIssue(
+                            "ungrounded_precondition",
+                            task.task_id,
+                            precondition,
+                        )
+                    )
+
+            effects = set(contract.expected_effects)
+            allowed_effects = ALLOWED_EFFECTS.get(action, frozenset())
+            required_effects = REQUIRED_EFFECTS.get(action, frozenset())
+
+            for effect in sorted(effects - allowed_effects):
+                issues.append(
+                    VerificationIssue(
+                        "effect_not_allowed",
+                        task.task_id,
+                        effect,
+                    )
+                )
+            for effect in sorted(required_effects - effects):
+                issues.append(
+                    VerificationIssue(
+                        "required_effect_missing",
+                        task.task_id,
+                        effect,
+                    )
+                )
+
+            if "goal_complete" in effects:
+                completion_tasks.append(task.task_id)
+                if action is not Capability.PLACE:
+                    issues.append(
+                        VerificationIssue(
+                            "goal_complete_wrong_action",
+                            task.task_id,
+                            action.value,
+                        )
+                    )
+
+            if action is Capability.PICK:
+                if contract.object_id != goal.object_id:
+                    issues.append(
+                        VerificationIssue(
+                            "goal_object_mismatch",
+                            task.task_id,
+                            str(contract.object_id),
+                        )
+                    )
+                if contract.source != goal.source:
+                    issues.append(
+                        VerificationIssue(
+                            "goal_source_mismatch",
+                            task.task_id,
+                            str(contract.source),
+                        )
+                    )
+            elif action is Capability.MOVE:
+                if contract.object_id != goal.object_id:
+                    issues.append(
+                        VerificationIssue(
+                            "goal_object_mismatch",
+                            task.task_id,
+                            str(contract.object_id),
+                        )
+                    )
+                if contract.destination != goal.destination:
+                    issues.append(
+                        VerificationIssue(
+                            "goal_destination_mismatch",
+                            task.task_id,
+                            str(contract.destination),
+                        )
+                    )
+            elif action is Capability.PLACE:
+                if contract.object_id != goal.object_id:
+                    issues.append(
+                        VerificationIssue(
+                            "goal_object_mismatch",
+                            task.task_id,
+                            str(contract.object_id),
+                        )
+                    )
+                if contract.destination != goal.destination:
+                    issues.append(
+                        VerificationIssue(
+                            "goal_destination_mismatch",
+                            task.task_id,
+                            str(contract.destination),
+                        )
+                    )
+
+            grounded_facts.update(effects & allowed_effects)
+
+        if len(physical_resource_ids) != 1:
+            issues.append(
+                VerificationIssue(
+                    "load_requires_single_physical_resource",
+                    detail=",".join(sorted(physical_resource_ids)),
+                )
+            )
+
+        if len(completion_tasks) != 1:
+            issues.append(
+                VerificationIssue(
+                    "invalid_goal_completion_count",
+                    detail=str(len(completion_tasks)),
+                )
+            )
+        elif children.get(completion_tasks[0]):
+            issues.append(
+                VerificationIssue(
+                    "goal_completion_not_terminal",
+                    completion_tasks[0],
+                )
+            )
+
+        pick_ids = action_task_ids.get(Capability.PICK, [])
+        move_ids = action_task_ids.get(Capability.MOVE, [])
+        place_ids = action_task_ids.get(Capability.PLACE, [])
+        if len(pick_ids) == len(move_ids) == len(place_ids) == 1:
+            pick_id, move_id, place_id = pick_ids[0], move_ids[0], place_ids[0]
+            if pick_id not in ancestors(move_id):
+                issues.append(
+                    VerificationIssue(
+                        "move_not_dependent_on_pick",
+                        move_id,
+                    )
+                )
+            if move_id not in ancestors(place_id):
+                issues.append(
+                    VerificationIssue(
+                        "place_not_dependent_on_move",
+                        place_id,
+                    )
+                )
+
+        return VerificationResult(not issues, issues)