Skip to main content

anomaly-watcher

anomaly-watcher detects anomalies in timestamped sensor data with a rolling-window Isolation Forest pipeline. It includes a batch CLI and a local Streamlit dashboard for CSV, MQTT, and project-based monitoring.

Install

python -m pip install anomaly-watcher

The package requires Python 3.13 or newer. The project is licensed under AGPL-3.0-or-later.

Batch CLI

Both input files need a timestamp column and matching signal columns. Numeric, boolean, and categorical signals are supported; incomplete rows are discarded.

anomaly-watcher --train train.csv --test test.csv --output anomaly_overview.png

Useful options include:

  • --save-scores scores.csv writes one score row per test window.
  • --plot-sensor SENSOR highlights one signal in the overview plot.
  • --window-seconds SECONDS controls the rolling feature window.
  • --stride-seconds SECONDS controls the distance between windows.
  • --threshold-mode max|quantile|std selects threshold calculation.
  • --forests-number NUMBER controls the Isolation Forest ensemble size.

Run anomaly-watcher --help for the complete option list.

anomaly-watcher-template copies the bundled CSV template into a target directory.

Dashboard

Launch the local dashboard with:

anomaly-watcher-dashboard

The dashboard creates a project folder containing:

  • project_config.json for the project, source, model, and retraining configuration.
  • sources/raw_<source-id>.json for persisted source records.
  • sources/features.json, sources/scores.json, and sources/anomalies.json for derived results.
  • model.joblib for the trained model and scaler.

Each DataSource card keeps its configured name as its source ID. CSV sources can be reloaded from their configured file; MQTT sources can collect train, calibration, or test records; OPC UA is currently an adapter placeholder. MQTT passwords are requested at runtime and are not written to project configuration.

The Run page shows data requirements before training. The Monitoring page displays scaled features, scores, thresholds, and anomaly windows. Clearing source data removes persisted raw records and invalidates derived results while keeping the source card; deleting a source also removes its configuration.

Retraining preserves the original training and calibration records. New good test windows can be allocated as retrain-candidate or recalibrate-candidate, then promoted to retrain-used or recalibrate-used after a successful cycle. Supported allocation strategies are alternating, blocks, ratio, retrain_only, and recalibrate_only.

Bundled demo data

The package includes these fixtures under anomaly_watcher/resources/:

  • mock_training.csv: 500 normal records.
  • mock_calibration.csv: 300 normal records.
  • mock_test_v1.csv: 250 records with a climate anomaly.
  • mock_test_v2.csv: 250 records with an air-quality anomaly.
  • mock_test_v3.csv: 250 records with an equipment/pressure anomaly.

All fixtures use seven streams sampled every two seconds: room temperature, equipment temperature, humidity, CO2, ozone, air pressure, and VOC.

anomaly-watcher --train src/anomaly_watcher/resources/mock_training.csv --test src/anomaly_watcher/resources/mock_test_v1.csv --output mock_overview.png --save-scores mock_scores.csv --plot-sensor temperature_room --window-seconds 10 --stride-seconds 4 --forests-number 3 --relief-margin 0

Development and release

From the anomaly_watcher directory:

python -m pip install -e ".[test,release]"
python -m pytest tests/ -q
python -m build
python -m twine check dist/*

The current package version is 0.2.0. These commands build and validate the PyPI artifacts locally; uploading requires an explicit twine upload dist/* step and configured PyPI credentials.

Metadata

Release files for anomaly-watcher 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for anomaly-watcher 0.2.0
File Size Uploaded Provenance Actions
anomaly_watcher-0.2.0.tar.gz 1.9 MB With provenance Details for anomaly_watcher-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for anomaly-watcher 0.2.0
File Interpreter ABI Platform Actions
anomaly_watcher-0.2.0-py3-none-any.whl Python 3 none any Details for anomaly_watcher-0.2.0-py3-none-any.whl

Total release size: 3.7 MB

Release files / anomaly_watcher-0.2.0.tar.gz

Download URL anomaly_watcher-0.2.0.tar.gz
Size 1.9 MB
Tags Source
SHA-256 checksum
How to use checksums
1bbe213f821576ba90552b28ec12cd791485ba20e81d672f2b5a0fd00092e553
BLAKE2b-256 checksum
How to use checksums
c2eb5c3ee3029970a5a3682094a6794e132e1d4c04c50ed971bf8bbab888d5f8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 17, 2026.

Transparency log

Release files / anomaly_watcher-0.2.0-py3-none-any.whl

Download URL anomaly_watcher-0.2.0-py3-none-any.whl
Size 1.9 MB
Tags Python 3
SHA-256 checksum
How to use checksums
160fb219144feb8f3920b0beabe105e7a8bc1d24b2cdcc110844594ee791f0f6
BLAKE2b-256 checksum
How to use checksums
34de66cbbb7418f10fb61cd74d7a8a44ffcb71443a66afd69340021f82d21b29
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 17, 2026.

Transparency log

Security for anomaly-watcher 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for anomaly_watcher-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page