usdf 0.1.2__py3-none-any.whl

usdf/errors.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+
+# What to do about a refusal only the person can clear, by its code (appended to str(), and ``hint``).
+ERROR_HINTS = {
+    "reauth_required": "this needs a session signed in within the last few minutes (max_age_seconds in the body): confirm it's you on the site, or sign in again and use the new session token; API keys are never asked",
+    "recent_link_hold": "a sign-in method was added to this account in the last 24 hours: money leaves it from lifts_at in the body, or once you confirm it's you on the site with a method it had before",
+}
+
+
+class USDFError(Exception):
+    """The gateway's error envelope ({"error": {"message", "type", "code"}}) with its HTTP status.
+
+    ``retry_after`` is the Retry-After header in seconds when the gateway sent one (rate limits,
+    payment back-off); ``request_id`` the x-request-id header where there is one.
+    """
+
+    def __init__(self, status: int, message: str, type: str = "error", code: Optional[str] = None, *, request_id: Optional[str] = None, retry_after: Optional[int] = None, body: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.message = message
+        self.type = type
+        self.code = code
+        self.request_id = request_id
+        self.retry_after = retry_after
+        self.body = body
+        self.hint = ERROR_HINTS.get(code) if code else None
+
+    def __str__(self) -> str:
+        code = f" {self.code}" if self.code else ""
+        hint = f" ({self.hint})" if self.hint else ""
+        return f"{self.status}{code}: {self.message}{hint}"
+
+    @classmethod
+    def from_response(cls, status: int, body: Any, headers: Optional[Mapping[str, str]] = None) -> "USDFError":
+        headers = headers or {}
+        err = body.get("error") if isinstance(body, dict) else None
+        if isinstance(err, dict):
+            message = err.get("message") if isinstance(err.get("message"), str) else f"gateway answered {status}"
+            type_ = err.get("type") if isinstance(err.get("type"), str) else "error"
+            code = err.get("code") if isinstance(err.get("code"), str) else None
+        else:
+            # The auth service answers {error, error_description} or {msg, error_code}; PostgREST
+            # answers {code, message, details, hint}.
+            message = None
+            code = None
+            if isinstance(body, dict):
+                message = body.get("error_description") or body.get("msg") or body.get("message") or (err if isinstance(err, str) else None)
+                raw_code = body.get("error_code") or body.get("code") or (err if isinstance(err, str) else None)
+                code = str(raw_code) if raw_code else None
+            message = str(message) if message else f"gateway answered {status}"
+            type_ = "auth_error" if isinstance(body, dict) and err is None else "error"
+        retry = headers.get("retry-after")
+        return cls(status, message, type_, code, request_id=headers.get("x-request-id"), retry_after=int(retry) if retry and retry.isdigit() else None, body=body)

usdf/estimate.py

@@ -0,0 +1,123 @@
+"""The gateway's hold arithmetic (gateway/src/pricing.ts), reproduced for client-side estimates.
+
+Costs are whole units (1 unit = $0.000001 = 0.000001 USDF), rounded up. The gateway's own figures
+bind: ``USDF.quote`` asks it, and the receipt reports what was charged.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Iterable, Mapping, Optional
+
+IMAGE_TOKENS = 16_384
+
+
+def _bytes(v: Any) -> int:
+    if isinstance(v, str):
+        return len(v.encode("utf-8"))
+    return len(json.dumps(v if v is not None else "", separators=(",", ":"), ensure_ascii=False).encode("utf-8"))
+
+
+def prompt_shape(messages: Optional[Iterable[Mapping[str, Any]]] = None, prompt: Optional[str] = None, tools: Any = None, response_format: Any = None) -> Dict[str, int]:
+    text_bytes = 0
+    images = 0
+    n = 0
+    for m in messages or []:
+        n += 1
+        text_bytes += _bytes(m.get("role")) + _bytes(m.get("name") or "")
+        c = m.get("content")
+        if isinstance(c, str):
+            text_bytes += _bytes(c)
+        elif isinstance(c, list):
+            for p in c:
+                t = p.get("type") if isinstance(p, dict) else None
+                if t in ("image_url", "input_image", "image"):
+                    images += 1
+                elif t == "text":
+                    text_bytes += _bytes(p.get("text"))
+                else:
+                    text_bytes += _bytes(p)
+        elif c is not None:
+            text_bytes += _bytes(c)
+        if m.get("tool_calls"):
+            text_bytes += _bytes(m["tool_calls"])
+    if prompt is not None:
+        text_bytes += _bytes(prompt)
+    if isinstance(tools, list):
+        text_bytes += _bytes(tools)
+    if response_format is not None:
+        text_bytes += _bytes(response_format)
+    return {"text_bytes": text_bytes, "images": images, "messages": max(n, 1)}
+
+
+_ESTIMATE_KWARGS = {"tools", "response_format", "context"}
+
+
+def _check_kwargs(kw: Dict[str, Any]) -> None:
+    extra = set(kw) - _ESTIMATE_KWARGS
+    if extra:
+        raise TypeError(f"unsupported keyword argument(s): {', '.join(sorted(extra))}")
+
+
+def estimate_prompt_tokens(messages=None, prompt=None, image_tokens: int = IMAGE_TOKENS, context: Optional[int] = None, **kw) -> int:
+    """Prompt tokens the gateway holds for: two bytes per token plus per-image and per-message overhead,
+    capped at ``context`` (the model's context window), as the gateway and the TS SDK both cap it."""
+    _check_kwargs(kw)
+    s = prompt_shape(messages, prompt, kw.get("tools"), kw.get("response_format"))
+    n = -(-s["text_bytes"] // 2) + s["images"] * image_tokens + 8 * s["messages"] + 16
+    return min(n, context) if context else n
+
+
+def max_prompt_tokens(messages=None, prompt=None, image_tokens: int = IMAGE_TOKENS, context: Optional[int] = None, **kw) -> int:
+    """Prompt tokens at one per UTF-8 byte: the bound the x402 quote uses, capped at ``context``."""
+    _check_kwargs(kw)
+    s = prompt_shape(messages, prompt, kw.get("tools"), kw.get("response_format"))
+    n = estimate_prompt_tokens(messages, prompt, image_tokens, **kw) + s["text_bytes"] // 2
+    return min(n, context) if context else n
+
+
+def _per_m(usd_per_m: float) -> int:
+    return int(round(usd_per_m * 1_000_000))
+
+
+def _ceil_div(a: int, b: int) -> int:
+    return -(-a // b)
+
+
+def _rates(price: Mapping[str, Any], prompt_tokens: int):
+    lc = price.get("long_context")
+    p = lc if lc and prompt_tokens > lc["above_prompt_tokens"] else price
+    inp = _per_m(p["input"])
+    cached = inp if p.get("cached_input") is None else _per_m(p["cached_input"])
+    # The public Receipt reports one combined cache_write_tokens (not split 5m/1h): billed at whichever
+    # write rate the sheet publishes (5m, else 1h, else the plain input rate).
+    if p.get("cache_write_5m") is not None:
+        write = _per_m(p["cache_write_5m"])
+    elif p.get("cache_write_1h") is not None:
+        write = _per_m(p["cache_write_1h"])
+    else:
+        write = inp
+    return inp, _per_m(p["output"]), cached, write
+
+
+def max_cost_units(price: Mapping[str, Any], prompt_tokens: int, max_output: int) -> int:
+    """The hold for a prompt of ``prompt_tokens`` and an output budget of ``max_output``."""
+    inp, out, _, _ = _rates(price, prompt_tokens)
+    return _ceil_div(max(0, prompt_tokens) * inp + max(0, max_output) * out, 1_000_000)
+
+
+def cost_units(price: Mapping[str, Any], prompt_tokens: int, completion_tokens: int, cached_tokens: int = 0, cache_write_tokens: int = 0) -> int:
+    """The charge for reported usage."""
+    inp, out, cached_rate, write_rate = _rates(price, prompt_tokens)
+    cached = max(0, cached_tokens)
+    write = max(0, cache_write_tokens)
+    uncached = max(0, max(0, prompt_tokens) - cached - write)
+    return _ceil_div(uncached * inp + cached * cached_rate + write * write_rate + max(0, completion_tokens) * out, 1_000_000)
+
+
+def units(v: int) -> Dict[str, str]:
+    """Units as the gateway renders them: {units, usd, usdf} with six decimals."""
+    neg = v < 0
+    a = -v if neg else v
+    usd = f"{'-' if neg else ''}{a // 1_000_000}.{a % 1_000_000:06d}"
+    return {"units": str(v), "usd": usd, "usdf": usd}

usdf/langchain.py

@@ -0,0 +1,142 @@
+"""LangChain chat model over the USDF gateway: ``USDFChat(model=..., wallet=wallet)`` pays each call over
+x402 with no account; ``USDFChat(model=..., api_key="sk_...")`` (or USDF_API_KEY) charges a prepaid
+balance. ``invoke`` returns an ``AIMessage`` whose ``response_metadata["receipt"]`` is the gateway's
+receipt and whose ``usage_metadata`` holds the token counts. Needs ``langchain-core``
+(``pip install usdf langchain``).
+
+For a plain OpenAI-compatible client in LangChain, ``ChatOpenAI(base_url=".../v1", api_key=...)``
+works as well (docs/agents.md); this class adds the wallet path and the receipt.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Iterator, List, Mapping, Optional, Sequence, Union
+
+from langchain_core.callbacks import CallbackManagerForLLMRun
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.messages import AIMessage, AIMessageChunk, BaseMessage
+from langchain_core.outputs import ChatGeneration, ChatGenerationChunk, ChatResult
+from pydantic import ConfigDict, Field, PrivateAttr, SecretStr
+
+from .client import USDF
+
+try:  # langchain-core 0.3 and later
+    from langchain_core.messages import convert_to_openai_messages
+except ImportError:  # pragma: no cover - older cores
+    convert_to_openai_messages = None  # type: ignore[assignment]
+
+
+def _openai_messages(messages: List[BaseMessage]) -> List[Dict[str, Any]]:
+    if convert_to_openai_messages is not None:
+        return list(convert_to_openai_messages(messages))
+    roles = {"human": "user", "ai": "assistant", "system": "system", "tool": "tool"}
+    out: List[Dict[str, Any]] = []
+    for m in messages:
+        d: Dict[str, Any] = {"role": roles.get(m.type, m.type), "content": m.content}
+        if m.type == "tool":
+            d["tool_call_id"] = getattr(m, "tool_call_id", None)
+        out.append(d)
+    return out
+
+
+def _usage(receipt: Any) -> Optional[Dict[str, int]]:
+    u = getattr(receipt, "usage", None)
+    if u is None:
+        return None
+    return {"input_tokens": u.prompt_tokens, "output_tokens": u.completion_tokens, "total_tokens": u.prompt_tokens + u.completion_tokens}
+
+
+class USDFChat(BaseChatModel):
+    """A chat model on the USDF gateway, paid from a wallet (x402) or a prepaid key."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True, populate_by_name=True)
+
+    model: str
+    # An eth-account account (``Account.from_key(...)``) or a private key: pays each call over x402. Kept
+    # out of repr, model_dump and the serialized form LangChain hands to callbacks and tracers.
+    wallet: Any = Field(default=None, repr=False, exclude=True)
+    # An API key (sk_...): charges the prepaid balance. Unset, USDF_API_KEY is read unless a wallet is
+    # given. A secret: masked in repr, left out of model_dump, named in lc_secrets.
+    api_key: Optional[SecretStr] = Field(default=None, repr=False, exclude=True)
+    # Gateway origin without /v1; unset, USDF_BASE_URL, else the production gateway.
+    base_url: Optional[str] = None
+    max_tokens: Optional[int] = None
+    temperature: Optional[float] = None
+    # Privacy and routing asks, sent as the request's `provider` field.
+    provider: Optional[Dict[str, Any]] = None
+    # x402: "USDF" or "USDG" (default: USDF when its Permit2 allowance covers the amount, else USDG),
+    # the one-time Permit2 approval, and where to read the allowance.
+    asset: Optional[str] = None
+    approve: bool = False
+    rpc_url: Optional[str] = None
+    # x402: the cap on one payment in base units (default USDF_MAX_AMOUNT, else 1 USDF) and the payee the
+    # gateway must name (default USDF_PAY_TO, else the gateway's hot wallet).
+    max_amount: Optional[int] = None
+    pay_to: Optional[Union[str, Sequence[str]]] = None
+
+    _client: Optional[USDF] = PrivateAttr(default=None)
+
+    @property
+    def lc_secrets(self) -> Dict[str, str]:
+        return {"api_key": "USDF_API_KEY"}
+
+    @property
+    def client(self) -> USDF:
+        if self._client is None:
+            key = self.api_key.get_secret_value() if self.api_key is not None else None
+            self._client = USDF(api_key=key, wallet=self.wallet, base_url=self.base_url, asset=self.asset, approve=self.approve, rpc_url=self.rpc_url, max_amount=self.max_amount, pay_to=self.pay_to)
+        return self._client
+
+    @property
+    def _llm_type(self) -> str:
+        return "usdf"
+
+    @property
+    def _identifying_params(self) -> Dict[str, Any]:
+        return {"model": self.model, "base_url": self.client.base_url, "pays_with": self.client.pays_with}
+
+    def _params(self, stop: Optional[List[str]], kwargs: Mapping[str, Any]) -> Dict[str, Any]:
+        p: Dict[str, Any] = {}
+        if self.max_tokens is not None:
+            p["max_tokens"] = self.max_tokens
+        if self.temperature is not None:
+            p["temperature"] = self.temperature
+        if self.provider is not None:
+            p["provider"] = self.provider
+        if stop:
+            p["stop"] = stop
+        p.update({k: v for k, v in kwargs.items() if v is not None})
+        return p
+
+    def _generate(self, messages: List[BaseMessage], stop: Optional[List[str]] = None, run_manager: Optional[CallbackManagerForLLMRun] = None, **kwargs: Any) -> ChatResult:
+        r = self.client.run(self.model, _openai_messages(messages), **self._params(stop, kwargs))
+        receipt = getattr(r.receipt, "raw", r.receipt)
+        message = AIMessage(
+            content=r.text,
+            id=r.id,
+            response_metadata={"id": r.id, "model_name": getattr(r.receipt, "model", self.model), "receipt": receipt, **({"payment": r.payment} if r.payment else {})},
+            usage_metadata=_usage(r.receipt),  # type: ignore[arg-type]
+        )
+        return ChatResult(generations=[ChatGeneration(message=message)], llm_output={"id": r.id, "receipt": receipt})
+
+    def _stream(self, messages: List[BaseMessage], stop: Optional[List[str]] = None, run_manager: Optional[CallbackManagerForLLMRun] = None, **kwargs: Any) -> Iterator[ChatGenerationChunk]:
+        c = self.client
+        params = self._params(stop, kwargs)
+        msgs = _openai_messages(messages)
+        if c.api_key:
+            s = c.chat.completions.create(self.model, msgs, stream=True, **params)
+        else:
+            s = c.x402.chat.completions.create(self.model, msgs, stream=True, **c._pay_kwargs(), **params)
+        for chunk in s:  # type: ignore[union-attr]
+            for ch in chunk.get("choices") or []:
+                d = (ch.get("delta") or {}).get("content")
+                if isinstance(d, str) and d:
+                    out = ChatGenerationChunk(message=AIMessageChunk(content=d, id=s.request_id))  # type: ignore[union-attr]
+                    if run_manager:
+                        run_manager.on_llm_new_token(d, chunk=out)
+                    yield out
+        receipt = s.receipt  # type: ignore[union-attr]
+        yield ChatGenerationChunk(message=AIMessageChunk(content="", id=s.request_id, response_metadata={"id": s.request_id, "receipt": getattr(receipt, "raw", receipt)}, usage_metadata=_usage(receipt)))  # type: ignore[union-attr,arg-type]
+
+
+__all__ = ["USDFChat"]

usdf/sse.py

@@ -0,0 +1,49 @@
+"""Server-sent events as the gateway writes them: ``data:`` payloads and comment lines (``: receipt
+{...}``), which carry the receipt of a stream and are dropped by every standard client."""
+
+from __future__ import annotations
+
+from typing import Iterable, Iterator, Tuple
+
+Event = Tuple[str, str]  # ("data", payload) or ("comment", text)
+
+
+def read_sse(chunks: Iterable[bytes]) -> Iterator[Event]:
+    buf = b""
+    data: list = []
+    for chunk in chunks:
+        buf += chunk
+        while True:
+            nl = buf.find(b"\n")
+            if nl < 0:
+                break
+            line = buf[:nl]
+            buf = buf[nl + 1 :]
+            ev = _line(line, data)
+            if ev is not None:
+                yield ev
+    if buf:
+        ev = _line(buf, data)
+        if ev is not None:
+            yield ev
+    if data:
+        yield ("data", "\n".join(data))
+
+
+def _line(raw: bytes, data: list):
+    if raw.endswith(b"\r"):
+        raw = raw[:-1]
+    if raw == b"":
+        if not data:
+            return None
+        payload = "\n".join(data)
+        data.clear()
+        return ("data", payload)
+    text = raw.decode("utf-8", errors="replace")
+    if text.startswith(":"):
+        t = text[1:]
+        return ("comment", t[1:] if t.startswith(" ") else t)
+    if text.startswith("data:"):
+        v = text[5:]
+        data.append(v[1:] if v.startswith(" ") else v)
+    return None