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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: backloop-sdk
-Version: 0.1.1
+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.1 → 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.1 → backloop_sdk-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "backloop-sdk"
-version = "0.1.1"
+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.1 → backloop_sdk-0.1.3}/src/backloop/__init__.py

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

{backloop_sdk-0.1.1 → 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.1 → backloop_sdk-0.1.3}/src/backloop/server.py

@@ -12,6 +12,7 @@ from datetime import datetime, timezone
 from typing import Any, Callable, Dict, List, Mapping, Optional, Tuple, Union
 
 from .ids import new_id
+from .redact import redact as _redact
 from .types import (
     DEFAULT_MAX_BYTES,
     FEEDBACK_TYPES,
@@ -93,6 +94,9 @@ class FeedbackHandler:
       account behind a framework request; used by the integrations.
     - ``rate_limit`` is ``(max, window_seconds)`` per account (or per IP), or
       None to disable it.
+    - ``redact`` removes secrets, card numbers and email addresses from what
+      agents send, before ``on_record`` sees it. True (default), False, or a
+      dict of ``redact()`` options. Not every agent uses a client that does.
     """
 
     def __init__(
@@ -106,6 +110,7 @@ class FeedbackHandler:
         public_endpoint: Optional[str] = None,
         rate_limit: Optional[Tuple[int, float]] = (60, 60.0),
         source: FeedbackSource = "http",
+        redact: Union[bool, Mapping[str, Any]] = True,
         generate_id: Optional[Callable[[], str]] = None,
         now: Optional[Callable[[], datetime]] = None,
     ) -> None:
@@ -118,6 +123,7 @@ class FeedbackHandler:
         self.max_bytes = max_bytes
         self.public_endpoint = public_endpoint
         self.source = source
+        self.redact = redact
         self._limiter = _RateLimiter(*rate_limit) if rate_limit else None
         self._generate_id = generate_id or (lambda: new_id("fb"))
         self._now = now or (lambda: datetime.now(timezone.utc))
@@ -163,6 +169,8 @@ class FeedbackHandler:
         if account:
             record["account"] = account
         record["source"] = self.source or "http"
+        if self.redact is not False:
+            parsed = _redact(parsed, **(self.redact if isinstance(self.redact, Mapping) else {}))
         record["feedback"] = parsed
 
         try:

{backloop_sdk-0.1.1 → 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"})
 

{backloop_sdk-0.1.1 → backloop_sdk-0.1.3}/tests/test_server.py

@@ -51,6 +51,19 @@ class HappyPathTest(unittest.TestCase):
             [{"id": "fb_test", "received_at": "2026-09-28T10:04:11.123Z", "source": "http", "feedback": SUBMISSION}],
         )
 
+    def test_removes_secrets_and_emails_whatever_client_sent_them(self):
+        leaky = dict(SUBMISSION, message="401 with Bearer 9f8e7d6c5b4a3f2e for jane@acme.test", metadata={"password": "hunter2", "plan": "team"})
+        handler, sink = make()
+        status, _, _ = handler.handle_submit(json.dumps(leaky).encode(), JSON)
+        self.assertEqual(status, 202)
+        feedback = sink.records[0]["feedback"]
+        self.assertEqual(feedback["message"], "401 with [REDACTED] for [REDACTED]")
+        self.assertEqual(feedback["metadata"], {"password": "[REDACTED]", "plan": "team"})
+        # Asked not to: as sent.
+        handler, sink = make(redact=False)
+        handler.handle_submit(json.dumps(leaky).encode(), JSON)
+        self.assertEqual(sink.records[0]["feedback"]["message"], leaky["message"])
+
     def test_record_carries_service_account_and_source(self):
         handler, sink = make(service="acme-api", source="mcp")
         handler.handle_submit(BODY, JSON, "acct_abc")