Metadata-Version: 2.4
Name: anomaly-watcher
Version: 0.2.0
Summary: Source-centric anomaly detection for timestamped sensor and MQTT data
Author: Ricardo Cunha
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/ricardo-cunha/python-tools
Project-URL: Repository, https://github.com/ricardo-cunha/python-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Requires-Dist: joblib
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: plotly
Requires-Dist: paho-mqtt
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: streamlit
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Provides-Extra: release
Requires-Dist: build>=1.2; extra == "release"
Requires-Dist: twine>=5; extra == "release"

# 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

```powershell
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.

```powershell
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:

```powershell
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.

```powershell
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:

```powershell
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.
