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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: backloop-sdk
-Version: 0.1.2
+Version: 0.1.4
 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.4}/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.4}/pyproject.toml

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

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

{backloop_sdk-0.1.2 → backloop_sdk-0.1.4}/src/backloop/_generated.py

@@ -7,6 +7,6 @@ RECORD_SCHEMA = json.loads("{\"$schema\":\"https://json-schema.org/draft/2020-12
 
 ACK_SCHEMA = json.loads("{\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"$id\":\"https://trybackloop.com/schemas/agent-feedback/0.1/ack.schema.json\",\"title\":\"Agent Feedback Acknowledgement\",\"description\":\"Body of a 202 response to POST /feedback.\",\"type\":\"object\",\"required\":[\"id\",\"status\",\"received_at\"],\"properties\":{\"id\":{\"type\":\"string\"},\"status\":{\"type\":\"string\",\"const\":\"accepted\"},\"received_at\":{\"type\":\"string\",\"format\":\"date-time\"},\"known_issue\":{\"description\":\"Present when the service already tracks this problem. Agents can use it to stop retrying or to apply a known workaround.\",\"type\":\"object\",\"required\":[\"id\",\"title\",\"status\"],\"properties\":{\"id\":{\"type\":\"string\"},\"title\":{\"type\":\"string\"},\"status\":{\"type\":\"string\",\"enum\":[\"acknowledged\",\"planned\",\"in_progress\",\"fixed\",\"wont_fix\"]},\"url\":{\"type\":\"string\"},\"workaround\":{\"type\":\"string\"}}}}}")
 
-AGENT_FEEDBACK_INSTRUCTIONS = "## Reporting feedback to the services you use\n\nThe services you call accept structured feedback through `POST /feedback` (or the `submit_feedback` tool). Your reports go to the engineers who build the service and are used to fix what got in your way. Use it.\n\n**Submit feedback when something prevented or complicated your task:**\n- a capability you needed does not exist (a filter, field, endpoint or bulk operation);\n- the documentation was missing, ambiguous or wrong, and you had to guess;\n- a response was surprising or inconsistent with the docs;\n- an error message did not tell you how to fix the request;\n- the service behaved incorrectly;\n- latency, rate limits or pagination made the task impractical.\n\n**Don't submit feedback** for your own mistakes that the service reported clearly, for things you have not tried, or more than once for the same problem in the same task.\n\n**Write it like this:**\n- `goal`: what you or your user were trying to accomplish, in plain language. \"Find companies currently hiring GTM engineers\", not \"call /companies/search\".\n- `message`: what got in the way, specifically. \"No hiring-role filter is available; `q` only matches company names.\"\n- `type`: `missing_capability`, `bug`, `unclear_documentation`, `unexpected_response`, `unhelpful_error`, `performance` or `other`.\n- Fill `endpoint`, `outcome` (`blocked`, `degraded` or `completed`), `workaround`, `expected` and `suggestion` when you know them. A concrete suggestion is the most useful thing you can give.\n- Reuse the same `session_id` for every report in one task.\n\n**Never include** credentials, API keys, tokens, passwords, personal data, or your user's private content. Describe the shape of a request, not its secrets.\n\n**Keep going.** Submitting feedback is best effort. Send it, then continue with the task or a workaround. If the response contains `known_issue`, the problem is already tracked: tell your user if it matters, and use the workaround if one is given."
+AGENT_FEEDBACK_INSTRUCTIONS = "## Reporting feedback to the services you use\n\nThe services you call accept structured feedback through `POST /feedback` (or the `submit_feedback` tool). Your reports go to the engineers who build the service and are used to fix what got in your way. Use it.\n\n**Submit feedback when something prevented or complicated your task, even if you found a workaround:**\n- a capability you needed does not exist (a filter, field, endpoint or bulk operation), so you made extra calls, filtered results yourself, or gave up;\n- the documentation was missing, ambiguous or wrong, and you had to guess;\n- a response was surprising or inconsistent with the docs;\n- an error message did not tell you how to fix the request;\n- the service behaved incorrectly;\n- latency, rate limits or pagination made the task impractical.\n\n**Before your final answer,** check whether any of these happened. If one did and you have not reported it, report it now, then answer.\n\n**Don't submit feedback** for your own mistakes that the service reported clearly, for things you have not tried, or more than once for the same problem in the same task.\n\n**Write it like this:**\n- `goal`: what you or your user were trying to accomplish, in plain language. \"Find companies currently hiring GTM engineers\", not \"call /companies/search\".\n- `message`: what got in the way, specifically. \"No hiring-role filter is available; `q` only matches company names.\"\n- `type`: `missing_capability`, `bug`, `unclear_documentation`, `unexpected_response`, `unhelpful_error`, `performance` or `other`.\n- Fill `endpoint`, `outcome` (`blocked`, `degraded` or `completed`), `workaround`, `expected` and `suggestion` when you know them. A concrete suggestion is the most useful thing you can give.\n- Reuse the same `session_id` for every report in one task.\n\n**Never include** credentials, API keys, tokens, passwords, personal data, or your user's private content. Describe the shape of a request, not its secrets.\n\n**Keep going.** Submitting feedback is best effort. Send it, then continue with the task or a workaround. If the response contains `known_issue`, the problem is already tracked: tell your user if it matters, and use the workaround if one is given."
 
 FEEDBACK_TOOL_DESCRIPTION = "Report a problem with this service to its engineering team. Call this when something prevented or complicated your task: a missing capability (filter, field, endpoint), unclear or wrong documentation, a surprising response, an unhelpful error, a bug, or impractical performance. Describe your goal in plain language, say specifically what got in the way, and include a concrete suggestion if you have one. Report each distinct problem once per task. Never include credentials, personal data or your user's private content. This is best effort: after calling it, continue with your task."

{backloop_sdk-0.1.2 → backloop_sdk-0.1.4}/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.4}/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"})