oneshot-python 0.19.0__tar.gz → 0.23.1__tar.gz

{oneshot_python-0.19.0 → oneshot_python-0.23.1}/.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.19.0 → oneshot_python-0.23.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: oneshot-python
-Version: 0.19.0
-Summary: Core Python SDK for the OneShot API — HTTP client with x402 payment handling
+Version: 0.23.1
+Summary: Core Python SDK for the OneShot API — HTTP client with x402 payment handling — 35 tools
 License-Expression: MIT
 Requires-Python: >=3.10
 Requires-Dist: eth-account>=0.13.0

{oneshot_python-0.19.0 → oneshot_python-0.23.1}/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
@@ -164,3 +201,7 @@ Every method has an `a*` async mirror (`acompute`, `aget_compute_goal`, …).
 ## License
 
 MIT
+
+### Physical mail
+
+`client.physical_mail` supports U.S. letters and 4×6 postcards through `upload_artwork`, `validate_address`, `preview`, `get_quote`, `approve`, `send`, `get_order`, `recover`, and `cancel`. Async variants prefix the method with `a`. Review each proof and price, then call `approve(..., approved=True)` explicitly. Persist `idempotency_key` before sending. `recover(key)` retrieves the original order without creating another charge. Postal delivery does not prove readership; paid receipts and fulfillment events remain separate. Lob credentials stay on OneShot's server.

{oneshot_python-0.19.0 → oneshot_python-0.23.1}/oneshot/__init__.py

@@ -1,6 +1,10 @@
 """oneshot-python — Core Python SDK for the OneShot API."""
 
+from oneshot.physical_mail import PhysicalMail, PostalAddress, MailQuote, MailOrder
+
 from oneshot._errors import (
+    BudgetExceededError,
+    BudgetSyncError,
     ContentBlockedError,
     EmergencyNumberError,
     JobError,
@@ -11,6 +15,8 @@ from oneshot._errors import (
     ValidationError,
 )
 from oneshot._types import (
+    AgentBudgetConfig,
+    AgentBudgetStatus,
     ComputeBudgetStatus,
     ComputeCancelResult,
     ComputeFundResult,
@@ -30,16 +36,21 @@ from oneshot.client import OneShotClient
 from oneshot.x402 import sign_payment_authorization
 
 __all__ = [
+    "PhysicalMail", "PostalAddress", "MailQuote", "MailOrder",
     "OneShotClient",
     "OneShotError",
     "ToolError",
     "PaymentError",
+    "BudgetExceededError",
+    "BudgetSyncError",
     "JobError",
     "JobTimeoutError",
     "ValidationError",
     "ContentBlockedError",
     "EmergencyNumberError",
     "sign_payment_authorization",
+    "AgentBudgetConfig",
+    "AgentBudgetStatus",
     "ComputeSchedule",
     "ComputeGoalResult",
     "ComputeGoalStatus",

{oneshot_python-0.19.0 → oneshot_python-0.23.1}/oneshot/_errors.py

@@ -81,3 +81,49 @@ class EmergencyNumberError(OneShotError):
     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.19.0 → oneshot_python-0.23.1}/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