resilient-sdk-core 0.1.0__tar.gz

resilient_sdk_core-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: resilient-sdk-core
+Version: 0.1.0
+Summary: Adaptive retry SDK with persistent failure memory
+Keywords: retry,resilience,observability,backoff,circuit-breaker
+Author: Abhishek Dasgupta
+Author-email: abhishek_dasgupta@zykrr.com
+Requires-Python: >=3.10,<4.0
+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 :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: asyncpg (>=0.29,<0.30)
+Requires-Dist: tomli (>=2.0,<3.0) ; python_version < "3.11"
+Project-URL: Homepage, https://github.com/abhishekgit03/resilient-sdk
+Project-URL: Repository, https://github.com/abhishekgit03/resilient-sdk
+Description-Content-Type: text/markdown
+
+# resilient-sdk
+
+Adaptive retry SDK + CLI for production Python applications.
+
+Every developer writes ad-hoc retry logic - fixed attempts, guessed backoff values, no observability. **resilient-sdk** replaces that with a zero-config decorator that learns from your failure history and surfaces actionable insights via a CLI.
+
+```python
+from resilient import retry
+
+@retry.auto
+def call_openai(prompt: str):
+    return openai.chat.completions.create(...)
+```
+
+```bash
+$ resilient report
+$ resilient explain openai
+$ resilient anomalies
+```
+
+---
+
+## How it works
+
+- **`@retry.auto`** - wraps any function (sync or async), classifies exceptions automatically, and applies exponential backoff with jitter
+- **Postgres persistence** - every retry event is written to `resilient.events`, multi-pod safe
+- **CLI** - queries that data and gives you plain-English reports powered by Gemini
+
+---
+
+## Installation
+
+### Python SDK
+
+```bash
+pip install resilient-sdk-core
+```
+
+Requires Python 3.10+ and a Postgres database.
+
+### CLI
+
+Download the binary from [GitHub Releases](https://github.com/abhishekgit03/resilient-sdk/releases) or install with Go:
+
+```bash
+go install github.com/abhishekgit03/resilient-sdk/cli@latest
+```
+
+---
+
+## Setup
+
+### 1. Configure
+
+```bash
+resilient init --dsn postgresql://user:pass@host/dbname --gemini-key AIza...
+```
+
+This writes `~/.resilient/config.toml`. The SDK reads the same file.
+
+### 2. Use the decorator
+
+```python
+from resilient import retry
+
+# Works with any external call - HTTP, DB, queue
+@retry.auto
+def call_stripe():
+    return stripe.PaymentIntent.create(...)
+
+@retry.auto
+async def call_openai(prompt: str):
+    return await openai.chat.completions.create(...)
+```
+
+### 3. Optional - Circuit Breaker
+
+Pair with the circuit breaker to stop retrying a service that's fully down:
+
+```python
+from resilient import retry
+from resilient.circuit import CircuitBreaker
+
+cb = CircuitBreaker(failure_threshold=5, recovery_timeout=30)
+
+@retry.auto
+@cb.protect
+def call_openai(prompt: str):
+    ...
+```
+
+---
+
+## CLI Commands
+
+| Command | Description |
+|---|---|
+| `resilient init --dsn <dsn> --gemini-key <key>` | One-time setup |
+| `resilient report` | Failure summary, last 24h |
+| `resilient report --app openai --last 7d` | Scoped report |
+| `resilient explain <service>` | AI-powered analysis |
+| `resilient explain <service> --last 7d` | Scoped explanation |
+| `resilient anomalies` | Services that spiked vs yesterday |
+| `resilient top` | Worst offenders in the last hour |
+
+### Example output
+
+```
+$ resilient explain openai
+
+Analysing openai (last 7d)...
+
+OpenAI calls are failing at 4.2% over the last 7 days, up from 1.1% the week
+before. Failures cluster between 14:00–16:00 UTC. The rate_limit errors suggest
+you are retrying inside the same rate-limit window. Recommendation: add a 60s
+cooldown after 3 consecutive 429s and consider request batching during peak hours.
+```
+
+---
+
+## Error Classification
+
+The SDK classifies exceptions automatically - no configuration needed.
+
+| HTTP Status | Error Type | Strategy |
+|---|---|---|
+| 429 | `rate_limit` | Exponential backoff + jitter, 5 attempts |
+| 500/502/503/504 | `server_error` | Backoff + jitter, 4 attempts |
+| 400/401/403/404 | `client_fault` | No retry - fail immediately |
+| Timeout exceptions | `transient` | Short jitter, 3 attempts |
+
+Works with any HTTP library (`httpx`, `requests`, `aiohttp`) without importing them.
+
+---
+
+## Database Schema
+
+Auto-created on first run:
+
+```sql
+resilient.events  -- one row per retry attempt
+resilient.stats   -- aggregated windows (populated by CLI queries)
+```
+
+Compatible with any existing Postgres instance. Uses a dedicated `resilient` schema to avoid conflicts.
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| SDK | Python + Poetry |
+| CLI | Go + Cobra |
+| Storage | PostgreSQL |
+| AI | Gemini 2.5 Flash |
+
+---
+
+## License
+
+MIT
+

resilient_sdk_core-0.1.0/README.md

@@ -0,0 +1,162 @@
+# resilient-sdk
+
+Adaptive retry SDK + CLI for production Python applications.
+
+Every developer writes ad-hoc retry logic - fixed attempts, guessed backoff values, no observability. **resilient-sdk** replaces that with a zero-config decorator that learns from your failure history and surfaces actionable insights via a CLI.
+
+```python
+from resilient import retry
+
+@retry.auto
+def call_openai(prompt: str):
+    return openai.chat.completions.create(...)
+```
+
+```bash
+$ resilient report
+$ resilient explain openai
+$ resilient anomalies
+```
+
+---
+
+## How it works
+
+- **`@retry.auto`** - wraps any function (sync or async), classifies exceptions automatically, and applies exponential backoff with jitter
+- **Postgres persistence** - every retry event is written to `resilient.events`, multi-pod safe
+- **CLI** - queries that data and gives you plain-English reports powered by Gemini
+
+---
+
+## Installation
+
+### Python SDK
+
+```bash
+pip install resilient-sdk-core
+```
+
+Requires Python 3.10+ and a Postgres database.
+
+### CLI
+
+Download the binary from [GitHub Releases](https://github.com/abhishekgit03/resilient-sdk/releases) or install with Go:
+
+```bash
+go install github.com/abhishekgit03/resilient-sdk/cli@latest
+```
+
+---
+
+## Setup
+
+### 1. Configure
+
+```bash
+resilient init --dsn postgresql://user:pass@host/dbname --gemini-key AIza...
+```
+
+This writes `~/.resilient/config.toml`. The SDK reads the same file.
+
+### 2. Use the decorator
+
+```python
+from resilient import retry
+
+# Works with any external call - HTTP, DB, queue
+@retry.auto
+def call_stripe():
+    return stripe.PaymentIntent.create(...)
+
+@retry.auto
+async def call_openai(prompt: str):
+    return await openai.chat.completions.create(...)
+```
+
+### 3. Optional - Circuit Breaker
+
+Pair with the circuit breaker to stop retrying a service that's fully down:
+
+```python
+from resilient import retry
+from resilient.circuit import CircuitBreaker
+
+cb = CircuitBreaker(failure_threshold=5, recovery_timeout=30)
+
+@retry.auto
+@cb.protect
+def call_openai(prompt: str):
+    ...
+```
+
+---
+
+## CLI Commands
+
+| Command | Description |
+|---|---|
+| `resilient init --dsn <dsn> --gemini-key <key>` | One-time setup |
+| `resilient report` | Failure summary, last 24h |
+| `resilient report --app openai --last 7d` | Scoped report |
+| `resilient explain <service>` | AI-powered analysis |
+| `resilient explain <service> --last 7d` | Scoped explanation |
+| `resilient anomalies` | Services that spiked vs yesterday |
+| `resilient top` | Worst offenders in the last hour |
+
+### Example output
+
+```
+$ resilient explain openai
+
+Analysing openai (last 7d)...
+
+OpenAI calls are failing at 4.2% over the last 7 days, up from 1.1% the week
+before. Failures cluster between 14:00–16:00 UTC. The rate_limit errors suggest
+you are retrying inside the same rate-limit window. Recommendation: add a 60s
+cooldown after 3 consecutive 429s and consider request batching during peak hours.
+```
+
+---
+
+## Error Classification
+
+The SDK classifies exceptions automatically - no configuration needed.
+
+| HTTP Status | Error Type | Strategy |
+|---|---|---|
+| 429 | `rate_limit` | Exponential backoff + jitter, 5 attempts |
+| 500/502/503/504 | `server_error` | Backoff + jitter, 4 attempts |
+| 400/401/403/404 | `client_fault` | No retry - fail immediately |
+| Timeout exceptions | `transient` | Short jitter, 3 attempts |
+
+Works with any HTTP library (`httpx`, `requests`, `aiohttp`) without importing them.
+
+---
+
+## Database Schema
+
+Auto-created on first run:
+
+```sql
+resilient.events  -- one row per retry attempt
+resilient.stats   -- aggregated windows (populated by CLI queries)
+```
+
+Compatible with any existing Postgres instance. Uses a dedicated `resilient` schema to avoid conflicts.
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| SDK | Python + Poetry |
+| CLI | Go + Cobra |
+| Storage | PostgreSQL |
+| AI | Gemini 2.5 Flash |
+
+---
+
+## License
+
+MIT

resilient_sdk_core-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[tool.poetry]
+name = "resilient-sdk-core"
+version = "0.1.0"
+description = "Adaptive retry SDK with persistent failure memory"
+authors = ["Abhishek Dasgupta <abhishek_dasgupta@zykrr.com>"]
+readme = "README.md"
+homepage = "https://github.com/abhishekgit03/resilient-sdk"
+repository = "https://github.com/abhishekgit03/resilient-sdk"
+keywords = ["retry", "resilience", "observability", "backoff", "circuit-breaker"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+packages = [{ include = "resilient" }]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+asyncpg = "^0.29"
+tomli = { version = "^2.0", python = "<3.11" }  # built-in in 3.11+
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0"
+pytest-asyncio = "^0.23"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

resilient_sdk_core-0.1.0/resilient/__init__.py

@@ -0,0 +1,3 @@
+from .decorator import RetryManager
+
+retry = RetryManager()

resilient_sdk_core-0.1.0/resilient/circuit.py

@@ -0,0 +1,87 @@
+import threading
+import time
+from enum import Enum
+
+
+class State(Enum):
+    CLOSED = "closed"       # normal — calls go through
+    OPEN = "open"           # tripped — fail immediately
+    HALF_OPEN = "half_open" # testing recovery — one call allowed
+
+
+class CircuitBreakerOpen(Exception):
+    """Raised when a call is blocked by an open circuit breaker."""
+    def __init__(self, service: str):
+        super().__init__(f"Circuit breaker open for '{service}' — service appears to be down")
+
+
+class CircuitBreaker:
+    """
+    Usage:
+        cb = CircuitBreaker(failure_threshold=5, recovery_timeout=30)
+
+        @retry.auto
+        @cb.protect
+        def call_openai(...): ...
+    """
+
+    def __init__(
+        self,
+        failure_threshold: int = 5,    # failures before opening
+        recovery_timeout: float = 30.0, # seconds to wait before half-open
+    ):
+        self.failure_threshold = failure_threshold
+        self.recovery_timeout = recovery_timeout
+
+        self._state = State.CLOSED
+        self._failure_count = 0
+        self._opened_at: float | None = None
+        self._lock = threading.Lock()
+
+    @property
+    def state(self) -> State:
+        with self._lock:
+            return self._get_state()
+
+    def _get_state(self) -> State:
+        if self._state == State.OPEN:
+            if time.monotonic() - self._opened_at >= self.recovery_timeout:
+                # Cooldown elapsed — move to half-open to test recovery
+                self._state = State.HALF_OPEN
+        return self._state
+
+    def protect(self, fn):
+        """Decorator that wraps a function with circuit breaker protection."""
+        import functools
+
+        @functools.wraps(fn)
+        def inner(*args, **kwargs):
+            with self._lock:
+                state = self._get_state()
+                if state == State.OPEN:
+                    raise CircuitBreakerOpen(fn.__name__)
+                if state == State.HALF_OPEN:
+                    # Allow through — result determines if we close or re-open
+                    pass
+
+            try:
+                result = fn(*args, **kwargs)
+                self._on_success()
+                return result
+            except Exception:
+                self._on_failure()
+                raise
+
+        return inner
+
+    def _on_success(self):
+        with self._lock:
+            self._failure_count = 0
+            self._state = State.CLOSED
+
+    def _on_failure(self):
+        with self._lock:
+            self._failure_count += 1
+            if self._failure_count >= self.failure_threshold:
+                self._state = State.OPEN
+                self._opened_at = time.monotonic()

resilient_sdk_core-0.1.0/resilient/classifier.py

@@ -0,0 +1,81 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class RetryStrategy:
+    error_type: str      
+    should_retry: bool
+    base_delay: float 
+    max_attempts: int
+    use_jitter: bool
+
+
+_STRATEGIES: dict[str, RetryStrategy] = {
+    "rate_limit": RetryStrategy(
+        error_type="rate_limit",
+        should_retry=True,
+        base_delay=2.0,
+        max_attempts=5,
+        use_jitter=True,
+    ),
+    "server_error": RetryStrategy(
+        error_type="server_error",
+        should_retry=True,
+        base_delay=1.0,
+        max_attempts=4,
+        use_jitter=True,
+    ),
+    "transient": RetryStrategy(
+        error_type="transient",
+        should_retry=True,
+        base_delay=0.5,
+        max_attempts=3,
+        use_jitter=True,
+    ),
+    "client_fault": RetryStrategy(
+        error_type="client_fault",
+        should_retry=False,
+        base_delay=0.0,
+        max_attempts=1,
+        use_jitter=False,
+    ),
+    "unknown": RetryStrategy(
+        error_type="unknown",
+        should_retry=True,
+        base_delay=1.0,
+        max_attempts=3,
+        use_jitter=True,
+    ),
+}
+
+
+def classify(exc: Exception) -> RetryStrategy:
+    """Map an exception to a retry strategy."""
+
+    status = _extract_status_code(exc)
+    if status is not None:
+        if status == 429:
+            return _STRATEGIES["rate_limit"]
+        if status in (500, 502, 503, 504):
+            return _STRATEGIES["server_error"]
+        if status in (400, 401, 403, 404, 422):
+            return _STRATEGIES["client_fault"]
+
+    type_name = type(exc).__name__.lower()
+    if any(kw in type_name for kw in ("timeout", "timedout", "timed_out")):
+        return _STRATEGIES["transient"]
+    if any(kw in type_name for kw in ("connection", "network", "connect")):
+        return _STRATEGIES["transient"]
+
+    return _STRATEGIES["unknown"]
+
+
+def _extract_status_code(exc: Exception) -> int | None:
+    """Try common attribute names used by different HTTP libraries."""
+    for attr in ("status_code", "status", "code", "response"):
+        val = getattr(exc, attr, None)
+        if isinstance(val, int):
+            return val
+        if hasattr(val, "status_code"):
+            return val.status_code
+    return None

resilient_sdk_core-0.1.0/resilient/config.py

@@ -0,0 +1,30 @@
+import os
+import sys
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+
+_config: dict | None = None
+
+
+def get_config() -> dict:
+    global _config
+    if _config is not None:
+        return _config
+
+    config_path = Path(os.getenv("RESILIENT_CONFIG", Path.home() / ".resilient" / "config.toml"))
+
+    if config_path.exists():
+        with open(config_path, "rb") as f:
+            _config = tomllib.load(f)
+    else:
+        _config = {}
+
+    if dsn := os.getenv("RESILIENT_DSN"):
+        _config["dsn"] = dsn
+
+    return _config

resilient_sdk_core-0.1.0/resilient/decorator.py

@@ -0,0 +1,104 @@
+import asyncio
+import functools
+import inspect
+import random
+import time
+from typing import Any, Callable
+
+from .classifier import RetryStrategy, classify
+from .store import record_event
+
+
+class RetryManager:
+    """
+    Usage:
+        @retry.auto
+        def call_openai(...): ...
+
+        @retry.auto
+        async def call_stripe(...): ...
+    """
+
+    def auto(self, fn: Callable) -> Callable:
+        if inspect.iscoroutinefunction(fn):
+            return _async_wrapper(fn)
+        return _sync_wrapper(fn)
+
+
+#sync wrapper
+def _sync_wrapper(fn: Callable) -> Callable:
+    @functools.wraps(fn)
+    def inner(*args: Any, **kwargs: Any) -> Any:
+        service = fn.__module__.split(".")[0]
+        attempt = 0
+
+        while True:
+            t0 = time.monotonic()
+            try:
+                result = fn(*args, **kwargs)
+                duration_ms = int((time.monotonic() - t0) * 1000)
+                _fire_and_forget(record_event(service, fn.__name__, attempt + 1, "success", None, duration_ms))
+                return result
+
+            except Exception as exc:
+                duration_ms = int((time.monotonic() - t0) * 1000)
+                strategy = classify(exc)
+                attempt += 1
+
+                _fire_and_forget(record_event(service, fn.__name__, attempt, "failure", strategy.error_type, duration_ms))
+
+                if not strategy.should_retry or attempt >= strategy.max_attempts:
+                    raise
+
+                delay = _backoff(strategy, attempt)
+                time.sleep(delay)
+
+    return inner
+
+
+#async wrapper
+def _async_wrapper(fn: Callable) -> Callable:
+    @functools.wraps(fn)
+    async def inner(*args: Any, **kwargs: Any) -> Any:
+        service = fn.__module__.split(".")[0]
+        attempt = 0
+
+        while True:
+            t0 = time.monotonic()
+            try:
+                result = await fn(*args, **kwargs)
+                duration_ms = int((time.monotonic() - t0) * 1000)
+                await record_event(service, fn.__name__, attempt + 1, "success", None, duration_ms)
+                return result
+
+            except Exception as exc:
+                duration_ms = int((time.monotonic() - t0) * 1000)
+                strategy = classify(exc)
+                attempt += 1
+
+                await record_event(service, fn.__name__, attempt, "failure", strategy.error_type, duration_ms)
+
+                if not strategy.should_retry or attempt >= strategy.max_attempts:
+                    raise
+
+                delay = _backoff(strategy, attempt)
+                await asyncio.sleep(delay)
+
+    return inner
+
+
+def _backoff(strategy: RetryStrategy, attempt: int) -> float:
+    """Exponential backoff: base * 2^attempt, plus jitter up to base seconds."""
+    delay = strategy.base_delay * (2 ** (attempt - 1))
+    if strategy.use_jitter:
+        delay += random.uniform(0, strategy.base_delay)
+    return delay
+
+
+def _fire_and_forget(coro: Any) -> None:
+    """Run an async coroutine from sync context without blocking."""
+    try:
+        loop = asyncio.get_running_loop()
+        loop.create_task(coro)
+    except RuntimeError:
+        asyncio.run(coro)

resilient_sdk_core-0.1.0/resilient/store.py

@@ -0,0 +1,96 @@
+import asyncio
+import logging
+from datetime import datetime, timezone
+from typing import Optional
+
+import asyncpg
+
+from .config import get_config
+
+logger = logging.getLogger(__name__)
+
+_pool: asyncpg.Pool | None = None
+_pool_lock = asyncio.Lock()
+
+_SCHEMA_SQL = """
+CREATE SCHEMA IF NOT EXISTS resilient;
+
+CREATE TABLE IF NOT EXISTS resilient.events (
+    id          BIGSERIAL PRIMARY KEY,
+    service     TEXT        NOT NULL,
+    fn          TEXT        NOT NULL,
+    attempt     INT         NOT NULL,
+    status      TEXT        NOT NULL,   -- 'success' | 'failure'
+    error_type  TEXT,                   -- NULL on success
+    duration_ms INT         NOT NULL,
+    ts          TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_events_service_ts
+    ON resilient.events (service, ts DESC);
+
+CREATE TABLE IF NOT EXISTS resilient.stats (
+    id           BIGSERIAL PRIMARY KEY,
+    service      TEXT        NOT NULL,
+    window       TEXT        NOT NULL,  -- e.g. '1h', '24h', '7d'
+    failure_rate FLOAT       NOT NULL,
+    p95_latency  INT,                   -- ms
+    peak_hour    INT,                   -- 0-23 UTC
+    computed_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+"""
+
+
+async def _get_pool() -> asyncpg.Pool:
+    """Return the shared pool, creating it (and the schema) on first call."""
+    global _pool
+    if _pool is not None:
+        return _pool
+
+    async with _pool_lock:
+        if _pool is not None:
+            return _pool
+
+        dsn = get_config()["dsn"]
+        if not dsn:
+            raise RuntimeError(
+                "resilient-sdk: no DSN configured. "
+                "Set RESILIENT_DSN env var or add 'dsn' to config.toml."
+            )
+        _pool = await asyncpg.create_pool(dsn=dsn, min_size=2, max_size=10)
+
+        async with _pool.acquire() as conn:
+            await conn.execute(_SCHEMA_SQL)
+
+    return _pool
+
+
+async def record_event(
+    service: str,
+    fn: str,
+    attempt: int,
+    status: str,
+    error_type: Optional[str],
+    duration_ms: int,
+) -> None:
+    """Write one retry event row. Silently drops on any DB error."""
+    try:
+        pool = await _get_pool()
+        async with pool.acquire() as conn:
+            await conn.execute(
+                """
+                INSERT INTO resilient.events
+                    (service, fn, attempt, status, error_type, duration_ms, ts)
+                VALUES ($1, $2, $3, $4, $5, $6, $7)
+                """,
+                service,
+                fn,
+                attempt,
+                status,
+                error_type,
+                duration_ms,
+                datetime.now(timezone.utc),
+            )
+    except Exception:
+        # DB being down must never crash the decorated function
+        logger.debug("resilient: failed to record event", exc_info=True)