cloudcircuit 0.2.0__tar.gz → 0.3.7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudcircuit
-Version: 0.2.0
+Version: 0.3.7
 Summary: CloudCircuit Python package.
 Author: CloudCircuit Contributors
 License: MIT
@@ -23,6 +23,8 @@ Requires-Dist: ruff>=0.6.9; extra == 'dev'
 Requires-Dist: twine>=5.1.1; extra == 'dev'
 Description-Content-Type: text/markdown
 
+![cloudcircuit Banner](assets/images/banner.svg)
+
 # cloudcircuit
 
 CloudCircuit is a Python library for **cloud cost control**, **real-time spend anomaly detection**, **budget overrun prevention**, and **circuit-breaker style safety automation**.
@@ -68,6 +70,7 @@ python -m pip install cloudcircuit
 
 ```python
 from cloudcircuit import (
+    check_anomaly_robust,
     check_anomaly_spike,
     check_budget,
     check_burn_rate,
@@ -79,6 +82,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 +98,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 +137,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.7}/README.md

@@ -1,124 +1,145 @@
-# cloudcircuit
-
-CloudCircuit is a Python library for **cloud cost control**, **real-time spend anomaly detection**, **budget overrun prevention**, and **circuit-breaker style safety automation**.
-
-If you are searching for solutions like:
-- prevent unexpected cloud bills
-- detect cloud spend spikes
-- add budget guardrails in Python
-- implement FinOps automation for developers
-- stop runaway infrastructure loops
-
-this package is built for that exact problem set.
-
-## Why this library exists
-
-Many teams discover cloud overspend only after invoices land. A single misconfigured loop, unbounded worker fan-out, or retry storm can create massive costs in hours.
-
-CloudCircuit provides deterministic primitives so you can add spend safety in:
-- background jobs
-- CI/CD workflows
-- internal developer platforms
-- API middleware
-- scheduled FinOps monitors
-
-## Features
-
-- **Budget guardrails**: warning and hard-breach checks with explicit thresholds
-- **Spend anomaly detection**: latest-point spike detection against baseline
-- **Burn-rate monitoring**: detect hot spend acceleration before full breach
-- **Forecasting**: project period-end spend and overrun amount
-- **Circuit breaker decisions**: open/close logic for high-risk operations
-- **Policy engine**: combine budget + anomaly + breaker into `allow/throttle/block`
-- **Alert payload builder**: provider-agnostic payloads for Slack/webhooks/ops pipelines
-- **Typed API**: dataclass results with clear fields for logs and audits
-
-## Install
-
-```bash
-python -m pip install cloudcircuit
-```
-
-## Quickstart
-
-```python
-from cloudcircuit import (
-    check_anomaly_spike,
-    check_budget,
-    check_burn_rate,
-    evaluate_circuit_breaker,
-    evaluate_spend_policy,
-    forecast_budget_breach,
-    make_alert_payload,
-)
-
-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)
-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(
-    current_spend=920.0,
-    budget_limit=1000.0,
-    periods_elapsed=22,
-    total_periods=30,
-)
-
-policy = evaluate_spend_policy(budget=budget, anomaly=anomaly, breaker=breaker)
-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(alert)
-```
-
-## Common developer problems solved
-
-1. **Runaway cron or queue workers**
-   - Use anomaly + burn-rate checks every interval.
-   - Auto-throttle workers when policy returns `throttle`.
-
-2. **Unexpected month-end budget breach**
-   - Use forecast checks daily or hourly.
-   - Trigger remediation before hard limit is hit.
-
-3. **No standardized cost incident signal**
-   - Use `make_alert_payload` for consistent, structured incident events.
-
-4. **Need a safe default during telemetry failure**
-   - Combine breaker logic with fail-closed policy in critical paths.
-
-## API overview
-
-- `check_budget(...) -> BudgetCheckResult`
-- `check_anomaly_spike(...) -> AnomalyCheckResult`
-- `check_burn_rate(...) -> BurnRateResult`
-- `forecast_budget_breach(...) -> ForecastResult`
-- `evaluate_circuit_breaker(...) -> CircuitBreakerDecision`
-- `evaluate_spend_policy(...) -> PolicyDecision`
-- `make_alert_payload(...) -> dict[str, object]`
-
-## SEO keywords (for discoverability)
-
-cloud cost control python, finops python library, cloud budget guardrails, spend anomaly detection, prevent cloud bill shock, cost circuit breaker, cloud billing safety, cloud overspend monitoring, infrastructure cost alerts, developer finops toolkit
-
-## Development
-
-```bash
-python -m pip install -e ".[dev]"
-python -m pytest
-python -m ruff check .
-python -m mypy src
-```
-
-## Roadmap ideas
-
-- rolling window and percentile-based anomaly models
-- provider adapters for AWS/GCP/Azure billing streams
-- async event pipeline helpers
-- OpenTelemetry metric exporters
-- policy DSL for org-wide spend controls
-
-## License
-
+![cloudcircuit Banner](assets/images/banner.svg)
+
+# cloudcircuit
+
+CloudCircuit is a Python library for **cloud cost control**, **real-time spend anomaly detection**, **budget overrun prevention**, and **circuit-breaker style safety automation**.
+
+If you are searching for solutions like:
+- prevent unexpected cloud bills
+- detect cloud spend spikes
+- add budget guardrails in Python
+- implement FinOps automation for developers
+- stop runaway infrastructure loops
+
+this package is built for that exact problem set.
+
+## Why this library exists
+
+Many teams discover cloud overspend only after invoices land. A single misconfigured loop, unbounded worker fan-out, or retry storm can create massive costs in hours.
+
+CloudCircuit provides deterministic primitives so you can add spend safety in:
+- background jobs
+- CI/CD workflows
+- internal developer platforms
+- API middleware
+- scheduled FinOps monitors
+
+## Features
+
+- **Budget guardrails**: warning and hard-breach checks with explicit thresholds
+- **Spend anomaly detection**: latest-point spike detection against baseline
+- **Burn-rate monitoring**: detect hot spend acceleration before full breach
+- **Forecasting**: project period-end spend and overrun amount
+- **Circuit breaker decisions**: open/close logic for high-risk operations
+- **Policy engine**: combine budget + anomaly + breaker into `allow/throttle/block`
+- **Alert payload builder**: provider-agnostic payloads for Slack/webhooks/ops pipelines
+- **Typed API**: dataclass results with clear fields for logs and audits
+
+## Install
+
+```bash
+python -m pip install cloudcircuit
+```
+
+## Quickstart
+
+```python
+from cloudcircuit import (
+    check_anomaly_robust,
+    check_anomaly_spike,
+    check_budget,
+    check_burn_rate,
+    evaluate_circuit_breaker,
+    evaluate_spend_policy,
+    forecast_budget_breach,
+    make_alert_payload,
+)
+
+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(
+    current_spend=920.0,
+    budget_limit=1000.0,
+    periods_elapsed=22,
+    total_periods=30,
+)
+
+policy = evaluate_spend_policy(budget=budget, anomaly=anomaly, breaker=breaker)
+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**
+   - Use anomaly + burn-rate checks every interval.
+   - Auto-throttle workers when policy returns `throttle`.
+
+2. **Unexpected month-end budget breach**
+   - Use forecast checks daily or hourly.
+   - Trigger remediation before hard limit is hit.
+
+3. **No standardized cost incident signal**
+   - Use `make_alert_payload` for consistent, structured incident events.
+
+4. **Need a safe default during telemetry failure**
+   - Combine breaker logic with fail-closed policy in critical paths.
+
+## API overview
+
+- `check_budget(...) -> BudgetCheckResult`
+- `check_anomaly_spike(...) -> AnomalyCheckResult`
+- `check_anomaly_robust(...) -> AnomalyCheckResult`
+- `check_burn_rate(...) -> BurnRateResult`
+- `forecast_budget_breach(...) -> ForecastResult`
+- `evaluate_circuit_breaker(...) -> CircuitBreakerDecision`
+- `evaluate_spend_policy(...) -> PolicyDecision`
+- `make_alert_payload(...) -> dict[str, object]`
+
+## SEO keywords (for discoverability)
+
+cloud cost control python, finops python library, cloud budget guardrails, spend anomaly detection, prevent cloud bill shock, cost circuit breaker, cloud billing safety, cloud overspend monitoring, infrastructure cost alerts, developer finops toolkit
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m ruff check .
+python -m mypy src
+```
+
+## Roadmap ideas
+
+- rolling window and percentile-based anomaly models
+- provider adapters for AWS/GCP/Azure billing streams
+- async event pipeline helpers
+- OpenTelemetry metric exporters
+- policy DSL for org-wide spend controls
+
+## License
+
 MIT

cloudcircuit-0.3.7/assets/images/banner.svg

@@ -0,0 +1,7 @@
+<svg width="800" height="200" xmlns="http://www.w3.org/2000/svg">
+  <rect width="800" height="200" fill="#06b6d4" rx="10"/>
+  <text x="50%" y="50%" dominant-baseline="middle" text-anchor="middle" 
+        font-family="Arial, sans-serif" font-size="24" fill="white" font-weight="bold">
+    Cloud Infrastructure
+  </text>
+</svg>

cloudcircuit-0.3.7/assets/images/concept.svg

@@ -0,0 +1,13 @@
+<svg width="200" height="200" xmlns="http://www.w3.org/2000/svg">
+  <rect width="200" height="200" fill="#f8f9fa" stroke="#dee2e6" stroke-width="2"/>
+  <text x="50%" y="30%" dominant-baseline="middle" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#495057">
+    Cloud Circuit
+  </text>
+  <text x="50%" y="50%" dominant-baseline="middle" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#6c757d">
+    Cloud Infrastructure
+  </text>
+  <circle cx="100" cy="130" r="25" fill="#007bff" opacity="0.2"/>
+  <text x="50%" y="135%" dominant-baseline="middle" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#007bff">
+    Deployment
+  </text>
+</svg>

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cloudcircuit"
-version = "0.2.0"
+version = "0.3.7"
 description = "CloudCircuit Python package."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -74,3 +74,4 @@ pretty = true
 
 [tool.twine]
 repository = "pypi"
+

{cloudcircuit-0.2.0 → cloudcircuit-0.3.7}/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.7}/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.7}/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.7}/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