Metadata-Version: 2.4
Name: anomaly_impact_alert
Version: 0.3.0
Summary: Anomaly detection, impact explanation, forecasting, and alerting toolkit.
Author: Aleksey Voronko, Petr Devitsin
License: MIT License
        (c) 2025 Aleksey Voronko
        
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.3
Requires-Dist: numpy>=1.21
Requires-Dist: scikit-learn>=1.0
Requires-Dist: matplotlib>=3.5
Requires-Dist: prophet>=1.1
Requires-Dist: tqdm>=4.0
Requires-Dist: requests>=2.0
Requires-Dist: python-telegram-bot>=20.0
Dynamic: license-file
Dynamic: requires-python

# anomaly_impact_alert
<img src="https://github.com/klipbn/anomaly_impact_alert/raw/main/docs/logo.png" alt="Telegram Alert" width="200">


**Anomaly Impact Alert** — a lightweight Python toolkit for **detecting anomalies**, **forecasting metrics**, **explaining deviations**, and **sending alerts** (e.g. via Telegram).

---



## Purpose

This library helps analytics and monitoring teams automatically:
- Detect abnormal metric values in time-series data
- Forecast expected ranges (with confidence intervals)
- Explain the drivers behind changes (countries, platforms, etc.)
- Send structured alerts to Telegram

---

## Example Output

### Detection visualization
Shows detected anomalies (red dots), confidence intervals, and model outputs:

<img src="https://github.com/klipbn/anomaly_impact_alert/raw/main/docs/example_detection.png" alt="Anomaly Detection]" width="900">

### Telegram alert
Example of an automatically formatted alert with top contributing segments:

<img src="https://github.com/klipbn/anomaly_impact_alert/raw/main/docs/example_telegram.png" alt="Telegram Alert" width="400">

---

## Quick Start

```bash
pip install anomaly_impact_alert
```

```python
from anomaly_impact_alert import (
    AnomalyParams, analyze_latest_point,
    ImpactConfig, attach_impact_text,
    BFConfig, forecast_values_for_targets_better,
    AlertConfig, send_alert_for_date,
)

# 1. Detect anomalies
params = AnomalyParams(threshold=3.0)
anomalies = analyze_latest_point(df, params)

# 2. Forecast expected values
forecast_cfg = BFConfig(periods=7)
forecast = forecast_values_for_targets_better(df, forecast_cfg)

# 3. Explain the impact
impact_cfg = ImpactConfig(metric="amount")
text = attach_impact_text(anomalies, impact_cfg)

# 4. Send alert to Telegram
alert_cfg = AlertConfig(bot_token="YOUR_BOT_TOKEN", chat_id="YOUR_CHAT_ID")
send_alert_for_date(text, alert_cfg)
```

---

## Modules Overview

| Module | Description |
|--------|--------------|
| `anomaly_detector` | Detects anomalies using statistical and ML methods |
| `forecast` | Forecasts values and confidence intervals |
| `impact_explainer` | Explains which dimensions cause deviations |
| `alert_bot_telegram` | Sends rich alerts to Telegram |

---

## Dependencies
`pandas`, `numpy`, `scikit-learn`, `matplotlib`, `prophet`, `tqdm`, `requests`, `python-telegram-bot`

---

## License
MIT © 2025 Aleksey Voronko, Petr Devitsin
