yzhao062/pyod

A Python library for anomaly detection across tabular, time series, graph, text, image, and audio data. 60+ detectors, benchmark-backed ADEngine orchestration, and an agentic workflow for AI agents.

PyOD – Python Outlier Detection (v3)

What it is – A mature, open‑source Python library that bundles more than 60 anomaly‑detection algorithms for many data modalities (tabular, time‑series, graph, text, image, audio). Version 3 adds an agent‑ready orchestration layer called ADEngine and a natural‑language skill (od‑expert) so large‑language‑model agents (Claude Code, Codex, or any MCP‑compatible LLM) can drive detection workflows without writing code.

Key pillars

Pillar Meaning
Multi‑Modal One unified API covers 61 detectors across six data types.
Full Lifecycle From raw data to scored anomalies, explanations, and next‑step guidance in a single call.
Agentic LLMs can invoke PyOD via the od‑expert skill or MCP tools (e.g., list_detectors, run_detection).
Most Used >46 M downloads, benchmark‑backed model routing, and many enterprise adopters.

Quick install

pip install pyod                     # core library
# optional extras for agents
pip install pyod[mcp]                # MCP‑compatible LLMs
pyod install skill                    # install Claude Code / Codex skill

Run pyod info anytime to see version, detector count, and which activation path matches your environment.

Minimal example (classic API)

from pyod.models.iforest import IForest
clf = IForest()
clf.fit(X_train)                     # learn normal patterns
train_scores = clf.decision_scores_  # anomaly scores on training data
test_scores  = clf.decision_function(X_test)  # scores on new data

The same fit/predict interface works for any of the 61 detectors.

Three usage layers

Layer When to use Entry point
1 – Classic API You know which detector you want. from pyod.models.<mod> import <Detector>
2 – ADEngine Let PyOD automatically select, compare, and evaluate detectors. from pyod.utils.ad_engine import ADEngine
3 – Agentic Drive detection through natural‑language conversation with an LLM. od‑expert skill (Claude Code / Codex) or MCP server (python -m pyod.mcp_server).

Layers 2 & 3 are powered by ADEngine, which orchestrates data profiling, model routing, training (via SUOD parallelism), scoring, and result explanation.

Agentic interaction (example)

  • A Claude Code or Codex user can type a request like “Find abnormal heart‑rate patterns in the cardiotocography dataset.” The od‑expert skill translates the request into an ADEngine workflow, runs the chosen detector(s), and returns a concise explanation plus next‑step suggestions. The MCP server exposes ten stateless tools (e.g., list_detectors, plan_detection, run_detection) that any MCP‑compatible LLM can call.

Ecosystem & benchmarks

  • Benchmarks: ADBench (tabular), NLP‑ADBench (text), TSB‑AD (time‑series), BOND (graph) – all linked from the docs.
  • Related projects: PyGOD (graph AD), TODS (time‑series), AD‑LLM (LLM‑driven AD), etc.
  • Performance: Built on SUOD for fast parallel training and uses Numba JIT for per‑model speedups.

Documentation & resources

  • Full API reference: https://pyod.readthedocs.io/en/latest/ (tabular, time‑series, graph, embedding, ADEngine, utilities).
  • Installation guide, tutorials, and a gallery of examples are hosted on the docs site.
  • Impact page lists academic citations, enterprise deployments (Walmart, Databricks, Ericsson, etc.), books, courses, and podcasts.

When to choose PyOD

  • You need a single library that covers many anomaly‑detection algorithms and data types.
  • You want automatic model selection backed by large‑scale benchmarks.
  • You plan to integrate detection into an LLM‑driven workflow (Claude, Codex, or any MCP‑compatible model).
  • You value a stable, backward‑compatible API (fit/predict) while still getting modern orchestration features.

License

Open‑source under the BSD‑3‑Clause license.

Related

  • Project
    Albertsr/Anomaly-Detection

    A code-first educational collection of handwritten Python implementations for various tabular anomaly detection methods, including PCA reconstruction, RobustPCC, and PU learning.

  • Project
    yzhao062/SUOD

    An acceleration framework for large-scale unsupervised outlier detection that optimizes training and prediction for ensembles of heterogeneous models.

  • Project
    vc1492a/PyNomaly

    A Python implementation of Local Outlier Probabilities (LoOP) that provides interpretable outlier scores as probabilities between 0 and 1.

  • Project
    unit8co/darts

    Darts is a Python library that simplifies time‑series forecasting and anomaly detection. It offers a unified `fit`/`predict` API for classic models (ARIMA, Exponential Smoothing) and deep‑learning models (N‑BEATS, TCN, Transformers), supports multivariate series, covariates, probabilistic forecasts, back‑testing, and integrates with PyTorch Lightning and MLflow.

  • Project
    open-edge-platform/anomalib

    Anomalib is a deep learning library that provides a modular framework for training, benchmarking, and deploying state-of-the-art visual anomaly detection models across various hardware platforms.