Python Outlier Detection Files

Highlights

• Fixed: quality['stability'] is now informative. The old formula computed the Jaccard index of nested top-k slices and collapsed to a constant ~0.817 for any reasonable k, hiding cutoff-sharpness signal from od-expert and downstream consumers. The new formula measures the standardized score gap at the rank-k boundary, clipped to [0, 1]. quality['overall'] and quality['verdict'] may shift on the same data because the constant no longer dominates the average; the od-expert skill's stability < 0.5 trigger threshold may need empirical recalibration. Closes [#667] — thanks to @Quentin62 for reporting.
• Internal: ADEngine decomposed into 4 private helper modules. pyod/utils/_quality_metrics.py, _kb_router.py, _detector_factory.py, _nl_feedback.py carry the metric, routing, factory, and feedback-parsing logic that previously lived inside ad_engine.py. The supported import path is unchanged: from pyod.utils.ad_engine import ADEngine still exposes exactly 20 public methods with the same signatures.
• Cleanup: type hints, constants, and behavior tightenings. Type hints across the helper layer; magic numbers extracted to module constants. iterate(feedback) now raises ValueError on malformed dicts (previously produced a confirm_with_user next-action silently). Per-detector exceptions in run() and analyze() now emit WARNING logs before swallowing. The natural-language feedback parser uses word-boundary regex matching instead of substring in, so a few previously incidental matches no longer fire (e.g., "withoutdoubt" no longer matches the exclude pattern).

Backward compatibility

No public API changes. Same dict keys (quality['stability'], quality['overall'], quality['verdict']), same method signatures, same default behavior except where noted above. The stability numeric value changes for the same input data because the formula changed; the key name is preserved deliberately to avoid breaking v3.2.x users.

Pull requests bundled

• [#668] — fix: ADEngine stability metric is now informative (closes [#667])
• [#669] — refactor: decompose ADEngine into private helper modules
• [#670] — refactor: ADEngine type hints, validation, exception handling, NL parser
• [#671] — chore: untrack AGENTS.md and gitignore agent infrastructure

Install

pip install --upgrade pyod

PyPI: https://pypi.org/project/pyod/3.3.0/