cleanframe-engine 0.3.0__py3-none-any.whl

cleanframe/profile.py

@@ -0,0 +1,413 @@
+"""Deterministic profiling: what is *in* each column before we touch it.
+
+The profiler is the first stage of the pipeline. It computes per-column statistics
+(nulls, cardinality, examples) and — crucially — a best-guess **semantic type**
+(``email``, ``currency``, ``date``, ``categorical``, …) that detectors and schema
+inference build on. Everything here is read-only and reproducible: profiling the
+same frame twice yields identical numbers.
+
+Performance note: pattern-matching fractions are computed over a bounded, stable
+*head* sample (:data:`PATTERN_SAMPLE_CAP`) so profiling a million-row file stays
+fast without becoming non-deterministic.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+import pandas as pd
+
+from .ops import CURRENCY_SYMBOLS, parse_unit_scalar
+
+PATTERN_SAMPLE_CAP = 5000
+
+#: Values longer than this are never dates/currency/phones/numbers, and scanning
+#: them with the pattern regexes costs O(len^2) — a single long note or JSON blob
+#: would otherwise stall profiling for minutes.
+_MAX_PATTERN_VALUE_LEN = 200
+
+# -- reusable patterns -------------------------------------------------------
+EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+URL_RE = re.compile(r"^(https?://|www\.)\S+$", re.IGNORECASE)
+_DATEISH_RE = re.compile(r"[/.\-]|\d{1,2}\s*[A-Za-z]{3,}|[A-Za-z]{3,}\s*\d{1,2}")
+#: Clock times and ISO dates are not phone numbers, however many digits they hold.
+_TIMESTAMPISH_RE = re.compile(r"\d{4}-\d{2}-\d{2}|\d{1,2}:\d{2}")
+_DIGIT_RE = re.compile(r"\d")
+_BOOL_TOKENS = {"true", "false", "yes", "no", "t", "f", "y", "n"}
+
+#: Candidate date formats, ordered most-specific first. Shared with the dates
+#: detector so profiling and planning agree on what "a date" looks like. Pure
+#: all-digit formats are intentionally excluded to avoid classifying plain
+#: integers (``"20240101"``, ``"1200"``) as dates.
+COMMON_DATE_FORMATS = [
+    "%Y-%m-%dT%H:%M:%S",
+    "%Y-%m-%d %H:%M:%S",
+    "%Y-%m-%d",
+    "%Y/%m/%d",
+    "%d/%m/%Y",
+    "%m/%d/%Y",
+    "%d-%m-%Y",
+    "%m-%d-%Y",
+    "%d.%m.%Y",
+    "%d/%m/%y",
+    "%m/%d/%y",
+    "%d-%m-%y",
+    "%d %b %Y",
+    "%d %B %Y",
+    "%b %d, %Y",
+    "%B %d, %Y",
+    "%d-%b-%Y",
+    "%d-%b-%y",
+    "%b %d %Y",
+    "%d %b %y",
+]
+
+# Column-name hints (lowercased substrings) that nudge ambiguous classifications.
+_NAME_HINTS = {
+    "email": ("email", "e-mail", "mail"),
+    "phone": ("phone", "mobile", "contact", "tel", "cell", "whatsapp"),
+    "date": ("date", "dob", "day", "created", "updated", "signup", "joined", "timestamp"),
+    "currency": ("amount", "price", "cost", "salary", "revenue", "inr", "usd", "paid", "total"),
+    "id": ("id", "code", "uuid", "guid", "ref", "sku"),
+    "unit": ("weight", "mass", "height", "length", "width", "depth", "volume", "qty", "quantity", "size"),
+}
+
+
+@dataclass
+class ColumnProfile:
+    """Read-only statistics and a semantic-type guess for one column."""
+
+    name: str
+    dtype: str
+    count: int  # non-null
+    null_count: int
+    unique_count: int
+    semantic_type: str = "text"
+    type_confidence: float = 0.0
+    sample_values: list[Any] = field(default_factory=list)
+    most_common: list[tuple[Any, int]] = field(default_factory=list)
+    numeric_stats: dict[str, float] | None = None
+    str_len_stats: dict[str, float] | None = None
+    signals: dict[str, float] = field(default_factory=dict)
+
+    @property
+    def n(self) -> int:
+        return self.count + self.null_count
+
+    @property
+    def null_fraction(self) -> float:
+        return self.null_count / self.n if self.n else 0.0
+
+    @property
+    def unique_fraction(self) -> float:
+        return self.unique_count / self.count if self.count else 0.0
+
+    @property
+    def is_unique(self) -> bool:
+        return self.count > 0 and self.unique_count == self.count
+
+    @property
+    def is_constant(self) -> bool:
+        return self.unique_count == 1
+
+
+@dataclass
+class DataFrameProfile:
+    """Profiles for every column plus a few frame-level facts."""
+
+    n_rows: int
+    n_columns: int
+    columns: list[ColumnProfile]
+    duplicate_row_count: int = 0
+
+    def column(self, name: str) -> ColumnProfile | None:
+        for c in self.columns:
+            if c.name == name:
+                return c
+        return None
+
+    def __iter__(self):
+        return iter(self.columns)
+
+
+# ---------------------------------------------------------------------------
+# helpers
+# ---------------------------------------------------------------------------
+def _str_sample(series: pd.Series, cap: int = PATTERN_SAMPLE_CAP) -> list[str]:
+    """Bounded, stable list of stringified non-null values."""
+    non_null = series.dropna()
+    if len(non_null) > cap:
+        non_null = non_null.head(cap)
+    return [v if isinstance(v, str) else str(v) for v in non_null.tolist()]
+
+
+def _name_hint(column_name: str, kind: str) -> bool:
+    low = str(column_name).lower()
+    return any(h in low for h in _NAME_HINTS.get(kind, ()))
+
+
+def _frac(matches: int, total: int) -> float:
+    return matches / total if total else 0.0
+
+
+def _looks_date(value: str) -> bool:
+    if len(value) > _MAX_PATTERN_VALUE_LEN:
+        return False
+    return bool(_DATEISH_RE.search(value)) and bool(_DIGIT_RE.search(value))
+
+
+def _matching_dates(values: list[str]) -> list[str]:
+    """Return the subset of ``values`` that look like and parse as a common date."""
+    dateish = [v for v in values if _looks_date(v)]
+    if not dateish:
+        return []
+    ser = pd.Series(dateish, dtype="object")
+    matched = pd.Series(False, index=ser.index)
+    for fmt in COMMON_DATE_FORMATS:
+        pending = ser[~matched]
+        if pending.empty:
+            break
+        parsed = pd.to_datetime(pending, format=fmt, errors="coerce")
+        matched.loc[pending.index[parsed.notna().to_numpy()]] = True
+    return ser[matched].tolist()
+
+
+def _looks_currency(value: str) -> bool:
+    if len(value) > _MAX_PATTERN_VALUE_LEN:
+        return False
+    has_symbol = any(sym in value for sym in CURRENCY_SYMBOLS)
+    up = value.upper()
+    has_code = any(f" {c}" in f" {up} " or up.strip().endswith(c) or up.strip().startswith(c)
+                   for c in ("USD", "EUR", "GBP", "INR", "JPY"))
+    return (has_symbol or has_code) and bool(_DIGIT_RE.search(value))
+
+
+def _looks_unit(value: str) -> bool:
+    if len(value) > _MAX_PATTERN_VALUE_LEN:
+        return False
+    return parse_unit_scalar(value) is not None
+
+
+def _looks_phone(value: str) -> bool:
+    if len(value) > _MAX_PATTERN_VALUE_LEN or _TIMESTAMPISH_RE.search(value):
+        return False
+    digits = re.sub(r"\D", "", value)
+    if not (7 <= len(digits) <= 15):
+        return False
+    # Reject values that are "just a number" with no phone-like structure and no
+    # leading + / 0 — those are more likely quantities than phone numbers.
+    structured = bool(re.search(r"[+\-() ]", value)) or value.strip().startswith(("+", "0"))
+    return structured
+
+
+_STRICT_NUM_RE = re.compile(r"^[+-]?\d+(\.\d+)?$")
+
+
+def _is_strict_numeric(value: str) -> bool:
+    """True only for genuine numbers (allowing thousands separators/parentheses).
+
+    Deliberately stricter than :func:`ops._parse_number_scalar`, which strips *any*
+    non-digit and would turn an id like ``"U001"`` into ``1``. Here a stray letter
+    disqualifies the value, so alphanumeric ids are not mistaken for numbers.
+    """
+    if len(value) > _MAX_PATTERN_VALUE_LEN:
+        return False
+    s = value.strip()
+    if s.startswith("(") and s.endswith(")"):
+        s = s[1:-1]
+    s = s.replace(",", "").replace(" ", "")
+    return bool(_STRICT_NUM_RE.match(s))
+
+
+def _infer_semantic_type(
+    name: str, series: pd.Series, count: int, unique_count: int
+) -> tuple[str, float, dict[str, float]]:
+    """Return ``(semantic_type, confidence, signals)`` for a column.
+
+    Object/string columns are classified by the fraction of sampled values that
+    match each pattern, resolved by a fixed priority so the result is stable.
+    """
+    signals: dict[str, float] = {}
+    if count == 0:
+        return "empty", 1.0, signals
+
+    dtype = series.dtype
+    if pd.api.types.is_bool_dtype(dtype):
+        return "boolean", 1.0, signals
+    if pd.api.types.is_datetime64_any_dtype(dtype):
+        return "datetime", 1.0, signals
+    if pd.api.types.is_integer_dtype(dtype):
+        return "integer", 1.0, signals
+    if pd.api.types.is_float_dtype(dtype):
+        return "float", 1.0, signals
+
+    values = _str_sample(series)
+    total = len(values)
+    if total == 0:
+        return "text", 0.0, signals
+
+    # Evaluate each pattern predicate once per DISTINCT value, weighted by frequency.
+    # A 5000-value sample of a low-cardinality column has only a handful of distinct
+    # values; scoring each predicate per-occurrence re-does identical work. Fractions
+    # are exact (weighted counts), so classification is byte-identical.
+    from collections import Counter
+
+    vcounts = Counter(values)
+    distinct = list(vcounts)
+
+    def _wfrac(pred) -> float:
+        return sum(vcounts[v] for v in distinct if pred(v)) / total
+
+    def _short(v: str) -> bool:
+        return len(v) <= _MAX_PATTERN_VALUE_LEN
+
+    frac_bool = _wfrac(lambda v: _short(v) and v.strip().casefold() in _BOOL_TOKENS)
+    frac_email = _wfrac(lambda v: _short(v) and bool(EMAIL_RE.match(v.strip())))
+    frac_url = _wfrac(lambda v: _short(v) and bool(URL_RE.match(v.strip())))
+    frac_currency = _wfrac(_looks_currency)
+    frac_unit = _wfrac(_looks_unit)
+    frac_phone = _wfrac(_looks_phone)
+    frac_date = sum(vcounts[v] for v in _matching_dates(distinct)) / total
+    frac_dial_prefix = _wfrac(lambda v: v.strip().startswith(("+", "(")))
+    numeric_distinct = [v for v in distinct if _is_strict_numeric(v)]
+    frac_numeric = sum(vcounts[v] for v in numeric_distinct) / total
+    numeric_has_decimal = any("." in v for v in numeric_distinct)
+
+    signals.update(
+        bool=round(frac_bool, 3), email=round(frac_email, 3), url=round(frac_url, 3),
+        currency=round(frac_currency, 3), unit=round(frac_unit, 3),
+        date=round(frac_date, 3), phone=round(frac_phone, 3), numeric=round(frac_numeric, 3),
+        dial_prefix=round(frac_dial_prefix, 3),
+    )
+
+    uniq_frac = unique_count / count
+
+    # Fixed-priority resolution. Currency/date beat plain numeric because a money
+    # or date column also "parses as a number" once symbols are stripped.
+    if frac_bool >= 0.9:
+        return "boolean", frac_bool, signals
+    if frac_email >= 0.8 or (frac_email >= 0.5 and _name_hint(name, "email")):
+        return "email", max(frac_email, 0.8 if _name_hint(name, "email") else frac_email), signals
+    if frac_url >= 0.8:
+        return "url", frac_url, signals
+    if frac_currency >= 0.6:
+        return "currency", frac_currency, signals
+    if frac_unit >= 0.6 or (frac_unit >= 0.4 and _name_hint(name, "unit")):
+        return "unit", max(frac_unit, 0.8 if _name_hint(name, "unit") else frac_unit), signals
+    if frac_date >= 0.8 or (frac_date >= 0.5 and _name_hint(name, "date")):
+        return "date", max(frac_date, 0.8 if _name_hint(name, "date") else frac_date), signals
+    if _name_hint(name, "phone"):
+        if frac_phone >= 0.5:
+            return "phone", max(frac_phone, 0.8), signals
+    elif frac_phone >= 0.8 and frac_dial_prefix >= 0.5:
+        # Without a phone-ish column name, only an explicit dial prefix is evidence:
+        # timestamps and dashed ids otherwise look identical to a local number.
+        return "phone", frac_phone, signals
+    if frac_numeric >= 0.95:
+        return ("float" if numeric_has_decimal else "integer"), frac_numeric, signals
+    if unique_count <= 50 and uniq_frac < 0.5:
+        return "categorical", 1.0 - uniq_frac, signals
+    if uniq_frac >= 0.95:
+        return "id" if _name_hint(name, "id") else "text", uniq_frac, signals
+    return "text", 0.5, signals
+
+
+def _value_counts_stable(series: pd.Series, top: int = 10) -> list[tuple[Any, int]]:
+    import heapq
+
+    try:
+        vc = series.dropna().value_counts()
+    except TypeError:  # unhashable cells (lists/dicts) have no value counts
+        return []
+    # Deterministic tie-break: count desc, then string of value asc. heapq.nsmallest
+    # is sorted(...)[:top] without materialising/sorting every unique value, which
+    # matters on high-cardinality columns (millions of near-unique values).
+    pairs = heapq.nsmallest(top, vc.items(), key=lambda kv: (-int(kv[1]), str(kv[0])))
+    return [(k, int(v)) for k, v in pairs]
+
+
+def profile_column(series: pd.Series, name: str | None = None) -> ColumnProfile:
+    name = str(series.name if name is None else name)
+    n = len(series)
+    null_count = int(series.isna().sum())
+    count = n - null_count
+    non_null = series.dropna()
+    try:
+        unique_count = int(non_null.nunique())
+    except TypeError:  # unhashable cells (lists/dicts/sets) — compare by repr
+        unique_count = int(non_null.map(repr).nunique())
+
+    semantic_type, confidence, signals = _infer_semantic_type(name, series, count, unique_count)
+
+    try:
+        sample_values = non_null.drop_duplicates().head(5).tolist()
+    except TypeError:
+        sample_values = non_null.head(5).tolist()
+    most_common = _value_counts_stable(series)
+
+    numeric_stats = None
+    if pd.api.types.is_numeric_dtype(series.dtype) and count:
+        numeric = pd.to_numeric(series, errors="coerce")
+        numeric_stats = {
+            "min": float(numeric.min()),
+            "max": float(numeric.max()),
+            "mean": float(numeric.mean()),
+        }
+
+    str_len_stats = None
+    if semantic_type in ("text", "categorical", "id") and count:
+        # Bounded sample: a categorical column cannot be mapped elementwise, and a
+        # million-row text column should not be materialised just for three numbers.
+        lengths = [len(v) for v in _str_sample(series)]
+        if lengths:
+            str_len_stats = {
+                "min": float(min(lengths)),
+                "max": float(max(lengths)),
+                "mean": float(sum(lengths) / len(lengths)),
+            }
+
+    return ColumnProfile(
+        name=name,
+        dtype=str(series.dtype),
+        count=count,
+        null_count=null_count,
+        unique_count=unique_count,
+        semantic_type=semantic_type,
+        type_confidence=round(float(confidence), 3),
+        sample_values=sample_values,
+        most_common=most_common,
+        numeric_stats=numeric_stats,
+        str_len_stats=str_len_stats,
+        signals=signals,
+    )
+
+
+def profile_dataframe(df: pd.DataFrame) -> DataFrameProfile:
+    """Profile every column plus frame-level facts (row count, exact-duplicate rows)."""
+    from ._util import ensure_string_columns
+
+    df = ensure_string_columns(df)
+    columns = [profile_column(df[c], name=str(c)) for c in df.columns]
+    try:
+        duplicate_row_count = int(df.duplicated().sum())
+    except TypeError:  # unhashable cells cannot be compared row-wise
+        duplicate_row_count = 0
+    return DataFrameProfile(
+        n_rows=int(len(df)),
+        n_columns=int(df.shape[1]),
+        columns=columns,
+        duplicate_row_count=duplicate_row_count,
+    )
+
+
+__all__ = [
+    "ColumnProfile",
+    "DataFrameProfile",
+    "profile_column",
+    "profile_dataframe",
+    "COMMON_DATE_FORMATS",
+    "EMAIL_RE",
+    "URL_RE",
+]

cleanframe/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561 — CleanFrame ships inline type annotations.

cleanframe/quality.py

@@ -0,0 +1,81 @@
+"""A single, deterministic data-quality score.
+
+Turns a profile + detected issues into a 0–100 score and a letter grade. The
+formula is intentionally simple and documented so the number is explainable in a
+report and stable across runs:
+
+* Each issue contributes a penalty = ``severity_weight × affected_fraction``.
+* Exact-duplicate rows add their own penalty.
+* Penalties are averaged over the number of columns (so wide and narrow files land
+  on a comparable scale), then ``score = 100 × (1 − avg_penalty)``.
+
+It is a heuristic, not a benchmark — good for "is this file better than last
+month's?", not for splitting hairs between 87 and 88.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .issues import Issues
+from .profile import DataFrameProfile
+from .types import Severity
+
+_SEVERITY_WEIGHT = {Severity.ERROR: 1.0, Severity.WARNING: 0.4, Severity.INFO: 0.1}
+#: Used when an issue has no count in its evidence — a moderate assumed impact.
+_DEFAULT_FRACTION = 0.25
+
+
+@dataclass
+class QualityScore:
+    score: int
+    grade: str
+    label: str
+    color: str
+    penalty: float
+
+    def __str__(self) -> str:  # pragma: no cover - cosmetic
+        return f"{self.score}/100 ({self.grade})"
+
+
+def _affected_fraction(evidence: dict, n_rows: int) -> float:
+    if n_rows <= 0:
+        return _DEFAULT_FRACTION
+    for key in ("count", "null_count", "unparsed", "n_failed"):
+        if key in evidence and isinstance(evidence[key], (int, float)):
+            return min(1.0, evidence[key] / n_rows)
+    return _DEFAULT_FRACTION
+
+
+def _grade(score: int) -> tuple[str, str, str]:
+    if score >= 90:
+        return "A", "Excellent", "#16a34a"
+    if score >= 80:
+        return "B", "Good", "#65a30d"
+    if score >= 70:
+        return "C", "Fair", "#ca8a04"
+    if score >= 60:
+        return "D", "Poor", "#ea580c"
+    return "F", "Needs work", "#dc2626"
+
+
+def quality_score(profile: DataFrameProfile, issues: Issues) -> QualityScore:
+    n_rows = profile.n_rows or 1
+    n_cols = max(1, profile.n_columns)
+
+    penalty = 0.0
+    for issue in issues:
+        weight = _SEVERITY_WEIGHT.get(issue.severity, 0.2)
+        penalty += weight * _affected_fraction(issue.evidence, n_rows)
+
+    if profile.duplicate_row_count:
+        penalty += 0.5 * min(1.0, profile.duplicate_row_count / n_rows)
+
+    avg_penalty = min(1.0, penalty / n_cols)
+    score = int(round(100 * (1 - avg_penalty)))
+    score = max(0, min(100, score))
+    grade, label, color = _grade(score)
+    return QualityScore(score=score, grade=grade, label=label, color=color, penalty=round(penalty, 3))
+
+
+__all__ = ["QualityScore", "quality_score"]

cleanframe/readfix.py

@@ -0,0 +1,160 @@
+"""Read-time format auto-correction — deterministic, reviewable, replayable.
+
+Where the *content* detectors fix messy values, this fixes a messy *file shape* at
+read time: the wrong delimiter (a ``;``-separated file read as one column) and a
+non-UTF-8 encoding (Excel's Western "Save as CSV"). Every correction is:
+
+* **Deterministic** — an encoding fallback ladder (utf-8 → cp1252, which cannot
+  fail to decode) and a header-consensus delimiter vote among a fixed candidate
+  set. No probabilistic charset sniffing, so the result never drifts across
+  dependency/locale versions.
+* **Reviewable + replayable** — the chosen delimiter/encoding are pinned into the
+  recipe's ``read:`` section, so :func:`cleanframe.apply_recipe` re-reads the file
+  identically and never re-sniffs.
+* **Fail-loud on ambiguity** — if two delimiters split the header equally well, it
+  refuses (raises) rather than silently guessing, mirroring the library's
+  never-silently-corrupt contract.
+"""
+
+from __future__ import annotations
+
+import codecs
+import csv as _csv
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .errors import CleanFrameError
+
+_CSV_SUFFIXES = (".csv", ".txt", ".tsv")
+_DELIMITER_CANDIDATES = (",", ";", "\t", "|")
+_HEADER_SAMPLE_LINES = 20
+#: Only the first chunk is read for detection so a multi-GB file isn't loaded to RAM.
+_DETECT_BYTES = 65536
+
+
+@dataclass
+class ReadReport:
+    """What the read-time corrector detected and changed."""
+
+    encoding: str = "utf-8"
+    delimiter: str = ","
+    skipped_blank_lines: int = 0
+    notes: list[str] = field(default_factory=list)
+
+    def as_read_binding(self) -> dict:
+        """The subset to pin into a recipe's ``read:`` section for replay."""
+        out: dict = {}
+        if self.encoding not in ("utf-8", "utf-8-sig"):
+            out["encoding"] = self.encoding
+        if self.delimiter != ",":
+            out["sep"] = self.delimiter
+        if self.skipped_blank_lines:
+            out["blank_lines"] = self.skipped_blank_lines
+        return out
+
+
+def _decode(path: Path) -> tuple[str, str]:
+    """Return (sample_text, encoding) via a deterministic ladder: utf-8-sig then cp1252.
+
+    Only the first :data:`_DETECT_BYTES` are read, so detection stays O(1) memory on
+    huge files. A multi-byte UTF-8 char truncated at the read boundary is not treated
+    as a decode failure.
+    """
+    with open(path, "rb") as fh:
+        raw = fh.read(_DETECT_BYTES)
+    for bom, codec in (
+        (codecs.BOM_UTF32_LE, "utf-32"),
+        (codecs.BOM_UTF32_BE, "utf-32"),
+        (codecs.BOM_UTF16_LE, "utf-16"),
+        (codecs.BOM_UTF16_BE, "utf-16"),
+    ):
+        if raw.startswith(bom):
+            return raw.decode(codec, errors="ignore"), codec
+    if b"\x00" in raw:
+        raise CleanFrameError(
+            f"{path.name} looks binary (contains NUL bytes, and no UTF-16/32 byte-order "
+            "mark). Pass an explicit encoding= if this really is text, or convert the "
+            "file to UTF-8 CSV first."
+        )
+    try:
+        return raw.decode("utf-8-sig"), "utf-8"
+    except UnicodeDecodeError as exc:
+        if exc.start >= len(raw) - 4:  # a char split at the chunk boundary, not a bad file
+            return raw[: exc.start].decode("utf-8-sig"), "utf-8"
+    # cp1252 leaves five byte values undefined, so latin-1 (which maps all 256) is the
+    # final rung: the ladder must never raise for a file that is merely not UTF-8.
+    for codec in ("cp1252", "latin-1"):
+        try:
+            return raw.decode(codec), codec
+        except UnicodeDecodeError:
+            continue
+    return raw.decode("latin-1", errors="replace"), "latin-1"
+
+
+def _pick_delimiter(lines: list[str]) -> str:
+    """Vote for the delimiter that splits every header/sample line into the same
+    (>1) number of fields. Comma wins ties-with-comma; a tie between two non-comma
+    delimiters is refused."""
+    scores: dict[str, int] = {}
+    for cand in _DELIMITER_CANDIDATES:
+        try:
+            counts = [len(row) for row in _csv.reader(lines, delimiter=cand)]
+        except _csv.Error:
+            continue
+        if counts and counts[0] > 1 and all(c == counts[0] for c in counts):
+            scores[cand] = counts[0]
+    if not scores:
+        return ","  # nothing splits cleanly → treat as a single-column file
+    if "," in scores:
+        return ","  # comma already works → least-surprising choice
+    best = max(scores.values())
+    winners = sorted(c for c, s in scores.items() if s == best)
+    if len(winners) > 1:
+        pretty = [repr(w) for w in winners]
+        raise CleanFrameError(
+            f"Ambiguous delimiter: {', '.join(pretty)} each split the header into {best} "
+            "columns. Pass sep=... (or --sep) explicitly."
+        )
+    return winners[0]
+
+
+def detect_csv_options(path: str | Path) -> tuple[dict, ReadReport]:
+    """Detect encoding + delimiter (+ leading blank lines) for a CSV-family file.
+
+    Returns ``(read_options, report)`` where ``read_options`` is ready to pass to
+    :func:`pandas.read_csv` (``encoding``/``sep``/``skiprows``). Raises
+    :class:`~cleanframe.errors.CleanFrameError` on an ambiguous delimiter.
+    """
+    path = Path(path)
+    text, encoding = _decode(path)
+    lines = text.splitlines()
+
+    skip = 0
+    while skip < len(lines) and not lines[skip].strip():
+        skip += 1
+
+    sample = [ln for ln in lines[skip : skip + _HEADER_SAMPLE_LINES] if ln.strip()]
+    # .tsv is tab by definition — don't second-guess it.
+    delimiter = "\t" if path.suffix.lower() == ".tsv" else _pick_delimiter(sample)
+
+    report = ReadReport(encoding=encoding, delimiter=delimiter, skipped_blank_lines=skip)
+    if encoding not in ("utf-8", "utf-8-sig"):
+        report.notes.append(f"decoded as {encoding} (file was not valid UTF-8)")
+    if delimiter not in (",", "\t"):
+        report.notes.append(f"detected delimiter {delimiter!r} (not a comma)")
+    if skip:
+        report.notes.append(f"skipped {skip} leading blank line(s) before the header")
+
+    options: dict = {"encoding": "utf-8-sig" if encoding == "utf-8" else encoding}
+    if delimiter != ",":
+        options["sep"] = delimiter
+    if skip:
+        options["blank_lines"] = skip
+    return options, report
+
+
+def is_csv_family(path: str | Path) -> bool:
+    return Path(path).suffix.lower() in _CSV_SUFFIXES
+
+
+__all__ = ["ReadReport", "detect_csv_options", "is_csv_family"]