Metadata-Version: 2.4
Name: detectkit
Version: 0.4.1
Summary: Metric monitoring with automatic anomaly detection
Author: detectkit team
License: MIT
Project-URL: Homepage, https://github.com/alexeiveselov92/detectkit
Project-URL: Documentation, https://github.com/alexeiveselov92/detectkit
Project-URL: Repository, https://github.com/alexeiveselov92/detectkit
Project-URL: Issues, https://github.com/alexeiveselov92/detectkit/issues
Keywords: monitoring,anomaly-detection,metrics,timeseries,alerting
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: Topic :: Scientific/Engineering
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: click>=8.0
Requires-Dist: jinja2>=3.0
Requires-Dist: orjson>=3.0
Requires-Dist: requests>=2.25.0
Provides-Extra: clickhouse
Requires-Dist: clickhouse-driver>=0.2.0; extra == "clickhouse"
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9.0; extra == "postgres"
Provides-Extra: mysql
Requires-Dist: pymysql>=1.0.0; extra == "mysql"
Provides-Extra: all-db
Requires-Dist: clickhouse-driver>=0.2.0; extra == "all-db"
Requires-Dist: psycopg2-binary>=2.9.0; extra == "all-db"
Requires-Dist: pymysql>=1.0.0; extra == "all-db"
Provides-Extra: prophet
Requires-Dist: prophet>=1.1.0; extra == "prophet"
Provides-Extra: timesfm
Requires-Dist: timesfm>=0.1.0; extra == "timesfm"
Provides-Extra: advanced-detectors
Requires-Dist: prophet>=1.1.0; extra == "advanced-detectors"
Requires-Dist: timesfm>=0.1.0; extra == "advanced-detectors"
Provides-Extra: all
Requires-Dist: clickhouse-driver>=0.2.0; extra == "all"
Requires-Dist: psycopg2-binary>=2.9.0; extra == "all"
Requires-Dist: pymysql>=1.0.0; extra == "all"
Requires-Dist: prophet>=1.1.0; extra == "all"
Requires-Dist: timesfm>=0.1.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-requests-mock>=0.1; extra == "dev"
Requires-Dist: requests-mock>=1.12; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: integration
Requires-Dist: testcontainers[clickhouse]>=4.0; extra == "integration"
Dynamic: license-file

# detectkit

[![PyPI version](https://img.shields.io/pypi/v/detectkit.svg)](https://pypi.org/project/detectkit/)
[![Python](https://img.shields.io/pypi/pyversions/detectkit.svg)](https://pypi.org/project/detectkit/)

**Metric monitoring with automatic anomaly detection.**

`detectkit` is a Python library for data analysts and engineers to monitor time-series metrics with automatic anomaly detection and alerting. dbt-like project structure and CLI.

## Features

- **Pure numpy arrays** — no pandas dependency in core logic
- **Statistical detectors** — Z-Score, MAD, IQR, Manual Bounds
- **Multi-channel alerting** — Mattermost, Slack, Telegram, Email, Webhook
- **@mentions** — tag users/groups in alerts, each channel formats natively
- **Alert lifecycle** — consecutive anomalies, cooldown, recovery notifications
- **Database agnostic** — ClickHouse, PostgreSQL, MySQL
- **Idempotent** — resume from interruptions, no duplicate processing
- **CLI** — `dtk init`, `dtk run --select`, tag-based selectors

## Installation

```bash
pip install detectkit
```

With database drivers:

```bash
pip install detectkit[clickhouse]   # ClickHouse
pip install detectkit[all-db]       # All databases
```

## Quick Start

### CLI (Recommended)

```bash
# Create project
dtk init my_monitoring
cd my_monitoring

# Configure database in profiles.yml, then:
dtk run --select cpu_usage
dtk run --select tag:critical
dtk run --select cpu_usage --steps load,detect
dtk run --select cpu_usage --from 2024-01-01
```

### Metric Configuration

```yaml
# metrics/api_errors.yml
name: api_error_rate
interval: "5min"

query: |
  SELECT
    toStartOfInterval(timestamp, INTERVAL 5 MINUTE) AS timestamp,
    countIf(status_code >= 500) / count() * 100 AS value
  FROM http_requests
  WHERE timestamp >= %(from_date)s AND timestamp < %(to_date)s
  GROUP BY timestamp ORDER BY timestamp

detectors:
  - type: mad
    params:
      threshold: 3.0
      window_size: 2016    # 7 days

alerting:
  enabled: true
  channels: [mattermost_ops]
  consecutive_anomalies: 3
  direction: "up"
  mentions: [oncall_engineer, here]
  alert_cooldown: "30min"
  notify_on_recovery: true
  suppress_until: "2026-04-11 18:00:00"  # Suppress alerts until this UTC time
```

### Python API

```python
import numpy as np
from detectkit.detectors.statistical import ZScoreDetector

detector = ZScoreDetector(threshold=3.0, window_size=100)
results = detector.detect({
    'timestamp': np.array([...], dtype='datetime64[ms]'),
    'value': np.array([1.0, 2.0, 1.5, 10.0, 1.8]),
})

for r in results:
    if r.is_anomaly:
        print(f"Anomaly at {r.timestamp}: {r.value}")
```

## Documentation

- [Getting Started](docs/getting-started/quickstart.md) — 5-minute quickstart
- [Configuration Guide](docs/guides/configuration.md) — all config options
- [Detectors Guide](docs/guides/detectors.md) — choosing the right detector
- [Alerting Guide](docs/guides/alerting.md) — channels, mentions, cooldown, recovery
- [CLI Reference](docs/reference/cli.md) — command-line documentation
- [Examples](docs/examples/) — real-world monitoring scenarios
- [Changelog](CHANGELOG.md) — version history

## Requirements

- Python 3.10+
- numpy >= 1.24.0
- pydantic >= 2.0.0
- click >= 8.0
- PyYAML >= 6.0
- Jinja2 >= 3.0

## License

MIT License — see [LICENSE](LICENSE) for details.
