PyOD

PyOD is a Python toolbox for detecting outlying objects in multivariate data, established in 2017 and now the longest-running, most widely used anomaly-detection library in the Python ecosystem with 46+ million downloads. It unifies over 60 detection algorithms behind a single, consistent scikit-learn-compatible API (fit, decision_function, predict, predict_proba), spanning classic statistical methods (KNN, LOF, HBOS, COPOD), ensemble techniques (Isolation Forest, SUOD, LSCP), and deep-learning detectors (AutoEncoder, Deep SVDD, ALAD, DevNet) built on PyTorch.

Version 3 extends the classic library with two additional layers on top of the original detector API. ADEngine is a lifecycle-orchestration engine that profiles incoming data, selects and compares candidate detectors, runs detection, and explains the resulting anomalies in a single call, backed by benchmark results from ADBench, TSB-AD, and BOND. On top of that, an agentic layer (the od-expert Claude Code/Codex skill and a ten-tool MCP server) lets AI agents drive multi-turn anomaly-investigation workflows in natural language while keeping the underlying fit/predict contract unchanged for existing users.

The project is used across research and industry — cited in Walmart’s pricing-anomaly pipeline, Databricks’ Kakapo/MLflow integration, IQVIA’s pharmacy-claims monitoring, and the European Space Agency’s OPS-SAT telemetry benchmark (Nature Scientific Data, 2025) — and is the reference implementation behind two JMLR/Web Conference papers on scalable and LLM-assisted outlier detection.

What You Get

• 60+ outlier-detection algorithms — from classic statistical methods (HBOS, COPOD, ECOD) to proximity-based (KNN, LOF, CBLOF) and deep-learning detectors (AutoEncoder, Deep SVDD, ALAD, DevNet, MO-GAAL) — behind one scikit-learn-compatible API
• Multi-modal coverage: dedicated detector families for tabular, time series, graph (via PyTorch Geometric), NLP/text, image, and audio anomaly detection, not just tabular data
• ADEngine, a lifecycle-orchestration engine that profiles a dataset, plans and builds an appropriate detector, runs detection, and explains the anomalies it finds in one call instead of a hand-written model-selection loop
• An agentic activation path: the od-expert skill for Claude Code/Codex and a 10-tool MCP server (list_detectors, plan_detection, run_detection, explain_findings, etc.) so LLM agents can drive investigations conversationally
• SUOD-accelerated parallel training and numba JIT compilation for per-model speedups on large datasets
• Model persistence via joblib/pickle, combination utilities for building ensembles from multiple detectors, and PyThresh integration for data-driven contamination thresholding

Common Use Cases

• Fraud and anomaly detection on tabular business data (transactions, pricing feeds, claims) using unsupervised detectors when labeled fraud examples are scarce
• Benchmarking and comparing dozens of outlier-detection algorithms on a new dataset via ADBench-style evaluation instead of manually wiring up each library separately
• Time series anomaly detection on sensor/telemetry streams (e.g. spacecraft or IoT data) using PyOD’s dedicated time-series detector family
• Building an AI-agent-driven anomaly investigation workflow (natural-language request in, ranked findings and explanation out) via the MCP server or od-expert skill
• Research and coursework in outlier detection, where a single consistent API across dozens of published algorithms simplifies reproducing and comparing results

Under The Hood

Architecture PyOD is organized around a single abstract base class, BaseDetector (pyod/models/base.py), which subclasses scikit-learn’s BaseEstimator and defines the contract every detector must implement: fit, decision_function, predict, predict_proba, and predict_confidence, plus shared post-fit attributes (decision_scores_, threshold_, labels_). Each of the 60+ algorithms (pyod/models/*.py, e.g. iforest.py, knn.py, auto_encoder.py, deep_svdd.py) is a thin, self-contained subclass that wraps either a scikit-learn estimator or a PyTorch model behind that same interface, so adding or swapping detectors doesn’t touch calling code. Above the per-algorithm layer sits ADEngine (pyod/utils/ad_engine.py, ~2000 lines), which owns a knowledge base of algorithm metadata and orchestrates the profile → plan → build → detect → explain lifecycle; cli.py and mcp_server.py are thin dispatch layers on top of ADEngine for the CLI and MCP activation paths respectively, so the core detection logic has exactly one implementation regardless of entry point.

Tech Stack Core dependencies are deliberately minimal — numpy, scipy, scikit-learn, joblib, and numba (for JIT-accelerated inner loops) — with everything else gated behind optional extras declared in pyproject.toml: torch for the deep-learning detector family, torch_geometric for graph detectors, sentence-transformers/transformers for embedding-based and NLP detectors, librosa/soundfile for audio, xgboost/combo/suod/pythresh for ensemble and thresholding methods, and mcp for the agent server. Packaging uses setuptools with a dynamic version sourced from pyod/version.py. CI runs the pytest suite across a matrix of OSes and Python versions via GitHub Actions (testing.yml, plus a separate testing-cron.yml for scheduled runs), with coverage tracked through Coveralls and CodeClimate.

Code Quality The pyod/test/ directory mirrors the models/ directory almost one-to-one, with a dedicated test file per detector (test_iforest.py, test_knn.py, test_ad_engine.py, test_cli.py, etc.) plus shared fixtures and a conftest.py, giving each of the 60+ algorithms its own regression coverage in addition to the shared BaseDetector tests. Docstrings follow the numpydoc convention consistently across modules (parameters, attributes, and return shapes documented on every public method), which is what powers the auto-generated Sphinx API reference. There is no strict static type-checking (no mypy config found) and typing is documentation-driven rather than annotation-driven, which is the main gap relative to a fully typed codebase; error handling relies on scikit-learn’s own validation utilities (check_is_fitted, check_classification_targets) rather than custom exception types.

API Design The headline design goal — “outlier detection with five lines of code” — holds up: every one of the 60+ detectors shares the identical fit/decision_function/predict/predict_proba surface, so switching from IForest to ECOD to AutoEncoder requires no code change beyond the import and constructor. On top of that uniform base, PyOD layers two progressively higher-level entry points without breaking the low-level one: ADEngine for automatic detector selection/comparison, and the od-expert skill/MCP server for natural-language-driven investigation — letting a new user start at layer one and grow into the others as needs get more automated, rather than PyOD forcing a single rigid workflow.