driftwatch 0.2.0__py3-none-any.whl

driftwatch/__init__.py

@@ -0,0 +1,22 @@
+"""
+DriftWatch - Lightweight ML drift monitoring, built for real-world pipelines.
+
+DriftWatch is an open-source Python library for detecting data drift and
+model drift in machine learning systems.
+
+Basic Usage:
+    >>> from driftwatch import Monitor
+    >>> monitor = Monitor(reference_data=train_df, features=["age", "income"])
+    >>> report = monitor.check(production_df)
+    >>> print(report.summary())
+"""
+
+from driftwatch.core.monitor import Monitor
+from driftwatch.core.report import DriftReport
+
+__version__ = "0.2.0"
+__all__ = [
+    "DriftReport",
+    "Monitor",
+    "__version__",
+]

driftwatch/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Command-line interface for DriftWatch."""
+
+from driftwatch.cli.main import app
+
+__all__ = ["app"]

driftwatch/cli/main.py

@@ -0,0 +1,274 @@
+"""Main CLI application for DriftWatch.
+
+Provides commands for drift checking and reporting.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path  # noqa: TC003
+from typing import Annotated
+
+import pandas as pd
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from driftwatch import Monitor
+from driftwatch.core.report import DriftReport, DriftStatus
+
+app = typer.Typer(
+    name="driftwatch",
+    help="🔍 DriftWatch - ML Model Drift Detection",
+    add_completion=False,
+)
+console = Console()
+
+
+def load_dataframe(path: Path) -> pd.DataFrame:
+    """Load dataframe from CSV or Parquet file.
+
+    Args:
+        path: Path to the file
+
+    Returns:
+        Loaded pandas DataFrame
+
+    Raises:
+        typer.BadParameter: If file format is not supported
+    """
+    if path.suffix.lower() == ".csv":
+        return pd.read_csv(path)
+    elif path.suffix.lower() in [".parquet", ".pq"]:
+        return pd.read_parquet(path)
+    else:
+        raise typer.BadParameter(
+            f"Unsupported file format: {path.suffix}. Use .csv or .parquet"
+        )
+
+
+@app.command()
+def check(
+    ref: Annotated[
+        Path,
+        typer.Option(
+            "--ref",
+            "-r",
+            help="Path to reference dataset (CSV or Parquet)",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+        ),
+    ],
+    prod: Annotated[
+        Path,
+        typer.Option(
+            "--prod",
+            "-p",
+            help="Path to production dataset (CSV or Parquet)",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+        ),
+    ],
+    threshold_psi: Annotated[
+        float, typer.Option("--threshold-psi", help="PSI threshold (default: 0.2)")
+    ] = 0.2,
+    threshold_ks: Annotated[
+        float,
+        typer.Option("--threshold-ks", help="KS p-value threshold (default: 0.05)"),
+    ] = 0.05,
+    threshold_chi2: Annotated[
+        float,
+        typer.Option(
+            "--threshold-chi2", help="Chi-squared p-value threshold (default: 0.05)"
+        ),
+    ] = 0.05,
+    output: Annotated[
+        Path | None,
+        typer.Option("--output", "-o", help="Save report to JSON file"),
+    ] = None,
+) -> None:
+    """Check for drift between reference and production datasets.
+
+    Example:
+        driftwatch check --ref train.csv --prod prod.csv
+        driftwatch check -r train.parquet -p prod.parquet --threshold-psi 0.15
+    """
+    console.print("[bold blue]🔍 DriftWatch - Drift Detection[/bold blue]\n")
+
+    # Load datasets
+    console.print(f"Loading reference data from [cyan]{ref}[/cyan]...")
+    ref_df = load_dataframe(ref)
+    console.print(
+        f"✓ Loaded {len(ref_df):,} samples with {len(ref_df.columns)} features\n"
+    )
+
+    console.print(f"Loading production data from [cyan]{prod}[/cyan]...")
+    prod_df = load_dataframe(prod)
+    console.print(
+        f"✓ Loaded {len(prod_df):,} samples with {len(prod_df.columns)} features\n"
+    )
+
+    # Create monitor
+    console.print("Initializing monitor...")
+    monitor = Monitor(
+        reference_data=ref_df,
+        thresholds={
+            "psi": threshold_psi,
+            "ks_pvalue": threshold_ks,
+            "chi2_pvalue": threshold_chi2,
+        },
+    )
+
+    # Run drift check
+    console.print("Running drift detection...\n")
+    report = monitor.check(prod_df)
+
+    # Display results
+    _display_report(report)
+
+    # Save to file if requested
+    if output:
+        output.write_text(json.dumps(report.to_dict(), indent=2), encoding="utf-8")
+        console.print(f"\n✓ Report saved to [cyan]{output}[/cyan]")
+
+    # Exit with appropriate code
+    if report.status == DriftStatus.CRITICAL:
+        raise typer.Exit(code=2)
+    elif report.status == DriftStatus.WARNING:
+        raise typer.Exit(code=1)
+    else:
+        raise typer.Exit(code=0)
+
+
+@app.command()
+def report(
+    input_file: Annotated[
+        Path,
+        typer.Argument(
+            help="Path to drift report JSON file",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+        ),
+    ],
+    format: Annotated[
+        str,
+        typer.Option(
+            "--format",
+            "-f",
+            help="Output format (table or json)",
+        ),
+    ] = "table",
+    output: Annotated[
+        Path | None,
+        typer.Option("--output", "-o", help="Save output to file"),
+    ] = None,
+) -> None:
+    """Display a drift report from a JSON file.
+
+    Example:
+        driftwatch report drift_report.json
+        driftwatch report drift_report.json --format json
+        driftwatch report drift_report.json --format table --output report.txt
+    """
+    # Load report
+    data = json.loads(input_file.read_text(encoding="utf-8"))
+
+    # Reconstruct report (basic reconstruction)
+    # In a real scenario, you'd have a from_dict method
+    if format == "json":
+        output_str = json.dumps(data, indent=2)
+        if output:
+            output.write_text(output_str, encoding="utf-8")
+            console.print(f"✓ Report saved to [cyan]{output}[/cyan]")
+        else:
+            console.print(output_str)
+    else:
+        # Table format
+        _display_dict_report(data)
+        if output:
+            # For table output to file, we'd need to capture the rich output
+            console.print(
+                "[yellow]Warning: Table output to file not yet implemented. Use --format json[/yellow]"
+            )
+
+
+def _display_report(report: DriftReport) -> None:
+    """Display drift report with Rich formatting."""
+    # Status
+    status_colors = {
+        DriftStatus.OK: "green",
+        DriftStatus.WARNING: "yellow",
+        DriftStatus.CRITICAL: "red",
+    }
+    color = status_colors.get(report.status, "white")
+    console.print(f"[bold {color}]Status: {report.status.value}[/bold {color}]")
+
+    if report.has_drift():
+        console.print(
+            f"[{color}]Drift Detected: {len(report.drifted_features())}/{len(report.feature_results)} features[/{color}]"
+        )
+        console.print(f"[{color}]Drift Ratio: {report.drift_ratio():.1%}[/{color}]\n")
+    else:
+        console.print("[green]No drift detected ✓[/green]\n")
+
+    # Feature table
+    console.print("[bold]Feature Analysis:[/bold]\n")
+
+    table = Table(show_header=True, header_style="bold cyan")
+    table.add_column("Feature", style="cyan")
+    table.add_column("Method")
+    table.add_column("Score", justify="right")
+    table.add_column("Threshold", justify="right")
+    table.add_column("Status")
+
+    for result in report.feature_results:
+        status_str = "⚠️ DRIFT" if result.has_drift else "✓ OK"
+        status_color = "red" if result.has_drift else "green"
+
+        table.add_row(
+            result.feature_name,
+            result.method,
+            f"{result.score:.4f}",
+            f"{result.threshold:.4f}",
+            f"[{status_color}]{status_str}[/{status_color}]",
+        )
+
+    console.print(table)
+
+
+def _display_dict_report(data: dict) -> None:
+    """Display drift report from dictionary data."""
+    console.print(f"[bold]Status:[/bold] {data.get('status', 'UNKNOWN')}")
+
+    if data.get("feature_results"):
+        table = Table(show_header=True, header_style="bold cyan")
+        table.add_column("Feature", style="cyan")
+        table.add_column("Method")
+        table.add_column("Score", justify="right")
+        table.add_column("Threshold", justify="right")
+        table.add_column("Status")
+
+        for result in data["feature_results"]:
+            has_drift = result.get("has_drift", False)
+            status_str = "⚠️ DRIFT" if has_drift else "✓ OK"
+            status_color = "red" if has_drift else "green"
+
+            table.add_row(
+                result["feature_name"],
+                result["method"],
+                f"{result['score']:.4f}",
+                f"{result['threshold']:.4f}",
+                f"[{status_color}]{status_str}[/{status_color}]",
+            )
+
+        console.print(table)
+
+
+if __name__ == "__main__":
+    app()

driftwatch/core/__init__.py

@@ -0,0 +1,6 @@
+"""Core module containing the main Monitor and DriftReport classes."""
+
+from driftwatch.core.monitor import Monitor
+from driftwatch.core.report import DriftReport
+
+__all__ = ["DriftReport", "Monitor"]

driftwatch/core/monitor.py

@@ -0,0 +1,153 @@
+"""
+Monitor class for detecting drift between reference and production data.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from driftwatch.core.report import DriftReport, FeatureDriftResult
+from driftwatch.detectors import get_detector
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+    from driftwatch.detectors.base import BaseDetector
+
+
+class Monitor:
+    """
+    Main class for monitoring data and model drift.
+
+    The Monitor compares production data against a reference dataset
+    (typically training data) to detect distribution shifts.
+
+    Args:
+        reference_data: Reference DataFrame (training data)
+        features: List of feature columns to monitor.
+            If None, all columns are monitored.
+        model: Optional ML model for prediction drift detection
+        thresholds: Dictionary of threshold values for drift detection.
+            Supported keys: "psi", "ks_pvalue", "wasserstein", "chi2_pvalue"
+
+    Example:
+        >>> monitor = Monitor(
+        ...     reference_data=train_df,
+        ...     features=["age", "income", "category"],
+        ...     thresholds={"psi": 0.2, "ks_pvalue": 0.05}
+        ... )
+        >>> report = monitor.check(production_df)
+        >>> print(report.has_drift())
+    """
+
+    DEFAULT_THRESHOLDS: ClassVar[dict[str, float]] = {
+        "psi": 0.2,
+        "ks_pvalue": 0.05,
+        "wasserstein": 0.1,
+        "chi2_pvalue": 0.05,
+    }
+
+    def __init__(
+        self,
+        reference_data: pd.DataFrame,
+        features: list[str] | None = None,
+        model: Any | None = None,
+        thresholds: dict[str, float] | None = None,
+    ) -> None:
+        self._validate_reference_data(reference_data)
+
+        self.reference_data = reference_data
+        self.features = features or list(reference_data.columns)
+        self.model = model
+        self.thresholds = {**self.DEFAULT_THRESHOLDS, **(thresholds or {})}
+
+        self._detectors: dict[str, BaseDetector] = {}
+        self._setup_detectors()
+
+    def _validate_reference_data(self, data: pd.DataFrame) -> None:
+        """Validate reference data is not empty."""
+        if data.empty:
+            raise ValueError("Reference data cannot be empty")
+
+    def _setup_detectors(self) -> None:
+        """Initialize detectors for each feature based on dtype."""
+        for feature in self.features:
+            if feature not in self.reference_data.columns:
+                raise ValueError(f"Feature '{feature}' not found in reference data")
+
+            dtype = self.reference_data[feature].dtype
+            detector = get_detector(dtype, self.thresholds)
+            self._detectors[feature] = detector
+
+    def check(self, production_data: pd.DataFrame) -> DriftReport:
+        """
+        Check for drift between reference and production data.
+
+        Args:
+            production_data: Production DataFrame to compare
+
+        Returns:
+            DriftReport containing per-feature and aggregate drift results
+
+        Raises:
+            ValueError: If production data is empty or missing features
+        """
+        self._validate_production_data(production_data)
+
+        feature_results: list[FeatureDriftResult] = []
+
+        for feature in self.features:
+            ref_series = self.reference_data[feature]
+            prod_series = production_data[feature]
+
+            detector = self._detectors[feature]
+            result = detector.detect(ref_series, prod_series)
+
+            feature_results.append(
+                FeatureDriftResult(
+                    feature_name=feature,
+                    has_drift=result.has_drift,
+                    score=result.score,
+                    method=result.method,
+                    threshold=result.threshold,
+                    p_value=result.p_value,
+                )
+            )
+
+        return DriftReport(
+            feature_results=feature_results,
+            reference_size=len(self.reference_data),
+            production_size=len(production_data),
+        )
+
+    def _validate_production_data(self, data: pd.DataFrame) -> None:
+        """Validate production data has required features."""
+        if data.empty:
+            raise ValueError("Production data cannot be empty")
+
+        missing = set(self.features) - set(data.columns)
+        if missing:
+            raise ValueError(f"Missing features in production data: {missing}")
+
+    def add_feature(self, feature: str) -> None:
+        """Add a feature to monitor."""
+        if feature in self.features:
+            return
+
+        if feature not in self.reference_data.columns:
+            raise ValueError(f"Feature '{feature}' not found in reference data")
+
+        self.features.append(feature)
+        dtype = self.reference_data[feature].dtype
+        self._detectors[feature] = get_detector(dtype, self.thresholds)
+
+    def remove_feature(self, feature: str) -> None:
+        """Remove a feature from monitoring."""
+        if feature in self.features:
+            self.features.remove(feature)
+            del self._detectors[feature]
+
+    @property
+    def monitored_features(self) -> list[str]:
+        """Return list of monitored features."""
+        return self.features.copy()

driftwatch/core/report.py

@@ -0,0 +1,162 @@
+"""
+DriftReport class for structured drift detection results.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+
+class DriftStatus(str, Enum):
+    """Overall drift status levels."""
+
+    OK = "OK"
+    WARNING = "WARNING"
+    CRITICAL = "CRITICAL"
+
+
+@dataclass
+class FeatureDriftResult:
+    """Result of drift detection for a single feature."""
+
+    feature_name: str
+    has_drift: bool
+    score: float
+    method: str
+    threshold: float
+    p_value: float | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "feature_name": self.feature_name,
+            "has_drift": self.has_drift,
+            "score": self.score,
+            "method": self.method,
+            "threshold": self.threshold,
+            "p_value": self.p_value,
+        }
+
+
+@dataclass
+class DriftReport:
+    """
+    Comprehensive report of drift detection results.
+
+    Contains per-feature metrics and aggregate status.
+
+    Attributes:
+        feature_results: List of per-feature drift results
+        reference_size: Number of samples in reference data
+        production_size: Number of samples in production data
+        timestamp: When the check was performed
+        model_version: Optional model version identifier
+    """
+
+    feature_results: list[FeatureDriftResult]
+    reference_size: int
+    production_size: int
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    model_version: str | None = None
+
+    def has_drift(self) -> bool:
+        """Check if any feature has drift."""
+        return any(r.has_drift for r in self.feature_results)
+
+    def drifted_features(self) -> list[str]:
+        """Return list of features with detected drift."""
+        return [r.feature_name for r in self.feature_results if r.has_drift]
+
+    def drift_ratio(self) -> float:
+        """Return ratio of drifted features to total features."""
+        if not self.feature_results:
+            return 0.0
+        return len(self.drifted_features()) / len(self.feature_results)
+
+    @property
+    def status(self) -> DriftStatus:
+        """
+        Determine overall drift status.
+
+        - OK: No drift detected
+        - WARNING: <50% of features have drift
+        - CRITICAL: >=50% of features have drift
+        """
+        ratio = self.drift_ratio()
+        if ratio == 0:
+            return DriftStatus.OK
+        elif ratio < 0.5:
+            return DriftStatus.WARNING
+        else:
+            return DriftStatus.CRITICAL
+
+    def feature_drift(self, feature_name: str) -> FeatureDriftResult | None:
+        """Get drift result for a specific feature."""
+        for result in self.feature_results:
+            if result.feature_name == feature_name:
+                return result
+        return None
+
+    def summary(self) -> str:
+        """
+        Generate a human-readable summary of the drift report.
+
+        Returns:
+            Formatted string summary
+        """
+        lines = [
+            "=" * 50,
+            "DRIFT REPORT",
+            "=" * 50,
+            f"Status: {self.status.value}",
+            f"Timestamp: {self.timestamp.isoformat()}",
+            f"Reference samples: {self.reference_size:,}",
+            f"Production samples: {self.production_size:,}",
+            "",
+            f"Features analyzed: {len(self.feature_results)}",
+            f"Features with drift: {len(self.drifted_features())}",
+            f"Drift ratio: {self.drift_ratio():.1%}",
+            "",
+        ]
+
+        if self.drifted_features():
+            lines.append("Drifted features:")
+            for result in self.feature_results:
+                if result.has_drift:
+                    lines.append(
+                        f"  - {result.feature_name}: "
+                        f"{result.method}={result.score:.4f} "
+                        f"(threshold={result.threshold})"
+                    )
+
+        lines.append("=" * 50)
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert report to dictionary."""
+        return {
+            "status": self.status.value,
+            "timestamp": self.timestamp.isoformat(),
+            "reference_size": self.reference_size,
+            "production_size": self.production_size,
+            "model_version": self.model_version,
+            "has_drift": self.has_drift(),
+            "drift_ratio": self.drift_ratio(),
+            "drifted_features": self.drifted_features(),
+            "feature_results": [r.to_dict() for r in self.feature_results],
+        }
+
+    def to_json(self, indent: int = 2) -> str:
+        """Convert report to JSON string."""
+        return json.dumps(self.to_dict(), indent=indent, default=str)
+
+    def __repr__(self) -> str:
+        return (
+            f"DriftReport(status={self.status.value}, "
+            f"features={len(self.feature_results)}, "
+            f"drifted={len(self.drifted_features())})"
+        )

driftwatch/detectors/__init__.py

@@ -0,0 +1,6 @@
+"""Drift detectors module."""
+
+from driftwatch.detectors.base import BaseDetector, DetectionResult
+from driftwatch.detectors.registry import get_detector
+
+__all__ = ["BaseDetector", "DetectionResult", "get_detector"]

driftwatch/detectors/base.py

@@ -0,0 +1,67 @@
+"""Base class for drift detectors."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+@dataclass
+class DetectionResult:
+    """Result from a drift detection test."""
+
+    has_drift: bool
+    score: float
+    method: str
+    threshold: float
+    p_value: float | None = None
+
+
+class BaseDetector(ABC):
+    """
+    Abstract base class for drift detectors.
+
+    All drift detection methods should inherit from this class
+    and implement the `detect` method.
+
+    Args:
+        threshold: Threshold value for determining drift
+        name: Human-readable name for the detector
+    """
+
+    def __init__(self, threshold: float, name: str) -> None:
+        self.threshold = threshold
+        self.name = name
+
+    @abstractmethod
+    def detect(
+        self,
+        reference: pd.Series,
+        production: pd.Series,
+    ) -> DetectionResult:
+        """
+        Detect drift between reference and production data.
+
+        Args:
+            reference: Reference data series
+            production: Production data series
+
+        Returns:
+            DetectionResult with drift status and metrics
+        """
+        ...
+
+    def _validate_inputs(
+        self,
+        reference: pd.Series,
+        production: pd.Series,
+    ) -> None:
+        """Validate input series are not empty."""
+        if reference.empty:
+            raise ValueError("Reference series cannot be empty")
+        if production.empty:
+            raise ValueError("Production series cannot be empty")