oneshot-python 0.39.0__tar.gz → 0.40.0__tar.gz

oneshot_python-0.40.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.40.0 — breaking release (#1336)
+
+- Renamed `commerce_search()` / `acommerce_search()` → `product_find()` / `aproduct_find()`, without aliases.
+- Product discovery now calls `POST /v1/tools/find/product` (price key `find/product`), replacing `POST /v1/tools/commerce/search` (`commerce/search`). Input, results and Purchase compatibility are unchanged.
+- Release together with the person/company and other tool renames in #1334 and #1382; publish only with the coordinated server release.

{oneshot_python-0.39.0 → oneshot_python-0.40.0}/PKG-INFO

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

{oneshot_python-0.39.0 → oneshot_python-0.40.0}/README.md

@@ -343,3 +343,18 @@ async form).
 ## License
 
 MIT
+
+## Optional phone lookup
+
+Phone lookup is off by default. Source-returned numbers and published business or record numbers still appear. `include_phone=True` adds $0.10 × the requested search limit (default 100 → $10), or $0.10 for profile/dossier, for up to that many people with no guaranteed hit. Fallbacks and callbacks cost nothing extra. A completed lookup with no phone match is charged; a failed job is refunded.
+
+`max_cost` and per-transaction budgets apply to the full quote before authorization, even when credits cover it. Wallet and access-token sessions both obtain a quote before execution and retry with `x-quote-id`.
+
+```python
+people = client.person_find(job_titles=["CTO"], limit=3, include_phone=True, max_cost=1, wait_for_phones=True)
+profile = client.person_profile(email="jane@example.com", include_phone=True, max_cost=1, wait_for_phones=True)
+dossier = client.person_dossier(email="jane@example.com", include_phone=True, max_cost=1, wait_for_phones=True, timeout_sec=600)
+# Async equivalents: await client.aperson_find(...), aperson_profile(...), aperson_dossier(...).
+```
+
+`wait=False` returns the job and receipt IDs immediately. `wait_for_phones=True` keeps polling for pending phone callbacks after completion; it does not buy phones by itself. On timeout, the latest result can still have `phones_pending: True`.

{oneshot_python-0.39.0 → oneshot_python-0.40.0}/oneshot/client.py

@@ -60,7 +60,7 @@ try:
 
     SDK_VERSION = _pkg_version("oneshot-python")
 except Exception:  # pragma: no cover - editable/source runs without dist metadata
-    SDK_VERSION = "0.39.0"
+    SDK_VERSION = "0.40.0"
 
 _BASE_URL = "https://win.oneshotagent.com"
 _HUNT_BASE_URL = "https://api.soulhunt.ai"
@@ -917,6 +917,7 @@ class OneShotClient:
         on the ``x-quote-id`` header from the very first attempt, since
         quote-based routes reject before the 402 dance even starts without it.
         """
+        person_quote = endpoint in ("/v1/tools/find/person", "/v1/tools/lookup/person-profile", "/v1/tools/lookup/person-dossier")
         memo = payload.get("memo")
         if memo is not None:
             if not isinstance(memo, str) or not memo.strip():
@@ -999,7 +1000,7 @@ class OneShotClient:
                     "processing",
                 ):
                     if not wait:
-                        return result if endpoint.endswith(("/linkedin/invite", "/linkedin/invite/withdraw")) else {"request_id": result["request_id"], "status": result["status"]}
+                        return result if person_quote or endpoint.endswith(("/linkedin/invite", "/linkedin/invite/withdraw")) else {"request_id": result["request_id"], "status": result["status"]}
                     return await self._poll_job(
                         client,
                         result["request_id"],
@@ -1039,6 +1040,9 @@ class OneShotClient:
                         f"Quote ${total} exceeds max_cost ${max_cost}"
                     )
 
+            if person_quote and total is not None:
+                self._assert_within_budget(total)
+
             self._log(f"Payment required: {payment_request['amount']} USDC")
 
             if self._access_token:
@@ -1068,7 +1072,7 @@ class OneShotClient:
                 result = resp2.json()
                 if isinstance(result, dict) and result.get("request_id") and result.get("status") in ("pending", "processing"):
                     if not wait:
-                        return result if endpoint.endswith(("/linkedin/invite", "/linkedin/invite/withdraw")) else {"request_id": result["request_id"], "status": result["status"]}
+                        return result if person_quote or endpoint.endswith(("/linkedin/invite", "/linkedin/invite/withdraw")) else {"request_id": result["request_id"], "status": result["status"]}
                     return await self._poll_job(
                         client, result["request_id"], timeout_sec,
                         wait_for_phones=wait_for_phones, phone_timeout_sec=phone_timeout_sec,
@@ -1158,7 +1162,7 @@ class OneShotClient:
             ):
                 self._log(f"Job queued: {result['request_id']}")
                 if not wait:
-                    return result if endpoint.endswith(("/linkedin/invite", "/linkedin/invite/withdraw")) else {"request_id": result["request_id"], "status": result["status"]}
+                    return result if person_quote or endpoint.endswith(("/linkedin/invite", "/linkedin/invite/withdraw")) else {"request_id": result["request_id"], "status": result["status"]}
                 return await self._poll_job(
                     client,
                     result["request_id"],
@@ -2073,21 +2077,33 @@ class OneShotClient:
         approval_id = kwargs.pop("approval_id", None)
         return await self.acall_tool("/v1/tools/sms/send", {"message": message, "to_number": to_number, **kwargs}, approval_id=approval_id)
 
-    def person_find(self, **kwargs: Any) -> Any:
-        """Search for people by job title, company, etc. Blocking."""
-        return self.call_tool("/v1/tools/find/person", kwargs)
-
-    async def aperson_find(self, **kwargs: Any) -> Any:
-        """Search for people by job title, company, etc. Async."""
-        return await self.acall_tool("/v1/tools/find/person", kwargs)
-
-    def person_profile(self, **kwargs: Any) -> Any:
-        """Enrich a person's profile from LinkedIn URL, email, or name. Blocking."""
-        return self.call_tool("/v1/tools/lookup/person-profile", kwargs)
-
-    async def aperson_profile(self, **kwargs: Any) -> Any:
-        """Enrich a person's profile from LinkedIn URL, email, or name. Async."""
-        return await self.acall_tool("/v1/tools/lookup/person-profile", kwargs)
+    @staticmethod
+    def _person_call_options(kwargs: dict[str, Any]) -> dict[str, Any]:
+        """Keep SDK controls out of the canonical quoted input."""
+        return {key: kwargs.pop(key) for key in (
+            "max_cost", "timeout_sec", "wait", "wait_for_phones",
+            "phone_timeout_sec", "idempotency_key", "approval_id",
+        ) if key in kwargs}
+
+    def person_find(self, *, include_phone: bool = False, **kwargs: Any) -> Any:
+        """Phone lookup is off by default; opt-in uses the limit (default 100) and the per-person add-on on the pricing page, with no hit guaranteed."""
+        options = self._person_call_options(kwargs)
+        return self.call_tool("/v1/tools/find/person", {**kwargs, "include_phone": include_phone}, **options)
+
+    async def aperson_find(self, *, include_phone: bool = False, **kwargs: Any) -> Any:
+        """Phone lookup is off by default; opt-in uses the limit (default 100) and the per-person add-on on the pricing page, with no hit guaranteed."""
+        options = self._person_call_options(kwargs)
+        return await self.acall_tool("/v1/tools/find/person", {**kwargs, "include_phone": include_phone}, **options)
+
+    def person_profile(self, *, include_phone: bool = False, **kwargs: Any) -> Any:
+        """Phone lookup is off by default; opt-in uses the add-on on the pricing page for one person, with no hit guaranteed."""
+        options = self._person_call_options(kwargs)
+        return self.call_tool("/v1/tools/lookup/person-profile", {**kwargs, "include_phone": include_phone}, **options)
+
+    async def aperson_profile(self, *, include_phone: bool = False, **kwargs: Any) -> Any:
+        """Phone lookup is off by default; opt-in uses the add-on on the pricing page for one person, with no hit guaranteed."""
+        options = self._person_call_options(kwargs)
+        return await self.acall_tool("/v1/tools/lookup/person-profile", {**kwargs, "include_phone": include_phone}, **options)
 
     def company_find(self, **kwargs: Any) -> Any:
         """Search for companies by name, domain, industry, location, size, etc. Blocking."""
@@ -2159,13 +2175,15 @@ class OneShotClient:
         """Verify email deliverability. Async."""
         return await self.acall_tool("/v1/tools/lookup/person-email-status", {"email": email})
 
-    def person_dossier(self, **kwargs: Any) -> Any:
-        """Deep research on a person. Blocking."""
-        return self.call_tool("/v1/tools/lookup/person-dossier", kwargs)
+    def person_dossier(self, *, include_phone: bool = False, **kwargs: Any) -> Any:
+        """Phone lookup is off by default; opt-in uses the add-on on the pricing page for one person, with no hit guaranteed."""
+        options = self._person_call_options(kwargs)
+        return self.call_tool("/v1/tools/lookup/person-dossier", {**kwargs, "include_phone": include_phone}, **options)
 
-    async def aperson_dossier(self, **kwargs: Any) -> Any:
-        """Deep research on a person. Async."""
-        return await self.acall_tool("/v1/tools/lookup/person-dossier", kwargs)
+    async def aperson_dossier(self, *, include_phone: bool = False, **kwargs: Any) -> Any:
+        """Phone lookup is off by default; opt-in uses the add-on on the pricing page for one person, with no hit guaranteed."""
+        options = self._person_call_options(kwargs)
+        return await self.acall_tool("/v1/tools/lookup/person-dossier", {**kwargs, "include_phone": include_phone}, **options)
 
     def person_social_accounts(self, **kwargs: Any) -> Any:
         """Discover social media profiles. Blocking."""
@@ -2207,13 +2225,13 @@ class OneShotClient:
         """Get a person's social interactions. Async."""
         return await self.acall_tool("/v1/tools/lookup/person-followers", {"social_media_url": social_media_url, **kwargs})
 
-    def commerce_search(self, query: str, *, limit: int = 10, **kwargs: Any) -> Any:
+    def product_find(self, query: str, *, limit: int = 10, **kwargs: Any) -> Any:
         """Search for products. Blocking."""
-        return self.call_tool("/v1/tools/commerce/search", {"query": query, "limit": limit, **kwargs})
+        return self.call_tool("/v1/tools/find/product", {"query": query, "limit": limit, **kwargs})
 
-    async def acommerce_search(self, query: str, *, limit: int = 10, **kwargs: Any) -> Any:
+    async def aproduct_find(self, query: str, *, limit: int = 10, **kwargs: Any) -> Any:
         """Search for products. Async."""
-        return await self.acall_tool("/v1/tools/commerce/search", {"query": query, "limit": limit, **kwargs})
+        return await self.acall_tool("/v1/tools/find/product", {"query": query, "limit": limit, **kwargs})
 
     def commerce_buy(self, product_url: str, shipping_address: dict[str, Any], **kwargs: Any) -> Any:
         """Purchase a product. Blocking."""
@@ -2515,23 +2533,27 @@ class OneShotClient:
     @staticmethod
     def _is_phones_pending(result: Any) -> bool:
         """Detects whether a result is awaiting Apollo's async phone-reveal
-        webhook. Accepts legacy flat results and person_dossier's
-        ``result.profile.data.phones_pending``.
+        webhook. Accepts worker search rows, profile objects, dossier sections
+        and legacy flat results.
 
         Mirrors the TS SDK's _isPhonesPending — kept in lockstep so the worker
         contract works for both SDKs.
         """
         if not isinstance(result, dict):
             return False
-        if result.get("phones_pending") is True:
-            return True
-        inner = result.get("result")
-        if isinstance(inner, dict) and inner.get("phones_pending") is True:
-            return True
-        profile = inner.get("profile") if isinstance(inner, dict) else None
-        data = profile.get("data") if isinstance(profile, dict) else None
-        if isinstance(data, dict) and data.get("phones_pending") is True:
-            return True
+        def pending(value: Any) -> bool:
+            return isinstance(value, dict) and value.get("phones_pending") is True
+
+        for body in (result, result.get("result")):
+            if not isinstance(body, dict):
+                continue
+            profile = body.get("profile")
+            data = profile.get("data") if isinstance(profile, dict) else None
+            rows = body.get("results")
+            if pending(body) or pending(profile) or pending(data):
+                return True
+            if isinstance(rows, list) and any(pending(row) for row in rows):
+                return True
         return False
 
     async def _poll_for_phones(

{oneshot_python-0.39.0 → oneshot_python-0.40.0}/oneshot/lookup_manifest.py

@@ -563,6 +563,76 @@ LOOKUP_MANIFEST: list[dict[str, Any]] = [
             "longitude": -95.3698,
         },
     },
+    {
+        "name": "market_freight_rate",
+        "path": "/v1/tools/lookup/market-freight-rate",
+        "title": "Freight Rate Quote",
+        "description": "Quote the rate to move freight between two US ZIP codes on a pickup date, by mode: ltl shares a trailer by the pallet, ftl is a whole 53-foot dry van, van is a cargo van and box_truck is a 26-foot box truck. The answer is one carrier's quote for that lane: the rate for the whole shipment with every included service, the transit time, the pickup and delivery dates, when the quote lapses and whether it is firm or indicative. Use it to check a billed freight charge against the lane's going rate. For ltl give the pallets, the weight per pallet and the pallet dimensions; for van and box_truck give the pallets and the weight per pallet; for ftl the lane and date are enough. A lane the mode does not serve is refused as invalid input: try another mode. Covers US lanes. Nothing is booked.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "origin_zip": {
+                    "type": "string",
+                    "description": "Where the freight is collected. 5-digit US ZIP code.",
+                },
+                "destination_zip": {
+                    "type": "string",
+                    "description": "Where the freight is delivered. 5-digit US ZIP code.",
+                },
+                "mode": {
+                    "type": "string",
+                    "enum": [
+                        "ltl",
+                        "ftl",
+                        "van",
+                        "box_truck",
+                    ],
+                    "description": "How the freight moves. Picks the quote asked for; there is no default",
+                },
+                "pickup_date": {
+                    "type": "string",
+                    "description": "The day the freight is collected: today (UTC) or later. YYYY-MM-DD.",
+                },
+                "pallets": {
+                    "type": "integer",
+                    "description": "How many pallets. Required for ltl, van (up to 3) and box_truck (up to 12); not needed for ftl. At least 1.",
+                },
+                "weight_lbs_per_pallet": {
+                    "type": "integer",
+                    "description": "The weight of each pallet in pounds. Required for ltl, van (3,500 lb in all) and box_truck (10,000 lb in all); not needed for ftl. At least 1.",
+                },
+                "length_in": {
+                    "type": "integer",
+                    "description": "The length of each pallet in inches. Required for ltl; ignored for other modes. At least 1.",
+                },
+                "width_in": {
+                    "type": "integer",
+                    "description": "The width of each pallet in inches. Required for ltl; ignored for other modes. At least 1.",
+                },
+                "height_in": {
+                    "type": "integer",
+                    "description": "The height of each pallet in inches, up to 85. Required for ltl; ignored for other modes. At least 1.",
+                },
+            },
+            "required": [
+                "origin_zip",
+                "destination_zip",
+                "mode",
+                "pickup_date",
+            ],
+        },
+        "example": {
+            "origin_zip": "90012",
+            "destination_zip": "94105",
+            "mode": "ltl",
+            "pickup_date": "2026-10-20",
+            "pallets": 2,
+            "weight_lbs_per_pallet": 800,
+            "length_in": 48,
+            "width_in": 40,
+            "height_in": 48,
+        },
+    },
     {
         "name": "person_health_provider",
         "path": "/v1/tools/lookup/person-health-provider",
@@ -1298,7 +1368,7 @@ LOOKUP_MANIFEST: list[dict[str, Any]] = [
         "method": "POST",
         "pricing": "fixed",
         "title": "Changes",
-        "description": "What changed about one entity since a date, from the observations OneShot recorded: each change has the earlier value, the later value, when it was seen and the source. Give `attribute` (the name of a data tool that keeps history), `since`, and exactly one of `key` and `input`. A window with no changes is a completed, charged result. Paid per call.",
+        "description": "What changed about one entity since a date, from the observations OneShot recorded: each change has the earlier value, the later value, when it was seen and the source. Give `attribute` (the name of a data tool that keeps history), `since`, and exactly one of `key` and `input`. For healthcare_exclusions, input selects a held monthly release and optional exact name/NPI/UPIN; returns row membership and full-row additions/removals, with coverage. A corrected row is removal plus addition, never person identity. A window with no changes is a completed, charged result. Paid per call.",
         "input_schema": {
             "type": "object",
             "properties": {
@@ -1312,7 +1382,7 @@ LOOKUP_MANIFEST: list[dict[str, Any]] = [
                 },
                 "input": {
                     "type": "object",
-                    "description": "Input a search was called with, for a stored search. Give exactly one of key and input",
+                    "description": "Stored search input; healthcare_exclusions accepts {entity: person|company, release: YYYY-MM, name? | npi? | upin?, previous_release?, after?}. Exact row membership, not person identity. Give exactly one of key and input",
                 },
                 "source": {
                     "type": "string",
@@ -1320,7 +1390,7 @@ LOOKUP_MANIFEST: list[dict[str, Any]] = [
                 },
                 "since": {
                     "type": "string",
-                    "description": "First day of the window, YYYY-MM-DD",
+                    "description": "First day of the window, YYYY-MM-DD; optional for healthcare_exclusions monthly releases",
                 },
                 "until": {
                     "type": "string",
@@ -1333,7 +1403,6 @@ LOOKUP_MANIFEST: list[dict[str, Any]] = [
             },
             "required": [
                 "attribute",
-                "since",
             ],
         },
         "example": {

{oneshot_python-0.39.0 → oneshot_python-0.40.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "oneshot-python"
-version = "0.39.0"
+version = "0.40.0"
 description = "Core Python SDK for the OneShot API — HTTP client with x402 payment handling — 48 tools"
 readme = {text = "Core Python SDK for the OneShot API", content-type = "text/plain"}
 license = "MIT"

{oneshot_python-0.39.0 → oneshot_python-0.40.0}/tests/test_person_quote_credits.py

@@ -80,3 +80,51 @@ async def test_a_person_quote_the_credits_do_not_cover_signs_exactly_the_charge(
     assert len(sent) == 2
     assert signed.call_args.kwargs["amount"] == "0.101000"
     assert sent[1]["x-quote-id"] == "q-person"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("method", ["aperson_find", "aperson_profile", "aperson_dossier"])
+async def test_person_quote_caps_apply_to_full_price_before_wallet_or_credit_retry(method):
+    from oneshot._errors import OneShotError
+
+    for session in ("wallet", "wallet-credits", "token"):
+        for cap in ("max_cost", "budget"):
+            if session == "token" and cap == "budget":
+                continue  # Access-token budgets are configured on the server.
+            client = (OneShotClient(access_token="oneshot_" + "ab" * 32, address=MERCHANT)
+                      if session == "token" else OneShotClient(TEST_PRIVATE_KEY, **(
+                          {"budgets": {"per_transaction": 0.05}} if cap == "budget" else {})))
+            client._budget_synced = True
+            http = MagicMock()
+            http.post = AsyncMock(return_value=_quote("0.101000" if session == "wallet" else "0.000000"))
+            http.__aenter__ = AsyncMock(return_value=http)
+            http.__aexit__ = AsyncMock(return_value=False)
+            with patch("oneshot.client.httpx.AsyncClient", return_value=http), \
+                 patch("oneshot.client.parse_payment_required", return_value={"accepted": {"amount": "0"}}), \
+                 patch("oneshot.client.sign_payment_authorization") as sign:
+                with pytest.raises(OneShotError, match="exceeds"):
+                    await getattr(client, method)(name="Jane", include_phone=True, **({"max_cost": 0.05} if cap == "max_cost" else {}))
+            sign.assert_not_called()
+            assert http.post.await_count == 1
+            assert "max_cost" not in http.post.call_args.kwargs["json"]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("method", ["aperson_find", "aperson_profile", "aperson_dossier"])
+async def test_person_wait_false_preserves_receipt_and_keeps_controls_out_of_quote(method):
+    for token in (False, True):
+        client = (OneShotClient(access_token="oneshot_" + "ab" * 32, address=MERCHANT)
+                  if token else OneShotClient(TEST_PRIVATE_KEY))
+        client._budget_synced = True
+        http = MagicMock()
+        http.post = AsyncMock(side_effect=[_quote("0.000000"), _resp(202, {
+            "request_id": "job-1", "receipt_id": "receipt-1", "status": "processing",
+        })])
+        http.__aenter__ = AsyncMock(return_value=http)
+        http.__aexit__ = AsyncMock(return_value=False)
+        with patch("oneshot.client.httpx.AsyncClient", return_value=http), \
+             patch("oneshot.client.parse_payment_required", return_value={"accepted": {"amount": "0"}}):
+            result = await getattr(client, method)(name="Jane", include_phone=True, wait=False, wait_for_phones=True, phone_timeout_sec=1)
+        assert result["receipt_id"] == "receipt-1"
+        assert http.post.call_args.kwargs["json"] == {"name": "Jane", "include_phone": True}
+        assert http.post.call_args.kwargs["headers"]["x-quote-id"] == "q-person"

{oneshot_python-0.39.0 → oneshot_python-0.40.0}/tests/test_phones_pending.py

@@ -351,3 +351,9 @@ def test_dossier_profile_section_retains_strict_phone_wait_detection():
     for value in (True, False, "true", None):
         result = {"result": {"profile": {"state": "found", "data": {"phones_pending": value}}}}
         assert OneShotClient._is_phones_pending(result) is (value is True)
+
+
+def test_worker_profile_and_search_pending_shapes():
+    for value in (True, False, None, "true", 1):
+        assert OneShotClient._is_phones_pending({"status": "completed", "profile": {"phones_pending": value}}) is (value is True)
+        assert OneShotClient._is_phones_pending({"status": "completed", "results": [None, {}, {"phones_pending": value}]}) is (value is True)

oneshot_python-0.40.0/tests/test_product_find.py

@@ -0,0 +1,18 @@
+"""#1336: sync/async product discovery uses the new name without payload changes."""
+from unittest.mock import AsyncMock, patch
+import pytest
+from oneshot import OneShotClient
+
+
+@pytest.mark.asyncio
+async def test_product_find_sync_and_async_have_no_old_alias():
+    client = OneShotClient("0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80")
+    result = {"products": [{"product_url": "https://shop.example/products/desk"}], "count": 1}
+    assert not hasattr(client, "commerce_search")
+    assert not hasattr(client, "acommerce_search")
+    with patch.object(OneShotClient, "call_tool", return_value=result) as call:
+        assert client.product_find("desk") is result
+        call.assert_called_once_with("/v1/tools/find/product", {"query": "desk", "limit": 10})
+    with patch.object(OneShotClient, "acall_tool", new_callable=AsyncMock, return_value=result) as call:
+        assert await client.aproduct_find("desk", limit=5) is result
+        call.assert_awaited_once_with("/v1/tools/find/product", {"query": "desk", "limit": 5})