solverpilot 0.1__py3-none-any.whl

solverpilot/nlp/validation.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+from dataclasses import dataclass
+import numpy as np
+from .ad import NLPDerivativeEngine, evaluate_node
+from .ir import NLPProblem
+
+@dataclass(frozen=True, slots=True)
+class NLPValidationReport:
+    valid: bool
+    max_bound_violation: float
+    max_constraint_violation: float
+    objective_recomputed: float | None
+    objective_reported: float | None
+    objective_difference: float | None
+    objective_consistent: bool | None
+    finite: bool
+    warnings: tuple[str,...]=()
+
+
+def _violation(v, lo, hi):
+    return np.maximum(np.maximum(lo-v, v-hi), 0.0)
+
+def validate_nlp_solution(problem:NLPProblem, x, *, objective_reported=None, atol=1e-7, rtol=1e-7):
+    for name, raw in (("atol", atol), ("rtol", rtol)):
+        if isinstance(raw, bool) or type(raw) not in (int, float) or not np.isfinite(float(raw)) or float(raw) < 0:
+            raise ValueError(f'{name} must be finite and non-negative')
+    atol=float(atol); rtol=float(rtol)
+    if x is None:
+        return NLPValidationReport(False, np.inf, np.inf, None, objective_reported, None, None, False, ('missing primal solution',))
+    x=np.asarray(x,dtype=float).reshape(-1)
+    if x.shape != (problem.n_variables,) or not np.all(np.isfinite(x)):
+        return NLPValidationReport(False, np.inf, np.inf, None, objective_reported, None, None, False, ('non-finite or wrong-shaped primal solution',))
+    bv=float(np.max(_violation(x,problem.variable_lower,problem.variable_upper))) if x.size else 0.0
+    vals=[]
+    finite=True
+    for c in problem.constraints:
+        val=np.asarray(evaluate_node(problem,c.node,x),dtype=float).reshape(-1)
+        if not np.all(np.isfinite(val)): finite=False
+        vals.append((val,c.lower,c.upper))
+    cv=max((float(np.max(_violation(v,l,u))) for v,l,u in vals), default=0.0) if finite else np.inf
+    obj_arr=np.asarray(evaluate_node(problem,problem.objective_node,x),dtype=float).reshape(-1)
+    obj=float(obj_arr[0]) if obj_arr.size==1 and np.isfinite(obj_arr[0]) else None
+    if obj is None:
+        finite=False
+    diff=None; consistent=None
+    reported_finite=True
+    if objective_reported is not None:
+        try:
+            reported_finite=np.isfinite(float(objective_reported))
+        except (TypeError, ValueError):
+            reported_finite=False
+        if not reported_finite:
+            finite=False
+            diff=np.inf
+            consistent=False
+    if objective_reported is not None and obj is not None and reported_finite:
+        diff=abs(float(objective_reported)-obj)
+        consistent=diff <= atol + rtol*max(1.0,abs(obj),abs(float(objective_reported)))
+    valid=finite and bv<=atol and cv<=atol and (consistent is not False)
+    return NLPValidationReport(valid,bv,cv,obj,objective_reported,diff,consistent,finite,())

solverpilot/plan/__init__.py

@@ -0,0 +1,33 @@
+"""Planning primitives.
+
+Only the names listed in ``__all__`` are part of the M30 stable planning surface.
+Milestone-specific evidence translators and rejected research selectors live under
+``solverpilot.experimental``.
+"""
+
+from .model import CandidatePlan, HealthPolicy, PlannerContext, SolveBudget, SolveIntent, SolvePlan
+from .planner import NoCompatibleBackendError, plan_solve
+from .production import (
+    EvidenceClass,
+    M22_OFFICIAL_EVIDENCE,
+    PerformancePolicy,
+    ProductionDecision,
+    ProductionEvidence,
+    plan_production_solve,
+)
+
+__all__ = [
+    "CandidatePlan",
+    "EvidenceClass",
+    "HealthPolicy",
+    "NoCompatibleBackendError",
+    "PerformancePolicy",
+    "PlannerContext",
+    "ProductionDecision",
+    "ProductionEvidence",
+    "SolveBudget",
+    "SolveIntent",
+    "SolvePlan",
+    "plan_production_solve",
+    "plan_solve",
+]

solverpilot/plan/model.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+import math
+
+from solverpilot.inspect import ProblemFingerprint
+
+
+class SolveIntent(str, Enum):
+    PROVE_OPTIMAL = "prove_optimal"
+    BEST_FEASIBLE_UNDER_BUDGET = "best_feasible_under_budget"
+    FAST_FEASIBLE = "fast_feasible"
+    BALANCED = "balanced"
+    HIGH_ACCURACY = "high_accuracy"
+    LOW_MEMORY = "low_memory"
+
+
+class HealthPolicy(str, Enum):
+    """How planner evidence from explicit backend probes is used.
+
+    ``IGNORE`` preserves the capability-only planner. ``PREFER_HEALTHY`` excludes
+    backends that were explicitly observed unhealthy and gives a small tie-break to
+    healthy backends while leaving unprobed backends eligible. ``REQUIRE_HEALTHY``
+    admits only backends with a successful active smoke probe.
+    """
+
+    IGNORE = "ignore"
+    PREFER_HEALTHY = "prefer_healthy"
+    REQUIRE_HEALTHY = "require_healthy"
+
+
+@dataclass(frozen=True, slots=True)
+class SolveBudget:
+    wall_time_s: float | None = None
+    memory_mb: int | None = None
+    threads: int | None = None
+
+    def __post_init__(self) -> None:
+        if self.wall_time_s is not None:
+            if isinstance(self.wall_time_s, bool) or type(self.wall_time_s) not in (int, float):
+                raise ValueError("wall_time_s must be a finite positive number")
+            value = float(self.wall_time_s)
+            if not math.isfinite(value) or value <= 0:
+                raise ValueError("wall_time_s must be a finite positive number")
+            object.__setattr__(self, "wall_time_s", value)
+        for name in ("memory_mb", "threads"):
+            raw = getattr(self, name)
+            if raw is None:
+                continue
+            if isinstance(raw, bool) or type(raw) is not int or raw <= 0:
+                raise ValueError(f"{name} must be a positive integer")
+
+
+@dataclass(frozen=True, slots=True)
+class PlannerContext:
+    previous_backend: str | None = None
+    session_revision: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class CandidatePlan:
+    backend: str
+    score: float
+    rationale: tuple[str, ...]
+    health_status: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class SolvePlan:
+    selected_backend: str
+    candidates: tuple[CandidatePlan, ...]
+    intent: SolveIntent
+    budget: SolveBudget
+    fingerprint: ProblemFingerprint
+    strategy: str
+    rationale: tuple[str, ...]
+    evidence_level: str = "capability_only"
+    health_policy: HealthPolicy = HealthPolicy.IGNORE

solverpilot/plan/planner.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from solverpilot.backends import Backend, BackendHealthReport, BackendProbeStatus, BackendRegistry
+from solverpilot.capabilities import SupportLevel, compatible, requirements_for
+from solverpilot.inspect import ProblemFingerprint, inspect_problem
+from solverpilot.exceptions import NoCompatibleBackendError
+from solverpilot.problem import LinearProblem, QuadraticProblem
+
+from .model import CandidatePlan, HealthPolicy, PlannerContext, SolveBudget, SolveIntent, SolvePlan
+
+
+def _honors_intent(backend: Backend, intent: SolveIntent) -> tuple[bool, str | None]:
+    """Return whether a backend can honor hard semantic parts of an intent.
+
+    Most intents are performance preferences and remain ranking concerns until we have
+    empirical models. ``PROVE_OPTIMAL`` requests a backend capable of a solver-level
+    optimal termination/certificate. It does not promise independent proof reconstruction;
+    callers must inspect ``SolveResult.optimality_evidence`` for the actual trust level.
+    """
+    if intent is SolveIntent.PROVE_OPTIMAL and backend.manifest.metadata.get(
+        "no_optimality_certificate"
+    ) is True:
+        return False, "backend explicitly lacks an optimality certificate"
+    return True, None
+
+
+def _health_map(reports: Iterable[BackendHealthReport] | None) -> dict[str, BackendHealthReport]:
+    if reports is None:
+        return {}
+    result: dict[str, BackendHealthReport] = {}
+    for report in reports:
+        if report.backend in result:
+            raise ValueError(f"duplicate backend health report: {report.backend}")
+        result[report.backend] = report
+    return result
+
+
+def _candidate(
+    backend: Backend,
+    problem: LinearProblem | QuadraticProblem,
+    *,
+    context: PlannerContext,
+    health_report: BackendHealthReport | None,
+    health_policy: HealthPolicy,
+) -> CandidatePlan:
+    requirements = requirements_for(problem)
+    rationale: list[str] = []
+    score = 0.0
+
+    for capability in sorted(requirements.required, key=lambda c: c.value):
+        level = backend.manifest.support(capability)
+        if level is SupportLevel.NATIVE:
+            score += 100.0
+            rationale.append(f"native support: {capability.value}")
+        elif level is SupportLevel.EMULATED_SAFE:
+            score += 80.0
+            rationale.append(f"safe emulation: {capability.value}")
+
+    health_status = None if health_report is None else health_report.status.value
+    if health_policy is not HealthPolicy.IGNORE:
+        if health_report is None:
+            rationale.append("no active backend health probe supplied")
+        elif health_report.status is BackendProbeStatus.HEALTHY:
+            # Deliberately smaller than a capability support step: health is a tie-break,
+            # not an empirical performance claim.
+            score += 1.0
+            rationale.append("active backend smoke probe passed")
+        else:
+            rationale.append(f"backend health probe status: {health_report.status.value}")
+
+    # Stability is a deliberately tiny tie-breaker, not a performance claim.
+    if context.previous_backend == backend.manifest.name:
+        score += 0.1
+        rationale.append("small continuity tie-break: previous backend")
+
+    if backend.manifest.metadata.get("development_bridge"):
+        rationale.append("development bridge; no native state-reuse claim")
+
+    return CandidatePlan(
+        backend=backend.manifest.name,
+        score=score,
+        rationale=tuple(rationale),
+        health_status=health_status,
+    )
+
+
+def plan_solve(
+    problem: LinearProblem | QuadraticProblem,
+    registry: BackendRegistry,
+    *,
+    intent: SolveIntent | str = SolveIntent.BALANCED,
+    budget: SolveBudget | None = None,
+    fingerprint: ProblemFingerprint | None = None,
+    context: PlannerContext | None = None,
+    health_reports: Iterable[BackendHealthReport] | None = None,
+    health_policy: HealthPolicy | str = HealthPolicy.IGNORE,
+) -> SolvePlan:
+    intent = SolveIntent(intent)
+    health_policy = HealthPolicy(health_policy)
+    budget = SolveBudget() if budget is None else budget
+    fingerprint = inspect_problem(problem) if fingerprint is None else fingerprint
+    context = PlannerContext() if context is None else context
+    requirements = requirements_for(problem)
+    health = _health_map(health_reports)
+
+    eligible: list[tuple[int, CandidatePlan]] = []
+    unavailable_compatible: list[str] = []
+    rejected_by_health: list[str] = []
+    rejected_by_intent: list[str] = []
+
+    for registration_index, backend in enumerate(registry.all()):
+        if not compatible(backend.manifest, requirements):
+            continue
+        if not backend.is_available():
+            unavailable_compatible.append(backend.manifest.name)
+            continue
+
+        honors, intent_reason = _honors_intent(backend, intent)
+        if not honors:
+            rejected_by_intent.append(
+                f"{backend.manifest.name} ({intent_reason})"
+            )
+            continue
+
+        report = health.get(backend.manifest.name)
+        if report is not None and report.version != backend.manifest.version:
+            # Health evidence is version-specific. A report from another solver/package
+            # version is stale and must not authorize execution.
+            report = None
+        if health_policy is HealthPolicy.REQUIRE_HEALTHY:
+            if report is None or report.status is not BackendProbeStatus.HEALTHY:
+                rejected_by_health.append(backend.manifest.name)
+                continue
+        elif health_policy is HealthPolicy.PREFER_HEALTHY:
+            if report is not None and report.status in {
+                BackendProbeStatus.UNHEALTHY,
+                BackendProbeStatus.UNAVAILABLE,
+            }:
+                rejected_by_health.append(backend.manifest.name)
+                continue
+
+        eligible.append(
+            (
+                registration_index,
+                _candidate(
+                    backend,
+                    problem,
+                    context=context,
+                    health_report=report,
+                    health_policy=health_policy,
+                ),
+            )
+        )
+
+    if not eligible:
+        required = ", ".join(sorted(c.value for c in requirements.required))
+        extras: list[str] = []
+        if unavailable_compatible:
+            extras.append(f"compatible but unavailable: {', '.join(unavailable_compatible)}")
+        if rejected_by_health:
+            extras.append(f"rejected by health policy: {', '.join(rejected_by_health)}")
+        if rejected_by_intent:
+            extras.append(f"rejected by solve intent: {', '.join(rejected_by_intent)}")
+        suffix = "" if not extras else " " + "; ".join(extras) + "."
+        raise NoCompatibleBackendError(
+            f"no available backend supports required capabilities: {required}.{suffix}"
+        )
+
+    # Score first. Registration order is the explicit deterministic tie-breaker.
+    ranked = sorted(eligible, key=lambda item: (-item[1].score, item[0]))
+    candidates = tuple(item[1] for item in ranked)
+    selected = candidates[0]
+
+    rationale = [
+        f"selected {selected.backend} after hard capability and availability filtering",
+        "no empirical performance model is active",
+    ]
+    if health_policy is not HealthPolicy.IGNORE:
+        rationale.append(f"backend health policy: {health_policy.value}")
+    if intent is SolveIntent.PROVE_OPTIMAL:
+        rationale.append("hard intent gate excluded backends that explicitly lack optimality certificates")
+    tied = [c for c in candidates if c.score == selected.score]
+    if len(tied) > 1:
+        rationale.append(
+            "top candidates tied on evidence-backed score; registration order used as tie-break"
+        )
+
+    evidence_level = "capability_only" if health_policy is HealthPolicy.IGNORE else "capability+active_health"
+    return SolvePlan(
+        selected_backend=selected.backend,
+        candidates=candidates,
+        intent=intent,
+        budget=budget,
+        fingerprint=fingerprint,
+        strategy="single_backend",
+        rationale=tuple(rationale),
+        evidence_level=evidence_level,
+        health_policy=health_policy,
+    )