cloudcircuit 0.1.0__tar.gz

cloudcircuit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[dev]
+
+      - name: Lint
+        run: python -m ruff check .
+
+      - name: Type check
+        run: python -m mypy src
+
+      - name: Run tests
+        run: python -m pytest
+
+      - name: Build distribution
+        run: python -m build
+
+      - name: Verify distribution metadata
+        run: python -m twine check dist/*

cloudcircuit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,91 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+
+      - name: Build distribution
+        run: python -m build
+
+      - name: Verify distribution metadata
+        run: python -m twine check dist/*
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish-trusted:
+    if: ${{ secrets.PYPI_API_TOKEN == '' }}
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment:
+      name: pypi
+      url: https://pypi.org/p/cloudcircuit
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI with trusted publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-token:
+    if: ${{ secrets.PYPI_API_TOKEN != '' }}
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment:
+      name: pypi
+      url: https://pypi.org/p/cloudcircuit
+    permissions:
+      contents: read
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI with API token
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

cloudcircuit-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+
+# Virtual envs
+.venv/
+venv/
+
+# Test/cache
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# OS/editor
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/

cloudcircuit-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,138 @@
+# 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/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["hatchling>=1.26.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cloudcircuit"
+version = "0.1.0"
+description = "CloudCircuit Python package."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "CloudCircuit Contributors" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2.2",
+  "mypy>=1.11.2",
+  "pytest>=8.3.3",
+  "ruff>=0.6.9",
+  "twine>=5.1.1",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cloudcircuit"]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = ["-ra", "--strict-config", "--strict-markers"]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "N", "ANN", "C4", "SIM"]
+ignore = ["ANN101", "ANN102"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["ANN201", "ANN202", "ANN001", "ANN002", "ANN003"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"
+
+[tool.mypy]
+python_version = "3.10"
+packages = ["cloudcircuit"]
+mypy_path = "src"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+strict_equality = true
+show_error_codes = true
+pretty = true
+
+[tool.twine]
+repository = "pypi"

cloudcircuit-0.1.0/src/cloudcircuit/__init__.py

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

cloudcircuit-0.1.0/src/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/tests/conftest.py

@@ -0,0 +1,9 @@
+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.1.0/tests/test_safeguards.py

@@ -0,0 +1,87 @@
+import pytest
+
+from cloudcircuit.safeguards import (
+    check_anomaly_spike,
+    check_budget,
+    evaluate_circuit_breaker,
+)
+
+
+def test_budget_ok_without_warning() -> None:
+    result = check_budget(current_spend=40.0, budget_limit=100.0, warning_ratio=0.8)
+    assert result.usage_ratio == 0.4
+    assert result.remaining_budget == 60.0
+    assert result.is_warning is False
+    assert result.is_breached is False
+
+
+def test_budget_warning_and_breach() -> None:
+    result = check_budget(current_spend=100.0, budget_limit=100.0, warning_ratio=0.8)
+    assert result.is_warning is True
+    assert result.is_breached is True
+    assert result.remaining_budget == 0.0
+
+
+@pytest.mark.parametrize(
+    ("current_spend", "budget_limit", "warning_ratio"),
+    [(-1.0, 100.0, 0.9), (10.0, 0.0, 0.9), (10.0, 100.0, 0.0)],
+)
+def test_budget_invalid_inputs(
+    current_spend: float, budget_limit: float, warning_ratio: float
+) -> None:
+    with pytest.raises(ValueError):
+        check_budget(current_spend, budget_limit, warning_ratio)
+
+
+def test_anomaly_spike_detected() -> None:
+    result = check_anomaly_spike([10.0, 10.0, 10.0, 20.0], spike_multiplier=1.5)
+    assert result.baseline_mean == 10.0
+    assert result.threshold == 15.0
+    assert result.is_spike is True
+
+
+def test_anomaly_not_spike_with_min_baseline() -> None:
+    result = check_anomaly_spike([0.0, 0.0, 0.0, 0.4], spike_multiplier=2.0, min_baseline=0.5)
+    assert result.baseline_mean == 0.0
+    assert result.threshold == 1.0
+    assert result.is_spike is False
+
+
+def test_anomaly_invalid_inputs() -> None:
+    with pytest.raises(ValueError):
+        check_anomaly_spike([1.0], spike_multiplier=1.5)
+    with pytest.raises(ValueError):
+        check_anomaly_spike([1.0, 2.0], spike_multiplier=1.0)
+    with pytest.raises(ValueError):
+        check_anomaly_spike([1.0, -1.0], spike_multiplier=2.0)
+
+
+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
+    assert decision.allow_operation is True
+    assert decision.retry_after_steps == 0
+
+
+def test_circuit_breaker_opens_at_threshold() -> None:
+    decision = evaluate_circuit_breaker(consecutive_failures=3, failure_threshold=3)
+    assert decision.is_open is True
+    assert decision.allow_operation is False
+
+
+def test_circuit_breaker_stays_open_during_cooldown() -> None:
+    decision = evaluate_circuit_breaker(
+        consecutive_failures=0, failure_threshold=3, cooldown_steps_remaining=2
+    )
+    assert decision.is_open is True
+    assert decision.allow_operation is False
+    assert decision.retry_after_steps == 2
+
+
+def test_circuit_breaker_invalid_inputs() -> None:
+    with pytest.raises(ValueError):
+        evaluate_circuit_breaker(consecutive_failures=-1)
+    with pytest.raises(ValueError):
+        evaluate_circuit_breaker(consecutive_failures=0, failure_threshold=0)
+    with pytest.raises(ValueError):
+        evaluate_circuit_breaker(consecutive_failures=0, cooldown_steps_remaining=-1)

cloudcircuit-0.1.0/tests/test_version.py

@@ -0,0 +1,5 @@
+from cloudcircuit import __version__
+
+
+def test_version_is_defined() -> None:
+    assert __version__