solverpilot 0.1__py3-none-any.whl

solverpilot/reporting/explain.py

@@ -0,0 +1,327 @@
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import Any
+
+from solverpilot.runtime import SolveResult
+from solverpilot.validate import PublicStatus
+
+from .model import ClaimDisposition, ClaimKind, ExplanationClaim, ExplanationReport
+
+
+_STATUS_EXPLANATIONS: dict[PublicStatus, str] = {
+    PublicStatus.VALID_OPTIMAL: (
+        "The backend reported optimality and the returned primal candidate passed SolverPilot's canonical validation. "
+        "This status alone is not an independent proof of optimality; consult the optimality evidence in this report."
+    ),
+    PublicStatus.VALID_FEASIBLE: (
+        "The returned candidate passed SolverPilot's canonical feasibility validation. "
+        "Feasibility does not establish optimality."
+    ),
+    PublicStatus.FEASIBLE_LIMIT: (
+        "A candidate passed canonical validation, but the backend terminated at a configured or solver limit. "
+        "The result must not be presented as proven optimal."
+    ),
+    PublicStatus.INFEASIBLE: (
+        "The backend reported the model infeasible. Additional SolverPilot diagnostics, when present, are reported separately; "
+        "the public status alone is not an independently reconstructed universal infeasibility proof."
+    ),
+    PublicStatus.UNBOUNDED: (
+        "The backend reported the model unbounded. SolverPilot does not infer an independent unboundedness proof from this status alone."
+    ),
+    PublicStatus.INFEASIBLE_OR_UNBOUNDED: (
+        "The backend could not distinguish infeasibility from unboundedness. Neither conclusion should be stated separately without more evidence."
+    ),
+    PublicStatus.INVALID_SOLUTION: (
+        "The backend returned a candidate that failed SolverPilot's independent canonical validation. "
+        "The candidate must not be presented as a valid solution."
+    ),
+    PublicStatus.ERROR: (
+        "The solve did not produce a validated normal result. No feasibility, optimality, infeasibility, or superiority claim follows from this status."
+    ),
+    PublicStatus.UNKNOWN: (
+        "The outcome could not be mapped to a stronger public status. Additional evidence is required before making a solve-quality claim."
+    ),
+}
+
+
+def explain_status(status: PublicStatus | str) -> str:
+    if isinstance(status, str):
+        status = PublicStatus(status)
+    return _STATUS_EXPLANATIONS[status]
+
+
+def _validation_payload(result: SolveResult) -> dict[str, Any] | None:
+    report = result.validation
+    if report is None:
+        return None
+    return {
+        "valid": report.valid,
+        "max_bound_violation": report.max_bound_violation,
+        "max_constraint_violation": report.max_constraint_violation,
+        "max_integrality_violation": report.max_integrality_violation,
+        "objective_recomputed": report.objective_recomputed,
+        "objective_reported": report.objective_reported,
+        "objective_difference": report.objective_difference,
+        "objective_consistent": report.objective_consistent,
+        "warnings": tuple(report.warnings),
+    }
+
+
+def _optimality_payload(result: SolveResult) -> dict[str, bool]:
+    evidence = result.optimality_evidence
+    return {
+        "backend_reported_optimal": evidence.backend_reported_optimal,
+        "primal_validated": evidence.primal_validated,
+        "dual_verified": evidence.dual_verified,
+        "gap_verified": evidence.gap_verified,
+        "certificate_verified": evidence.certificate_verified,
+        "independently_verified_optimal": evidence.independently_verified_optimal,
+    }
+
+
+def _planner_payload(result: SolveResult) -> dict[str, Any] | None:
+    plan = result.plan
+    if plan is None:
+        return None
+    return {
+        "selected_backend": plan.selected_backend,
+        "intent": plan.intent.value,
+        "strategy": plan.strategy,
+        "evidence_level": plan.evidence_level,
+        "health_policy": plan.health_policy.value,
+        "rationale": tuple(plan.rationale),
+        "candidate_count": len(plan.candidates),
+    }
+
+
+def _runtime_payload(result: SolveResult) -> dict[str, Any]:
+    timings = result.trace.timings
+    return {
+        "reuse_applied": result.trace.reuse_applied,
+        "reuse_mode": result.trace.reuse_mode,
+        "total_s": timings.total_s,
+        "solve_s": timings.solve_s,
+        "validate_s": timings.validate_s,
+        "diagnose_s": timings.diagnose_s,
+    }
+
+
+def _diagnostics_payload(result: SolveResult) -> dict[str, Any] | None:
+    diagnostics = result.diagnostics
+    if diagnostics is None:
+        return None
+    return {
+        "confirmed_infeasible": diagnostics.confirmed_infeasible,
+        "static_issue_count": len(diagnostics.static_issues),
+        "iis_available": diagnostics.iis is not None,
+        "iis_valid": bool(diagnostics.iis is not None and diagnostics.iis.valid),
+        "elastic_available": diagnostics.elastic is not None,
+        "conflict_available": diagnostics.conflict is not None,
+        "conflict_irreducible": None if diagnostics.conflict is None else diagnostics.conflict.irreducible,
+        "warnings": tuple(diagnostics.warnings),
+    }
+
+
+def _claims(result: SolveResult) -> tuple[ExplanationClaim, ...]:
+    claims: list[ExplanationClaim] = []
+    validation_valid = bool(result.validation is not None and result.validation.valid and result.x is not None)
+    if validation_valid:
+        claims.append(
+            ExplanationClaim(
+                claim_id="solution.feasibility",
+                kind=ClaimKind.FEASIBILITY,
+                disposition=ClaimDisposition.SUPPORTED,
+                statement="The returned candidate passed SolverPilot's canonical validation.",
+                rationale="A primal candidate exists and ValidationReport.valid is true.",
+                evidence_refs=("result.validation",),
+            )
+        )
+    else:
+        claims.append(
+            ExplanationClaim(
+                claim_id="solution.feasibility",
+                kind=ClaimKind.FEASIBILITY,
+                disposition=ClaimDisposition.BLOCKED,
+                statement="A validated feasible candidate cannot be claimed from this result.",
+                rationale="No primal candidate passed SolverPilot's canonical validation.",
+                evidence_refs=("result.validation",),
+            )
+        )
+
+    evidence = result.optimality_evidence
+    if evidence.independently_verified_optimal:
+        claims.append(
+            ExplanationClaim(
+                claim_id="solution.optimality",
+                kind=ClaimKind.OPTIMALITY,
+                disposition=ClaimDisposition.SUPPORTED,
+                statement="Optimality satisfied SolverPilot's available independent optimality checks.",
+                rationale="Primal validation, dual verification, and a verified gap or certificate are all present.",
+                evidence_refs=("result.optimality_evidence",),
+                qualifiers=("The scope of verification is limited to the checks represented by OptimalityEvidence.",),
+            )
+        )
+    elif result.status is PublicStatus.VALID_OPTIMAL and evidence.backend_reported_optimal and evidence.primal_validated:
+        claims.append(
+            ExplanationClaim(
+                claim_id="solution.optimality",
+                kind=ClaimKind.OPTIMALITY,
+                disposition=ClaimDisposition.QUALIFIED,
+                statement="The backend reported optimality and the primal candidate passed canonical validation.",
+                rationale="SolverPilot did not independently reconstruct all optimality conditions required by OptimalityEvidence.",
+                evidence_refs=("result.optimality_evidence", "result.validation"),
+                qualifiers=("Do not describe this as independently proven optimal.",),
+            )
+        )
+    else:
+        claims.append(
+            ExplanationClaim(
+                claim_id="solution.optimality",
+                kind=ClaimKind.OPTIMALITY,
+                disposition=ClaimDisposition.BLOCKED,
+                statement="Optimality is not established by this result.",
+                rationale="The result does not carry sufficient optimality evidence.",
+                evidence_refs=("result.optimality_evidence",),
+            )
+        )
+
+    if result.status is PublicStatus.INFEASIBLE:
+        confirmed = bool(result.diagnostics is not None and result.diagnostics.confirmed_infeasible)
+        claims.append(
+            ExplanationClaim(
+                claim_id="solution.infeasibility",
+                kind=ClaimKind.INFEASIBILITY,
+                disposition=ClaimDisposition.SUPPORTED if confirmed else ClaimDisposition.QUALIFIED,
+                statement=(
+                    "SolverPilot diagnostics additionally confirmed infeasibility for the supplied model."
+                    if confirmed
+                    else "The backend reported the supplied model infeasible."
+                ),
+                rationale=(
+                    "InfeasibilityReport.confirmed_infeasible is true."
+                    if confirmed
+                    else "No independent SolverPilot diagnostic confirmation is attached to this SolveResult."
+                ),
+                evidence_refs=("result.diagnostics", "result.backend_status") if confirmed else ("result.backend_status",),
+                qualifiers=(
+                    "The claim is limited to the supplied mathematical model and data; it is not a statement about an external real-world process.",
+                ),
+            )
+        )
+    else:
+        claims.append(
+            ExplanationClaim(
+                claim_id="solution.infeasibility",
+                kind=ClaimKind.INFEASIBILITY,
+                disposition=ClaimDisposition.BLOCKED,
+                statement="Infeasibility is not established by this result.",
+                rationale=f"Public status is {result.status.value!r}, not 'infeasible'.",
+                evidence_refs=("result.status",),
+            )
+        )
+
+    if result.status is PublicStatus.UNBOUNDED:
+        claims.append(
+            ExplanationClaim(
+                claim_id="solution.unboundedness",
+                kind=ClaimKind.UNBOUNDEDNESS,
+                disposition=ClaimDisposition.QUALIFIED,
+                statement="The backend reported the supplied model unbounded.",
+                rationale="SolverPilot currently exposes no general independent unboundedness-proof field on SolveResult.",
+                evidence_refs=("result.backend_status",),
+                qualifiers=("Do not describe this as independently proven unbounded from SolveResult alone.",),
+            )
+        )
+    else:
+        claims.append(
+            ExplanationClaim(
+                claim_id="solution.unboundedness",
+                kind=ClaimKind.UNBOUNDEDNESS,
+                disposition=ClaimDisposition.BLOCKED,
+                statement="Unboundedness is not established by this result.",
+                rationale=f"Public status is {result.status.value!r}, not 'unbounded'.",
+                evidence_refs=("result.status",),
+            )
+        )
+
+    if result.plan is not None:
+        claims.append(
+            ExplanationClaim(
+                claim_id="routing.selection",
+                kind=ClaimKind.PLANNER_SELECTION,
+                disposition=ClaimDisposition.SUPPORTED,
+                statement=f"SolverPilot's planner selected backend {result.plan.selected_backend!r}.",
+                rationale="The selection is recorded in SolvePlan.",
+                evidence_refs=("result.plan",),
+                qualifiers=("Planner selection is not, by itself, evidence that this backend is globally fastest or superior.",),
+            )
+        )
+
+    if result.trace.reuse_applied is True:
+        claims.append(
+            ExplanationClaim(
+                claim_id="runtime.reuse",
+                kind=ClaimKind.REOPTIMIZATION,
+                disposition=ClaimDisposition.SUPPORTED,
+                statement="The recorded solve reused prior solver state.",
+                rationale="SolveTrace.reuse_applied is true.",
+                evidence_refs=("result.trace",),
+                qualifiers=("State reuse does not by itself establish a performance improvement.",),
+            )
+        )
+
+    return tuple(claims)
+
+
+def _warnings(result: SolveResult) -> tuple[str, ...]:
+    values: list[str] = []
+    if result.validation is not None:
+        values.extend(str(x) for x in result.validation.warnings)
+    values.extend(str(x) for x in result.trace.warnings)
+    if result.diagnostics is not None:
+        values.extend(str(x) for x in result.diagnostics.warnings)
+    # Preserve order while removing duplicates.
+    return tuple(dict.fromkeys(values))
+
+
+def explain_result(result: SolveResult) -> ExplanationReport:
+    if not isinstance(result, SolveResult):
+        raise TypeError("explain_result expects a SolveResult")
+    optimality = _optimality_payload(result)
+    independently_verified = optimality["independently_verified_optimal"]
+    if result.status is PublicStatus.VALID_OPTIMAL:
+        summary = (
+            "A validated candidate was returned and optimality passed SolverPilot's available independent checks."
+            if independently_verified
+            else "A validated candidate was returned; the backend reported optimality, but complete independent optimality verification is not available."
+        )
+    elif result.status in {PublicStatus.VALID_FEASIBLE, PublicStatus.FEASIBLE_LIMIT}:
+        summary = "A validated feasible candidate was returned without an independent optimality claim."
+    elif result.status is PublicStatus.INFEASIBLE:
+        summary = (
+            "The model was reported infeasible and SolverPilot diagnostics additionally confirmed infeasibility."
+            if result.diagnostics is not None and result.diagnostics.confirmed_infeasible
+            else "The backend reported the supplied model infeasible; no additional SolverPilot confirmation is attached."
+        )
+    elif result.status is PublicStatus.INVALID_SOLUTION:
+        summary = "The backend returned a candidate that failed SolverPilot's canonical validation."
+    else:
+        summary = f"The solve terminated with public status {result.status.value!r}."
+
+    return ExplanationReport(
+        status=result.status.value,
+        summary=summary,
+        status_explanation=explain_status(result.status),
+        problem_class=result.trace.problem_class,
+        backend=result.trace.backend,
+        backend_version=result.trace.backend_version,
+        objective=result.objective,
+        validation=_validation_payload(result),
+        optimality=optimality,
+        planner=_planner_payload(result),
+        runtime=_runtime_payload(result),
+        diagnostics=_diagnostics_payload(result),
+        claims=_claims(result),
+        warnings=_warnings(result),
+    )

solverpilot/reporting/model.py

@@ -0,0 +1,264 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+from solverpilot.io.hashing import deep_freeze_json, deep_thaw_json
+
+
+REPORT_SCHEMA_VERSION = "0.1"
+
+
+class ClaimKind(str, Enum):
+    FEASIBILITY = "feasibility"
+    OPTIMALITY = "optimality"
+    INFEASIBILITY = "infeasibility"
+    UNBOUNDEDNESS = "unboundedness"
+    PLANNER_SELECTION = "planner_selection"
+    REOPTIMIZATION = "reoptimization"
+
+
+class ClaimDisposition(str, Enum):
+    SUPPORTED = "supported"
+    QUALIFIED = "qualified"
+    BLOCKED = "blocked"
+
+
+def _nonempty_text(value: object, field_name: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{field_name} must be a non-empty string")
+    return value.strip()
+
+
+def _tuple_text(values: Sequence[str], field_name: str) -> tuple[str, ...]:
+    if isinstance(values, (str, bytes, bytearray)):
+        raise ValueError(f"{field_name} must be a sequence of strings, not a string")
+    try:
+        normalized = tuple(_nonempty_text(value, field_name) for value in values)
+    except TypeError as exc:
+        raise ValueError(f"{field_name} must be a sequence of strings") from exc
+    return normalized
+
+
+def _freeze_mapping(value: Mapping[str, Any] | None, field_name: str) -> Mapping[str, Any] | None:
+    if value is None:
+        return None
+    if not isinstance(value, Mapping):
+        raise ValueError(f"{field_name} must be a mapping or None")
+    try:
+        frozen = deep_freeze_json(value)
+    except Exception as exc:
+        if "finite" in str(exc).lower():
+            raise ValueError(f"report contains NaN or infinity at $.{field_name}") from exc
+        raise ValueError(f"report is not JSON-safe at $.{field_name}") from exc
+    if not isinstance(frozen, Mapping):
+        raise ValueError(f"{field_name} must form an object")
+    return frozen
+
+
+@dataclass(frozen=True, slots=True)
+class ExplanationClaim:
+    claim_id: str
+    kind: ClaimKind
+    disposition: ClaimDisposition
+    statement: str
+    rationale: str
+    evidence_refs: tuple[str, ...] = ()
+    qualifiers: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        claim_id = _nonempty_text(self.claim_id, "claim_id")
+        statement = _nonempty_text(self.statement, "statement")
+        rationale = _nonempty_text(self.rationale, "rationale")
+        try:
+            kind = self.kind if isinstance(self.kind, ClaimKind) else ClaimKind(str(self.kind).strip().lower())
+        except ValueError as exc:
+            raise ValueError("kind must be a supported ClaimKind") from exc
+        try:
+            disposition = (
+                self.disposition
+                if isinstance(self.disposition, ClaimDisposition)
+                else ClaimDisposition(str(self.disposition).strip().lower())
+            )
+        except ValueError as exc:
+            raise ValueError("disposition must be a supported ClaimDisposition") from exc
+        evidence_refs = _tuple_text(self.evidence_refs, "evidence_refs")
+        qualifiers = _tuple_text(self.qualifiers, "qualifiers")
+        if len(set(evidence_refs)) != len(evidence_refs):
+            raise ValueError("evidence_refs must not contain duplicates")
+        object.__setattr__(self, "claim_id", claim_id)
+        object.__setattr__(self, "kind", kind)
+        object.__setattr__(self, "disposition", disposition)
+        object.__setattr__(self, "statement", statement)
+        object.__setattr__(self, "rationale", rationale)
+        object.__setattr__(self, "evidence_refs", evidence_refs)
+        object.__setattr__(self, "qualifiers", qualifiers)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "claim_id": self.claim_id,
+            "kind": self.kind.value,
+            "disposition": self.disposition.value,
+            "statement": self.statement,
+            "rationale": self.rationale,
+            "evidence_refs": list(self.evidence_refs),
+            "qualifiers": list(self.qualifiers),
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ExplanationReport:
+    status: str
+    summary: str
+    status_explanation: str
+    problem_class: str
+    backend: str | None
+    backend_version: str | None
+    objective: float | None
+    validation: Mapping[str, Any] | None
+    optimality: Mapping[str, Any]
+    planner: Mapping[str, Any] | None
+    runtime: Mapping[str, Any]
+    diagnostics: Mapping[str, Any] | None
+    claims: tuple[ExplanationClaim, ...]
+    warnings: tuple[str, ...] = ()
+    schema_version: str = REPORT_SCHEMA_VERSION
+
+    def __post_init__(self) -> None:
+        status = _nonempty_text(self.status, "status")
+        summary = _nonempty_text(self.summary, "summary")
+        status_explanation = _nonempty_text(self.status_explanation, "status_explanation")
+        problem_class = _nonempty_text(self.problem_class, "problem_class")
+        backend = None if self.backend is None else _nonempty_text(self.backend, "backend")
+        backend_version = None if self.backend_version is None else _nonempty_text(self.backend_version, "backend_version")
+        if self.schema_version != REPORT_SCHEMA_VERSION:
+            raise ValueError(f"schema_version must be {REPORT_SCHEMA_VERSION!r}")
+        if self.objective is not None:
+            import math
+
+            if isinstance(self.objective, bool) or type(self.objective) not in (int, float) or not math.isfinite(float(self.objective)):
+                raise ValueError("report contains NaN or infinity at $.objective")
+            objective: float | None = float(self.objective)
+        else:
+            objective = None
+        validation = _freeze_mapping(self.validation, "validation")
+        optimality = _freeze_mapping(self.optimality, "optimality")
+        planner = _freeze_mapping(self.planner, "planner")
+        runtime = _freeze_mapping(self.runtime, "runtime")
+        diagnostics = _freeze_mapping(self.diagnostics, "diagnostics")
+        if optimality is None or runtime is None:
+            raise ValueError("optimality and runtime must be mappings")
+        claims = tuple(self.claims)
+        if any(not isinstance(claim, ExplanationClaim) for claim in claims):
+            raise ValueError("claims must contain ExplanationClaim objects")
+        warnings = _tuple_text(self.warnings, "warnings")
+        ids = [claim.claim_id for claim in claims]
+        if len(ids) != len(set(ids)):
+            raise ValueError("claim IDs must be unique")
+        object.__setattr__(self, "status", status)
+        object.__setattr__(self, "summary", summary)
+        object.__setattr__(self, "status_explanation", status_explanation)
+        object.__setattr__(self, "problem_class", problem_class)
+        object.__setattr__(self, "backend", backend)
+        object.__setattr__(self, "backend_version", backend_version)
+        object.__setattr__(self, "objective", objective)
+        object.__setattr__(self, "validation", validation)
+        object.__setattr__(self, "optimality", optimality)
+        object.__setattr__(self, "planner", planner)
+        object.__setattr__(self, "runtime", runtime)
+        object.__setattr__(self, "diagnostics", diagnostics)
+        object.__setattr__(self, "claims", claims)
+        object.__setattr__(self, "warnings", warnings)
+        _validate_claim_evidence_refs(claims)
+        if not self.claim_safe:
+            raise ValueError("ExplanationReport contains a supported claim that is not authorized by structured evidence")
+        _assert_json_safe(self.to_dict())
+
+    @property
+    def claim_safe(self) -> bool:
+        for claim in self.claims:
+            if claim.disposition is not ClaimDisposition.SUPPORTED:
+                continue
+            if claim.kind is ClaimKind.FEASIBILITY:
+                if not (isinstance(self.validation, Mapping) and self.validation.get("valid") is True):
+                    return False
+            elif claim.kind is ClaimKind.OPTIMALITY:
+                if self.optimality.get("independently_verified_optimal") is not True:
+                    return False
+            elif claim.kind is ClaimKind.INFEASIBILITY:
+                if not (isinstance(self.diagnostics, Mapping) and self.diagnostics.get("confirmed_infeasible") is True):
+                    return False
+            elif claim.kind is ClaimKind.UNBOUNDEDNESS:
+                # S5/S10 has no generic independent unboundedness-proof field.
+                return False
+            elif claim.kind is ClaimKind.PLANNER_SELECTION:
+                if self.planner is None:
+                    return False
+            elif claim.kind is ClaimKind.REOPTIMIZATION:
+                if self.runtime.get("reuse_applied") is not True:
+                    return False
+        return True
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = {
+            "status": self.status,
+            "summary": self.summary,
+            "status_explanation": self.status_explanation,
+            "problem_class": self.problem_class,
+            "backend": self.backend,
+            "backend_version": self.backend_version,
+            "objective": self.objective,
+            "validation": None if self.validation is None else deep_thaw_json(self.validation),
+            "optimality": deep_thaw_json(self.optimality),
+            "planner": None if self.planner is None else deep_thaw_json(self.planner),
+            "runtime": deep_thaw_json(self.runtime),
+            "diagnostics": None if self.diagnostics is None else deep_thaw_json(self.diagnostics),
+            "claims": [claim.to_dict() for claim in self.claims],
+            "warnings": list(self.warnings),
+            "schema_version": self.schema_version,
+        }
+        _assert_json_safe(payload)
+        if not self.claim_safe:
+            raise ValueError("ExplanationReport no longer satisfies claim-safety invariants")
+        return payload
+
+
+def _assert_json_safe(value: Any, *, path: str = "$") -> None:
+    import math
+
+    if value is None or isinstance(value, (str, bool, int)):
+        return
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise ValueError(f"report contains NaN or infinity at {path}")
+        return
+    if isinstance(value, (tuple, list)):
+        for index, item in enumerate(value):
+            _assert_json_safe(item, path=f"{path}[{index}]")
+        return
+    if isinstance(value, Mapping):
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise ValueError(f"report mapping keys must be strings at {path}")
+            _assert_json_safe(item, path=f"{path}.{key}")
+        return
+    raise ValueError(f"report is not JSON-safe at {path}: {type(value).__name__}")
+
+
+_KNOWN_EVIDENCE_REFS = frozenset({
+    "result.status",
+    "result.validation",
+    "result.optimality_evidence",
+    "result.backend_status",
+    "result.diagnostics",
+    "result.plan",
+    "result.trace",
+})
+
+
+def _validate_claim_evidence_refs(claims: tuple[ExplanationClaim, ...]) -> None:
+    unknown = sorted({ref for claim in claims for ref in claim.evidence_refs if ref not in _KNOWN_EVIDENCE_REFS})
+    if unknown:
+        raise ValueError(f"claims contain unknown evidence references: {unknown}")

solverpilot/reporting/render.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import html
+import json
+
+from .model import ExplanationReport
+
+
+def render_json(report: ExplanationReport, *, indent: int | None = 2) -> str:
+    if not isinstance(report, ExplanationReport):
+        raise TypeError("render_json expects an ExplanationReport")
+    if not report.claim_safe:
+        raise ValueError("refusing to render an explanation report that violates claim-safety invariants")
+    return json.dumps(report.to_dict(), ensure_ascii=False, sort_keys=True, indent=indent, allow_nan=False)
+
+
+def _md(value: object) -> str:
+    text = html.escape(str(value), quote=False)
+    return text.replace("|", "\\|").replace("\r", " ").replace("\n", " ")
+
+
+def render_markdown(report: ExplanationReport) -> str:
+    if not isinstance(report, ExplanationReport):
+        raise TypeError("render_markdown expects an ExplanationReport")
+    if not report.claim_safe:
+        raise ValueError("refusing to render an explanation report that violates claim-safety invariants")
+    lines = [
+        "# SolverPilot explanation",
+        "",
+        f"**Status:** `{_md(report.status)}`",
+        f"**Problem class:** `{_md(report.problem_class)}`",
+        f"**Backend:** `{_md(report.backend if report.backend is not None else 'unknown')}`",
+        f"**Objective:** `{_md(report.objective if report.objective is not None else 'not available')}`",
+        "",
+        "## Summary",
+        _md(report.summary),
+        "",
+        "## Status interpretation",
+        _md(report.status_explanation),
+        "",
+        "## Claims",
+        "| Claim | Disposition | Statement |",
+        "| --- | --- | --- |",
+    ]
+    for claim in report.claims:
+        lines.append(
+            f"| `{_md(claim.claim_id)}` | `{_md(claim.disposition.value)}` | {_md(claim.statement)} |"
+        )
+        if claim.qualifiers:
+            for qualifier in claim.qualifiers:
+                lines.append(f"  - **Qualifier:** {_md(qualifier)}")
+    if report.warnings:
+        lines.extend(["", "## Warnings"])
+        lines.extend(f"- {_md(warning)}" for warning in report.warnings)
+    return "\n".join(lines) + "\n"

solverpilot/runtime/__init__.py

@@ -0,0 +1,19 @@
+from .auto import builtin_backend_candidates, default_registry, solve, solve_production
+from .budgeting import apply_budget
+from .executor import execute
+from .portfolio import PortfolioAttempt, PortfolioSolveResult, execute_portfolio
+from .result import OptimalityEvidence, SolveResult
+
+__all__ = [
+    "PortfolioAttempt",
+    "PortfolioSolveResult",
+    "SolveResult",
+    "OptimalityEvidence",
+    "apply_budget",
+    "builtin_backend_candidates",
+    "default_registry",
+    "execute",
+    "execute_portfolio",
+    "solve",
+    "solve_production",
+]