cloudcircuit 0.1.0__py3-none-any.whl

cloudcircuit/__init__.py

@@ -0,0 +1,4 @@
+"""CloudCircuit package."""
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

cloudcircuit/safeguards.py

@@ -0,0 +1,115 @@
+"""Core cloud spend safeguard logic."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Sequence
+
+
+@dataclass(frozen=True, slots=True)
+class BudgetCheckResult:
+    current_spend: float
+    budget_limit: float
+    usage_ratio: float
+    remaining_budget: float
+    is_warning: bool
+    is_breached: bool
+
+
+@dataclass(frozen=True, slots=True)
+class AnomalyCheckResult:
+    latest_spend: float
+    baseline_mean: float
+    threshold: float
+    is_spike: bool
+
+
+@dataclass(frozen=True, slots=True)
+class CircuitBreakerDecision:
+    is_open: bool
+    allow_operation: bool
+    retry_after_steps: int
+
+
+def check_budget(
+    current_spend: float,
+    budget_limit: float,
+    warning_ratio: float = 0.9,
+) -> BudgetCheckResult:
+    """Evaluate budget usage against warning and breach thresholds."""
+    if budget_limit <= 0:
+        raise ValueError("budget_limit must be > 0")
+    if not (0 < warning_ratio <= 1):
+        raise ValueError("warning_ratio must be in (0, 1]")
+    if current_spend < 0:
+        raise ValueError("current_spend must be >= 0")
+
+    usage_ratio = current_spend / budget_limit
+    remaining_budget = budget_limit - current_spend
+    is_warning = usage_ratio >= warning_ratio
+    is_breached = current_spend >= budget_limit
+    return BudgetCheckResult(
+        current_spend=current_spend,
+        budget_limit=budget_limit,
+        usage_ratio=usage_ratio,
+        remaining_budget=remaining_budget,
+        is_warning=is_warning,
+        is_breached=is_breached,
+    )
+
+
+def check_anomaly_spike(
+    spend_series: Sequence[float],
+    spike_multiplier: float = 1.5,
+    min_baseline: float = 0.0,
+) -> AnomalyCheckResult:
+    """
+    Detect whether the latest spend point is an anomalous spike.
+
+    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 spike_multiplier <= 1.0:
+        raise ValueError("spike_multiplier must be > 1.0")
+    if min_baseline < 0:
+        raise ValueError("min_baseline must be >= 0")
+    if any(value < 0 for value in spend_series):
+        raise ValueError("spend_series values must be >= 0")
+
+    latest_spend = float(spend_series[-1])
+    history = spend_series[:-1]
+    baseline_mean = sum(history) / len(history)
+    effective_baseline = max(baseline_mean, min_baseline)
+    threshold = effective_baseline * spike_multiplier
+    is_spike = latest_spend > threshold
+    return AnomalyCheckResult(
+        latest_spend=latest_spend,
+        baseline_mean=baseline_mean,
+        threshold=threshold,
+        is_spike=is_spike,
+    )
+
+
+def evaluate_circuit_breaker(
+    consecutive_failures: int,
+    failure_threshold: int = 3,
+    cooldown_steps_remaining: int = 0,
+) -> CircuitBreakerDecision:
+    """Return deterministic breaker state from failure and cooldown counters."""
+    if consecutive_failures < 0:
+        raise ValueError("consecutive_failures must be >= 0")
+    if failure_threshold <= 0:
+        raise ValueError("failure_threshold must be > 0")
+    if cooldown_steps_remaining < 0:
+        raise ValueError("cooldown_steps_remaining must be >= 0")
+
+    threshold_reached = consecutive_failures >= failure_threshold
+    is_open = threshold_reached or cooldown_steps_remaining > 0
+    allow_operation = not is_open
+    retry_after_steps = cooldown_steps_remaining if is_open else 0
+    return CircuitBreakerDecision(
+        is_open=is_open,
+        allow_operation=allow_operation,
+        retry_after_steps=retry_after_steps,
+    )

cloudcircuit-0.1.0.dist-info/METADATA

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: cloudcircuit
+Version: 0.1.0
+Summary: CloudCircuit Python package.
+Author: CloudCircuit Contributors
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == 'dev'
+Requires-Dist: mypy>=1.11.2; extra == 'dev'
+Requires-Dist: pytest>=8.3.3; extra == 'dev'
+Requires-Dist: ruff>=0.6.9; extra == 'dev'
+Requires-Dist: twine>=5.1.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cloudcircuit
+
+Lightweight, deterministic safeguards you can embed into cloud spend enforcement:
+
+- Budget usage checks (`check_budget`)
+- Spend spike detection (`check_anomaly_spike`)
+- Simple circuit-breaker decisioning (`evaluate_circuit_breaker`)
+
+This package focuses on the core logic only. You bring your own metrics ingestion (billing exports, CloudWatch,
+BigQuery, etc.) and enforcement (alerts, policy, throttling, kill-switches).
+
+## Install
+
+From PyPI (once published):
+
+```bash
+python -m pip install cloudcircuit
+```
+
+For local development from this repo:
+
+```bash
+cd cloudcircuit
+python -m pip install -e ".[dev]"
+pytest
+```
+
+## Usage
+
+The public APIs currently live in `cloudcircuit.safeguards`:
+
+```python
+from cloudcircuit.safeguards import (
+    check_anomaly_spike,
+    check_budget,
+    evaluate_circuit_breaker,
+)
+```
+
+All functions are deterministic and raise `ValueError` on invalid inputs (negative spend, invalid thresholds, etc.).
+
+## Quickstart
+
+### 1) Budget guardrail
+
+```python
+from cloudcircuit.safeguards import check_budget
+
+result = check_budget(current_spend=920.0, budget_limit=1000.0, warning_ratio=0.9)
+
+if result.is_breached:
+    # Hard stop: disable non-essential workloads, block expensive operations, etc.
+    print("BUDGET BREACHED:", result)
+elif result.is_warning:
+    # Soft stop: alert, reduce concurrency, apply stricter policy.
+    print("BUDGET WARNING:", result)
+else:
+    print("OK:", result)
+```
+
+### 2) Spike detection (latest point vs baseline)
+
+```python
+from cloudcircuit.safeguards import check_anomaly_spike
+
+# Example: daily spend totals (or hourly), latest point last.
+series = [120.0, 125.0, 118.0, 260.0]
+
+result = check_anomaly_spike(series, spike_multiplier=1.5, min_baseline=0.0)
+if result.is_spike:
+    print("SPEND SPIKE:", result.latest_spend, "threshold:", result.threshold)
+```
+
+### 3) Circuit-breaker decisioning
+
+```python
+from cloudcircuit.safeguards import evaluate_circuit_breaker
+
+decision = evaluate_circuit_breaker(
+    consecutive_failures=3,
+    failure_threshold=3,
+    cooldown_steps_remaining=0,
+)
+
+if not decision.allow_operation:
+    print("BREAKER OPEN; retry after steps:", decision.retry_after_steps)
+```
+
+## Architecture
+
+Current modules:
+
+- `src/cloudcircuit/safeguards.py`: core dataclasses and guardrail functions:
+  - `BudgetCheckResult`, `check_budget`
+  - `AnomalyCheckResult`, `check_anomaly_spike`
+  - `CircuitBreakerDecision`, `evaluate_circuit_breaker`
+- `tests/test_safeguards.py`: contract tests for edge cases and input validation.
+
+Design goals:
+
+- Deterministic, side-effect free logic (easy to unit-test and reason about)
+- Minimal dependencies (safe to embed in CLIs, jobs, and services)
+- Typed, explicit return objects (so callers can log/audit decisions)
+
+Non-goals (by design):
+
+- Cloud provider integrations (metrics ingestion / policy enforcement)
+- Stateful breaker implementation (persistence, jitter/backoff, distributed locks)
+
+## Deployment Guide
+
+Typical deployment looks like a thin integration layer around `cloudcircuit`:
+
+1. Collect spend and operational signals.
+   - Spend totals: billing exports, cost explorer, warehouse tables, or internal chargeback.
+   - Failure counters: request error rates, provider API failures, budget retrieval failures.
+2. Evaluate guardrails.
+   - `check_budget()` for hard/soft budget thresholds.
+   - `check_anomaly_spike()` to catch sudden jumps early.
+   - `evaluate_circuit_breaker()` to gate high-cost operations when systems are unstable.
+3. Enforce decisions.
+   - Alerting: Slack/email/PagerDuty with `*_Result` fields for audit context.
+   - Throttling: reduce concurrency, disable non-critical jobs, or switch to cheaper defaults.
+   - Kill-switch: block expensive actions when `is_breached` is true.
+4. Persist state externally when needed.
+   - Store the last N spend points, consecutive failure counts, and cooldown counters in your DB/redis.
+   - Run the evaluator on a schedule (cron / Airflow / Cloud Scheduler) or inline per request.
+
+Recommended patterns:
+
+- Treat spend series as monotonic time buckets (hourly/daily) and pass the newest point last.
+- Log the full result objects (they are small and serializable) so you can explain why a safeguard tripped.
+- Prefer "fail closed" for high-risk operations: if your metrics pipeline is down, open the breaker or block
+  expensive actions until signals recover.
+
+## License
+
+MIT (see `pyproject.toml` for the current license declaration).

cloudcircuit-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+cloudcircuit/__init__.py,sha256=2n1PpRG-K5Gfjkwcx-OsRKS6hUQHzvtTaq6B0PV1yDc,76
+cloudcircuit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cloudcircuit/safeguards.py,sha256=0mkUbEH7Iry66OwDEUIW13rsppAcUDnBanW1OcwUUQw,3567
+cloudcircuit-0.1.0.dist-info/METADATA,sha256=JGQN3YOM2foR4qshbsRCvQ7-jtOl0mxgDIcjgKBDse4,5400
+cloudcircuit-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+cloudcircuit-0.1.0.dist-info/RECORD,,

cloudcircuit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any