detectkit 0.3.8__tar.gz → 0.3.10__tar.gz

detectkit-0.3.10/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: detectkit
+Version: 0.3.10
+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: black>=23.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+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
+```
+
+### 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.

detectkit-0.3.10/README.md

@@ -0,0 +1,119 @@
+# 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
+```
+
+### 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.

{detectkit-0.3.8 → detectkit-0.3.10}/detectkit/__init__.py

@@ -4,7 +4,7 @@ detectk - Anomaly Detection for Time-Series Metrics
 A Python library for data analysts and engineers to monitor metrics with automatic anomaly detection.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.3.10"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.3.8 → detectkit-0.3.10}/detectkit/alerting/orchestrator.py

@@ -519,15 +519,21 @@ class AlertOrchestrator:
                 )
                 detection_records.append(record)
 
-        # Count consecutive anomalies (same logic as should_alert)
-        consecutive = self._count_consecutive_anomalies(
-            detections=detection_records,
-            min_detectors=self.conditions.min_detectors,
-            direction=self.conditions.direction
-        )
+        # Group by timestamp and sort (same format as should_alert uses)
+        detections_by_time = self._group_by_timestamp(detection_records)
+        timestamps_sorted = sorted(detections_by_time.keys(), reverse=True)
+
+        # Check that latest post-alert point is NOT anomalous
+        # (prevents false recovery when there are fewer post-alert points
+        # than consecutive_anomalies threshold)
+        latest_ts = timestamps_sorted[0]
+        latest_detections = detections_by_time[latest_ts]
+        latest_anomalies = [d for d in latest_detections if d.is_anomaly]
+        if len(latest_anomalies) >= self.conditions.min_detectors:
+            # Latest point is still anomalous — no recovery
+            return False
 
-        # Recovery = consecutive dropped below threshold
-        return consecutive < self.conditions.consecutive_anomalies
+        return True
 
     def should_send_recovery(
         self,

{detectkit-0.3.8 → detectkit-0.3.10}/detectkit/cli/commands/test_alert.py

@@ -115,14 +115,14 @@ def run_test_alert(metric_name: str, profile: Optional[str] = None):
         return
 
     # Check if alerting is configured
-    if not metric_config.alerting or not metric_config.alerting.enabled:
+    if not metric_config.alerting:
         print(f"Error: Alerting not enabled for metric '{metric_name}'")
         print("Enable alerting in metric config (alerting.enabled: true)")
         return
 
-    if not metric_config.alerting.channels:
-        print(f"Error: No alert channels configured for metric '{metric_name}'")
-        print("Add channels in metric config (alerting.channels: [...])")
+    active_configs = [c for c in metric_config.alerting if c.enabled and c.channels]
+    if not active_configs:
+        print(f"Error: No active alert configs for metric '{metric_name}'")
         return
 
     # Load profiles
@@ -138,50 +138,51 @@ def run_test_alert(metric_name: str, profile: Optional[str] = None):
 
     alert_channels_config = profiles_data.get("alert_channels", {})
 
-    # Get timezone for display
-    timezone_display = metric_config.alerting.timezone or "UTC"
-
-    # Create mock alert data
     print(f"\n📨 Sending test alert for metric: {metric_name}")
-    print(f"   Timezone: {timezone_display}")
-    print(f"   Channels: {', '.join(metric_config.alerting.channels)}\n")
 
-    alert_data = create_mock_alert_data(metric_config, timezone_display)
+    total_success = 0
+    total_channels = 0
 
-    # Send to each configured channel
-    success_count = 0
-    for channel_name in metric_config.alerting.channels:
-        if channel_name not in alert_channels_config:
-            print(f"⚠️  Channel '{channel_name}' not found in profiles.yml - skipping")
-            continue
+    for i, alerting_config in enumerate(active_configs):
+        timezone_display = alerting_config.timezone or "UTC"
+        if len(active_configs) > 1:
+            print(f"\n   [config {i + 1}/{len(active_configs)}]")
+        print(f"   Timezone: {timezone_display}")
+        print(f"   Channels: {', '.join(alerting_config.channels)}\n")
 
-        channel_config = alert_channels_config[channel_name]
+        alert_data = create_mock_alert_data(metric_config, timezone_display)
 
-        try:
-            # Create channel instance
-            # channel_config должен содержать 'type' + остальные параметры
-            channel = AlertChannelFactory.create_from_config(channel_config)
-
-            # Get custom template if configured
-            template = None
-            if metric_config.alerting.template_consecutive:
-                template = metric_config.alerting.template_consecutive
-
-            # Send alert
-            print(f"   → Sending to {channel_name}...", end=" ")
-            success = channel.send(alert_data, template=template)
-
-            if success:
-                print("✓ SUCCESS")
-                success_count += 1
-            else:
-                print("✗ FAILED")
-
-        except Exception as e:
-            print(f"✗ ERROR: {e}")
-
-    # Summary
-    print(f"\n{'✓' if success_count > 0 else '✗'} Sent test alert to {success_count}/{len(metric_config.alerting.channels)} channels")
+        success_count = 0
+        for channel_name in alerting_config.channels:
+            total_channels += 1
+            if channel_name not in alert_channels_config:
+                print(f"⚠️  Channel '{channel_name}' not found in profiles.yml - skipping")
+                continue
+
+            channel_config = alert_channels_config[channel_name]
+
+            try:
+                channel = AlertChannelFactory.create_from_config(channel_config)
+
+                template = alerting_config.template_consecutive or None
+
+                print(f"   → Sending to {channel_name}...", end=" ")
+                success = channel.send(alert_data, template=template)
+
+                if success:
+                    print("✓ SUCCESS")
+                    success_count += 1
+                    total_success += 1
+                else:
+                    print("✗ FAILED")
+
+            except Exception as e:
+                print(f"✗ ERROR: {e}")
+
+        print(f"\n{'✓' if success_count > 0 else '✗'} Sent test alert to {success_count}/{len(alerting_config.channels)} channels")
+
+    if len(active_configs) > 1:
+        print(f"\nTotal: {total_success}/{total_channels} channels across {len(active_configs)} alert configs")
 
     if success_count > 0:
         print("\n💡 Check your configured channels to verify message formatting")

{detectkit-0.3.8 → detectkit-0.3.10}/detectkit/config/metric_config.py

@@ -341,9 +341,19 @@ class MetricConfig(BaseModel):
     detectors: List[DetectorConfig] = Field(
         default_factory=list, description="Detector configurations"
     )
-    alerting: Optional[AlertConfig] = Field(
-        default=None, description="Alert configuration"
+    alerting: Optional[List[AlertConfig]] = Field(
+        default=None, description="Alert configuration(s) — single dict or list of dicts"
     )
+
+    @field_validator("alerting", mode="before")
+    @classmethod
+    def normalize_alerting(cls, v):
+        """Normalize alerting to list. Accepts single dict/AlertConfig (backward compat) or list."""
+        if v is None:
+            return None
+        if isinstance(v, (dict, AlertConfig)):
+            return [v]
+        return v
     tables: Optional[TablesConfig] = Field(
         default=None, description="Custom table names (overrides defaults)"
     )

{detectkit-0.3.8 → detectkit-0.3.10}/detectkit/database/internal_tables.py

@@ -814,13 +814,14 @@ class InternalTablesManager:
         no_data_alert = 0
         min_detectors = 1
 
-        if metric_config.alerting:
-            is_alert_enabled = 1 if metric_config.alerting.enabled else 0
-            timezone_str = metric_config.alerting.timezone
-            direction = metric_config.alerting.direction
-            consecutive_anomalies = metric_config.alerting.consecutive_anomalies
-            no_data_alert = 1 if metric_config.alerting.no_data_alert else 0
-            min_detectors = metric_config.alerting.min_detectors
+        first_alerting = metric_config.alerting[0] if metric_config.alerting else None
+        if first_alerting:
+            is_alert_enabled = 1 if first_alerting.enabled else 0
+            timezone_str = first_alerting.timezone
+            direction = first_alerting.direction
+            consecutive_anomalies = first_alerting.consecutive_anomalies
+            no_data_alert = 1 if first_alerting.no_data_alert else 0
+            min_detectors = first_alerting.min_detectors
 
         # Prepare data for INSERT
         data = {