PyOD 3.0.0 — Agentic Anomaly Detection At Scale

PyOD 3 repositions the library around a three-layer architecture and adds multi-modal detector coverage while keeping the classic fit/predict API fully backward-compatible.

Layer 1 — Classic API: 60+ detectors across tabular, time series, graph, text, and image data with a single BaseDetector interface.
Layer 2 — ADEngine: intelligent orchestration that profiles data, selects benchmark-backed detectors (ADBench, TSB-AD, BOND, NLP-ADBench), runs top-N in parallel, computes consensus, and assesses result quality in one investigate(X) call.
Layer 3 — Agentic Investigation: a full session API (start, plan, run, analyze, iterate, report) so any AI agent can drive an expert-level investigation through natural conversation. Ships with an od-expert skill for Claude Code and an MCP server for any MCP-compatible LLM.

What's new

Detector modalities

Graph (pip install pyod[graph]): 8 PyG-based detectors (DOMINANT, CoLA, CONAD, AnomalyDAE, GUIDE, Radar, ANOMALOUS, SCAN) routed via the BOND benchmark (NeurIPS 2022).
Time series: 5 stable detectors (TimeSeriesOD, MatrixProfile, SpectralResidual, KShape, LSTMAD) plus 2 experimental (SAND, AnomalyTransformer) routed via the TSB-AD benchmark (NeurIPS 2024).
Text and image: EmbeddingOD adds multi-modal anomaly detection via foundation model embeddings (sentence-transformers, OpenAI, HuggingFace). Routed via NLP-ADBench.

Intelligence layer

ADEngine with a JSON-backed knowledge base of 58 detector metadata entries (benchmark rankings, complexity, strengths, weaknesses, preprocessing modes).
Multi-detector rank-normalized consensus plus quality metrics (separation, agreement, stability) plus actionable iteration on structured or natural-language feedback.
od-expert skill for Claude Code and MCP server for any MCP-compatible LLM.

Packaging modernization

Migrated from setup.py to pyproject.toml (PEP 621) with SPDX license metadata, dynamic version and dependencies from requirements.txt, and modern extras (pyod[torch], [suod], [xgboost], [combo], [pythresh], [embedding], [openai], [huggingface], [graph], [mcp], [all]).
Python floor bumped to >=3.9; CI tests on 3.9 through 3.13.
New pyod-install-skill console script that copies the bundled Claude Code skill into ~/.claude/skills/od-expert/ after pip install.

Documentation redesign

README and Sphinx docs both lead with the three-layer story. New docs/examples/ directory with 9 walkthroughs (agentic, ADEngine, tabular, time series, graph, embedding, combination, thresholding, index).
API reference split by modality: pyod.models.tabular, pyod.models.timeseries, pyod.models.graph, pyod.models.embedding, pyod.ad_engine, pyod.utils.
New docs/impact.rst page documenting PyOD's reach: ESA OPS-SAT (Nature Scientific Data, 2025), Walmart, Databricks, IQVIA, Ericsson, 3+ dedicated books, 2 major podcasts, 60+ third-party media references.

Backwards compatibility

No breaking API changes. All existing BaseDetector subclasses and fit/predict calls continue to work unchanged.

Install

pip install --upgrade pyod
pyod-install-skill            # optional: install the od-expert skill for Claude Code
python -m pyod.mcp_server     # optional: start the MCP server for any MCP-compatible LLM

5 Lines of Code

from pyod.models.iforest import IForest
clf = IForest()
clf.fit(X_train)
y_train_scores = clf.decision_scores_
y_test_scores = clf.decision_function(X_test)

Documentation

Full V3 docs: https://pyod.readthedocs.io
Agentic walkthrough: https://pyod.readthedocs.io/en/latest/examples/agentic.html
Impact page: https://pyod.readthedocs.io/en/latest/impact.html
PyPI: https://pypi.org/project/pyod/3.0.0/

Citing

If you use PyOD in research, please cite:

@inproceedings{chen2025pyod,
  title={PyOD 2: A Python Library for Outlier Detection with LLM-powered Model Selection},
  author={Chen, Sihan and Qian, Zhuangzhuang and Siu, Wingchun and Hu, Xingcan and Li, Jiaqi and Li, Shawn and Qin, Yuehan and Yang, Tiankai and Xiao, Zhuo and Ye, Wanghao and others},
  booktitle={Companion Proceedings of the ACM on Web Conference 2025},
  pages={2807--2810},
  year={2025}
}

The original 2019 JMLR paper remains the canonical library reference:

@article{zhao2019pyod,
  author  = {Zhao, Yue and Nasrullah, Zain and Li, Zheng},
  title   = {PyOD: A Python Toolbox for Scalable Outlier Detection},
  journal = {Journal of Machine Learning Research},
  year    = {2019},
  volume  = {20},
  number  = {96},
  pages   = {1-7},
  url     = {http://jmlr.org/papers/v20/19-011.html}
}

yzhao062/pyod v3.0.0 on GitHub