loopgain 0.4.2__tar.gz → 0.4.3__tar.gz

{loopgain-0.4.2 → loopgain-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loopgain
-Version: 0.4.2
+Version: 0.4.3
 Summary: An open-source cost controller for AI agent loops. Stops a loop when it has actually converged and rolls back before it degrades — replacing the max_iterations guess with a real-time loop-gain (Aβ) monitor with five named threshold bands and best-so-far rollback.
 Author-email: Dave Fitzsimmons <hello@loopgain.ai>
 License: Apache-2.0
@@ -183,6 +183,7 @@ LoopGain saves money by stopping a loop once it stops improving — fewer iterat
 
 - **Savings depend on your workload.** Loops that usually succeed fast save the most (~96%); adversarial, failure-prone loops save less (~78–84%). The headline is a blend — run the benchmark on your own loops before quoting a number.
 - **LoopGain detects convergence, not correctness.** It stops when your error signal stops improving — which means more iterations won't help, *not* that the loop succeeded. On the benchmark this preserved quality (it rarely stopped early on a worse output; false-stop rate ≤4.5%), but a loop can stall with the error still above zero — a plateau at, say, 2 failing tests. So check `result.best_error` (or your own pass/fail) before you trust the output: if it plateaued short of your target, that's a quality gap LoopGain can't see, and a false stop that forces a rerun is the one way it eats into the savings. LoopGain decides *when to stop*; you decide *whether the answer is good enough*.
+- **LoopGain is only as right as your verifier.** It acts on the error signal you give it. If your verifier reports zero errors, LoopGain trusts that and stops — so a verifier with blind spots can report success on an answer that is still wrong, and LoopGain will confidently stop there. This is not the plateau case above: the error reads zero and the loop looks like a clean success, so neither LoopGain nor its convergence signal can flag it. The quality of the stop is bounded by the quality of the check behind your error signal. Pair LoopGain with the strongest verifier you can afford at the stop — executable tests over a sampled subset, a schema or type check over a vibe, a held-out check the loop didn't optimize against.
 
 ---
 

{loopgain-0.4.2 → loopgain-0.4.3}/README.md

@@ -134,6 +134,7 @@ LoopGain saves money by stopping a loop once it stops improving — fewer iterat
 
 - **Savings depend on your workload.** Loops that usually succeed fast save the most (~96%); adversarial, failure-prone loops save less (~78–84%). The headline is a blend — run the benchmark on your own loops before quoting a number.
 - **LoopGain detects convergence, not correctness.** It stops when your error signal stops improving — which means more iterations won't help, *not* that the loop succeeded. On the benchmark this preserved quality (it rarely stopped early on a worse output; false-stop rate ≤4.5%), but a loop can stall with the error still above zero — a plateau at, say, 2 failing tests. So check `result.best_error` (or your own pass/fail) before you trust the output: if it plateaued short of your target, that's a quality gap LoopGain can't see, and a false stop that forces a rerun is the one way it eats into the savings. LoopGain decides *when to stop*; you decide *whether the answer is good enough*.
+- **LoopGain is only as right as your verifier.** It acts on the error signal you give it. If your verifier reports zero errors, LoopGain trusts that and stops — so a verifier with blind spots can report success on an answer that is still wrong, and LoopGain will confidently stop there. This is not the plateau case above: the error reads zero and the loop looks like a clean success, so neither LoopGain nor its convergence signal can flag it. The quality of the stop is bounded by the quality of the check behind your error signal. Pair LoopGain with the strongest verifier you can afford at the stop — executable tests over a sampled subset, a schema or type check over a vibe, a held-out check the loop didn't optimize against.
 
 ---
 

{loopgain-0.4.2 → loopgain-0.4.3}/loopgain/_version.py

@@ -7,4 +7,4 @@ from here so the value never drifts between ``__version__`` and the
 ``pyproject.toml``) for each release.
 """
 
-__version__ = "0.4.2"
+__version__ = "0.4.3"

{loopgain-0.4.2 → loopgain-0.4.3}/loopgain/core.py

@@ -514,6 +514,8 @@ class LoopGain:
         loop_type: Optional[str] = None,
         team: Optional[str] = None,
         include_per_iteration: bool = True,
+        retries: int = 2,
+        retry_backoff: float = 0.25,
     ) -> bool:
         """Send anonymized telemetry to a receiver endpoint.
 
@@ -544,6 +546,12 @@ class LoopGain:
                 per-iteration Aβ + error trajectories (capped) so the
                 dashboard's Loop Detail scrubber works. Set ``False`` to
                 send only aggregate summary stats.
+            retries: Additional attempts if a send fails *transiently*
+                (timeout, connection error, 5xx/429). Default 2 (up to 3
+                attempts). Set to 0 for single-shot. Deterministic failures
+                (bad token, etc.) are never retried.
+            retry_backoff: Base seconds between attempts; the nth retry waits
+                ``retry_backoff * n``. Default 0.25.
 
         Returns:
             ``True`` on 2xx response, ``False`` otherwise.
@@ -572,5 +580,11 @@ class LoopGain:
             include_per_iteration=include_per_iteration,
         )
         return send_payload(
-            endpoint, token, payload, timeout=timeout, allow_insecure=allow_insecure
+            endpoint,
+            token,
+            payload,
+            timeout=timeout,
+            allow_insecure=allow_insecure,
+            retries=retries,
+            retry_backoff=retry_backoff,
         )

{loopgain-0.4.2 → loopgain-0.4.3}/loopgain/telemetry.py

@@ -22,7 +22,9 @@ from __future__ import annotations
 
 import json
 import math
+import socket
 import statistics
+import time
 import urllib.error
 import urllib.request
 from datetime import datetime, timezone
@@ -218,18 +220,43 @@ def build_payload(
     return payload
 
 
+def _is_transient(exc: BaseException) -> bool:
+    """Is this send failure worth retrying?
+
+    Transient = timeout, connection/DNS error, or a 5xx/429 from the server —
+    a later attempt might succeed. Deterministic failures (4xx other than 429,
+    a refused redirect) will never succeed on retry, so they are *not*
+    transient and we give up immediately.
+    """
+    if isinstance(exc, urllib.error.HTTPError):  # subclass of URLError — check first
+        return exc.code >= 500 or exc.code == 429
+    return isinstance(exc, (TimeoutError, socket.timeout, urllib.error.URLError, OSError))
+
+
 def send_payload(
     endpoint: str,
     token: str,
     payload: dict[str, Any],
     timeout: float = 2.0,
     allow_insecure: bool = False,
+    retries: int = 2,
+    retry_backoff: float = 0.25,
 ) -> bool:
     """POST a telemetry payload to the given endpoint.
 
     Best-effort: errors are swallowed; never raises. Returns ``True`` if
     the server returned a 2xx status, ``False`` otherwise.
 
+    A single send is one HTTP POST with a ``timeout``-second deadline. The
+    warm round-trip to the hosted receiver is ~150 ms, so the default 2 s
+    timeout has wide headroom; the failure mode in practice is a *transient*
+    outlier (a cold database first-write, a momentary network blip) that
+    blows past it. Because a low-frequency caller may send only one aggregate
+    per run, a single dropped send loses that whole run's data — so a transient
+    failure is retried up to ``retries`` times with a short linear backoff.
+    Deterministic failures (bad token, malformed payload, refused redirect)
+    are *not* retried. Still best-effort throughout: the loop never raises.
+
     Args:
         endpoint: Telemetry receiver URL (e.g.,
             ``https://telemetry.loopgain.ai/v1/aggregate``). Must use
@@ -240,13 +267,18 @@ def send_payload(
         token: Bearer token issued by the receiver. Identifies the customer
             account; rotatable; not linked to any production secrets.
         payload: Dict from ``build_payload``.
-        timeout: Per-request timeout in seconds. Default 2.0.
+        timeout: Per-attempt timeout in seconds. Default 2.0.
         allow_insecure: If ``True``, permit ``http://`` endpoints. Intended
             for local development against a self-hosted receiver on
             ``http://localhost``. Default ``False``.
+        retries: Number of *additional* attempts after the first if the send
+            fails transiently. Default 2 (so up to 3 attempts total). Set to
+            0 to restore single-shot behavior.
+        retry_backoff: Base seconds to sleep between attempts; the nth retry
+            waits ``retry_backoff * n`` (0.25 s, 0.50 s, …). Default 0.25.
 
     Returns:
-        ``True`` on 2xx response, ``False`` otherwise.
+        ``True`` on a 2xx response, ``False`` otherwise.
     """
     # Refuse to attach the bearer token to anything but http(s); silently
     # best-effort so a misconfigured endpoint can't break the user's loop.
@@ -263,23 +295,33 @@ def send_payload(
 
     try:
         body = json.dumps(payload).encode("utf-8")
-        req = urllib.request.Request(
-            endpoint,
-            data=body,
-            method="POST",
-            headers={
-                "Content-Type": "application/json",
-                "Authorization": f"Bearer {token}",
-                "User-Agent": f"loopgain/{LIBRARY_VERSION}",
-            },
-        )
-        # Use the no-redirect seam so a malicious or misconfigured
-        # endpoint can't 302 the bearer token to a different host.
-        with _open_request(req, timeout) as resp:
-            return 200 <= resp.status < 300
     except Exception:
-        # Best-effort: never break the user's loop because telemetry failed.
-        # Catches URLError, HTTPError, TimeoutError, OSError, plus the
-        # ValueError that urllib raises for malformed URLs (e.g., missing scheme),
-        # plus any JSON-encoding edge case in the payload.
+        # A payload that won't JSON-encode will never send — don't retry.
         return False
+
+    req = urllib.request.Request(
+        endpoint,
+        data=body,
+        method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {token}",
+            "User-Agent": f"loopgain/{LIBRARY_VERSION}",
+        },
+    )
+
+    attempts = max(1, retries + 1)
+    for i in range(attempts):
+        try:
+            # Use the no-redirect seam so a malicious or misconfigured
+            # endpoint can't 302 the bearer token to a different host.
+            with _open_request(req, timeout) as resp:
+                return 200 <= resp.status < 300
+        except Exception as exc:
+            # Best-effort: never break the user's loop because telemetry failed.
+            # Retry only transient failures, and only if attempts remain.
+            last = i == attempts - 1
+            if last or not _is_transient(exc):
+                return False
+            time.sleep(retry_backoff * (i + 1))
+    return False

{loopgain-0.4.2 → loopgain-0.4.3}/loopgain.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loopgain
-Version: 0.4.2
+Version: 0.4.3
 Summary: An open-source cost controller for AI agent loops. Stops a loop when it has actually converged and rolls back before it degrades — replacing the max_iterations guess with a real-time loop-gain (Aβ) monitor with five named threshold bands and best-so-far rollback.
 Author-email: Dave Fitzsimmons <hello@loopgain.ai>
 License: Apache-2.0
@@ -183,6 +183,7 @@ LoopGain saves money by stopping a loop once it stops improving — fewer iterat
 
 - **Savings depend on your workload.** Loops that usually succeed fast save the most (~96%); adversarial, failure-prone loops save less (~78–84%). The headline is a blend — run the benchmark on your own loops before quoting a number.
 - **LoopGain detects convergence, not correctness.** It stops when your error signal stops improving — which means more iterations won't help, *not* that the loop succeeded. On the benchmark this preserved quality (it rarely stopped early on a worse output; false-stop rate ≤4.5%), but a loop can stall with the error still above zero — a plateau at, say, 2 failing tests. So check `result.best_error` (or your own pass/fail) before you trust the output: if it plateaued short of your target, that's a quality gap LoopGain can't see, and a false stop that forces a rerun is the one way it eats into the savings. LoopGain decides *when to stop*; you decide *whether the answer is good enough*.
+- **LoopGain is only as right as your verifier.** It acts on the error signal you give it. If your verifier reports zero errors, LoopGain trusts that and stops — so a verifier with blind spots can report success on an answer that is still wrong, and LoopGain will confidently stop there. This is not the plateau case above: the error reads zero and the loop looks like a clean success, so neither LoopGain nor its convergence signal can flag it. The quality of the stop is bounded by the quality of the check behind your error signal. Pair LoopGain with the strongest verifier you can afford at the stop — executable tests over a sampled subset, a schema or type check over a vibe, a held-out check the loop didn't optimize against.
 
 ---
 

{loopgain-0.4.2 → loopgain-0.4.3}/tests/test_telemetry.py

@@ -660,3 +660,117 @@ def test_send_payload_refuses_redirects():
         req = urllib.request.Request("https://example.com/")
         with pytest.raises(urllib.error.HTTPError):
             method(req, io.BytesIO(b""), 302, "Found", {})
+
+
+# ----- send_payload retry behavior (transient failures) -----
+
+import socket as _socket
+import urllib.error as _uerr
+
+from loopgain import telemetry as _tele
+
+
+class _OkResp:
+    status = 202
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        pass
+
+
+def _retry_payload():
+    return build_payload(_make_terminated_loop(), workload_id="retry-test")
+
+
+def test_send_payload_retries_transient_then_succeeds(monkeypatch):
+    """A transient failure (timeout) is retried; a later success returns True."""
+    calls = {"n": 0}
+
+    def flaky(req, timeout=None):
+        calls["n"] += 1
+        if calls["n"] < 3:
+            raise _socket.timeout("slow first attempts")
+        return _OkResp()
+
+    sleeps: list[float] = []
+    monkeypatch.setattr("loopgain.telemetry._open_request", flaky)
+    monkeypatch.setattr("loopgain.telemetry.time.sleep", lambda s: sleeps.append(s))
+
+    ok = send_payload("https://t.example/v1/aggregate", token="t", payload=_retry_payload())
+    assert ok is True
+    assert calls["n"] == 3                 # two transient failures, third succeeds
+    assert sleeps == [0.25, 0.5]           # linear backoff between attempts
+
+
+def test_send_payload_gives_up_after_retries_on_persistent_5xx(monkeypatch):
+    """A persistent transient (503) exhausts retries and returns False."""
+    calls = {"n": 0}
+
+    def always_503(req, timeout=None):
+        calls["n"] += 1
+        raise _uerr.HTTPError("https://t.example", 503, "unavailable", {}, None)
+
+    monkeypatch.setattr("loopgain.telemetry._open_request", always_503)
+    monkeypatch.setattr("loopgain.telemetry.time.sleep", lambda s: None)
+
+    ok = send_payload("https://t.example/v1/aggregate", token="t", payload=_retry_payload(), retries=2)
+    assert ok is False
+    assert calls["n"] == 3                  # 1 initial + 2 retries
+
+
+def test_send_payload_does_not_retry_deterministic_4xx(monkeypatch):
+    """A 401 will never succeed on retry — fail fast, no backoff."""
+    calls = {"n": 0}
+    slept = {"n": 0}
+
+    def unauthorized(req, timeout=None):
+        calls["n"] += 1
+        raise _uerr.HTTPError("https://t.example", 401, "unauthorized", {}, None)
+
+    monkeypatch.setattr("loopgain.telemetry._open_request", unauthorized)
+    monkeypatch.setattr("loopgain.telemetry.time.sleep", lambda s: slept.__setitem__("n", slept["n"] + 1))
+
+    ok = send_payload("https://t.example/v1/aggregate", token="bad", payload=_retry_payload())
+    assert ok is False
+    assert calls["n"] == 1                  # no retry on a deterministic 4xx
+    assert slept["n"] == 0
+
+
+def test_send_payload_retries_zero_is_single_shot(monkeypatch):
+    """retries=0 restores the original single-attempt behavior."""
+    calls = {"n": 0}
+
+    def timeout(req, timeout=None):
+        calls["n"] += 1
+        raise TimeoutError()
+
+    monkeypatch.setattr("loopgain.telemetry._open_request", timeout)
+    monkeypatch.setattr("loopgain.telemetry.time.sleep", lambda s: None)
+
+    ok = send_payload("https://t.example/v1/aggregate", token="t", payload=_retry_payload(), retries=0)
+    assert ok is False
+    assert calls["n"] == 1
+
+
+def test_send_payload_never_raises_on_unexpected_error(monkeypatch):
+    """A non-transient, unexpected error is swallowed (best-effort), no retry."""
+    def boom(req, timeout=None):
+        raise RuntimeError("unexpected")
+
+    monkeypatch.setattr("loopgain.telemetry._open_request", boom)
+    monkeypatch.setattr("loopgain.telemetry.time.sleep", lambda s: None)
+
+    assert send_payload("https://t.example/v1/aggregate", token="t", payload=_retry_payload()) is False
+
+
+def test_is_transient_classification():
+    assert _tele._is_transient(TimeoutError()) is True
+    assert _tele._is_transient(_socket.timeout()) is True
+    assert _tele._is_transient(_uerr.URLError("dns")) is True
+    assert _tele._is_transient(_uerr.HTTPError("u", 503, "x", {}, None)) is True
+    assert _tele._is_transient(_uerr.HTTPError("u", 429, "x", {}, None)) is True
+    assert _tele._is_transient(_uerr.HTTPError("u", 400, "x", {}, None)) is False
+    assert _tele._is_transient(_uerr.HTTPError("u", 401, "x", {}, None)) is False
+    assert _tele._is_transient(RuntimeError("x")) is False