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

devagent_physical_engine/optimization/candidates.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass
+from typing import Protocol, Sequence
+
+from .contracts import PlanCandidate
+from ..agent.contracts import RoutingPolicy
+from ..agent.evidence import task_graph_hash
+from ..agent.planner import PlannerAgent
+from ..models import Goal, Resource, WorldState
+
+
+class CandidateGenerationError(RuntimeError):
+    pass
+
+
+class CandidateSource(Protocol):
+    def generate(
+        self,
+        *,
+        goal: Goal,
+        resources: list[Resource],
+        world: WorldState,
+        target_count: int,
+        existing: tuple[PlanCandidate, ...] = (),
+        attempt_budget: int = 12,
+    ) -> tuple[PlanCandidate, ...]: ...
+
+
+@dataclass(slots=True)
+class StaticCandidateSource:
+    candidates: tuple[PlanCandidate, ...]
+
+    def generate(
+        self,
+        *,
+        goal: Goal,
+        resources: list[Resource],
+        world: WorldState,
+        target_count: int,
+        existing: tuple[PlanCandidate, ...] = (),
+        attempt_budget: int = 12,
+    ) -> tuple[PlanCandidate, ...]:
+        del goal, resources, world, attempt_budget
+        existing_fingerprints = {item.fingerprint for item in existing}
+        output = list(existing)
+        for candidate in self.candidates:
+            if candidate.fingerprint in existing_fingerprints:
+                continue
+            output.append(candidate)
+            existing_fingerprints.add(candidate.fingerprint)
+            if len(output) >= target_count:
+                break
+        return tuple(output)
+
+
+class AgentCandidateGenerator:
+    """Generate unique verified task plans through one or more model policies.
+
+    Parallelism is optional and bounded. Results are merged in attempt order for
+    deterministic evidence. A failed model call consumes budget but does not
+    poison other candidates or expose provider exception text.
+    """
+
+    def __init__(
+        self,
+        planner: PlannerAgent,
+        policies: Sequence[RoutingPolicy],
+        *,
+        max_parallelism: int = 1,
+    ) -> None:
+        if not policies:
+            raise ValueError("candidate_policies_required")
+        if not 1 <= max_parallelism <= 8:
+            raise ValueError("candidate_parallelism_out_of_range")
+        self.planner = planner
+        self.policies = tuple(policies)
+        self.max_parallelism = max_parallelism
+
+    def _plan_once(
+        self,
+        attempt_index: int,
+        *,
+        goal: Goal,
+        resources: list[Resource],
+        world: WorldState,
+        existing_hashes: tuple[str, ...],
+    ) -> tuple[int, object | None]:
+        policy = self.policies[attempt_index % len(self.policies)]
+        feedback = (
+            f"candidate_generation_attempt:{attempt_index + 1}",
+            "Seek a meaningfully different valid resource/task decomposition when alternatives exist.",
+            "Do not invent preconditions, effects, safety claims, or motion constraints.",
+            (
+                f"existing_plan_hashes:{','.join(existing_hashes)}"
+                if existing_hashes
+                else "existing_plan_hashes:none"
+            ),
+        )
+        try:
+            planned = self.planner.plan(
+                goal,
+                resources,
+                world,
+                policy,
+                feedback=feedback,
+            )
+        except Exception:
+            return attempt_index, None
+        return attempt_index, planned
+
+    def generate(
+        self,
+        *,
+        goal: Goal,
+        resources: list[Resource],
+        world: WorldState,
+        target_count: int,
+        existing: tuple[PlanCandidate, ...] = (),
+        attempt_budget: int = 12,
+    ) -> tuple[PlanCandidate, ...]:
+        if target_count <= 0:
+            raise ValueError("target_count_invalid")
+        if attempt_budget <= 0:
+            raise ValueError("attempt_budget_invalid")
+
+        output = list(existing)
+        hashes = {item.graph_hash for item in output}
+        attempt_index = 0
+        successful_calls = 0
+
+        while len(output) < target_count and attempt_index < attempt_budget:
+            remaining_attempts = attempt_budget - attempt_index
+            batch_size = min(self.max_parallelism, remaining_attempts)
+            batch_indices = tuple(range(attempt_index, attempt_index + batch_size))
+            snapshot_hashes = tuple(sorted(hashes))
+            batch_results: list[tuple[int, object | None]] = []
+
+            if batch_size == 1:
+                batch_results.append(
+                    self._plan_once(
+                        batch_indices[0],
+                        goal=goal,
+                        resources=resources,
+                        world=world,
+                        existing_hashes=snapshot_hashes,
+                    )
+                )
+            else:
+                with ThreadPoolExecutor(
+                    max_workers=batch_size,
+                    thread_name_prefix="devagent-candidate",
+                ) as executor:
+                    futures = {
+                        executor.submit(
+                            self._plan_once,
+                            index,
+                            goal=goal,
+                            resources=resources,
+                            world=world,
+                            existing_hashes=snapshot_hashes,
+                        ): index
+                        for index in batch_indices
+                    }
+                    for future in as_completed(futures):
+                        batch_results.append(future.result())
+
+            for _, planned in sorted(batch_results, key=lambda item: item[0]):
+                if planned is None:
+                    continue
+                successful_calls += 1
+                graph_hash = task_graph_hash(planned.graph)
+                if graph_hash in hashes:
+                    continue
+                provider = planned.evidence.selected_provider or "unknown"
+                model = planned.evidence.selected_model or "unknown"
+                output.append(
+                    PlanCandidate(
+                        candidate_id=f"C{len(output) + 1}",
+                        graph=planned.graph,
+                        source=f"{provider}:{model}",
+                        metadata={
+                            "trace_id": planned.evidence.trace_id,
+                            "provider": provider,
+                            "model": model,
+                        },
+                    )
+                )
+                hashes.add(graph_hash)
+                if len(output) >= target_count:
+                    break
+
+            attempt_index += batch_size
+
+        if not output and successful_calls == 0:
+            raise CandidateGenerationError("candidate_generation_exhausted")
+        return tuple(output)

devagent_physical_engine/optimization/contracts.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from math import isfinite
+from typing import Any, Mapping
+from hashlib import sha256
+
+from ..agent.evidence import task_graph_hash
+from ..models import TaskGraph
+
+
+class OptimizationProfileName(str, Enum):
+    BALANCED = "balanced"
+    THROUGHPUT = "throughput"
+    ROBUSTNESS = "robustness"
+    ENERGY = "energy"
+
+
+@dataclass(frozen=True, slots=True)
+class ObjectiveWeights:
+    cycle_time: float
+    path_length: float
+    clearance: float
+    energy: float
+    recovery_risk: float
+    resource_contention: float
+    experience: float = 0.0
+
+    def __post_init__(self) -> None:
+        values = (
+            self.cycle_time,
+            self.path_length,
+            self.clearance,
+            self.energy,
+            self.recovery_risk,
+            self.resource_contention,
+            self.experience,
+        )
+        if any(not isfinite(value) or value < 0 for value in values):
+            raise ValueError("objective_weight_invalid")
+        if sum(values) <= 0:
+            raise ValueError("objective_weights_empty")
+
+    def normalized(self) -> "ObjectiveWeights":
+        total = sum(
+            (
+                self.cycle_time,
+                self.path_length,
+                self.clearance,
+                self.energy,
+                self.recovery_risk,
+                self.resource_contention,
+                self.experience,
+            )
+        )
+        return ObjectiveWeights(
+            cycle_time=self.cycle_time / total,
+            path_length=self.path_length / total,
+            clearance=self.clearance / total,
+            energy=self.energy / total,
+            recovery_risk=self.recovery_risk / total,
+            resource_contention=self.resource_contention / total,
+            experience=self.experience / total,
+        )
+
+    @classmethod
+    def for_profile(cls, profile: OptimizationProfileName) -> "ObjectiveWeights":
+        if profile is OptimizationProfileName.THROUGHPUT:
+            return cls(0.50, 0.15, 0.10, 0.08, 0.08, 0.04, 0.05)
+        if profile is OptimizationProfileName.ROBUSTNESS:
+            return cls(0.16, 0.08, 0.32, 0.05, 0.22, 0.07, 0.10)
+        if profile is OptimizationProfileName.ENERGY:
+            return cls(0.18, 0.12, 0.12, 0.35, 0.10, 0.05, 0.08)
+        return cls(0.30, 0.12, 0.24, 0.10, 0.12, 0.05, 0.07)
+
+
+@dataclass(frozen=True, slots=True)
+class OptimizationThresholds:
+    min_clearance_m: float = 0.0
+    max_recovery_risk: float = 0.40
+    max_resource_contention: float = 0.80
+    min_confidence: float = 0.70
+    preferred_clearance_m: float = 0.02
+    preferred_max_recovery_risk: float = 0.20
+    preferred_confidence: float = 0.90
+
+    def __post_init__(self) -> None:
+        for name, value in (
+            ("min_clearance_m", self.min_clearance_m),
+            ("max_recovery_risk", self.max_recovery_risk),
+            ("max_resource_contention", self.max_resource_contention),
+            ("min_confidence", self.min_confidence),
+            ("preferred_clearance_m", self.preferred_clearance_m),
+            ("preferred_max_recovery_risk", self.preferred_max_recovery_risk),
+            ("preferred_confidence", self.preferred_confidence),
+        ):
+            if not isfinite(value) or value < 0:
+                raise ValueError(f"{name}_invalid")
+        for value in (
+            self.max_recovery_risk,
+            self.max_resource_contention,
+            self.min_confidence,
+            self.preferred_max_recovery_risk,
+            self.preferred_confidence,
+        ):
+            if value > 1.0:
+                raise ValueError("normalized_threshold_out_of_range")
+        if self.preferred_clearance_m < self.min_clearance_m:
+            raise ValueError("preferred_clearance_below_minimum")
+        if self.preferred_max_recovery_risk > self.max_recovery_risk:
+            raise ValueError("preferred_risk_above_maximum")
+        if self.preferred_confidence < self.min_confidence:
+            raise ValueError("preferred_confidence_below_minimum")
+
+
+@dataclass(frozen=True, slots=True)
+class CandidateMetrics:
+    cycle_time_s: float
+    path_length_m: float
+    min_clearance_m: float
+    energy_proxy: float
+    recovery_risk: float
+    resource_contention: float
+    confidence: float
+    measurement_context: str = "default"
+    metrics_origin: str = "unspecified"
+    simulation_success: bool = True
+    hard_violations: tuple[str, ...] = ()
+    unknown_fields: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        nonnegative = (
+            ("cycle_time_s", self.cycle_time_s),
+            ("path_length_m", self.path_length_m),
+            ("min_clearance_m", self.min_clearance_m),
+            ("energy_proxy", self.energy_proxy),
+        )
+        for name, value in nonnegative:
+            if not isfinite(value) or value < 0:
+                raise ValueError(f"{name}_invalid")
+        for name, value in (
+            ("recovery_risk", self.recovery_risk),
+            ("resource_contention", self.resource_contention),
+            ("confidence", self.confidence),
+        ):
+            if not isfinite(value) or not 0.0 <= value <= 1.0:
+                raise ValueError(f"{name}_out_of_range")
+        if not self.measurement_context.strip():
+            raise ValueError("measurement_context_required")
+        if not self.metrics_origin.strip():
+            raise ValueError("metrics_origin_required")
+        if any(not item.strip() for item in self.hard_violations):
+            raise ValueError("empty_hard_violation")
+        if any(not item.strip() for item in self.unknown_fields):
+            raise ValueError("empty_unknown_field")
+
+
+@dataclass(frozen=True, slots=True)
+class PlanCandidate:
+    candidate_id: str
+    graph: TaskGraph
+    source: str = "unknown"
+    variant_key: str = "task"
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.candidate_id.strip():
+            raise ValueError("candidate_id_required")
+        if not self.source.strip():
+            raise ValueError("candidate_source_required")
+        if not self.variant_key.strip():
+            raise ValueError("candidate_variant_key_required")
+
+    @property
+    def graph_hash(self) -> str:
+        return task_graph_hash(self.graph)
+
+    @property
+    def fingerprint(self) -> str:
+        raw = f"{self.graph_hash}:{self.variant_key.strip()}".encode("utf-8")
+        return sha256(raw).hexdigest()
+
+
+@dataclass(frozen=True, slots=True)
+class CandidateEvaluation:
+    candidate: PlanCandidate
+    metrics: CandidateMetrics
+    eligible: bool
+    disqualifiers: tuple[str, ...] = ()
+    score: float | None = None
+    pareto_member: bool = False
+    experience_bonus: float = 0.0
+
+
+@dataclass(frozen=True, slots=True)
+class OptimizationResult:
+    selected: CandidateEvaluation
+    evaluations: tuple[CandidateEvaluation, ...]
+    pareto_candidate_ids: tuple[str, ...]
+    profile: OptimizationProfileName
+    escalation_level: int
+    mode: str
+    quality_warnings: tuple[str, ...] = ()
+
+    @property
+    def comparatively_optimized(self) -> bool:
+        return len([item for item in self.evaluations if item.eligible]) >= 2
+
+
+@dataclass(frozen=True, slots=True)
+class OptimizationConfig:
+    profile: OptimizationProfileName = OptimizationProfileName.BALANCED
+    weights: ObjectiveWeights | None = None
+    thresholds: OptimizationThresholds = field(default_factory=OptimizationThresholds)
+    escalation_targets: tuple[int, ...] = (1, 3, 5)
+    max_generation_attempts_per_level: int = 12
+    allow_fast_path: bool = True
+    max_experience_bonus: float = 0.05
+
+    def __post_init__(self) -> None:
+        if not self.escalation_targets:
+            raise ValueError("escalation_targets_required")
+        if any(target <= 0 for target in self.escalation_targets):
+            raise ValueError("escalation_target_invalid")
+        if tuple(sorted(set(self.escalation_targets))) != self.escalation_targets:
+            raise ValueError("escalation_targets_must_be_unique_sorted")
+        if not 1 <= self.max_generation_attempts_per_level <= 64:
+            raise ValueError("generation_attempt_budget_out_of_range")
+        if not 0.0 <= self.max_experience_bonus <= 0.20:
+            raise ValueError("max_experience_bonus_out_of_range")
+
+    @property
+    def effective_weights(self) -> ObjectiveWeights:
+        return (self.weights or ObjectiveWeights.for_profile(self.profile)).normalized()

devagent_physical_engine/optimization/evaluator.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import Callable, Mapping, Protocol
+
+from .contracts import CandidateMetrics, PlanCandidate
+from ..agent.semantic import AgentPlanSemanticPolicy
+from ..execution import ExecutionMode, ExecutionSupervisor
+from ..models import Goal, Resource, WorldState
+from ..simulation import DeterministicSimulationBackend, SimulationBackend
+from ..verification import DeterministicVerifier
+
+
+class CandidateMetricEvaluator(Protocol):
+    def evaluate(
+        self,
+        candidate: PlanCandidate,
+        *,
+        goal: Goal,
+        resources: list[Resource],
+        world: WorldState,
+    ) -> CandidateMetrics: ...
+
+
+def candidate_verification_violations(
+    candidate: PlanCandidate,
+    *,
+    goal: Goal,
+    resources: list[Resource],
+    world: WorldState,
+) -> tuple[str, ...]:
+    """Run structural/capability and semantic verification before optimization."""
+    issues: list[str] = []
+    structural = DeterministicVerifier().verify_graph(candidate.graph, resources)
+    issues.extend(f"structural:{issue.code}" for issue in structural.issues)
+    semantic = AgentPlanSemanticPolicy().verify(goal, candidate.graph, resources, world)
+    issues.extend(f"semantic:{issue.code}" for issue in semantic.issues)
+    return tuple(dict.fromkeys(issues))
+
+
+class DeterministicMetricEvaluator:
+    """Qualification evaluator with deterministic metric fixtures.
+
+    It still verifies and executes the candidate through DevAgent's deterministic
+    boundaries; fixture metrics cannot hide plan or simulation failure. Real
+    ROS/Gazebo metric extraction implements `CandidateMetricEvaluator`
+    separately.
+    """
+
+    def __init__(
+        self,
+        metrics_by_id: Mapping[str, CandidateMetrics],
+        *,
+        backend_factory: Callable[[PlanCandidate], SimulationBackend] | None = None,
+    ) -> None:
+        self._metrics_by_id = dict(metrics_by_id)
+        self._backend_factory = backend_factory or (lambda _: DeterministicSimulationBackend())
+
+    def evaluate(
+        self,
+        candidate: PlanCandidate,
+        *,
+        goal: Goal,
+        resources: list[Resource],
+        world: WorldState,
+    ) -> CandidateMetrics:
+        try:
+            metrics = self._metrics_by_id[candidate.candidate_id]
+        except KeyError as exc:
+            raise KeyError(f"missing_metric_fixture:{candidate.candidate_id}") from exc
+
+        verification = candidate_verification_violations(
+            candidate,
+            goal=goal,
+            resources=resources,
+            world=world,
+        )
+        if verification:
+            return replace(
+                metrics,
+                simulation_success=False,
+                hard_violations=tuple(
+                    dict.fromkeys(metrics.hard_violations + ("plan_verification_failed",) + verification)
+                ),
+            )
+
+        simulation_world = WorldState(facts=set(world.facts), values=dict(world.values))
+        report = ExecutionSupervisor().execute(
+            candidate.graph,
+            resources,
+            simulation_world,
+            self._backend_factory(candidate),
+            ExecutionMode.SIMULATION,
+        )
+        if report.completed:
+            return metrics
+        violation_codes = tuple(
+            dict.fromkeys(
+                ("deterministic_simulation_failed",)
+                + tuple(issue.code for issue in report.issues)
+            )
+        )
+        return replace(
+            metrics,
+            simulation_success=False,
+            hard_violations=tuple(dict.fromkeys(metrics.hard_violations + violation_codes)),
+        )

devagent_physical_engine/optimization/evidence.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from hashlib import sha256
+from typing import Any
+
+from .contracts import OptimizationResult
+from ..agent.structured import canonical_json
+
+
+def optimization_evidence(result: OptimizationResult) -> dict[str, Any]:
+    return {
+        "profile": result.profile.value,
+        "mode": result.mode,
+        "escalation_level": result.escalation_level,
+        "selected_candidate_id": result.selected.candidate.candidate_id,
+        "selected_graph_hash": result.selected.candidate.graph_hash,
+        "selected_candidate_fingerprint": result.selected.candidate.fingerprint,
+        "pareto_candidate_ids": list(result.pareto_candidate_ids),
+        "quality_warnings": list(result.quality_warnings),
+        "candidates": [
+            {
+                "candidate_id": evaluation.candidate.candidate_id,
+                "graph_hash": evaluation.candidate.graph_hash,
+                "candidate_fingerprint": evaluation.candidate.fingerprint,
+                "variant_key": evaluation.candidate.variant_key,
+                "source": evaluation.candidate.source,
+                "eligible": evaluation.eligible,
+                "disqualifiers": list(evaluation.disqualifiers),
+                "pareto_member": evaluation.pareto_member,
+                "score": evaluation.score,
+                "experience_bonus": evaluation.experience_bonus,
+                "metrics": {
+                    "cycle_time_s": evaluation.metrics.cycle_time_s,
+                    "path_length_m": evaluation.metrics.path_length_m,
+                    "min_clearance_m": evaluation.metrics.min_clearance_m,
+                    "energy_proxy": evaluation.metrics.energy_proxy,
+                    "recovery_risk": evaluation.metrics.recovery_risk,
+                    "resource_contention": evaluation.metrics.resource_contention,
+                    "confidence": evaluation.metrics.confidence,
+                    "measurement_context": evaluation.metrics.measurement_context,
+                    "metrics_origin": evaluation.metrics.metrics_origin,
+                    "simulation_success": evaluation.metrics.simulation_success,
+                    "hard_violations": list(evaluation.metrics.hard_violations),
+                    "unknown_fields": list(evaluation.metrics.unknown_fields),
+                },
+            }
+            for evaluation in result.evaluations
+        ],
+    }
+
+
+def optimization_evidence_hash(result: OptimizationResult) -> str:
+    return sha256(canonical_json(optimization_evidence(result)).encode("utf-8")).hexdigest()

devagent_physical_engine/optimization/experience.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+from threading import Lock
+
+from .contracts import CandidateMetrics, PlanCandidate
+from ..models import Goal, Resource
+
+
+@dataclass(frozen=True, slots=True)
+class ExperienceKey:
+    goal_action: str
+    vendor: str
+    model: str
+    destination: str
+
+
+@dataclass(frozen=True, slots=True)
+class ExperienceRecord:
+    key: ExperienceKey
+    candidate_fingerprint: str
+    success: bool
+    verified: bool
+    metrics: CandidateMetrics
+
+
+class ExperienceStore:
+    """Bounded verified-outcome memory used only as a small ranking prior.
+
+    Experience can never make an ineligible candidate eligible and never changes
+    deterministic safety/semantic verification.
+    """
+
+    def __init__(self, *, max_records: int = 2048) -> None:
+        if not 32 <= max_records <= 100_000:
+            raise ValueError("experience_max_records_out_of_range")
+        self._records: deque[ExperienceRecord] = deque(maxlen=max_records)
+        self._lock = Lock()
+
+    @staticmethod
+    def key(goal: Goal, resource: Resource) -> ExperienceKey:
+        return ExperienceKey(
+            goal_action=goal.action.strip().lower(),
+            vendor=str(resource.metadata.get("vendor", "unknown")).strip().lower(),
+            model=str(resource.metadata.get("model", "unknown")).strip().lower(),
+            destination=goal.destination.strip().lower(),
+        )
+
+    def record(
+        self,
+        *,
+        goal: Goal,
+        resource: Resource,
+        candidate: PlanCandidate,
+        metrics: CandidateMetrics,
+        success: bool,
+        verified: bool,
+    ) -> None:
+        if not verified:
+            return
+        record = ExperienceRecord(
+            key=self.key(goal, resource),
+            candidate_fingerprint=candidate.fingerprint,
+            success=bool(success),
+            verified=True,
+            metrics=metrics,
+        )
+        with self._lock:
+            self._records.append(record)
+
+    def prior(
+        self,
+        *,
+        goal: Goal,
+        resource: Resource,
+        candidate: PlanCandidate,
+    ) -> float:
+        key = self.key(goal, resource)
+        with self._lock:
+            matches = tuple(
+                record
+                for record in self._records
+                if record.key == key and record.candidate_fingerprint == candidate.fingerprint
+            )
+        successes = sum(1 for record in matches if record.success)
+        failures = len(matches) - successes
+        return (successes + 1.0) / (successes + failures + 2.0)
+
+    def bonus(
+        self,
+        *,
+        goal: Goal,
+        resource: Resource,
+        candidate: PlanCandidate,
+        max_abs_bonus: float = 0.05,
+    ) -> float:
+        if not 0.0 <= max_abs_bonus <= 0.20:
+            raise ValueError("experience_bonus_out_of_range")
+        prior = self.prior(goal=goal, resource=resource, candidate=candidate)
+        return (prior - 0.5) * 2.0 * max_abs_bonus
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._records)