alpha-engine-lib 0.47.0__tar.gz → 0.48.0__tar.gz

{alpha_engine_lib-0.47.0 → alpha_engine_lib-0.48.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: alpha-engine-lib
-Version: 0.47.0
-Summary: Shared utilities for the Alpha Engine modules: preflight, logging, ArcticDB, dates, decision capture, cost telemetry, Anthropic payload chokepoint, artifact freshness, RAG, agent schemas, SSM secrets, Telegram + SNS alerts, EC2 spot resilience, SSM log-capture, SSM dispatcher, Step-Functions execution-state projection, and S3-conditional-PUT writer locks. Full surface documented in README.
+Version: 0.48.0
+Summary: Shared utilities for the Alpha Engine modules: preflight, logging, ArcticDB, dates, decision capture, cost telemetry, Anthropic payload chokepoint, artifact freshness, RAG, agent schemas, SSM secrets, Telegram + SNS alerts, EC2 spot resilience, SSM log-capture, SSM dispatcher, Step-Functions execution-state projection, S3-conditional-PUT writer locks, and bounded-backoff HTTP retry. Full surface documented in README.
 Author: Brian McMahon
 License: Proprietary
 Requires-Python: >=3.9
@@ -265,6 +265,10 @@ The shared institutional-analytics engine: pure, front-end- and data-source-agno
 - **`quant.returns`** — `xirr` (money-weighted, Newton + bisection), `time_weighted_return` (GIPS), `cumulative_return`, `annualize` (stdlib).
 - **`quant.attribution`** — single-period Brinson-Fachler decomposition (`brinson_fachler`) + multi-period Cariño linking (`link_periods`) (stdlib).
 
+### `http_retry` — bounded-backoff transient-API retry chokepoint
+
+`request_with_retry(url, *, params, session, transient_status, ...)` returns the final `requests.Response` after retrying the transient class — 429 + 5xx responses (honoring `Retry-After`) and `Timeout`/`ConnectionError` network errors — with exponential backoff + full jitter; an exhausted network error raises `HttpRetryError` (api-key-scrubbed), while a persistent transient-status response is returned for the caller to interpret (so a 403, not in the transient set, is handed back for e.g. polygon's `PolygonForbiddenError` conversion). Also exposes the low-level `backoff_delay(attempt, *, base, cap, retry_after)` and `scrub_api_keys(msg)` (masks `api_key=`/`apiKey=` querystring values) for consumers with bespoke loops (the rate-limited `polygon_client` keeps its own loop + 403 + JSON parse and reuses just the delay math + scrubber). Consolidates the four mirrored alpha-engine-data retry sites (FRED fetch, polygon client, preflight reachability, FRED repair) into one policy so they stop drifting (L4499). Stdlib + `requests` only.
+
 ```python
 from alpha_engine_lib.quant.risk_measures import historical_cvar
 from alpha_engine_lib.quant.factor_risk import estimate_factor_model, portfolio_risk

{alpha_engine_lib-0.47.0 → alpha_engine_lib-0.48.0}/README.md

@@ -230,6 +230,10 @@ The shared institutional-analytics engine: pure, front-end- and data-source-agno
 - **`quant.returns`** — `xirr` (money-weighted, Newton + bisection), `time_weighted_return` (GIPS), `cumulative_return`, `annualize` (stdlib).
 - **`quant.attribution`** — single-period Brinson-Fachler decomposition (`brinson_fachler`) + multi-period Cariño linking (`link_periods`) (stdlib).
 
+### `http_retry` — bounded-backoff transient-API retry chokepoint
+
+`request_with_retry(url, *, params, session, transient_status, ...)` returns the final `requests.Response` after retrying the transient class — 429 + 5xx responses (honoring `Retry-After`) and `Timeout`/`ConnectionError` network errors — with exponential backoff + full jitter; an exhausted network error raises `HttpRetryError` (api-key-scrubbed), while a persistent transient-status response is returned for the caller to interpret (so a 403, not in the transient set, is handed back for e.g. polygon's `PolygonForbiddenError` conversion). Also exposes the low-level `backoff_delay(attempt, *, base, cap, retry_after)` and `scrub_api_keys(msg)` (masks `api_key=`/`apiKey=` querystring values) for consumers with bespoke loops (the rate-limited `polygon_client` keeps its own loop + 403 + JSON parse and reuses just the delay math + scrubber). Consolidates the four mirrored alpha-engine-data retry sites (FRED fetch, polygon client, preflight reachability, FRED repair) into one policy so they stop drifting (L4499). Stdlib + `requests` only.
+
 ```python
 from alpha_engine_lib.quant.risk_measures import historical_cvar
 from alpha_engine_lib.quant.factor_risk import estimate_factor_model, portfolio_risk

{alpha_engine_lib-0.47.0 → alpha_engine_lib-0.48.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "alpha-engine-lib"
-version = "0.47.0"
-description = "Shared utilities for the Alpha Engine modules: preflight, logging, ArcticDB, dates, decision capture, cost telemetry, Anthropic payload chokepoint, artifact freshness, RAG, agent schemas, SSM secrets, Telegram + SNS alerts, EC2 spot resilience, SSM log-capture, SSM dispatcher, Step-Functions execution-state projection, and S3-conditional-PUT writer locks. Full surface documented in README."
+version = "0.48.0"
+description = "Shared utilities for the Alpha Engine modules: preflight, logging, ArcticDB, dates, decision capture, cost telemetry, Anthropic payload chokepoint, artifact freshness, RAG, agent schemas, SSM secrets, Telegram + SNS alerts, EC2 spot resilience, SSM log-capture, SSM dispatcher, Step-Functions execution-state projection, S3-conditional-PUT writer locks, and bounded-backoff HTTP retry. Full surface documented in README."
 readme = "README.md"
 # EC2 still runs Python 3.9 on the always-on micro instance (boto3 drops
 # 3.9 support 2026-04-29, so upgrade is on the near-term roadmap). All

{alpha_engine_lib-0.47.0 → alpha_engine_lib-0.48.0}/src/alpha_engine_lib/__init__.py

@@ -1,3 +1,3 @@
 """alpha-engine-lib — shared utilities for Alpha Engine modules."""
 
-__version__ = "0.47.0"
+__version__ = "0.48.0"

alpha_engine_lib-0.48.0/src/alpha_engine_lib/http_retry.py

@@ -0,0 +1,199 @@
+"""Bounded-backoff HTTP retry primitive — the transient external-API
+resilience chokepoint (L4499).
+
+Consolidates the backoff + full-jitter + ``Retry-After`` + api-key-scrub
+retry idiom that was mirrored across four alpha-engine-data sites:
+
+  * ``collectors/daily_closes.py::_fred_get_with_retry``     (L4480)
+  * ``polygon_client.py::_get`` / ``_backoff``               (L4496)
+  * ``preflight.py::_reachability_get``                      (L4494)
+  * ``collectors/daily_closes_fred_repair.py::_fetch_fred_range``
+
+Each had its own copy of "exponential backoff + full jitter, honor
+``Retry-After``, retry the transient class, scrub the api-key from the
+error before logging/raising, then fail loud." This module is the single
+source of truth for that policy so the four callsites stop drifting.
+
+Two layers are exported:
+
+  * :func:`request_with_retry` — the full GET-with-retry for the plain
+    callsites (FRED fetch, preflight probe, FRED repair). Returns the final
+    ``requests.Response``; the caller still owns status interpretation
+    (``raise_for_status`` / special-casing a 403), so genuinely different
+    consumers compose it without a leaky mega-config.
+  * :func:`backoff_delay` + :func:`scrub_api_keys` — the low-level pieces for
+    a consumer with bespoke control flow (the rate-limited ``polygon_client``
+    keeps its own loop + 403 handling + JSON parse + rate limiter, but shares
+    the delay math and the scrubber).
+
+Design note (anti-over-engineering): this is deliberately NOT a
+pluggable-everything HTTP framework. It captures the one invariant the four
+sites share; consumers whose semantics diverge (polygon's 403 + rate limiter)
+reuse the primitives rather than being forced through a generic loop.
+"""
+
+from __future__ import annotations
+
+import logging as _logging
+import random as _random
+import re
+import time as _time
+from typing import Callable, Iterable
+
+import requests
+
+_DEFAULT_LOGGER = _logging.getLogger(__name__)
+
+# Transient HTTP status class: 429 (rate limit) + the retryable 5xx. A 4xx
+# other than 429 is a deterministic client error — retrying it is pointless,
+# so it is NOT in the default set and is returned to the caller as-is.
+DEFAULT_TRANSIENT_STATUS: "frozenset[int]" = frozenset({429, 500, 502, 503, 504})
+
+# Mask FRED ``api_key=`` (snake) and polygon ``apiKey=`` (camel) querystring
+# VALUES — both leak via ``requests`` exception ``str()`` (the effective URL)
+# and via hand-built error strings. Mirrors the per-repo scrubbers this module
+# replaces; complements ``alpha_engine_lib.logging.SecretsRedactingFilter``
+# (which catches token-shaped secrets, not query-param api keys).
+_API_KEY_RE = re.compile(r"(?:api_key|apiKey)=[^&\s]+")
+
+
+def scrub_api_keys(msg: object) -> str:
+    """Mask ``api_key=...`` / ``apiKey=...`` querystring values in a string.
+
+    Preserves the key NAME (so logs still show *which* param) and the value
+    delimiter, replacing only the secret value with ``***``. Idempotent.
+    """
+    return _API_KEY_RE.sub(lambda m: m.group(0).split("=", 1)[0] + "=***", str(msg))
+
+
+class HttpRetryError(RuntimeError):
+    """Raised when all attempts are exhausted on a transient NETWORK error
+    (``requests.Timeout`` / ``requests.ConnectionError``) or a non-transient
+    ``RequestException``.
+
+    The message is api-key-scrubbed. The originating exception is preserved
+    as ``__cause__`` (and on ``.last_exc``); ``.label`` / ``.attempts`` carry
+    context for callers that want to re-wrap (e.g. preflight's
+    ``RuntimeError(... unreachable ...)``).
+    """
+
+    def __init__(self, label: str, attempts: int, last_exc: BaseException) -> None:
+        self.label = label
+        self.attempts = attempts
+        self.last_exc = last_exc
+        super().__init__(
+            scrub_api_keys(
+                f"{label or 'request'} failed after {attempts} attempt(s): {last_exc}"
+            )
+        )
+
+
+def backoff_delay(
+    attempt: int,
+    *,
+    base: float = 1.0,
+    cap: float = 30.0,
+    retry_after: "str | float | None" = None,
+    rng: "_random.Random | None" = None,
+) -> float:
+    """Full-jitter exponential backoff: ``min(base*2**attempt + U(0, base), cap)``.
+
+    ``attempt`` is 0-indexed. Honors a server ``Retry-After`` (seconds, str or
+    float) when supplied — a numeric value replaces the exponential term (still
+    + jitter, still capped); a non-numeric ``Retry-After`` (HTTP-date form)
+    falls back to the exponential term. ``rng`` is injectable for deterministic
+    tests.
+    """
+    wait: "float | None" = None
+    if retry_after is not None:
+        try:
+            wait = float(retry_after)
+        except (TypeError, ValueError):
+            wait = None
+    if wait is None:
+        wait = base * (2 ** attempt)
+    jitter = (rng or _random).uniform(0, base)
+    return min(wait + jitter, cap)
+
+
+def request_with_retry(
+    url: str,
+    *,
+    method: str = "GET",
+    params: "dict | None" = None,
+    session: "requests.Session | None" = None,
+    timeout: float = 15.0,
+    max_attempts: int = 3,
+    backoff_base: float = 1.0,
+    backoff_cap: float = 30.0,
+    transient_status: Iterable[int] = DEFAULT_TRANSIENT_STATUS,
+    retry_network: bool = True,
+    honor_retry_after: bool = True,
+    scrub: Callable[[object], str] = scrub_api_keys,
+    logger: "_logging.Logger | None" = None,
+    label: str = "",
+    sleep: Callable[[float], None] = _time.sleep,
+) -> requests.Response:
+    """``method`` ``url`` with bounded backoff + full jitter on the transient
+    class, returning the final :class:`requests.Response`.
+
+    Retries:
+      * responses whose status is in ``transient_status`` (default 429 + 5xx),
+        honoring ``Retry-After`` when ``honor_retry_after``; and
+      * (when ``retry_network``) ``requests.Timeout`` / ``ConnectionError``.
+
+    Terminal behavior:
+      * a transient-status response that survives ``max_attempts`` is
+        **returned** — the caller decides whether to ``raise_for_status`` or
+        special-case it (e.g. a 403, which is NOT in the transient set, is
+        returned immediately for the caller to convert); and
+      * an exhausted NETWORK error (or a non-transient ``RequestException``
+        such as a bad URL) raises :class:`HttpRetryError` (scrubbed).
+
+    ``scrub`` is applied to every error string logged or raised. ``session``
+    lets a caller reuse a session (e.g. one carrying auth query params).
+    ``sleep`` is injectable for tests. ``max_attempts`` must be >= 1.
+    """
+    if max_attempts < 1:
+        raise ValueError(f"max_attempts must be >= 1, got {max_attempts}")
+    log = logger or _DEFAULT_LOGGER
+    transient = frozenset(transient_status)
+    requester = (session or requests).request
+    resp: "requests.Response | None" = None
+    for attempt in range(max_attempts):
+        last = attempt == max_attempts - 1
+        try:
+            resp = requester(method, url, params=params or {}, timeout=timeout)
+        except (requests.Timeout, requests.ConnectionError) as exc:
+            if not retry_network or last:
+                raise HttpRetryError(label, attempt + 1, exc) from exc
+            delay = backoff_delay(attempt, base=backoff_base, cap=backoff_cap)
+            log.warning(
+                "%s transient %s — backing off %.1fs (attempt %d/%d)",
+                label or url, type(exc).__name__, delay, attempt + 1, max_attempts,
+            )
+            sleep(delay)
+            continue
+        except requests.RequestException as exc:
+            # Non-transient (bad URL / too many redirects / invalid schema) —
+            # retrying a deterministic error is pointless; fail loud now.
+            raise HttpRetryError(label, attempt + 1, exc) from exc
+
+        if resp.status_code in transient and not last:
+            retry_after = resp.headers.get("Retry-After") if honor_retry_after else None
+            delay = backoff_delay(
+                attempt, base=backoff_base, cap=backoff_cap, retry_after=retry_after,
+            )
+            log.warning(
+                "%s HTTP %d — backing off %.1fs (attempt %d/%d)",
+                label or url, resp.status_code, delay, attempt + 1, max_attempts,
+            )
+            sleep(delay)
+            continue
+        return resp
+
+    # Loop exhausted on transient-status responses: return the last one for the
+    # caller to interpret (network exhaustion already raised above). resp is
+    # non-None because max_attempts >= 1 guarantees at least one assignment.
+    assert resp is not None
+    return resp

{alpha_engine_lib-0.47.0 → alpha_engine_lib-0.48.0}/src/alpha_engine_lib.egg-info/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: alpha-engine-lib
-Version: 0.47.0
-Summary: Shared utilities for the Alpha Engine modules: preflight, logging, ArcticDB, dates, decision capture, cost telemetry, Anthropic payload chokepoint, artifact freshness, RAG, agent schemas, SSM secrets, Telegram + SNS alerts, EC2 spot resilience, SSM log-capture, SSM dispatcher, Step-Functions execution-state projection, and S3-conditional-PUT writer locks. Full surface documented in README.
+Version: 0.48.0
+Summary: Shared utilities for the Alpha Engine modules: preflight, logging, ArcticDB, dates, decision capture, cost telemetry, Anthropic payload chokepoint, artifact freshness, RAG, agent schemas, SSM secrets, Telegram + SNS alerts, EC2 spot resilience, SSM log-capture, SSM dispatcher, Step-Functions execution-state projection, S3-conditional-PUT writer locks, and bounded-backoff HTTP retry. Full surface documented in README.
 Author: Brian McMahon
 License: Proprietary
 Requires-Python: >=3.9
@@ -265,6 +265,10 @@ The shared institutional-analytics engine: pure, front-end- and data-source-agno
 - **`quant.returns`** — `xirr` (money-weighted, Newton + bisection), `time_weighted_return` (GIPS), `cumulative_return`, `annualize` (stdlib).
 - **`quant.attribution`** — single-period Brinson-Fachler decomposition (`brinson_fachler`) + multi-period Cariño linking (`link_periods`) (stdlib).
 
+### `http_retry` — bounded-backoff transient-API retry chokepoint
+
+`request_with_retry(url, *, params, session, transient_status, ...)` returns the final `requests.Response` after retrying the transient class — 429 + 5xx responses (honoring `Retry-After`) and `Timeout`/`ConnectionError` network errors — with exponential backoff + full jitter; an exhausted network error raises `HttpRetryError` (api-key-scrubbed), while a persistent transient-status response is returned for the caller to interpret (so a 403, not in the transient set, is handed back for e.g. polygon's `PolygonForbiddenError` conversion). Also exposes the low-level `backoff_delay(attempt, *, base, cap, retry_after)` and `scrub_api_keys(msg)` (masks `api_key=`/`apiKey=` querystring values) for consumers with bespoke loops (the rate-limited `polygon_client` keeps its own loop + 403 + JSON parse and reuses just the delay math + scrubber). Consolidates the four mirrored alpha-engine-data retry sites (FRED fetch, polygon client, preflight reachability, FRED repair) into one policy so they stop drifting (L4499). Stdlib + `requests` only.
+
 ```python
 from alpha_engine_lib.quant.risk_measures import historical_cvar
 from alpha_engine_lib.quant.factor_risk import estimate_factor_model, portfolio_risk

{alpha_engine_lib-0.47.0 → alpha_engine_lib-0.48.0}/src/alpha_engine_lib.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ src/alpha_engine_lib/decision_capture.py
 src/alpha_engine_lib/ec2_spot.py
 src/alpha_engine_lib/email_sender.py
 src/alpha_engine_lib/eval_artifacts.py
+src/alpha_engine_lib/http_retry.py
 src/alpha_engine_lib/locks.py
 src/alpha_engine_lib/logging.py
 src/alpha_engine_lib/model_pricing.yaml
@@ -64,6 +65,7 @@ tests/test_decision_capture.py
 tests/test_ec2_spot.py
 tests/test_email_sender.py
 tests/test_eval_artifacts.py
+tests/test_http_retry.py
 tests/test_locks.py
 tests/test_logging.py
 tests/test_pillars.py

alpha_engine_lib-0.48.0/tests/test_http_retry.py

@@ -0,0 +1,199 @@
+"""Tests for ``alpha_engine_lib.http_retry`` — the consolidated transient
+external-API retry primitive (L4499)."""
+
+from __future__ import annotations
+
+import random
+from unittest.mock import MagicMock, patch
+
+import pytest
+import requests
+
+from alpha_engine_lib import http_retry
+from alpha_engine_lib.http_retry import (
+    HttpRetryError,
+    backoff_delay,
+    request_with_retry,
+    scrub_api_keys,
+)
+
+
+# ── scrub_api_keys ───────────────────────────────────────────────────────────
+
+
+def test_scrub_masks_both_styles():
+    assert scrub_api_keys("x?api_key=SECRET&y=1") == "x?api_key=***&y=1"
+    assert scrub_api_keys("x?apiKey=SECRET&y=1") == "x?apiKey=***&y=1"
+
+
+def test_scrub_terminates_at_ampersand():
+    assert scrub_api_keys("u?apiKey=SECRET&file_type=json") == "u?apiKey=***&file_type=json"
+
+
+def test_scrub_passthrough_and_idempotent():
+    assert scrub_api_keys("no key here") == "no key here"
+    once = scrub_api_keys("?api_key=SECRET")
+    assert scrub_api_keys(once) == once == "?api_key=***"
+
+
+def test_scrub_accepts_exception_object():
+    exc = requests.HTTPError("500 for url: https://x/?apiKey=LEAKED&a=1")
+    out = scrub_api_keys(exc)
+    assert "LEAKED" not in out and "apiKey=***" in out
+
+
+# ── backoff_delay ────────────────────────────────────────────────────────────
+
+
+def test_backoff_grows_exponentially_and_caps():
+    rng = MagicMock()
+    rng.uniform.return_value = 0.0  # zero jitter → deterministic
+    assert backoff_delay(0, base=1.0, cap=30.0, rng=rng) == 1.0
+    assert backoff_delay(1, base=1.0, cap=30.0, rng=rng) == 2.0
+    assert backoff_delay(2, base=1.0, cap=30.0, rng=rng) == 4.0
+    assert backoff_delay(10, base=1.0, cap=30.0, rng=rng) == 30.0  # capped
+
+
+def test_backoff_jitter_is_bounded():
+    for attempt in range(4):
+        d = backoff_delay(attempt, base=1.0, cap=100.0, rng=random.Random(attempt))
+        base_term = 1.0 * (2 ** attempt)
+        assert base_term <= d <= base_term + 1.0
+
+
+def test_backoff_honors_numeric_retry_after():
+    rng = MagicMock(); rng.uniform.return_value = 0.0
+    # Retry-After replaces the exponential term.
+    assert backoff_delay(3, base=1.0, cap=100.0, retry_after="12", rng=rng) == 12.0
+    assert backoff_delay(3, base=1.0, cap=100.0, retry_after=7.5, rng=rng) == 7.5
+
+
+def test_backoff_non_numeric_retry_after_falls_back():
+    rng = MagicMock(); rng.uniform.return_value = 0.0
+    # HTTP-date form → not parseable → exponential term (2**1 = 2).
+    assert backoff_delay(1, base=1.0, cap=100.0, retry_after="Wed, 21 Oct 2026 07:28:00 GMT", rng=rng) == 2.0
+
+
+# ── request_with_retry ───────────────────────────────────────────────────────
+
+
+def _resp(status: int, headers: "dict | None" = None) -> MagicMock:
+    r = MagicMock(spec=requests.Response)
+    r.status_code = status
+    r.headers = headers or {}
+    return r
+
+
+def _session(*side_effect):
+    s = MagicMock()
+    s.request.side_effect = list(side_effect)
+    return s
+
+
+_NOSLEEP = lambda *_a, **_k: None  # noqa: E731
+
+
+def test_success_first_try_returns_response():
+    s = _session(_resp(200))
+    out = request_with_retry("https://x", session=s, sleep=_NOSLEEP, label="x")
+    assert out.status_code == 200
+    assert s.request.call_count == 1
+
+
+def test_5xx_retries_then_succeeds():
+    s = _session(_resp(500), _resp(200))
+    out = request_with_retry("https://x", session=s, max_attempts=3, sleep=_NOSLEEP)
+    assert out.status_code == 200
+    assert s.request.call_count == 2
+
+
+def test_5xx_exhausted_returns_last_response():
+    # A persistent transient status is RETURNED (caller does raise_for_status).
+    s = _session(_resp(503), _resp(503), _resp(503))
+    out = request_with_retry("https://x", session=s, max_attempts=3, sleep=_NOSLEEP)
+    assert out.status_code == 503
+    assert s.request.call_count == 3
+
+
+def test_429_honors_retry_after_header():
+    delays = []
+    s = _session(_resp(429, {"Retry-After": "5"}), _resp(200))
+    request_with_retry(
+        "https://x", session=s, max_attempts=3,
+        sleep=lambda d: delays.append(d),
+    )
+    # The single backoff used Retry-After=5 (+ jitter in [0,1)).
+    assert len(delays) == 1 and 5.0 <= delays[0] < 6.0
+
+
+def test_non_transient_status_returned_immediately():
+    # 403 is not in the transient set → returned at once for the caller (e.g.
+    # polygon's PolygonForbiddenError conversion), no retry.
+    s = _session(_resp(403))
+    out = request_with_retry("https://x", session=s, max_attempts=3, sleep=_NOSLEEP)
+    assert out.status_code == 403
+    assert s.request.call_count == 1
+
+
+def test_network_error_retries_then_succeeds():
+    s = _session(requests.ConnectionError("boom"), _resp(200))
+    out = request_with_retry("https://x", session=s, max_attempts=3, sleep=_NOSLEEP)
+    assert out.status_code == 200
+    assert s.request.call_count == 2
+
+
+def test_network_error_exhausted_raises_scrubbed():
+    s = _session(requests.Timeout("read timed out ?apiKey=LEAKED"),
+                 requests.Timeout("read timed out ?apiKey=LEAKED"))
+    with pytest.raises(HttpRetryError) as ei:
+        request_with_retry("https://x", session=s, max_attempts=2, sleep=_NOSLEEP, label="polygon")
+    assert "LEAKED" not in str(ei.value)
+    assert ei.value.attempts == 2
+    assert isinstance(ei.value.last_exc, requests.Timeout)
+    assert "polygon" in str(ei.value)
+
+
+def test_retry_network_false_raises_on_first_network_error():
+    s = _session(requests.ConnectionError("boom"))
+    with pytest.raises(HttpRetryError):
+        request_with_retry("https://x", session=s, retry_network=False, sleep=_NOSLEEP)
+    assert s.request.call_count == 1
+
+
+def test_non_transient_request_exception_raises_immediately():
+    s = _session(requests.TooManyRedirects("loop"))
+    with pytest.raises(HttpRetryError):
+        request_with_retry("https://x", session=s, max_attempts=3, sleep=_NOSLEEP)
+    assert s.request.call_count == 1  # no retry on a deterministic error
+
+
+def test_max_attempts_must_be_positive():
+    with pytest.raises(ValueError, match="max_attempts must be >= 1"):
+        request_with_retry("https://x", session=_session(_resp(200)), max_attempts=0)
+
+
+def test_default_session_uses_requests_module():
+    # session=None path uses the module-level requests.request.
+    with patch.object(http_retry.requests, "request", return_value=_resp(200)) as m:
+        out = request_with_retry("https://x", sleep=_NOSLEEP)
+    assert out.status_code == 200
+    m.assert_called_once()
+    # method + url threaded positionally; params/timeout as kwargs.
+    args, kwargs = m.call_args
+    assert args[0] == "GET" and args[1] == "https://x"
+    assert "timeout" in kwargs
+
+
+def test_custom_transient_status_set():
+    # Caller can widen/narrow the retry class; 418 retried here, 500 not.
+    s = _session(_resp(418), _resp(200))
+    out = request_with_retry(
+        "https://x", session=s, transient_status={418}, max_attempts=3, sleep=_NOSLEEP,
+    )
+    assert out.status_code == 200 and s.request.call_count == 2
+
+    s2 = _session(_resp(500))
+    out2 = request_with_retry(
+        "https://x", session=s2, transient_status={418}, max_attempts=3, sleep=_NOSLEEP,
+    )
+    assert out2.status_code == 500 and s2.request.call_count == 1  # 500 not transient here