driftwatch 0.2.0__py3-none-any.whl

driftwatch/detectors/categorical.py

@@ -0,0 +1,145 @@
+"""Categorical feature drift detectors."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+from scipy import stats
+
+from driftwatch.detectors.base import BaseDetector, DetectionResult
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+class ChiSquaredDetector(BaseDetector):
+    """
+    Chi-Squared test for categorical drift detection.
+
+    Tests whether the frequency distribution of categories
+    has changed between reference and production data.
+
+    Args:
+        threshold: P-value threshold below which drift is detected.
+            Default is 0.05 (95% confidence).
+
+    Example:
+        >>> detector = ChiSquaredDetector(threshold=0.05)
+        >>> result = detector.detect(reference_series, production_series)
+    """
+
+    def __init__(self, threshold: float = 0.05) -> None:
+        super().__init__(threshold=threshold, name="chi_squared")
+
+    def detect(
+        self,
+        reference: pd.Series,
+        production: pd.Series,
+    ) -> DetectionResult:
+        """
+        Perform Chi-Squared test on category frequencies.
+
+        Returns:
+            DetectionResult with chi-squared statistic and p-value
+        """
+        self._validate_inputs(reference, production)
+
+        # Get all categories from both datasets
+        all_categories = set(reference.dropna().unique()) | set(
+            production.dropna().unique()
+        )
+
+        # Count frequencies
+        ref_counts = reference.value_counts()
+        prod_counts = production.value_counts()
+
+        # Align to same categories
+        ref_freq = np.array([ref_counts.get(cat, 0) for cat in all_categories])
+        prod_freq = np.array([prod_counts.get(cat, 0) for cat in all_categories])
+
+        # Handle edge case of zero frequencies
+        if ref_freq.sum() == 0 or prod_freq.sum() == 0:
+            return DetectionResult(
+                has_drift=True,
+                score=float("inf"),
+                method=self.name,
+                threshold=self.threshold,
+                p_value=0.0,
+            )
+
+        # Calculate expected frequencies based on reference proportions
+        ref_proportions = ref_freq / ref_freq.sum()
+        expected = ref_proportions * prod_freq.sum()
+
+        # Add small epsilon to avoid division by zero
+        expected = np.maximum(expected, 1e-10)
+
+        # Chi-squared statistic
+        statistic, p_value = stats.chisquare(prod_freq, f_exp=expected)
+
+        return DetectionResult(
+            has_drift=p_value < self.threshold,
+            score=float(statistic),
+            method=self.name,
+            threshold=self.threshold,
+            p_value=float(p_value),
+        )
+
+
+class FrequencyPSIDetector(BaseDetector):
+    """
+    PSI-based detector for categorical features.
+
+    Calculates PSI using category frequency distributions
+    instead of numerical buckets.
+
+    Args:
+        threshold: PSI value above which drift is detected.
+            Default is 0.2.
+    """
+
+    def __init__(self, threshold: float = 0.2) -> None:
+        super().__init__(threshold=threshold, name="frequency_psi")
+
+    def detect(
+        self,
+        reference: pd.Series,
+        production: pd.Series,
+    ) -> DetectionResult:
+        """
+        Calculate PSI on category frequencies.
+
+        Returns:
+            DetectionResult with PSI score
+        """
+        self._validate_inputs(reference, production)
+
+        # Get normalized frequencies
+        ref_freq = reference.value_counts(normalize=True)
+        prod_freq = production.value_counts(normalize=True)
+
+        # Get all categories
+        all_categories = set(ref_freq.index) | set(prod_freq.index)
+
+        # Calculate PSI
+        eps = 1e-10
+        psi = 0.0
+
+        for cat in all_categories:
+            ref_pct = ref_freq.get(cat, eps)
+            prod_pct = prod_freq.get(cat, eps)
+
+            # Clip to avoid log(0)
+            ref_pct = max(ref_pct, eps)
+            prod_pct = max(prod_pct, eps)
+
+            psi += (prod_pct - ref_pct) * np.log(prod_pct / ref_pct)
+
+        return DetectionResult(
+            has_drift=psi >= self.threshold,
+            score=float(psi),
+            method=self.name,
+            threshold=self.threshold,
+            p_value=None,
+        )

driftwatch/detectors/numerical.py

@@ -0,0 +1,198 @@
+"""Numerical feature drift detectors."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+from scipy import stats
+
+from driftwatch.detectors.base import BaseDetector, DetectionResult
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+class KSDetector(BaseDetector):
+    """
+    Kolmogorov-Smirnov test for numerical drift detection.
+
+    The KS test measures the maximum distance between the cumulative
+    distribution functions of two samples.
+
+    Args:
+        threshold: P-value threshold below which drift is detected.
+            Default is 0.05 (95% confidence).
+
+    Example:
+        >>> detector = KSDetector(threshold=0.05)
+        >>> result = detector.detect(reference_series, production_series)
+        >>> print(f"Drift detected: {result.has_drift}")
+    """
+
+    def __init__(self, threshold: float = 0.05) -> None:
+        super().__init__(threshold=threshold, name="ks_test")
+
+    def detect(
+        self,
+        reference: pd.Series,
+        production: pd.Series,
+    ) -> DetectionResult:
+        """
+        Perform KS test between reference and production distributions.
+
+        Returns:
+            DetectionResult with KS statistic as score and p-value
+        """
+        self._validate_inputs(reference, production)
+
+        statistic, p_value = stats.ks_2samp(
+            reference.dropna(),
+            production.dropna(),
+        )
+
+        return DetectionResult(
+            has_drift=p_value < self.threshold,
+            score=float(statistic),
+            method=self.name,
+            threshold=self.threshold,
+            p_value=float(p_value),
+        )
+
+
+class PSIDetector(BaseDetector):
+    """
+    Population Stability Index (PSI) for numerical drift detection.
+
+    PSI measures the shift in distribution between two populations.
+    Commonly used thresholds:
+    - PSI < 0.1: No significant change
+    - 0.1 <= PSI < 0.2: Minor shift
+    - PSI >= 0.2: Significant shift (drift)
+
+    Args:
+        threshold: PSI value above which drift is detected.
+            Default is 0.2.
+        buckets: Number of buckets for binning. Default is 10.
+
+    Example:
+        >>> detector = PSIDetector(threshold=0.2, buckets=10)
+        >>> result = detector.detect(reference_series, production_series)
+    """
+
+    def __init__(self, threshold: float = 0.2, buckets: int = 10) -> None:
+        super().__init__(threshold=threshold, name="psi")
+        self.buckets = buckets
+
+    def detect(
+        self,
+        reference: pd.Series,
+        production: pd.Series,
+    ) -> DetectionResult:
+        """
+        Calculate PSI between reference and production distributions.
+
+        Returns:
+            DetectionResult with PSI score
+        """
+        self._validate_inputs(reference, production)
+
+        psi_value = self._calculate_psi(
+            np.asarray(reference.dropna().values),
+            np.asarray(production.dropna().values),
+        )
+
+        return DetectionResult(
+            has_drift=psi_value >= self.threshold,
+            score=float(psi_value),
+            method=self.name,
+            threshold=self.threshold,
+            p_value=None,
+        )
+
+    def _calculate_psi(
+        self,
+        reference: np.ndarray,
+        production: np.ndarray,
+    ) -> float:
+        """
+        Calculate PSI using percentile-based buckets.
+
+        The reference distribution defines the bucket boundaries,
+        and we compare the distribution of production data across
+        these same buckets.
+        """
+        # Create buckets based on reference quantiles
+        breakpoints = np.percentile(
+            reference,
+            np.linspace(0, 100, self.buckets + 1),
+        )
+        # Ensure unique breakpoints
+        breakpoints = np.unique(breakpoints)
+
+        if len(breakpoints) < 2:
+            # Not enough variation, return 0
+            return 0.0
+
+        # Calculate distribution in each bucket
+        ref_counts = np.histogram(reference, bins=breakpoints)[0]
+        prod_counts = np.histogram(production, bins=breakpoints)[0]
+
+        # Convert to percentages, avoiding division by zero
+        ref_pct = ref_counts / len(reference)
+        prod_pct = prod_counts / len(production)
+
+        # Add small epsilon to avoid log(0)
+        eps = 1e-10
+        ref_pct = np.clip(ref_pct, eps, 1)
+        prod_pct = np.clip(prod_pct, eps, 1)
+
+        # Calculate PSI
+        psi: float = float(np.sum((prod_pct - ref_pct) * np.log(prod_pct / ref_pct)))
+
+        return float(psi)
+
+
+class WassersteinDetector(BaseDetector):
+    """
+    Wasserstein distance (Earth Mover's Distance) for drift detection.
+
+    Measures the minimum "work" required to transform one distribution
+    into another. More sensitive to subtle distributional changes.
+
+    Args:
+        threshold: Distance above which drift is detected.
+    """
+
+    def __init__(self, threshold: float = 0.1) -> None:
+        super().__init__(threshold=threshold, name="wasserstein")
+
+    def detect(
+        self,
+        reference: pd.Series,
+        production: pd.Series,
+    ) -> DetectionResult:
+        """
+        Calculate Wasserstein distance between distributions.
+
+        Note: Values are normalized by the reference standard deviation
+        to make the threshold more interpretable.
+        """
+        self._validate_inputs(reference, production)
+
+        ref_clean = reference.dropna().values
+        prod_clean = production.dropna().values
+
+        distance = stats.wasserstein_distance(ref_clean, prod_clean)
+
+        # Normalize by reference std for interpretability
+        ref_std = np.std(ref_clean)
+        normalized_distance = distance / ref_std if ref_std > 0 else distance
+
+        return DetectionResult(
+            has_drift=normalized_distance >= self.threshold,
+            score=float(normalized_distance),
+            method=self.name,
+            threshold=self.threshold,
+            p_value=None,
+        )

driftwatch/detectors/registry.py

@@ -0,0 +1,71 @@
+"""Detector registry for automatic selection based on dtype."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from driftwatch.detectors.categorical import ChiSquaredDetector
+from driftwatch.detectors.numerical import KSDetector, PSIDetector, WassersteinDetector
+
+if TYPE_CHECKING:
+    from driftwatch.detectors.base import BaseDetector
+
+
+def get_detector(dtype: np.dtype[Any], thresholds: dict[str, float]) -> BaseDetector:
+    """
+    Get appropriate detector based on data type.
+
+    Args:
+        dtype: NumPy dtype of the feature
+        thresholds: Dictionary of threshold values
+
+    Returns:
+        Appropriate detector instance
+
+    Note:
+        - Numerical types use PSI by default
+        - Categorical/object types use Chi-Squared
+    """
+    if np.issubdtype(dtype, np.number):
+        # Use PSI for numerical features by default
+        return PSIDetector(threshold=thresholds.get("psi", 0.2))
+    else:
+        # Use Chi-Squared for categorical features
+        return ChiSquaredDetector(threshold=thresholds.get("chi2_pvalue", 0.05))
+
+
+def get_detector_by_name(
+    name: str,
+    thresholds: dict[str, float],
+) -> BaseDetector:
+    """
+    Get detector by explicit name.
+
+    Args:
+        name: Detector name ("ks", "psi", "wasserstein", "chi2")
+        thresholds: Dictionary of threshold values
+
+    Returns:
+        Requested detector instance
+
+    Raises:
+        ValueError: If detector name is unknown
+    """
+    detectors = {
+        "ks": lambda: KSDetector(threshold=thresholds.get("ks_pvalue", 0.05)),
+        "psi": lambda: PSIDetector(threshold=thresholds.get("psi", 0.2)),
+        "wasserstein": lambda: WassersteinDetector(
+            threshold=thresholds.get("wasserstein", 0.1)
+        ),
+        "chi2": lambda: ChiSquaredDetector(
+            threshold=thresholds.get("chi2_pvalue", 0.05)
+        ),
+    }
+
+    if name not in detectors:
+        available = ", ".join(detectors.keys())
+        raise ValueError(f"Unknown detector '{name}'. Available: {available}")
+
+    return detectors[name]()

driftwatch/integrations/__init__.py

@@ -0,0 +1,5 @@
+"""DriftWatch integrations for external services."""
+
+from driftwatch.integrations.fastapi import DriftMiddleware, add_drift_routes
+
+__all__ = ["DriftMiddleware", "add_drift_routes"]

driftwatch/integrations/alerting.py

@@ -0,0 +1,211 @@
+"""Alerting integrations for DriftWatch.
+
+Provides alerting mechanisms (Slack, Email, etc.) for drift detection.
+"""
+
+from __future__ import annotations
+
+import time
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+if TYPE_CHECKING:
+    from driftwatch.core.report import DriftReport
+
+
+class SlackAlerter:
+    """
+    Send drift alerts to Slack via webhook.
+
+    Formats drift reports as Slack Block Kit messages with feature-level
+    details and supports alert throttling to avoid spam.
+
+    Args:
+        webhook_url: Slack webhook URL (https://hooks.slack.com/...)
+        throttle_minutes: Minimum minutes between alerts (default: 60)
+        mention_user: Optional Slack user ID to mention (@U123ABC)
+        channel_override: Optional channel to post to (overrides webhook default)
+
+    Example:
+        ```python
+        from driftwatch.integrations.alerting import SlackAlerter
+
+        alerter = SlackAlerter(
+            webhook_url="https://hooks.slack.com/services/...",
+            throttle_minutes=60
+        )
+
+        if report.has_drift():
+            alerter.send(report)
+        ```
+    """
+
+    def __init__(
+        self,
+        webhook_url: str,
+        throttle_minutes: int = 60,
+        mention_user: str | None = None,
+        channel_override: str | None = None,
+    ) -> None:
+        self.webhook_url = webhook_url
+        self.throttle_seconds = throttle_minutes * 60
+        self.mention_user = mention_user
+        self.channel_override = channel_override
+        self._last_alert_time: float = 0.0
+
+    def send(
+        self,
+        report: DriftReport,
+        force: bool = False,
+        custom_message: str | None = None,
+    ) -> bool:
+        """
+        Send drift report to Slack.
+
+        Args:
+            report: DriftReport to send
+            force: Skip throttling check
+            custom_message: Optional custom message prefix
+
+        Returns:
+            True if alert was sent, False if throttled
+
+        Raises:
+            httpx.HTTPError: If webhook request fails
+        """
+        # Check throttling
+        if not force and self._is_throttled():
+            return False
+
+        # Build Slack message
+        blocks = self._build_blocks(report, custom_message)
+        payload: dict[str, Any] = {"blocks": blocks}
+
+        if self.channel_override:
+            payload["channel"] = self.channel_override
+
+        # Send to Slack
+        response = httpx.post(
+            self.webhook_url, json=payload, timeout=10.0, follow_redirects=True
+        )
+        response.raise_for_status()
+
+        # Update throttle timestamp
+        self._last_alert_time = time.time()
+
+        return True
+
+    def _is_throttled(self) -> bool:
+        """Check if alert should be throttled."""
+        if self._last_alert_time == 0.0:
+            return False
+
+        elapsed = time.time() - self._last_alert_time
+        return elapsed < self.throttle_seconds
+
+    def _build_blocks(
+        self, report: DriftReport, custom_message: str | None = None
+    ) -> list[dict[str, Any]]:
+        """Build Slack Block Kit message."""
+        blocks: list[dict[str, Any]] = []
+
+        # Status emoji and color
+        emoji = {"OK": "✅", "WARNING": "⚠️", "CRITICAL": "🚨"}.get(
+            report.status.value, "📊"
+        )
+
+        # Header
+        header_text = f"{emoji} *Drift Detected - DriftWatch*"
+        if custom_message:
+            header_text = f"{custom_message}\n{header_text}"
+        if self.mention_user:
+            header_text = f"<@{self.mention_user}> {header_text}"
+
+        blocks.append(
+            {"type": "header", "text": {"type": "plain_text", "text": header_text}}
+        )
+
+        # Summary section
+        summary_fields = [
+            {"type": "mrkdwn", "text": f"*Status:*\n{report.status.value}"},
+            {
+                "type": "mrkdwn",
+                "text": f"*Drift Ratio:*\n{report.drift_ratio():.1%}",
+            },
+            {
+                "type": "mrkdwn",
+                "text": f"*Affected Features:*\n{len(report.drifted_features())}/{len(report.feature_results)}",
+            },
+            {
+                "type": "mrkdwn",
+                "text": f"*Timestamp:*\n{self._format_timestamp(report.timestamp)}",
+            },
+        ]
+
+        blocks.append({"type": "section", "fields": summary_fields})
+
+        # Divider
+        blocks.append({"type": "divider"})
+
+        # Feature details (only drifted features)
+        if report.drifted_features():
+            blocks.append(
+                {
+                    "type": "section",
+                    "text": {
+                        "type": "mrkdwn",
+                        "text": "*Drifted Features:*",
+                    },
+                }
+            )
+
+            feature_details = []
+            for result in report.feature_results:
+                if result.has_drift:
+                    detail = f"• `{result.feature_name}`: {result.method.upper()}={result.score:.4f} (threshold={result.threshold:.4f})"
+                    feature_details.append(detail)
+
+            blocks.append(
+                {
+                    "type": "section",
+                    "text": {
+                        "type": "mrkdwn",
+                        "text": "\n".join(feature_details),
+                    },
+                }
+            )
+
+        # Context footer
+        context_text = "DriftWatch Monitor"
+        if report.model_version:
+            context_text += f" • Model: {report.model_version}"
+
+        blocks.append(
+            {
+                "type": "context",
+                "elements": [{"type": "mrkdwn", "text": context_text}],
+            }
+        )
+
+        return blocks
+
+    def _format_timestamp(self, timestamp: datetime) -> str:
+        """Format timestamp for Slack message."""
+        if timestamp.tzinfo is None:
+            timestamp = timestamp.replace(tzinfo=timezone.utc)
+
+        return timestamp.strftime("%Y-%m-%d %H:%M:%S UTC")
+
+    def get_next_alert_time(self) -> datetime | None:
+        """Get the earliest time the next alert can be sent."""
+        if self._last_alert_time == 0.0:
+            return None
+
+        next_time = self._last_alert_time + self.throttle_seconds
+        return datetime.fromtimestamp(next_time, tz=timezone.utc)
+
+    def reset_throttle(self) -> None:
+        """Reset throttle timer (allows immediate next alert)."""
+        self._last_alert_time = 0.0