data-drift-lite 0.1.0__py3-none-any.whl

data_drift_lite/__init__.py

@@ -0,0 +1,20 @@
+"""Detect whether production data has drifted from training data, column by column.
+
+    import data_drift_lite
+    report = data_drift_lite.detect(reference_df, current_df)
+    report.drifted, report.drifted_columns, report.summary(), report.to_dict()
+"""
+
+from ._core import DriftMonitor, detect
+from ._report import ColumnDrift, DriftReport, SchemaDrift
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "detect",
+    "DriftMonitor",
+    "DriftReport",
+    "ColumnDrift",
+    "SchemaDrift",
+    "__version__",
+]

data_drift_lite/__main__.py

@@ -0,0 +1,8 @@
+"""Allow ``python -m data_drift_lite reference.csv current.csv``."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

data_drift_lite/_core.py

@@ -0,0 +1,359 @@
+"""``detect()`` and ``DriftMonitor``: profile the reference once, compare any number of batches."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Dict, Hashable, Iterable, List, Optional, Tuple, Union
+
+import numpy as np
+import pandas as pd
+
+from . import _stats as st
+from ._io import TableLike, load_table
+from ._report import ColumnDrift, DriftReport, SchemaDrift
+
+logger = logging.getLogger(__name__)
+
+TINY_ROWS = 20  # below this many rows the tests are unreliable; the report says so
+MISSING_SHIFT_NOTE = 0.1  # note when the missing share moves by more than this
+HIGH_CARDINALITY = 100  # note when a categorical column has more categories than this
+_PREVIEW = 5  # how many category names to list in a note
+
+ColumnsArg = Optional[Union[Hashable, Iterable[Hashable]]]
+
+
+@dataclass
+class _Profile:
+    """Everything about one reference column that a batch is compared against."""
+
+    name: Hashable
+    family: str
+    dtype: str
+    values: st.ColumnValues
+    stats: Dict[str, Any]
+    edges: np.ndarray = field(default_factory=lambda: np.empty(0, dtype="float64"))
+    bin_counts: np.ndarray = field(default_factory=lambda: np.empty(0, dtype=np.int64))
+    cat_counts: Dict[str, int] = field(default_factory=dict)
+
+    @property
+    def kind(self) -> str:
+        return st.kind_of(self.family)
+
+
+def _profile_column(name: Hashable, series: pd.Series) -> _Profile:
+    cv = st.extract(series)
+    dtype = str(series.dtype)
+    if cv.family == "category":
+        counts = st.value_counts(cv.values)
+        return _Profile(name, cv.family, dtype, cv, st.category_stats(cv, counts, dtype), cat_counts=counts)
+    edges = st.numeric_edges(cv.values)
+    return _Profile(
+        name,
+        cv.family,
+        dtype,
+        cv,
+        st.numeric_stats(cv, dtype),
+        edges=edges,
+        bin_counts=st.bin_counts(cv.values, edges),
+    )
+
+
+# --------------------------------------------------------------------------- per-column comparison
+
+
+def _preview(names: Iterable[str]) -> str:
+    listed = list(names)
+    shown = ", ".join(repr(n) for n in listed[:_PREVIEW])
+    extra = len(listed) - _PREVIEW
+    return shown + (f" (+{extra} more)" if extra > 0 else "")
+
+
+def _skipped_note(test_name: str, sides: List[str]) -> str:
+    where = " and ".join(sides) if sides else "reference or current"
+    return f"{test_name} skipped: no usable values in {where}"
+
+
+def _is_drifted(
+    p_value: Optional[float],
+    psi_value: Optional[float],
+    threshold: Optional[float],
+    psi_threshold: Optional[float],
+) -> bool:
+    if p_value is not None and threshold is not None and p_value < threshold:
+        return True
+    if psi_value is not None and psi_threshold is not None and psi_value > psi_threshold:
+        return True
+    return False
+
+
+def _compare_numeric(
+    profile: _Profile, cv: st.ColumnValues, notes: List[str]
+) -> Tuple[Optional[float], Optional[float], Optional[float]]:
+    ref = profile.values
+    statistic, p_value = st.ks_test(ref.values, cv.values)
+    ref_counts = profile.bin_counts
+    cur_counts = st.bin_counts(cv.values, profile.edges)
+    if ref.n_missing or cv.n_missing:
+        # missing values form their own bin, so a change in missingness shows up in PSI
+        ref_counts = np.append(ref_counts, ref.n_missing)
+        cur_counts = np.append(cur_counts, cv.n_missing)
+    psi_value = st.psi(ref_counts, cur_counts)
+    if statistic is None:
+        sides = [label for label, x in (("reference", ref), ("current", cv)) if x.values.size == 0]
+        notes.append(_skipped_note("KS test", sides))
+    if cv.n_nonfinite:
+        notes.append(f"current has {cv.n_nonfinite} non-finite value(s), counted as missing")
+    return statistic, p_value, psi_value
+
+
+def _compare_categorical(
+    profile: _Profile, cv: st.ColumnValues, notes: List[str]
+) -> Tuple[Optional[float], Optional[float], Optional[float], Dict[str, int]]:
+    ref = profile.values
+    cur_counts = st.value_counts(cv.values)
+    seen = list(profile.cat_counts)
+    unseen = {cat: n for cat, n in cur_counts.items() if cat not in profile.cat_counts}
+    # PSI: the reference categories plus one pooled bin for anything the reference never saw
+    ref_psi = [profile.cat_counts[cat] for cat in seen] + [0]
+    cur_psi = [cur_counts.get(cat, 0) for cat in seen] + [sum(unseen.values())]
+    # chi-square: every category from either side
+    union = seen + list(unseen)
+    ref_chi = [profile.cat_counts.get(cat, 0) for cat in union]
+    cur_chi = [cur_counts.get(cat, 0) for cat in union]
+    if ref.n_missing or cv.n_missing:
+        ref_psi.append(ref.n_missing)
+        cur_psi.append(cv.n_missing)
+        ref_chi.append(ref.n_missing)
+        cur_chi.append(cv.n_missing)
+    statistic, p_value = st.chi2_test(np.array([ref_chi, cur_chi], dtype="float64"))
+    psi_value = st.psi(ref_psi, cur_psi)
+    if statistic is None:
+        sides = [label for label, x in (("reference", ref), ("current", cv)) if x.n_rows == 0]
+        notes.append(_skipped_note("chi-square test", sides))
+    if unseen:
+        word = "category" if len(unseen) == 1 else "categories"
+        notes.append(f"{len(unseen)} {word} unseen in reference: {_preview(unseen)}")
+    if len(union) > HIGH_CARDINALITY:
+        notes.append(
+            f"high cardinality ({len(union)} categories); the chi-square p-value may be unreliable"
+        )
+    return statistic, p_value, psi_value, cur_counts
+
+
+def _compare(
+    profile: _Profile,
+    series: pd.Series,
+    threshold: Optional[float],
+    psi_threshold: Optional[float],
+) -> ColumnDrift:
+    cv = st.extract(series)
+    dtype = str(series.dtype)
+    notes: List[str] = []
+    if profile.kind == "numeric":
+        test = "ks"
+        statistic, p_value, psi_value = _compare_numeric(profile, cv, notes)
+        current_stats = st.numeric_stats(cv, dtype)
+    else:
+        test = "chi2"
+        statistic, p_value, psi_value, cur_counts = _compare_categorical(profile, cv, notes)
+        current_stats = st.category_stats(cv, cur_counts, dtype)
+    before, after = profile.values.missing_share, cv.missing_share
+    if abs(after - before) > MISSING_SHIFT_NOTE:
+        notes.append(f"missing share moved from {before:.1%} to {after:.1%}")
+    return ColumnDrift(
+        kind=profile.kind,
+        statistic=statistic,
+        p_value=p_value,
+        psi=psi_value,
+        drifted=_is_drifted(p_value, psi_value, threshold, psi_threshold),
+        reference_stats=dict(profile.stats),
+        current_stats=current_stats,
+        name=str(profile.name),
+        test=test,
+        notes=notes,
+    )
+
+
+# --------------------------------------------------------------------------- inputs and options
+
+
+def _check_options(threshold: Optional[float], psi_threshold: Optional[float], sample: Optional[int]) -> None:
+    if threshold is not None and not (0.0 <= float(threshold) <= 1.0):
+        raise ValueError("threshold must be between 0 and 1, or None to disable the p-value rule")
+    if psi_threshold is not None and not (float(psi_threshold) >= 0.0):
+        raise ValueError("psi_threshold must be >= 0, or None to disable the PSI rule")
+    if sample is not None and (
+        isinstance(sample, bool) or not isinstance(sample, (int, np.integer)) or sample < 1
+    ):
+        raise ValueError("sample must be a positive integer, or None to disable sampling")
+
+
+def _load(source: TableLike, label: str) -> pd.DataFrame:
+    frame = load_table(source, label)
+    if frame.columns.has_duplicates:
+        dupes = sorted({str(c) for c in frame.columns[frame.columns.duplicated()]})
+        raise ValueError(f"{label} has duplicate column names: {', '.join(dupes)}")
+    return frame
+
+
+def _maybe_sample(
+    frame: pd.DataFrame, sample: Optional[int], random_state: Any, label: str
+) -> Tuple[pd.DataFrame, Optional[str]]:
+    n_rows = len(frame)
+    if sample is None or n_rows <= sample:
+        return frame, None
+    sampled = frame.sample(n=int(sample), random_state=random_state)
+    note = f"{label} sampled down to {int(sample):,} of {n_rows:,} rows (random_state={random_state!r})"
+    return sampled, note
+
+
+def _tiny_note(n_rows: int, label: str) -> Optional[str]:
+    if n_rows >= TINY_ROWS:
+        return None
+    rows = "row" if n_rows == 1 else "rows"
+    return f"{label} has only {n_rows} {rows} (fewer than {TINY_ROWS}); test results are unreliable at this size"
+
+
+def _normalize_columns(columns: ColumnsArg, frame: pd.DataFrame) -> Optional[List[Hashable]]:
+    if columns is None:
+        return None
+    if isinstance(columns, (str, bytes)) or not isinstance(columns, Iterable):
+        requested: List[Hashable] = [columns]
+    else:
+        requested = list(columns)
+    if not requested:
+        raise ValueError("columns= must name at least one column; pass None to compare every column")
+    unknown = [c for c in requested if c not in frame.columns]
+    if unknown:
+        raise ValueError(f"columns not found in reference: {', '.join(repr(c) for c in unknown)}")
+    ordered: List[Hashable] = []
+    for c in requested:
+        if c not in ordered:
+            ordered.append(c)
+    return ordered
+
+
+# --------------------------------------------------------------------------- public API
+
+
+class DriftMonitor:
+    """Profile a reference dataset once, then check any number of batches against it.
+
+    Takes the same options as :func:`detect`. The reference is loaded, optionally
+    sampled and profiled in ``__init__``, so each :meth:`check` only has to look at
+    the batch. Use it when scoring many batches against the same training data.
+
+    Attributes:
+        columns: the reference columns that batches are compared on.
+        reference_rows: rows in the (possibly sampled) reference.
+    """
+
+    def __init__(
+        self,
+        reference: TableLike,
+        *,
+        columns: ColumnsArg = None,
+        threshold: Optional[float] = 0.05,
+        psi_threshold: Optional[float] = 0.2,
+        sample: Optional[int] = 100_000,
+        random_state: Any = 0,
+    ) -> None:
+        _check_options(threshold, psi_threshold, sample)
+        frame = _load(reference, "reference")
+        frame, sample_note = _maybe_sample(frame, sample, random_state, "reference")
+        self.threshold = threshold
+        self.psi_threshold = psi_threshold
+        self.sample = sample
+        self.random_state = random_state
+        self._requested = _normalize_columns(columns, frame)
+        self.columns: List[Hashable] = (
+            list(self._requested) if self._requested is not None else list(frame.columns)
+        )
+        self.reference_rows = int(len(frame))
+        self._reference_columns = set(frame.columns)
+        self._profiles = {name: _profile_column(name, frame[name]) for name in self.columns}
+        tiny_note = _tiny_note(self.reference_rows, "reference")
+        self._notes = [note for note in (sample_note, tiny_note) if note]
+        if tiny_note:
+            logger.warning(tiny_note)
+
+    def check(self, batch: TableLike) -> DriftReport:
+        """Compare one batch (DataFrame or .csv/.parquet path) against the reference."""
+        frame = _load(batch, "current")
+        frame, sample_note = _maybe_sample(frame, self.sample, self.random_state, "current")
+        notes = list(self._notes)
+        if sample_note:
+            notes.append(sample_note)
+        tiny_note = _tiny_note(len(frame), "current")
+        if tiny_note:
+            notes.append(tiny_note)
+            logger.warning(tiny_note)
+
+        present = set(frame.columns)
+        missing = [name for name in self.columns if name not in present]
+        if self._requested is None:
+            new = [name for name in frame.columns if name not in self._reference_columns]
+        else:
+            new = []
+        dtype_changed: Dict[Hashable, Tuple[str, str]] = {}
+        columns: Dict[Hashable, ColumnDrift] = {}
+        for name in self.columns:
+            if name not in present:
+                continue
+            profile = self._profiles[name]
+            series = frame[name]
+            if st.family_of(series.dtype) != profile.family:
+                dtype_changed[name] = (profile.dtype, str(series.dtype))
+                continue
+            columns[name] = _compare(profile, series, self.threshold, self.psi_threshold)
+
+        return DriftReport(
+            columns=columns,
+            schema=SchemaDrift(missing, new, dtype_changed),
+            threshold=self.threshold,
+            psi_threshold=self.psi_threshold,
+            reference_rows=self.reference_rows,
+            current_rows=int(len(frame)),
+            notes=notes,
+        )
+
+
+def detect(
+    reference: TableLike,
+    current: TableLike,
+    *,
+    columns: ColumnsArg = None,
+    threshold: Optional[float] = 0.05,
+    psi_threshold: Optional[float] = 0.2,
+    sample: Optional[int] = 100_000,
+    random_state: Any = 0,
+) -> DriftReport:
+    """Detect whether ``current`` has drifted from ``reference``, column by column.
+
+    Args:
+        reference: training-time data - a DataFrame, a Series, or a .csv/.parquet path.
+        current: the data to check - same accepted types.
+        columns: compare only these columns (default: every reference column).
+        threshold: a column is drifted when its test p-value is below this
+            (KS test for numeric columns, chi-square for categorical). ``None``
+            switches the p-value rule off.
+        psi_threshold: a column is drifted when its Population Stability Index is
+            above this. ``None`` switches the PSI rule off.
+        sample: cap each side at this many random rows to keep large checks fast;
+            ``None`` uses every row.
+        random_state: seed for that sampling, so results are reproducible.
+
+    Returns:
+        A :class:`DriftReport` with one :class:`ColumnDrift` per compared column
+        plus schema differences (missing / new / type-changed columns).
+    """
+    monitor = DriftMonitor(
+        reference,
+        columns=columns,
+        threshold=threshold,
+        psi_threshold=psi_threshold,
+        sample=sample,
+        random_state=random_state,
+    )
+    return monitor.check(current)

data_drift_lite/_io.py

@@ -0,0 +1,47 @@
+"""Input loading: a pandas DataFrame, a Series, or a path to a .csv / .parquet file."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Union
+
+import pandas as pd
+
+TableLike = Union[pd.DataFrame, pd.Series, str, "os.PathLike[str]"]
+
+
+def load_table(source: TableLike, label: str = "data") -> pd.DataFrame:
+    """Return ``source`` as a DataFrame, reading .csv/.tsv/.parquet files from disk.
+
+    DataFrames are returned as-is (never copied or mutated); a Series becomes a
+    one-column frame. ``label`` names the argument in error messages.
+    """
+    if isinstance(source, pd.DataFrame):
+        return source
+    if isinstance(source, pd.Series):
+        return source.to_frame()
+    if isinstance(source, (str, os.PathLike)):
+        path = Path(source)
+        if not path.is_file():
+            raise FileNotFoundError(f"{label}: no such file: {path}")
+        suffixes = [s.lower() for s in path.suffixes]
+        if ".parquet" in suffixes or ".pq" in suffixes:
+            try:
+                return pd.read_parquet(path)
+            except ImportError as exc:
+                raise ImportError(
+                    "reading .parquet files needs pyarrow: "
+                    'pip install "data-drift-lite[parquet]"'
+                ) from exc
+        if ".csv" in suffixes:
+            return pd.read_csv(path)
+        if ".tsv" in suffixes:
+            return pd.read_csv(path, sep="\t")
+        raise ValueError(
+            f"{label}: unsupported file type {path.suffix!r}; expected .csv, .tsv or .parquet"
+        )
+    raise TypeError(
+        f"{label} must be a pandas DataFrame, a Series, or a path to a .csv/.parquet file, "
+        f"not {type(source).__name__}"
+    )

data_drift_lite/_report.py

@@ -0,0 +1,264 @@
+"""Result objects: ``ColumnDrift``, ``SchemaDrift`` and ``DriftReport``.
+
+All three are plain dataclasses. ``to_dict()`` is JSON-safe (no numpy scalars,
+no NaN/inf) and ``summary()`` is a short human-readable text.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+
+_NAME_WIDTH = 40
+
+
+def json_safe(obj: Any) -> Any:
+    """Recursively turn numpy scalars, tuples and non-finite floats into JSON-safe values."""
+    if isinstance(obj, dict):
+        return {str(k): json_safe(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple, set)):
+        return [json_safe(v) for v in obj]
+    if isinstance(obj, (bool, np.bool_)):
+        return bool(obj)
+    if isinstance(obj, (int, np.integer)):
+        return int(obj)
+    if isinstance(obj, (float, np.floating)):
+        value = float(obj)
+        return value if math.isfinite(value) else None
+    if obj is None or isinstance(obj, str):
+        return obj
+    return str(obj)
+
+
+def _fmt(value: Optional[float]) -> str:
+    return "n/a" if value is None else f"{value:.4f}"
+
+
+def _fmt_p(value: Optional[float]) -> str:
+    if value is None:
+        return "n/a"
+    return f"{value:.4f}" if value >= 1e-4 else f"{value:.1e}"
+
+
+def _clip(text: str, width: int = _NAME_WIDTH) -> str:
+    return text if len(text) <= width else text[: width - 3] + "..."
+
+
+@dataclass
+class ColumnDrift:
+    """Drift result for one column.
+
+    ``statistic`` and ``p_value`` come from the KS test (numeric columns) or the
+    chi-square test (categorical columns); ``psi`` is the Population Stability
+    Index. Each is ``None`` when it could not be computed; ``notes`` says why.
+    """
+
+    kind: str
+    statistic: Optional[float]
+    p_value: Optional[float]
+    psi: Optional[float]
+    drifted: bool
+    reference_stats: Dict[str, Any]
+    current_stats: Dict[str, Any]
+    name: str = ""
+    test: str = ""
+    notes: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """JSON-safe dict of this column's result."""
+        return json_safe(
+            {
+                "name": self.name,
+                "kind": self.kind,
+                "test": self.test,
+                "statistic": self.statistic,
+                "p_value": self.p_value,
+                "psi": self.psi,
+                "drifted": self.drifted,
+                "reference_stats": self.reference_stats,
+                "current_stats": self.current_stats,
+                "notes": list(self.notes),
+            }
+        )
+
+
+@dataclass
+class SchemaDrift:
+    """Structural differences between the reference and the current data."""
+
+    missing_columns: List[Any] = field(default_factory=list)
+    new_columns: List[Any] = field(default_factory=list)
+    dtype_changed: Dict[Any, Tuple[str, str]] = field(default_factory=dict)
+
+    @property
+    def drifted(self) -> bool:
+        """True when a reference column is missing or changed its type family.
+
+        New columns are reported but do not count: nothing the reference relied on
+        has changed.
+        """
+        return bool(self.missing_columns or self.dtype_changed)
+
+    @property
+    def changed(self) -> bool:
+        """True when anything at all differs, new columns included."""
+        return bool(self.missing_columns or self.new_columns or self.dtype_changed)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """JSON-safe dict of the schema differences."""
+        return json_safe(
+            {
+                "missing_columns": list(self.missing_columns),
+                "new_columns": list(self.new_columns),
+                "dtype_changed": {
+                    name: {"reference": before, "current": after}
+                    for name, (before, after) in self.dtype_changed.items()
+                },
+                "drifted": self.drifted,
+            }
+        )
+
+
+@dataclass
+class DriftReport:
+    """Everything :func:`data_drift_lite.detect` found.
+
+    ``columns`` maps each compared column to its :class:`ColumnDrift`, in reference
+    order. Columns that are missing from the current data or changed type family are
+    not compared; they live in ``schema``.
+    """
+
+    columns: Dict[Any, ColumnDrift]
+    schema: SchemaDrift = field(default_factory=SchemaDrift)
+    threshold: Optional[float] = 0.05
+    psi_threshold: Optional[float] = 0.2
+    reference_rows: int = 0
+    current_rows: int = 0
+    notes: List[str] = field(default_factory=list)
+
+    # ---------------------------------------------------------------- headline numbers
+
+    @property
+    def drifted_columns(self) -> List[Any]:
+        """Names of the compared columns flagged as drifted, in reference order."""
+        return [name for name, col in self.columns.items() if col.drifted]
+
+    @property
+    def drift_share(self) -> float:
+        """Fraction of compared columns that drifted (0.0 when nothing was compared)."""
+        return len(self.drifted_columns) / len(self.columns) if self.columns else 0.0
+
+    @property
+    def drifted(self) -> bool:
+        """True when any column drifted, a column went missing, or a type family changed."""
+        return bool(self.drifted_columns) or self.schema.drifted
+
+    @property
+    def missing_columns(self) -> List[Any]:
+        """Reference columns absent from the current data."""
+        return self.schema.missing_columns
+
+    @property
+    def new_columns(self) -> List[Any]:
+        """Current columns absent from the reference."""
+        return self.schema.new_columns
+
+    @property
+    def dtype_changed(self) -> Dict[Any, Tuple[str, str]]:
+        """Columns whose type family changed: name -> (reference dtype, current dtype)."""
+        return self.schema.dtype_changed
+
+    # ---------------------------------------------------------------- output
+
+    def _rule_text(self) -> str:
+        parts = []
+        if self.threshold is not None:
+            parts.append(f"p < {self.threshold:g}")
+        if self.psi_threshold is not None:
+            parts.append(f"PSI > {self.psi_threshold:g}")
+        return "drifted when " + " or ".join(parts) if parts else "drift rules disabled (both thresholds are None)"
+
+    def _table_lines(self) -> List[str]:
+        headers = ("column", "kind", "test", "statistic", "p-value", "PSI", "status")
+        rows = [
+            (
+                _clip(str(name)),
+                col.kind,
+                col.test or "-",
+                _fmt(col.statistic),
+                _fmt_p(col.p_value),
+                _fmt(col.psi),
+                "DRIFTED" if col.drifted else "ok",
+            )
+            for name, col in self.columns.items()
+        ]
+        widths = [max(len(header), *(len(row[i]) for row in rows)) for i, header in enumerate(headers)]
+        right = {3, 4, 5}
+
+        def render(cells: Tuple[str, ...]) -> str:
+            padded = [
+                cell.rjust(widths[i]) if i in right else cell.ljust(widths[i]) for i, cell in enumerate(cells)
+            ]
+            return "  " + "  ".join(padded).rstrip()
+
+        return [render(headers)] + [render(row) for row in rows]
+
+    def summary(self) -> str:
+        """Human-readable summary: verdict, one line per column, schema changes, notes."""
+        n_compared = len(self.columns)
+        n_drifted = len(self.drifted_columns)
+        if n_drifted:
+            verdict = f"DRIFT DETECTED: {n_drifted} of {n_compared} columns drifted ({self.drift_share:.0%})"
+        elif self.schema.drifted:
+            verdict = f"DRIFT DETECTED: schema changed (0 of {n_compared} columns drifted)"
+        elif n_compared:
+            verdict = f"no drift detected ({n_compared} columns compared)"
+        else:
+            verdict = "no columns compared"
+        lines = [
+            f"data-drift-lite: {verdict}",
+            f"reference rows: {self.reference_rows:,} | current rows: {self.current_rows:,} | {self._rule_text()}",
+        ]
+        if n_compared:
+            lines.append("")
+            lines.extend(self._table_lines())
+        if self.schema.changed:
+            lines.append("")
+            lines.append("schema:")
+            if self.schema.missing_columns:
+                names = ", ".join(str(c) for c in self.schema.missing_columns)
+                lines.append(f"  - missing in current: {names}")
+            if self.schema.new_columns:
+                names = ", ".join(str(c) for c in self.schema.new_columns)
+                lines.append(f"  - new in current: {names}")
+            for name, (before, after) in self.schema.dtype_changed.items():
+                lines.append(f"  - dtype changed: {name} ({before} -> {after})")
+        column_notes = [f"{name}: {note}" for name, col in self.columns.items() for note in col.notes]
+        if self.notes or column_notes:
+            lines.append("")
+            lines.append("notes:")
+            lines.extend(f"  - {note}" for note in list(self.notes) + column_notes)
+        return "\n".join(lines)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """JSON-safe dict with the verdict, every column, the schema section and notes."""
+        return json_safe(
+            {
+                "drifted": self.drifted,
+                "drift_share": self.drift_share,
+                "drifted_columns": self.drifted_columns,
+                "threshold": self.threshold,
+                "psi_threshold": self.psi_threshold,
+                "reference_rows": self.reference_rows,
+                "current_rows": self.current_rows,
+                "columns": {name: col.to_dict() for name, col in self.columns.items()},
+                "schema": self.schema.to_dict(),
+                "notes": list(self.notes),
+            }
+        )
+
+    def __str__(self) -> str:
+        return self.summary()

data_drift_lite/_stats.py

@@ -0,0 +1,223 @@
+"""Statistical building blocks: column typing, value extraction, binning, PSI, KS, chi-square.
+
+Everything here works on plain numpy arrays and returns plain Python numbers (or
+``None`` when a quantity cannot be computed), so the report stays JSON-friendly.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+from pandas.api import types as pdt
+from scipy import stats as sps
+
+PSI_EPS = 1e-4  # floor for bin shares so log(0) never happens
+LOW_CARDINALITY = 10  # numeric columns with this many distinct values or fewer: one bin per value
+QUANTILE_BINS = 10  # otherwise: quantile bins built from the reference
+TOP_CATEGORIES = 5  # categories listed in the per-column stats
+
+_NUMERIC_FAMILIES = frozenset({"number", "datetime", "timedelta"})
+
+
+def family_of(dtype: Any) -> str:
+    """Map a pandas dtype to one of ``number``, ``datetime``, ``timedelta``, ``category``."""
+    if pdt.is_bool_dtype(dtype):
+        return "category"
+    if pdt.is_datetime64_any_dtype(dtype):
+        return "datetime"
+    if pdt.is_timedelta64_dtype(dtype):
+        return "timedelta"
+    if pdt.is_numeric_dtype(dtype):
+        return "number"
+    return "category"
+
+
+def kind_of(family: str) -> str:
+    """Public kind label for a family: ``numeric`` or ``categorical``."""
+    return "numeric" if family in _NUMERIC_FAMILIES else "categorical"
+
+
+def share(part: int, whole: int) -> float:
+    """``part / whole`` as a float, 0.0 when ``whole`` is 0."""
+    return float(part) / float(whole) if whole else 0.0
+
+
+@dataclass
+class ColumnValues:
+    """The usable values of one column plus how much was missing."""
+
+    family: str
+    n_rows: int
+    n_missing: int
+    values: np.ndarray  # number: finite float64; datetime/timedelta: int64 ns; category: object array of str
+    n_nonfinite: int = 0  # +/-inf in a number column; counted inside n_missing
+
+    @property
+    def missing_share(self) -> float:
+        return share(self.n_missing, self.n_rows)
+
+
+def extract(series: pd.Series) -> ColumnValues:
+    """Pull the usable values out of a Series according to its dtype family."""
+    family = family_of(series.dtype)
+    n_rows = int(len(series))
+    if family == "number":
+        arr = np.asarray(series.to_numpy(dtype="float64", na_value=np.nan), dtype="float64")
+        finite = np.isfinite(arr)
+        n_present = int(finite.sum())
+        n_nan = int(np.isnan(arr).sum())
+        return ColumnValues(
+            family, n_rows, n_rows - n_present, arr[finite], n_nonfinite=n_rows - n_present - n_nan
+        )
+    if family in ("datetime", "timedelta"):
+        s = series
+        if family == "datetime" and getattr(s.dtype, "tz", None) is not None:
+            s = s.dt.tz_convert(None)
+        unit = "datetime64[ns]" if family == "datetime" else "timedelta64[ns]"
+        arr = s.to_numpy(dtype=unit)
+        present = ~np.isnat(arr)
+        return ColumnValues(family, n_rows, n_rows - int(present.sum()), arr[present].astype(np.int64))
+    missing = series.isna().to_numpy(dtype=bool)
+    present_values = series[~missing].astype(str).to_numpy(dtype=object)
+    return ColumnValues("category", n_rows, int(missing.sum()), present_values)
+
+
+# --------------------------------------------------------------------------- numeric bins
+
+
+def numeric_edges(values: np.ndarray) -> np.ndarray:
+    """Right-closed interior boundaries built from the reference values.
+
+    Bin ``i`` covers ``(edges[i-1], edges[i]]``; the outer bins extend to -inf and
+    +inf so every current value lands somewhere. Columns with at most
+    ``LOW_CARDINALITY`` distinct values get one bin per value (boundaries at the
+    midpoints), everything else gets ``QUANTILE_BINS`` quantile bins. A constant
+    column yields no boundaries, i.e. a single bin, so its PSI is 0 rather than NaN.
+    """
+    if values.size == 0:
+        return np.empty(0, dtype="float64")
+    uniq = np.unique(values)
+    if uniq.size <= LOW_CARDINALITY:
+        lo = uniq[:-1].astype("float64")
+        hi = uniq[1:].astype("float64")
+        return (lo + hi) / 2.0
+    probs = np.linspace(0.0, 1.0, QUANTILE_BINS + 1)[1:-1]
+    return np.unique(np.quantile(values, probs))
+
+
+def bin_counts(values: np.ndarray, edges: np.ndarray) -> np.ndarray:
+    """Count values per bin for the boundaries from :func:`numeric_edges`."""
+    idx = np.searchsorted(edges, values, side="left")
+    return np.bincount(idx, minlength=edges.size + 1)
+
+
+# --------------------------------------------------------------------------- categories
+
+
+def value_counts(values: np.ndarray) -> Dict[str, int]:
+    """Counts per category, ordered by count descending then name (deterministic)."""
+    if values.size == 0:
+        return {}
+    uniq, counts = np.unique(values, return_counts=True)
+    pairs = sorted(zip(uniq.tolist(), counts.tolist()), key=lambda pair: (-pair[1], pair[0]))
+    return {str(cat): int(n) for cat, n in pairs}
+
+
+# --------------------------------------------------------------------------- tests
+
+
+def psi(reference_counts: Any, current_counts: Any) -> Optional[float]:
+    """Population Stability Index between two aligned count vectors.
+
+    Shares are floored at ``PSI_EPS`` so an empty bin on one side contributes a
+    large but finite amount. Returns ``None`` when either side has no counts.
+    """
+    ref = np.asarray(reference_counts, dtype="float64")
+    cur = np.asarray(current_counts, dtype="float64")
+    if ref.size == 0 or ref.sum() <= 0 or cur.sum() <= 0:
+        return None
+    r = np.clip(ref / ref.sum(), PSI_EPS, None)
+    c = np.clip(cur / cur.sum(), PSI_EPS, None)
+    value = float(np.sum((c - r) * np.log(c / r)))
+    if not math.isfinite(value):
+        return None
+    return max(value, 0.0)
+
+
+def ks_test(reference: np.ndarray, current: np.ndarray) -> Tuple[Optional[float], Optional[float]]:
+    """Two-sample Kolmogorov-Smirnov test; ``(None, None)`` when a side is empty."""
+    if reference.size == 0 or current.size == 0:
+        return None, None
+    result = sps.ks_2samp(reference, current)
+    return float(result.statistic), float(result.pvalue)
+
+
+def chi2_test(table: np.ndarray) -> Tuple[Optional[float], Optional[float]]:
+    """Chi-square test of independence on a 2 x K count table.
+
+    Returns ``(None, None)`` when a row is empty, and ``(0.0, 1.0)`` for a single
+    category (zero degrees of freedom).
+    """
+    table = np.asarray(table, dtype="float64")
+    if table.ndim != 2 or table.shape[1] == 0 or np.any(table.sum(axis=1) <= 0):
+        return None, None
+    if table.shape[1] == 1:
+        return 0.0, 1.0
+    result = sps.chi2_contingency(table)
+    return float(result[0]), float(result[1])
+
+
+# --------------------------------------------------------------------------- stats
+
+
+def _format_datetime(ns: Any) -> str:
+    return pd.Timestamp(int(ns)).isoformat()
+
+
+def _format_timedelta(ns: Any) -> str:
+    return str(pd.Timedelta(int(ns)))
+
+
+def numeric_stats(cv: ColumnValues, dtype: str) -> Dict[str, Any]:
+    """Descriptive stats for a numeric column (datetimes and timedeltas as strings)."""
+    v = cv.values
+    out: Dict[str, Any] = {
+        "dtype": dtype,
+        "count": int(v.size),
+        "missing_share": round(cv.missing_share, 6),
+    }
+    if cv.family == "number":
+        keys = ("mean", "std", "min", "median", "max")
+        if v.size:
+            vals: Tuple[Any, ...] = (
+                float(v.mean()),
+                float(v.std()),
+                float(v.min()),
+                float(np.median(v)),
+                float(v.max()),
+            )
+        else:
+            vals = (None,) * len(keys)
+    else:
+        fmt = _format_datetime if cv.family == "datetime" else _format_timedelta
+        keys = ("min", "median", "max")
+        vals = (fmt(v.min()), fmt(np.median(v)), fmt(v.max())) if v.size else (None,) * len(keys)
+    out.update(zip(keys, vals))
+    return out
+
+
+def category_stats(cv: ColumnValues, counts: Dict[str, int], dtype: str) -> Dict[str, Any]:
+    """Descriptive stats for a categorical column, including its top categories."""
+    total = sum(counts.values())
+    top = {cat: round(n / total, 6) for cat, n in list(counts.items())[:TOP_CATEGORIES]} if total else {}
+    return {
+        "dtype": dtype,
+        "count": int(cv.values.size),
+        "missing_share": round(cv.missing_share, 6),
+        "n_categories": len(counts),
+        "top": top,
+    }

data_drift_lite/cli.py

@@ -0,0 +1,108 @@
+"""Command line interface: ``data-drift-lite reference.csv current.csv [options]``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Optional, Sequence
+
+from . import __version__
+from ._core import detect
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """The argparse parser for the ``data-drift-lite`` command."""
+    parser = argparse.ArgumentParser(
+        prog="data-drift-lite",
+        description="Detect whether current data has drifted from reference data, column by column.",
+    )
+    parser.add_argument("reference", help="reference dataset (.csv or .parquet), e.g. the training data")
+    parser.add_argument("current", help="current dataset (.csv or .parquet), e.g. a production batch")
+    parser.add_argument(
+        "--columns", nargs="+", metavar="COL", help="compare only these columns (default: every reference column)"
+    )
+    parser.add_argument(
+        "--threshold",
+        type=float,
+        default=0.05,
+        metavar="P",
+        help="p-value below which a column counts as drifted (default: 0.05)",
+    )
+    parser.add_argument(
+        "--psi-threshold",
+        type=float,
+        default=0.2,
+        metavar="PSI",
+        help="PSI above which a column counts as drifted (default: 0.2)",
+    )
+    parser.add_argument(
+        "--sample",
+        type=int,
+        default=100_000,
+        metavar="N",
+        help="cap each dataset at N random rows; 0 disables sampling (default: 100000)",
+    )
+    parser.add_argument(
+        "--random-state", type=int, default=0, metavar="SEED", help="seed for the sampling (default: 0)"
+    )
+    parser.add_argument("--json", action="store_true", help="print the full report as JSON instead of the summary")
+    parser.add_argument("--output", metavar="PATH", help="also write the full report as JSON to PATH")
+    parser.add_argument(
+        "--fail-on-drift",
+        action="store_true",
+        help="exit with status 1 when drift is detected (handy in CI and cron jobs)",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return parser
+
+
+def _configure_streams() -> None:
+    """Make stdout/stderr UTF-8 tolerant so non-Latin column names never raise."""
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            try:
+                stream.reconfigure(encoding="utf-8", errors="replace")
+            except (ValueError, OSError):  # pragma: no cover - exotic stream
+                pass
+
+
+def _emit(text: str) -> None:
+    try:
+        print(text)
+    except UnicodeEncodeError:  # pragma: no cover - only when reconfigure was unavailable
+        encoding = getattr(sys.stdout, "encoding", None) or "ascii"
+        print(text.encode(encoding, errors="replace").decode(encoding))
+
+
+def _as_json(payload: object) -> str:
+    return json.dumps(payload, indent=2, ensure_ascii=False)
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """Entry point. Returns the process exit status."""
+    _configure_streams()
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        report = detect(
+            args.reference,
+            args.current,
+            columns=args.columns,
+            threshold=args.threshold,
+            psi_threshold=args.psi_threshold,
+            sample=args.sample or None,
+            random_state=args.random_state,
+        )
+    except (ValueError, TypeError, ImportError, OSError) as exc:
+        parser.error(str(exc))
+    payload = report.to_dict()
+    _emit(_as_json(payload) if args.json else report.summary())
+    if args.output:
+        Path(args.output).write_text(_as_json(payload), encoding="utf-8")
+    return 1 if (args.fail_on_drift and report.drifted) else 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

data_drift_lite-0.1.0.dist-info/METADATA

@@ -0,0 +1,165 @@
+Metadata-Version: 2.5
+Name: data-drift-lite
+Version: 0.1.0
+Summary: Detect whether production data has drifted from training data, column by column, with a single call
+Project-URL: Homepage, https://pypi.org/project/data-drift-lite/
+Project-URL: Author, https://pypi.org/user/pranaymahendrakar/
+Author: Pranay Mahendrakar
+License-Expression: MIT
+License-File: LICENSE
+Keywords: data drift,drift detection,kolmogorov-smirnov,mlops,model monitoring,pandas,population stability index,psi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: scipy>=1.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=12; extra == 'parquet'
+Description-Content-Type: text/markdown
+
+# data-drift-lite
+
+Detect whether production data has drifted from training data, column by column, with a single call.
+
+## Install
+
+```
+pip install data-drift-lite
+```
+
+Reading `.parquet` files needs `pip install "data-drift-lite[parquet]"`.
+
+## Quickstart
+
+```python
+import pandas as pd
+import data_drift_lite
+
+reference = pd.DataFrame({"age": list(range(20, 60, 2)), "plan": ["basic", "pro"] * 10})
+current = pd.DataFrame({"age": list(range(50, 90, 2)), "plan": ["pro"] * 18 + ["enterprise"] * 2})
+report = data_drift_lite.detect(reference, current)
+print(report.summary())
+```
+
+Prints:
+
+```
+data-drift-lite: DRIFT DETECTED: 2 of 2 columns drifted (100%)
+reference rows: 20 | current rows: 20 | drifted when p < 0.05 or PSI > 0.2
+
+  column  kind         test  statistic  p-value     PSI  status
+  age     numeric      ks       0.7500  9.5e-06  6.4703  DRIFTED
+  plan    categorical  chi2    14.2857   0.0008  5.1829  DRIFTED
+
+notes:
+  - plan: 1 category unseen in reference: 'enterprise'
+```
+
+Then `report.drifted` is `True`, `report.drifted_columns` is `["age", "plan"]`, and
+`report.to_dict()` is ready for `json.dumps`.
+
+## What it checks
+
+- **Numeric columns** (ints, floats, nullable ints/floats; datetimes and timedeltas
+  are compared as int64 nanoseconds): a two-sample Kolmogorov-Smirnov test
+  (`scipy.stats.ks_2samp`) plus the Population Stability Index over 10 quantile
+  bins built from the reference.
+- **Categorical columns** (strings, objects, `category`, and bool): a chi-square
+  test on category frequencies (`scipy.stats.chi2_contingency`) plus PSI over the
+  reference categories, with every category the reference never saw pooled into a
+  single extra bin.
+- A column is **drifted** when `p_value < threshold` (default 0.05) **or**
+  `psi > psi_threshold` (default 0.2). Pass `None` for either to switch that rule off.
+- **Missing values count.** They form their own bin for PSI (and their own category
+  in the chi-square table), so a column whose values start disappearing is flagged
+  even when the values that remain look the same. The KS test uses the non-missing
+  values. `+inf`/`-inf` are treated as missing.
+- **Schema drift** is reported alongside: columns missing from the current data,
+  new columns, and columns whose type family changed (for example `int64 -> object`).
+  Missing columns and type changes set `report.drifted`; new columns are listed but
+  do not raise the flag.
+- **Guard rails.** Constant columns get PSI 0, never NaN or inf. Numeric columns with
+  ten or fewer distinct values get one bin per value, so a 95/5 to 5/95 flip in a
+  0/1 column is caught. A reference or batch with fewer than 20 rows produces a
+  warning note in the report (and a `logging` warning) instead of a crash. Each side
+  is capped at `sample` random rows (default 100,000, seeded by `random_state`) so a
+  check stays fast on big tables.
+
+## API
+
+### `detect(reference, current, *, columns=None, threshold=0.05, psi_threshold=0.2, sample=100_000, random_state=0) -> DriftReport`
+
+The one-call path. `reference` and `current` accept a pandas DataFrame, a Series,
+or a path to a `.csv` / `.parquet` file.
+
+- `columns`: compare only these columns (default: every reference column).
+- `threshold`: p-value below which a column is drifted; `None` disables the rule.
+- `psi_threshold`: PSI above which a column is drifted; `None` disables the rule.
+- `sample`: cap each side at this many random rows; `None` uses every row.
+- `random_state`: seed for that sampling, so results are reproducible.
+
+### `DriftMonitor(reference, *, columns=None, threshold=0.05, psi_threshold=0.2, sample=100_000, random_state=0)`
+
+Profiles the reference once; `monitor.check(batch)` returns a `DriftReport` for
+each batch. Use it when scoring many batches against the same training data.
+
+```python
+monitor = data_drift_lite.DriftMonitor(train_df, psi_threshold=0.1)
+for batch in batches:
+    report = monitor.check(batch)
+    if report.drifted:
+        alert(report.summary())
+```
+
+### `DriftReport`
+
+| attribute / method | meaning |
+| --- | --- |
+| `columns` | `dict[column -> ColumnDrift]` for every compared column, in reference order |
+| `drifted_columns` | `list[str]` of the columns flagged as drifted |
+| `drift_share` | fraction of compared columns that drifted |
+| `drifted` | `True` if any column drifted, a column is missing, or a dtype changed |
+| `missing_columns`, `new_columns`, `dtype_changed` | schema drift; `dtype_changed` maps `column -> (reference dtype, current dtype)` |
+| `schema` | the same three as a `SchemaDrift` dataclass with its own `.drifted` and `.to_dict()` |
+| `reference_rows`, `current_rows`, `threshold`, `psi_threshold`, `notes` | what the check ran on |
+| `summary()` | human-readable text (also what `str(report)` returns) |
+| `to_dict()` | JSON-safe dict: plain Python numbers, `None` for anything not computable |
+
+### `ColumnDrift`
+
+Dataclass with `kind` (`"numeric"` or `"categorical"`), `test` (`"ks"` or `"chi2"`),
+`statistic`, `p_value`, `psi`, `drifted`, `reference_stats`, `current_stats`,
+`name`, `notes`, and `to_dict()`. Stats hold `dtype`, `count`, `missing_share`,
+then `mean`/`std`/`min`/`median`/`max` for numeric columns (ISO strings for
+datetimes) or `n_categories` and the `top` category shares for categorical ones.
+Any statistic that could not be computed is `None`, and `notes` says why.
+
+## CLI
+
+```
+data-drift-lite train.csv batch.csv
+data-drift-lite train.parquet batch.parquet --columns age plan --psi-threshold 0.1
+data-drift-lite train.csv batch.csv --json
+data-drift-lite train.csv batch.csv --output report.json --fail-on-drift
+```
+
+`data-drift-lite REFERENCE CURRENT` prints the summary. Options:
+
+- `--columns COL [COL ...]`, `--threshold P`, `--psi-threshold PSI`,
+  `--sample N` (0 disables sampling), `--random-state SEED` mirror `detect()`.
+- `--json` prints `to_dict()` as JSON instead of the summary.
+- `--output PATH` also writes that JSON to a file.
+- `--fail-on-drift` exits with status 1 when drift is detected, for CI and cron jobs.
+- `--version`, `--help`.
+
+## License
+
+MIT

data_drift_lite-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+data_drift_lite/__init__.py,sha256=ADd1a1sltU8Fe0ISL2kzI2a3lclCbI3rPVOCvM5af7w,505
+data_drift_lite/__main__.py,sha256=Q7_LIfYSfVKNW9ul9YyA6XK-kcZFgE64J9Un9ZlbfGQ,153
+data_drift_lite/_core.py,sha256=r7W67v-W7AyYwVMRivRTso_mCJ4Ddp5Q7MpyWbSmiX4,14162
+data_drift_lite/_io.py,sha256=wbUjnTLF5nfO0yzmoueXzqGJGrqmx73IKSDq9nSa4Ng,1734
+data_drift_lite/_report.py,sha256=yTutRj53gs9SOZo_oF4ta61cZI_XvYDHBrQDuRzyH1s,9782
+data_drift_lite/_stats.py,sha256=hKIyi9A-fjmcsiRvjf9NCU4i91WaCLPfCuZDBpZGNnU,8678
+data_drift_lite/cli.py,sha256=i3m3-UHNMwbWvoVDlbENr0fJeLkD5DAN1drEvjrsrLM,3981
+data_drift_lite-0.1.0.dist-info/METADATA,sha256=aivwYShb3DSa-8qkGbOhzMry93b9xllldde_mvP6OgI,7187
+data_drift_lite-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+data_drift_lite-0.1.0.dist-info/entry_points.txt,sha256=IX0EXyuz4u3rl8mBopXDTb1VSMkyqcpoPkTltPhQNes,61
+data_drift_lite-0.1.0.dist-info/licenses/LICENSE,sha256=tAQiayNS3nK2VTEQSvK_ogaTFLAd8pAwIMd15JFkOQ4,1075
+data_drift_lite-0.1.0.dist-info/RECORD,,

data_drift_lite-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

data_drift_lite-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+data-drift-lite = data_drift_lite.cli:main

data_drift_lite-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pranay Mahendrakar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.