backstop-ai 0.6.0__py3-none-any.whl

backstop/__init__.py

@@ -0,0 +1,43 @@
+from .config import BackstopConfig, Priority
+from .cost import CostEstimate, estimate as cost_estimate
+
+__version__ = "0.6.0"
+from .exceptions import (
+    BackstopError,
+    BudgetExceededError,
+    CircuitBreakerOpenError,
+    LatencyBudgetExceededError,
+    UnsupportedClientError,
+)
+from .extract import count_tokens
+from .hooks import AfterResponseHook, BeforeRequestHook
+from .latency import BackstopMeta
+from .ledger import BudgetLedger, ReservationTicket, TenantBudget, get_current_tenant, get_ledger, with_budget
+from .wrapper import Backstop
+
+__all__ = [
+    "AfterResponseHook",
+    "Backstop",
+    "BackstopConfig",
+    "BackstopMeta",
+    "BeforeRequestHook",
+    "BudgetExceededError",
+    "BudgetLedger",
+    "CircuitBreakerOpenError",
+    "CostEstimate",
+    "LatencyBudgetExceededError",
+    "Priority",
+    "ReservationTicket",
+    "TenantBudget",
+    "UnsupportedClientError",
+    "BackstopError",
+    "budgets",
+    "count_tokens",
+    "get_current_tenant",
+    "with_budget",
+    "cost",
+]
+
+budgets = get_ledger()
+cost = type("_CostModule", (), {"estimate": staticmethod(cost_estimate)})()
+

backstop/__main__.py

@@ -0,0 +1,4 @@
+"""Entry point for ``python -m backstop``."""
+from .cli import main
+
+raise SystemExit(main())

backstop/_httpcompat.py

@@ -0,0 +1,119 @@
+"""Select the httpx-compatible module each wrapped SDK actually uses.
+
+``openai>=3`` and ``anthropic>=1`` moved to ``httpx2``; older SDK majors use
+``httpx``. The two modules expose the same transport API surface but their
+objects are mutually incompatible — an SDK rejects an http client built from
+the other module, so Backstop must build its transports from the module the
+wrapped SDK itself uses.
+
+The module is detected from the wrapped client's own internal HTTP client,
+so the choice always matches the SDK in front of us. When ``httpx2`` is not
+installed, only the classic ``httpx`` compatibility is available.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+try:  # httpx2 is optional: it arrives as a dependency of modern openai/anthropic SDKs
+    import httpx2  # noqa: F401
+
+    _HAS_HTTPX2 = True
+except ImportError:  # pragma: no cover - exercised only on httpx-only installs
+    httpx2 = None  # type: ignore[assignment]
+    _HAS_HTTPX2 = False
+
+
+class _HttpCompat:
+    """Namespace exposing one httpx-compatible module's transport surface."""
+
+    __slots__ = (
+        "module",
+        "name",
+        "Client",
+        "AsyncClient",
+        "BaseTransport",
+        "AsyncBaseTransport",
+        "HTTPTransport",
+        "AsyncHTTPTransport",
+        "Request",
+        "Response",
+        "URL",
+        "Timeout",
+        "TimeoutException",
+        "TransportError",
+        "ConnectError",
+        "ReadTimeout",
+        "MockTransport",
+    )
+
+    def __init__(self, module: Any) -> None:
+        self.module = module
+        self.name = getattr(module, "__name__", "")
+        self.Client = module.Client
+        self.AsyncClient = module.AsyncClient
+        self.BaseTransport = module.BaseTransport
+        self.AsyncBaseTransport = module.AsyncBaseTransport
+        self.HTTPTransport = module.HTTPTransport
+        self.AsyncHTTPTransport = module.AsyncHTTPTransport
+        self.Request = module.Request
+        self.Response = module.Response
+        self.URL = module.URL
+        self.Timeout = module.Timeout
+        self.TimeoutException = module.TimeoutException
+        self.TransportError = module.TransportError
+        self.ConnectError = module.ConnectError
+        self.ReadTimeout = module.ReadTimeout
+        self.MockTransport = module.MockTransport
+
+
+HTTPX = _HttpCompat(httpx)
+HTTPX2 = _HttpCompat(httpx2) if _HAS_HTTPX2 else None
+
+# Module-level exports default to the classic httpx family: ``httpx`` is an
+# unconditional dependency while ``httpx2`` is optional, so this is the only
+# default that cannot fail on an httpx-only install. Per-client selection goes
+# through :func:`compat_for` instead.
+Client = HTTPX.Client
+AsyncClient = HTTPX.AsyncClient
+BaseTransport = HTTPX.BaseTransport
+AsyncBaseTransport = HTTPX.AsyncBaseTransport
+HTTPTransport = HTTPX.HTTPTransport
+AsyncHTTPTransport = HTTPX.AsyncHTTPTransport
+Request = HTTPX.Request
+Response = HTTPX.Response
+URL = HTTPX.URL
+Timeout = HTTPX.Timeout
+TimeoutException = HTTPX.TimeoutException
+TransportError = HTTPX.TransportError
+ConnectError = HTTPX.ConnectError
+ReadTimeout = HTTPX.ReadTimeout
+MockTransport = getattr(httpx, "MockTransport")
+
+
+def compat_for(base_client: Any) -> _HttpCompat:
+    """Return the compat module matching the SDK's own internal client.
+
+    ``base_client`` is the wrapped SDK client's ``_client`` attribute. Its
+    class ``__mro__`` names the module family (``httpx`` vs ``httpx2``) that
+    built it, which is the module the SDK will accept back.
+    """
+    for cls in type(base_client).__mro__:
+        root = getattr(cls, "__module__", "").partition(".")[0]
+        if root == "httpx2":
+            if HTTPX2 is None:
+                break
+            return HTTPX2
+        if root == "httpx":
+            return HTTPX
+    return HTTPX
+
+
+def module_root(obj: Any) -> str:
+    """Return ``httpx`` or ``httpx2`` for an object, whichever built its type."""
+    for cls in type(obj).__mro__:
+        root = getattr(cls, "__module__", "").partition(".")[0]
+        if root in ("httpx", "httpx2"):
+            return root
+    return ""

backstop/adapters/__init__.py

@@ -0,0 +1,73 @@
+"""Framework adapters (Deep Research P1#6).
+
+Backstop enforces in-process, but agents live inside frameworks (LangChain,
+LlamaIndex, CrewAI, AutoGen). These thin, optional-import adapters bridge the
+framework's callback system to Backstop's hooks/metrics/tenant scoping so
+Backstop becomes *the* guardrail inside the framework instead of a wrapper around
+the raw SDK. Framework imports are deferred to call time, so ``import
+backstop.adapters`` is always safe without the framework installed.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+class BackstopAdapter:
+    """Framework-agnostic bridge. Subclass or call ``on_llm_start`` /
+    ``on_llm_end`` from a framework callback to feed Backstop's metrics and
+    audit log. No framework dependency."""
+
+    def __init__(self, config: Any, tenant_id: str | None = None) -> None:
+        self.config = config
+        self.tenant_id = tenant_id
+
+    def on_llm_start(self, model: str, estimated_tokens: int = 0) -> dict:
+        return {"model": model, "estimated_tokens": estimated_tokens, "tenant_id": self.tenant_id}
+
+    def on_llm_end(self, model: str, prompt_tokens: int = 0, completion_tokens: int = 0) -> dict:
+        return {
+            "model": model,
+            "prompt_tokens": prompt_tokens,
+            "completion_tokens": completion_tokens,
+            "tenant_id": self.tenant_id,
+        }
+
+
+def get_langchain_handler(config: Any, tenant_id: str | None = None) -> Any:
+    from langchain_core.callbacks import BaseCallbackHandler
+
+    adapter = BackstopAdapter(config, tenant_id)
+
+    class BackstopCallbackHandler(BaseCallbackHandler):
+        def on_llm_start(self, serialized, prompts, **kwargs):
+            model = (serialized or {}).get("name", "") if isinstance(serialized, dict) else ""
+            est = sum(len(p) // 4 for p in prompts) if prompts else 0
+            adapter.on_llm_start(model, est)
+
+        def on_llm_end(self, response, **kwargs):
+            model = getattr(response, "llm_output", None) or {}
+            usage = (model.get("token_usage") if isinstance(model, dict) else None) or {}
+            adapter.on_llm_end(
+                model.get("model_name", "") if isinstance(model, dict) else "",
+                usage.get("prompt_tokens", 0),
+                usage.get("completion_tokens", 0),
+            )
+
+    return BackstopCallbackHandler()
+
+
+def get_llama_index_callback(config: Any, tenant_id: str | None = None) -> Any:
+    from llama_index.core.callbacks import BaseCallbackHandler as LlamaBase
+
+    adapter = BackstopAdapter(config, tenant_id)
+
+    class BackstopLlamaHandler(LlamaBase):
+        def on_event_start(self, event_type, payload=None, event_id="", parent_id="", **kwargs):
+            if str(event_type).lower().startswith("llm"):
+                adapter.on_llm_start(str(payload.get("model", "")) if isinstance(payload, dict) else "")
+
+        def on_event_end(self, event_type, payload=None, event_id="", parent_id="", **kwargs):
+            if str(event_type).lower().startswith("llm"):
+                adapter.on_llm_end(str(payload.get("model", "")) if isinstance(payload, dict) else "")
+
+    return BackstopLlamaHandler()

backstop/admission.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import asyncio
+import itertools
+import threading
+import time
+from collections import deque
+from dataclasses import dataclass
+
+from .aimd import AIMDController
+from .config import BackstopConfig, Priority
+
+
+@dataclass
+class _Ticket:
+    priority: Priority
+    sequence: int
+    enqueued_at: float
+
+
+class PriorityGate:
+    def __init__(self, config: BackstopConfig, aimd: AIMDController) -> None:
+        self._config = config
+        self._aimd = aimd
+        self._active = 0
+        self._counter = itertools.count()
+        self._queues: dict[Priority, deque[_Ticket]] = {
+            Priority.CRITICAL: deque(),
+            Priority.DEFAULT: deque(),
+            Priority.BACKGROUND: deque(),
+        }
+        self._condition = threading.Condition()
+        self._async_condition = asyncio.Condition()
+
+    @property
+    def active(self) -> int:
+        with self._condition:
+            return self._active
+
+    @property
+    def depth(self) -> int:
+        with self._condition:
+            return sum(len(queue) for queue in self._queues.values())
+
+    def acquire(self, priority: Priority, timeout: float | None = None) -> float:
+        ticket = _Ticket(priority, next(self._counter), time.monotonic())
+        effective = timeout if timeout is not None else self._config.queue_timeout
+        with self._condition:
+            self._queues[priority].append(ticket)
+            self._condition.notify_all()
+            while not self._can_admit(ticket):
+                if effective is None:
+                    self._condition.wait()
+                else:
+                    if not self._condition.wait(timeout=effective):
+                        raise TimeoutError("gate acquire timed out")
+            self._queues[priority].popleft()
+            self._active += 1
+            return time.monotonic() - ticket.enqueued_at
+
+    def release(self) -> None:
+        with self._condition:
+            self._active = max(0, self._active - 1)
+            self._condition.notify_all()
+
+    async def aacquire(self, priority: Priority, timeout: float | None = None) -> float:
+        ticket = _Ticket(priority, next(self._counter), time.monotonic())
+        effective = timeout if timeout is not None else self._config.queue_timeout
+        async with self._async_condition:
+            self._queues[priority].append(ticket)
+            self._async_condition.notify_all()
+            while not self._can_admit(ticket):
+                try:
+                    if effective is None:
+                        await self._async_condition.wait()
+                    else:
+                        await asyncio.wait_for(self._async_condition.wait(), effective)
+                except asyncio.TimeoutError:
+                    raise TimeoutError("gate acquire timed out")
+            self._queues[priority].popleft()
+            self._active += 1
+            return time.monotonic() - ticket.enqueued_at
+
+    async def arelease(self) -> None:
+        async with self._async_condition:
+            self._active = max(0, self._active - 1)
+            self._async_condition.notify_all()
+
+    def _can_admit(self, ticket: _Ticket) -> bool:
+        if self._active >= self._aimd.current_limit:
+            return False
+        chosen = self._choose_ticket()
+        return chosen is ticket
+
+    def _choose_ticket(self) -> _Ticket | None:
+        now = time.monotonic()
+        critical = self._queues[Priority.CRITICAL]
+        if critical:
+            return critical[0]
+
+        aged = [
+            queue[0]
+            for queue in self._queues.values()
+            if queue and now - queue[0].enqueued_at >= self._config.starvation_after_seconds
+        ]
+        if aged:
+            return min(aged, key=lambda item: item.sequence)
+
+        for priority in (Priority.DEFAULT, Priority.BACKGROUND):
+            queue = self._queues[priority]
+            if queue:
+                return queue[0]
+        return None
+

backstop/agent_guard.py

@@ -0,0 +1,54 @@
+"""Agent-native guardrails (Deep Research P2#11).
+
+Coding/agent loops can run away: repeated tool calls, runaway generation, or
+stalls. ``AgentGuard`` tracks per-agent request counts and token spend within a
+sliding window and blocks (returns False) once a ceiling is hit, so a misbehaving
+agent is fenced by Backstop rather than silently burning the whole budget.
+"""
+from __future__ import annotations
+
+import threading
+import time
+from collections import deque
+
+
+class AgentGuard:
+    def __init__(
+        self,
+        max_calls: int = 100,
+        window_seconds: float = 60.0,
+        max_tokens: int | None = None,
+    ) -> None:
+        self.max_calls = max_calls
+        self.window_seconds = window_seconds
+        self.max_tokens = max_tokens
+        self._calls: dict[str, deque[float]] = {}
+        self._tokens: dict[str, deque[tuple[float, int]]] = {}
+        self._lock = threading.Lock()
+
+    def allow(self, agent_id: str, tokens: int = 0) -> bool:
+        now = time.monotonic()
+        with self._lock:
+            calls = self._calls.setdefault(agent_id, deque())
+            self._trim(calls, now)
+            if len(calls) >= self.max_calls:
+                return False
+            calls.append(now)
+
+            if self.max_tokens is not None and tokens > 0:
+                spent = self._tokens.setdefault(agent_id, deque())
+                self._trim_tokens(spent, now)
+                if sum(t for _, t in spent) + tokens > self.max_tokens:
+                    return False
+                spent.append((now, tokens))
+            return True
+
+    def _trim(self, calls: deque[float], now: float) -> None:
+        cutoff = now - self.window_seconds
+        while calls and calls[0] < cutoff:
+            calls.popleft()
+
+    def _trim_tokens(self, spent: deque[tuple[float, int]], now: float) -> None:
+        cutoff = now - self.window_seconds
+        while spent and spent[0][0] < cutoff:
+            spent.popleft()

backstop/aimd.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import threading
+import time
+
+from .config import BackstopConfig
+
+
+class AIMDController:
+    def __init__(self, config: BackstopConfig) -> None:
+        self._config = config
+        self._limit = config.initial_concurrency
+        # Initialize so the first adjustment is always allowed regardless
+        # of how long this system has been running (monotonic clock).
+        self._last_adjustment = -self._config.aimd_adjustment_interval
+        self._lock = threading.Lock()
+
+    @property
+    def current_limit(self) -> int:
+        with self._lock:
+            return self._limit
+
+    def record_success(self) -> bool:
+        now = time.monotonic()
+        with self._lock:
+            if now - self._last_adjustment < self._config.aimd_adjustment_interval:
+                return False
+            if self._limit >= self._config.max_concurrency:
+                return False
+            self._limit = min(self._config.max_concurrency, self._limit + self._config.aimd_increase)
+            self._last_adjustment = now
+            return True
+
+    def record_pressure(self) -> bool:
+        now = time.monotonic()
+        with self._lock:
+            if now - self._last_adjustment < self._config.aimd_adjustment_interval:
+                return False
+            new_limit = max(
+                self._config.min_concurrency,
+                int(self._limit * self._config.aimd_decrease_factor),
+            )
+            if new_limit == self._limit:
+                return False
+            self._limit = new_limit
+            self._last_adjustment = now
+            return True
+
+    def apply_external_decrease(self, pressure: float = 1.0) -> bool:
+        """Proactively clamp the limit from an out-of-band signal (e.g. provider
+        quota pressure). Bypasses the adjustment-interval throttle so a quota
+        warning takes effect on the very next request."""
+        with self._lock:
+            factor = max(self._config.aimd_decrease_factor, min(1.0, pressure))
+            new_limit = max(self._config.min_concurrency, int(self._limit * factor))
+            if new_limit == self._limit:
+                return False
+            self._limit = new_limit
+            self._last_adjustment = time.monotonic()
+            return True
+

backstop/audit.py

@@ -0,0 +1,79 @@
+"""Tamper-evident audit log (Deep Research P2#8).
+
+Every enforcement decision (deny / fallback / downgrade / cache_hit) is appended
+as a JSON record whose integrity is chained: each record carries an HMAC of its
+own payload plus the previous record's chain hash. `verify()` replays the chain
+and detects any tampering. This is the enterprise "escape hatch" that makes
+in-process enforcement audit-ready and closes the supply-chain / audit gap the
+research flagged (e.g. the March-2026 LiteLLM incident class).
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import threading
+import time
+from typing import Any, Callable
+
+
+def _chain_hash(prev: bytes, payload: bytes, key: bytes) -> str:
+    mac = hmac.new(key, prev + payload, hashlib.sha256).hexdigest()
+    return hashlib.sha256((prev.hex() + mac).encode()).hexdigest()
+
+
+class AuditLog:
+    def __init__(self, sink: str | Callable[[str], None], hmac_key: str | None = None) -> None:
+        self._key = (hmac_key or "").encode("utf-8")
+        self._prev = b""
+        self._lock = threading.Lock()
+        self._file = open(sink, "a", encoding="utf-8") if isinstance(sink, str) else None
+        self._callable = sink if callable(sink) else None
+
+    def record(self, decision: str, reason: str, **fields: Any) -> dict:
+        rec = {"ts": time.time(), "decision": decision, "reason": reason}
+        if fields:
+            rec.update(fields)
+        payload = json.dumps(rec, sort_keys=True, default=str).encode("utf-8")
+        with self._lock:
+            chain = _chain_hash(self._prev, payload, self._key)
+            rec["_chain"] = chain
+            self._prev = bytes.fromhex(chain)
+        line = json.dumps(rec, sort_keys=True, default=str)
+        with self._lock:
+            if self._file is not None:
+                self._file.write(line + "\n")
+                self._file.flush()
+            elif self._callable is not None:
+                self._callable(line)
+        return rec
+
+    def verify(self, lines: list[str] | None = None) -> bool:
+        prev = b""
+        source = lines if lines is not None else self._read_lines()
+        for line in source:
+            line = line.strip()
+            if not line:
+                continue
+            rec = json.loads(line)
+            payload = json.dumps(
+                {k: v for k, v in rec.items() if k != "_chain"}, sort_keys=True, default=str
+            ).encode("utf-8")
+            chain = _chain_hash(prev, payload, self._key)
+            if chain != rec.get("_chain"):
+                return False
+            prev = bytes.fromhex(rec["_chain"])
+        return True
+
+    def _read_lines(self) -> list[str]:
+        if self._file is None:
+            return []
+        path = self._file.name
+        self._file.flush()
+        with open(path, "r", encoding="utf-8") as fh:
+            return fh.readlines()
+
+    def close(self) -> None:
+        if self._file is not None:
+            self._file.close()
+            self._file = None