aberrant 0.5.0__py3-none-any.whl

aberrant/__init__.py

@@ -0,0 +1,15 @@
+"""ABERRANT: Online Anomaly Detection library for streaming data.
+
+A Python library implementing the online learning paradigm for anomaly
+detection. All models process data one point at a time, updating their
+state incrementally without storing historical data.
+
+Modules:
+    base: Core abstract classes (BaseModel, BaseTransformer, Pipeline)
+    drift: Concept drift detection algorithms (ADWIN, KSWIN, PageHinkley)
+    model: Anomaly detection models
+    stream: Streaming data utilities
+    transform: Data transformers (scalers, projections)
+"""
+
+__version__ = "0.5.0"

aberrant/base/__init__.py

@@ -0,0 +1,46 @@
+"""Base classes for online anomaly detection models and components.
+
+This module provides the fundamental abstract base classes that define the
+interfaces for models, transformers, pipelines, and other core components
+in the aberrant library.
+"""
+
+import importlib
+from typing import Any
+
+from aberrant.base.exceptions import (
+    AberrantError,
+    IncompatibleComponentError,
+    ModelNotFittedError,
+    PipelineError,
+    TransformationError,
+    UnsupportedFeatureError,
+    ValidationError,
+)
+from aberrant.base.model import BaseModel
+from aberrant.base.pipeline import Pipeline
+from aberrant.base.similarity import BaseSimilaritySearchEngine
+from aberrant.base.transformer import BaseTransformer
+
+__all__ = [
+    "Architecture",
+    "BaseModel",
+    "BaseSimilaritySearchEngine",
+    "BaseTransformer",
+    "IncompatibleComponentError",
+    "ModelNotFittedError",
+    "AberrantError",
+    "Pipeline",
+    "PipelineError",
+    "TransformationError",
+    "UnsupportedFeatureError",
+    "ValidationError",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy import of Architecture to avoid torch dependency."""
+    if name == "Architecture":
+        module = importlib.import_module("aberrant.base.architecture")
+        return module.Architecture
+    raise AttributeError(f"module 'aberrant.base' has no attribute '{name}'")

aberrant/base/architecture.py

@@ -0,0 +1,76 @@
+"""Neural network architecture base class for deep learning models."""
+
+import abc
+import random
+
+import numpy as np
+import torch
+from torch import nn
+
+
+class Architecture(abc.ABC, nn.Module):
+    """
+    Abstract base class for defining neural network architectures.
+
+    This class ensures that any neural network architecture can be plugged into
+    online anomaly detection models. It provides a consistent interface and
+    device handling capabilities.
+
+    Subclasses must implement the `forward` and `input_size` methods.
+    """
+
+    def __init__(self, device: torch.device | None = None) -> None:
+        """
+        Initialize the architecture.
+
+        Args:
+            device: The device to run the model on. If None, uses CPU.
+        """
+        super().__init__()
+        self.device = device or torch.device("cpu")
+        self.to(self.device)
+
+    @abc.abstractmethod
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """
+        Forward pass through the network.
+
+        Args:
+            x: Input tensor.
+
+        Returns:
+            Output tensor.
+        """
+        raise NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def input_size(self) -> int:
+        """
+        The expected input size for the network.
+
+        Returns:
+            Number of input features.
+        """
+        raise NotImplementedError
+
+    @staticmethod
+    def set_seed(seed: int) -> None:
+        """
+        Set random seeds for reproducibility.
+
+        Args:
+            seed: Random seed value.
+        """
+        random.seed(seed)
+        np.random.seed(seed)
+        torch.manual_seed(seed)
+        if torch.cuda.is_available():
+            torch.cuda.manual_seed(seed)
+            torch.cuda.manual_seed_all(seed)
+        torch.backends.cudnn.deterministic = True
+        torch.backends.cudnn.benchmark = False
+
+    def __repr__(self) -> str:
+        """Return a string representation of the architecture."""
+        return f"{self.__class__.__name__}(input_size={self.input_size}, device={self.device})"

aberrant/base/exceptions.py

@@ -0,0 +1,51 @@
+"""Custom exceptions for the aberrant library."""
+
+
+class AberrantError(Exception):
+    """Base exception class for all aberrant-specific errors."""
+
+    pass
+
+
+class ModelNotFittedError(AberrantError):
+    """Raised when a model method is called before the model has been fitted."""
+
+    def __init__(self, message: str = "Model has not been fitted yet.") -> None:
+        super().__init__(message)
+
+
+class TransformationError(AberrantError):
+    """Raised when a transformation operation fails."""
+
+    pass
+
+
+class PipelineError(AberrantError):
+    """Raised when a pipeline operation fails."""
+
+    pass
+
+
+class ValidationError(AberrantError):
+    """Raised when input validation fails."""
+
+    pass
+
+
+class UnsupportedFeatureError(AberrantError):
+    """Raised when an unsupported feature is encountered."""
+
+    def __init__(self, feature_name: str) -> None:
+        super().__init__(f"Feature '{feature_name}' has not been seen during training.")
+        self.feature_name = feature_name
+
+
+class IncompatibleComponentError(PipelineError):
+    """Raised when pipeline components are incompatible."""
+
+    def __init__(self, component_name: str, expected_type: str) -> None:
+        super().__init__(
+            f"Component '{component_name}' is not compatible. Expected: {expected_type}"
+        )
+        self.component_name = component_name
+        self.expected_type = expected_type

aberrant/base/model.py

@@ -0,0 +1,48 @@
+"""Base model interface for online anomaly detection."""
+
+import abc
+
+
+class BaseModel(abc.ABC):
+    """
+    Abstract base class for online anomaly detection models.
+
+    This class defines the interface that all online anomaly detection models should implement.
+    Online models process one data point at a time, updating their internal state and providing
+    anomaly scores for each data point.
+
+    Subclasses must implement the `learn_one` and `score_one` methods.
+    """
+
+    @abc.abstractmethod
+    def learn_one(self, x: dict[str, float]) -> None:
+        """
+        Update the model with a single data point.
+
+        Args:
+            x: A dictionary representing a single data point. The keys are feature names,
+               and the values are the corresponding feature values.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def score_one(self, x: dict[str, float]) -> float:
+        """
+        Compute the anomaly score for a single data point.
+
+        Args:
+            x: A dictionary representing a single data point. The keys are feature names,
+               and the values are the corresponding feature values.
+
+        Returns:
+            The anomaly score for the data point. Higher scores indicate greater anomaly.
+        """
+        raise NotImplementedError
+
+    def __repr__(self) -> str:
+        """Return a string representation of the model."""
+        return f"{self.__class__.__name__}()"
+
+    def __str__(self) -> str:
+        """Return a human-readable string representation of the model."""
+        return self.__repr__()

aberrant/base/pipeline.py

@@ -0,0 +1,127 @@
+"""Pipeline for chaining transformers and models together."""
+
+from typing import Any
+
+from .exceptions import IncompatibleComponentError, PipelineError
+
+
+class Pipeline:
+    """
+    Pipeline for chaining transformers and models.
+
+    A pipeline allows you to chain multiple components together, where the output
+    of one component becomes the input of the next. The pipeline can contain
+    transformers (which modify data) and models (which score data).
+
+    Args:
+        first: The first component in the pipeline (transformer or model).
+        second: The second component in the pipeline (transformer or model).
+
+    Example:
+        >>> scaler = MinMaxScaler()
+        >>> model = RandomModel()
+        >>> pipeline = Pipeline(scaler, model)
+        >>> pipeline.learn_one({"feature": 1.0})
+        >>> score = pipeline.score_one({"feature": 2.0})
+    """
+
+    def __init__(self, first: Any, second: Any) -> None:
+        self._validate_components(first, second)
+        self.first = first
+        self.second = second
+
+    def learn_one(self, x: dict[str, float]) -> None:
+        """
+        Learn from a single data point through the pipeline.
+
+        Args:
+            x: A dictionary representing a single data point.
+        """
+        self.first.learn_one(x)
+        transformed_x = self.first.transform_one(x)
+        self.second.learn_one(transformed_x)
+
+    def transform_one(self, x: dict[str, float]) -> dict[str, float]:
+        """
+        Transform a single data point through the pipeline.
+
+        Args:
+            x: A dictionary representing a single data point.
+
+        Returns:
+            The transformed data point.
+        """
+        transformed_x = self.first.transform_one(x)
+        transformed = self.second.transform_one(transformed_x)
+        if not isinstance(transformed, dict):
+            raise PipelineError(
+                "The final transformer must return a dict[str, float] from transform_one."
+            )
+        return transformed
+
+    def score_one(self, x: dict[str, float]) -> float:
+        """
+        Score a single data point using the pipeline.
+
+        Args:
+            x: A dictionary representing a single data point.
+
+        Returns:
+            The anomaly score for the data point.
+
+        Raises:
+            PipelineError: If the final component doesn't support scoring.
+        """
+        transformed_x = self.first.transform_one(x)
+
+        if hasattr(self.second, "score_one"):
+            score = self.second.score_one(transformed_x)
+            if not isinstance(score, int | float):
+                raise PipelineError(
+                    "The final component must return a numeric score from score_one."
+                )
+            return float(score)
+        else:
+            raise PipelineError(
+                f"The final component ({self.second.__class__.__name__}) does not have a 'score_one' method."
+            )
+
+    def __or__(self, other: Any) -> "Pipeline":
+        """Overload the | operator to allow further chaining of pipelines."""
+        return Pipeline(self, other)
+
+    def __repr__(self) -> str:
+        """Return a string representation of the pipeline."""
+        return f"Pipeline({self.first!r} | {self.second!r})"
+
+    def __str__(self) -> str:
+        """Return a human-readable string representation of the pipeline."""
+        return f"{self.first.__class__.__name__} | {self.second.__class__.__name__}"
+
+    def _validate_components(self, first: Any, second: Any) -> None:
+        """
+        Validate that the pipeline components are compatible.
+
+        Args:
+            first: The first component.
+            second: The second component.
+
+        Raises:
+            IncompatibleComponentError: If components are not compatible.
+        """
+        # Check first component has required methods
+        if not hasattr(first, "learn_one"):
+            raise IncompatibleComponentError(
+                first.__class__.__name__, "component with 'learn_one' method"
+            )
+
+        if not hasattr(first, "transform_one"):
+            raise IncompatibleComponentError(
+                first.__class__.__name__, "component with 'transform_one' method"
+            )
+
+        # Check second component has required methods
+        if not hasattr(second, "learn_one"):
+            raise IncompatibleComponentError(
+                second.__class__.__name__, "component with 'learn_one' method"
+            )

aberrant/base/similarity.py

@@ -0,0 +1,48 @@
+"""Base similarity search engine interface."""
+
+import abc
+
+
+class BaseSimilaritySearchEngine(abc.ABC):
+    """
+    Abstract base class for similarity search engines.
+
+    This class defines the interface for similarity search engines that can store
+    data points and find similar neighbors for query points.
+
+    Subclasses must implement the `append` and `search` methods.
+    """
+
+    @abc.abstractmethod
+    def append(self, x: dict[str, float]) -> None:
+        """
+        Add a data point to the search engine.
+
+        Args:
+            x: A dictionary representing a single data point. The keys are feature names,
+               and the values are the corresponding feature values.
+        """
+        pass
+
+    @abc.abstractmethod
+    def search(self, x: dict[str, float], n_neighbors: int) -> float:
+        """
+        Search for the n nearest neighbors of a data point.
+
+        Args:
+            x: A dictionary representing the query data point.
+            n_neighbors: The number of nearest neighbors to find.
+
+        Returns:
+            A similarity or distance score based on the nearest neighbors.
+            Should return a consistent numeric value (e.g., 0.0 if insufficient data).
+        """
+        pass
+
+    def __repr__(self) -> str:
+        """Return a string representation of the search engine."""
+        return f"{self.__class__.__name__}()"
+
+    def __str__(self) -> str:
+        """Return a human-readable string representation of the search engine."""
+        return self.__repr__()

aberrant/base/transformer.py

@@ -0,0 +1,56 @@
+"""Base transformer interface for online data transformation."""
+
+import abc
+from typing import TYPE_CHECKING, Any
+
+from aberrant.base.pipeline import Pipeline
+
+if TYPE_CHECKING:
+    from aberrant.base.pipeline import Pipeline
+
+
+class BaseTransformer(abc.ABC):
+    """
+    Abstract base class for online transformers.
+
+    This class defines the interface for transformers that can learn from and transform
+    data points incrementally. Transformers modify the input data while maintaining
+    the streaming nature of the processing.
+
+    Subclasses must implement the `learn_one` and `transform_one` methods.
+    """
+
+    @abc.abstractmethod
+    def learn_one(self, x: dict[str, float]) -> None:
+        """
+        Update the transformer with a single data point.
+
+        Args:
+            x: A dictionary representing a single data point. The keys are feature names,
+               and the values are the corresponding feature values.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def transform_one(self, x: dict[str, float]) -> dict[str, float]:
+        """
+        Transform a single data point.
+
+        Args:
+            x: A dictionary representing a single data point to transform.
+
+        Returns:
+            A dictionary with transformed feature values.
+        """
+        raise NotImplementedError
+
+    def __or__(self, other: Any) -> "Pipeline":
+        return Pipeline(self, other)
+
+    def __repr__(self) -> str:
+        """Return a string representation of the transformer."""
+        return f"{self.__class__.__name__}()"
+
+    def __str__(self) -> str:
+        """Return a human-readable string representation of the transformer."""
+        return self.__repr__()

aberrant/drift/__init__.py

@@ -0,0 +1,13 @@
+"""Concept drift detection algorithms for streaming data."""
+
+from aberrant.drift.adwin import ADWIN
+from aberrant.drift.base import BaseDriftDetector
+from aberrant.drift.kswin import KSWIN
+from aberrant.drift.page_hinkley import PageHinkley
+
+__all__ = [
+    "ADWIN",
+    "BaseDriftDetector",
+    "KSWIN",
+    "PageHinkley",
+]