detectkit 0.1.0__py3-none-any.whl

detectkit/detectors/factory.py

@@ -0,0 +1,138 @@
+"""
+Detector factory for creating detector instances from configuration.
+"""
+
+from typing import Dict, List
+
+from detectkit.detectors.base import BaseDetector
+from detectkit.detectors.statistical.iqr import IQRDetector
+from detectkit.detectors.statistical.mad import MADDetector
+from detectkit.detectors.statistical.manual_bounds import ManualBoundsDetector
+from detectkit.detectors.statistical.zscore import ZScoreDetector
+
+
+class DetectorFactory:
+    """
+    Factory for creating detector instances from configuration.
+
+    Supports creating detectors by type name with parameters.
+
+    Example:
+        >>> factory = DetectorFactory()
+        >>> detector = factory.create("zscore", {"threshold": 3.0})
+        >>> isinstance(detector, ZScoreDetector)
+        True
+    """
+
+    # Registry of available detector types
+    DETECTOR_TYPES = {
+        "zscore": ZScoreDetector,
+        "mad": MADDetector,
+        "iqr": IQRDetector,
+        "manual_bounds": ManualBoundsDetector,
+        "manual": ManualBoundsDetector,  # Alias
+    }
+
+    @classmethod
+    def create(cls, detector_type: str, params: Dict = None) -> BaseDetector:
+        """
+        Create detector instance from type and parameters.
+
+        Args:
+            detector_type: Type of detector (e.g., "zscore", "mad")
+            params: Detector parameters (optional)
+
+        Returns:
+            Detector instance
+
+        Raises:
+            ValueError: If detector type is unknown
+
+        Example:
+            >>> detector = DetectorFactory.create("zscore", {"threshold": 3.0, "window_size": 100})
+            >>> detector = DetectorFactory.create("mad", {"threshold": 2.5})
+        """
+        params = params or {}
+
+        detector_type = detector_type.lower()
+
+        if detector_type not in cls.DETECTOR_TYPES:
+            available = ", ".join(sorted(cls.DETECTOR_TYPES.keys()))
+            raise ValueError(
+                f"Unknown detector type: '{detector_type}'. "
+                f"Available types: {available}"
+            )
+
+        detector_class = cls.DETECTOR_TYPES[detector_type]
+
+        try:
+            return detector_class(**params)
+        except TypeError as e:
+            raise ValueError(
+                f"Invalid parameters for {detector_type} detector: {e}"
+            ) from e
+
+    @classmethod
+    def create_from_config(cls, detector_config: Dict) -> BaseDetector:
+        """
+        Create detector from configuration dictionary.
+
+        Args:
+            detector_config: Configuration with 'type' and optional 'params'
+                Example: {"type": "zscore", "params": {"threshold": 3.0}}
+
+        Returns:
+            Detector instance
+
+        Example:
+            >>> config = {"type": "zscore", "params": {"threshold": 3.0}}
+            >>> detector = DetectorFactory.create_from_config(config)
+        """
+        detector_type = detector_config.get("type")
+        if not detector_type:
+            raise ValueError("Detector config must have 'type' field")
+
+        params = detector_config.get("params", {})
+
+        return cls.create(detector_type, params)
+
+    @classmethod
+    def create_multiple(cls, detector_configs: List[Dict]) -> List[BaseDetector]:
+        """
+        Create multiple detectors from list of configurations.
+
+        Args:
+            detector_configs: List of detector configurations
+
+        Returns:
+            List of detector instances
+
+        Example:
+            >>> configs = [
+            ...     {"type": "zscore", "params": {"threshold": 3.0}},
+            ...     {"type": "mad", "params": {"threshold": 2.5}},
+            ... ]
+            >>> detectors = DetectorFactory.create_multiple(configs)
+            >>> len(detectors)
+            2
+        """
+        detectors = []
+        for config in detector_configs:
+            detector = cls.create_from_config(config)
+            detectors.append(detector)
+        return detectors
+
+    @classmethod
+    def list_available_types(cls) -> List[str]:
+        """
+        Get list of available detector types.
+
+        Returns:
+            List of detector type names
+
+        Example:
+            >>> types = DetectorFactory.list_available_types()
+            >>> "zscore" in types
+            True
+        """
+        return sorted(cls.DETECTOR_TYPES.keys())

detectkit/detectors/statistical/__init__.py

@@ -0,0 +1,8 @@
+"""Statistical anomaly detectors."""
+
+from detectkit.detectors.statistical.iqr import IQRDetector
+from detectkit.detectors.statistical.mad import MADDetector
+from detectkit.detectors.statistical.manual_bounds import ManualBoundsDetector
+from detectkit.detectors.statistical.zscore import ZScoreDetector
+
+__all__ = ["IQRDetector", "MADDetector", "ManualBoundsDetector", "ZScoreDetector"]

detectkit/detectors/statistical/iqr.py

@@ -0,0 +1,230 @@
+"""
+Interquartile Range (IQR) anomaly detector.
+
+IQR is a robust statistical method for outlier detection that:
+- Uses quartiles (Q1, Q3) instead of mean
+- Measures spread using IQR = Q3 - Q1
+- Less sensitive to outliers than Z-Score
+- Similar robustness to MAD
+
+Formula:
+- Q1 = 25th percentile
+- Q3 = 75th percentile
+- IQR = Q3 - Q1
+- lower_bound = Q1 - threshold × IQR
+- upper_bound = Q3 + threshold × IQR
+
+Default threshold = 1.5 (standard Tukey's fences)
+"""
+
+from typing import Any, Dict
+
+import numpy as np
+
+from detectkit.detectors.base import BaseDetector, DetectionResult
+
+
+class IQRDetector(BaseDetector):
+    """
+    Interquartile Range (IQR) detector for anomaly detection.
+
+    Detects anomalies using Tukey's fences method based on quartiles.
+    This is a robust method that works well with skewed distributions.
+
+    Parameters:
+        threshold (float): IQR multiplier for bounds (default: 1.5)
+            - 1.5 is standard Tukey's fences (identifies outliers)
+            - 3.0 identifies extreme outliers
+            - Higher = less sensitive (fewer anomalies)
+            - Lower = more sensitive (more anomalies)
+
+        window_size (int): Historical window size in points (default: 100)
+            - Uses last N points to compute statistics
+            - Larger = more stable but less responsive
+            - Smaller = more responsive but less stable
+
+        min_samples (int): Minimum samples required for detection (default: 30)
+            - Skip detection if window has fewer valid points
+            - Ensures statistical reliability
+
+    Example:
+        >>> detector = IQRDetector(threshold=1.5, window_size=100)
+        >>> results = detector.detect(data)
+        >>> for r in results:
+        ...     if r.is_anomaly:
+        ...         print(f"Anomaly: {r.value} outside [{r.confidence_lower}, {r.confidence_upper}]")
+    """
+
+    def __init__(
+        self,
+        threshold: float = 1.5,
+        window_size: int = 100,
+        min_samples: int = 30,
+    ):
+        """Initialize IQR detector with parameters."""
+        super().__init__(
+            threshold=threshold,
+            window_size=window_size,
+            min_samples=min_samples,
+        )
+
+    def _validate_params(self):
+        """Validate detector parameters."""
+        threshold = self.params.get("threshold")
+        if threshold is None or threshold <= 0:
+            raise ValueError("threshold must be positive")
+
+        window_size = self.params.get("window_size")
+        if window_size is None or window_size < 1:
+            raise ValueError("window_size must be at least 1")
+
+        min_samples = self.params.get("min_samples")
+        if min_samples is None or min_samples < 4:
+            raise ValueError("min_samples must be at least 4 (for quartiles)")
+
+        if min_samples > window_size:
+            raise ValueError("min_samples cannot exceed window_size")
+
+    def detect(self, data: Dict[str, np.ndarray]) -> list[DetectionResult]:
+        """
+        Perform IQR-based anomaly detection.
+
+        For each point, uses historical window to compute:
+        1. Q1 = 25th percentile of window
+        2. Q3 = 75th percentile of window
+        3. IQR = Q3 - Q1
+        4. lower_bound = Q1 - threshold × IQR
+        5. upper_bound = Q3 + threshold × IQR
+        6. is_anomaly = value outside [lower_bound, upper_bound]
+
+        Args:
+            data: Dictionary with keys:
+                - timestamp: np.array of datetime64[ms]
+                - value: np.array of float64 (may contain NaN)
+                - seasonality_data: np.array of JSON strings (not used yet)
+                - seasonality_columns: list of column names (not used yet)
+
+        Returns:
+            List of DetectionResult for each point
+
+        Notes:
+            - NaN values are skipped (marked as non-anomalous)
+            - First min_samples-1 points are skipped (insufficient history)
+            - Uses linear interpolation for percentile calculation
+            - Seasonality support will be added in future versions
+        """
+        timestamps = data["timestamp"]
+        values = data["value"]
+        threshold = self.params["threshold"]
+        window_size = self.params["window_size"]
+        min_samples = self.params["min_samples"]
+
+        results = []
+        n_points = len(timestamps)
+
+        for i in range(n_points):
+            current_val = values[i]
+            current_ts = timestamps[i]
+
+            # Skip NaN values
+            if np.isnan(current_val):
+                results.append(
+                    DetectionResult(
+                        timestamp=current_ts,
+                        value=current_val,
+                        is_anomaly=False,
+                        detection_metadata={"reason": "missing_data"},
+                    )
+                )
+                continue
+
+            # Get historical window (not including current point)
+            window_start = max(0, i - window_size)
+            window_values = values[window_start:i]
+
+            # Filter out NaN values from window
+            window_valid = window_values[~np.isnan(window_values)]
+
+            # Check if we have enough samples
+            if len(window_valid) < min_samples:
+                results.append(
+                    DetectionResult(
+                        timestamp=current_ts,
+                        value=current_val,
+                        is_anomaly=False,
+                        detection_metadata={
+                            "reason": "insufficient_data",
+                            "window_size": int(len(window_valid)),
+                            "min_samples": min_samples,
+                        },
+                    )
+                )
+                continue
+
+            # Compute IQR statistics
+            q1 = np.percentile(window_valid, 25)
+            q3 = np.percentile(window_valid, 75)
+            iqr = q3 - q1
+
+            # Handle edge case: IQR = 0 (all values in same range)
+            if iqr == 0:
+                # Use Q1/Q3 with small epsilon
+                # If no spread, any value outside Q1-Q3 is anomalous
+                confidence_lower = q1 - 1e-10
+                confidence_upper = q3 + 1e-10
+            else:
+                confidence_lower = q1 - threshold * iqr
+                confidence_upper = q3 + threshold * iqr
+
+            # Check if current value is anomalous
+            is_anomaly = (current_val < confidence_lower) or (current_val > confidence_upper)
+
+            # Determine direction and severity
+            metadata = {
+                "q1": float(q1),
+                "q3": float(q3),
+                "iqr": float(iqr),
+                "window_size": int(len(window_valid)),
+            }
+
+            if is_anomaly:
+                if current_val < confidence_lower:
+                    direction = "below"
+                    distance = confidence_lower - current_val
+                else:
+                    direction = "above"
+                    distance = current_val - confidence_upper
+
+                # Severity: how many IQR units away
+                severity = distance / iqr if iqr > 0 else float("inf")
+
+                metadata.update({
+                    "direction": direction,
+                    "severity": float(severity),
+                    "distance": float(distance),
+                })
+
+            results.append(
+                DetectionResult(
+                    timestamp=current_ts,
+                    value=current_val,
+                    is_anomaly=is_anomaly,
+                    confidence_lower=float(confidence_lower),
+                    confidence_upper=float(confidence_upper),
+                    detection_metadata=metadata,
+                )
+            )
+
+        return results
+
+    def _get_non_default_params(self) -> Dict[str, Any]:
+        """Get parameters that differ from defaults."""
+        defaults = {
+            "threshold": 1.5,
+            "window_size": 100,
+            "min_samples": 30,
+        }
+        return {
+            k: v for k, v in self.params.items()
+            if v != defaults.get(k)
+        }