oneshot-python 0.18.0__tar.gz → 0.20.2__tar.gz

{oneshot_python-0.18.0 → oneshot_python-0.20.2}/.gitignore

@@ -90,3 +90,6 @@ output/
 
 # Claude Code agent metadata (lockfile + local settings)
 .claude/
+
+# generated by scripts/deploy-blog-generator.sh
+scripts/humanizer.vendored.ts

{oneshot_python-0.18.0 → oneshot_python-0.20.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oneshot-python
-Version: 0.18.0
+Version: 0.20.2
 Summary: Core Python SDK for the OneShot API — HTTP client with x402 payment handling
 License-Expression: MIT
 Requires-Python: >=3.10

{oneshot_python-0.18.0 → oneshot_python-0.20.2}/README.md

@@ -66,6 +66,43 @@ Read endpoints (inbox, SMS inbox, notifications, balance, browser profiles) retu
 
 This is automatic — no extra code beyond `private_key`. **Requires `oneshot-python >= 0.17.0`.** Older versions keep working until the API enables enforcement, after which they must send a valid `x-agent-proof`.
 
+## Spend Budgets
+
+Cap what the agent can spend so a runaway loop can't drain the wallet overnight:
+
+```python
+client = OneShotClient(
+    "0x...",
+    budgets={
+        "daily": 50,            # max USDC per UTC day
+        "per_transaction": 5,   # max USDC for any single call
+        "alert_at": 0.8,        # warn at 80% of daily
+        "pause_at": 1.0,        # stop paying at 100%
+    },
+    alert_email="you@example.com",
+)
+```
+
+Unlike `max_cost` (a per-call client-side check), budgets are **enforced server-side** against your receipt ledger. The config is synced once before your first paid call, so the daily figure is a true per-agent total — shared across every process and restart using the same wallet.
+
+At `alert_at` you get a `budget_warning` notification (in-app via `/v1/tools/notifications`, plus email if set). At `pause_at` paid calls raise `BudgetExceededError` until the window resets at the next UTC midnight:
+
+```python
+from oneshot import BudgetExceededError
+
+try:
+    client.research(topic="...")
+except BudgetExceededError as e:
+    print(f"{e.reason} budget hit — ${e.spent} spent, resumes {e.resets_at}")
+
+client.get_budgets()
+# {"daily_usdc": 50, "spent_today_usdc": "41.20", "pct_used": 0.824, "resets_at": "..."}
+```
+
+Omit `budgets` to leave whatever is stored server-side untouched — agents without a budget are unlimited. **Requires `oneshot-python >= 0.20.0`.**
+
+The sync **fails closed**: if the budget can't be confirmed with the server, the paid call raises `BudgetSyncError` and is not made (retried on the next call). An invalid config (`daily=-1`, `alert_at=2`) raises `ValidationError` at construction.
+
 ## Configuration
 
 ```python

{oneshot_python-0.18.0 → oneshot_python-0.20.2}/oneshot/__init__.py

@@ -1,15 +1,20 @@
 """oneshot-python — Core Python SDK for the OneShot API."""
 
 from oneshot._errors import (
+    BudgetExceededError,
+    BudgetSyncError,
     ContentBlockedError,
     EmergencyNumberError,
     JobError,
     JobTimeoutError,
     OneShotError,
+    PaymentError,
     ToolError,
     ValidationError,
 )
 from oneshot._types import (
+    AgentBudgetConfig,
+    AgentBudgetStatus,
     ComputeBudgetStatus,
     ComputeCancelResult,
     ComputeFundResult,
@@ -32,12 +37,17 @@ __all__ = [
     "OneShotClient",
     "OneShotError",
     "ToolError",
+    "PaymentError",
+    "BudgetExceededError",
+    "BudgetSyncError",
     "JobError",
     "JobTimeoutError",
     "ValidationError",
     "ContentBlockedError",
     "EmergencyNumberError",
     "sign_payment_authorization",
+    "AgentBudgetConfig",
+    "AgentBudgetStatus",
     "ComputeSchedule",
     "ComputeGoalResult",
     "ComputeGoalStatus",

oneshot_python-0.20.2/oneshot/_errors.py

@@ -0,0 +1,129 @@
+"""Error classes mirroring the TypeScript OneShot SDK error hierarchy."""
+
+
+class OneShotError(Exception):
+    """Base error for all OneShot operations."""
+
+
+class ToolError(OneShotError):
+    """HTTP-level error from the OneShot API."""
+
+    def __init__(self, message: str, status_code: int, response_body: str) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_body = response_body
+
+
+class PaymentError(OneShotError):
+    """The facilitator rejected the payment signed for this request.
+
+    Distinct from the ordinary 402 that opens the quote-pay handshake: this is a
+    402 arriving on the PAID retry, meaning the signature was refused.
+    ``reason`` is the facilitator's machine-readable code
+    (``insufficient_funds``, ``invalid_exact_evm_payload_authorization_value``,
+    …) and ``expected`` / ``received`` name the amounts when the two disagree —
+    the case that produced a silent, bodiless 402 before the server started
+    reporting it.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        reason: str,
+        expected: dict | None = None,
+        received: dict | None = None,
+        quote_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.reason = reason
+        self.expected = expected or {}
+        self.received = received or {}
+        self.quote_id = quote_id
+
+
+class JobError(OneShotError):
+    """Async job completed with an error."""
+
+    def __init__(self, message: str, job_id: str, job_error: str) -> None:
+        super().__init__(message)
+        self.job_id = job_id
+        self.job_error = job_error
+
+
+class JobTimeoutError(OneShotError):
+    """Async job exceeded the polling timeout."""
+
+    def __init__(self, job_id: str, elapsed_ms: int) -> None:
+        super().__init__(f"Job {job_id} timed out after {elapsed_ms / 1000}s")
+        self.job_id = job_id
+        self.elapsed_ms = elapsed_ms
+
+
+class ValidationError(OneShotError):
+    """Client-side input validation failure."""
+
+    def __init__(self, message: str, field: str) -> None:
+        super().__init__(message)
+        self.field = field
+
+
+class ContentBlockedError(OneShotError):
+    """Content safety filter rejected the request."""
+
+    def __init__(self, message: str, categories: list[str]) -> None:
+        super().__init__(message)
+        self.categories = categories
+
+
+class EmergencyNumberError(OneShotError):
+    """Voice call rejected because the target number is an emergency line."""
+
+    def __init__(self, message: str, blocked_number: str) -> None:
+        super().__init__(message)
+        self.blocked_number = blocked_number
+
+
+class BudgetExceededError(OneShotError):
+    """The agent's own spend budget stopped this call (HTTP 403 ``budget_exceeded``).
+
+    Distinct from :class:`PaymentError`: nothing was signed and nothing was
+    charged. A retry cannot succeed until the daily window resets
+    (``resets_at``) or the budget is raised — which is why the server answers
+    403 rather than 402. ``reason`` is ``"daily"`` when cumulative UTC-day
+    spend would cross the budget, or ``"per_transaction"`` when this single
+    call is larger than the per-call cap.
+
+    Mirrors ``BudgetExceededError`` in ``libs/agent-sdk/src/errors.ts``.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        reason: str,
+        cap: float | None = None,
+        spent: float | None = None,
+        charge: float | None = None,
+        resets_at: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.reason = reason
+        self.cap = cap
+        self.spent = spent
+        self.charge = charge
+        self.resets_at = resets_at
+
+
+class BudgetSyncError(OneShotError):
+    """The configured spend budget could not be confirmed with the server, so
+    the paid call was NOT made.
+
+    Budgets are enforced server-side; if the sync fails (network error, 5xx,
+    rate limit, rejected config) proceeding would silently drop the guardrail
+    the developer configured. The sync is retried on the next paid call.
+    ``status`` is the HTTP status when the server answered, else None.
+    """
+
+    def __init__(self, message: str, status: int | None = None, body: str | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body

{oneshot_python-0.18.0 → oneshot_python-0.20.2}/oneshot/_types.py

@@ -181,6 +181,12 @@ class DomainPoolEntry(TypedDict, total=False):
 
     domain: str
     default_from: str
+    # 'mailbox' = a real mailbox is provisioned per address, so every address not
+    # already active in addresses[] bills the one-time mailbox_provisioning_fee on
+    # its first send — the canonical default_from included. 'relay' = header-only,
+    # no per-address fee. A property of the DOMAIN, fixed at setup: omitting
+    # mailbox_mode on a quote does not make the send relay.
+    mailbox_mode: str  # relay | mailbox
     addresses: list[DomainAddressEntry]
     pool_status: str  # active | paused | removed
     warmup_state: str  # warming | warmed | degraded
@@ -227,3 +233,37 @@ __all__ = [
     "DomainPoolListResult",
     "DomainPoolStatusResult",
 ]
+
+
+# ── Agent spend budgets ──────────────────────────────────────────────────
+
+
+class AgentBudgetConfig(TypedDict, total=False):
+    """Spend budget passed to ``OneShotClient(budgets=...)``.
+
+    Mirrors ``AgentBudgetConfig`` in TS (snake_case here; camelCase keys are
+    accepted too and normalised). Synced to the server once, before the first
+    paid call, and enforced there against the receipt ledger.
+    """
+
+    daily: float
+    """Max USDC per UTC day."""
+    per_transaction: float
+    """Max USDC for any single call."""
+    alert_at: float
+    """Fraction of ``daily`` that triggers a ``budget_warning`` (default 0.8)."""
+    pause_at: float
+    """Fraction of ``daily`` at which paid calls stop (default 1.0)."""
+
+
+class AgentBudgetStatus(TypedDict):
+    """Live utilization from ``GET /v1/agents/me/budgets``. Mirrors ``AgentBudgetStatus`` in TS."""
+
+    daily_usdc: Optional[float]
+    per_transaction_usdc: Optional[float]
+    alert_at: Optional[float]
+    pause_at: Optional[float]
+    spent_today_usdc: str
+    remaining_usdc: Optional[str]
+    pct_used: Optional[float]
+    resets_at: str