backloop-sdk 0.1.2__tar.gz → 0.1.3__tar.gz

{backloop_sdk-0.1.2 → backloop_sdk-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: backloop-sdk
-Version: 0.1.2
+Version: 0.1.3
 Summary: Python SDK for the Agent Feedback Protocol: validate, send and receive structured feedback from AI agents.
 Project-URL: Homepage, https://trybackloop.com
 Project-URL: Specification, https://trybackloop.com/spec/
@@ -72,7 +72,8 @@ tools = [feedback_tool()]  # {"name": "submit_feedback", "description", "input_s
 from backloop import FeedbackHandler, forward_to, hash_account
 
 handler = FeedbackHandler(
-    on_record=forward_to("https://collector.example.com", ingest_key=INGEST_KEY),  # or your own callable
+    # wait: answer the agent after at most 0.5 s and go on forwarding in a background thread.
+    on_record=forward_to("https://collector.example.com", ingest_key=INGEST_KEY, wait=0.5),  # or your own callable
     service="acme-companies-api",
     identify=lambda request: hash_account(current_account_id(request), SECRET) if authenticated(request) else None,
 )

{backloop_sdk-0.1.2 → backloop_sdk-0.1.3}/README.md

@@ -48,7 +48,8 @@ tools = [feedback_tool()]  # {"name": "submit_feedback", "description", "input_s
 from backloop import FeedbackHandler, forward_to, hash_account
 
 handler = FeedbackHandler(
-    on_record=forward_to("https://collector.example.com", ingest_key=INGEST_KEY),  # or your own callable
+    # wait: answer the agent after at most 0.5 s and go on forwarding in a background thread.
+    on_record=forward_to("https://collector.example.com", ingest_key=INGEST_KEY, wait=0.5),  # or your own callable
     service="acme-companies-api",
     identify=lambda request: hash_account(current_account_id(request), SECRET) if authenticated(request) else None,
 )

{backloop_sdk-0.1.2 → backloop_sdk-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "backloop-sdk"
-version = "0.1.2"
+version = "0.1.3"
 description = "Python SDK for the Agent Feedback Protocol: validate, send and receive structured feedback from AI agents."
 readme = "README.md"
 license = "Apache-2.0"

{backloop_sdk-0.1.2 → backloop_sdk-0.1.3}/src/backloop/__init__.py

@@ -44,7 +44,7 @@ from .validate import (
     validate_submission,
 )
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 
 __all__ = [
     "ACK_SCHEMA",

{backloop_sdk-0.1.2 → backloop_sdk-0.1.3}/src/backloop/forward.py

@@ -2,6 +2,9 @@
 
 from __future__ import annotations
 
+import logging
+import threading
+from concurrent.futures import ThreadPoolExecutor, TimeoutError as _Timeout
 from typing import Callable, List, Optional
 
 from . import _http
@@ -9,6 +12,14 @@ from .server import OnRecord, OnRecordResult
 from .types import FeedbackRecord
 
 
+logger = logging.getLogger("backloop")
+
+# Forwards that outlive their request. Few threads: they wait on the network, and a
+# collector that is down must not take the service's threads with it.
+_BACKGROUND_THREADS = 4
+_BACKGROUND_LIMIT = 200
+
+
 class ForwardError(Exception):
     """The collector could not be reached, returned an error, or rejected the record."""
 
@@ -17,13 +28,26 @@ class ForwardError(Exception):
         self.status = status
 
 
-def forward_to(url: str, ingest_key: Optional[str] = None, timeout: float = 5.0) -> OnRecord:
+def forward_to(
+    url: str,
+    ingest_key: Optional[str] = None,
+    timeout: float = 5.0,
+    wait: Optional[float] = None,
+    on_error: Optional[Callable[[Exception, FeedbackRecord], None]] = None,
+) -> OnRecord:
     """
     An ``on_record`` sink that forwards records to a collector's
     ``POST /v1/records`` and passes any ``known_issue`` back to the agent.
 
     Retries once on network errors, 429 and 5xx; raises ``ForwardError`` on
     failure, which the handler turns into ``503 unavailable``.
+
+    ``wait``: how long the agent's request waits for the collector's answer, in
+    seconds. None: until it answers (or fails). Set: at most that long, then
+    forwarding goes on in a background thread, so a slow collector never holds
+    a worker. An answer that came in time still carries the known issue back.
+    ``on_error`` is told about a forward that failed after the request was
+    answered (default: logged).
     """
     endpoint = url.rstrip("/") + "/v1/records"
     headers = {"content-type": "application/json"}
@@ -46,7 +70,50 @@ def forward_to(url: str, ingest_key: Optional[str] = None, timeout: float = 5.0)
                 break
         raise last_error
 
-    return sink
+    if wait is None:
+        return sink
+
+    pool = ThreadPoolExecutor(max_workers=_BACKGROUND_THREADS, thread_name_prefix="backloop-forward")
+    pending = threading.BoundedSemaphore(_BACKGROUND_LIMIT)
+
+    def late(error: Exception, record: FeedbackRecord) -> None:
+        if on_error:
+            on_error(error, record)
+        else:
+            logger.error("[backloop] feedback record %s not forwarded: %s", record.get("id"), error)
+
+    def background(record: FeedbackRecord) -> OnRecordResult:
+        # More waiting than a collector that is down can take: this one is dropped, and said so.
+        if not pending.acquire(blocking=False):
+            late(ForwardError(f"Too many records waiting for {endpoint}"), record)
+            return None
+        answered = threading.Event()
+        lock = threading.Lock()
+
+        def work() -> OnRecordResult:
+            try:
+                return sink(record)
+            except Exception as e:
+                with lock:
+                    if not answered.is_set():
+                        raise
+                late(e, record)
+                return None
+            finally:
+                pending.release()
+
+        future = pool.submit(work)
+        try:
+            return future.result(timeout=wait)
+        except _Timeout:
+            with lock:
+                answered.set()
+            # It failed between the timeout and the lock: nobody was told yet.
+            if future.done() and future.exception() is not None:
+                late(future.exception(), record)  # type: ignore[arg-type]
+            return None
+
+    return background
 
 
 def _result(raw: bytes) -> OnRecordResult:

{backloop_sdk-0.1.2 → backloop_sdk-0.1.3}/tests/test_forward.py

@@ -1,4 +1,6 @@
 import json
+import threading
+import time
 import unittest
 
 from backloop import FeedbackHandler, ForwardError, fan_out, forward_to, memory_sink
@@ -68,6 +70,51 @@ class ForwardToTest(unittest.TestCase):
             forward_to(refused_url(), timeout=2)(RECORD)
 
 
+class BackgroundForwardTest(unittest.TestCase):
+    def test_answers_without_waiting_for_a_slow_collector_and_still_forwards(self):
+        release = threading.Event()
+
+        def slow(_request):
+            release.wait(5)
+            return (200, DUPLICATE, {})
+
+        with LocalServer(slow) as collector:
+            started = time.monotonic()
+            result = forward_to(collector.url, wait=0.05)(RECORD)
+            self.assertIsNone(result)
+            self.assertLess(time.monotonic() - started, 1.0)
+            release.set()
+            deadline = time.monotonic() + 5
+            while not collector.requests and time.monotonic() < deadline:
+                time.sleep(0.01)
+            self.assertEqual(json.loads(collector.requests[0]["body"]), {"records": [RECORD]})
+
+    def test_a_quick_answer_still_reaches_the_agent(self):
+        with LocalServer((200, DUPLICATE, {})) as collector:
+            self.assertEqual(forward_to(collector.url, wait=2)(RECORD), {"known_issue": KNOWN_ISSUE})
+
+    def test_a_quick_failure_is_raised(self):
+        with self.assertRaises(ForwardError):
+            forward_to(refused_url(), wait=5)(RECORD)
+
+    def test_a_late_failure_is_reported_not_raised(self):
+        failed = []
+        done = threading.Event()
+
+        def late(_request):
+            time.sleep(0.2)
+            return (400, {"error": {"message": "no"}}, {})
+
+        def on_error(error, record):
+            failed.append((type(error).__name__, record["id"]))
+            done.set()
+
+        with LocalServer(late) as collector:
+            self.assertIsNone(forward_to(collector.url, wait=0.02, on_error=on_error)(RECORD))
+            self.assertTrue(done.wait(5))
+        self.assertEqual(failed, [("ForwardError", "fb_1")])
+
+
 class HandlerForwardingTest(unittest.TestCase):
     BODY = json.dumps({"type": "bug", "goal": "g", "message": "m"})