tsanomaly

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

pip install tsanomaly
tsanomaly detect metrics.csv     # or straight from the terminal

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

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

quickstart: NYC taxi ridership with detected anomalies

Examples

CNC mill vibration with the two Bosch-labeled bad cycles flagged

Documentation

Usage guide - data formats, batch & streaming APIs, configuration, persistence, incidents, events, feedback, evaluation utilities.
Architecture - the full pipeline.
Examples

How it works

For more details, refer to docs/architecture.md.

Acknowledgements

The autonomous per-metric architecture is inspired by ideas in Anodot's published patents, implemented here with different, modern mechanisms - see the acknowledgements in docs/architecture.md.

License

Apache-2.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tsanomaly-0.3.0.tar.gz (72.6 kB view details)

Uploaded Jul 25, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

tsanomaly-0.3.0-py3-none-any.whl (76.6 kB view details)

Uploaded Jul 25, 2026 Python 3

File details

Details for the file tsanomaly-0.3.0.tar.gz.

File metadata

Download URL: tsanomaly-0.3.0.tar.gz
Upload date: Jul 25, 2026
Size: 72.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for tsanomaly-0.3.0.tar.gz
Algorithm	Hash digest
SHA256	`9204fed3bdc45c7a8f3fc7c074d98432f8683a99fcf479dd3c8a8cca2ab3177f`
MD5	`6f13ac8255a88f3c99a266d0092f5610`
BLAKE2b-256	`492a2f421843d0a6ef945a90450280c139bf4604029121225d2febb243e52cb6`

See more details on using hashes here.

Provenance

The following attestation bundles were made for tsanomaly-0.3.0.tar.gz:

Publisher: release.yml on visakhunnikrishnan/tsanomaly

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: tsanomaly-0.3.0.tar.gz
- Subject digest: 9204fed3bdc45c7a8f3fc7c074d98432f8683a99fcf479dd3c8a8cca2ab3177f
- Sigstore transparency entry: 2242945875
- Sigstore integration time: Jul 25, 2026
Source repository:
- Permalink: visakhunnikrishnan/tsanomaly@4517b3663ccdf21e84bf9be75cf18b13feb87bad
- Branch / Tag: refs/tags/v0.3.0
- Owner: https://github.com/visakhunnikrishnan
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@4517b3663ccdf21e84bf9be75cf18b13feb87bad
- Trigger Event: push