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

devagent_physical_engine/execution.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+from .models import Resource, TaskGraph, WorldState
+from .simulation import SimulationBackend
+from .verification import DeterministicVerifier, VerificationIssue
+
+
+class ExecutionMode(str, Enum):
+    SIMULATION = "simulation"
+    SHADOW = "shadow"
+    REAL = "real"
+
+
+@dataclass(slots=True)
+class ExecutionReport:
+    completed: bool
+    executed_tasks: list[str] = field(default_factory=list)
+    blocked_task: str | None = None
+    issues: list[VerificationIssue] = field(default_factory=list)
+
+
+class ExecutionSupervisor:
+    """Fail-closed executor.
+
+    Simulation advances the supplied simulated world. Shadow mode advances an isolated copy so
+    hypothetical expected effects never mutate live observed state. V0.1 locks real execution until
+    hardware qualification and an explicit promotion gate exist.
+    """
+
+    def __init__(self, verifier: DeterministicVerifier | None = None) -> None:
+        self.verifier = verifier or DeterministicVerifier()
+
+    def execute(
+        self,
+        graph: TaskGraph,
+        resources: list[Resource],
+        world: WorldState,
+        backend: SimulationBackend,
+        mode: ExecutionMode = ExecutionMode.SIMULATION,
+    ) -> ExecutionReport:
+        graph_result = self.verifier.verify_graph(graph, resources)
+        if not graph_result.passed:
+            return ExecutionReport(False, issues=graph_result.issues)
+
+        if mode is ExecutionMode.REAL:
+            return ExecutionReport(
+                False,
+                issues=[
+                    VerificationIssue(
+                        "real_execution_locked",
+                        detail="requires qualified hardware adapter and promotion gate",
+                    )
+                ],
+            )
+
+        evaluation_world = (
+            world
+            if mode is ExecutionMode.SIMULATION
+            else WorldState(facts=set(world.facts), values=dict(world.values))
+        )
+
+        report = ExecutionReport(False)
+        for task in graph.topological_order():
+            preconditions = self.verifier.verify_runtime_preconditions(task, evaluation_world)
+            if not preconditions.passed:
+                report.blocked_task = task.task_id
+                report.issues.extend(preconditions.issues)
+                return report
+
+            step = backend.run_task(task, evaluation_world)
+            constraints = self.verifier.verify_simulation_constraints(
+                task, set(step.satisfied_constraints)
+            )
+            if not step.success or not constraints.passed:
+                report.blocked_task = task.task_id
+                report.issues.extend(constraints.issues)
+                if not step.success and not constraints.issues:
+                    report.issues.append(
+                        VerificationIssue("simulation_failed", task.task_id, step.detail)
+                    )
+                return report
+
+            evaluation_world.apply_effects(task.contract.expected_effects)
+            report.executed_tasks.append(task.task_id)
+
+        report.completed = True
+        return report

devagent_physical_engine/models.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Iterable
+
+
+class Capability(str, Enum):
+    MOVE = "move"
+    PICK = "pick"
+    PLACE = "place"
+    WAIT = "wait"
+    INSPECT = "inspect"
+    NAVIGATE = "navigate"
+    TRANSPORT = "transport"
+    DOCK = "dock"
+    TRANSFER = "transfer"
+
+
+@dataclass(frozen=True, slots=True)
+class Goal:
+    goal_id: str
+    action: str
+    object_id: str
+    source: str
+    destination: str
+
+    def __post_init__(self) -> None:
+        for name, value in (("goal_id", self.goal_id), ("action", self.action), ("object_id", self.object_id), ("source", self.source), ("destination", self.destination)):
+            if not value.strip():
+                raise ValueError(f"empty_{name}")
+
+
+@dataclass(frozen=True, slots=True)
+class Resource:
+    resource_id: str
+    resource_type: str
+    capabilities: frozenset[Capability]
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.resource_id.strip():
+            raise ValueError("empty_resource_id")
+        if not self.resource_type.strip():
+            raise ValueError("empty_resource_type")
+
+    def supports(self, capability: Capability) -> bool:
+        return capability in self.capabilities
+
+
+@dataclass(frozen=True, slots=True)
+class ActionContract:
+    action: Capability
+    resource_id: str
+    object_id: str | None = None
+    source: str | None = None
+    destination: str | None = None
+    preconditions: tuple[str, ...] = ()
+    expected_effects: tuple[str, ...] = ()
+    constraints: tuple[str, ...] = ()
+    timeout_ms: int = 10_000
+
+    def __post_init__(self) -> None:
+        if not self.resource_id.strip():
+            raise ValueError("empty_resource_id")
+        if self.timeout_ms <= 0:
+            raise ValueError("invalid_timeout")
+        for name, values in (("precondition", self.preconditions), ("effect", self.expected_effects), ("constraint", self.constraints)):
+            if any(not value.strip() for value in values):
+                raise ValueError(f"empty_{name}")
+
+
+@dataclass(frozen=True, slots=True)
+class TaskNode:
+    task_id: str
+    contract: ActionContract
+    depends_on: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.task_id.strip():
+            raise ValueError("empty_task_id")
+
+
+@dataclass(frozen=True, slots=True)
+class TaskGraph:
+    goal_id: str
+    tasks: tuple[TaskNode, ...]
+
+    def __post_init__(self) -> None:
+        if not self.goal_id.strip():
+            raise ValueError("empty_goal_id")
+        if not self.tasks:
+            raise ValueError("empty_task_graph")
+
+    def validate_structure(self) -> tuple[str, ...]:
+        errors: list[str] = []
+        ids = [task.task_id for task in self.tasks]
+        if len(ids) != len(set(ids)):
+            errors.append("duplicate_task_id")
+        known = set(ids)
+        for task in self.tasks:
+            for dependency in task.depends_on:
+                if dependency not in known:
+                    errors.append(f"unknown_dependency:{task.task_id}:{dependency}")
+                if dependency == task.task_id:
+                    errors.append(f"self_dependency:{task.task_id}")
+        return tuple(errors)
+
+    def topological_order(self) -> tuple[TaskNode, ...]:
+        errors = self.validate_structure()
+        if errors:
+            raise ValueError(";".join(errors))
+        tasks_by_id = {task.task_id: task for task in self.tasks}
+        indegree = {task.task_id: 0 for task in self.tasks}
+        children: dict[str, list[str]] = {task.task_id: [] for task in self.tasks}
+        for task in self.tasks:
+            for dependency in task.depends_on:
+                indegree[task.task_id] += 1
+                children[dependency].append(task.task_id)
+        ready = [task.task_id for task in self.tasks if indegree[task.task_id] == 0]
+        ordered: list[TaskNode] = []
+        while ready:
+            current = ready.pop(0)
+            ordered.append(tasks_by_id[current])
+            for child in children[current]:
+                indegree[child] -= 1
+                if indegree[child] == 0:
+                    ready.append(child)
+        if len(ordered) != len(self.tasks):
+            raise ValueError("cyclic_task_graph")
+        return tuple(ordered)
+
+
+@dataclass(slots=True)
+class WorldState:
+    facts: set[str] = field(default_factory=set)
+    values: dict[str, Any] = field(default_factory=dict)
+
+    def has_all(self, required: Iterable[str]) -> bool:
+        return all(item in self.facts for item in required)
+
+    def apply_effects(self, effects: Iterable[str]) -> None:
+        self.facts.update(effects)

devagent_physical_engine/operating_envelope.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from math import isfinite
+from typing import Sequence
+
+from .physical_campaign import PhysicalCaseResult
+
+
+class OperatingEnvelopeError(ValueError):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class ObservedEnvelope:
+    """Observed one-dimensional boundary; never an interpolated safety guarantee."""
+
+    sweep_group: str
+    parameter: str
+    total_observations: int
+    successful_observations: int
+    observed_success_min: float | None
+    observed_success_max: float | None
+    nearest_failure_below: float | None
+    nearest_failure_above: float | None
+    all_oracle_backed: bool
+    unsafe_false_passes: int
+
+    @property
+    def usable_for_qualification(self) -> bool:
+        return (
+            self.total_observations > 0
+            and self.successful_observations > 0
+            and self.all_oracle_backed
+            and self.unsafe_false_passes == 0
+        )
+
+    def to_dict(self) -> dict:
+        return {**asdict(self), "usable_for_qualification": self.usable_for_qualification}
+
+
+class OperatingEnvelopeAnalyzer:
+    """Compute only boundaries directly observed in explicit single-axis sweeps."""
+
+    def analyze(
+        self,
+        results: Sequence[PhysicalCaseResult],
+        *,
+        sweep_group: str,
+        parameter: str,
+    ) -> ObservedEnvelope:
+        if not sweep_group.strip() or not parameter.strip():
+            raise OperatingEnvelopeError("sweep_identity_required")
+        selected = [
+            item
+            for item in results
+            if item.case.sweep_group == sweep_group
+            and item.case.sweep_parameter == parameter
+        ]
+        if not selected:
+            raise OperatingEnvelopeError("sweep_observations_not_found")
+
+        observations: list[tuple[float, PhysicalCaseResult]] = []
+        for item in selected:
+            raw = item.case.parameters.get(parameter)
+            if isinstance(raw, bool) or not isinstance(raw, (int, float)):
+                raise OperatingEnvelopeError("sweep_parameter_must_be_numeric")
+            value = float(raw)
+            if not isfinite(value):
+                raise OperatingEnvelopeError("sweep_parameter_non_finite")
+            observations.append((value, item))
+        observations.sort(key=lambda pair: pair[0])
+
+        successes = [value for value, item in observations if item.actual_success]
+        success_min = min(successes) if successes else None
+        success_max = max(successes) if successes else None
+        below = None
+        above = None
+        if success_min is not None:
+            failures_below = [
+                value
+                for value, item in observations
+                if not item.actual_success and value < success_min
+            ]
+            below = max(failures_below) if failures_below else None
+        if success_max is not None:
+            failures_above = [
+                value
+                for value, item in observations
+                if not item.actual_success and value > success_max
+            ]
+            above = min(failures_above) if failures_above else None
+
+        return ObservedEnvelope(
+            sweep_group=sweep_group,
+            parameter=parameter,
+            total_observations=len(observations),
+            successful_observations=len(successes),
+            observed_success_min=success_min,
+            observed_success_max=success_max,
+            nearest_failure_below=below,
+            nearest_failure_above=above,
+            all_oracle_backed=all(item.case.oracle_backed for _, item in observations),
+            unsafe_false_passes=sum(item.unsafe_false_pass for _, item in observations),
+        )
+
+    def discover(self, results: Sequence[PhysicalCaseResult]) -> tuple[ObservedEnvelope, ...]:
+        groups = sorted(
+            {
+                (item.case.sweep_group, item.case.sweep_parameter)
+                for item in results
+                if item.case.sweep_group is not None
+                and item.case.sweep_parameter is not None
+            }
+        )
+        return tuple(
+            self.analyze(results, sweep_group=group, parameter=parameter)
+            for group, parameter in groups
+            if group is not None and parameter is not None
+        )

devagent_physical_engine/optimization/__init__.py

@@ -0,0 +1,50 @@
+from .benchmark import OptimizationBenchmarkCase, OptimizationBenchmarkCaseResult, OptimizationBenchmarkRunner, OptimizationBenchmarkSummary
+from .candidates import AgentCandidateGenerator, CandidateGenerationError, CandidateSource, StaticCandidateSource
+from .contracts import (
+    CandidateEvaluation,
+    CandidateMetrics,
+    ObjectiveWeights,
+    OptimizationConfig,
+    OptimizationProfileName,
+    OptimizationResult,
+    OptimizationThresholds,
+    PlanCandidate,
+)
+from .evaluator import CandidateMetricEvaluator, DeterministicMetricEvaluator
+from .evidence import optimization_evidence, optimization_evidence_hash
+from .experience import ExperienceStore
+from .measured import MeasuredCandidateMetricEvaluator, RawSimulationMetrics, SimulationMetricsBackend
+from .optimizer import MultiObjectiveOptimizer, OptimizationError, pareto_front
+from .orchestrator import AdaptiveOptimizationEngine, AdaptiveOptimizationError
+
+__all__ = [
+    "AdaptiveOptimizationEngine",
+    "AdaptiveOptimizationError",
+    "AgentCandidateGenerator",
+    "CandidateGenerationError",
+    "CandidateEvaluation",
+    "CandidateMetricEvaluator",
+    "CandidateMetrics",
+    "CandidateSource",
+    "DeterministicMetricEvaluator",
+    "ExperienceStore",
+    "MeasuredCandidateMetricEvaluator",
+    "MultiObjectiveOptimizer",
+    "ObjectiveWeights",
+    "OptimizationBenchmarkCase",
+    "OptimizationBenchmarkCaseResult",
+    "OptimizationBenchmarkRunner",
+    "OptimizationBenchmarkSummary",
+    "OptimizationConfig",
+    "OptimizationError",
+    "OptimizationProfileName",
+    "OptimizationResult",
+    "OptimizationThresholds",
+    "PlanCandidate",
+    "RawSimulationMetrics",
+    "SimulationMetricsBackend",
+    "StaticCandidateSource",
+    "optimization_evidence",
+    "optimization_evidence_hash",
+    "pareto_front",
+]

devagent_physical_engine/optimization/benchmark.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from statistics import fmean
+from typing import Iterable
+
+from .orchestrator import AdaptiveOptimizationEngine
+from ..models import Goal, Resource, WorldState
+
+
+@dataclass(frozen=True, slots=True)
+class OptimizationBenchmarkCase:
+    case_id: str
+    engine: AdaptiveOptimizationEngine
+    goal: Goal
+    resources: tuple[Resource, ...]
+    world: WorldState
+
+    def __post_init__(self) -> None:
+        if not self.case_id.strip():
+            raise ValueError("benchmark_case_id_required")
+
+
+@dataclass(frozen=True, slots=True)
+class OptimizationBenchmarkCaseResult:
+    case_id: str
+    passed: bool
+    selected_candidate_id: str | None
+    comparatively_optimized: bool
+    quality_warning_count: int
+    cycle_time_s: float | None
+    min_clearance_m: float | None
+    failure_code: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class OptimizationBenchmarkSummary:
+    cases: tuple[OptimizationBenchmarkCaseResult, ...]
+
+    @property
+    def total(self) -> int:
+        return len(self.cases)
+
+    @property
+    def passed(self) -> int:
+        return sum(1 for case in self.cases if case.passed)
+
+    @property
+    def success_rate(self) -> float:
+        return self.passed / self.total if self.total else 0.0
+
+    @property
+    def comparative_rate(self) -> float:
+        passed = [case for case in self.cases if case.passed]
+        return (
+            sum(1 for case in passed if case.comparatively_optimized) / len(passed)
+            if passed
+            else 0.0
+        )
+
+    @property
+    def warning_rate(self) -> float:
+        passed = [case for case in self.cases if case.passed]
+        return (
+            sum(1 for case in passed if case.quality_warning_count > 0) / len(passed)
+            if passed
+            else 0.0
+        )
+
+    @property
+    def average_cycle_time_s(self) -> float | None:
+        values = [case.cycle_time_s for case in self.cases if case.cycle_time_s is not None]
+        return fmean(values) if values else None
+
+    @property
+    def average_min_clearance_m(self) -> float | None:
+        values = [case.min_clearance_m for case in self.cases if case.min_clearance_m is not None]
+        return fmean(values) if values else None
+
+
+class OptimizationBenchmarkRunner:
+    """Run deterministic optimization scenarios and aggregate behavioral metrics."""
+
+    def run(
+        self, cases: Iterable[OptimizationBenchmarkCase]
+    ) -> OptimizationBenchmarkSummary:
+        results: list[OptimizationBenchmarkCaseResult] = []
+        for case in cases:
+            try:
+                result = case.engine.optimize(
+                    goal=case.goal,
+                    resources=list(case.resources),
+                    world=case.world,
+                )
+            except Exception as exc:
+                results.append(
+                    OptimizationBenchmarkCaseResult(
+                        case_id=case.case_id,
+                        passed=False,
+                        selected_candidate_id=None,
+                        comparatively_optimized=False,
+                        quality_warning_count=0,
+                        cycle_time_s=None,
+                        min_clearance_m=None,
+                        failure_code=f"optimization_failed:{type(exc).__name__}",
+                    )
+                )
+                continue
+
+            results.append(
+                OptimizationBenchmarkCaseResult(
+                    case_id=case.case_id,
+                    passed=True,
+                    selected_candidate_id=result.selected.candidate.candidate_id,
+                    comparatively_optimized=result.comparatively_optimized,
+                    quality_warning_count=len(result.quality_warnings),
+                    cycle_time_s=result.selected.metrics.cycle_time_s,
+                    min_clearance_m=result.selected.metrics.min_clearance_m,
+                    failure_code=None,
+                )
+            )
+        return OptimizationBenchmarkSummary(tuple(results))