usdf 0.1.2__py3-none-any.whl

usdf/types.py

@@ -0,0 +1,407 @@
+"""Shapes of the gateway's responses, from the gateway's own handlers (gateway/src/proxy.ts, public.ts,
+mcp.ts, account.ts, keys.ts, x402.ts). Each dataclass keeps the full response in ``raw`` so a field the
+SDK does not model is still there. Money is carried as strings: ``units`` are whole base units
+(1 unit = $0.000001 = 0.000001 USDF); ``usd`` and ``usdf`` are the same decimal figure."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class Amount:
+    units: str
+    usd: str
+    usdf: str
+
+    @classmethod
+    def of(cls, d: Optional[Dict[str, Any]]) -> Optional["Amount"]:
+        if not isinstance(d, dict):
+            return None
+        return cls(str(d.get("units")), str(d.get("usd")), str(d.get("usdf")))
+
+    @property
+    def as_int(self) -> int:
+        return int(self.units)
+
+
+@dataclass
+class Usage:
+    prompt_tokens: int
+    completion_tokens: int
+    cached_tokens: int = 0
+    cache_write_tokens: int = 0
+
+    @classmethod
+    def of(cls, d: Optional[Dict[str, Any]]) -> "Usage":
+        d = d or {}
+        return cls(int(d.get("prompt_tokens") or 0), int(d.get("completion_tokens") or 0), int(d.get("cached_tokens") or 0), int(d.get("cache_write_tokens") or 0))
+
+
+@dataclass
+class Receipt:
+    """The receipt attached to every keyed completion (JSON body, or the stream's last comment line)."""
+
+    request_id: str
+    model: str
+    provider: str
+    status: str  # "ok" | "partial"
+    usage: Usage
+    price_version: str
+    cost: Amount
+    balance: Optional[Amount]  # None when the ledger had not confirmed the charge when the response went out
+    settlement_status: str
+    note: Optional[str]
+    # What the serving route does with content and what the request asked for; on attested hardware it
+    # also carries ``attestation`` (pending, then verified or failed on the lookup) and ``attestation_lookup``.
+    data_policy: Optional[Dict[str, Any]] = None
+    # A request that failed after its hold was taken: status "failed_refunded", why, and what went back.
+    reason: Optional[str] = None
+    refunded: Optional[Amount] = None
+    batch: bool = False
+    raw: Dict[str, Any] = field(repr=False, default_factory=dict)
+
+    @property
+    def attestation(self) -> Optional[str]:
+        return (self.data_policy or {}).get("attestation")
+
+    @classmethod
+    def of(cls, d: Dict[str, Any]) -> "Receipt":
+        price = d.get("price") or {}
+        return cls(
+            request_id=str(d.get("request_id")),
+            model=str(d.get("model")),
+            provider=str(d.get("provider")),
+            status=str(d.get("status")),
+            usage=Usage.of(d.get("usage")),
+            price_version=str(price.get("version")),
+            cost=Amount.of(d.get("cost")) or Amount("0", "0.000000", "0.000000"),
+            balance=Amount.of(d.get("balance")),
+            settlement_status=str((d.get("settlement") or {}).get("status")),
+            note=d.get("note"),
+            data_policy=d.get("data_policy"),
+            reason=d.get("reason"),
+            refunded=Amount.of(d.get("refunded")),
+            batch=d.get("batch") is True,
+            raw=d,
+        )
+
+
+@dataclass
+class X402Receipt:
+    """An x402 receipt: ``paid`` is what the request was charged, its metered cost at the quoted price and
+    never more than the payment (``raw["payment"]["amount"]``); the rest of the payment is refunded to the
+    payer (``raw["refund"]``). ``usage_cost`` is what the usage came to at that price."""
+
+    request_id: str
+    model: str
+    provider: str
+    status: str
+    usage: Usage
+    price_version: str
+    paid: Amount
+    usage_cost: Amount
+    payment_tx: str
+    payer: str
+    asset: str  # "USDF" | "USDG"
+    method: str  # "permit2" | "eip3009"
+    raw: Dict[str, Any] = field(repr=False, default_factory=dict)
+
+    @classmethod
+    def of(cls, d: Dict[str, Any]) -> "X402Receipt":
+        payment = d.get("payment") or {}
+        return cls(
+            request_id=str(d.get("request_id")),
+            model=str(d.get("model")),
+            provider=str(d.get("provider")),
+            status=str(d.get("status")),
+            usage=Usage.of(d.get("usage")),
+            price_version=str((d.get("price") or {}).get("version")),
+            paid=Amount.of(d.get("paid")) or Amount("0", "0.000000", "0.000000"),
+            usage_cost=Amount.of(d.get("usage_cost")) or Amount("0", "0.000000", "0.000000"),
+            payment_tx=str(payment.get("tx")),
+            payer=str(payment.get("payer")),
+            asset=str(payment.get("asset")),
+            method=str(payment.get("method")),
+            raw=d,
+        )
+
+
+@dataclass
+class ChatCompletion:
+    """A completion in the OpenAI shape, with the gateway's receipt. ``raw`` is the whole body."""
+
+    id: str
+    model: str
+    content: Optional[str]
+    finish_reason: Optional[str]
+    tool_calls: Optional[List[Dict[str, Any]]]
+    usage: Optional[Dict[str, Any]]
+    receipt: Any  # Receipt, or X402Receipt for an x402 completion
+    raw: Dict[str, Any] = field(repr=False, default_factory=dict)
+
+    @classmethod
+    def of(cls, d: Dict[str, Any], x402: bool = False) -> "ChatCompletion":
+        choices = d.get("choices") or []
+        msg = (choices[0].get("message") if choices and isinstance(choices[0], dict) else None) or {}
+        receipt = d.get("receipt")
+        return cls(
+            id=str(d.get("id")),
+            model=str(d.get("model")),
+            content=msg.get("content"),
+            finish_reason=choices[0].get("finish_reason") if choices else None,
+            tool_calls=msg.get("tool_calls"),
+            usage=d.get("usage"),
+            receipt=(X402Receipt.of(receipt) if x402 else Receipt.of(receipt)) if isinstance(receipt, dict) else None,
+            raw=d,
+        )
+
+
+@dataclass
+class ReceiptLookup:
+    """GET /v1/receipts/{id}: the charge and, once settled, the batch, its transaction and the rows URL."""
+
+    request_id: str
+    model: str
+    provider: str
+    status: str
+    created_at: str
+    usage: Usage
+    price_version: str
+    cost: Amount
+    settlement_status: str
+    settlement_batch: Optional[str]
+    settlement_tx: Optional[str]
+    settlement_explorer: Optional[str]
+    settlement_rows: Optional[str]
+    # The request's leaf in the usage log (status, leaf_index, tree_size, anchored_by, proof).
+    log: Optional[Dict[str, Any]] = None
+    # Served on attested hardware: pending, verified or failed, the provider's receipt id, where to read it.
+    attestation: Optional[str] = None
+    attestation_receipt: Optional[str] = None
+    attestation_lookup: Optional[str] = None
+    reason: Optional[str] = None
+    refunded: Optional[Amount] = None
+    raw: Dict[str, Any] = field(repr=False, default_factory=dict)
+
+    @classmethod
+    def of(cls, d: Dict[str, Any]) -> "ReceiptLookup":
+        s = d.get("settlement") or {}
+        return cls(
+            request_id=str(d.get("request_id")),
+            model=str(d.get("model")),
+            provider=str(d.get("provider")),
+            status=str(d.get("status")),
+            created_at=str(d.get("created_at")),
+            usage=Usage.of(d.get("usage")),
+            price_version=str(d.get("price_version")),
+            cost=Amount.of(d.get("cost")) or Amount("0", "0.000000", "0.000000"),
+            settlement_status=str(s.get("status")),
+            settlement_batch=s.get("batch"),
+            settlement_tx=s.get("tx_hash"),
+            settlement_explorer=s.get("explorer"),
+            settlement_rows=s.get("rows"),
+            log=d.get("log"),
+            attestation=d.get("attestation"),
+            attestation_receipt=d.get("attestation_receipt"),
+            attestation_lookup=d.get("attestation_lookup"),
+            reason=d.get("reason"),
+            refunded=Amount.of(d.get("refunded")),
+            raw=d,
+        )
+
+
+@dataclass
+class Model:
+    id: str
+    name: str
+    owned_by: str
+    context_length: int
+    max_output_tokens: int
+    endpoints: List[str]
+    raw: Dict[str, Any] = field(repr=False, default_factory=dict)
+
+    @classmethod
+    def of(cls, d: Dict[str, Any]) -> "Model":
+        return cls(str(d.get("id")), str(d.get("name")), str(d.get("owned_by")), int(d.get("context_length") or 0), int(d.get("max_output_tokens") or 0), list(d.get("endpoints") or []), d)
+
+
+@dataclass
+class PricingModel:
+    id: str
+    name: str
+    owned_by: str
+    context: int
+    max_output: int
+    endpoints: List[str]
+    pricing: str  # "list" | "passthrough": every model at a list price ("markup" only on sheets before 2026-10-10)
+    price: Dict[str, Any]  # USD per 1M tokens: input, output, cached_input?, long_context?
+    available: bool
+    routes: List[Dict[str, Any]]
+    raw: Dict[str, Any] = field(repr=False, default_factory=dict)
+
+    @classmethod
+    def of(cls, d: Dict[str, Any]) -> "PricingModel":
+        return cls(str(d.get("id")), str(d.get("name")), str(d.get("owned_by")), int(d.get("context") or 0), int(d.get("max_output") or 0), list(d.get("endpoints") or []), str(d.get("pricing")), dict(d.get("price") or {}), bool(d.get("available")), list(d.get("routes") or []), d)
+
+
+@dataclass
+class Pricing:
+    version: str
+    unit: str
+    markup: str
+    sheet_sha256: str
+    models: List[PricingModel]
+    raw: Dict[str, Any] = field(repr=False, default_factory=dict)
+
+    @classmethod
+    def of(cls, d: Dict[str, Any]) -> "Pricing":
+        return cls(str(d.get("version")), str(d.get("unit")), str(d.get("markup")), str(d.get("sheet_sha256")), [PricingModel.of(m) for m in d.get("models") or []], d)
+
+    def model(self, model_id: str) -> Optional[PricingModel]:
+        base = model_id.split(":")[0]
+        return next((m for m in self.models if m.id == base), None)
+
+
+@dataclass
+class Quote:
+    """The hold the gateway places for a request (MCP ``quote``), and the x402 amount for the same request."""
+
+    model: str
+    price_version: str
+    max_tokens: int
+    prompt_tokens_held: int
+    max_cost: Amount
+    price: Dict[str, Any]
+    note: str
+    x402_amount: Optional[Amount]
+    raw: Dict[str, Any] = field(repr=False, default_factory=dict)
+
+    @classmethod
+    def of(cls, d: Dict[str, Any]) -> "Quote":
+        x = d.get("x402") or {}
+        return cls(str(d.get("model")), str(d.get("price_version")), int(d.get("max_tokens") or 0), int(d.get("prompt_tokens_held") or 0), Amount.of(d.get("max_cost")) or Amount("0", "0.000000", "0.000000"), dict(d.get("price") or {}), str(d.get("note") or ""), Amount.of(x.get("amount")), d)
+
+
+@dataclass
+class Balance:
+    """MCP ``balance``: what the key can spend, the account's balance and holds, the key's budget."""
+
+    available: Amount
+    balance: Optional[Amount]
+    held: Optional[Amount]
+    key_id: str
+    key_budget: Optional[Amount]
+    key_spent: Optional[Amount]
+    key_budget_left: Optional[Amount]
+    rate_limit_rpm: int
+    note: Optional[str]
+    raw: Dict[str, Any] = field(repr=False, default_factory=dict)
+
+    @classmethod
+    def of(cls, d: Dict[str, Any]) -> "Balance":
+        k = d.get("key") or {}
+        return cls(Amount.of(d.get("available")) or Amount("0", "0.000000", "0.000000"), Amount.of(d.get("balance")), Amount.of(d.get("held")), str(k.get("id")), Amount.of(k.get("budget")), Amount.of(k.get("spent")), Amount.of(k.get("budget_left")), int(d.get("rate_limit_rpm") or 0), d.get("note"), d)
+
+
+@dataclass
+class Account:
+    """GET /v1/account: balance, held, linked wallet, pending withdrawals and the deposit address."""
+
+    id: str
+    wallet_address: Optional[str]
+    balance_units: int
+    held_units: int
+    pending_withdrawals: int
+    pending_withdrawal_units: int
+    deposit_to: str
+    deposit_token: str
+    chain_id: int
+    raw: Dict[str, Any] = field(repr=False, default_factory=dict)
+
+    @property
+    def available_units(self) -> int:
+        return self.balance_units - self.held_units
+
+    @classmethod
+    def of(cls, d: Dict[str, Any]) -> "Account":
+        a = d.get("account") or {}
+        w = d.get("withdrawals") or {}
+        dep = d.get("deposit") or {}
+        return cls(str(a.get("id")), a.get("wallet_address"), int(a.get("balance_units") or 0), int(a.get("held_units") or 0), int(w.get("pending_count") or 0), int(w.get("pending_units") or 0), str(dep.get("to")), str(dep.get("token")), int(dep.get("chain_id") or 0), d)
+
+
+@dataclass
+class Session:
+    access_token: str
+    refresh_token: Optional[str]
+    expires_in: int
+    user_id: Optional[str]
+    email: Optional[str]
+    raw: Dict[str, Any] = field(repr=False, default_factory=dict)
+
+    @classmethod
+    def of(cls, d: Dict[str, Any]) -> "Session":
+        u = d.get("user") or {}
+        return cls(str(d.get("access_token")), d.get("refresh_token"), int(d.get("expires_in") or 0), u.get("id"), u.get("email"), d)
+
+
+@dataclass
+class CreatedKey:
+    key_id: str
+    api_key: str  # shown once; the ledger keeps only its hash
+    prefix: str
+
+
+@dataclass
+class ApiKey:
+    id: str
+    key_prefix: str
+    label: Optional[str]
+    budget_units: Optional[int]
+    spent_units: int
+    rate_limit_rpm: int
+    created_at: str
+    last_used_at: Optional[str]
+    revoked_at: Optional[str]
+    raw: Dict[str, Any] = field(repr=False, default_factory=dict)
+
+    @classmethod
+    def of(cls, d: Dict[str, Any]) -> "ApiKey":
+        b = d.get("budget_units")
+        return cls(str(d.get("id")), str(d.get("key_prefix")), d.get("label"), None if b is None else int(b), int(d.get("spent_units") or 0), int(d.get("rate_limit_rpm") or 0), str(d.get("created_at")), d.get("last_used_at"), d.get("revoked_at"), d)
+
+
+@dataclass
+class KeyLimits:
+    """GET /v1/keys/{id}/limits: trailing-window spend, caps, pause state, privacy flags, webhook."""
+
+    key_id: str
+    label: Optional[str]
+    hour_spent_units: int
+    hour_limit_units: Optional[int]
+    day_spent_units: int
+    day_limit_units: Optional[int]
+    month_spent_units: int
+    month_limit_units: Optional[int]
+    paused: bool
+    pause_reason: Optional[str]
+    auto_resume: Optional[bool]
+    no_logs: bool
+    private_tier: bool
+    webhook_url: Optional[str]
+    updated: List[str]
+    raw: Dict[str, Any] = field(repr=False, default_factory=dict)
+
+    @classmethod
+    def of(cls, d: Dict[str, Any]) -> "KeyLimits":
+        spend = d.get("spend") or {}
+        h = spend.get("hour") or {}
+        day = spend.get("day") or {}
+        # Pre-migration ledgers (gateway/src/keys.ts): the gateway sends spend.month as null.
+        month = spend.get("month") or {}
+        p = d.get("paused") or {}
+        priv = d.get("privacy") or {}
+        lim = lambda v: None if v is None else int(v)  # noqa: E731
+        return cls(str(d.get("key_id")), d.get("label"), int(h.get("spent_units") or 0), lim(h.get("limit_units")), int(day.get("spent_units") or 0), lim(day.get("limit_units")), int(month.get("spent_units") or 0), lim(month.get("limit_units")), bool(p.get("state")), p.get("reason"), p.get("auto_resume"), bool(priv.get("no_logs")), bool(priv.get("private_tier")), (d.get("webhook") or {}).get("url"), list(d.get("updated") or []), d)