# 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.
## Status
✅ **Production Ready** - Version 0.1.2
Published to PyPI: https://pypi.org/project/detectkit/
Complete rewrite with modern architecture and full documentation (2025).
## Features
- ✅ **Pure numpy arrays** - No pandas dependency in core logic
- ✅ **Batch processing** - Efficient vectorized operations
- ✅ **Multiple detectors** - Statistical methods (Z-Score, MAD, IQR, Manual Bounds)
- ✅ **Alert channels** - Mattermost, Slack, Webhook support
- ✅ **Database agnostic** - ClickHouse, PostgreSQL, MySQL support
- ✅ **Idempotent operations** - Resume from interruptions
- 🚧 **CLI interface** - dbt-like commands (coming soon)
## Installation
```bash
pip install detectkit
```
Or from source:
```bash
git clone https://github.com/alexeiveselov92/detectkit
cd detectkit
pip install -e .
```
### Optional dependencies
```bash
# ClickHouse support
pip install detectkit[clickhouse]
# All database drivers
pip install detectkit[all-db]
# Development dependencies
pip install detectkit[dev]
```
## Quick Start
### CLI Usage (Recommended)
```bash
# Create a new project
dtk init my_monitoring_project
cd my_monitoring_project
# Configure database in profiles.yml
# Then run your metrics
dtk run --select example_cpu_usage
# Run specific pipeline steps
dtk run --select cpu_usage --steps load,detect
# Run all critical metrics
dtk run --select tag:critical
# Reload data from specific date
dtk run --select cpu_usage --from 2024-01-01
```
### Python API Usage
```python
import numpy as np
from detectkit.detectors.statistical import ZScoreDetector
# Your time-series data
timestamps = np.array([...], dtype='datetime64[ms]')
values = np.array([1.0, 2.0, 1.5, 10.0, 1.8]) # 10.0 is anomaly
# Create detector
detector = ZScoreDetector(threshold=3.0, window_size=100)
# Detect anomalies
data = {
'timestamp': timestamps,
'value': values
}
results = detector.detect(data)
# Check results
for result in results:
if result.is_anomaly:
print(f"Anomaly at {result.timestamp}: {result.value}")
```
## Architecture
- **Detectors** - Statistical and ML-based anomaly detection
- **Loaders** - Metric data loading from databases with gap filling
- **Alerting** - Multi-channel notifications with orchestration
- **Config** - YAML-based configuration (dbt-like)
## Testing
```bash
# Run tests
pytest tests/
# With coverage
pytest tests/ --cov=detectkit --cov-report=html
```
**Current status:** 287 tests passing, 87% coverage
## Development Status
### ✅ Completed (Phases 1-6)
- ✅ **Phase 1**: Core models (Interval, TableModel, ColumnDefinition)
- ✅ **Phase 2**: Database managers & data loading (MetricLoader, gap filling, seasonality)
- ✅ **Phase 3**: Statistical detectors (Z-Score, MAD, IQR, Manual Bounds)
- ✅ **Phase 4**: Alerting system (Channels, Orchestrator, consecutive anomalies)
- ✅ **Phase 5**: Task manager (Pipeline execution, locking, idempotency)
- ✅ **Phase 6**: CLI commands (dtk init, dtk run with selectors)
### 🔄 Integration Status
- ⚠️ Full end-to-end integration pending (database connection required)
- ⚠️ Advanced detectors (Prophet, TimesFM) - optional extras
- ⚠️ Additional alert channels (Telegram, Email) - optional
## Documentation
📚 **Complete documentation available at: https://github.com/alexeiveselov92/detectkit/tree/main/docs**
- [Getting Started](https://github.com/alexeiveselov92/detectkit/blob/main/docs/getting-started/quickstart.md) - 5-minute quickstart
- [Configuration Guide](https://github.com/alexeiveselov92/detectkit/blob/main/docs/guides/configuration.md) - All configuration options
- [Detectors Guide](https://github.com/alexeiveselov92/detectkit/blob/main/docs/guides/detectors.md) - Choosing the right detector
- [Alerting Guide](https://github.com/alexeiveselov92/detectkit/blob/main/docs/guides/alerting.md) - Setting up alerts
- [CLI Reference](https://github.com/alexeiveselov92/detectkit/blob/main/docs/reference/cli.md) - Command-line documentation
- [Examples](https://github.com/alexeiveselov92/detectkit/tree/main/docs/examples) - Real-world monitoring scenarios
## 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 file for details
## Contributing
This project is currently in active development. Contributions are welcome once we reach v1.0.0.
## Changelog
### 0.1.0 (2025-11-07)
- Initial release with complete rewrite
- ✅ Core foundation: models, database, config
- ✅ Metric loading with gap filling and seasonality extraction
- ✅ Statistical detectors (Z-Score, MAD, IQR, Manual Bounds)
- ✅ Alert channels (Webhook, Mattermost, Slack)
- ✅ Alert orchestration with consecutive anomaly logic
- ✅ Task manager for pipeline execution
- ✅ CLI commands (dtk init, dtk run)
- 📊 287 unit tests, 87% coverage
Raw data
{
"_id": null,
"home_page": null,
"name": "detectkit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "monitoring, anomaly-detection, metrics, timeseries, alerting",
"author": "detectkit team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/5c/d7/a14c200f792807477fbec393fb8647605486faa77b9cc5fdf71a3f1c96a7/detectkit-0.3.0.tar.gz",
"platform": null,
"description": "# detectkit\n\n**Metric monitoring with automatic anomaly detection**\n\n`detectkit` is a Python library for data analysts and engineers to monitor time-series metrics with automatic anomaly detection and alerting.\n\n## Status\n\n\u2705 **Production Ready** - Version 0.1.2\n\nPublished to PyPI: https://pypi.org/project/detectkit/\n\nComplete rewrite with modern architecture and full documentation (2025).\n\n## Features\n\n- \u2705 **Pure numpy arrays** - No pandas dependency in core logic\n- \u2705 **Batch processing** - Efficient vectorized operations\n- \u2705 **Multiple detectors** - Statistical methods (Z-Score, MAD, IQR, Manual Bounds)\n- \u2705 **Alert channels** - Mattermost, Slack, Webhook support\n- \u2705 **Database agnostic** - ClickHouse, PostgreSQL, MySQL support\n- \u2705 **Idempotent operations** - Resume from interruptions\n- \ud83d\udea7 **CLI interface** - dbt-like commands (coming soon)\n\n## Installation\n\n```bash\npip install detectkit\n```\n\nOr from source:\n\n```bash\ngit clone https://github.com/alexeiveselov92/detectkit\ncd detectkit\npip install -e .\n```\n\n### Optional dependencies\n\n```bash\n# ClickHouse support\npip install detectkit[clickhouse]\n\n# All database drivers\npip install detectkit[all-db]\n\n# Development dependencies\npip install detectkit[dev]\n```\n\n## Quick Start\n\n### CLI Usage (Recommended)\n\n```bash\n# Create a new project\ndtk init my_monitoring_project\ncd my_monitoring_project\n\n# Configure database in profiles.yml\n# Then run your metrics\ndtk run --select example_cpu_usage\n\n# Run specific pipeline steps\ndtk run --select cpu_usage --steps load,detect\n\n# Run all critical metrics\ndtk run --select tag:critical\n\n# Reload data from specific date\ndtk run --select cpu_usage --from 2024-01-01\n```\n\n### Python API Usage\n\n```python\nimport numpy as np\nfrom detectkit.detectors.statistical import ZScoreDetector\n\n# Your time-series data\ntimestamps = np.array([...], dtype='datetime64[ms]')\nvalues = np.array([1.0, 2.0, 1.5, 10.0, 1.8]) # 10.0 is anomaly\n\n# Create detector\ndetector = ZScoreDetector(threshold=3.0, window_size=100)\n\n# Detect anomalies\ndata = {\n 'timestamp': timestamps,\n 'value': values\n}\nresults = detector.detect(data)\n\n# Check results\nfor result in results:\n if result.is_anomaly:\n print(f\"Anomaly at {result.timestamp}: {result.value}\")\n```\n\n## Architecture\n\n- **Detectors** - Statistical and ML-based anomaly detection\n- **Loaders** - Metric data loading from databases with gap filling\n- **Alerting** - Multi-channel notifications with orchestration\n- **Config** - YAML-based configuration (dbt-like)\n\n## Testing\n\n```bash\n# Run tests\npytest tests/\n\n# With coverage\npytest tests/ --cov=detectkit --cov-report=html\n```\n\n**Current status:** 287 tests passing, 87% coverage\n\n## Development Status\n\n### \u2705 Completed (Phases 1-6)\n- \u2705 **Phase 1**: Core models (Interval, TableModel, ColumnDefinition)\n- \u2705 **Phase 2**: Database managers & data loading (MetricLoader, gap filling, seasonality)\n- \u2705 **Phase 3**: Statistical detectors (Z-Score, MAD, IQR, Manual Bounds)\n- \u2705 **Phase 4**: Alerting system (Channels, Orchestrator, consecutive anomalies)\n- \u2705 **Phase 5**: Task manager (Pipeline execution, locking, idempotency)\n- \u2705 **Phase 6**: CLI commands (dtk init, dtk run with selectors)\n\n### \ud83d\udd04 Integration Status\n- \u26a0\ufe0f Full end-to-end integration pending (database connection required)\n- \u26a0\ufe0f Advanced detectors (Prophet, TimesFM) - optional extras\n- \u26a0\ufe0f Additional alert channels (Telegram, Email) - optional\n\n## Documentation\n\n\ud83d\udcda **Complete documentation available at: https://github.com/alexeiveselov92/detectkit/tree/main/docs**\n\n- [Getting Started](https://github.com/alexeiveselov92/detectkit/blob/main/docs/getting-started/quickstart.md) - 5-minute quickstart\n- [Configuration Guide](https://github.com/alexeiveselov92/detectkit/blob/main/docs/guides/configuration.md) - All configuration options\n- [Detectors Guide](https://github.com/alexeiveselov92/detectkit/blob/main/docs/guides/detectors.md) - Choosing the right detector\n- [Alerting Guide](https://github.com/alexeiveselov92/detectkit/blob/main/docs/guides/alerting.md) - Setting up alerts\n- [CLI Reference](https://github.com/alexeiveselov92/detectkit/blob/main/docs/reference/cli.md) - Command-line documentation\n- [Examples](https://github.com/alexeiveselov92/detectkit/tree/main/docs/examples) - Real-world monitoring scenarios\n\n\n## Requirements\n\n- Python 3.10+\n- numpy >= 1.24.0\n- pydantic >= 2.0.0\n- click >= 8.0\n- PyYAML >= 6.0\n- Jinja2 >= 3.0\n\n## License\n\nMIT License - See LICENSE file for details\n\n## Contributing\n\nThis project is currently in active development. Contributions are welcome once we reach v1.0.0.\n\n## Changelog\n\n### 0.1.0 (2025-11-07)\n- Initial release with complete rewrite\n- \u2705 Core foundation: models, database, config\n- \u2705 Metric loading with gap filling and seasonality extraction\n- \u2705 Statistical detectors (Z-Score, MAD, IQR, Manual Bounds)\n- \u2705 Alert channels (Webhook, Mattermost, Slack)\n- \u2705 Alert orchestration with consecutive anomaly logic\n- \u2705 Task manager for pipeline execution\n- \u2705 CLI commands (dtk init, dtk run)\n- \ud83d\udcca 287 unit tests, 87% coverage\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Metric monitoring with automatic anomaly detection",
"version": "0.3.0",
"project_urls": {
"Documentation": "https://github.com/alexeiveselov92/detectkit",
"Homepage": "https://github.com/alexeiveselov92/detectkit",
"Issues": "https://github.com/alexeiveselov92/detectkit/issues",
"Repository": "https://github.com/alexeiveselov92/detectkit"
},
"split_keywords": [
"monitoring",
" anomaly-detection",
" metrics",
" timeseries",
" alerting"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a4462fd875eeb82b94b53d07e959d25721eaaa0a83e8332f9ed14ed8ed578498",
"md5": "0cab69937c01e4e1a130ed38eb787704",
"sha256": "e68575bc185821c29eafff72fd4be94114bb7b2ab8c63cd0998c1056b7ac1176"
},
"downloads": -1,
"filename": "detectkit-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0cab69937c01e4e1a130ed38eb787704",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 100870,
"upload_time": "2025-11-10T10:39:31",
"upload_time_iso_8601": "2025-11-10T10:39:31.802022Z",
"url": "https://files.pythonhosted.org/packages/a4/46/2fd875eeb82b94b53d07e959d25721eaaa0a83e8332f9ed14ed8ed578498/detectkit-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5cd7a14c200f792807477fbec393fb8647605486faa77b9cc5fdf71a3f1c96a7",
"md5": "868adcd47849a1ce5913338f2dee62bc",
"sha256": "e7c47c46ee537b675140f3c0833ae80ed5bd33373b25a9cafbed36b076c28590"
},
"downloads": -1,
"filename": "detectkit-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "868adcd47849a1ce5913338f2dee62bc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 77540,
"upload_time": "2025-11-10T10:39:36",
"upload_time_iso_8601": "2025-11-10T10:39:36.041069Z",
"url": "https://files.pythonhosted.org/packages/5c/d7/a14c200f792807477fbec393fb8647605486faa77b9cc5fdf71a3f1c96a7/detectkit-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-10 10:39:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alexeiveselov92",
"github_project": "detectkit",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "numpy",
"specs": [
[
">=",
"1.24.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "PyYAML",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "Jinja2",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.28.0"
]
]
},
{
"name": "orjson",
"specs": [
[
">=",
"3.9.0"
]
]
}
],
"lcname": "detectkit"
}
JSON
