Metadata-Version: 2.4
Name: tsanomaly
Version: 0.1.1
Summary: A Python library for autonomous, explainable, real-time anomaly detection on time-series metrics
Author: Visakh Unni
License: Apache-2.0
Project-URL: Homepage, https://github.com/visakhunnikrishnan/tsanomaly
Project-URL: Repository, https://github.com/visakhunnikrishnan/tsanomaly
Project-URL: Issues, https://github.com/visakhunnikrishnan/tsanomaly/issues
Project-URL: Changelog, https://github.com/visakhunnikrishnan/tsanomaly/blob/main/CHANGELOG.md
Keywords: anomaly-detection,time-series,monitoring,outlier-detection,changepoint,conformal-prediction,seasonality,streaming
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: pandas>=2.0
Requires-Dist: pydantic>=2.5
Requires-Dist: matplotlib>=3.7
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: hypothesis>=6.88; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Dynamic: license-file

# tsanomaly

**A Python library for autonomous, explainable, real-time anomaly detection on time-series metrics.**

```
pip install tsanomaly
```

## Why tsanomaly

- **Zero configuration** - seasonality, model choice, and the expected-range "envelope"
  are learned per metric.
- **Calibrated** - envelope coverage is enforced by adaptive conformal inference; tail
  rarity comes from extreme value theory, not Gaussian assumptions.
- **Comparable scores** - magnitude × duration × persistence, judged against the
  metric's own history: a 90 means the same rarity on any metric.
- **Regime-aware** - a permanent level shift becomes one "new normal" finding and a
  re-anchored baseline, not endless alerts.
- **Incidents** - concurrent anomalies group into one finding, ordered by who moved
  first: the root-cause hint.
- **Real-time** - O(1) streaming updates, out-of-order tolerance, alert lifecycle with
  pluggable sinks, stall detection, checkpoint/restore.
- **Explainable** - every anomaly carries its expected range, score breakdown,
  provenance, and a counterfactual.

## Quickstart

```python
import pandas as pd
import tsanomaly as tsa

# any long frame with metric / timestamp / value columns
history = pd.read_csv("payments.csv", parse_dates=["ts"])

det = tsa.Detector.auto()
det.fit(history)                      # learn normal, per metric
result = det.detect(new_data)         # scored, explained anomalies

print(result.summary())
for anomaly in result.alerts(min_score=70):
    print(anomaly.explain().to_text())
```

Output (NYC taxi ridership around the January 2015 blizzard):

```
learned seasonality: day (strength 0.67), week (strength 0.84)

`nyc.taxi.passengers` dropped to 7076 (expected 18060 to 25606)
    for 33.0 h starting 2014-11-27 05:30 UTC - score 100.   # Thanksgiving
`nyc.taxi.passengers` spiked to 23848 (expected 15488 to 19792)
    for 6.0 h starting 2015-01-18 09:30 UTC - score 100.    # MLK weekend
`nyc.taxi.passengers` dropped to 570 (expected 15629 to 22110)
    for 39.0 h starting 2015-01-26 11:30 UTC - score 100.   # blizzard travel ban
```

<img src="examples/images/quickstart.png" alt="quickstart: NYC taxi ridership with detected anomalies" width="820">

## Examples

- [quickstart.py](examples/quickstart.py)
- [cnc_vibration.py](examples/cnc_vibration.py)
- [streaming_alerts.py](examples/streaming_alerts.py)
- [traffic_incident.py](examples/traffic_incident.py)
- [root_cause.py](examples/root_cause.py)
- [gallery.py](examples/gallery.py)
- [adaptive_envelopes.py](examples/adaptive_envelopes.py)

<img src="examples/images/cnc_vibration.png" alt="CNC mill vibration with the two Bosch-labeled bad cycles flagged" width="820">

## Documentation

- **[Usage guide](docs/usage.md)** - data formats, batch & streaming APIs, configuration,
  persistence, incidents, events, feedback, evaluation utilities.
- **[Architecture](docs/architecture.md)** - the full pipeline.
- **[Examples](examples/)**

## How it works

<img src="docs/images/pipeline.png" alt="the tsanomaly pipeline" width="860">

For more details, refer to [docs/architecture.md](docs/architecture.md).

## Acknowledgements

The architecture of `tsanomaly` - autonomous per-metric baselines, anomaly scoring
against a metric's own history, automatic seasonality detection, and condensing
concurrent anomalies into incidents - is inspired by the system described in
**Anodot's published patents**:

- [US 10,061,632 - System and method for transforming observed metrics into detected and scored anomalies](https://patents.google.com/patent/US10061632B2/en)
- [US 10,061,677 - Fast automated detection of seasonal patterns in time series data](https://patents.google.com/patent/US10061677B2/en)
- [US 2016/0210556 A1 - Heuristic inference of topological representation of metric relationships](https://patents.google.com/patent/US20160210556A1/en)
- [US 2020/0233774 A1 - Efficient estimation of high-cardinality time-series models](https://patents.google.com/patent/US20200233774A1/en)
- [US 12,101,343 - Event-based machine learning for a time-series metric](https://patents.google.com/patent/US12101343B2/en)

`tsanomaly` borrows the *ideas* and implements them with different, modern mechanisms -
adaptive conformal calibration, extreme-value tail modeling, Bayesian online changepoint
detection, harmonic-mean evidence combination, and effective-signal correction - detailed
in [docs/architecture.md](docs/architecture.md).

## License

Apache-2.0
