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

devagent_physical_engine/optimization/measured.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from .contracts import CandidateMetrics, PlanCandidate
+from .evaluator import candidate_verification_violations
+from ..models import Goal, Resource, WorldState
+
+
+@dataclass(frozen=True, slots=True)
+class RawSimulationMetrics:
+    """Metric payload produced by a real simulation/motion backend.
+
+    Optional values are intentional: missing measurements become explicit
+    uncertainty and therefore fail the optimizer's eligibility gate instead of
+    being guessed by an LLM.
+    """
+
+    measurement_context: str
+    cycle_time_s: float | None = None
+    path_length_m: float | None = None
+    min_clearance_m: float | None = None
+    energy_proxy: float | None = None
+    recovery_risk: float | None = None
+    resource_contention: float | None = None
+    confidence: float | None = None
+    simulation_success: bool = True
+    hard_violations: tuple[str, ...] = ()
+    metrics_origin: str = "measured_simulation"
+
+    def __post_init__(self) -> None:
+        if not self.measurement_context.strip():
+            raise ValueError("measurement_context_required")
+        if not self.metrics_origin.strip():
+            raise ValueError("metrics_origin_required")
+
+
+class SimulationMetricsBackend(Protocol):
+    def measure(
+        self,
+        candidate: PlanCandidate,
+        *,
+        goal: Goal,
+        resources: list[Resource],
+        world: WorldState,
+    ) -> RawSimulationMetrics: ...
+
+
+class MeasuredCandidateMetricEvaluator:
+    """Verify first, then convert measured backend output without guessing.
+
+    Any missing required metric is listed in `unknown_fields`, which makes the
+    candidate ineligible until the backend can actually measure it.
+    """
+
+    def __init__(self, backend: SimulationMetricsBackend) -> None:
+        self.backend = backend
+
+    def evaluate(
+        self,
+        candidate: PlanCandidate,
+        *,
+        goal: Goal,
+        resources: list[Resource],
+        world: WorldState,
+    ) -> CandidateMetrics:
+        verification = candidate_verification_violations(
+            candidate,
+            goal=goal,
+            resources=resources,
+            world=world,
+        )
+        if verification:
+            return CandidateMetrics(
+                cycle_time_s=0.0,
+                path_length_m=0.0,
+                min_clearance_m=0.0,
+                energy_proxy=0.0,
+                recovery_risk=1.0,
+                resource_contention=1.0,
+                confidence=0.0,
+                measurement_context="verification-failed",
+                metrics_origin="deterministic_verification",
+                simulation_success=False,
+                hard_violations=("plan_verification_failed",) + verification,
+                unknown_fields=(
+                    "cycle_time_s",
+                    "path_length_m",
+                    "min_clearance_m",
+                    "energy_proxy",
+                    "recovery_risk",
+                    "resource_contention",
+                    "confidence",
+                ),
+            )
+
+        raw = self.backend.measure(
+            candidate,
+            goal=goal,
+            resources=resources,
+            world=world,
+        )
+        unknown: list[str] = []
+
+        def value(name: str, item: float | None, conservative: float) -> float:
+            if item is None:
+                unknown.append(name)
+                return conservative
+            return float(item)
+
+        return CandidateMetrics(
+            cycle_time_s=value("cycle_time_s", raw.cycle_time_s, 0.0),
+            path_length_m=value("path_length_m", raw.path_length_m, 0.0),
+            min_clearance_m=value("min_clearance_m", raw.min_clearance_m, 0.0),
+            energy_proxy=value("energy_proxy", raw.energy_proxy, 0.0),
+            recovery_risk=value("recovery_risk", raw.recovery_risk, 1.0),
+            resource_contention=value("resource_contention", raw.resource_contention, 1.0),
+            confidence=value("confidence", raw.confidence, 0.0),
+            measurement_context=raw.measurement_context,
+            metrics_origin=raw.metrics_origin,
+            simulation_success=raw.simulation_success,
+            hard_violations=raw.hard_violations,
+            unknown_fields=tuple(unknown),
+        )

devagent_physical_engine/optimization/optimizer.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+from dataclasses import replace
+from math import isclose
+from typing import Iterable, Mapping
+
+from .contracts import (
+    CandidateEvaluation,
+    CandidateMetrics,
+    ObjectiveWeights,
+    OptimizationConfig,
+    OptimizationResult,
+    PlanCandidate,
+)
+
+
+class OptimizationError(RuntimeError):
+    pass
+
+
+def _eligibility_reasons(metrics: CandidateMetrics, config: OptimizationConfig) -> tuple[str, ...]:
+    thresholds = config.thresholds
+    reasons: list[str] = []
+    if not metrics.simulation_success:
+        reasons.append("simulation_failed")
+    reasons.extend(f"hard_violation:{item}" for item in metrics.hard_violations)
+    reasons.extend(f"unknown:{item}" for item in metrics.unknown_fields)
+    if metrics.min_clearance_m < thresholds.min_clearance_m:
+        reasons.append("clearance_below_minimum")
+    if metrics.recovery_risk > thresholds.max_recovery_risk:
+        reasons.append("recovery_risk_above_maximum")
+    if metrics.resource_contention > thresholds.max_resource_contention:
+        reasons.append("resource_contention_above_maximum")
+    if metrics.confidence < thresholds.min_confidence:
+        reasons.append("confidence_below_minimum")
+    return tuple(dict.fromkeys(reasons))
+
+
+def _objective_vector(metrics: CandidateMetrics) -> tuple[float, ...]:
+    """All objectives transformed so lower is better for Pareto comparison."""
+    return (
+        metrics.cycle_time_s,
+        metrics.path_length_m,
+        -metrics.min_clearance_m,
+        metrics.energy_proxy,
+        metrics.recovery_risk,
+        metrics.resource_contention,
+    )
+
+
+def _dominates(left: CandidateMetrics, right: CandidateMetrics) -> bool:
+    lv = _objective_vector(left)
+    rv = _objective_vector(right)
+    no_worse = all(a <= b or isclose(a, b, rel_tol=1e-12, abs_tol=1e-12) for a, b in zip(lv, rv))
+    strictly_better = any(a < b and not isclose(a, b, rel_tol=1e-12, abs_tol=1e-12) for a, b in zip(lv, rv))
+    return no_worse and strictly_better
+
+
+def pareto_front(evaluations: Iterable[CandidateEvaluation]) -> tuple[CandidateEvaluation, ...]:
+    eligible = tuple(item for item in evaluations if item.eligible)
+    front: list[CandidateEvaluation] = []
+    for candidate in eligible:
+        if any(
+            other.candidate.candidate_id != candidate.candidate.candidate_id
+            and _dominates(other.metrics, candidate.metrics)
+            for other in eligible
+        ):
+            continue
+        front.append(candidate)
+    return tuple(front)
+
+
+def _utility(values: Mapping[str, float], key: str, value: float, *, higher_is_better: bool) -> float:
+    minimum = values[f"{key}:min"]
+    maximum = values[f"{key}:max"]
+    if isclose(minimum, maximum, rel_tol=1e-12, abs_tol=1e-12):
+        return 1.0
+    normalized = (value - minimum) / (maximum - minimum)
+    return normalized if higher_is_better else 1.0 - normalized
+
+
+def _ranges(evaluations: Iterable[CandidateEvaluation]) -> dict[str, float]:
+    eligible = tuple(evaluations)
+    metrics = {
+        "cycle_time": [item.metrics.cycle_time_s for item in eligible],
+        "path_length": [item.metrics.path_length_m for item in eligible],
+        "clearance": [item.metrics.min_clearance_m for item in eligible],
+        "energy": [item.metrics.energy_proxy for item in eligible],
+        "recovery_risk": [item.metrics.recovery_risk for item in eligible],
+        "resource_contention": [item.metrics.resource_contention for item in eligible],
+    }
+    output: dict[str, float] = {}
+    for key, values in metrics.items():
+        output[f"{key}:min"] = min(values)
+        output[f"{key}:max"] = max(values)
+    return output
+
+
+def _score(
+    evaluation: CandidateEvaluation,
+    ranges: Mapping[str, float],
+    weights: ObjectiveWeights,
+) -> float:
+    metrics = evaluation.metrics
+    score = (
+        weights.cycle_time * _utility(ranges, "cycle_time", metrics.cycle_time_s, higher_is_better=False)
+        + weights.path_length * _utility(ranges, "path_length", metrics.path_length_m, higher_is_better=False)
+        + weights.clearance * _utility(ranges, "clearance", metrics.min_clearance_m, higher_is_better=True)
+        + weights.energy * _utility(ranges, "energy", metrics.energy_proxy, higher_is_better=False)
+        + weights.recovery_risk * _utility(ranges, "recovery_risk", metrics.recovery_risk, higher_is_better=False)
+        + weights.resource_contention
+        * _utility(ranges, "resource_contention", metrics.resource_contention, higher_is_better=False)
+        + weights.experience * max(0.0, min(1.0, 0.5 + evaluation.experience_bonus / 0.10))
+    )
+    return max(0.0, min(1.0, score))
+
+
+class MultiObjectiveOptimizer:
+    """Hard-gate candidates, build a Pareto frontier, then rank the frontier.
+
+    Weighted scoring never rescues an unsafe/ineligible candidate. It is applied
+    only after hard constraints and uncertainty gates pass.
+    """
+
+    def evaluate(
+        self,
+        candidates: Iterable[PlanCandidate],
+        metrics_by_id: Mapping[str, CandidateMetrics],
+        config: OptimizationConfig,
+        *,
+        experience_bonus_by_id: Mapping[str, float] | None = None,
+    ) -> tuple[CandidateEvaluation, ...]:
+        bonuses = experience_bonus_by_id or {}
+        evaluations: list[CandidateEvaluation] = []
+        seen: set[str] = set()
+        for candidate in candidates:
+            if candidate.candidate_id in seen:
+                raise OptimizationError(f"duplicate_candidate_id:{candidate.candidate_id}")
+            seen.add(candidate.candidate_id)
+            try:
+                metrics = metrics_by_id[candidate.candidate_id]
+            except KeyError as exc:
+                raise OptimizationError(f"missing_metrics:{candidate.candidate_id}") from exc
+            reasons = _eligibility_reasons(metrics, config)
+            bonus = float(bonuses.get(candidate.candidate_id, 0.0))
+            bonus = max(-config.max_experience_bonus, min(config.max_experience_bonus, bonus))
+            evaluations.append(
+                CandidateEvaluation(
+                    candidate=candidate,
+                    metrics=metrics,
+                    eligible=not reasons,
+                    disqualifiers=reasons,
+                    experience_bonus=bonus,
+                )
+            )
+        return tuple(evaluations)
+
+    def select(
+        self,
+        candidates: Iterable[PlanCandidate],
+        metrics_by_id: Mapping[str, CandidateMetrics],
+        config: OptimizationConfig,
+        *,
+        experience_bonus_by_id: Mapping[str, float] | None = None,
+        escalation_level: int = 0,
+        mode: str = "optimized_multi_candidate",
+        quality_warnings: tuple[str, ...] = (),
+    ) -> OptimizationResult:
+        evaluations = self.evaluate(
+            candidates,
+            metrics_by_id,
+            config,
+            experience_bonus_by_id=experience_bonus_by_id,
+        )
+        eligible = tuple(item for item in evaluations if item.eligible)
+        if not eligible:
+            raise OptimizationError("no_eligible_candidate")
+        contexts = {item.metrics.measurement_context for item in eligible}
+        if len(contexts) != 1:
+            raise OptimizationError("mixed_measurement_context")
+
+        front = pareto_front(eligible)
+        ranges = _ranges(eligible)
+        weights = config.effective_weights
+        scores = {
+            item.candidate.candidate_id: _score(item, ranges, weights)
+            for item in front
+        }
+        front_ids = {item.candidate.candidate_id for item in front}
+        updated = tuple(
+            replace(
+                item,
+                pareto_member=item.candidate.candidate_id in front_ids,
+                score=scores.get(item.candidate.candidate_id),
+            )
+            for item in evaluations
+        )
+        ranked_front = sorted(
+            (item for item in updated if item.pareto_member),
+            key=lambda item: (
+                -(item.score if item.score is not None else -1.0),
+                -item.metrics.confidence,
+                item.candidate.candidate_id,
+            ),
+        )
+        selected = ranked_front[0]
+        return OptimizationResult(
+            selected=selected,
+            evaluations=updated,
+            pareto_candidate_ids=tuple(item.candidate.candidate_id for item in ranked_front),
+            profile=config.profile,
+            escalation_level=escalation_level,
+            mode=mode,
+            quality_warnings=quality_warnings,
+        )

devagent_physical_engine/optimization/orchestrator.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+from dataclasses import replace
+
+from .candidates import CandidateSource
+from .contracts import CandidateMetrics, OptimizationConfig, OptimizationResult, PlanCandidate
+from .evaluator import CandidateMetricEvaluator
+from .experience import ExperienceStore
+from .optimizer import MultiObjectiveOptimizer, OptimizationError
+from ..models import Goal, Resource, WorldState
+
+
+class AdaptiveOptimizationError(RuntimeError):
+    pass
+
+
+class AdaptiveOptimizationEngine:
+    """Escalate search only when the current candidate set is not convincing.
+
+    Easy tasks may use a single verified candidate fast path. Ambiguous/risky
+    tasks escalate to comparative search. The returned result explicitly states
+    whether it was a fast path or a true multi-candidate comparison.
+    """
+
+    def __init__(
+        self,
+        source: CandidateSource,
+        evaluator: CandidateMetricEvaluator,
+        *,
+        optimizer: MultiObjectiveOptimizer | None = None,
+        experience_store: ExperienceStore | None = None,
+        config: OptimizationConfig | None = None,
+    ) -> None:
+        self.source = source
+        self.evaluator = evaluator
+        self.optimizer = optimizer or MultiObjectiveOptimizer()
+        self.experience_store = experience_store
+        self.config = config or OptimizationConfig()
+
+    def _experience_bonuses(
+        self,
+        candidates: tuple[PlanCandidate, ...],
+        *,
+        goal: Goal,
+        resources: list[Resource],
+    ) -> dict[str, float]:
+        if self.experience_store is None:
+            return {}
+        resource_map = {resource.resource_id: resource for resource in resources}
+        bonuses: dict[str, float] = {}
+        for candidate in candidates:
+            ordered = candidate.graph.topological_order()
+            if not ordered:
+                continue
+            resource = resource_map.get(ordered[0].contract.resource_id)
+            if resource is None:
+                continue
+            bonuses[candidate.candidate_id] = self.experience_store.bonus(
+                goal=goal,
+                resource=resource,
+                candidate=candidate,
+                max_abs_bonus=self.config.max_experience_bonus,
+            )
+        return bonuses
+
+    def _warnings(self, metrics: CandidateMetrics) -> tuple[str, ...]:
+        thresholds = self.config.thresholds
+        warnings: list[str] = []
+        if metrics.min_clearance_m < thresholds.preferred_clearance_m:
+            warnings.append("clearance_below_preferred")
+        if metrics.recovery_risk > thresholds.preferred_max_recovery_risk:
+            warnings.append("recovery_risk_above_preferred")
+        if metrics.confidence < thresholds.preferred_confidence:
+            warnings.append("confidence_below_preferred")
+        return tuple(warnings)
+
+    def optimize(
+        self,
+        *,
+        goal: Goal,
+        resources: list[Resource],
+        world: WorldState,
+    ) -> OptimizationResult:
+        candidates: tuple[PlanCandidate, ...] = ()
+        metrics_by_id: dict[str, CandidateMetrics] = {}
+        last_error: BaseException | None = None
+
+        for level, target in enumerate(self.config.escalation_targets):
+            candidates = self.source.generate(
+                goal=goal,
+                resources=resources,
+                world=world,
+                target_count=target,
+                existing=candidates,
+                attempt_budget=self.config.max_generation_attempts_per_level,
+            )
+            for candidate in candidates:
+                if candidate.candidate_id in metrics_by_id:
+                    continue
+                metrics_by_id[candidate.candidate_id] = self.evaluator.evaluate(
+                    candidate,
+                    goal=goal,
+                    resources=resources,
+                    world=world,
+                )
+            if not candidates:
+                last_error = AdaptiveOptimizationError("candidate_generation_empty")
+                continue
+
+            bonuses = self._experience_bonuses(candidates, goal=goal, resources=resources)
+            try:
+                provisional = self.optimizer.select(
+                    candidates,
+                    metrics_by_id,
+                    self.config,
+                    experience_bonus_by_id=bonuses,
+                    escalation_level=level,
+                    mode="verified_fast_path" if len(candidates) == 1 else "optimized_multi_candidate",
+                )
+            except OptimizationError as exc:
+                last_error = exc
+                continue
+
+            warnings = self._warnings(provisional.selected.metrics)
+            eligible_count = sum(1 for item in provisional.evaluations if item.eligible)
+
+            if (
+                self.config.allow_fast_path
+                and eligible_count == 1
+                and level == 0
+                and not warnings
+            ):
+                return replace(provisional, quality_warnings=())
+
+            if eligible_count >= 2 and not warnings:
+                return replace(
+                    provisional,
+                    mode="optimized_multi_candidate",
+                    quality_warnings=(),
+                )
+
+            if level == len(self.config.escalation_targets) - 1:
+                return replace(
+                    provisional,
+                    mode=(
+                        "optimized_multi_candidate"
+                        if eligible_count >= 2
+                        else "verified_single_candidate"
+                    ),
+                    quality_warnings=warnings,
+                )
+
+        raise AdaptiveOptimizationError(
+            f"optimization_failed:{type(last_error).__name__ if last_error else 'unknown'}"
+        )