backplanes 0.1.0__py3-none-any.whl

backplanes/__init__.py

@@ -0,0 +1,95 @@
+"""Backplanes Python SDK for agent telemetry and identity management.
+
+The five-minute path:
+
+    >>> import backplanes
+    >>> client = backplanes.init(agent_name="my-agent")
+    >>> # Anthropic/OpenAI clients constructed after this line are
+    >>> # instrumented automatically; nothing else to write.
+
+Instrumentation comes in three composable tiers — semantic wrappers
+(`wrap_anthropic` / `wrap_openai`), `init()`'s constructor hooks, and the
+transport net (`patch_httpx` / `patch_requests`) — described in
+docs/design/INSTRUMENTATION_TIERS.md. Custom events are always available:
+
+    >>> event = client.create_event(edge_type="tool", direction="egress")
+    >>> client.ingest(event)
+
+Handling an incoming workflow from another agent:
+
+    >>> context_jwt = request.headers.get("Backplanes-Context")
+    >>> with client.request_context(context_jwt):
+    ...     client.ingest(client.create_event(edge_type="tool", direction="ingress"))
+
+Anything not exported here is still importable from its submodule
+(`backplanes.config`, `backplanes.identity`, `backplanes.integrations`,
+`backplanes.signing`, `backplanes.v1`) — a stable but quieter surface.
+"""
+
+from backplanes.client import BackplanesClient, BackplanesNotReadyError
+from backplanes.integrations import (
+    instrument_asgi,
+    instrument_fastapi,
+    instrument_wsgi,
+    patch_httpx,
+    patch_requests,
+)
+from backplanes.wrappers import auto_wrap, wrap_anthropic, wrap_openai
+
+__version__ = "0.1.0"
+__all__ = [
+    "init",
+    "BackplanesClient",
+    "BackplanesNotReadyError",
+    "wrap_anthropic",
+    "wrap_openai",
+    "patch_httpx",
+    "patch_requests",
+    "instrument_fastapi",
+    "instrument_asgi",
+    "instrument_wsgi",
+]
+
+
+def init(
+    agent_name=None,
+    *,
+    auto_instrument=True,
+    **client_kwargs,
+) -> BackplanesClient:
+    """One-call setup: construct the client and instrument the process.
+
+    Builds a `BackplanesClient`, hooks the Anthropic/OpenAI SDK
+    constructors so clients created afterwards come out wrapped (tier 1
+    fidelity), and installs the httpx/requests transport net for everything
+    else. SDK clients constructed before `init()` are covered by the
+    transport net alone.
+
+    Args:
+        agent_name: Human-readable name for agent registration.
+        auto_instrument: Whether to hook SDK constructors and install the
+            transport patches at all.
+        **client_kwargs: Passed through to `BackplanesClient`.
+
+    Returns:
+        The constructed BackplanesClient.
+    """
+    client = BackplanesClient(agent_name=agent_name, **client_kwargs)
+    if not auto_instrument:
+        return client
+
+    auto_wrap(client)
+    for patch in (patch_httpx, patch_requests):
+        # The transport patches import their target library lazily; a
+        # missing library just narrows the net.
+        try:
+            patch(
+                client,
+            )
+        except ImportError as exc:
+            import logging
+
+            logging.getLogger(__name__).debug(
+                "Skipping transport patch %s: %s", patch.__name__, exc
+            )
+    return client

backplanes/_integration_events.py

@@ -0,0 +1,97 @@
+"""Shared event construction for inbound and outbound HTTP integrations."""
+
+from __future__ import annotations
+
+import logging
+import time
+from contextlib import nullcontext
+from typing import Any, Optional
+from urllib.parse import urlsplit, urlunsplit
+
+from backplanes import causality
+
+logger = logging.getLogger(__name__)
+
+
+def safe_emit_http_event(
+    client: Any,
+    direction: str,
+    method: str,
+    url: str,
+    started_at: float,
+    status: str,
+    request_size_bytes: int,
+    response_size_bytes: int,
+    metadata: Optional[dict[str, str]] = None,
+    error_info: Optional[dict[str, str]] = None,
+    extra: Optional[dict[str, Any]] = None,
+    detached: bool = False,
+) -> None:
+    """Best-effort HTTP event emission that never interrupts user traffic."""
+    try:
+        merged_metadata: dict[str, str] = dict(metadata or {})
+        extra_fields = dict(extra or {})
+        merged_metadata.update(extra_fields.pop("metadata", None) or {})
+        fields: dict[str, Any] = {
+            "edge_type": "network",
+            "direction": direction,
+            "status": status,
+            "timestamp_unix_ms": int(started_at * 1000),
+            "duration_ms": duration_ms(started_at),
+            "request_size_bytes": request_size_bytes,
+            "response_size_bytes": response_size_bytes,
+            "metadata": merged_metadata,
+            "error_info": error_info,
+        }
+        fields.update(extra_fields)
+        scope = causality.detached() if detached else nullcontext()
+        with scope:
+            client.ingest(client.create_event(**fields))
+    except Exception as exc:  # pragma: no cover - defensive only
+        logger.debug("Failed to emit Backplanes HTTP event: %s", exc)
+
+
+def duration_ms(started_at: float) -> int:
+    """Convert a start timestamp into duration milliseconds."""
+    return max(0, int((time.time() - started_at) * 1000))
+
+
+def status_from_http_code(status_code: Optional[int]) -> str:
+    """Map an HTTP status code to a Backplanes event status."""
+    if status_code is None:
+        return "ok"
+    if status_code == 408:
+        return "timeout"
+    if status_code == 429:
+        return "rate_limited"
+    if status_code >= 400:
+        return "error"
+    return "ok"
+
+
+def exception_status(exc: BaseException) -> str:
+    """Map an exception to a Backplanes event status."""
+    return "timeout" if "timeout" in exc.__class__.__name__.lower() else "error"
+
+
+def http_metadata(
+    method: str,
+    url: str,
+    status_code: Optional[int],
+) -> dict[str, str]:
+    """Build lightweight HTTP metadata for emitted events."""
+    try:
+        parsed_url = urlsplit(url)
+        sanitized_url = urlunsplit(
+            (parsed_url.scheme, parsed_url.netloc, parsed_url.path, "", "")
+        )
+    except ValueError:
+        # Malformed URLs must not let best-effort telemetry break user traffic.
+        sanitized_url = url.split("#", 1)[0].split("?", 1)[0]
+    metadata = {
+        "http.method": method.upper(),
+        "http.url": sanitized_url,
+    }
+    if status_code is not None:
+        metadata["http.status_code"] = str(status_code)
+    return metadata

backplanes/_payload_fields.py

@@ -0,0 +1,24 @@
+"""Event fields derived from request and response bodies."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from backplanes import payloads, pii
+
+
+def payload_fields(request_body: bytes, response_body: bytes) -> dict[str, Any]:
+    """PII counts and optional captured content for one wire exchange."""
+    counts = pii.scan(request_body[: pii.MAX_SCAN_BYTES])
+    for category, count in pii.scan(response_body[: pii.MAX_SCAN_BYTES]).items():
+        counts[category] = counts.get(category, 0) + count
+
+    fields: dict[str, Any] = {}
+    if counts:
+        fields["pii_categories"] = pii.categories(counts)
+        fields["pii_counts"] = counts
+
+    captured = payloads.capture(request_body, response_body)
+    if captured:
+        fields["json_passed"] = captured
+    return fields