cleanframe-engine 0.3.0__py3-none-any.whl

cleanframe/drift.py

@@ -0,0 +1,283 @@
+"""Schema-drift detection: catch the file that came back *different*.
+
+Before replaying a recipe on next month's file, compare that file against the
+recipe's ``source_fingerprint`` and its declared expectations. If a column was
+renamed, a new one appeared, a dtype shifted, or values stopped matching the
+formats the recipe parses, CleanFrame **stops and tells you** instead of silently
+producing garbage — exactly the failure mode that makes hand-cleaning fragile.
+
+Findings carry fuzzy-match suggestions ("94% match to recipe column …") so the fix
+is obvious. By default ``apply_recipe`` / ``cleanframe apply`` **stop** on drift;
+pass ``on_drift="warn"`` / ``--force`` only when you intentionally want to continue.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import pandas as pd
+
+from ._util import best_match, canonicalize_dtype, similarity
+from .errors import CleanFrameError
+from .fingerprint import DEFAULT_SAMPLE_ROWS, fingerprint_dataframe
+from .llm import _sketch
+from .ops import parse_dates_to_datetime
+from .recipe import Recipe
+from .types import Severity
+
+_RENAME_CONFIDENCE = 0.6
+
+
+@dataclass
+class DriftFinding:
+    kind: str
+    message: str
+    severity: Severity = Severity.WARNING
+    column: str | None = None
+    suggestion: str | None = None
+    evidence: dict = field(default_factory=dict)
+
+
+@dataclass
+class DriftReport:
+    findings: list[DriftFinding] = field(default_factory=list)
+    source: str | None = None
+
+    @property
+    def has_drift(self) -> bool:
+        return any(f.severity.rank >= Severity.WARNING.rank for f in self.findings)
+
+    @property
+    def worst(self) -> Severity | None:
+        if not self.findings:
+            return None
+        return max((f.severity for f in self.findings), key=lambda s: s.rank)
+
+    def by_kind(self, kind: str) -> list[DriftFinding]:
+        return [f for f in self.findings if f.kind == kind]
+
+    def render(self) -> str:
+        if not self.findings:
+            where = f" in {self.source}" if self.source else ""
+            return f"✓ No schema drift detected{where}."
+        where = f" in {self.source}" if self.source else ""
+        lines = [f"⚠ Schema drift detected{where}"]
+        for f in self.findings:
+            lines.append(f"  • {f.message}")
+            if f.suggestion:
+                lines.append(f"    ↳ {f.suggestion}")
+        lines.append(
+            "  Run `cleanframe suggest <file> --recipe <recipe.yaml> --update` to review a patch."
+        )
+        return "\n".join(lines)
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return f"DriftReport({len(self.findings)} finding(s), has_drift={self.has_drift})"
+
+
+def detect_drift(df: pd.DataFrame, recipe: Recipe, *, source: str | None = None) -> DriftReport:
+    """Compare an incoming frame against the expectations baked into ``recipe``."""
+    report = DriftReport(source=source)
+    fp = recipe.source_fingerprint or {}
+    if not isinstance(fp, dict):
+        raise CleanFrameError(
+            f"recipe source_fingerprint must be a mapping, got {type(fp).__name__}."
+        )
+    raw_cols = fp.get("column_names") or []
+    if not isinstance(raw_cols, (list, tuple)):
+        raise CleanFrameError("recipe source_fingerprint.column_names must be a list.")
+    raw_dtypes = fp.get("dtypes") or {}
+    if not isinstance(raw_dtypes, dict):
+        raise CleanFrameError("recipe source_fingerprint.dtypes must be a mapping.")
+    expected_cols: list[str] = [str(c) for c in raw_cols]
+    expected_dtypes: dict[str, str] = {str(k): str(v) for k, v in raw_dtypes.items()}
+    actual_cols = [str(c) for c in df.columns]
+
+    # A fingerprint without column names (hand-written recipe) says nothing about
+    # structure; comparing against an empty list would call every column new.
+    missing = [c for c in expected_cols if c not in actual_cols] if expected_cols else []
+    new = [c for c in actual_cols if c not in expected_cols] if expected_cols else []
+
+    # -- new columns: try to explain each as a rename ------------------
+    for col in new:
+        candidate, score = best_match(col, missing + [c.output_name for c in recipe.columns])
+        if candidate and score >= _RENAME_CONFIDENCE:
+            report.findings.append(
+                DriftFinding(
+                    kind="renamed_column",
+                    message=f'Column "{col}" is new — {score:.0%} match to recipe column "{candidate}"',
+                    severity=Severity.WARNING,
+                    column=col,
+                    suggestion=f'If "{col}" replaces "{candidate}", update the recipe to map it.',
+                    evidence={"match": candidate, "score": round(score, 3)},
+                )
+            )
+        else:
+            report.findings.append(
+                DriftFinding(
+                    kind="new_column",
+                    message=f'Column "{col}" is new and unrecognised',
+                    severity=Severity.WARNING,
+                    column=col,
+                    suggestion="Confirm the new column is expected, or drop/ignore it before apply.",
+                    evidence={},
+                )
+            )
+
+    # -- missing columns not explained by a rename --------------------
+    explained = {f.evidence.get("match") for f in report.by_kind("renamed_column")}
+    for col in missing:
+        if col in explained:
+            continue
+        report.findings.append(
+            DriftFinding(
+                kind="missing_column",
+                message=f'Column "{col}" expected by the recipe is missing',
+                severity=Severity.WARNING,
+                column=col,
+                suggestion=_closest_hint(col, new),
+                evidence={},
+            )
+        )
+
+    # -- dtype changes (canonical families — object vs str is not drift) -
+    for col in actual_cols:
+        if col not in expected_dtypes:
+            continue
+        was = expected_dtypes[col]
+        now = str(df[col].dtype)
+        if canonicalize_dtype(was) == canonicalize_dtype(now):
+            continue
+        report.findings.append(
+            DriftFinding(
+                kind="dtype_change",
+                message=f'Column "{col}" changed dtype ({was} → {now})',
+                severity=Severity.WARNING,
+                column=col,
+                suggestion="Re-plan or update casts if ops assume the old dtype.",
+                evidence={"was": was, "now": now},
+            )
+        )
+
+    # -- content fingerprint (row_count / hash_sample) ------------------
+    _detect_content_drift(df, fp, report)
+
+    # -- value-level format drift (declared parse_date formats) --------
+    _detect_format_drift(df, recipe, report)
+
+    return report
+
+
+def _detect_content_drift(df: pd.DataFrame, fp: dict, report: DriftReport) -> None:
+    """Compare stored content fingerprint fields when present.
+
+    Row-count and sample-hash changes are expected for monthly files, so they are
+    INFO (visible in the report, do not stop apply). Schema / dtype / format
+    findings remain the apply-blocking signals. Same row count + different hash is
+    called out in the message so operators can spot a possible wrong-file swap.
+    """
+    expected_rows = fp.get("row_count")
+    expected_hash = fp.get("hash_sample")
+    if expected_rows is None and expected_hash is None:
+        return
+
+    try:
+        sample_rows = int(fp.get("sampled_rows") or DEFAULT_SAMPLE_ROWS)
+    except (TypeError, ValueError):
+        sample_rows = DEFAULT_SAMPLE_ROWS
+    actual_fp = fingerprint_dataframe(df, sample_rows=sample_rows)
+    actual_rows = actual_fp["row_count"]
+    actual_hash = actual_fp["hash_sample"]
+
+    try:
+        rows_changed = expected_rows is not None and int(expected_rows) != int(actual_rows)
+    except (TypeError, ValueError):
+        rows_changed = False
+        expected_rows = None
+    hash_changed = expected_hash is not None and str(expected_hash) != str(actual_hash)
+
+    if rows_changed:
+        report.findings.append(
+            DriftFinding(
+                kind="row_count_change",
+                message=f"Row count changed ({expected_rows} → {actual_rows})",
+                severity=Severity.INFO,
+                evidence={"was": int(expected_rows), "now": int(actual_rows)},  # type: ignore[arg-type]
+            )
+        )
+
+    if hash_changed:
+        same_n = bool(expected_rows is not None and int(expected_rows) == int(actual_rows))
+        report.findings.append(
+            DriftFinding(
+                kind="content_hash_change",
+                message=(
+                    "Leading-row content hash changed "
+                    f"({expected_hash} → {actual_hash})"
+                ),
+                severity=Severity.INFO,
+                suggestion=(
+                    "Same row count but different sample values — confirm this is "
+                    "the intended file (not a schema-matched swap)."
+                    if same_n
+                    else None
+                ),
+                evidence={"was": str(expected_hash), "now": str(actual_hash)},
+            )
+        )
+
+
+def _detect_format_drift(df: pd.DataFrame, recipe: Recipe, report: DriftReport) -> None:
+    for col_recipe in recipe.columns:
+        src = col_recipe.source
+        if src not in df.columns:
+            continue
+        for op in col_recipe.ops:
+            if op.name != "parse_date":
+                continue
+            formats = op.params.get("formats")
+            if not formats:
+                continue
+            series = df[src].dropna()
+            if series.empty:
+                continue
+            parsed = parse_dates_to_datetime(
+                series,
+                list(formats),
+                dayfirst=bool(op.params.get("dayfirst", False)),
+                yearfirst=bool(op.params.get("yearfirst", False)),
+            )
+            unmatched = series[parsed.isna()]
+            if len(unmatched):
+                examples = [str(v) for v in unmatched.head(3).tolist()]
+                sketches = sorted({_sketch(e) for e in examples})
+                report.findings.append(
+                    DriftFinding(
+                        kind="format_drift",
+                        message=(
+                            f'{len(unmatched)} value(s) in "{src}" match no allowed date format '
+                            f"(new: {examples[0]!r})"
+                        ),
+                        severity=Severity.WARNING,
+                        column=src,
+                        suggestion=f"New pattern {sketches[0]!r}; add its format to the recipe.",
+                        evidence={
+                            "count": int(len(unmatched)),
+                            "examples": examples,
+                            "sketches": sketches,
+                        },
+                    )
+                )
+
+
+def _closest_hint(col: str, candidates: list[str]) -> str | None:
+    if not candidates:
+        return None
+    best = max(candidates, key=lambda c: similarity(col, c))
+    score = similarity(col, best)
+    if score >= 0.4:
+        return f'Did a new column "{best}" ({score:.0%} match) replace it?'
+    return None
+
+
+__all__ = ["detect_drift", "DriftReport", "DriftFinding"]

cleanframe/errors.py

@@ -0,0 +1,66 @@
+"""Exception hierarchy for CleanFrame.
+
+Every error CleanFrame raises deliberately derives from :class:`CleanFrameError`,
+so callers can ``except cleanframe.CleanFrameError`` to catch anything the library
+raises on purpose without also swallowing unrelated bugs.
+"""
+
+from __future__ import annotations
+
+
+class CleanFrameError(Exception):
+    """Base class for all errors raised deliberately by CleanFrame."""
+
+
+class CleanFrameWarning(UserWarning):
+    """Category for every warning CleanFrame raises deliberately.
+
+    Silence the library's advisory output with
+    ``warnings.simplefilter("ignore", cleanframe.CleanFrameWarning)``.
+    """
+
+
+class RecipeError(CleanFrameError):
+    """A recipe is malformed, references an unknown op, or fails to load."""
+
+
+class OpError(CleanFrameError):
+    """An op could not be applied (bad params, or a runtime failure in pandas)."""
+
+
+class ExecutionError(CleanFrameError):
+    """Applying a recipe to a dataframe failed."""
+
+
+class ValidationFailure(CleanFrameError):
+    """A validation rule failed under a policy that raises (e.g. ``on_fail: error``
+    or ``mode="strict"``)."""
+
+    def __init__(self, message: str, failures: list | None = None) -> None:
+        super().__init__(message)
+        self.failures = failures or []
+
+
+class DriftError(CleanFrameError):
+    """Schema drift was detected under a policy that raises (e.g. ``mode="strict"``)."""
+
+    def __init__(self, message: str, report=None) -> None:  # noqa: ANN001 - avoid import cycle
+        super().__init__(message)
+        self.report = report
+
+
+class SchemaError(CleanFrameError):
+    """A target schema is malformed or cannot be satisfied."""
+
+
+class LLMError(CleanFrameError):
+    """The LLM planner could not produce a valid recipe (misconfigured, no key,
+    budget exceeded, or invalid output)."""
+
+
+class BudgetExceeded(LLMError):
+    """Planning was aborted because it would exceed ``max_tokens_budget``."""
+
+
+class OutputError(CleanFrameError):
+    """An output file could not be written (bad path, permissions, or engine)."""

cleanframe/executor.py

@@ -0,0 +1,229 @@
+"""The executor: replay a recipe on a dataframe, deterministically.
+
+This is the "Pandas executes" half of the promise. It runs a recipe in fixed
+phases — column ops → renames → frame ops → validation — tracking column lineage
+and a stable row id throughout so a complete :class:`~cleanframe.diff.CellDiff`
+can be computed at the end. No AI, no network, no randomness: the same recipe and
+the same frame always produce the same output, the same diff, and the same
+quarantine.
+"""
+
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass, field
+
+import pandas as pd
+
+from ._util import DEFAULT_MAX_DIFF_CHANGES
+from .diff import CellDiff, compute_diff
+from .errors import CleanFrameWarning, ExecutionError
+from .ops import apply_column_op, apply_frame_op
+from .recipe import Recipe
+from .types import Mode
+from .validate import ValidationResult, apply_validations
+
+
+@dataclass
+class ExecutionResult:
+    """Everything replaying a recipe produced."""
+
+    dataframe: pd.DataFrame
+    diff: CellDiff
+    quarantine: pd.DataFrame = field(default_factory=pd.DataFrame)
+    validation_results: list[ValidationResult] = field(default_factory=list)
+    lineage: dict[str, str | None] = field(default_factory=dict)
+    log: list[str] = field(default_factory=list)
+
+    @property
+    def has_quarantine(self) -> bool:
+        return not self.quarantine.empty
+
+
+def execute(
+    recipe: Recipe,
+    df: pd.DataFrame,
+    *,
+    mode: Mode | str = Mode.REVIEW,
+    max_diff_changes: int | None = DEFAULT_MAX_DIFF_CHANGES,
+) -> ExecutionResult:
+    """Apply ``recipe`` to ``df`` and return the cleaned frame plus full lineage.
+
+    Parameters
+    ----------
+    max_diff_changes:
+        Cap on stored cell-level diff entries (default 100_000). Pass ``None`` to
+        store every change. Counts remain exact when truncated.
+
+    Memory model
+    ------------
+    Peak extra allocation is roughly ``input + (op-touched columns snapshot) +
+    (up to max_diff_changes CellChange records)`` — NOT two full frames. Only the
+    columns an op can change are snapshotted for the diff; pass-through columns are
+    read back from the final frame. So a 500 MB frame cleans in well under 2x RAM,
+    and the diff detail is bounded by ``max_diff_changes`` regardless of frame size.
+    """
+    from ._util import ensure_string_columns
+
+    mode = Mode.coerce(mode)
+    # Stable positional row id (survives renames and row drops for the diff).
+    work = ensure_string_columns(df).reset_index(drop=True)
+    n_rows_before = int(len(work))
+    original_columns = [str(c) for c in work.columns]
+    # Snapshot ONLY the columns whose *values* an op can change (column-op sources +
+    # validation targets), not the whole frame. Pass-through columns are read back
+    # from the final frame in the diff, which roughly halves peak memory on wide or
+    # large inputs. This set is complete: the only value-mutating paths are column
+    # ops (need a ColumnRecipe with ops) and the ``null`` validation policy.
+    rename_reverse = {c.rename_to: c.source for c in recipe.columns if c.rename_to}
+    snapshot_sources = {c.source for c in recipe.columns if c.ops}
+    for v in recipe.validations:
+        snapshot_sources.add(rename_reverse.get(v.column, v.column))
+    snapshot_cols = [c for c in original_columns if c in snapshot_sources]
+    original = work[snapshot_cols].copy()
+    log: list[str] = []
+    dropped_rows: list[tuple[int, str]] = []
+    nulled: dict[str, int] = {}
+
+    # source_of[current_column] -> original source column, or None if derived.
+    source_of: dict[str, str | None] = {str(c): str(c) for c in work.columns}
+
+    # -- Phase 1: column ops --------------------------------------------
+    for col_recipe in recipe.columns:
+        src = col_recipe.source
+        if src not in work.columns:
+            msg = f"recipe references column {src!r}, which is not in the data"
+            if mode is Mode.STRICT:
+                raise ExecutionError(msg + " (strict mode)")
+            log.append("skipped: " + msg)
+            warnings.warn(
+                f"CleanFrame: skipped recipe column {src!r} — not present in the data. "
+                "Use mode='strict' to fail instead, or re-plan / suggest_update for drift.",
+                CleanFrameWarning,
+                stacklevel=2,
+            )
+            continue
+
+        series = work[src]
+        na_before = int(series.isna().sum())
+        emitted: dict[str, pd.Series] = {}
+        for op in col_recipe.ops:
+            result = apply_column_op(op, series)
+            series = result.series
+            for name, extra in result.emit.items():
+                if name in emitted:
+                    raise ExecutionError(
+                        f"Column {src!r} emits {name!r} more than once; rename one target."
+                    )
+                emitted[name] = extra
+        work[src] = series
+        na_after = int(series.isna().sum())
+        if na_after > na_before:
+            nulled[src] = na_after - na_before
+        for name, extra in emitted.items():
+            if name in source_of and source_of[name] is None:
+                # Another op this run already emitted this derived column — two ops
+                # writing the same output name would silently clobber each other
+                # (the rename phase already guards this class of collision).
+                raise ExecutionError(
+                    f"Two ops emit the same derived column {name!r}; rename one target."
+                )
+            # If this emit overwrites a pre-existing column that wasn't in the partial
+            # snapshot, capture its still-original value now (before the overwrite) so
+            # the clobber is tracked in the diff — robust to any emit op.
+            if name in original_columns and name not in original.columns:
+                original[name] = work[name].copy()
+            work[name] = extra.reindex(work.index)
+            if name not in source_of:
+                source_of[name] = None  # brand-new derived column, no "before"
+            # else: `name` is an existing source column being overwritten — keep its
+            # lineage so every clobbered cell is tracked in the diff, and an
+            # idempotent re-emit of identical values registers as no change.
+            log.append(f"{src}: emitted derived column {name!r}")
+
+    if nulled:
+        detail = ", ".join(f"{col} ({n})" for col, n in sorted(nulled.items()))
+        msg = f"values became missing because an op could not parse them: {detail}"
+        log.append(msg)
+        warnings.warn("CleanFrame: " + msg, CleanFrameWarning, stacklevel=2)
+
+    # -- Phase 2: renames -----------------------------------------------
+    rename_map = {
+        c.source: c.rename_to
+        for c in recipe.columns
+        if c.rename_to and c.source in work.columns
+    }
+    if rename_map:
+        targets = list(rename_map.values())
+        survivors = [str(c) for c in work.columns if c not in rename_map]
+        clash = (set(targets) & set(survivors)) | {t for t in targets if targets.count(t) > 1}
+        if clash:
+            raise ExecutionError(f"Recipe renames collide on output name(s): {sorted(clash)}")
+        work = work.rename(columns=rename_map)
+        for src, dst in rename_map.items():
+            source_of[dst] = source_of.pop(src, src)
+
+    # Post-transform values of rows that later get dropped, so a value rewrite on a
+    # row that dedup/validation removes is still tracked in the diff (invariant #5).
+    # Only the dropped rows are snapshotted, not the whole frame.
+    dropped_snaps: list[pd.DataFrame] = []
+
+    # -- Phase 3: frame ops (dedup, drop_columns, …) --------------------
+    for op in recipe.frame_ops:
+        prev = work
+        work = apply_frame_op(op, prev)
+        dropped = set(prev.index) - set(work.index)
+        if dropped:
+            ids = sorted(dropped)
+            for rid in ids:
+                dropped_rows.append((int(rid), op.name))
+            dropped_snaps.append(prev.loc[ids])
+            log.append(f"{op.name}: dropped {len(dropped)} row(s)")
+        # a frame op can also remove columns (drop_columns); keep lineage tidy
+        for name in list(source_of):
+            if name not in work.columns:
+                source_of.pop(name, None)
+
+    # -- Phase 4: validation --------------------------------------------
+    pre_validation = work
+    outcome = apply_validations(work, recipe.validations, mode)
+    work = outcome.dataframe
+    if outcome.removed_rows:
+        present = [rid for rid, _ in outcome.removed_rows if rid in pre_validation.index]
+        if present:
+            dropped_snaps.append(pre_validation.loc[present])
+    dropped_rows.extend(outcome.removed_rows)
+    log.extend(outcome.log)
+
+    dropped_after = pd.concat(dropped_snaps) if dropped_snaps else None
+
+    # -- Diff -----------------------------------------------------------
+    diff = compute_diff(
+        original,
+        work,
+        source_of,
+        dropped_rows=dropped_rows,
+        dropped_after=dropped_after,
+        original_columns=original_columns,
+        n_rows_before=n_rows_before,
+        max_changes=max_diff_changes,
+    )
+    if diff.truncated:
+        msg = (
+            f"diff detail truncated to {len(diff.changes)} of {diff.changed_cells} "
+            "changed cells (raise max_diff_changes or pass None for a full lineage)"
+        )
+        log.append(msg)
+        warnings.warn("CleanFrame: " + msg, CleanFrameWarning, stacklevel=2)
+
+    return ExecutionResult(
+        dataframe=work,
+        diff=diff,
+        quarantine=outcome.quarantine,
+        validation_results=outcome.results,
+        lineage=source_of,
+        log=log,
+    )
+
+
+__all__ = ["execute", "ExecutionResult"]

cleanframe/fingerprint.py

@@ -0,0 +1,83 @@
+"""Deterministic hashing and dataframe fingerprints.
+
+Everything here is pure and reproducible: the same input always yields the same
+digest, on any machine, in any process. That property is what lets a recipe's
+``source_fingerprint`` be compared reliably months later for drift detection.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Any
+
+import pandas as pd
+
+#: How many leading rows feed the content hash. Fixed so the fingerprint is
+#: stable regardless of total file size.
+DEFAULT_SAMPLE_ROWS = 200
+
+
+def _canonical(value: Any) -> str:
+    """Render a single cell to a stable string.
+
+    ``NaN``/``None`` collapse to a single sentinel so that a missing value hashes
+    the same whether it arrived as ``float('nan')``, ``None``, or ``pd.NA``.
+    """
+    if value is None:
+        return "\x00NA\x00"
+    # pd.isna raises on array-like; cells are scalars here.
+    try:
+        if pd.isna(value):
+            return "\x00NA\x00"
+    except (TypeError, ValueError):
+        pass
+    if isinstance(value, float):
+        # repr(float) is round-trippable and stable across platforms in CPython.
+        return repr(value)
+    return str(value)
+
+
+def stable_hash(*parts: Any, length: int | None = None) -> str:
+    """Hash an arbitrary sequence of parts into a hex digest.
+
+    Parts are joined with a delimiter that cannot appear in :func:`_canonical`
+    output, so ``("a", "bc")`` and ``("ab", "c")`` never collide.
+    """
+    hasher = hashlib.sha256()
+    for part in parts:
+        hasher.update(_canonical(part).encode("utf-8"))
+        hasher.update(b"\x1f")  # unit separator delimiter
+    digest = hasher.hexdigest()
+    return digest[:length] if length else digest
+
+
+def fingerprint_dataframe(df: pd.DataFrame, sample_rows: int = DEFAULT_SAMPLE_ROWS) -> dict:
+    """Build a compact, comparable fingerprint of a dataframe's shape and content.
+
+    The returned dict is plain JSON/YAML-serialisable and is stored verbatim in a
+    recipe's ``source_fingerprint``. It intentionally records *structure* (column
+    names, order, dtypes) plus a *content* hash of the leading rows — enough to
+    detect drift without embedding the data itself.
+    """
+    columns = [str(c) for c in df.columns]
+    dtypes = {str(c): str(df[c].dtype) for c in df.columns}
+
+    head = df.head(sample_rows)
+    hasher = hashlib.sha256()
+    # Column names participate in the content hash so a rename alone changes it.
+    for col in columns:
+        hasher.update(col.encode("utf-8"))
+        hasher.update(b"\x1e")  # record separator
+        series = head[col]
+        for value in series.tolist():
+            hasher.update(_canonical(value).encode("utf-8"))
+            hasher.update(b"\x1f")
+
+    return {
+        "columns": len(columns),
+        "column_names": columns,
+        "dtypes": dtypes,
+        "row_count": int(len(df)),
+        "sampled_rows": int(len(head)),
+        "hash_sample": hasher.hexdigest()[:16],
+    }