pyod 3.5.2__tar.gz → 3.6.0__tar.gz

{pyod-3.5.2/pyod.egg-info → pyod-3.6.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pyod
-Version: 3.5.2
-Summary: A Python library for anomaly detection across tabular, time series, graph, text, and image data. 60+ detectors, benchmark-backed ADEngine orchestration, and an agentic workflow for AI agents.
+Version: 3.6.0
+Summary: A Python library for anomaly detection across tabular, time series, graph, text, image, and audio data. 61 detectors, benchmark-backed ADEngine orchestration, and an agentic workflow for AI agents.
 Author-email: Yue Zhao <yzhao062@gmail.com>
 License-Expression: BSD-2-Clause
 Project-URL: Homepage, https://github.com/yzhao062/pyod
@@ -53,6 +53,9 @@ Requires-Dist: torch>=2.0; extra == "graph"
 Requires-Dist: torch_geometric>=2.0; extra == "graph"
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: audio
+Requires-Dist: librosa>=0.10; extra == "audio"
+Requires-Dist: soundfile; extra == "audio"
 Provides-Extra: all
 Requires-Dist: torch>=2.0; extra == "all"
 Requires-Dist: suod; extra == "all"
@@ -65,6 +68,8 @@ Requires-Dist: transformers>=4.25.1; extra == "all"
 Requires-Dist: torch_geometric>=2.0; extra == "all"
 Requires-Dist: Pillow; extra == "all"
 Requires-Dist: mcp>=1.0; extra == "all"
+Requires-Dist: librosa>=0.10; extra == "all"
+Requires-Dist: soundfile; extra == "all"
 Dynamic: license-file
 
 Python Outlier Detection (PyOD) 3
@@ -131,7 +136,7 @@ PyOD 3 is the most comprehensive Python library for anomaly detection. Four pill
 ===========================  ========================================================================================
 Pillar                       What it means
 ===========================  ========================================================================================
-Multi-Modal                  60+ detectors across **tabular, time series, graph, text, and image** data, one API
+Multi-Modal                  61 detectors across **tabular, time series, graph, text, image, and audio** data, one API
 Full Lifecycle               From raw data to explained anomalies and next-step guidance in a single call
 Agentic                      ``od-expert`` turns natural-language requests into ADEngine workflows; MCP exposes structured tools for other agents
 Most Used                    38+ million downloads; benchmark-backed routing (ADBench, TSB-AD, BOND, NLP-ADBench)
@@ -191,7 +196,7 @@ Layer      Name                   When to use
 3          Agentic Investigation  You want an AI agent to drive OD through natural conversation           `Layer 3 walkthrough <https://pyod.readthedocs.io/en/latest/examples/agentic.html>`__
 =========  =====================  ======================================================================  =======================================
 
-Layers 2 and 3 are powered by ``ADEngine``, PyOD's intelligent orchestration core. The full multi-turn Layer 3 investigation flow is available through the ``od-expert`` skill for Claude Code and Codex. The MCP server (``python -m pyod.mcp_server``) exposes ten stateless tools for MCP-compatible LLMs, spanning knowledge queries (``list_detectors``, ``explain_detector``, ``compare_detectors``, ``get_benchmarks``), planning (``profile_data``, ``plan_detection``, ``build_detector``), and detection (``run_detection``, ``analyze_results``, ``explain_findings``); stateful ``investigate`` / ``iterate`` MCP tools are deferred.
+Layers 2 and 3 are powered by ``ADEngine``, PyOD's lifecycle orchestration core. The full multi-turn Layer 3 investigation flow is available through the ``od-expert`` skill for Claude Code and Codex. The MCP server (``python -m pyod.mcp_server``) exposes ten stateless tools for MCP-compatible LLMs, spanning knowledge queries (``list_detectors``, ``explain_detector``, ``compare_detectors``, ``get_benchmarks``), planning (``profile_data``, ``plan_detection``, ``build_detector``), and detection (``run_detection``, ``analyze_results``, ``explain_findings``); stateful ``investigate`` / ``iterate`` MCP tools are deferred.
 
 .. image:: https://raw.githubusercontent.com/yzhao062/pyod/development/docs/figs/agentic-demo.png
    :alt: PyOD 3 agentic investigation demo on cardiotocography dataset
@@ -211,7 +216,7 @@ About PyOD
 
 PyOD, established in 2017, is the longest-running and most widely used Python library for anomaly detection. With `38+ million downloads <https://pepy.tech/project/pyod>`__, it serves both academic research (featured in `Analytics Vidhya <https://www.analyticsvidhya.com/blog/2019/02/outlier-detection-python-pyod/>`__, `KDnuggets <https://www.kdnuggets.com/2019/02/outlier-detection-methods-cheat-sheet.html>`__, and `Towards Data Science <https://towardsdatascience.com/anomaly-detection-for-dummies-15f148e559c1>`__) and commercial products.
 
-V3 extends the library with ``ADEngine`` (intelligent orchestration) and the ``od-expert`` skill (agentic workflow), while keeping the classic ``fit``/``predict`` API fully backward-compatible. V3 is built on SUOD [#Zhao2021SUOD]_ for fast parallel training and numba JIT for per-model speedups.
+V3 extends the library with ``ADEngine`` (lifecycle orchestration) and the ``od-expert`` skill (agentic workflow), while keeping the classic ``fit``/``predict`` API fully backward-compatible. V3 is built on SUOD [#Zhao2021SUOD]_ for fast parallel training and numba JIT for per-model speedups.
 
 **Impact & Recognition**:
 
@@ -322,7 +327,7 @@ Additional Topics
 Implemented Algorithms
 ^^^^^^^^^^^^^^^^^^^^^^
 
-PyOD is organized into two functional groups: **(i) Detection Algorithms**, with dedicated subsections for tabular, time series, and graph data (EmbeddingOD inside the tabular table adds multi-modal support for text and image via foundation model encoders); and **(ii) Utility Functions** for data generation, evaluation, and intelligent orchestration.
+PyOD is organized into two functional groups: **(i) Detection Algorithms**, with dedicated subsections for tabular, time series, and graph data (EmbeddingOD inside the tabular table adds multi-modal support for text, image, and audio via foundation model or handcrafted encoders); and **(ii) Utility Functions** for data generation, evaluation, and lifecycle orchestration.
 
 **(i-a) Tabular & Multi-Modal Detection Algorithms** :
 
@@ -577,7 +582,7 @@ PyOD is organized into two functional groups: **(i) Detection Algorithms**, with
      - [#Goodge2022Lunar]_
    * - Embedding-based
      - EmbeddingOD
-     - Multi-modal anomaly detection via foundation model embeddings, text and image (`example <https://github.com/yzhao062/pyod/blob/development/examples/embedding_od_example.py>`__)
+     - Multi-modal anomaly detection via foundation model embeddings, text, image, and audio (`example <https://github.com/yzhao062/pyod/blob/development/examples/embedding_od_example.py>`__)
      - 2025
      - [#Li2024NLPADBench]_
 

{pyod-3.5.2 → pyod-3.6.0}/README.rst

@@ -62,7 +62,7 @@ PyOD 3 is the most comprehensive Python library for anomaly detection. Four pill
 ===========================  ========================================================================================
 Pillar                       What it means
 ===========================  ========================================================================================
-Multi-Modal                  60+ detectors across **tabular, time series, graph, text, and image** data, one API
+Multi-Modal                  61 detectors across **tabular, time series, graph, text, image, and audio** data, one API
 Full Lifecycle               From raw data to explained anomalies and next-step guidance in a single call
 Agentic                      ``od-expert`` turns natural-language requests into ADEngine workflows; MCP exposes structured tools for other agents
 Most Used                    38+ million downloads; benchmark-backed routing (ADBench, TSB-AD, BOND, NLP-ADBench)
@@ -122,7 +122,7 @@ Layer      Name                   When to use
 3          Agentic Investigation  You want an AI agent to drive OD through natural conversation           `Layer 3 walkthrough <https://pyod.readthedocs.io/en/latest/examples/agentic.html>`__
 =========  =====================  ======================================================================  =======================================
 
-Layers 2 and 3 are powered by ``ADEngine``, PyOD's intelligent orchestration core. The full multi-turn Layer 3 investigation flow is available through the ``od-expert`` skill for Claude Code and Codex. The MCP server (``python -m pyod.mcp_server``) exposes ten stateless tools for MCP-compatible LLMs, spanning knowledge queries (``list_detectors``, ``explain_detector``, ``compare_detectors``, ``get_benchmarks``), planning (``profile_data``, ``plan_detection``, ``build_detector``), and detection (``run_detection``, ``analyze_results``, ``explain_findings``); stateful ``investigate`` / ``iterate`` MCP tools are deferred.
+Layers 2 and 3 are powered by ``ADEngine``, PyOD's lifecycle orchestration core. The full multi-turn Layer 3 investigation flow is available through the ``od-expert`` skill for Claude Code and Codex. The MCP server (``python -m pyod.mcp_server``) exposes ten stateless tools for MCP-compatible LLMs, spanning knowledge queries (``list_detectors``, ``explain_detector``, ``compare_detectors``, ``get_benchmarks``), planning (``profile_data``, ``plan_detection``, ``build_detector``), and detection (``run_detection``, ``analyze_results``, ``explain_findings``); stateful ``investigate`` / ``iterate`` MCP tools are deferred.
 
 .. image:: https://raw.githubusercontent.com/yzhao062/pyod/development/docs/figs/agentic-demo.png
    :alt: PyOD 3 agentic investigation demo on cardiotocography dataset
@@ -142,7 +142,7 @@ About PyOD
 
 PyOD, established in 2017, is the longest-running and most widely used Python library for anomaly detection. With `38+ million downloads <https://pepy.tech/project/pyod>`__, it serves both academic research (featured in `Analytics Vidhya <https://www.analyticsvidhya.com/blog/2019/02/outlier-detection-python-pyod/>`__, `KDnuggets <https://www.kdnuggets.com/2019/02/outlier-detection-methods-cheat-sheet.html>`__, and `Towards Data Science <https://towardsdatascience.com/anomaly-detection-for-dummies-15f148e559c1>`__) and commercial products.
 
-V3 extends the library with ``ADEngine`` (intelligent orchestration) and the ``od-expert`` skill (agentic workflow), while keeping the classic ``fit``/``predict`` API fully backward-compatible. V3 is built on SUOD [#Zhao2021SUOD]_ for fast parallel training and numba JIT for per-model speedups.
+V3 extends the library with ``ADEngine`` (lifecycle orchestration) and the ``od-expert`` skill (agentic workflow), while keeping the classic ``fit``/``predict`` API fully backward-compatible. V3 is built on SUOD [#Zhao2021SUOD]_ for fast parallel training and numba JIT for per-model speedups.
 
 **Impact & Recognition**:
 
@@ -253,7 +253,7 @@ Additional Topics
 Implemented Algorithms
 ^^^^^^^^^^^^^^^^^^^^^^
 
-PyOD is organized into two functional groups: **(i) Detection Algorithms**, with dedicated subsections for tabular, time series, and graph data (EmbeddingOD inside the tabular table adds multi-modal support for text and image via foundation model encoders); and **(ii) Utility Functions** for data generation, evaluation, and intelligent orchestration.
+PyOD is organized into two functional groups: **(i) Detection Algorithms**, with dedicated subsections for tabular, time series, and graph data (EmbeddingOD inside the tabular table adds multi-modal support for text, image, and audio via foundation model or handcrafted encoders); and **(ii) Utility Functions** for data generation, evaluation, and lifecycle orchestration.
 
 **(i-a) Tabular & Multi-Modal Detection Algorithms** :
 
@@ -508,7 +508,7 @@ PyOD is organized into two functional groups: **(i) Detection Algorithms**, with
      - [#Goodge2022Lunar]_
    * - Embedding-based
      - EmbeddingOD
-     - Multi-modal anomaly detection via foundation model embeddings, text and image (`example <https://github.com/yzhao062/pyod/blob/development/examples/embedding_od_example.py>`__)
+     - Multi-modal anomaly detection via foundation model embeddings, text, image, and audio (`example <https://github.com/yzhao062/pyod/blob/development/examples/embedding_od_example.py>`__)
      - 2025
      - [#Li2024NLPADBench]_
 

{pyod-3.5.2 → pyod-3.6.0}/pyod/cli.py

@@ -46,10 +46,16 @@ def _cmd_info(args: argparse.Namespace) -> int:
         from pyod.utils.ad_engine import ADEngine
         engine = ADEngine()
         counts: Counter = Counter()
-        for algo in engine.kb.algorithms.values():
+        # Count only buildable detectors: a `planned` entry (e.g., LLMAD) has
+        # no backing module, so it must not inflate the reported total.
+        buildable = {
+            name: algo for name, algo in engine.kb.algorithms.items()
+            if algo.get("status") != "planned"
+        }
+        for algo in buildable.values():
             for dt in algo.get("data_types", []):
                 counts[dt] += 1
-        total = len(engine.kb.algorithms)
+        total = len(buildable)
         ad_ok = True
     except Exception:
         counts = Counter()

pyod-3.6.0/pyod/models/audio_ae.py

@@ -0,0 +1,235 @@
+# -*- coding: utf-8 -*-
+"""AudioAE: a log-mel reconstruction autoencoder for audio anomaly detection.
+
+Each clip is turned into overlapping log-mel context windows; a dense
+autoencoder is fit on the windows of the (mostly normal) training clips,
+and each clip is scored by its mean per-window reconstruction error. This
+is the DCASE-style audio anomaly detection baseline, expressed through
+PyOD's ``AutoEncoder`` so the training loop and preprocessing are shared
+with the rest of the library.
+"""
+# Author: Yue Zhao <yzhao062@gmail.com>
+# License: BSD 2 clause
+
+import numpy as np
+from sklearn.utils.validation import check_is_fitted
+
+from .base import BaseDetector
+from ..utils.encoders.audio import _to_mono_waveform
+
+_DEFAULT_SR = 22050
+
+
+def _logmel_windows(y, sr, n_mels, context, hop_length):
+    """Return overlapping log-mel context windows for one waveform.
+
+    Output shape is ``(n_windows, n_mels * context)``. Clips shorter than
+    one context window are padded so at least one window is produced.
+    """
+    import librosa
+
+    spec = librosa.power_to_db(
+        librosa.feature.melspectrogram(
+            y=y, sr=sr, n_mels=n_mels, hop_length=hop_length))
+    n_frames = spec.shape[1]
+    if n_frames < context:
+        pad = np.zeros((n_mels, context - n_frames), dtype=spec.dtype)
+        spec = np.concatenate([spec, pad], axis=1)
+        n_frames = context
+    windows = [spec[:, t:t + context].T.reshape(-1)
+               for t in range(n_frames - context + 1)]
+    return np.stack(windows).astype(np.float32)
+
+
+class AudioAE(BaseDetector):
+    """Log-mel reconstruction autoencoder for audio anomaly detection.
+
+    The detector extracts overlapping log-mel context windows from each
+    clip, fits a dense autoencoder (PyOD's :class:`AutoEncoder`) on the
+    windows of the training clips, and scores each clip by its mean
+    per-window reconstruction error. Training assumes the input is mostly
+    normal, the usual unsupervised setting.
+
+    Requires ``torch`` (for the autoencoder) and ``pyod[audio]``
+    (``librosa``, ``soundfile``).
+
+    Parameters
+    ----------
+    n_mels : int, optional (default=64)
+        Number of mel bands in the spectrogram.
+
+    context : int, optional (default=5)
+        Number of consecutive frames stacked into one autoencoder input
+        window. The window dimensionality is ``n_mels * context``.
+
+    hop_length : int, optional (default=512)
+        STFT hop length in samples.
+
+    sr : int, optional (default=22050)
+        Target sample rate. File inputs are loaded at this rate;
+        ``(waveform, sample_rate)`` tuples are resampled to it.
+
+    contamination : float, optional (default=0.1)
+        Expected proportion of outliers, used for the clip-level
+        threshold and labels.
+
+    epoch_num : int, optional (default=40)
+        Autoencoder training epochs.
+
+    batch_size : int, optional (default=1024)
+        Autoencoder mini-batch size (over frames, not clips).
+
+    lr : float, optional (default=1e-3)
+        Learning rate.
+
+    hidden_neuron_list : list of int or None, optional (default=None)
+        Encoder hidden sizes. ``None`` uses ``[128, 32, 8]``, which gives
+        the DCASE-style 320-128-32-8 contraction for the default
+        320-dimensional window (``n_mels=64``, ``context=5``).
+
+    device : str or None, optional (default=None)
+        Torch device. ``None`` auto-selects.
+
+    random_state : int, optional (default=42)
+        Seed forwarded to the autoencoder.
+
+    verbose : int, optional (default=0)
+        Autoencoder verbosity.
+
+    Attributes
+    ----------
+    decision_scores_ : numpy array of shape (n_clips,)
+        Clip-level outlier scores of the training data.
+
+    threshold_ : float
+        Score threshold based on ``contamination``.
+
+    labels_ : numpy array of shape (n_clips,)
+        Binary labels of training clips (0: inlier, 1: outlier).
+
+    ae_ : AutoEncoder
+        The fitted frame-level autoencoder.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pyod.models.audio_ae import AudioAE
+    >>> clips = [np.random.RandomState(s).randn(22050) for s in range(20)]
+    >>> clf = AudioAE(epoch_num=5)
+    >>> clf.fit(clips)  # doctest: +SKIP
+    >>> scores = clf.decision_function(clips)  # doctest: +SKIP
+    """
+
+    def __init__(self, n_mels=64, context=5, hop_length=512, sr=_DEFAULT_SR,
+                 contamination=0.1, epoch_num=40, batch_size=1024, lr=1e-3,
+                 hidden_neuron_list=None, device=None, random_state=42,
+                 verbose=0):
+        super(AudioAE, self).__init__(contamination=contamination)
+        self.n_mels = n_mels
+        self.context = context
+        self.hop_length = hop_length
+        self.sr = sr
+        self.epoch_num = epoch_num
+        self.batch_size = batch_size
+        self.lr = lr
+        self.hidden_neuron_list = hidden_neuron_list
+        self.device = device
+        self.random_state = random_state
+        self.verbose = verbose
+
+    def _extract(self, X):
+        """Return (frames, clip_idx) over all clips in X."""
+        try:
+            import librosa  # noqa: F401
+            import soundfile  # noqa: F401
+        except ImportError:
+            raise ImportError(
+                "AudioAE requires 'librosa' and 'soundfile'. "
+                "Install with: pip install pyod[audio]")
+        if len(X) == 0:
+            raise ValueError("AudioAE received an empty input.")
+        frames_list, clip_idx = [], []
+        for i, item in enumerate(X):
+            y = _to_mono_waveform(item, self.sr)
+            windows = _logmel_windows(y, self.sr, self.n_mels,
+                                      self.context, self.hop_length)
+            frames_list.append(windows)
+            clip_idx.append(np.full(len(windows), i, dtype=np.int64))
+        return np.concatenate(frames_list, axis=0), np.concatenate(clip_idx)
+
+    @staticmethod
+    def _aggregate(frame_scores, clip_idx, n_clips):
+        """Mean per-frame score within each clip."""
+        out = np.zeros(n_clips, dtype=np.float64)
+        for i in range(n_clips):
+            mask = clip_idx == i
+            if mask.any():
+                out[i] = float(frame_scores[mask].mean())
+        return out
+
+    def fit(self, X, y=None):
+        """Fit the frame autoencoder and score the training clips.
+
+        Parameters
+        ----------
+        X : list
+            Audio clips as file paths, waveform arrays, or
+            ``(waveform, sample_rate)`` tuples.
+
+        y : Ignored
+            Not used, present for API consistency.
+
+        Returns
+        -------
+        self : object
+        """
+        try:
+            import torch  # noqa: F401
+        except ImportError:
+            raise ImportError(
+                "AudioAE requires torch (for the autoencoder) and "
+                "pyod[audio] (librosa, soundfile). Install with: "
+                "pip install pyod[torch,audio]")
+        from .auto_encoder import AutoEncoder
+
+        frames, clip_idx = self._extract(X)
+        dim = frames.shape[1]
+        hidden = self.hidden_neuron_list or [128, 32, 8]
+        # Drop hidden layers that are not smaller than the input so the
+        # autoencoder stays a contraction for unusually small windows.
+        hidden = [h for h in hidden if h < dim] or [max(dim // 2, 2)]
+
+        # Cap the batch size to the frame count. PyOD's AutoEncoder drops
+        # the last incomplete batch, so a batch larger than the dataset
+        # would drop every frame and leave the training loop with nothing.
+        batch_size = max(1, min(self.batch_size, frames.shape[0]))
+
+        self.ae_ = AutoEncoder(
+            contamination=self.contamination, epoch_num=self.epoch_num,
+            batch_size=batch_size, lr=self.lr,
+            hidden_neuron_list=hidden, device=self.device,
+            random_state=self.random_state, verbose=self.verbose)
+        self.ae_.fit(frames)
+
+        frame_scores = self.ae_.decision_function(frames)
+        self._set_n_classes(y)
+        self.decision_scores_ = self._aggregate(frame_scores, clip_idx, len(X))
+        self._process_decision_scores()
+        return self
+
+    def decision_function(self, X):
+        """Predict clip-level anomaly scores for X.
+
+        Parameters
+        ----------
+        X : list
+            Audio clips in the same formats accepted by ``fit``.
+
+        Returns
+        -------
+        anomaly_scores : numpy array of shape (n_clips,)
+        """
+        check_is_fitted(self, ['decision_scores_', 'threshold_', 'labels_'])
+        frames, clip_idx = self._extract(X)
+        frame_scores = self.ae_.decision_function(frames)
+        return self._aggregate(frame_scores, clip_idx, len(X))

{pyod-3.5.2 → pyod-3.6.0}/pyod/models/embedding.py

@@ -431,6 +431,55 @@ class EmbeddingOD(BaseDetector):
         config = {**presets[quality], **kwargs}
         return cls(**config)
 
+    @classmethod
+    def for_audio(cls, quality='balanced', **kwargs):
+        """Create an EmbeddingOD configured for audio anomaly detection.
+
+        Uses a handcrafted 74-dim acoustic feature encoder (20 MFCC,
+        12 chroma, and 5 spectral descriptors, each as mean and standard
+        deviation over frames) followed by a classical PyOD detector. This
+        embed-then-detect pattern with classical detectors is competitive
+        on standard audio anomaly detection benchmarks and needs no GPU.
+        Requires ``pyod[audio]`` (librosa, soundfile).
+
+        Input clips may be file paths, waveform arrays, or
+        ``(waveform, sample_rate)`` tuples.
+
+        Parameters
+        ----------
+        quality : str, optional (default='balanced')
+            - 'fast': handcrafted features + IForest.
+            - 'balanced': handcrafted features + KNN.
+            - 'best': handcrafted features + LUNAR (requires torch).
+
+        **kwargs
+            Override any EmbeddingOD parameter.
+
+        Returns
+        -------
+        clf : EmbeddingOD
+        """
+        presets = {
+            'fast': {
+                'encoder': 'audio-mfcc',
+                'detector': 'IForest',
+            },
+            'balanced': {
+                'encoder': 'audio-mfcc',
+                'detector': 'KNN',
+            },
+            'best': {
+                'encoder': 'audio-mfcc',
+                'detector': 'LUNAR',
+            },
+        }
+        if quality not in presets:
+            raise ValueError(
+                "quality must be 'fast', 'balanced', or 'best', "
+                "got '%s'" % quality)
+        config = {**presets[quality], **kwargs}
+        return cls(**config)
+
 
 class MultiModalOD(BaseDetector):
     """Multi-modal anomaly detection via score fusion.