yzhao062/pyodA 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.
.. image:: https://raw.githubusercontent.com/yzhao062/pyod/master/brand/pyod-icon.svg :target: https://pyod.dev :alt: PyOD Ecosystem :width: 84px
PyOD 3: Agentic Anomaly Detection At Scale
|badge_website| |badge_pypi| |badge_anaconda| |badge_docs| |badge_stars| |badge_forks| |badge_downloads| |badge_testing| |badge_coverage| |badge_maintainability| |badge_license| |badge_benchmark|
.. |badge_website| image:: https://img.shields.io/badge/website-pyod.dev-990000 :target: https://pyod.dev :alt: Website
.. |badge_pypi| image:: https://img.shields.io/pypi/v/pyod.svg?color=brightgreen :target: https://pypi.org/project/pyod/ :alt: PyPI version
.. |badge_anaconda| image:: https://anaconda.org/conda-forge/pyod/badges/version.svg :target: https://anaconda.org/conda-forge/pyod :alt: Anaconda version
.. |badge_docs| image:: https://readthedocs.org/projects/pyod/badge/?version=latest :target: https://pyod.readthedocs.io/en/latest/?badge=latest :alt: Documentation status
.. |badge_stars| image:: https://img.shields.io/github/stars/yzhao062/pyod.svg :target: https://github.com/yzhao062/pyod/stargazers :alt: GitHub stars
.. |badge_forks| image:: https://img.shields.io/github/forks/yzhao062/pyod.svg?color=blue :target: https://github.com/yzhao062/pyod/network :alt: GitHub forks
.. |badge_downloads| image:: https://pepy.tech/badge/pyod :target: https://pepy.tech/project/pyod :alt: Downloads
.. |badge_testing| image:: https://github.com/yzhao062/pyod/actions/workflows/testing.yml/badge.svg :target: https://github.com/yzhao062/pyod/actions/workflows/testing.yml :alt: Testing
.. |badge_coverage| image:: https://coveralls.io/repos/github/yzhao062/pyod/badge.svg :target: https://coveralls.io/github/yzhao062/pyod :alt: Coverage Status
.. |badge_maintainability| image:: https://api.codeclimate.com/v1/badges/bdc3d8d0454274c753c4/maintainability :target: https://codeclimate.com/github/yzhao062/Pyod/maintainability :alt: Maintainability
.. |badge_license| image:: https://img.shields.io/github/license/yzhao062/pyod.svg :target: https://github.com/yzhao062/pyod/blob/master/LICENSE :alt: License
.. |badge_benchmark| image:: https://img.shields.io/badge/ADBench-benchmark_results-pink :target: https://github.com/Minqi824/ADBench :alt: Benchmark
**PyOD is agent-ready.** Claude Code and Codex can use the ``od-expert`` skill to drive ADEngine investigations, while MCP-compatible agents can query PyOD's detector knowledge and planning tools. The classic ``fit``/``predict`` API stays unchanged.
PyOD 3 is the most comprehensive Python library for anomaly detection. Four pillars:
=========================== ========================================================================================
Pillar What it means
=========================== ========================================================================================
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 46+ million downloads; benchmark-backed routing (ADBench, TSB-AD, BOND, NLP-ADBench)
=========================== ========================================================================================
Install ^^^^^^^
Core library (required for every activation path):
.. code-block:: bash
pip install pyod
Then pick the activation path that matches your agent stack:
.. code-block:: bash
# 1. Claude Code / Codex — enables the od-expert skill
pyod install skill # Claude Code: user-global (~/.claude/skills/)
pyod install skill --project # Codex: project-local (./skills/, Codex has no user-global dir)
# 2. Any MCP-compatible LLM — requires the optional mcp extra
pip install pyod[mcp]
pyod mcp serve # alias for `python -m pyod.mcp_server`
# 3. Pure Python — no extra step
# from pyod.utils.ad_engine import ADEngine
Run pyod info at any time to see version, detector counts, and
the install state of each activation path. pyod info also detects
which agent stack you have installed (~/.claude/ for Claude Code,
~/.codex/ for Codex) and recommends the right install command.
For conda, source install, dependency details, and troubleshooting,
see the full installation guide <https://pyod.readthedocs.io/en/latest/install.html>__.
The legacy pyod-install-skill command from v3.0.0 still works as an
alias for pyod install skill.
Outlier Detection with 5 Lines of Code (pip install pyod):
.. code-block:: python
from pyod.models.iforest import IForest
clf = IForest()
clf.fit(X_train)
y_train_scores = clf.decision_scores_ # training anomaly scores
y_test_scores = clf.decision_function(X_test) # test anomaly scores
Three ways to use PyOD:
========= ===================== ====================================================================== =======================================
Layer Name When to use Entry point
========= ===================== ====================================================================== =======================================
1 Classic API You know which detector you want Layer 1 examples <https://pyod.readthedocs.io/en/latest/examples/tabular.html>__
2 ADEngine You want PyOD to choose, compare, and assess automatically Layer 2 walkthrough <https://pyod.readthedocs.io/en/latest/examples/adengine.html>__
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 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 :align: center :width: 720
The figure above shows a real 5-turn agentic conversation on the UCI Cardiotocography dataset. See the full walkthrough <https://pyod.readthedocs.io/en/latest/examples/agentic.html>, runnable agentic example <https://github.com/yzhao062/pyod/blob/development/examples/agentic_example.py>, or interactive HTML demo <https://htmlpreview.github.io/?https://github.com/yzhao062/pyod/blob/development/examples/agentic_demo.html>__.
PyOD Ecosystem & Resources: