madwatch 0.1.0__tar.gz

madwatch-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e '.[dev]'
+      - run: ruff check src tests
+      - run: pytest -q

madwatch-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,21 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

madwatch-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/
+.ruff_cache/
+.DS_Store
+build/

madwatch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Efecan Küçük
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

madwatch-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: madwatch
+Version: 0.1.0
+Summary: Robust anomaly detection on MAD and the Modified Z-Score, with seasonal baselines
+Project-URL: Repository, https://github.com/efekckk/madwatch
+Project-URL: Why MAD?, https://efekckk.github.io/blog/why-mad
+Author-email: Efecan Küçük <efe.kckk@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Efecan Küçük
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: anomaly-detection,mad,modified-z-score,monitoring,time-series
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Requires-Dist: numpy<3,>=1.24
+Provides-Extra: cli
+Requires-Dist: matplotlib>=3.7; extra == 'cli'
+Requires-Dist: pandas>=2.0; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: matplotlib>=3.7; extra == 'dev'
+Requires-Dist: pandas>=2.0; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# madwatch
+
+[![CI](https://github.com/efekckk/madwatch/actions/workflows/ci.yml/badge.svg)](https://github.com/efekckk/madwatch/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/madwatch)](https://pypi.org/project/madwatch/)
+[![Python](https://img.shields.io/pypi/pyversions/madwatch)](https://pypi.org/project/madwatch/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Robust anomaly detection that doesn't panic at paydays.
+
+`madwatch` scores time-series values with the **Modified Z-Score over MAD**
+(Median Absolute Deviation) instead of mean/standard deviation. Medians don't
+care about your whale transaction: one huge outlier can't inflate the baseline
+and mask the next real anomaly.
+
+![demo](docs/assets/demo.png)
+
+## Install
+
+```bash
+pip install madwatch        # core, numpy only
+pip install 'madwatch[cli]' # + CLI, pandas, matplotlib
+```
+
+## Quickstart
+
+```python
+from madwatch import RollingDetector
+
+det = RollingDetector(window=40, threshold=3.5, min_samples=10)
+for value in stream:
+    score = det.update(value)
+    if score.is_anomaly:
+        alert(value, score.z)
+```
+
+## Why MAD?
+
+Standard deviation has a design flaw for anomaly detection: the anomaly you are
+trying to catch is *inside* the calculation. One spike inflates sigma, the
+threshold stretches, and the next three real anomalies walk through undetected.
+MAD is median-based, so a single outlier in the window barely moves the
+baseline. The `0.6745` constant makes the score comparable to a classic z-score
+on normal data, so the usual "flag at 3.5" rule still reads naturally.
+
+Longer version: [Why MAD instead of standard deviation?](https://efekckk.github.io/blog/why-mad)
+
+## Seasonal baselines
+
+Mondays don't look like Saturdays and 9 AM doesn't look like midnight. Comparing
+a value against a global baseline produces false alarms at every weekly rhythm.
+`SeasonalBaseline` buckets history by day-of-week and/or hour and scores each
+point against its own bucket:
+
+```python
+from madwatch import SeasonalBaseline
+
+sb = SeasonalBaseline(granularity="dow_hour").fit(timestamps, values)
+z = sb.score(new_timestamps, new_values)
+```
+
+In production use on financial streams, this combination cut false positives by
+roughly 60% compared to a naive z-score.
+
+## CLI
+
+```bash
+madwatch data.csv --column amount --window 40 --threshold 3.5 --plot out.png
+madwatch data.csv --column amount --timestamp ts --seasonal dow_hour
+```
+
+```
+where                        value         z
+2026-02-07T12:00:00         512.00      9.41
+1 anomalies in 312 points
+```
+
+## API
+
+| Name | What it does |
+|---|---|
+| `mad(x)` | Median Absolute Deviation of an array |
+| `modified_zscore(x, scale=0.6745)` | Per-element robust z-score |
+| `RollingDetector(window, threshold, min_samples)` | Streaming detection over a trailing window |
+| `SeasonalBaseline(granularity)` | Per-bucket (dow/hour) baselines with global fallback |
+
+Behavior notes: constant windows (MAD = 0) score `z = 0`; the detector stays
+silent until `min_samples` values have arrived; `NaN` input raises `ValueError`
+(the CLI skips NaN rows with a warning).
+
+## Development
+
+```bash
+uv venv && uv pip install -e '.[dev]'
+pytest
+ruff check src tests
+```
+
+## License
+
+MIT

madwatch-0.1.0/README.md

@@ -0,0 +1,100 @@
+# madwatch
+
+[![CI](https://github.com/efekckk/madwatch/actions/workflows/ci.yml/badge.svg)](https://github.com/efekckk/madwatch/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/madwatch)](https://pypi.org/project/madwatch/)
+[![Python](https://img.shields.io/pypi/pyversions/madwatch)](https://pypi.org/project/madwatch/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Robust anomaly detection that doesn't panic at paydays.
+
+`madwatch` scores time-series values with the **Modified Z-Score over MAD**
+(Median Absolute Deviation) instead of mean/standard deviation. Medians don't
+care about your whale transaction: one huge outlier can't inflate the baseline
+and mask the next real anomaly.
+
+![demo](docs/assets/demo.png)
+
+## Install
+
+```bash
+pip install madwatch        # core, numpy only
+pip install 'madwatch[cli]' # + CLI, pandas, matplotlib
+```
+
+## Quickstart
+
+```python
+from madwatch import RollingDetector
+
+det = RollingDetector(window=40, threshold=3.5, min_samples=10)
+for value in stream:
+    score = det.update(value)
+    if score.is_anomaly:
+        alert(value, score.z)
+```
+
+## Why MAD?
+
+Standard deviation has a design flaw for anomaly detection: the anomaly you are
+trying to catch is *inside* the calculation. One spike inflates sigma, the
+threshold stretches, and the next three real anomalies walk through undetected.
+MAD is median-based, so a single outlier in the window barely moves the
+baseline. The `0.6745` constant makes the score comparable to a classic z-score
+on normal data, so the usual "flag at 3.5" rule still reads naturally.
+
+Longer version: [Why MAD instead of standard deviation?](https://efekckk.github.io/blog/why-mad)
+
+## Seasonal baselines
+
+Mondays don't look like Saturdays and 9 AM doesn't look like midnight. Comparing
+a value against a global baseline produces false alarms at every weekly rhythm.
+`SeasonalBaseline` buckets history by day-of-week and/or hour and scores each
+point against its own bucket:
+
+```python
+from madwatch import SeasonalBaseline
+
+sb = SeasonalBaseline(granularity="dow_hour").fit(timestamps, values)
+z = sb.score(new_timestamps, new_values)
+```
+
+In production use on financial streams, this combination cut false positives by
+roughly 60% compared to a naive z-score.
+
+## CLI
+
+```bash
+madwatch data.csv --column amount --window 40 --threshold 3.5 --plot out.png
+madwatch data.csv --column amount --timestamp ts --seasonal dow_hour
+```
+
+```
+where                        value         z
+2026-02-07T12:00:00         512.00      9.41
+1 anomalies in 312 points
+```
+
+## API
+
+| Name | What it does |
+|---|---|
+| `mad(x)` | Median Absolute Deviation of an array |
+| `modified_zscore(x, scale=0.6745)` | Per-element robust z-score |
+| `RollingDetector(window, threshold, min_samples)` | Streaming detection over a trailing window |
+| `SeasonalBaseline(granularity)` | Per-bucket (dow/hour) baselines with global fallback |
+
+Behavior notes: constant windows (MAD = 0) score `z = 0`; the detector stays
+silent until `min_samples` values have arrived; `NaN` input raises `ValueError`
+(the CLI skips NaN rows with a warning).
+
+## Development
+
+```bash
+uv venv && uv pip install -e '.[dev]'
+pytest
+ruff check src tests
+```
+
+## License
+
+MIT