backloop-sdk 0.1.5__tar.gz → 0.2.0__tar.gz

{backloop_sdk-0.1.5 → backloop_sdk-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: backloop-sdk
-Version: 0.1.5
+Version: 0.2.0
 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/
@@ -20,6 +20,8 @@ Provides-Extra: fastapi
 Requires-Dist: fastapi>=0.100; extra == 'fastapi'
 Provides-Extra: flask
 Requires-Dist: flask>=2.0; extra == 'flask'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # backloop-sdk
@@ -97,6 +99,36 @@ document = handler.discovery("https://api.example.com")
 
 `on_record(record)` stores or forwards each accepted record. Return `{"known_issue": {...}}` to pass a tracked issue back to the agent. If it raises, the agent gets `503`. Add `feedback_link_header()` as a `Link` header on your API's error responses so agents find the endpoint.
 
+## MCP servers: session analytics
+
+```sh
+pip install "backloop-sdk[mcp]"
+```
+
+```python
+from mcp.server.fastmcp import FastMCP  # or mcp.server.mcpserver.MCPServer (mcp 2.x), or fastmcp.FastMCP
+from backloop import instrument_server
+
+mcp = FastMCP("acme")
+analytics = instrument_server(mcp, url=BACKLOOP_URL, ingest_key=INGEST_KEY, service="acme-mcp")
+```
+
+Every tool call becomes a `tool_call` event (session, client, duration, ok or error, redacted previews of the input and result), sent in batches to `<url>/v1/sessions/events` from a background thread. Tools registered before or after the call are covered, sync or async. Each tool gets an optional `telemetry` argument the agent fills in (`user_intent`, `agent_thinking`, `user_frustration`, `agent_model`); it is removed before your function runs. Sending never raises into a tool: a failure logs one warning.
+
+Options: `identify=lambda ctx: ...` returns the pseudonymous account (may be async for async tools), `telemetry=False`, `redact=False`, `preview_chars=2000`, `flush_ms=1000`, `on_events=callable` for a sink of your own. Call `analytics.flush()` before a serverless function returns (it also runs at exit).
+
+## REST APIs: agent request analytics
+
+```python
+from backloop import record_requests
+
+app.add_middleware(record_requests, url=BACKLOOP_URL, ingest_key=INGEST_KEY, service="acme-api")  # FastAPI / Starlette
+app.wsgi_app = record_requests(app.wsgi_app, url=BACKLOOP_URL, ingest_key=INGEST_KEY)              # Flask
+application = record_requests(application, url=BACKLOOP_URL, ingest_key=INGEST_KEY)                # any ASGI or WSGI app
+```
+
+Each request from an AI agent becomes an `http_request` event: method, route template (FastAPI's route or Flask's rule, else the path with ids collapsed to `:id`), status, duration, the agent, and redacted previews of the query (or body) and response. `X-Agent-Session` or `Mcp-Session-Id` groups requests into a session. Browser and unknown traffic is skipped unless `agents_only=False`; `detect_agent(headers)` tells you what was detected (Claude-User, ChatGPT-User, claude-code, Cursor, the Anthropic and OpenAI SDKs, `X-Agent-Name`, `Signature-Agent`...). `/feedback`, `/health`, `/healthz` and `/.well-known/` are skipped by default (`skip=lambda path: ...`). Other options: `identify` and `route` (both get the ASGI scope or WSGI environ), `preview_chars=1000`, `redact`, `flush_ms`, `on_events`.
+
 ## Utilities
 
 ```python

{backloop_sdk-0.1.5 → backloop_sdk-0.2.0}/README.md

@@ -73,6 +73,36 @@ document = handler.discovery("https://api.example.com")
 
 `on_record(record)` stores or forwards each accepted record. Return `{"known_issue": {...}}` to pass a tracked issue back to the agent. If it raises, the agent gets `503`. Add `feedback_link_header()` as a `Link` header on your API's error responses so agents find the endpoint.
 
+## MCP servers: session analytics
+
+```sh
+pip install "backloop-sdk[mcp]"
+```
+
+```python
+from mcp.server.fastmcp import FastMCP  # or mcp.server.mcpserver.MCPServer (mcp 2.x), or fastmcp.FastMCP
+from backloop import instrument_server
+
+mcp = FastMCP("acme")
+analytics = instrument_server(mcp, url=BACKLOOP_URL, ingest_key=INGEST_KEY, service="acme-mcp")
+```
+
+Every tool call becomes a `tool_call` event (session, client, duration, ok or error, redacted previews of the input and result), sent in batches to `<url>/v1/sessions/events` from a background thread. Tools registered before or after the call are covered, sync or async. Each tool gets an optional `telemetry` argument the agent fills in (`user_intent`, `agent_thinking`, `user_frustration`, `agent_model`); it is removed before your function runs. Sending never raises into a tool: a failure logs one warning.
+
+Options: `identify=lambda ctx: ...` returns the pseudonymous account (may be async for async tools), `telemetry=False`, `redact=False`, `preview_chars=2000`, `flush_ms=1000`, `on_events=callable` for a sink of your own. Call `analytics.flush()` before a serverless function returns (it also runs at exit).
+
+## REST APIs: agent request analytics
+
+```python
+from backloop import record_requests
+
+app.add_middleware(record_requests, url=BACKLOOP_URL, ingest_key=INGEST_KEY, service="acme-api")  # FastAPI / Starlette
+app.wsgi_app = record_requests(app.wsgi_app, url=BACKLOOP_URL, ingest_key=INGEST_KEY)              # Flask
+application = record_requests(application, url=BACKLOOP_URL, ingest_key=INGEST_KEY)                # any ASGI or WSGI app
+```
+
+Each request from an AI agent becomes an `http_request` event: method, route template (FastAPI's route or Flask's rule, else the path with ids collapsed to `:id`), status, duration, the agent, and redacted previews of the query (or body) and response. `X-Agent-Session` or `Mcp-Session-Id` groups requests into a session. Browser and unknown traffic is skipped unless `agents_only=False`; `detect_agent(headers)` tells you what was detected (Claude-User, ChatGPT-User, claude-code, Cursor, the Anthropic and OpenAI SDKs, `X-Agent-Name`, `Signature-Agent`...). `/feedback`, `/health`, `/healthz` and `/.well-known/` are skipped by default (`skip=lambda path: ...`). Other options: `identify` and `route` (both get the ASGI scope or WSGI environ), `preview_chars=1000`, `redact`, `flush_ms`, `on_events`.
+
 ## Utilities
 
 ```python

{backloop_sdk-0.1.5 → backloop_sdk-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "backloop-sdk"
-version = "0.1.5"
+version = "0.2.0"
 description = "Python SDK for the Agent Feedback Protocol: validate, send and receive structured feedback from AI agents."
 readme = "README.md"
 license = "Apache-2.0"
@@ -29,6 +29,7 @@ Issues = "https://github.com/backloophq/agent-feedback-protocol/issues"
 [project.optional-dependencies]
 fastapi = ["fastapi>=0.100"]
 flask = ["flask>=2.0"]
+mcp = ["mcp>=1.2"]
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/backloop"]

{backloop_sdk-0.1.5 → backloop_sdk-0.2.0}/src/backloop/__init__.py

@@ -11,7 +11,9 @@ from .client import FeedbackClient, FeedbackError, SubmitResult, feedback_url_fr
 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 .mcp import SessionAnalytics, instrument_server
 from .redact import REDACTED, redact, redact_string
+from .requests_recorder import collapse_path, detect_agent, record_requests
 from .server import (
     FeedbackHandler,
     HandlerResponse,
@@ -45,7 +47,7 @@ from .validate import (
     validate_submission,
 )
 
-__version__ = "0.1.5"
+__version__ = "0.2.0"
 
 __all__ = [
     "ACK_SCHEMA",
@@ -60,6 +62,7 @@ __all__ = [
     "RECORD_SCHEMA",
     "REDACTED",
     "SPEC_VERSION",
+    "SessionAnalytics",
     "WELL_KNOWN_PATH",
     "AgentInfo",
     "DiscoveryDocument",
@@ -79,6 +82,8 @@ __all__ = [
     "ValidationIssue",
     "ValidationResult",
     "agent_from_user_agent",
+    "collapse_path",
+    "detect_agent",
     "error_response",
     "fan_out",
     "fastapi_router",
@@ -90,8 +95,10 @@ __all__ = [
     "format_issues",
     "forward_to",
     "hash_account",
+    "instrument_server",
     "memory_sink",
     "new_id",
+    "record_requests",
     "redact",
     "redact_string",
     "validate_ack",

backloop_sdk-0.2.0/src/backloop/_events.py

@@ -0,0 +1,219 @@
+"""Session events: the shared queue, previews and limits behind ``instrument_server`` and ``record_requests``.
+
+Events go to ``POST <url>/v1/sessions/events`` as ``{"events": [...]}``, in the
+same JSON shapes as the TypeScript SDK's ``sessions.ts``.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import logging
+import threading
+import time
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, List, Mapping, Optional, Union
+
+from . import _http
+from .redact import redact as _redact
+from .redact import redact_string
+
+logger = logging.getLogger("backloop")
+
+FRUSTRATION_LEVELS = ("low", "medium", "high")
+
+#: Same values as ``SESSION_EVENT_LIMITS`` in ``@backloop/sdk``.
+SESSION_EVENT_LIMITS = {"preview": 4000, "error": 1000, "telemetry": 1000, "batch": 500}
+
+SessionEvent = Dict[str, Any]
+OnEvents = Callable[[List[SessionEvent]], Any]
+RedactOption = Union[bool, Mapping[str, Any]]
+
+
+def clip(value: str, limit: int) -> str:
+    return value if len(value) <= limit else value[: limit - 1] + "…"
+
+
+def iso_now(ms: Optional[float] = None) -> str:
+    """ISO 8601 in UTC with milliseconds, like ``Date.prototype.toISOString``."""
+    dt = datetime.fromtimestamp((time.time() * 1000 if ms is None else ms) / 1000, timezone.utc)
+    return dt.strftime("%Y-%m-%dT%H:%M:%S.") + f"{dt.microsecond // 1000:03d}Z"
+
+
+def _jsonable(value: Any) -> Any:
+    dump = getattr(value, "model_dump", None)  # pydantic models
+    if callable(dump):
+        try:
+            return dump(mode="json")
+        except Exception:
+            pass
+    if isinstance(value, (set, frozenset)):
+        return list(value)
+    if isinstance(value, bytes):
+        return value.decode("utf-8", "replace")
+    return str(value)
+
+
+class Scrubber:
+    """Redaction and size-capped previews, from the ``redact`` and ``preview_chars`` options."""
+
+    def __init__(self, redact: RedactOption = True, preview_chars: int = 2000) -> None:
+        self.enabled = redact is not False
+        options = dict(redact) if isinstance(redact, Mapping) else {}
+        self.emails = options.get("emails", True)
+        self.patterns = list(options.get("patterns") or ())
+        self.preview_chars = min(max(int(preview_chars), 0), SESSION_EVENT_LIMITS["preview"])
+
+    def string(self, value: str) -> str:
+        return redact_string(value, self.emails, self.patterns) if self.enabled else value
+
+    def value(self, value: Any) -> Any:
+        return _redact(value, self.emails, self.patterns) if self.enabled else value
+
+    def preview(self, value: Any) -> Optional[str]:
+        if not self.preview_chars or value is None:
+            return None
+        try:
+            if isinstance(value, str):
+                text = value
+            else:
+                plain = json.loads(json.dumps(value, ensure_ascii=False, default=_jsonable))
+                text = json.dumps(self.value(plain), ensure_ascii=False, separators=(",", ":"))
+        except Exception:
+            return None
+        return clip(self.string(text), self.preview_chars) if text else None
+
+    def error(self, message: str) -> str:
+        return clip(self.string(message), SESSION_EVENT_LIMITS["error"])
+
+
+def clean_telemetry(raw: Any, scrubber: Scrubber) -> Optional[Dict[str, str]]:
+    """Keep the known telemetry fields, trimmed, redacted and capped; None when nothing is left."""
+    if raw is None:
+        return None
+    if not isinstance(raw, Mapping):
+        dump = getattr(raw, "model_dump", None)
+        raw = dump() if callable(dump) else getattr(raw, "__dict__", None)
+        if not isinstance(raw, Mapping):
+            return None
+    out: Dict[str, str] = {}
+    for key in ("user_intent", "agent_thinking"):
+        value = raw.get(key)
+        if isinstance(value, str) and value.strip():
+            out[key] = clip(scrubber.string(value.strip()), SESSION_EVENT_LIMITS["telemetry"])
+    model = raw.get("agent_model")
+    if isinstance(model, str) and model.strip():
+        out["agent_model"] = clip(model.strip(), 128)
+    frustration = raw.get("user_frustration")
+    if isinstance(frustration, str) and frustration in FRUSTRATION_LEVELS:
+        out["user_frustration"] = frustration
+    # Keep the TS key order: user_intent, agent_thinking, user_frustration, agent_model.
+    order = ("user_intent", "agent_thinking", "user_frustration", "agent_model")
+    return {k: out[k] for k in order if k in out} or None
+
+
+class EventQueue:
+    """Queues events and POSTs them in batches from one background daemon thread.
+
+    A send failure goes to ``on_error`` (default: one logged warning) and is
+    never raised to the code that pushed the event.
+    """
+
+    def __init__(
+        self,
+        url: Optional[str] = None,
+        ingest_key: Optional[str] = None,
+        on_events: Optional[OnEvents] = None,
+        flush_ms: float = 1000,
+        on_error: Optional[Callable[[BaseException], None]] = None,
+        timeout: float = 5.0,
+    ) -> None:
+        self.endpoint = url.rstrip("/") + "/v1/sessions/events" if url else None
+        self.ingest_key = ingest_key
+        self.on_events = on_events
+        self.flush_s = max(float(flush_ms), 0) / 1000
+        self.timeout = timeout
+        self.enabled = bool(self.endpoint or on_events)
+        self._on_error = on_error
+        self._warned = False
+        self._cond = threading.Condition()
+        self._send_lock = threading.Lock()
+        self._queue: List[SessionEvent] = []
+        self._thread: Optional[threading.Thread] = None
+        if self.enabled:
+            atexit.register(self.flush)
+
+    def push(self, event: SessionEvent) -> None:
+        if not self.enabled:
+            return
+        with self._cond:
+            self._queue.append(event)
+            # Started lazily, and again in a forked worker (threads don't survive fork).
+            if self._thread is None or not self._thread.is_alive():
+                self._thread = threading.Thread(target=self._run, name="backloop-events", daemon=True)
+                self._thread.start()
+            self._cond.notify()
+
+    def flush(self) -> None:
+        """Send what is queued now, in the calling thread. Never raises."""
+        with self._send_lock:
+            with self._cond:
+                events, self._queue = self._queue, []
+            if not events:
+                return
+            try:
+                self._send(events)
+            except BaseException as e:  # noqa: BLE001 - never raised into the caller
+                self._error(e)
+
+    def _run(self) -> None:
+        batch = SESSION_EVENT_LIMITS["batch"]
+        while True:
+            with self._cond:
+                while not self._queue:
+                    self._cond.wait()
+                deadline = time.monotonic() + self.flush_s
+                while 0 < len(self._queue) < batch:
+                    remaining = deadline - time.monotonic()
+                    if remaining <= 0:
+                        break
+                    self._cond.wait(remaining)
+            self.flush()
+
+    def _send(self, events: List[SessionEvent]) -> None:
+        if self.on_events is not None:
+            self.on_events(events)
+        if not self.endpoint:
+            return
+        headers = {"content-type": "application/json"}
+        if self.ingest_key:
+            headers["authorization"] = f"Bearer {self.ingest_key}"
+        size = SESSION_EVENT_LIMITS["batch"]
+        for i in range(0, len(events), size):
+            body = _http.dumps({"events": events[i : i + size]})
+            last_error: Optional[BaseException] = None
+            for _ in range(2):
+                try:
+                    status, _headers, _raw = _http.request(self.endpoint, "POST", body, headers, self.timeout)
+                except Exception as e:
+                    last_error = e
+                    continue
+                if 200 <= status < 300:
+                    last_error = None
+                    break
+                last_error = RuntimeError(f"Backloop returned HTTP {status}")
+                if status < 500 and status != 429:
+                    break
+            if last_error is not None:
+                raise last_error
+
+    def _error(self, error: BaseException) -> None:
+        if self._on_error is not None:
+            try:
+                self._on_error(error)
+            except Exception:
+                pass
+            return
+        if not self._warned:
+            self._warned = True
+            logger.warning("[backloop] session events not sent: %s", error)

{backloop_sdk-0.1.5 → backloop_sdk-0.2.0}/src/backloop/_generated.py

@@ -5,7 +5,7 @@ FEEDBACK_SCHEMA = json.loads("{\"$schema\":\"https://json-schema.org/draft/2020-
 
 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\"}}}}}")
+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\"},\"fixed_at\":{\"type\":\"string\",\"format\":\"date-time\",\"description\":\"When status is fixed: when the fix shipped.\"},\"note\":{\"type\":\"string\",\"description\":\"Written by a person on the service's team: what changed and how to use it now.\"}}}}}")
 
 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- Always fill `agent`: `name` (the agent or product you run as) and `model`. Engineers use it to tell which agent a report came from.\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."