backloop-sdk 0.1.0__py3-none-any.whl

backloop/__init__.py

@@ -0,0 +1,98 @@
+"""Python SDK for the Agent Feedback Protocol: validate, send and receive structured feedback from AI agents."""
+
+from ._generated import (
+    ACK_SCHEMA,
+    AGENT_FEEDBACK_INSTRUCTIONS,
+    FEEDBACK_SCHEMA,
+    FEEDBACK_TOOL_DESCRIPTION,
+    RECORD_SCHEMA,
+)
+from .client import FeedbackClient, FeedbackError, SubmitResult, feedback_url_from_link
+from .forward import ForwardError, MemorySink, fan_out, forward_to, memory_sink
+from .ids import hash_account, new_id
+from .integrations import fastapi_router, flask_blueprint
+from .redact import REDACTED, redact, redact_string
+from .server import (
+    FeedbackHandler,
+    HandlerResponse,
+    OnRecordResult,
+    error_response,
+    feedback_link_header,
+)
+from .tool import FEEDBACK_TOOL_NAME, feedback_tool, feedback_tool_input_schema
+from .types import (
+    DEFAULT_MAX_BYTES,
+    FEEDBACK_TYPES,
+    LINK_REL,
+    OUTCOMES,
+    SPEC_VERSION,
+    WELL_KNOWN_PATH,
+    AgentInfo,
+    DiscoveryDocument,
+    Evidence,
+    FeedbackAck,
+    FeedbackRecord,
+    FeedbackSubmission,
+    KnownIssue,
+    ValidationIssue,
+)
+from .validate import (
+    ValidationResult,
+    format_issues,
+    validate_ack,
+    validate_record,
+    validate_submission,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ACK_SCHEMA",
+    "AGENT_FEEDBACK_INSTRUCTIONS",
+    "DEFAULT_MAX_BYTES",
+    "FEEDBACK_SCHEMA",
+    "FEEDBACK_TOOL_DESCRIPTION",
+    "FEEDBACK_TOOL_NAME",
+    "FEEDBACK_TYPES",
+    "LINK_REL",
+    "OUTCOMES",
+    "RECORD_SCHEMA",
+    "REDACTED",
+    "SPEC_VERSION",
+    "WELL_KNOWN_PATH",
+    "AgentInfo",
+    "DiscoveryDocument",
+    "Evidence",
+    "FeedbackAck",
+    "FeedbackClient",
+    "FeedbackError",
+    "FeedbackHandler",
+    "FeedbackRecord",
+    "FeedbackSubmission",
+    "ForwardError",
+    "HandlerResponse",
+    "KnownIssue",
+    "MemorySink",
+    "OnRecordResult",
+    "SubmitResult",
+    "ValidationIssue",
+    "ValidationResult",
+    "error_response",
+    "fan_out",
+    "fastapi_router",
+    "feedback_link_header",
+    "feedback_tool",
+    "feedback_tool_input_schema",
+    "feedback_url_from_link",
+    "flask_blueprint",
+    "format_issues",
+    "forward_to",
+    "hash_account",
+    "memory_sink",
+    "new_id",
+    "redact",
+    "redact_string",
+    "validate_ack",
+    "validate_record",
+    "validate_submission",
+]

backloop/_generated.py

@@ -0,0 +1,12 @@
+# Generated by scripts/sync-schema.mjs from spec/. Do not edit by hand.
+import json
+
+FEEDBACK_SCHEMA = json.loads("{\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"$id\":\"https://trybackloop.com/schemas/agent-feedback/0.1/feedback.schema.json\",\"title\":\"Agent Feedback Submission\",\"description\":\"Structured feedback an AI agent sends to a service when something prevents or complicates its task. Agent Feedback Protocol v0.1.\",\"type\":\"object\",\"required\":[\"type\",\"goal\",\"message\"],\"additionalProperties\":false,\"properties\":{\"spec_version\":{\"description\":\"Protocol version the agent is speaking. Defaults to \\\"0.1\\\" when omitted.\",\"type\":\"string\",\"const\":\"0.1\"},\"type\":{\"description\":\"Category of the problem.\",\"type\":\"string\",\"enum\":[\"missing_capability\",\"bug\",\"unclear_documentation\",\"unexpected_response\",\"unhelpful_error\",\"performance\",\"other\"]},\"goal\":{\"description\":\"What the agent (or its user) was trying to accomplish, in plain language. Describe the task, not the API call.\",\"type\":\"string\",\"minLength\":1,\"maxLength\":1000},\"message\":{\"description\":\"What prevented or complicated the task.\",\"type\":\"string\",\"minLength\":1,\"maxLength\":4000},\"endpoint\":{\"description\":\"The operation involved: an HTTP path template (\\\"/companies/search\\\") or a tool name (\\\"search_companies\\\").\",\"type\":\"string\",\"minLength\":1,\"maxLength\":512},\"method\":{\"description\":\"HTTP method, when the endpoint is an HTTP path.\",\"type\":\"string\",\"enum\":[\"GET\",\"POST\",\"PUT\",\"PATCH\",\"DELETE\",\"HEAD\",\"OPTIONS\"]},\"outcome\":{\"description\":\"What happened to the task. blocked: the task could not be completed. degraded: completed, but worse or slower than it should have been. completed: completed fine; the feedback is a suggestion.\",\"type\":\"string\",\"enum\":[\"blocked\",\"degraded\",\"completed\"]},\"workaround\":{\"description\":\"Whether the agent found a workaround.\",\"type\":\"boolean\"},\"workaround_description\":{\"description\":\"The workaround the agent used, if any.\",\"type\":\"string\",\"maxLength\":2000},\"expected\":{\"description\":\"What the agent expected to find or happen.\",\"type\":\"string\",\"maxLength\":2000},\"suggestion\":{\"description\":\"A concrete change that would have let the agent succeed.\",\"type\":\"string\",\"maxLength\":2000},\"request_id\":{\"description\":\"The service's request ID for a related call, to join feedback with logs.\",\"type\":\"string\",\"maxLength\":256},\"session_id\":{\"description\":\"Opaque ID shared by all feedback from one agent task run. Used to de-duplicate retries.\",\"type\":\"string\",\"maxLength\":256},\"agent\":{\"description\":\"Self-reported information about the agent.\",\"type\":\"object\",\"additionalProperties\":false,\"properties\":{\"name\":{\"type\":\"string\",\"maxLength\":128},\"version\":{\"type\":\"string\",\"maxLength\":64},\"model\":{\"type\":\"string\",\"maxLength\":128},\"framework\":{\"type\":\"string\",\"maxLength\":128}}},\"evidence\":{\"description\":\"Sanitized details of the failing interaction. Never include credentials or personal data.\",\"type\":\"object\",\"additionalProperties\":false,\"properties\":{\"status_code\":{\"type\":\"integer\",\"minimum\":100,\"maximum\":599},\"request\":{\"description\":\"Parameters or body the agent sent, with secrets removed.\",\"type\":\"object\"},\"response_excerpt\":{\"description\":\"The relevant part of the response.\",\"type\":\"string\",\"maxLength\":4000}}},\"metadata\":{\"description\":\"Free-form extra data. Services may ignore it.\",\"type\":\"object\"}}}")
+
+RECORD_SCHEMA = json.loads("{\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"$id\":\"https://trybackloop.com/schemas/agent-feedback/0.1/record.schema.json\",\"title\":\"Agent Feedback Record\",\"description\":\"A feedback submission after the receiving service has accepted it: the agent's submission plus server-side context. This is what services store and forward to collectors.\",\"type\":\"object\",\"required\":[\"id\",\"received_at\",\"feedback\"],\"additionalProperties\":false,\"properties\":{\"id\":{\"description\":\"Unique ID assigned by the receiving service.\",\"type\":\"string\",\"minLength\":1,\"maxLength\":128},\"received_at\":{\"description\":\"RFC 3339 timestamp of when the service accepted the submission.\",\"type\":\"string\",\"format\":\"date-time\"},\"service\":{\"description\":\"Name of the service that received the feedback.\",\"type\":\"string\",\"maxLength\":128},\"account\":{\"description\":\"Opaque, stable identifier of the customer account the agent authenticated as. Services should hash or pseudonymize it.\",\"type\":\"string\",\"maxLength\":256},\"source\":{\"description\":\"Channel the feedback arrived through.\",\"type\":\"string\",\"enum\":[\"http\",\"mcp\",\"sdk\",\"other\"]},\"feedback\":{\"$ref\":\"feedback.schema.json\"}}}")
+
+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."
+
+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/_http.py

@@ -0,0 +1,50 @@
+"""Minimal urllib wrapper: returns every HTTP status instead of raising on 4xx/5xx."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Mapping, Optional, Tuple
+
+Response = Tuple[int, Mapping[str, str], bytes]
+
+
+def request(
+    url: str,
+    method: str = "GET",
+    body: Optional[bytes] = None,
+    headers: Optional[Dict[str, str]] = None,
+    timeout: float = 10.0,
+) -> Response:
+    """Send a request and return ``(status, headers, body)``.
+
+    Network failures (connection refused, timeouts, bad URLs) raise. Like
+    fetch, only http(s) URLs are allowed: urllib would also open file:// URLs.
+    """
+    if urllib.parse.urlsplit(url).scheme.lower() not in ("http", "https"):
+        raise ValueError(f"Unsupported URL: {url}")
+    req = urllib.request.Request(url, data=body, method=method, headers=headers or {})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as res:
+            return res.status, res.headers, res.read()
+    except urllib.error.HTTPError as e:
+        try:
+            raw = e.read()  # reading to the end also releases the connection
+        except Exception:
+            raw = b""
+        return e.code, e.headers, raw
+
+
+def parse_json(raw: bytes) -> Any:
+    """Parse a JSON body, or return None when it is not JSON."""
+    try:
+        return json.loads(raw)
+    except ValueError:
+        return None
+
+
+def dumps(value: Any) -> bytes:
+    """Compact UTF-8 JSON, like ``JSON.stringify``."""
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":")).encode("utf-8")

backloop/client.py

@@ -0,0 +1,205 @@
+"""Send feedback to a service's ``/feedback`` endpoint."""
+
+from __future__ import annotations
+
+import email.utils
+import math
+import re
+import time
+import urllib.parse
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Mapping, Optional, Union
+
+from . import _http
+from .redact import redact as _redact
+from .types import (
+    SPEC_VERSION,
+    WELL_KNOWN_PATH,
+    AgentInfo,
+    DiscoveryDocument,
+    FeedbackAck,
+    FeedbackSubmission,
+    ValidationIssue,
+)
+from .validate import format_issues, validate_submission
+
+RETRYABLE = frozenset({429, 500, 502, 503, 504})
+USER_AGENT = f"backloop-sdk-python/{SPEC_VERSION}"
+
+
+class FeedbackError(Exception):
+    """Raised on validation, network or HTTP errors. ``code`` is the protocol error code."""
+
+    def __init__(
+        self,
+        message: str,
+        code: str,
+        status: Optional[int] = None,
+        details: Optional[List[ValidationIssue]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status = status
+        self.details = details
+
+
+@dataclass
+class SubmitResult:
+    """Result of ``try_submit``: ``ack`` when ``ok``, otherwise ``error``."""
+
+    ok: bool
+    ack: Optional[FeedbackAck] = None
+    error: Optional[FeedbackError] = None
+
+
+class FeedbackClient:
+    """Client for a service's feedback endpoint.
+
+    ``redact`` may be ``True`` (default), ``False``, or a dict of ``redact()``
+    options such as ``{"emails": False}``.
+    """
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        *,
+        endpoint: Optional[str] = None,
+        api_key: Optional[str] = None,
+        headers: Optional[Dict[str, str]] = None,
+        agent: Optional[AgentInfo] = None,
+        session_id: Optional[str] = None,
+        redact: Union[bool, Mapping[str, Any]] = True,
+        timeout: float = 10.0,
+    ) -> None:
+        if endpoint is None and base_url:
+            endpoint = base_url.rstrip("/") + "/feedback"
+        if not endpoint:
+            raise ValueError("FeedbackClient needs `endpoint` or `base_url`")
+        self.endpoint = endpoint
+        self.api_key = api_key
+        self.headers = dict(headers or {})
+        self.agent = agent
+        self.session_id = session_id
+        self.redact = redact
+        self.timeout = timeout
+
+    def prepare(self, feedback: FeedbackSubmission) -> FeedbackSubmission:
+        """Build the submission that would be sent: defaults applied, redacted and validated."""
+        body: Any = dict(feedback) if isinstance(feedback, dict) else feedback
+        if isinstance(body, dict):
+            if self.agent and not body.get("agent"):
+                body["agent"] = self.agent
+            if self.session_id and not body.get("session_id"):
+                body["session_id"] = self.session_id
+        if self.redact is not False:
+            options = self.redact if isinstance(self.redact, Mapping) else {}
+            body = _redact(body, **options)
+        result = validate_submission(body)
+        if not result.valid:
+            raise FeedbackError(format_issues(result.issues), "invalid_feedback", None, result.issues)
+        return body
+
+    def submit(self, feedback: FeedbackSubmission) -> FeedbackAck:
+        """Send feedback. Raises ``FeedbackError`` on validation, network or HTTP errors.
+
+        Retries once on 429 and 5xx, after ``Retry-After`` (default 1s, capped at 10s).
+        """
+        body = _http.dumps(self.prepare(feedback))
+        status, headers, raw = self._post(body)
+        if status in RETRYABLE:
+            delay = _retry_after_seconds(headers.get("retry-after"))
+            time.sleep(max(0.0, min(1.0 if delay is None else delay, 10.0)))
+            status, headers, raw = self._post(body)
+        payload = _http.parse_json(raw)
+        if status in (200, 202):
+            return payload
+        error = payload.get("error") if isinstance(payload, dict) else None
+        if not isinstance(error, dict):
+            error = {}
+        message = error.get("message")
+        code = error.get("code")
+        raise FeedbackError(
+            message if message is not None else f"Feedback endpoint returned HTTP {status}",
+            code if code is not None else "http_error",
+            status,
+            error.get("details"),
+        )
+
+    def try_submit(self, feedback: FeedbackSubmission) -> SubmitResult:
+        """Like ``submit``, but never raises: feedback must never break the agent's task."""
+        try:
+            return SubmitResult(ok=True, ack=self.submit(feedback))
+        except FeedbackError as e:
+            return SubmitResult(ok=False, error=e)
+        except Exception as e:  # noqa: BLE001 - best effort by design
+            return SubmitResult(ok=False, error=FeedbackError(str(e), "network_error"))
+
+    def _post(self, body: bytes) -> _http.Response:
+        headers = {"content-type": "application/json", "user-agent": USER_AGENT, **self.headers}
+        if self.api_key:
+            headers["authorization"] = f"Bearer {self.api_key}"
+        try:
+            return _http.request(self.endpoint, "POST", body, headers, self.timeout)
+        except Exception as e:
+            reason = getattr(e, "reason", e)
+            raise FeedbackError(f"Could not reach {self.endpoint}: {reason}", "network_error") from e
+
+    @staticmethod
+    def discover(base_url: str, timeout: float = 5.0) -> Optional[DiscoveryDocument]:
+        """Fetch a service's discovery document at ``/.well-known/agent-feedback``.
+
+        Returns None when the service does not implement the protocol.
+        """
+        try:
+            url = urllib.parse.urljoin(base_url, WELL_KNOWN_PATH)
+            status, _, raw = _http.request(url, headers={"user-agent": USER_AGENT}, timeout=timeout)
+        except Exception:
+            return None
+        if not 200 <= status < 300:
+            return None
+        doc = _http.parse_json(raw)
+        return doc if isinstance(doc, dict) and isinstance(doc.get("endpoint"), str) else None
+
+    @classmethod
+    def from_discovery(cls, base_url: str, **options: Any) -> Optional[FeedbackClient]:
+        """Create a client from a service's discovery document, if it has one."""
+        doc = cls.discover(base_url)
+        if doc is None:
+            return None
+        return cls(endpoint=urllib.parse.urljoin(base_url, doc["endpoint"]), **options)
+
+
+_LINK_PART = re.compile(r"<([^>]+)>\s*;(.*)")
+_LINK_REL = re.compile(r'rel="?[^";]*\bagent-feedback\b', re.ASCII)
+
+
+def feedback_url_from_link(link: Optional[str], base: str) -> Optional[str]:
+    """Parse a ``Link`` header and return the agent-feedback URL, if any."""
+    if not link:
+        return None
+    for part in link.split(","):
+        m = _LINK_PART.search(part)
+        if m and _LINK_REL.search(m.group(2)):
+            return urllib.parse.urljoin(base, m.group(1))
+    return None
+
+
+def _retry_after_seconds(header: Optional[str]) -> Optional[float]:
+    """Seconds to wait from a ``Retry-After`` header (delta-seconds or HTTP-date)."""
+    if not header:
+        return None
+    try:
+        seconds = float(header)
+        if math.isfinite(seconds):
+            return seconds
+    except ValueError:
+        pass
+    try:
+        when = email.utils.parsedate_to_datetime(header)
+    except (TypeError, ValueError, IndexError, OverflowError):
+        return None
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=timezone.utc)
+    return max(0.0, (when - datetime.now(timezone.utc)).total_seconds())

backloop/forward.py

@@ -0,0 +1,88 @@
+"""``on_record`` sinks: forward records to a collector, or keep them in memory."""
+
+from __future__ import annotations
+
+from typing import Callable, List, Optional
+
+from . import _http
+from .server import OnRecord, OnRecordResult
+from .types import FeedbackRecord
+
+
+class ForwardError(Exception):
+    """The collector could not be reached, returned an error, or rejected the record."""
+
+    def __init__(self, message: str, status: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.status = status
+
+
+def forward_to(url: str, ingest_key: Optional[str] = None, timeout: float = 5.0) -> 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``.
+    """
+    endpoint = url.rstrip("/") + "/v1/records"
+    headers = {"content-type": "application/json"}
+    if ingest_key:
+        headers["authorization"] = f"Bearer {ingest_key}"
+
+    def sink(record: FeedbackRecord) -> OnRecordResult:
+        body = _http.dumps({"records": [record]})
+        last_error = ForwardError(f"Could not forward to {endpoint}")
+        for _attempt in range(2):
+            try:
+                status, _, raw = _http.request(endpoint, "POST", body, headers, timeout)
+            except Exception as e:
+                last_error = ForwardError(f"Could not reach {endpoint}: {getattr(e, 'reason', e)}")
+                continue
+            if 200 <= status < 300:
+                return _result(raw)
+            last_error = ForwardError(f"Collector returned HTTP {status}", status)
+            if status < 500 and status != 429:
+                break
+        raise last_error
+
+    return sink
+
+
+def _result(raw: bytes) -> OnRecordResult:
+    data = _http.parse_json(raw)
+    if not isinstance(data, dict):
+        raise ForwardError("Collector returned an invalid response")
+    results = data.get("results")
+    result = results[0] if isinstance(results, list) and results and isinstance(results[0], dict) else {}
+    if result.get("status") == "rejected":
+        error = result.get("error")
+        message = error.get("message") if isinstance(error, dict) else None
+        raise ForwardError(f"Collector rejected record: {message or 'unknown error'}")
+    known_issue = result.get("known_issue")
+    return {"known_issue": known_issue} if known_issue else None
+
+
+def fan_out(*sinks: Callable[[FeedbackRecord], OnRecordResult]) -> OnRecord:
+    """Run several sinks for each record; the first ``known_issue`` wins."""
+
+    def sink(record: FeedbackRecord) -> OnRecordResult:
+        results = [s(record) for s in sinks]
+        return next((r for r in results if r and r.get("known_issue")), None)
+
+    return sink
+
+
+class MemorySink:
+    """Keeps records in ``records``. Useful for tests and prototypes."""
+
+    def __init__(self) -> None:
+        self.records: List[FeedbackRecord] = []
+
+    def __call__(self, record: FeedbackRecord) -> None:
+        self.records.append(record)
+
+
+def memory_sink() -> MemorySink:
+    """An ``on_record`` sink that keeps records in memory (``sink.records``)."""
+    return MemorySink()

backloop/ids.py

@@ -0,0 +1,35 @@
+"""Record IDs and account pseudonymization."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+import time
+
+_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"  # Crockford base32
+
+
+def new_id(prefix: str = "fb") -> str:
+    """Time-sortable unique ID (ULID layout) with a prefix, e.g. ``fb_01JAX3ZK7Q8W2M4N6P9RTV5B``."""
+    ms = time.time_ns() // 1_000_000
+    ts = ""
+    for _ in range(10):
+        ts = _ALPHABET[ms % 32] + ts
+        ms //= 32
+    rand = "".join(_ALPHABET[b % 32] for b in os.urandom(16))
+    return f"{prefix}_{ts}{rand}"
+
+
+def _utf8(value: str) -> bytes:
+    # Encode like the WHATWG TextEncoder: lone surrogates become U+FFFD.
+    return value.encode("utf-16", "surrogatepass").decode("utf-16", "replace").encode("utf-8")
+
+
+def hash_account(account_id: str, secret: str) -> str:
+    """
+    Pseudonymize an account ID with HMAC-SHA256, so collectors can count
+    affected customers without learning who they are.
+    """
+    digest = hmac.new(_utf8(secret), _utf8(account_id), hashlib.sha256).digest()
+    return "acct_" + digest[:12].hex()

backloop/integrations.py

@@ -0,0 +1,106 @@
+"""Optional FastAPI and Flask helpers. Each imports its framework lazily.
+
+No ``from __future__ import annotations`` here: FastAPI must be able to
+resolve the locally imported ``Request`` annotation.
+"""
+
+import inspect
+import json
+from typing import Any, Callable, Optional
+
+from .server import JSON_HEADERS, FeedbackHandler
+from .types import WELL_KNOWN_PATH
+
+Identify = Callable[[Any], Any]
+
+_DISCOVERY_HEADERS = {**JSON_HEADERS, "cache-control": "public, max-age=3600"}
+
+
+def _client_ip(forwarded_for: Optional[str], remote: Optional[str]) -> Optional[str]:
+    if forwarded_for:
+        first = forwarded_for.split(",")[0].strip()
+        if first:
+            return first
+    return remote
+
+
+def _read_capped(stream: Any, limit: int) -> bytes:
+    """Read at most ``limit + 1`` bytes: enough for the handler to reject an oversized body."""
+    chunks = []
+    size = 0
+    while size <= limit:
+        chunk = stream.read(limit + 1 - size)
+        if not chunk:
+            break
+        chunks.append(chunk)
+        size += len(chunk)
+    return b"".join(chunks)
+
+
+def fastapi_router(handler: FeedbackHandler, identify: Optional[Identify] = None) -> Any:
+    """A FastAPI ``APIRouter`` serving ``POST /feedback`` and ``GET /.well-known/agent-feedback``.
+
+    ``identify(request)`` (sync or async; defaults to ``handler.identify``)
+    returns the caller's pseudonymous account, or None. Include it at the app
+    root: ``app.include_router(fastapi_router(handler))``.
+    """
+    from fastapi import APIRouter, Request
+    from fastapi.responses import JSONResponse
+    from starlette.concurrency import run_in_threadpool
+
+    resolve = identify or handler.identify
+    router = APIRouter()
+
+    @router.post("/feedback")
+    async def submit_feedback(request: Request):  # type: ignore[no-untyped-def]
+        body = bytearray()
+        async for chunk in request.stream():
+            body += chunk
+            if len(body) > handler.max_bytes:
+                break
+        account = resolve(request) if resolve else None
+        if inspect.isawaitable(account):
+            account = await account
+        client_ip = _client_ip(
+            request.headers.get("x-forwarded-for"), request.client.host if request.client else None
+        )
+        status, payload, headers = await run_in_threadpool(
+            handler.handle_submit, bytes(body), request.headers.get("content-type"), account, client_ip
+        )
+        return JSONResponse(payload, status_code=status, headers=headers)
+
+    @router.get(WELL_KNOWN_PATH)
+    async def agent_feedback_discovery(request: Request):  # type: ignore[no-untyped-def]
+        return JSONResponse(handler.discovery(str(request.base_url)), headers=_DISCOVERY_HEADERS)
+
+    return router
+
+
+def flask_blueprint(handler: FeedbackHandler, identify: Optional[Identify] = None) -> Any:
+    """A Flask ``Blueprint`` serving ``POST /feedback`` and ``GET /.well-known/agent-feedback``.
+
+    ``identify(request)`` (defaults to ``handler.identify``) returns the
+    caller's pseudonymous account, or None. Register it at the app root:
+    ``app.register_blueprint(flask_blueprint(handler))``.
+    """
+    from flask import Blueprint, Response, request
+
+    resolve = identify or handler.identify
+    blueprint = Blueprint("backloop", __name__)
+
+    @blueprint.route("/feedback", methods=["POST"])
+    def submit_feedback() -> Any:
+        body = _read_capped(request.stream, handler.max_bytes)
+        account = resolve(request) if resolve else None
+        client_ip = _client_ip(request.headers.get("X-Forwarded-For"), request.remote_addr)
+        status, payload, headers = handler.handle_submit(
+            body, request.headers.get("Content-Type"), account, client_ip
+        )
+        return Response(json.dumps(payload, ensure_ascii=False), status=status, headers=headers)
+
+    @blueprint.route(WELL_KNOWN_PATH, methods=["GET"])
+    def agent_feedback_discovery() -> Any:
+        doc = handler.discovery(request.url_root)
+        return Response(json.dumps(doc), headers=_DISCOVERY_HEADERS)
+
+    return blueprint