dfshrink 0.1.0__py3-none-any.whl

dfshrink/__init__.py

@@ -0,0 +1,31 @@
+"""dfshrink -- fail-fast data tooling for Polars."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from dfshrink.columns import ColumnReduction, minimize_columns
+from dfshrink.failure import Diagnosis, Explainer, Failure
+from dfshrink.shrink import DEFAULT_MAX_EVALS, FailPredicate, Repro, shrink_rows
+from dfshrink.values import Direction, ValueReduction, direction_for_rule, minimize_values
+
+try:
+    __version__ = version("dfshrink")
+except PackageNotFoundError:  # pragma: no cover - only when run from a source tree
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "DEFAULT_MAX_EVALS",
+    "ColumnReduction",
+    "Diagnosis",
+    "Direction",
+    "Explainer",
+    "FailPredicate",
+    "Failure",
+    "Repro",
+    "ValueReduction",
+    "direction_for_rule",
+    "minimize_columns",
+    "minimize_values",
+    "shrink_rows",
+]

dfshrink/_render.py

@@ -0,0 +1,198 @@
+"""Render a repro as pasteable code, a markdown table, or a failure line.
+
+:meth:`dfshrink.Repro.to_code` and :meth:`dfshrink.Repro.to_markdown` are the
+public entry points; this module holds the formatting so :mod:`dfshrink.shrink`
+stays about the algorithm.  :func:`render_diagnosis_markdown` folds the
+:class:`~dfshrink.Failure` into the same report, so a ticket reads *why* a frame
+failed and shows the row that does it.
+
+Rendering is **lossless or loud**: :func:`render_code` rebuilds the frame from
+the data and schema it is about to print and panics when the rebuild does not
+equal the original.  A dtype whose values cannot be written as Python literals
+(a column of :class:`polars.Object`, say) raises instead of emitting code that
+would silently build a different frame.
+"""
+
+from __future__ import annotations
+
+import datetime
+import math
+from decimal import Decimal
+from typing import TYPE_CHECKING, Any
+
+import polars as pl
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from dfshrink.failure import Diagnosis, Failure
+
+
+def render_code(frame: pl.DataFrame) -> str:
+    """Return a pasteable ``pl.DataFrame(...)`` constructor for ``frame``.
+
+    Postcondition: ``eval(render_code(frame))`` -- with only ``polars as pl`` in
+    scope -- is a :class:`polars.DataFrame` equal to ``frame``.  A dtype that
+    cannot be rendered without loss raises ``TypeError`` rather than emitting
+    code that builds a different frame.
+    """
+    data: dict[str, list[Any]] = {}
+    dtypes: dict[str, pl.DataType] = {}
+    values: list[str] = []
+    schema: list[str] = []
+    for name, series in zip(frame.columns, frame.iter_columns(), strict=True):
+        ready = _ready_values(series)
+        try:
+            rendered = _render_values(ready)
+        except TypeError as exc:
+            msg = f"cannot render column {name!r} as code: {exc}"
+            raise TypeError(msg) from exc
+        data[name] = ready
+        dtypes[name] = series.dtype
+        values.append(f"{name!r}: {rendered}")
+        schema.append(f"{name!r}: {_render_dtype(series.dtype)}")
+
+    _verify_round_trip(frame, data, dtypes)
+    return f"pl.DataFrame(\n    {{{', '.join(values)}}},\n    schema={{{', '.join(schema)}}},\n)"
+
+
+def render_markdown(frame: pl.DataFrame) -> str:
+    """Return ``frame`` as a GitHub-flavoured markdown table.
+
+    Each header carries the column's dtype (``amount (Int64)``), so the table
+    documents the schema as well as the values.
+    """
+    headers = [f"{name} ({dtype})" for name, dtype in frame.schema.items()]
+    lines = [
+        f"| {' | '.join(headers)} |",
+        f"| {' | '.join('---' for _ in headers)} |",
+        *(f"| {' | '.join(_render_cell(value) for value in row)} |" for row in frame.iter_rows()),
+    ]
+    return "\n".join(lines)
+
+
+def describe_failure(failure: Failure | None) -> str:
+    """A short phrase naming the failing rule and column, for a summary line."""
+    if failure is None:
+        return "no failure metadata"
+    rule, column = failure.rule, failure.column
+    if column is not None and rule is not None:
+        return f"column {column!r} fails rule {rule!r}"
+    if column is not None:
+        return f"column {column!r} fails"
+    if rule is not None:
+        return f"rule {rule!r} fails"
+    return "validation failed"
+
+
+def render_diagnosis_markdown(diagnosis: Diagnosis) -> str:
+    """A ticket-ready report: why the frame failed, then the minimal repro."""
+    failure = diagnosis.failure
+    lines = [f"Validation failed: {describe_failure(failure)}."]
+    if failure is not None and failure.message:
+        lines += ["", *(f"> {line}" for line in failure.message.splitlines())]
+    lines += ["", "Minimal repro:", "", render_markdown(diagnosis.repro.frame)]
+    return "\n".join(lines)
+
+
+def _ready_values(series: pl.Series) -> list[Any]:
+    """The series' values, as the literals :func:`pl.DataFrame` rebuilds from.
+
+    This is the same data the emitted code carries, so the round-trip check in
+    :func:`_verify_round_trip` exercises exactly what ``to_code`` prints.
+    Datetime and Duration columns become integer counts in the dtype's own
+    unit, which is exact at every unit -- Python datetimes only carry
+    microseconds, so a nanosecond column would otherwise lose precision.
+    """
+    if isinstance(series.dtype, (pl.Datetime, pl.Duration)):
+        return series.cast(pl.Int64).to_list()
+    return [_to_literal(value, series.dtype) for value in series.to_list()]
+
+
+def _to_literal(value: Any, dtype: Any) -> Any:
+    """Rewrite one value into the literal form ``dtype`` rebuilds it from."""
+    if value is None:
+        return None
+    if isinstance(dtype, (pl.List, pl.Array)):
+        return [_to_literal(item, dtype.inner) for item in value]
+    if isinstance(dtype, pl.Struct):
+        fields = {field.name: field.dtype for field in dtype.fields}
+        return {key: _to_literal(item, fields.get(key)) for key, item in value.items()}
+    if isinstance(dtype, (pl.Date, pl.Time)) or isinstance(value, (datetime.date, datetime.time)):
+        return value.isoformat()
+    if isinstance(dtype, pl.Decimal) or isinstance(value, Decimal):
+        return str(value)
+    if isinstance(value, datetime.timedelta):
+        return value / datetime.timedelta(microseconds=1)
+    return value
+
+
+def _render_values(values: Sequence[Any]) -> str:
+    return f"[{', '.join(_render_value(value) for value in values)}]"
+
+
+def _render_value(value: Any) -> str:
+    """A Python literal for a value already reduced by :func:`_to_literal`."""
+    if value is None or isinstance(value, (bool, int, str, bytes)):
+        return repr(value)
+    if isinstance(value, float):
+        if math.isnan(value):
+            return "float('nan')"
+        if math.isinf(value):
+            return "float('inf')" if value > 0 else "float('-inf')"
+        return repr(value)
+    if isinstance(value, (list, tuple)):
+        return f"[{', '.join(_render_value(item) for item in value)}]"
+    if isinstance(value, dict):
+        items = ", ".join(f"{_render_value(k)}: {_render_value(v)}" for k, v in value.items())
+        return f"{{{items}}}"
+    msg = f"cannot render value of type {type(value).__name__!r} as code"
+    raise TypeError(msg)
+
+
+def _render_dtype(dtype: Any) -> str:
+    """A ``pl.<Dtype>(...)`` expression that reconstructs ``dtype`` exactly."""
+    if isinstance(dtype, pl.List):
+        return f"pl.List({_render_dtype(dtype.inner)})"
+    if isinstance(dtype, pl.Array):
+        return f"pl.Array({_render_dtype(dtype.inner)}, {dtype.size})"
+    if isinstance(dtype, pl.Struct):
+        fields = ", ".join(
+            f"{field.name!r}: {_render_dtype(field.dtype)}" for field in dtype.fields
+        )
+        return f"pl.Struct({{{fields}}})"
+    if isinstance(dtype, pl.Datetime):
+        if dtype.time_zone is None:
+            return f"pl.Datetime(time_unit={dtype.time_unit!r})"
+        return f"pl.Datetime(time_unit={dtype.time_unit!r}, time_zone={dtype.time_zone!r})"
+    if isinstance(dtype, pl.Duration):
+        return f"pl.Duration(time_unit={dtype.time_unit!r})"
+    if isinstance(dtype, pl.Decimal):
+        return f"pl.Decimal(precision={dtype.precision}, scale={dtype.scale})"
+    if isinstance(dtype, pl.Enum):
+        return f"pl.Enum({dtype.categories.to_list()!r})"
+    return f"pl.{dtype.base_type()}"
+
+
+def _render_cell(value: Any) -> str:
+    if value is None:
+        return "null"
+    if isinstance(value, float) and (math.isnan(value) or math.isinf(value)):
+        return _render_value(value)
+    text = value if isinstance(value, str) else str(value)
+    return text.replace("\\", "\\\\").replace("|", "\\|").replace("\n", "<br>")
+
+
+def _verify_round_trip(
+    frame: pl.DataFrame,
+    data: dict[str, list[Any]],
+    dtypes: dict[str, pl.DataType],
+) -> None:
+    """Postcondition check: the data and schema we print rebuild ``frame``."""
+    msg = f"to_code cannot render this frame without loss; columns: {dict(frame.schema)}"
+    try:
+        rebuilt = pl.DataFrame(data, schema=dtypes)
+    except Exception as exc:  # one vocabulary for any rebuild failure
+        raise TypeError(msg) from exc
+    if not rebuilt.equals(frame):
+        raise TypeError(msg)

dfshrink/columns.py

@@ -0,0 +1,240 @@
+"""Drop the columns a failing frame does not need to keep failing.
+
+:func:`dfshrink.shrink_rows` minimizes *rows*; :func:`dfshrink.minimize_values`
+moves *values*; :func:`minimize_columns` removes whole *columns*.  The result is
+the same failure on the narrowest frame: a schema that flags ``amount`` on a
+frame carrying a debug column reduces to the columns the rule actually reads.
+
+Column reduction is **schema-aware**, because a black-box ``DataFrame -> bool``
+predicate cannot tell "still fails for the original reason" from "now fails
+because a column went missing".  So the caller passes the adapter's *explainer*
+(``as_failure(schema)``); a candidate column subset is accepted only while the
+explainer still names the same rule and column.  That is the contract: the
+frame must keep failing **for the same reason**, not merely keep failing.
+
+The "frame must already match the schema's columns and dtypes" precondition
+relaxes here: the reducer may **drop** columns, but never changes a kept
+column's dtype.  ``minimality_proven`` spans two dimensions and both are
+reported: :attr:`ColumnReduction.proven` is the column dimension, and
+``repro.minimality_proven`` is the row dimension, re-checked against the
+preserved reason so a column drop cannot make an inherited flag a lie.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING, override
+
+from dfshrink.failure import Diagnosis, Explainer, Failure
+from dfshrink.shrink import DEFAULT_MAX_EVALS, Repro, _split, _without_row
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    import polars as pl
+
+__all__ = ["ColumnReduction", "minimize_columns"]
+
+
+class _Exhausted:
+    """Sentinel: the explainer budget is spent, so the reason is unknown."""
+
+
+_EXHAUSTED = _Exhausted()
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class ColumnReduction:
+    """A repro with the columns no failing rule needed removed.
+
+    ``eq=False`` for the same reason as :class:`dfshrink.Repro`: a
+    :class:`polars.DataFrame` field would otherwise compare element-wise.
+    """
+
+    repro: Repro
+    """The column-reduced repro.  Its frame still fails for ``failure``'s reason,
+    with the kept columns' dtypes and row order unchanged.  Its
+    ``minimality_proven`` is the *row* dimension re-checked for that reason --
+    not for the whole schema, which the reduced frame may no longer satisfy."""
+
+    failure: Failure
+    """The failure preserved across the reduction -- the reason the reduced
+    frame still fails."""
+
+    dropped_columns: tuple[str, ...]
+    """The removed column names, in original frame order."""
+
+    proven: bool
+    """``True`` iff the kept column set is 1-minimal for the preserved reason:
+    dropping any single remaining column changes or removes that reason."""
+
+    predicate_calls: int
+    """Explainer calls the column search spent (row shrinking did its own)."""
+
+    @override
+    def __repr__(self) -> str:
+        """A compact repr: dropped count, width, and the proof flag."""
+        state = "proven" if self.proven else "not proven"
+        return (
+            f"ColumnReduction(dropped={len(self.dropped_columns)}, "
+            f"columns_left={self.repro.frame.width}, {state}, calls={self.predicate_calls})"
+        )
+
+
+def minimize_columns(
+    source: Repro | Diagnosis,
+    explain: Explainer,
+    *,
+    max_evals: int = DEFAULT_MAX_EVALS,
+) -> ColumnReduction:
+    """Remove every column the failing frame does not need to keep failing.
+
+    ``explain`` is the adapter's failure explainer (``as_failure(schema)``):
+    ``DataFrame -> Failure | None``.  ``source`` may be a
+    :class:`~dfshrink.Diagnosis` or a bare :class:`~dfshrink.Repro`; its rows are
+    kept and its frame defines the candidate columns.
+
+    Contract:
+
+    * Preconditions -- caller's bug, so panic: ``max_evals >= 1``; a source
+      frame that fails; a failure the explainer can *name* (a structural
+      failure with no rule is refused, because nothing can be preserved).
+    * Postcondition: ``repro.frame`` is a column-subset of the input, keeps the
+      input's rows and every kept column's dtype, and still fails for the
+      preserved reason.
+    * Expected failures, returned as values: an exhausted search budget returns
+      the frame untouched with ``proven=False``; it never guesses.
+
+    The search is ddmin over columns, so it reaches 1-minimality in roughly
+    ``O(k log k)`` explainer calls for ``k`` columns.  A column is removed only
+    while ``explain`` still reports the *same* rule and column; a drop that
+    merely breaks the frame some other way (a missing required column) is
+    rejected.  The column search gets its own ``max_evals`` budget; naming the
+    source reason is setup and always fits (``max_evals >= 1``).
+    """
+    if max_evals < 1:
+        msg = f"max_evals must be >= 1, got {max_evals}"
+        raise ValueError(msg)
+
+    repro = source.repro if isinstance(source, Diagnosis) else source
+    frame = repro.frame
+
+    tracker = _ReasonTracker(frame, explain, max_evals)
+    baseline = tracker.explain(frame)
+    assert not isinstance(baseline, _Exhausted), "max_evals >= 1 leaves room for the baseline"
+    if baseline is None:
+        msg = "minimize_columns needs a failing frame; the source repro passes"
+        raise ValueError(msg)
+    if baseline.rule is None:
+        msg = (
+            "minimize_columns needs a named failing rule; the validator reported a "
+            "structural failure (missing column or wrong dtype) with no rule to preserve"
+        )
+        raise ValueError(msg)
+
+    current = tuple(range(frame.width))
+    tracker.last_true = current
+    if frame.width >= 2:
+        n = 2
+        while len(current) >= 2 and not tracker.exhausted:
+            reduced, n = _reduce_once(tracker, current, n, baseline)
+            if reduced is not None:
+                current = reduced
+                continue
+            if n >= len(current):
+                break
+            n = min(len(current), 2 * n)
+    assert current == tracker.last_true, "postcondition: reduced columns must still fail"
+
+    reduced_frame = frame.select([frame.columns[i] for i in current])
+    rows_proven = repro.minimality_proven and _rows_minimal(reduced_frame, tracker, baseline)
+    dropped = tuple(name for i, name in enumerate(frame.columns) if i not in set(current))
+    return ColumnReduction(
+        repro=replace(repro, frame=reduced_frame, minimality_proven=rows_proven),
+        failure=baseline,
+        dropped_columns=dropped,
+        proven=frame.width < 2 or not tracker.exhausted,
+        predicate_calls=tracker.calls,
+    )
+
+
+def _reduce_once(
+    tracker: _ReasonTracker,
+    current: tuple[int, ...],
+    n: int,
+    reason: Failure,
+) -> tuple[tuple[int, ...] | None, int]:
+    """One ddmin step over columns: prefer a same-reason chunk, then a complement.
+
+    Returns the reduced index tuple (or ``None`` when neither a chunk nor a
+    complement keeps the reason) and the chunk count to use next.
+    """
+    chunks = _split(current, n)
+    for _, _, chunk in chunks:
+        if tracker.holds_on(chunk, reason) is True:
+            return chunk, 2
+    for start, stop, _ in chunks:
+        complement = current[:start] + current[stop:]
+        if complement and tracker.holds_on(complement, reason) is True:
+            return complement, max(n - 1, 2)
+    return None, n
+
+
+def _rows_minimal(frame: pl.DataFrame, tracker: _ReasonTracker, reason: Failure) -> bool:
+    """Re-check 1-minimality along rows against the preserved reason.
+
+    Mirrors :func:`dfshrink.shrink_rows`: a one-row frame is trivially minimal
+    (the empty candidate is never tested), and a row that can be dropped while
+    the reason survives means the inherited flag is no longer true.  Returns
+    ``False`` when the budget runs out before a row is cleared.
+    """
+    if frame.height < 2:
+        return True
+    for row in range(frame.height):
+        if tracker.same_reason(_without_row(frame, row), reason) is not False:
+            return False
+    return True
+
+
+class _ReasonTracker:
+    """Budgeted explainer that answers "same failing reason?" over column subsets.
+
+    Three-state: :meth:`same_reason` returns ``True`` (same rule and column),
+    ``False`` (a different or absent failure), or ``None`` once the budget is
+    spent.  ``None`` is never read as either side -- the search stops and the
+    result is reported unproven.
+    """
+
+    def __init__(self, frame: pl.DataFrame, explain: Explainer, max_evals: int) -> None:
+        self._frame = frame
+        self._explain = explain
+        self.max_evals = max_evals
+        self.calls = 0
+        self.last_true: tuple[int, ...] | None = None
+
+    @property
+    def exhausted(self) -> bool:
+        """``True`` once no further explainer call may be made."""
+        return self.calls >= self.max_evals
+
+    def explain(self, frame: pl.DataFrame) -> Failure | _Exhausted | None:
+        """Explain ``frame``, or return :data:`_EXHAUSTED` when the budget is spent."""
+        if self.exhausted:
+            return _EXHAUSTED
+        self.calls += 1
+        return self._explain(frame)
+
+    def same_reason(self, frame: pl.DataFrame, reason: Failure) -> bool | None:
+        """Whether ``frame`` still fails for ``reason`` (same rule and column)."""
+        found = self.explain(frame)
+        if isinstance(found, _Exhausted):
+            return None
+        return found is not None and found.rule == reason.rule and found.column == reason.column
+
+    def holds_on(self, columns: Sequence[int], reason: Failure) -> bool | None:
+        """Whether selecting ``columns`` still fails for ``reason``."""
+        candidate = self._frame.select([self._frame.columns[i] for i in columns])
+        outcome = self.same_reason(candidate, reason)
+        if outcome is True:
+            self.last_true = tuple(columns)
+        return outcome

dfshrink/ext/__init__.py

@@ -0,0 +1,20 @@
+"""Per-library adapters that turn validators into failure predicates and explainers.
+
+``dfshrink`` core knows nothing about validators: :func:`dfshrink.shrink_rows`
+takes a plain ``DataFrame -> bool`` predicate.  Each module here owns the
+adapter for one real library, so importing the module is what pulls in that
+library -- the base ``dfshrink`` package never does.
+
+* :mod:`dfshrink.ext.dataframely` -- ``is_valid(df) -> bool`` schemas.
+* :mod:`dfshrink.ext.pandera` -- ``validate(df)``-raises schemas.
+* :mod:`dfshrink.ext.patito` -- ``Model.validate(df)``-raises models.
+
+Use them as::
+
+    from dfshrink.ext.dataframely import shrink_rows, diagnose
+    repro = shrink_rows(df, HouseSchema)
+    found = diagnose(df, HouseSchema)   # repro + why it failed
+
+Each module also exposes :func:`as_predicate` for the raw predicate and
+:func:`as_failure` for the raw ``DataFrame -> Failure | None`` explainer.
+"""

dfshrink/ext/_adapter.py

@@ -0,0 +1,168 @@
+"""Shared plumbing for the per-library adapters in :mod:`dfshrink.ext`.
+
+Every adapter module turns one validator's failure signal into a
+``DataFrame -> bool`` predicate and hands it to :func:`dfshrink.shrink_rows`.
+The predicate is library-specific; the shrink call is not.  Adapters build
+their public ``shrink_rows`` from :func:`make_shrink_rows`, so the wrapper --
+including the keyword-only ``max_evals`` and its default -- is written once and
+cannot drift between libraries.  The same adapters build ``diagnose`` from
+:func:`make_diagnose`: it explains *why* the frame fails (rule, column, invalid
+rows) and shrinks -- using the invalid rows as the starting point when the
+validator reports them, the full frame otherwise.
+
+This module imports no validator library; the adapters own those imports.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+from dfshrink.columns import minimize_columns
+from dfshrink.failure import Diagnosis, Explainer, Failure
+from dfshrink.shrink import (
+    DEFAULT_MAX_EVALS,
+    FailPredicate,
+    Repro,
+    shrink_rows as _shrink_rows,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    import polars as pl
+
+__all__ = [
+    "DEFAULT_MAX_EVALS",
+    "Diagnose",
+    "Diagnosis",
+    "Explainer",
+    "FailPredicate",
+    "Failure",
+    "Repro",
+    "ShrinkRows",
+    "make_diagnose",
+    "make_shrink_rows",
+]
+
+
+class ShrinkRows[SchemaT](Protocol):
+    """A schema-aware :func:`dfshrink.shrink_rows` bound to one library's predicate."""
+
+    def __call__(
+        self,
+        frame: pl.DataFrame,
+        schema: SchemaT,
+        *,
+        max_evals: int = DEFAULT_MAX_EVALS,
+    ) -> Repro | None: ...
+
+
+class Diagnose[SchemaT](Protocol):
+    """A schema-aware :func:`dfshrink.ext.<lib>.diagnose` bound to one library."""
+
+    def __call__(
+        self,
+        frame: pl.DataFrame,
+        schema: SchemaT,
+        *,
+        max_evals: int = DEFAULT_MAX_EVALS,
+        columns: bool = False,
+    ) -> Diagnosis | None: ...
+
+
+def make_shrink_rows[SchemaT](
+    as_predicate: Callable[[SchemaT], FailPredicate],
+) -> ShrinkRows[SchemaT]:
+    """Build the ``shrink_rows(frame, schema, *, max_evals)`` wrapper for an adapter.
+
+    ``as_predicate`` maps a library schema to the failure predicate
+    :func:`dfshrink.shrink_rows` minimizes; the returned callable re-applies it
+    on each invocation.  See :func:`dfshrink.shrink_rows` for the full contract.
+    """
+
+    def shrink_rows(
+        frame: pl.DataFrame,
+        schema: SchemaT,
+        *,
+        max_evals: int = DEFAULT_MAX_EVALS,
+    ) -> Repro | None:
+        """Shrink ``frame`` to a minimal row subset that still fails ``schema``.
+
+        A thin wrapper over :func:`dfshrink.shrink_rows`; see there for the full
+        contract.
+        """
+        return _shrink_rows(frame, as_predicate(schema), max_evals=max_evals)
+
+    return shrink_rows
+
+
+def make_diagnose[SchemaT](
+    as_failure: Callable[[SchemaT], Explainer],
+    as_predicate: Callable[[SchemaT], FailPredicate],
+) -> Diagnose[SchemaT]:
+    """Build the ``diagnose(frame, schema, *, max_evals)`` wrapper for an adapter.
+
+    ``as_failure`` maps a schema to its failure explainer (``DataFrame ->
+    Failure | None``); ``as_predicate`` maps it to the failure predicate
+    :func:`dfshrink.shrink_rows` minimizes.  ``diagnose`` explains first and
+    shrinks second: when the explainer reports the invalid rows, shrinking
+    starts there instead of over the whole frame, so the validator's own
+    failure signal -- not black-box ddmin -- pinpoints the repro.
+
+    Contract (same shape as :func:`dfshrink.shrink_rows`):
+
+    * Preconditions -- caller's bug, so panic: an empty ``frame`` or
+      ``max_evals < 1`` raises ``ValueError``.
+    * Expected failure, returned as a value: a non-failing frame returns
+      ``None``; otherwise a :class:`Diagnosis` whose ``repro`` still fails,
+      has >= 1 row, preserves order, and is 1-minimal when
+      ``minimality_proven`` is ``True``.
+    * A validator that reports a failure the predicate does not reproduce is
+      an adapter bug and panics.
+    * ``columns=True`` removes columns no failing rule needs (see
+      :func:`dfshrink.minimize_columns`), preserving the diagnosed failure; the
+      column search gets its own ``max_evals`` budget.
+    """
+
+    def diagnose(
+        frame: pl.DataFrame,
+        schema: SchemaT,
+        *,
+        max_evals: int = DEFAULT_MAX_EVALS,
+        columns: bool = False,
+    ) -> Diagnosis | None:
+        """Explain and shrink ``frame`` against ``schema``.
+
+        Returns ``None`` when the frame passes, else a :class:`Diagnosis` with
+        the minimal failing repro and the reason it fails (when the validator
+        exposes one).  See :func:`dfshrink.shrink_rows` for the repro contract.
+
+        With ``columns=True`` the repro is additionally reduced along columns
+        via :func:`dfshrink.minimize_columns`, keeping the same failing rule; the
+        column search spends its own ``max_evals`` budget after the row search.
+        """
+        if frame.height < 1:
+            msg = f"frame must have at least one row, got {frame.height}"
+            raise ValueError(msg)
+        if max_evals < 1:
+            msg = f"max_evals must be >= 1, got {max_evals}"
+            raise ValueError(msg)
+
+        explainer = as_failure(schema)
+        failure = explainer(frame)
+        if failure is None:
+            return None
+
+        start = frame if failure.invalid_rows is None else failure.invalid_rows
+        repro = _shrink_rows(start, as_predicate(schema), max_evals=max_evals)
+        assert repro is not None, (
+            "diagnose: the validator reported a failure the predicate does not reproduce"
+        )
+        if columns:
+            reduced = minimize_columns(
+                Diagnosis(repro=repro, failure=failure), explainer, max_evals=max_evals
+            )
+            repro = reduced.repro
+        return Diagnosis(repro=repro, failure=failure)
+
+    return diagnose