cloudcircuit 0.2.0__tar.gz → 0.3.0__tar.gz

{cloudcircuit-0.2.0 → cloudcircuit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudcircuit
-Version: 0.2.0
+Version: 0.3.0
 Summary: CloudCircuit Python package.
 Author: CloudCircuit Contributors
 License: MIT
@@ -68,6 +68,7 @@ python -m pip install cloudcircuit
 
 ```python
 from cloudcircuit import (
+    check_anomaly_robust,
     check_anomaly_spike,
     check_budget,
     check_burn_rate,
@@ -79,6 +80,7 @@ from cloudcircuit import (
 
 budget = check_budget(current_spend=920.0, budget_limit=1000.0, warning_ratio=0.9)
 anomaly = check_anomaly_spike([120.0, 118.0, 121.0, 250.0], spike_multiplier=1.6)
+robust_anomaly = check_anomaly_robust([120.0, 118.0, 121.0, 250.0], method="mad", z_threshold=3.5)
 burn = check_burn_rate([120.0, 118.0, 121.0, 250.0], hot_multiplier=1.4)
 breaker = evaluate_circuit_breaker(consecutive_failures=0, failure_threshold=3)
 forecast = forecast_budget_breach(
@@ -94,9 +96,25 @@ alert = make_alert_payload(policy, service="billing-worker", environment="prod")
 print(policy.action, policy.severity)
 print(forecast.projected_total_spend, forecast.will_breach)
 print(burn.burn_rate_ratio, burn.is_hot)
+print(robust_anomaly.threshold, robust_anomaly.is_spike)
 print(alert)
 ```
 
+## Robust anomaly detection (MAD / percentile)
+
+Mean-based thresholds can be brittle when cloud spend is heavy-tailed or bursty. For more robust
+detection, use `check_anomaly_robust`:
+
+```python
+from cloudcircuit import check_anomaly_robust
+
+mad = check_anomaly_robust([120.0, 118.0, 121.0, 250.0], method="mad", z_threshold=3.5)
+p95 = check_anomaly_robust([120.0, 118.0, 121.0, 250.0], method="percentile", percentile=0.95)
+
+print(mad.threshold, mad.is_spike)
+print(p95.threshold, p95.is_spike)
+```
+
 ## Common developer problems solved
 
 1. **Runaway cron or queue workers**
@@ -117,6 +135,7 @@ print(alert)
 
 - `check_budget(...) -> BudgetCheckResult`
 - `check_anomaly_spike(...) -> AnomalyCheckResult`
+- `check_anomaly_robust(...) -> AnomalyCheckResult`
 - `check_burn_rate(...) -> BurnRateResult`
 - `forecast_budget_breach(...) -> ForecastResult`
 - `evaluate_circuit_breaker(...) -> CircuitBreakerDecision`

{cloudcircuit-0.2.0 → cloudcircuit-0.3.0}/README.md

@@ -43,6 +43,7 @@ python -m pip install cloudcircuit
 
 ```python
 from cloudcircuit import (
+    check_anomaly_robust,
     check_anomaly_spike,
     check_budget,
     check_burn_rate,
@@ -54,6 +55,7 @@ from cloudcircuit import (
 
 budget = check_budget(current_spend=920.0, budget_limit=1000.0, warning_ratio=0.9)
 anomaly = check_anomaly_spike([120.0, 118.0, 121.0, 250.0], spike_multiplier=1.6)
+robust_anomaly = check_anomaly_robust([120.0, 118.0, 121.0, 250.0], method="mad", z_threshold=3.5)
 burn = check_burn_rate([120.0, 118.0, 121.0, 250.0], hot_multiplier=1.4)
 breaker = evaluate_circuit_breaker(consecutive_failures=0, failure_threshold=3)
 forecast = forecast_budget_breach(
@@ -69,9 +71,25 @@ alert = make_alert_payload(policy, service="billing-worker", environment="prod")
 print(policy.action, policy.severity)
 print(forecast.projected_total_spend, forecast.will_breach)
 print(burn.burn_rate_ratio, burn.is_hot)
+print(robust_anomaly.threshold, robust_anomaly.is_spike)
 print(alert)
 ```
 
+## Robust anomaly detection (MAD / percentile)
+
+Mean-based thresholds can be brittle when cloud spend is heavy-tailed or bursty. For more robust
+detection, use `check_anomaly_robust`:
+
+```python
+from cloudcircuit import check_anomaly_robust
+
+mad = check_anomaly_robust([120.0, 118.0, 121.0, 250.0], method="mad", z_threshold=3.5)
+p95 = check_anomaly_robust([120.0, 118.0, 121.0, 250.0], method="percentile", percentile=0.95)
+
+print(mad.threshold, mad.is_spike)
+print(p95.threshold, p95.is_spike)
+```
+
 ## Common developer problems solved
 
 1. **Runaway cron or queue workers**
@@ -92,6 +110,7 @@ print(alert)
 
 - `check_budget(...) -> BudgetCheckResult`
 - `check_anomaly_spike(...) -> AnomalyCheckResult`
+- `check_anomaly_robust(...) -> AnomalyCheckResult`
 - `check_burn_rate(...) -> BurnRateResult`
 - `forecast_budget_breach(...) -> ForecastResult`
 - `evaluate_circuit_breaker(...) -> CircuitBreakerDecision`

{cloudcircuit-0.2.0 → cloudcircuit-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cloudcircuit"
-version = "0.2.0"
+version = "0.3.0"
 description = "CloudCircuit Python package."
 readme = "README.md"
 requires-python = ">=3.10"

{cloudcircuit-0.2.0 → cloudcircuit-0.3.0}/src/cloudcircuit/__init__.py

@@ -7,6 +7,7 @@ from cloudcircuit.safeguards import (
     CircuitBreakerDecision,
     ForecastResult,
     PolicyDecision,
+    check_anomaly_robust,
     check_anomaly_spike,
     check_budget,
     check_burn_rate,
@@ -16,7 +17,7 @@ from cloudcircuit.safeguards import (
     make_alert_payload,
 )
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 __all__ = [
     "__version__",
     "AnomalyCheckResult",
@@ -25,6 +26,7 @@ __all__ = [
     "CircuitBreakerDecision",
     "ForecastResult",
     "PolicyDecision",
+    "check_anomaly_robust",
     "check_anomaly_spike",
     "check_budget",
     "check_burn_rate",

{cloudcircuit-0.2.0 → cloudcircuit-0.3.0}/src/cloudcircuit/safeguards.py

@@ -2,8 +2,10 @@
 
 from __future__ import annotations
 
+from collections.abc import Sequence
 from dataclasses import dataclass
-from typing import Literal, Sequence
+from math import ceil, floor
+from typing import Literal
 
 
 @dataclass(frozen=True, slots=True)
@@ -123,6 +125,91 @@ def check_anomaly_spike(
     )
 
 
+def _median(values: Sequence[float]) -> float:
+    if not values:
+        raise ValueError("values must be non-empty")
+    sorted_values = sorted(float(value) for value in values)
+    mid = len(sorted_values) // 2
+    if len(sorted_values) % 2 == 1:
+        return sorted_values[mid]
+    return (sorted_values[mid - 1] + sorted_values[mid]) / 2.0
+
+
+def _quantile(values: Sequence[float], p: float) -> float:
+    if not values:
+        raise ValueError("values must be non-empty")
+    if not (0.0 < p < 1.0):
+        raise ValueError("p must be in (0, 1)")
+    sorted_values = sorted(float(value) for value in values)
+    if len(sorted_values) == 1:
+        return sorted_values[0]
+    rank = p * (len(sorted_values) - 1)
+    lo = int(floor(rank))
+    hi = int(ceil(rank))
+    if lo == hi:
+        return sorted_values[lo]
+    weight = rank - lo
+    return sorted_values[lo] + weight * (sorted_values[hi] - sorted_values[lo])
+
+
+def check_anomaly_robust(
+    spend_series: Sequence[float],
+    *,
+    method: Literal["mad", "percentile"] = "mad",
+    z_threshold: float = 3.5,
+    min_mad: float = 0.0,
+    percentile: float = 0.95,
+    min_baseline: float = 0.0,
+) -> AnomalyCheckResult:
+    """
+    Robust spend spike detection using MAD or percentile thresholding.
+
+    - MAD method uses median + z * (MAD / 0.6745) as a robust z-score threshold.
+    - Percentile method uses a historical percentile as the spike threshold.
+
+    Baseline is computed from all values except the latest.
+    """
+    if len(spend_series) < 2:
+        raise ValueError("spend_series must contain at least 2 points")
+    if any(value < 0 for value in spend_series):
+        raise ValueError("spend_series values must be >= 0")
+    if min_baseline < 0:
+        raise ValueError("min_baseline must be >= 0")
+
+    if method == "mad":
+        if z_threshold <= 0:
+            raise ValueError("z_threshold must be > 0")
+        if min_mad < 0:
+            raise ValueError("min_mad must be >= 0")
+    elif method == "percentile":
+        if not (0.0 < percentile < 1.0):
+            raise ValueError("percentile must be in (0, 1)")
+    else:
+        raise ValueError("method must be 'mad' or 'percentile'")
+
+    latest_spend = float(spend_series[-1])
+    history = spend_series[:-1]
+
+    if method == "mad":
+        baseline_location = _median(history)
+        abs_deviations = [abs(float(value) - baseline_location) for value in history]
+        mad = max(_median(abs_deviations), float(min_mad))
+        effective_location = max(baseline_location, float(min_baseline))
+        robust_sigma = mad / 0.6745 if mad > 0 else 0.0
+        threshold = effective_location + (float(z_threshold) * robust_sigma)
+    else:
+        baseline_location = _quantile(history, float(percentile))
+        threshold = max(baseline_location, float(min_baseline))
+
+    is_spike = latest_spend > threshold
+    return AnomalyCheckResult(
+        latest_spend=latest_spend,
+        baseline_mean=float(baseline_location),
+        threshold=float(threshold),
+        is_spike=is_spike,
+    )
+
+
 def evaluate_circuit_breaker(
     consecutive_failures: int,
     failure_threshold: int = 3,

{cloudcircuit-0.2.0 → cloudcircuit-0.3.0}/tests/conftest.py

@@ -3,7 +3,6 @@ from __future__ import annotations
 import sys
 from pathlib import Path
 
-
 ROOT = Path(__file__).resolve().parents[1]
 SRC = ROOT / "src"
 sys.path.insert(0, str(SRC))

{cloudcircuit-0.2.0 → cloudcircuit-0.3.0}/tests/test_safeguards.py

@@ -1,6 +1,7 @@
 import pytest
 
 from cloudcircuit.safeguards import (
+    check_anomaly_robust,
     check_anomaly_spike,
     check_budget,
     check_burn_rate,
@@ -60,6 +61,81 @@ def test_anomaly_invalid_inputs() -> None:
         check_anomaly_spike([1.0, -1.0], spike_multiplier=2.0)
 
 
+def test_anomaly_robust_mad_detects_spike_with_zero_mad() -> None:
+    result = check_anomaly_robust([10.0, 10.0, 10.0, 25.0], method="mad", z_threshold=3.5)
+    assert result.baseline_mean == 10.0
+    assert result.threshold == 10.0
+    assert result.is_spike is True
+
+
+def test_anomaly_robust_mad_not_spike_on_stable_series() -> None:
+    result = check_anomaly_robust([10.0, 10.0, 10.0, 10.0], method="mad")
+    assert result.baseline_mean == 10.0
+    assert result.threshold == 10.0
+    assert result.is_spike is False
+
+
+def test_anomaly_robust_mad_detects_spike_with_nonzero_mad() -> None:
+    result = check_anomaly_robust([10.0, 10.0, 11.0, 10.0, 12.0, 11.0, 50.0], method="mad")
+    assert result.baseline_mean == 10.5
+    assert 0.0 < result.threshold < 50.0
+    assert result.is_spike is True
+
+
+def test_anomaly_robust_percentile_detects_spike() -> None:
+    result = check_anomaly_robust(
+        [10.0, 10.0, 10.0, 10.0, 50.0],
+        method="percentile",
+        percentile=0.95,
+    )
+    assert result.baseline_mean == 10.0
+    assert result.threshold == 10.0
+    assert result.is_spike is True
+
+
+def test_anomaly_robust_percentile_not_spike() -> None:
+    result = check_anomaly_robust(
+        [10.0, 12.0, 11.0, 13.0, 12.8],
+        method="percentile",
+        percentile=0.95,
+    )
+    assert result.is_spike is False
+
+
+def test_anomaly_robust_invalid_inputs() -> None:
+    with pytest.raises(ValueError):
+        check_anomaly_robust([1.0], method="mad")
+    with pytest.raises(ValueError):
+        check_anomaly_robust([1.0, -1.0], method="mad")
+    with pytest.raises(ValueError):
+        check_anomaly_robust([1.0, 2.0], method="unknown")  # type: ignore[arg-type]
+
+    with pytest.raises(ValueError):
+        check_anomaly_robust([1.0, 2.0], method="mad", z_threshold=0.0)
+    with pytest.raises(ValueError):
+        check_anomaly_robust([1.0, 2.0], method="mad", min_mad=-0.1)
+    with pytest.raises(ValueError):
+        check_anomaly_robust([1.0, 2.0], method="mad", min_baseline=-0.1)
+
+    with pytest.raises(ValueError):
+        check_anomaly_robust([1.0, 2.0], method="percentile", percentile=1.0)
+
+
+def test_anomaly_robust_min_baseline_floor() -> None:
+    mad = check_anomaly_robust([0.0, 0.0, 0.0, 0.4], method="mad", min_baseline=0.5)
+    assert mad.threshold == 0.5
+    assert mad.is_spike is False
+
+    pct = check_anomaly_robust(
+        [0.0, 0.0, 0.0, 0.4],
+        method="percentile",
+        percentile=0.95,
+        min_baseline=0.5,
+    )
+    assert pct.threshold == 0.5
+    assert pct.is_spike is False
+
+
 def test_circuit_breaker_allows_operation_below_threshold() -> None:
     decision = evaluate_circuit_breaker(consecutive_failures=2, failure_threshold=3)
     assert decision.is_open is False