usdf 0.1.2__py3-none-any.whl

usdf/__init__.py

@@ -0,0 +1,102 @@
+"""Client for the USDF metered inference gateway."""
+
+from .client import DEFAULT_BASE_URL, SDK_VERSION, USDF, ChatCompletionStream, RunResult, X402
+from .errors import USDFError
+from .estimate import cost_units, estimate_prompt_tokens, max_cost_units, max_prompt_tokens, units
+from .types import (
+    Account,
+    Amount,
+    ApiKey,
+    Balance,
+    ChatCompletion,
+    CreatedKey,
+    KeyLimits,
+    Pricing,
+    PricingModel,
+    Quote,
+    Receipt,
+    ReceiptLookup,
+    Session,
+    X402Receipt,
+)
+from .x402 import (
+    CHAIN_ID,
+    DEFAULT_MAX_AMOUNT,
+    GATEWAY_PAYEE,
+    GATEWAY_ORIGIN,
+    PERMIT2_ADDRESS,
+    PUBLIC_RPC_URL,
+    USDF_ADDRESS,
+    USDG_ADDRESS,
+    X402_EXACT_PERMIT2_PROXY,
+    PaymentLimits,
+    Signer,
+    check_accept,
+    choose_accept,
+    decode_payment_required,
+    decode_payment_response,
+    decode_uint256,
+    encode_payment_signature,
+    approve_permit2,
+    eth_account_signer,
+    permit2_allowance_call,
+    permit2_approval_call,
+    payment_limits,
+    read_permit2_allowance,
+    sign_exact_payment,
+    wallet_signer,
+)
+
+__all__ = [
+    "USDF",
+    "USDFError",
+    "X402",
+    "DEFAULT_BASE_URL",
+    "SDK_VERSION",
+    "RunResult",
+    "ChatCompletionStream",
+    "Account",
+    "Amount",
+    "ApiKey",
+    "Balance",
+    "ChatCompletion",
+    "CreatedKey",
+    "KeyLimits",
+    "Pricing",
+    "PricingModel",
+    "Quote",
+    "Receipt",
+    "ReceiptLookup",
+    "Session",
+    "X402Receipt",
+    "cost_units",
+    "estimate_prompt_tokens",
+    "max_cost_units",
+    "max_prompt_tokens",
+    "units",
+    "PERMIT2_ADDRESS",
+    "X402_EXACT_PERMIT2_PROXY",
+    "CHAIN_ID",
+    "USDF_ADDRESS",
+    "USDG_ADDRESS",
+    "GATEWAY_PAYEE",
+    "GATEWAY_ORIGIN",
+    "PUBLIC_RPC_URL",
+    "DEFAULT_MAX_AMOUNT",
+    "PaymentLimits",
+    "payment_limits",
+    "check_accept",
+    "Signer",
+    "choose_accept",
+    "decode_payment_required",
+    "decode_payment_response",
+    "decode_uint256",
+    "encode_payment_signature",
+    "eth_account_signer",
+    "permit2_allowance_call",
+    "permit2_approval_call",
+    "sign_exact_payment",
+    "wallet_signer",
+    "read_permit2_allowance",
+    "approve_permit2",
+]

usdf/_http.py

@@ -0,0 +1,91 @@
+"""HTTP transport: httpx when installed (and not disabled), the standard library's urllib otherwise.
+
+Both return the same shape so the client never knows which ran: a status, lower-cased headers, and
+either the whole body or an iterator of byte chunks for streams.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Dict, Iterator, Optional
+
+try:  # optional
+    import httpx  # type: ignore
+except Exception:  # pragma: no cover - depends on the environment
+    httpx = None
+
+
+@dataclass
+class Response:
+    status: int
+    headers: Dict[str, str]
+    body: bytes
+
+    def json(self) -> Any:
+        if not self.body:
+            return None
+        try:
+            return json.loads(self.body.decode("utf-8"))
+        except ValueError:
+            return None
+
+
+@dataclass
+class StreamResponse:
+    status: int
+    headers: Dict[str, str]
+    chunks: Iterator[bytes]
+    close: Any
+
+
+def pick_transport(name: Optional[str]) -> str:
+    name = name or os.environ.get("USDF_TRANSPORT") or ("urllib" if os.environ.get("USDF_NO_HTTPX") else None)
+    if name == "httpx":
+        if httpx is None:
+            raise RuntimeError("httpx is not installed; pip install usdf[httpx]")
+        return "httpx"
+    if name == "urllib":
+        return "urllib"
+    return "httpx" if httpx is not None else "urllib"
+
+
+class Transport:
+    def __init__(self, name: Optional[str] = None):
+        self.name = pick_transport(name)
+        self._client = httpx.Client(timeout=None) if self.name == "httpx" else None
+
+    def request(self, method: str, url: str, headers: Dict[str, str], body: Optional[bytes], timeout: float) -> Response:
+        if self._client is not None:
+            r = self._client.request(method, url, headers=headers, content=body, timeout=timeout)
+            return Response(r.status_code, {k.lower(): v for k, v in r.headers.items()}, r.content)
+        req = urllib.request.Request(url, data=body, method=method, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as res:
+                return Response(res.status, {k.lower(): v for k, v in res.headers.items()}, res.read())
+        except urllib.error.HTTPError as e:
+            return Response(e.code, {k.lower(): v for k, v in e.headers.items()}, e.read())
+
+    def stream(self, method: str, url: str, headers: Dict[str, str], body: Optional[bytes], timeout: float) -> StreamResponse:
+        if self._client is not None:
+            req = self._client.build_request(method, url, headers=headers, content=body, timeout=timeout)
+            r = self._client.send(req, stream=True)
+            return StreamResponse(r.status_code, {k.lower(): v for k, v in r.headers.items()}, r.iter_bytes(), r.close)
+        req = urllib.request.Request(url, data=body, method=method, headers=headers)
+        try:
+            res = urllib.request.urlopen(req, timeout=timeout)
+        except urllib.error.HTTPError as e:
+            data = e.read()
+            return StreamResponse(e.code, {k.lower(): v for k, v in e.headers.items()}, iter([data]), lambda: None)
+
+        def chunks() -> Iterator[bytes]:
+            while True:
+                piece = res.read1(8192) if hasattr(res, "read1") else res.read(8192)
+                if not piece:
+                    return
+                yield piece
+
+        return StreamResponse(res.status, {k.lower(): v for k, v in res.headers.items()}, chunks(), res.close)

usdf/accept.py

@@ -0,0 +1,187 @@
+"""Accept USDF in one integration: charge your own API's callers in USDF over x402, settled by Foundry's facilitator
+and paid on to your payout address in USDF (or in USDG, 1:1, with settle_as="usdg"). Your server needs your Foundry API
+key (an approved partner's, in USDF_API_KEY) and a price.
+
+    from usdf.accept import AcceptUSDF
+
+    paid = AcceptUSDF(price="0.01")
+    app = paid.wsgi(app)  # any WSGI app (Flask's app.wsgi_app, Django's application)
+
+Or for one request, whatever the framework:
+
+    result = paid.charge(url, headers)
+    if not result.paid:
+        return result.status, result.headers, result.body  # 402 asking for payment, or a refusal
+    # serve it; add result.headers (PAYMENT-RESPONSE) to the answer
+
+A request without a payment is answered 402 with the PAYMENT-REQUIRED header any x402 client reads; one with a payment
+(PAYMENT-SIGNATURE, or X-PAYMENT) is settled before the app runs, and the app runs only for a payment that settled.
+Standard library only."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Iterable, Mapping, Optional, Union
+
+DEFAULT_FACILITATOR_URL = "https://api.usdf.fi"
+_PRICE = re.compile(r"^\d{1,5}(\.\d{1,6})?$")
+
+
+@dataclass
+class Accepted:
+    """A settled payment: its transaction, payer and network, and what it came to for you."""
+
+    transaction: str
+    payer: str
+    network: str
+    amount: str
+    fee: str
+    paid_on: str
+    settle_as: str
+    settlement_id: str
+
+
+@dataclass
+class ChargeResult:
+    """paid: the payment settled (payment holds it; add headers to your answer). Otherwise answer with status,
+    headers and body instead of running the request."""
+
+    paid: bool
+    status: int = 200
+    headers: Dict[str, str] = field(default_factory=dict)
+    body: bytes = b""
+    payment: Optional[Accepted] = None
+
+
+def _refusal(status: int, code: str, message: str) -> ChargeResult:
+    body = json.dumps({"error": {"message": message, "type": "payment_error", "code": code}}).encode()
+    return ChargeResult(paid=False, status=status, headers={"content-type": "application/json"}, body=body)
+
+
+def _header(headers: Mapping[str, str], name: str) -> Optional[str]:
+    for k, v in headers.items():
+        if k.lower() == name:
+            return v
+    return None
+
+
+class AcceptUSDF:
+    """Charges each request `price` USDF (a string like "0.01", or a function of the request's URL and headers)."""
+
+    def __init__(
+        self,
+        price: Union[str, Callable[[str, Mapping[str, str]], str]],
+        api_key: Optional[str] = None,
+        settle_as: str = "usdf",
+        description: str = "",
+        mime_type: str = "application/json",
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        opener: Optional[Callable[..., Any]] = None,
+    ) -> None:
+        if settle_as not in ("usdf", "usdg"):
+            raise ValueError('settle_as is "usdf" or "usdg"')
+        self.price = price
+        self.api_key = api_key
+        self.settle_as = settle_as
+        self.description = description
+        self.mime_type = mime_type
+        self.base_url = (base_url or os.environ.get("USDF_BASE_URL") or DEFAULT_FACILITATOR_URL).rstrip("/")
+        self.timeout = timeout
+        self._open = opener or urllib.request.urlopen
+
+    def charge(self, url: str, headers: Mapping[str, str]) -> ChargeResult:
+        """One request checked: settled, or the answer to give instead."""
+        key = self.api_key or os.environ.get("USDF_API_KEY")
+        if not key:
+            return _refusal(503, "not_configured", "this API takes USDF, but its key is not set")
+        price = self.price(url, headers) if callable(self.price) else self.price
+        if not isinstance(price, str) or not _PRICE.match(price.strip()):
+            return _refusal(500, "bad_price", "this API's price is not an amount of USDF")
+        payment = _header(headers, "payment-signature") or _header(headers, "x-payment")
+        body: Dict[str, Any] = {
+            "amount": price.strip(),
+            "settle_as": self.settle_as,
+            "resource": {"url": url, "description": self.description, "mime_type": self.mime_type},
+        }
+        if payment:
+            body["payment"] = payment
+        req = urllib.request.Request(
+            self.base_url + "/v1/facilitator/charge",
+            data=json.dumps(body).encode(),
+            method="POST",
+            headers={"authorization": "Bearer " + key, "content-type": "application/json"},
+        )
+        try:
+            with self._open(req, timeout=self.timeout) as r:
+                status, raw, got = r.status, r.read(), {k.lower(): v for k, v in r.headers.items()}
+        except urllib.error.HTTPError as e:
+            status, raw, got = e.code, e.read(), {k.lower(): v for k, v in (e.headers or {}).items()}
+        except (urllib.error.URLError, OSError, ValueError):
+            return _refusal(503, "facilitator_unreachable", "the payment could not be checked just now; nothing was charged, try again")
+        if status == 402:
+            out = {"content-type": "application/json"}
+            for h in ("payment-required", "www-authenticate"):
+                if got.get(h):
+                    out[h] = got[h]
+            return ChargeResult(paid=False, status=402, headers=out, body=raw)
+        if status != 200:
+            code = "payment_unavailable"
+            try:
+                code = str(json.loads(raw.decode() or "{}").get("error", {}).get("code") or code)
+            except (ValueError, AttributeError):
+                pass
+            return _refusal(429 if status == 429 else 503, code, "the payment could not be taken just now; nothing was charged, try again")
+        try:
+            v = json.loads(raw.decode())
+        except ValueError:
+            return _refusal(503, "payment_unavailable", "the payment could not be taken just now; try again")
+        if v.get("paid") is not True or not isinstance(v.get("transaction"), str):
+            return _refusal(503, "payment_unavailable", "the payment could not be taken just now; try again")
+        response = v.get("payment_response") or got.get("payment-response")
+        s = v.get("settlement") or {}
+
+        def usdf(x: Any) -> str:
+            return str((x or {}).get("usdf", ""))
+
+        return ChargeResult(
+            paid=True,
+            headers={"payment-response": response, "x-payment-response": response} if response else {},
+            payment=Accepted(
+                transaction=v["transaction"],
+                payer=str(v.get("payer", "")),
+                network=str(v.get("network", "")),
+                amount=usdf(s.get("amount")),
+                fee=usdf(s.get("fee")),
+                paid_on=usdf(s.get("paid_on")),
+                settle_as="usdg" if s.get("settle_as") == "usdg" else "usdf",
+                settlement_id=str(s.get("id", "")),
+            ),
+        )
+
+    def wsgi(self, app: Callable[..., Iterable[bytes]]) -> Callable[..., Iterable[bytes]]:
+        """A WSGI app that charges every request before `app` runs it (the payment in environ["usdf.payment"])."""
+
+        def wrapped(environ: Dict[str, Any], start_response: Callable[..., Any]) -> Iterable[bytes]:
+            headers = {k[5:].replace("_", "-").lower(): v for k, v in environ.items() if k.startswith("HTTP_")}
+            scheme = environ.get("HTTP_X_FORWARDED_PROTO", environ.get("wsgi.url_scheme", "https")).split(",")[0].strip()
+            host = environ.get("HTTP_X_FORWARDED_HOST") or environ.get("HTTP_HOST") or environ.get("SERVER_NAME", "localhost")
+            path = environ.get("PATH_INFO", "/") + (("?" + environ["QUERY_STRING"]) if environ.get("QUERY_STRING") else "")
+            result = self.charge(f"{'http' if scheme == 'http' else 'https'}://{host}{path}", headers)
+            if not result.paid:
+                reason = {402: "Payment Required", 429: "Too Many Requests", 500: "Internal Server Error"}.get(result.status, "Service Unavailable")
+                start_response(f"{result.status} {reason}", list(result.headers.items()))
+                return [result.body]
+            environ["usdf.payment"] = result.payment
+
+            def start(status: str, response_headers: list, exc_info: Any = None) -> Any:
+                return start_response(status, list(response_headers) + list(result.headers.items()), exc_info) if exc_info else start_response(status, list(response_headers) + list(result.headers.items()))
+
+            return app(environ, start)
+
+        return wrapped