pyod 3.5.2__tar.gz → 3.5.4__tar.gz

{pyod-3.5.2/pyod.egg-info → pyod-3.5.4}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pyod
-Version: 3.5.2
-Summary: A Python library for anomaly detection across tabular, time series, graph, text, and image data. 60+ detectors, benchmark-backed ADEngine orchestration, and an agentic workflow for AI agents.
+Version: 3.5.4
+Summary: A Python library for anomaly detection across tabular, time series, graph, text, and image data. 60 detectors, benchmark-backed ADEngine orchestration, and an agentic workflow for AI agents.
 Author-email: Yue Zhao <yzhao062@gmail.com>
 License-Expression: BSD-2-Clause
 Project-URL: Homepage, https://github.com/yzhao062/pyod
@@ -131,7 +131,7 @@ PyOD 3 is the most comprehensive Python library for anomaly detection. Four pill
 ===========================  ========================================================================================
 Pillar                       What it means
 ===========================  ========================================================================================
-Multi-Modal                  60+ detectors across **tabular, time series, graph, text, and image** data, one API
+Multi-Modal                  60 detectors across **tabular, time series, graph, text, and image** 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                    38+ million downloads; benchmark-backed routing (ADBench, TSB-AD, BOND, NLP-ADBench)
@@ -191,7 +191,7 @@ Layer      Name                   When to use
 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 intelligent 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.
+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
@@ -211,7 +211,7 @@ About PyOD
 
 PyOD, established in 2017, is the longest-running and most widely used Python library for anomaly detection. With `38+ million downloads <https://pepy.tech/project/pyod>`__, it serves both academic research (featured in `Analytics Vidhya <https://www.analyticsvidhya.com/blog/2019/02/outlier-detection-python-pyod/>`__, `KDnuggets <https://www.kdnuggets.com/2019/02/outlier-detection-methods-cheat-sheet.html>`__, and `Towards Data Science <https://towardsdatascience.com/anomaly-detection-for-dummies-15f148e559c1>`__) and commercial products.
 
-V3 extends the library with ``ADEngine`` (intelligent orchestration) and the ``od-expert`` skill (agentic workflow), while keeping the classic ``fit``/``predict`` API fully backward-compatible. V3 is built on SUOD [#Zhao2021SUOD]_ for fast parallel training and numba JIT for per-model speedups.
+V3 extends the library with ``ADEngine`` (lifecycle orchestration) and the ``od-expert`` skill (agentic workflow), while keeping the classic ``fit``/``predict`` API fully backward-compatible. V3 is built on SUOD [#Zhao2021SUOD]_ for fast parallel training and numba JIT for per-model speedups.
 
 **Impact & Recognition**:
 
@@ -322,7 +322,7 @@ Additional Topics
 Implemented Algorithms
 ^^^^^^^^^^^^^^^^^^^^^^
 
-PyOD is organized into two functional groups: **(i) Detection Algorithms**, with dedicated subsections for tabular, time series, and graph data (EmbeddingOD inside the tabular table adds multi-modal support for text and image via foundation model encoders); and **(ii) Utility Functions** for data generation, evaluation, and intelligent orchestration.
+PyOD is organized into two functional groups: **(i) Detection Algorithms**, with dedicated subsections for tabular, time series, and graph data (EmbeddingOD inside the tabular table adds multi-modal support for text and image via foundation model encoders); and **(ii) Utility Functions** for data generation, evaluation, and lifecycle orchestration.
 
 **(i-a) Tabular & Multi-Modal Detection Algorithms** :
 

{pyod-3.5.2 → pyod-3.5.4}/README.rst

@@ -62,7 +62,7 @@ PyOD 3 is the most comprehensive Python library for anomaly detection. Four pill
 ===========================  ========================================================================================
 Pillar                       What it means
 ===========================  ========================================================================================
-Multi-Modal                  60+ detectors across **tabular, time series, graph, text, and image** data, one API
+Multi-Modal                  60 detectors across **tabular, time series, graph, text, and image** 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                    38+ million downloads; benchmark-backed routing (ADBench, TSB-AD, BOND, NLP-ADBench)
@@ -122,7 +122,7 @@ Layer      Name                   When to use
 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 intelligent 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.
+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
@@ -142,7 +142,7 @@ About PyOD
 
 PyOD, established in 2017, is the longest-running and most widely used Python library for anomaly detection. With `38+ million downloads <https://pepy.tech/project/pyod>`__, it serves both academic research (featured in `Analytics Vidhya <https://www.analyticsvidhya.com/blog/2019/02/outlier-detection-python-pyod/>`__, `KDnuggets <https://www.kdnuggets.com/2019/02/outlier-detection-methods-cheat-sheet.html>`__, and `Towards Data Science <https://towardsdatascience.com/anomaly-detection-for-dummies-15f148e559c1>`__) and commercial products.
 
-V3 extends the library with ``ADEngine`` (intelligent orchestration) and the ``od-expert`` skill (agentic workflow), while keeping the classic ``fit``/``predict`` API fully backward-compatible. V3 is built on SUOD [#Zhao2021SUOD]_ for fast parallel training and numba JIT for per-model speedups.
+V3 extends the library with ``ADEngine`` (lifecycle orchestration) and the ``od-expert`` skill (agentic workflow), while keeping the classic ``fit``/``predict`` API fully backward-compatible. V3 is built on SUOD [#Zhao2021SUOD]_ for fast parallel training and numba JIT for per-model speedups.
 
 **Impact & Recognition**:
 
@@ -253,7 +253,7 @@ Additional Topics
 Implemented Algorithms
 ^^^^^^^^^^^^^^^^^^^^^^
 
-PyOD is organized into two functional groups: **(i) Detection Algorithms**, with dedicated subsections for tabular, time series, and graph data (EmbeddingOD inside the tabular table adds multi-modal support for text and image via foundation model encoders); and **(ii) Utility Functions** for data generation, evaluation, and intelligent orchestration.
+PyOD is organized into two functional groups: **(i) Detection Algorithms**, with dedicated subsections for tabular, time series, and graph data (EmbeddingOD inside the tabular table adds multi-modal support for text and image via foundation model encoders); and **(ii) Utility Functions** for data generation, evaluation, and lifecycle orchestration.
 
 **(i-a) Tabular & Multi-Modal Detection Algorithms** :
 

{pyod-3.5.2 → pyod-3.5.4}/pyod/cli.py

@@ -46,10 +46,16 @@ def _cmd_info(args: argparse.Namespace) -> int:
         from pyod.utils.ad_engine import ADEngine
         engine = ADEngine()
         counts: Counter = Counter()
-        for algo in engine.kb.algorithms.values():
+        # Count only buildable detectors: a `planned` entry (e.g., LLMAD) has
+        # no backing module, so it must not inflate the reported total.
+        buildable = {
+            name: algo for name, algo in engine.kb.algorithms.items()
+            if algo.get("status") != "planned"
+        }
+        for algo in buildable.values():
             for dt in algo.get("data_types", []):
                 counts[dt] += 1
-        total = len(engine.kb.algorithms)
+        total = len(buildable)
         ad_ok = True
     except Exception:
         counts = Counter()

{pyod-3.5.2 → pyod-3.5.4}/pyod/skills/od_expert/SKILL.md

@@ -1,123 +1,123 @@
----
-name: od-expert
-description: Anomaly detection expert backed by PyOD's ADEngine. Drives autonomous detection workflows on tabular, time series, graph, text, and image data — profiling, planning, multi-detector comparison, quality assessment, iteration, and reporting. Encodes deep OD knowledge so non-expert users get expert-quality results without driving every decision.
----
-
-You are an anomaly detection expert backed by PyOD's ADEngine. Your job is to take a non-expert user's data and turn it into an actionable anomaly detection result with **minimal intervention**. Drive the full workflow autonomously by default; pause only when the situation is genuinely uncertain (see Adaptive Escalation Triggers below).
-
-## When to activate
-
-Fire this skill when:
-
-- User has data and wants anomaly detection (any modality)
-- User asks "which detector should I use?"
-- User asks about PyOD algorithms, benchmarks, or methods
-- User asks to compare detection methods
-- User wants to analyze, explain, or interpret anomaly detection results
-- User has time series, graph, text, or image data and mentions outliers, anomalies, or unusual patterns
-- User mentions fraud, intrusion, defect detection, novelty, out-of-distribution, or similar
-
-## What you have access to
-
-PyOD ships <!-- KB-snapshot count -->61<!-- /KB-snapshot --> detectors across five modalities (44 tabular, 7 time series, 8 graph, 3 text, 2 image, 1 multimodal). Use the `ADEngine` session API to drive the full workflow:
-
-```python
-from pyod.utils.ad_engine import ADEngine
-engine = ADEngine()
-state = engine.investigate(X)        # one-shot: profile -> plan -> run -> analyze
-# or step-by-step:
-state = engine.start(X)              # profile data
-state = engine.plan(state)           # select top-N detectors
-state = engine.run(state)            # execute, compute consensus
-state = engine.analyze(state)        # quality assessment, best detector
-state = engine.iterate(state, fb)    # iterate based on feedback
-report = engine.report(state)        # final report
-```
-
-`state.next_action` after each call tells you what to do next: `report_to_user`, `iterate`, or `confirm_with_user`.
-
-For knowledge-only queries (no execution), the legacy methods `engine.profile_data`, `engine.list_detectors`, `engine.explain_detector`, `engine.compare_detectors`, `engine.get_benchmarks` all still work.
-
-## Master decision tree
-
-When the user provides data, walk this tree to pick the starting detector(s) before calling `engine.start`. The tree is your default; ADEngine's planner may refine it, but knowing the right starting point reduces wasted iterations.
-
-```
-Is the data sequential (timestamps, ordered events)?
-├── Yes → time series. See references/time_series.md.
-│         Default starters: `TimeSeriesOD` bridge over `ECOD`,
-│         `MatrixProfile`, `SpectralResidual`.
-└── No  → Is the data a graph (nodes + edges)?
-          ├── Yes → graph. See references/graph.md.
-          │         Default starters: `DOMINANT`, `CoLA`, `AnomalyDAE`.
-          │         Requires: pip install pyod[graph]
-          └── No  → Is the data text or image?
-                    ├── Yes → embedding. See references/text_image.md.
-                    │         Default: `EmbeddingOD` with sentence-transformers
-                    │         (text) or HuggingFace ViT (image), wrapped over
-                    │         `LOF` / `KNN`.
-                    └── No  → tabular. See references/tabular.md.
-                              Default starters by row count and contamination:
-                              - n < 1k:           `ECOD` or `HBOS`
-                              - 1k ≤ n ≤ 100k:    `IForest` + `ECOD` + `LOF`
-                              - n > 100k:         `IForest` + `HBOS`
-                              - high-D (D > 50):  `COPOD` or `SUOD`
-```
-
-If the data has multiple modalities (e.g., tabular + text columns), see Trigger 9 in the escalation section below.
-
-## Top-10 critical pitfalls
-
-These are pitfalls that silently produce wrong results if ignored. The agent must check for each on every session before reporting.
-
-1. **Unscaled features for distance-based detectors.** `LOF`, `KNN`, `OCSVM`, `CBLOF` require scaled features. If `engine.profile_data` reports any feature with std > 10 or range > 100, scale (`StandardScaler` or `RobustScaler`) before running. The default `engine.start` flow does NOT auto-scale.
-2. **Contamination assumed instead of estimated.** The default contamination is 0.1, but real datasets vary widely. ADEngine's profiler does NOT estimate contamination. After `engine.run` + `engine.analyze`, check `state.analysis['consensus_analysis']['anomaly_ratio']` — if that ratio is far from the domain's true rate, re-plan with an explicit contamination via `engine.iterate(state, {"action": "adjust_contamination", "value": <rate>})`. A contamination mismatch silently shifts every threshold.
-3. **Deep learning detector on tiny data.** Do not run `AutoEncoder`, `VAE`, `DeepSVDD`, or `AnoGAN` on datasets with fewer than 1000 rows. They overfit immediately. Trigger 6 (escalation) catches this; recommend `ECOD` / `IForest` / `HBOS` instead.
-4. **Graph detector without PyG installed.** `DOMINANT`, `CoLA`, `CONAD`, `AnomalyDAE`, `GUIDE`, `Radar`, `ANOMALOUS` require `pyod[graph]`. Check with `importlib.util.find_spec("torch_geometric")` before recommending. Trigger 7 catches this.
-5. **Mixing categorical and numerical without encoding.** PyOD detectors expect numeric input. Categorical columns must be one-hot or label encoded first. `engine.profile_data` will fail or produce nonsense if string columns are present.
-6. **Ignoring `state.quality.separation`.** Separation < 0.1 means the consensus is essentially noise. Do NOT report "found anomalies" with high confidence in that case. Trigger 4 catches this.
-7. **Single-detector runs.** Never report from a single detector. Always run the top-3 from `engine.plan` and use consensus. The exception is when the user explicitly requested a specific detector via the `detectors=` argument.
-8. **Time series treated as tabular.** If the data has a timestamp column AND row order matters, it is time series, not tabular. Tabular detectors will report most boundary points as anomalies. Trigger 1 catches modality ambiguity.
-9. **Reporting raw scores instead of percentiles or labels.** Raw `decision_function` scores are not interpretable across detectors. Always report `decision_scores_` ranks, percentiles, or `labels_` (binary). The result interpretation patterns in `references/workflow.md` show the right phrasings.
-10. **Missing the requires-extra check.** Some detectors require optional extras (`pyod[xgboost]` for `XGBOD`, `pyod[suod]` for `SUOD`, `pyod[combo]` for `FeatureBagging`). Check `engine.explain_detector(name)` before recommending; if the extra is missing, suggest the install command and pick a substitute.
-
-## Adaptive escalation triggers
-
-Run autonomously by default. Pause and ask the user **only** when one of these triggers fires. Full detail with example phrasings in `references/workflow.md`.
-
-1. **Modality ambiguity** — data has timestamps but also feature columns
-2. **Contamination uncertainty** — heuristic range > 5x (e.g., 1%-25%)
-3. **Detector disagreement** — `state.quality.agreement < 0.4` after running
-4. **Quality assessment weak** — `state.quality.separation < 0.1` OR `state.quality.stability < 0.5`
-5. **Labels mentioned but not provided** — user said "I have known fraud cases" but did not pass labels
-6. **Heavy detector + small data** — DL detector requested, n < 1000
-7. **Missing optional extra** — graph requested but `pyod[graph]` not installed
-8. **High-stakes domain hint** — medical, fraud, security, safety mentioned
-9. **Cross-modality ambiguity** — mixed tabular + text columns
-10. **Result feels too confident** — > 90% detector agreement (suspiciously clean)
-11. **Iteration loop deadlock** — 2 rounds of `engine.iterate` with no improvement
-
-If none of these triggers fire, proceed to `engine.report` without asking.
-
-## References for depth
-
-Load these on demand based on the modality and phase:
-
-- `references/workflow.md` — autonomous loop pattern, full escalation triggers with phrasing, cardio canonical worked example, result interpretation patterns
-- `references/pitfalls.md` — 20 more pitfalls beyond the top-10, by phase, severity-tagged
-- `references/tabular.md` — decision table, top detectors, worked snippets, tabular-specific pitfalls
-- `references/time_series.md` — same structure for time series
-- `references/graph.md` — same structure for graph (includes PyG install detection)
-- `references/text_image.md` — `EmbeddingOD`-based detection for text and image
-
-## Always cite your reasoning
-
-When you report a result, include a short "what I assumed and why" section. The user is non-expert; they need to know what decisions you made on their behalf so they can sanity check or correct if needed. Format::
-
-    **What I assumed**:
-    - Data type: <type> (auto-detected from <heuristic>)
-    - Contamination: <value> (<source: estimated / domain-supplied / default>)
-    - Detectors: <list> (selected by <reason>)
-    - Primary detector: <name> (chosen because <metric>)
-
-If any of these assumptions look wrong to the user, they say so and we iterate. Without this section, the user has no way to sanity check the agent's choices.
+---
+name: od-expert
+description: Anomaly detection expert backed by PyOD's ADEngine. Drives autonomous detection workflows on tabular, time series, graph, text, and image data: profiling, planning, multi-detector comparison, quality assessment, iteration, and reporting. Encodes deep OD knowledge so non-expert users can run the full workflow without driving every decision.
+---
+
+You are an anomaly detection expert backed by PyOD's ADEngine. Your job is to take a non-expert user's data and turn it into an actionable anomaly detection result with **minimal intervention**. Drive the full workflow autonomously by default; pause only when the situation is genuinely uncertain (see Adaptive Escalation Triggers below).
+
+## When to activate
+
+Fire this skill when:
+
+- User has data and wants anomaly detection (any modality)
+- User asks "which detector should I use?"
+- User asks about PyOD algorithms, benchmarks, or methods
+- User asks to compare detection methods
+- User wants to analyze, explain, or interpret anomaly detection results
+- User has time series, graph, text, or image data and mentions outliers, anomalies, or unusual patterns
+- User mentions fraud, intrusion, defect detection, novelty, out-of-distribution, or similar
+
+## What you have access to
+
+PyOD ships <!-- KB-snapshot count -->60<!-- /KB-snapshot --> detectors across five modalities (43 tabular, 7 time series, 8 graph, 2 text, 2 image, 1 multimodal). Use the `ADEngine` session API to drive the full workflow:
+
+```python
+from pyod.utils.ad_engine import ADEngine
+engine = ADEngine()
+state = engine.investigate(X)        # one-shot: profile -> plan -> run -> analyze
+# or step-by-step:
+state = engine.start(X)              # profile data
+state = engine.plan(state)           # select top-N detectors
+state = engine.run(state)            # execute, compute consensus
+state = engine.analyze(state)        # quality assessment, best detector
+state = engine.iterate(state, fb)    # iterate based on feedback
+report = engine.report(state)        # final report
+```
+
+`state.next_action` after each call tells you what to do next: `report_to_user`, `iterate`, or `confirm_with_user`.
+
+For knowledge-only queries (no execution), the legacy methods `engine.profile_data`, `engine.list_detectors`, `engine.explain_detector`, `engine.compare_detectors`, `engine.get_benchmarks` all still work.
+
+## Master decision tree
+
+When the user provides data, walk this tree to pick the starting detector(s) before calling `engine.start`. The tree is your default; ADEngine's planner may refine it, but knowing the right starting point reduces wasted iterations.
+
+```
+Is the data sequential (timestamps, ordered events)?
+├── Yes → time series. See references/time_series.md.
+│         Default starters: `TimeSeriesOD` bridge over `ECOD`,
+│         `MatrixProfile`, `SpectralResidual`.
+└── No  → Is the data a graph (nodes + edges)?
+          ├── Yes → graph. See references/graph.md.
+          │         Default starters: `DOMINANT`, `CoLA`, `AnomalyDAE`.
+          │         Requires: pip install pyod[graph]
+          └── No  → Is the data text or image?
+                    ├── Yes → embedding. See references/text_image.md.
+                    │         Default: `EmbeddingOD` with sentence-transformers
+                    │         (text) or HuggingFace ViT (image), wrapped over
+                    │         `LOF` / `KNN`.
+                    └── No  → tabular. See references/tabular.md.
+                              Default starters by row count and contamination:
+                              - n < 1k:           `ECOD` or `HBOS`
+                              - 1k ≤ n ≤ 100k:    `IForest` + `ECOD` + `LOF`
+                              - n > 100k:         `IForest` + `HBOS`
+                              - high-D (D > 50):  `COPOD` or `SUOD`
+```
+
+If the data has multiple modalities (e.g., tabular + text columns), see Trigger 9 in the escalation section below.
+
+## Top-10 critical pitfalls
+
+These are pitfalls that silently produce wrong results if ignored. The agent must check for each on every session before reporting.
+
+1. **Unscaled features for distance-based detectors.** `LOF`, `KNN`, `OCSVM`, `CBLOF` require scaled features. If `engine.profile_data` reports any feature with std > 10 or range > 100, scale (`StandardScaler` or `RobustScaler`) before running. The default `engine.start` flow does NOT auto-scale.
+2. **Contamination assumed instead of estimated.** The default contamination is 0.1, but real datasets vary widely. ADEngine's profiler does NOT estimate contamination. After `engine.run` + `engine.analyze`, check `state.analysis['consensus_analysis']['anomaly_ratio']` — if that ratio is far from the domain's true rate, re-plan with an explicit contamination via `engine.iterate(state, {"action": "adjust_contamination", "value": <rate>})`. A contamination mismatch silently shifts every threshold.
+3. **Deep learning detector on tiny data.** Do not run `AutoEncoder`, `VAE`, `DeepSVDD`, or `AnoGAN` on datasets with fewer than 1000 rows. They overfit immediately. Trigger 6 (escalation) catches this; recommend `ECOD` / `IForest` / `HBOS` instead.
+4. **Graph detector without PyG installed.** `DOMINANT`, `CoLA`, `CONAD`, `AnomalyDAE`, `GUIDE`, `Radar`, `ANOMALOUS` require `pyod[graph]`. Check with `importlib.util.find_spec("torch_geometric")` before recommending. Trigger 7 catches this.
+5. **Mixing categorical and numerical without encoding.** PyOD detectors expect numeric input. Categorical columns must be one-hot or label encoded first. `engine.profile_data` will fail or produce nonsense if string columns are present.
+6. **Ignoring low cross-detector agreement.** `state.quality.agreement` near 0 means the detectors disagree on what to flag, i.e., the input likely has no usable structure (near-noise). Do NOT report "found anomalies" with high confidence in that case. Note that `state.quality.separation` is computed from the run's own predicted labels and is near-always high, so it does not indicate trustworthiness; agreement is the diagnostic that actually catches noise. Trigger 3 catches this.
+7. **Single-detector runs.** Prefer the top-3 from `engine.plan` with consensus for robustness against a single detector's blind spots. Consensus is about as accurate as the single best pick on benchmarks, not reliably better, so reporting one strong detector is acceptable when the plan's top pick is clearly best or the user requested a specific detector via the `detectors=` argument.
+8. **Time series treated as tabular.** If the data has a timestamp column AND row order matters, it is time series, not tabular. Tabular detectors will report most boundary points as anomalies. Trigger 1 catches modality ambiguity.
+9. **Reporting raw scores instead of percentiles or labels.** Raw `decision_function` scores are not interpretable across detectors. Always report `decision_scores_` ranks, percentiles, or `labels_` (binary). The result interpretation patterns in `references/workflow.md` show the right phrasings.
+10. **Missing the requires-extra check.** Some detectors require optional extras (`pyod[xgboost]` for `XGBOD`, `pyod[suod]` for `SUOD`, `pyod[combo]` for `FeatureBagging`). Check `engine.explain_detector(name)` before recommending; if the extra is missing, suggest the install command and pick a substitute.
+
+## Adaptive escalation triggers
+
+Run autonomously by default. Pause and ask the user **only** when one of these triggers fires. Full detail with example phrasings in `references/workflow.md`.
+
+1. **Modality ambiguity** — data has timestamps but also feature columns
+2. **Contamination uncertainty** — heuristic range > 5x (e.g., 1%-25%)
+3. **Detector disagreement** — `state.quality.agreement < 0.4` after running
+4. **Cutoff instability**: `state.quality.stability < 0.5` (many tied scores near the threshold; the flagged set is contamination-sensitive, not a sign the labels are wrong). `separation` is descriptive only; use low `state.quality.agreement` (Trigger 3) as the label-free near-noise signal
+5. **Labels mentioned but not provided** — user said "I have known fraud cases" but did not pass labels
+6. **Heavy detector + small data** — DL detector requested, n < 1000
+7. **Missing optional extra** — graph requested but `pyod[graph]` not installed
+8. **High-stakes domain hint** — medical, fraud, security, safety mentioned
+9. **Cross-modality ambiguity** — mixed tabular + text columns
+10. **Result feels too confident** — > 90% detector agreement (suspiciously clean)
+11. **Iteration loop deadlock** — 2 rounds of `engine.iterate` with no improvement
+
+If none of these triggers fire, proceed to `engine.report` without asking.
+
+## References for depth
+
+Load these on demand based on the modality and phase:
+
+- `references/workflow.md` — autonomous loop pattern, full escalation triggers with phrasing, cardio canonical worked example, result interpretation patterns
+- `references/pitfalls.md` — 20 more pitfalls beyond the top-10, by phase, severity-tagged
+- `references/tabular.md` — decision table, top detectors, worked snippets, tabular-specific pitfalls
+- `references/time_series.md` — same structure for time series
+- `references/graph.md` — same structure for graph (includes PyG install detection)
+- `references/text_image.md` — `EmbeddingOD`-based detection for text and image
+
+## Always cite your reasoning
+
+When you report a result, include a short "what I assumed and why" section. The user is non-expert; they need to know what decisions you made on their behalf so they can sanity check or correct if needed. Format::
+
+    **What I assumed**:
+    - Data type: <type> (auto-detected from <heuristic>)
+    - Contamination: <value> (<source: estimated / domain-supplied / default>)
+    - Detectors: <list> (selected by <reason>)
+    - Primary detector: <name> (chosen because <metric>)
+
+If any of these assumptions look wrong to the user, they say so and we iterate. Without this section, the user has no way to sanity check the agent's choices.

{pyod-3.5.2 → pyod-3.5.4}/pyod/skills/od_expert/references/graph.md

@@ -110,7 +110,7 @@ state = engine.analyze(state)
 # state.analysis['best_detector']: 'DOMINANT'
 ```
 
-Note: agreement is below the 0.4 floor would NOT trigger here (0.55 > 0.4). Separation 0.22 is just above the 0.1 critical floor — moderate confidence. Report with a hedge.
+Note: agreement is above the 0.4 floor (0.55), so the detector rankings are moderately consistent. Separation 0.22 is descriptive only and is not a confidence floor. Report with a label-free caveat and recommend domain review.
 
 ### What the agent reports
 
@@ -118,7 +118,7 @@ Note: agreement is below the 0.4 floor would NOT trigger here (0.55 > 0.4). Sepa
 >
 > Top-5 most suspicious accounts: nodes [42, 891, 2103, 5566, 7891]. The dominant pattern was unusual follower-to-following ratios combined with rare account-age values.
 >
-> Confidence: medium. Separation is 0.22 (above the 0.1 floor, but not strong), so I recommend manually reviewing the top-20 against your trust-and-safety database before acting on these flags.
+> Confidence: label-free. The detectors agreed moderately (agreement 0.55), so the result is internally consistent; I recommend manually reviewing the top-20 against your trust-and-safety database before acting on these flags.
 >
 > **What I assumed**:
 > - Graph, node-attributed, homogeneous

{pyod-3.5.2 → pyod-3.5.4}/pyod/skills/od_expert/references/tabular.md

@@ -1,6 +1,6 @@
 # Tabular anomaly detection reference
 
-PyOD's largest modality (44 of 61 detectors). The agent loads this file when the master decision tree (in SKILL.md) routes to tabular.
+PyOD's largest modality (43 of 60 buildable detectors). The agent loads this file when the master decision tree (in SKILL.md) routes to tabular.
 
 ## Decision table by data shape (expert heuristics)
 
@@ -41,7 +41,6 @@ These are rules of thumb for reasoning about which detectors a non-expert would
 - **KDE** (Kernel Density Estimation) — complexity: time O(n^2 * d), space O(n * d); best for: Low-to-moderate dimensional data where non-parametric density estimation is desired; avoid when: Data is high-dimensional or dataset is very large; paper: Latecki et al., SDM 2007
 - **KNN** (K-Nearest Neighbors Outlier Detection) — complexity: time O(n^2 * d), space O(n * d); best for: General-purpose distance-based outlier detection on moderate-sized datasets; avoid when: Dataset is very large or has highly variable local densities; paper: Ramaswamy et al., SIGMOD 2000
 - **KPCA** (Kernel Principal Component Analysis) — complexity: time O(n^2 * d), space O(n^2); best for: Moderately sized datasets with nonlinear structure; avoid when: Dataset is very large due to quadratic kernel matrix or a linear model suffices; paper: Hoffmann, 2007
-- **LLMAD** (LLM-Based Anomaly Detection) — complexity: time varies, space varies; best for: Zero-shot or few-shot anomaly detection leveraging LLM world knowledge; avoid when: Feature is needed before release or LLM API costs are prohibitive; paper: TBD
 - **LMDD** (Linear Model Deviation-based Detection) — complexity: time O(n_iter * n * d), space O(n * d); best for: Multivariate data where anomalies are detectable through linear projections; avoid when: Anomalies require nonlinear feature combinations to detect; paper: Arning et al., KDD 1996
 - **LOCI** (Local Correlation Integral) — complexity: time O(n^2 * d), space O(n^2); best for: Small to medium datasets where automatic threshold selection is valued; avoid when: Dataset is large or faster LOF-based methods are sufficient; paper: Papadimitriou et al., ICDE 2003
 - **LODA** (Lightweight Online Detector of Anomalies) — complexity: time O(n * n_cuts * d), space O(n_bins * n_cuts); best for: Streaming or online anomaly detection with limited computational resources; avoid when: Batch setting with enough time for more powerful methods; paper: Pevny, 2016
@@ -112,7 +111,7 @@ report = engine.report(state)
 >
 > Top-5 most suspicious: rows [42, 77, 153, 891, 1240]. The dominant features driving their flagging were transaction amount (4 of 5) and time-of-day (3 of 5).
 >
-> Confidence: medium. Separation is moderate (0.28), so I recommend manually checking the top-5 against your fraud database.
+> Confidence: label-free. The detectors agreed (agreement 0.71), so the result is internally consistent, but I recommend manually checking the top-5 against your fraud database to confirm.
 >
 > **What I assumed**:
 > - Tabular, unlabeled
@@ -136,7 +135,7 @@ Some datasets have outliers concentrated in 1-2 columns (e.g., latency monitorin
 
 ### T4. Ensemble combination defaults
 
-The default consensus combination is `mean`. For very imbalanced detector quality, `weighted_mean` (weighted by separation) can be better. Mitigation: ADEngine handles this if you use `engine.run` directly. Do not bypass.
+The default consensus combination is `mean`. Do not weight detectors by `separation`; it is computed from each detector's own predicted labels and is not a cross-detector quality measure. Use the rank-normalized consensus from `state.consensus['scores']`, and inspect low `agreement` when detector rankings conflict.
 
 ### T5. ID-only embeddings without numerics
 

{pyod-3.5.2 → pyod-3.5.4}/pyod/skills/od_expert/references/text_image.md

@@ -14,7 +14,6 @@ The two-step pattern (embed first, then run a classical detector) won the NLP-AD
 
 <!-- BEGIN KB-DERIVED: text-image-detector-list -->
 - **EmbeddingOD** (Embedding-Based Outlier Detection) — complexity: time O(n * embedding_cost + detector_cost), space O(n * embedding_dim); best for: Anomaly detection on unstructured data (text, images) via foundation model representations; avoid when: Data is already tabular or a suitable encoder is not available; requires: pyod[torch]; paper: Zhao et al., 2025
-- **LLMAD** (LLM-Based Anomaly Detection) — complexity: time varies, space varies; best for: Zero-shot or few-shot anomaly detection leveraging LLM world knowledge; avoid when: Feature is needed before release or LLM API costs are prohibitive; paper: TBD
 - **MultiModalOD** (Multi-Modal Outlier Detection) — complexity: time O(n * n_modalities * embedding_cost + detector_cost), space O(n * n_modalities * embedding_dim); best for: Anomaly detection on multi-modal data combining text, image, or other modalities; avoid when: Only a single modality is available or data is purely tabular; requires: pyod[torch]; paper: Zhao et al., 2025
 <!-- END KB-DERIVED: text-image-detector-list -->
 
@@ -111,7 +110,7 @@ report = engine.report(state)
 >
 > Top-5 most unusual descriptions: rows [42, 815, 2200, 14501, 31200]. The dominant pattern was descriptions in non-English languages mixed into the catalog, plus descriptions consisting only of model numbers without prose.
 >
-> Confidence: medium. Separation is 0.24 (above the 0.1 floor, but moderate), so I recommend manually reviewing the top-50 to validate the categories of anomaly.
+> Confidence: label-free, and only one detector ran, so there is no cross-detector agreement to lean on and `separation` (0.24) is descriptive only. I recommend manually reviewing the top-50 to validate the categories of anomaly.
 >
 > **What I assumed**:
 > - Text data, English (auto-detected from sample)

{pyod-3.5.2 → pyod-3.5.4}/pyod/skills/od_expert/references/time_series.md

@@ -105,7 +105,7 @@ report = engine.report(state)
 >
 > Top-5 most anomalous intervals: minutes [842, 1503, 4221, 5917, 8330]. The dominant pattern in 4 of 5 was a sharp temperature spike followed by a slow recovery — characteristic of a sensor glitch or cooling failure.
 >
-> Confidence: medium-high. Separation is 0.31 (above the 0.2 floor), agreement is 0.62 (above the 0.4 floor), stability is around 0.X (cutoff-gap-based).
+> Confidence: label-free. Agreement is 0.62 (above the 0.4 floor), so the detectors are consistent; stability is around 0.X (cutoff-gap-based, a threshold-sensitivity signal), and `separation` (0.31) is descriptive only. Validate the top intervals against domain knowledge or held-out labels.
 >
 > **What I assumed**:
 > - Time series, univariate, regular sampling (passed `data_type='time_series'` explicitly)