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.csvwrites one score row per test window.--plot-sensor SENSORhighlights one signal in the overview plot.--window-seconds SECONDScontrols the rolling feature window.--stride-seconds SECONDScontrols the distance between windows.--threshold-mode max|quantile|stdselects threshold calculation.--forests-number NUMBERcontrols 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.jsonfor the project, source, model, and retraining configuration.sources/raw_<source-id>.jsonfor persisted source records.sources/features.json,sources/scores.json, andsources/anomalies.jsonfor derived results.model.joblibfor 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.