""" Xpenvo Agents for Python. One file, standard library only (Python 3.9+). It does four small things for an agent that already uses a provider's own SDK: 1. gives the Xpenvo address for each provider (base_url), 2. adds your agent key and the optional run, step and end-customer labels (headers), 3. waits for a person to approve a big request, then runs it again (with_approval), 4. tells you why Xpenvo stopped a request (reason). Privacy: it never reads, logs or sends your prompts anywhere except to Xpenvo, exactly as your agent would without it. Run, step and customer labels must be your own ids, never an email. """ from __future__ import annotations import json import re import secrets import time import urllib.error import urllib.request from typing import Any, Callable, Dict, Optional, TypeVar __all__ = ["Xpenvo", "reason", "REASONS", "new_run_id", "DEFAULT_BASE"] __version__ = "0.1.0" DEFAULT_BASE = "https://agents.xpenvo.com" _TAG = re.compile(r"^[A-Za-z0-9_.:-]{1,64}$") _APPROVAL = re.compile(r"^apr_[0-9a-f]{16}$") _AZURE = re.compile(r"^[a-z0-9][a-z0-9-]{1,62}$") _REGION = re.compile(r"^[a-z]{2}(-gov)?-[a-z]+-\d$") _BASE = re.compile(r"^(https://.+|http://(localhost|127\.0\.0\.1)(:\d+)?)$") T = TypeVar("T") REASONS: Dict[str, str] = { "over_budget": "A budget would go over its limit.", "request_limit": "One request could cost more than the per-request limit.", "customer_limit": "This end customer reached their limit.", "run_limit": "This run reached its spending limit.", "hourly_limit": "This key reached its hourly limit.", "billing_inactive": "The organisation has no active plan.", "kill_switch": "The kill switch is on.", "key_paused": "This key is paused.", "budget_paused": "The budget is paused.", "policy_provider": "The budget does not allow this provider.", "policy_model": "The budget does not allow this model.", "policy_time": "The budget may not be used at this time.", "customer_required": "The budget needs an end customer id on every request.", "rate_limit": "Too many requests a minute. Retry shortly.", "loop_detected": "The key sent the same request again and again, so it was paused.", "spend_spike": "The key spent far faster than usual, so it was paused.", "approval_required": "A person must approve this request first.", "approval_pending": "Still waiting for approval.", "approval_denied": "A person denied this request.", "approval_limit": "Too many approvals are waiting.", } def _headers_of(obj: Any) -> Any: h = getattr(obj, "headers", None) if h is None: resp = getattr(obj, "response", None) # openai / anthropic errors keep the response here h = getattr(resp, "headers", None) return h def _header(obj: Any, name: str) -> Optional[str]: h = _headers_of(obj) if h is None: return None try: v = h.get(name) except Exception: return None return v if isinstance(v, str) and v else None def reason(err_or_response: Any) -> Optional[str]: """Why Xpenvo stopped a request, as a short code (see REASONS), or None if it was not Xpenvo.""" return _header(err_or_response, "x-xpenvo-error") def new_run_id(prefix: str = "run") -> str: """A random run id, for the Flight Recorder.""" return f"{prefix}_{secrets.token_hex(8)}" def _check_tag(name: str, v: Optional[str]) -> Optional[str]: if v is None or v == "": return None if not isinstance(v, str) or not _TAG.match(v) or "@" in v: raise ValueError(f"xpenvo: {name} must be 1-64 letters, digits, _ . : or - (and never an email address)") return v class Xpenvo: """ x = Xpenvo(key=os.environ["XPENVO_KEY"], run=new_run_id(), customer="customer-42") client = OpenAI(base_url=x.base_url("openai"), default_headers=x.headers()) """ def __init__( self, key: str, base: str = DEFAULT_BASE, run: Optional[str] = None, step: Optional[str] = None, customer: Optional[str] = None, wait_for_approval: bool = True, approval_timeout: float = 600.0, poll: float = 5.0, ) -> None: if not isinstance(key, str) or not key: raise ValueError("xpenvo: key is required") base = base.rstrip("/") if not _BASE.match(base): raise ValueError("xpenvo: base must be an https address") self.key = key self.base = base self.run = _check_tag("run", run) self.step = _check_tag("step", step) self.customer = _check_tag("customer", customer) self.wait = wait_for_approval self.approval_timeout = approval_timeout self.poll = max(1.0, poll) def __repr__(self) -> str: # never print the key return f"Xpenvo(base={self.base!r}, run={self.run!r}, step={self.step!r}, customer={self.customer!r})" def base_url(self, provider: str, where: Optional[str] = None) -> str: """The base URL to give your provider's SDK. For Azure pass the resource name, for Bedrock the region.""" b = self.base if provider == "openai": return f"{b}/v1" if provider == "anthropic": return b if provider in ("gemini", "mistral", "openrouter"): return f"{b}/v1/{provider}" if provider == "azure": if not where or not _AZURE.match(where): raise ValueError('xpenvo: give the Azure resource name, e.g. base_url("azure", "my-resource")') return f"{b}/v1/azure/{where}" if provider == "bedrock": if not where or not _REGION.match(where): raise ValueError('xpenvo: give the AWS region, e.g. base_url("bedrock", "us-east-1")') return f"{b}/v1/bedrock/{where}" raise ValueError(f'xpenvo: unknown provider "{provider}"') def headers(self, extra: Optional[Dict[str, str]] = None) -> Dict[str, str]: """Headers to add to every request (default_headers in the OpenAI and Anthropic SDKs).""" h = {"X-Xpenvo-Key": self.key} if self.run: h["X-Xpenvo-Run"] = self.run if self.step: h["X-Xpenvo-Step"] = self.step if self.customer: h["X-Xpenvo-Customer"] = self.customer if extra: h.update(extra) return h def with_(self, **change: Any) -> "Xpenvo": """The same settings with a different run, step or customer.""" o = dict(key=self.key, base=self.base, run=self.run, step=self.step, customer=self.customer, wait_for_approval=self.wait, approval_timeout=self.approval_timeout, poll=self.poll) o.update(change) return Xpenvo(**o) def approval_status(self, approval_id: str) -> str: """'pending', 'approved', 'denied', 'expired' or 'used'.""" if not _APPROVAL.match(approval_id or ""): raise ValueError("xpenvo: not an approval id") req = urllib.request.Request(f"{self.base}/v1/xpenvo/approvals/{approval_id}", headers={"X-Xpenvo-Key": self.key}) try: with urllib.request.urlopen(req, timeout=30) as r: return str(json.load(r).get("state", "pending")) except urllib.error.HTTPError as e: return "expired" if e.code == 404 else "pending" except (urllib.error.URLError, TimeoutError, ValueError): return "pending" def wait_for_approval(self, approval_id: str, timeout: Optional[float] = None) -> bool: """Wait until the approval is decided. True when approved.""" until = time.monotonic() + (self.approval_timeout if timeout is None else timeout) while time.monotonic() < until: s = self.approval_status(approval_id) if s == "approved": return True if s != "pending": return False time.sleep(self.poll) return False def with_approval(self, call: Callable[[], T]) -> T: """Run `call` (any SDK call); if Xpenvo asks for approval, wait for a person and run it again.""" try: return call() except Exception as e: approval_id = _header(e, "x-xpenvo-approval") code = reason(e) if not self.wait or not approval_id or code not in ("approval_required", "approval_pending"): raise if not self.wait_for_approval(approval_id): raise return call()