solverpilot 0.1__py3-none-any.whl

solverpilot/inspect/fingerprint.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+
+import numpy as np
+from scipy import sparse
+
+from solverpilot.problem import ConvexityStatus, LinearProblem, QuadraticProblem, VariableDomain
+
+
+@dataclass(frozen=True, slots=True)
+class DistributionStats:
+    minimum: float
+    q25: float
+    median: float
+    mean: float
+    q75: float
+    maximum: float
+
+
+@dataclass(frozen=True, slots=True)
+class ProblemFingerprint:
+    problem_class: str
+    n_variables: int
+    n_constraints: int
+    nnz_a: int
+    density_a: float
+    binary_fraction: float
+    integer_fraction: float
+    equality_fraction: float
+    fully_bounded_variable_fraction: float
+    free_variable_fraction: float
+    objective_nnz_fraction: float
+    coefficient_dynamic_range_log10: float | None
+    objective_dynamic_range_log10: float | None
+    rhs_dynamic_range_log10: float | None
+    row_nnz: DistributionStats
+    col_nnz: DistributionStats
+    singleton_rows: int
+    singleton_cols: int
+    positive_coefficient_fraction: float
+    negative_coefficient_fraction: float
+    quadratic_nnz: int | None
+    quadratic_density: float | None
+    convexity_status: str | None
+    structural_hash: str
+    estimated_numeric_bytes: int
+
+
+def _distribution(values: np.ndarray) -> DistributionStats:
+    values = np.asarray(values, dtype=np.float64)
+    if values.size == 0:
+        return DistributionStats(0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
+    q25, med, q75 = np.quantile(values, [0.25, 0.5, 0.75])
+    return DistributionStats(
+        minimum=float(np.min(values)),
+        q25=float(q25),
+        median=float(med),
+        mean=float(np.mean(values)),
+        q75=float(q75),
+        maximum=float(np.max(values)),
+    )
+
+
+def _dynamic_range_log10(values: np.ndarray) -> float | None:
+    values = np.asarray(values, dtype=np.float64)
+    finite_nonzero = np.abs(values[np.isfinite(values) & (values != 0.0)])
+    if finite_nonzero.size == 0:
+        return None
+    lo = float(np.min(finite_nonzero))
+    hi = float(np.max(finite_nonzero))
+    if lo <= 0.0 or hi <= 0.0:
+        return None
+    return float(math.log10(hi / lo))
+
+
+def _estimated_bytes_linear(problem: LinearProblem) -> int:
+    A = problem.A
+    sparse_bytes = int(A.data.nbytes + A.indices.nbytes + A.indptr.nbytes)
+    dense_bytes = sum(
+        int(arr.nbytes)
+        for arr in (
+            problem.c,
+            problem.variable_lower,
+            problem.variable_upper,
+            problem.constraint_lower,
+            problem.constraint_upper,
+            problem.domains,
+        )
+    )
+    return sparse_bytes + dense_bytes
+
+
+def inspect_problem(problem: LinearProblem | QuadraticProblem) -> ProblemFingerprint:
+    if isinstance(problem, QuadraticProblem):
+        if problem.convexity_status is not ConvexityStatus.CONFIRMED:
+            raise ValueError("unverified quadratic problem cannot be inspected/routed as convex_qp")
+        linear = problem.linear
+        problem_class = "convex_qp"
+        quadratic_nnz: int | None = int(problem.P.nnz)
+        n = problem.n_variables
+        quadratic_density: float | None = (
+            float(problem.P.nnz / (n * n)) if n > 0 else 0.0
+        )
+        convexity_status: str | None = ConvexityStatus(problem.convexity_status).value
+        extra_bytes = int(problem.P.data.nbytes + problem.P.indices.nbytes + problem.P.indptr.nbytes)
+    elif isinstance(problem, LinearProblem):
+        linear = problem
+        problem_class = "milp" if problem.has_integer_variables else "lp"
+        quadratic_nnz = None
+        quadratic_density = None
+        convexity_status = None
+        extra_bytes = 0
+    else:
+        raise TypeError(f"unsupported problem type: {type(problem)!r}")
+
+    m, n = linear.A.shape
+    size = m * n
+    density = float(linear.A.nnz / size) if size else 0.0
+
+    domains = linear.domains
+    if n:
+        binary_fraction = float(np.mean(domains == VariableDomain.BINARY.value))
+        integer_fraction = float(
+            np.mean(
+                np.isin(
+                    domains,
+                    [VariableDomain.INTEGER.value, VariableDomain.BINARY.value],
+                )
+            )
+        )
+        fully_bounded = float(
+            np.mean(np.isfinite(linear.variable_lower) & np.isfinite(linear.variable_upper))
+        )
+        free_fraction = float(
+            np.mean(np.isneginf(linear.variable_lower) & np.isposinf(linear.variable_upper))
+        )
+        objective_nnz_fraction = float(np.count_nonzero(linear.c) / n)
+    else:
+        binary_fraction = integer_fraction = fully_bounded = free_fraction = 0.0
+        objective_nnz_fraction = 0.0
+
+    if m:
+        equality_mask = (
+            np.isfinite(linear.constraint_lower)
+            & np.isfinite(linear.constraint_upper)
+            & (linear.constraint_lower == linear.constraint_upper)
+        )
+        equality_fraction = float(np.mean(equality_mask))
+    else:
+        equality_fraction = 0.0
+
+    row_counts = np.diff(linear.A.indptr)
+    col_counts = np.diff(linear.A.tocsc().indptr)
+
+    data = linear.A.data
+    if data.size:
+        positive_fraction = float(np.mean(data > 0.0))
+        negative_fraction = float(np.mean(data < 0.0))
+    else:
+        positive_fraction = negative_fraction = 0.0
+
+    finite_rhs = np.concatenate(
+        [
+            linear.constraint_lower[np.isfinite(linear.constraint_lower)],
+            linear.constraint_upper[np.isfinite(linear.constraint_upper)],
+            linear.variable_lower[np.isfinite(linear.variable_lower)],
+            linear.variable_upper[np.isfinite(linear.variable_upper)],
+        ]
+    )
+
+    return ProblemFingerprint(
+        problem_class=problem_class,
+        n_variables=n,
+        n_constraints=m,
+        nnz_a=int(linear.A.nnz),
+        density_a=density,
+        binary_fraction=binary_fraction,
+        integer_fraction=integer_fraction,
+        equality_fraction=equality_fraction,
+        fully_bounded_variable_fraction=fully_bounded,
+        free_variable_fraction=free_fraction,
+        objective_nnz_fraction=objective_nnz_fraction,
+        coefficient_dynamic_range_log10=_dynamic_range_log10(linear.A.data),
+        objective_dynamic_range_log10=_dynamic_range_log10(linear.c),
+        rhs_dynamic_range_log10=_dynamic_range_log10(finite_rhs),
+        row_nnz=_distribution(row_counts),
+        col_nnz=_distribution(col_counts),
+        singleton_rows=int(np.count_nonzero(row_counts == 1)),
+        singleton_cols=int(np.count_nonzero(col_counts == 1)),
+        positive_coefficient_fraction=positive_fraction,
+        negative_coefficient_fraction=negative_fraction,
+        quadratic_nnz=quadratic_nnz,
+        quadratic_density=quadratic_density,
+        convexity_status=convexity_status,
+        structural_hash=problem.structural_hash,
+        estimated_numeric_bytes=_estimated_bytes_linear(linear) + extra_bytes,
+    )

solverpilot/intelligence/__init__.py

@@ -0,0 +1,36 @@
+"""Feature contracts and conservative distribution-shift diagnostics.
+
+This package does not select a solver. It only standardizes pre-solve features,
+audits leakage boundaries, and reports simple explainable shift evidence.
+"""
+from .errors import DistributionShiftError, FeatureSchemaError, IntelligenceError, LeakageDetectedError
+from .fingerprint import PROBLEM_FINGERPRINT_FEATURE_SCHEMA, feature_record_from_problem, problem_fingerprint_feature_schema
+from .leakage import LeakageAuditReport, LeakageFinding, audit_feature_boundary
+from .schema import (
+    FeatureDataType,
+    FeatureDefinition,
+    FeatureRecord,
+    FeatureSchema,
+    MissingnessPolicy,
+    build_feature_record,
+    build_feature_schema,
+)
+from .shift import (
+    DistributionShiftAssessment,
+    DistributionShiftProfile,
+    ShiftFlag,
+    ShiftSeverity,
+    assess_distribution_shift,
+    fit_distribution_shift_profile,
+    fit_training_shift_profile,
+)
+
+__all__ = [
+    "IntelligenceError", "FeatureSchemaError", "LeakageDetectedError", "DistributionShiftError",
+    "FeatureDataType", "MissingnessPolicy", "FeatureDefinition", "FeatureSchema", "FeatureRecord",
+    "build_feature_schema", "build_feature_record",
+    "LeakageFinding", "LeakageAuditReport", "audit_feature_boundary",
+    "ShiftSeverity", "ShiftFlag", "DistributionShiftProfile", "DistributionShiftAssessment",
+    "fit_distribution_shift_profile", "fit_training_shift_profile", "assess_distribution_shift",
+    "PROBLEM_FINGERPRINT_FEATURE_SCHEMA", "problem_fingerprint_feature_schema", "feature_record_from_problem",
+]

solverpilot/intelligence/errors.py

@@ -0,0 +1,16 @@
+"""Errors for versioned feature-intelligence contracts."""
+
+class IntelligenceError(ValueError):
+    """Base error for SolverPilot feature-intelligence validation."""
+
+
+class FeatureSchemaError(IntelligenceError):
+    """Raised when a feature schema or record is invalid."""
+
+
+class LeakageDetectedError(IntelligenceError):
+    """Raised when feature inputs cross the pre-solve/outcome boundary."""
+
+
+class DistributionShiftError(IntelligenceError):
+    """Raised when a distribution-shift profile cannot be built or compared safely."""

solverpilot/intelligence/fingerprint.py

@@ -0,0 +1,108 @@
+"""Versioned feature schema for SolverPilot's existing ProblemFingerprint."""
+from __future__ import annotations
+
+from solverpilot.inspect import ProblemFingerprint, inspect_problem
+from solverpilot.problem import LinearProblem, QuadraticProblem
+
+from .schema import FeatureDefinition, FeatureRecord, MissingnessPolicy, build_feature_record, build_feature_schema
+
+_EXTRACTOR_ID = "solverpilot.inspect.problem_fingerprint"
+_EXTRACTOR_VERSION = "1.0.0"
+
+
+def _d(name: str, dtype: str, unit: str, source: tuple[str, ...], *, nullable: bool = False, allowed: tuple[str, ...] = (), lower: float | None = None, upper: float | None = None) -> FeatureDefinition:
+    return FeatureDefinition(
+        name=name,
+        data_type=dtype,
+        unit=unit,
+        missingness=MissingnessPolicy.NULLABLE if nullable else MissingnessPolicy.FORBIDDEN,
+        description=f"Pre-solve structural feature {name} derived from the canonical problem representation.",
+        source_fields=source,
+        lower_bound=lower,
+        upper_bound=upper,
+        allowed_values=allowed,
+    )
+
+
+def problem_fingerprint_feature_schema():
+    defs = [
+        _d("problem_class", "categorical", "category", ("problem.type",), allowed=("convex_qp", "lp", "milp")),
+        _d("n_variables", "integer", "count", ("problem.variables",), lower=0),
+        _d("n_constraints", "integer", "count", ("problem.constraints",), lower=0),
+        _d("nnz_a", "integer", "count", ("problem.A",), lower=0),
+        _d("density_a", "number", "ratio", ("problem.A",), lower=0, upper=1),
+        _d("binary_fraction", "number", "ratio", ("problem.domains",), lower=0, upper=1),
+        _d("integer_fraction", "number", "ratio", ("problem.domains",), lower=0, upper=1),
+        _d("equality_fraction", "number", "ratio", ("problem.constraint_bounds",), lower=0, upper=1),
+        _d("fully_bounded_variable_fraction", "number", "ratio", ("problem.variable_bounds",), lower=0, upper=1),
+        _d("free_variable_fraction", "number", "ratio", ("problem.variable_bounds",), lower=0, upper=1),
+        _d("objective_nnz_fraction", "number", "ratio", ("problem.objective_coefficients",), lower=0, upper=1),
+        _d("coefficient_dynamic_range_log10", "number", "log10_ratio", ("problem.A",), nullable=True, lower=0),
+        _d("objective_dynamic_range_log10", "number", "log10_ratio", ("problem.objective_coefficients",), nullable=True, lower=0),
+        _d("rhs_dynamic_range_log10", "number", "log10_ratio", ("problem.constraint_bounds", "problem.variable_bounds"), nullable=True, lower=0),
+        _d("singleton_rows", "integer", "count", ("problem.A",), lower=0),
+        _d("singleton_cols", "integer", "count", ("problem.A",), lower=0),
+        _d("positive_coefficient_fraction", "number", "ratio", ("problem.A",), lower=0, upper=1),
+        _d("negative_coefficient_fraction", "number", "ratio", ("problem.A",), lower=0, upper=1),
+        _d("quadratic_nnz", "integer", "count", ("problem.P",), nullable=True, lower=0),
+        _d("quadratic_density", "number", "ratio", ("problem.P",), nullable=True, lower=0, upper=1),
+        _d("convexity_status", "categorical", "category", ("problem.convexity_status",), nullable=True, allowed=("confirmed",)),
+        _d("estimated_numeric_bytes", "integer", "bytes", ("problem.canonical_arrays",), lower=0),
+    ]
+    for prefix in ("row_nnz", "col_nnz"):
+        for suffix in ("minimum", "q25", "median", "mean", "q75", "maximum"):
+            defs.append(_d(f"{prefix}_{suffix}", "number", "count", ("problem.A",), lower=0))
+    return build_feature_schema(domain="solverpilot_problem_fingerprint", version="1.0.0", definitions=defs)
+
+
+PROBLEM_FINGERPRINT_FEATURE_SCHEMA = problem_fingerprint_feature_schema()
+
+
+def _values(f: ProblemFingerprint) -> dict[str, object]:
+    values: dict[str, object] = {
+        "problem_class": f.problem_class,
+        "n_variables": f.n_variables,
+        "n_constraints": f.n_constraints,
+        "nnz_a": f.nnz_a,
+        "density_a": f.density_a,
+        "binary_fraction": f.binary_fraction,
+        "integer_fraction": f.integer_fraction,
+        "equality_fraction": f.equality_fraction,
+        "fully_bounded_variable_fraction": f.fully_bounded_variable_fraction,
+        "free_variable_fraction": f.free_variable_fraction,
+        "objective_nnz_fraction": f.objective_nnz_fraction,
+        "coefficient_dynamic_range_log10": f.coefficient_dynamic_range_log10,
+        "objective_dynamic_range_log10": f.objective_dynamic_range_log10,
+        "rhs_dynamic_range_log10": f.rhs_dynamic_range_log10,
+        "singleton_rows": f.singleton_rows,
+        "singleton_cols": f.singleton_cols,
+        "positive_coefficient_fraction": f.positive_coefficient_fraction,
+        "negative_coefficient_fraction": f.negative_coefficient_fraction,
+        "quadratic_nnz": f.quadratic_nnz,
+        "quadratic_density": f.quadratic_density,
+        "convexity_status": f.convexity_status,
+        "estimated_numeric_bytes": f.estimated_numeric_bytes,
+    }
+    for prefix, stats in (("row_nnz", f.row_nnz), ("col_nnz", f.col_nnz)):
+        for suffix in ("minimum", "q25", "median", "mean", "q75", "maximum"):
+            values[f"{prefix}_{suffix}"] = getattr(stats, suffix)
+    return values
+
+
+def feature_record_from_problem(
+    problem: LinearProblem | QuadraticProblem,
+    *,
+    instance_id: str | None = None,
+) -> FeatureRecord:
+    fingerprint = inspect_problem(problem)
+    values = _values(fingerprint)
+    reasons = {name: "not applicable to this problem class" for name, value in values.items() if value is None}
+    return build_feature_record(
+        schema=PROBLEM_FINGERPRINT_FEATURE_SCHEMA,
+        instance_id=problem.data_hash if instance_id is None else instance_id,
+        values=values,
+        missingness_reasons=reasons,
+        source_content_sha256=problem.data_hash,
+        extractor_id=_EXTRACTOR_ID,
+        extractor_version=_EXTRACTOR_VERSION,
+    )

solverpilot/intelligence/leakage.py

@@ -0,0 +1,69 @@
+"""Fail-closed auditing for predictive feature boundaries."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+from typing import Iterable
+
+from .errors import LeakageDetectedError
+from .schema import FeatureRecord, FeatureSchema
+
+_FORBIDDEN_FRAGMENTS = (
+    "solver", "backend_result", "solve_result", "selected_backend", "selected_solver", "winner",
+    "runtime", "wall_clock", "cpu_time", "regret", "target", "label", "prediction",
+    "benchmark_result", "oracle", "quality_score", "best_known", "timeout", "solve_status",
+    "optimality_status", "validation_result", "rank",
+)
+
+
+def _norm(value: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "_", str(value).strip().lower()).strip("_")
+
+
+@dataclass(frozen=True, slots=True)
+class LeakageFinding:
+    code: str
+    location: str
+    fragment: str
+    message: str
+
+
+@dataclass(frozen=True, slots=True)
+class LeakageAuditReport:
+    passed: bool
+    findings: tuple[LeakageFinding, ...]
+    audited_feature_count: int
+    audited_record_count: int
+
+    def require_pass(self) -> None:
+        if not self.passed:
+            raise LeakageDetectedError(f"feature leakage audit failed with {len(self.findings)} finding(s)")
+
+
+def audit_feature_boundary(schema: FeatureSchema, records: Iterable[FeatureRecord] = ()) -> LeakageAuditReport:
+    rows = tuple(records)
+    findings: list[LeakageFinding] = []
+    for definition in schema.definitions:
+        locations = [(f"definition.{definition.name}.name", definition.name)]
+        locations.extend((f"definition.{definition.name}.source_fields", field) for field in definition.source_fields)
+        for location, raw in locations:
+            normalized = _norm(raw)
+            for fragment in _FORBIDDEN_FRAGMENTS:
+                if fragment in normalized:
+                    findings.append(LeakageFinding(
+                        "FORBIDDEN_PREDICTIVE_INPUT", location, fragment,
+                        "feature boundary references solver outcome, runtime, target, oracle, or other post-solve evidence",
+                    ))
+    for record in rows:
+        if record.feature_schema_id != schema.feature_schema_id:
+            findings.append(LeakageFinding(
+                "SCHEMA_MISMATCH", "record.feature_schema_id", "schema_mismatch",
+                "record does not belong to the audited feature schema",
+            ))
+        undeclared = sorted(set(record.values) - set(schema.names))
+        for name in undeclared:
+            findings.append(LeakageFinding(
+                "UNDECLARED_FEATURE", "record.values", name,
+                "record contains an undeclared feature",
+            ))
+    return LeakageAuditReport(not findings, tuple(findings), len(schema.definitions), len(rows))