oneshot-python 0.8.3__tar.gz → 0.9.0__tar.gz

{oneshot_python-0.8.3 → oneshot_python-0.9.0}/.gitignore

@@ -70,6 +70,8 @@ tmp/
 
 # Secrets
 soul-api-keys.json
+config/envs/
+config/secrets/
 
 # Next.js
 .next/

{oneshot_python-0.8.3 → oneshot_python-0.9.0}/PKG-INFO

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

{oneshot_python-0.8.3 → oneshot_python-0.9.0}/oneshot/client.py

@@ -94,10 +94,25 @@ class OneShotClient:
         *,
         max_cost: Optional[float] = None,
         timeout_sec: int = 120,
+        wait_for_phones: bool = False,
+        phone_timeout_sec: int = 360,
     ) -> Any:
-        """Execute a paid tool call (blocking). Handles the full x402 flow."""
+        """Execute a paid tool call (blocking). Handles the full x402 flow.
+
+        Set ``wait_for_phones=True`` to keep polling AFTER status=completed
+        until Apollo's async phone-reveal webhook delivers phone numbers
+        (or until ``phone_timeout_sec`` expires, default 6 min — Apollo says
+        "several minutes"). Default is False for backwards compat.
+        """
         return asyncio.get_event_loop().run_until_complete(
-            self.acall_tool(endpoint, payload, max_cost=max_cost, timeout_sec=timeout_sec)
+            self.acall_tool(
+                endpoint,
+                payload,
+                max_cost=max_cost,
+                timeout_sec=timeout_sec,
+                wait_for_phones=wait_for_phones,
+                phone_timeout_sec=phone_timeout_sec,
+            )
         )
 
     async def acall_tool(
@@ -107,6 +122,8 @@ class OneShotClient:
         *,
         max_cost: Optional[float] = None,
         timeout_sec: int = 120,
+        wait_for_phones: bool = False,
+        phone_timeout_sec: int = 360,
     ) -> Any:
         """Execute a paid tool call (async). Handles the full x402 flow."""
         url = f"{self.base_url}{endpoint}"
@@ -137,7 +154,13 @@ class OneShotClient:
                     "pending",
                     "processing",
                 ):
-                    return await self._poll_job(client, result["request_id"], timeout_sec)
+                    return await self._poll_job(
+                        client,
+                        result["request_id"],
+                        timeout_sec,
+                        wait_for_phones=wait_for_phones,
+                        phone_timeout_sec=phone_timeout_sec,
+                    )
                 return result.get("data", result)
 
             # Step 2 — Parse 402 response
@@ -219,7 +242,13 @@ class OneShotClient:
                 "processing",
             ):
                 self._log(f"Job queued: {result['request_id']}")
-                return await self._poll_job(client, result["request_id"], timeout_sec)
+                return await self._poll_job(
+                    client,
+                    result["request_id"],
+                    timeout_sec,
+                    wait_for_phones=wait_for_phones,
+                    phone_timeout_sec=phone_timeout_sec,
+                )
 
             return result.get("data", result)
 
@@ -601,6 +630,9 @@ class OneShotClient:
         client: httpx.AsyncClient,
         request_id: str,
         timeout_sec: int,
+        *,
+        wait_for_phones: bool = False,
+        phone_timeout_sec: int = 360,
     ) -> Any:
         start = time.monotonic()
         retries = 0
@@ -622,7 +654,20 @@ class OneShotClient:
 
                 if job.get("status") == "completed":
                     self._log("Job completed")
-                    return job.get("result", job)
+                    result = job.get("result", job)
+                    # Optional second phase: keep polling for Apollo phone-reveal
+                    # callbacks. Only fires when the caller explicitly opts in
+                    # AND the result still has phones_pending=true (set by the
+                    # worker when Apollo enrichment is awaiting an async webhook).
+                    # Backwards-compat: existing callers see no change.
+                    if wait_for_phones and self._is_phones_pending(result):
+                        return await self._poll_for_phones(
+                            client,
+                            request_id,
+                            phone_timeout_sec,
+                            initial_result=result,
+                        )
+                    return result
 
                 if job.get("status") == "failed":
                     raise JobError(
@@ -644,3 +689,74 @@ class OneShotClient:
 
         elapsed_ms = int((time.monotonic() - start) * 1000)
         raise JobTimeoutError(request_id, elapsed_ms)
+
+    @staticmethod
+    def _is_phones_pending(result: Any) -> bool:
+        """Detects whether a result is awaiting Apollo's async phone-reveal
+        webhook. Tolerates two shapes: the unwrapped result ``{phones_pending}``
+        and the deep_research_person wrapper ``{result: {phones_pending}}``.
+
+        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
+        return False
+
+    async def _poll_for_phones(
+        self,
+        client: httpx.AsyncClient,
+        request_id: str,
+        timeout_sec: int,
+        *,
+        initial_result: Any = None,
+    ) -> Any:
+        """Slow poll loop (5s cadence) for Apollo phone-reveal callbacks.
+
+        The webhook handler in soul-hunt-api UPDATEs jobs.result_data with
+        phones once Apollo POSTs them. We poll the GET endpoint until phones
+        arrive (phones_pending flips false) or ``timeout_sec`` expires. On
+        timeout we return the last snapshot — phones_pending will still be
+        True so the consumer knows phones never arrived.
+
+        Soft-fails on transient HTTP errors and returns the most recent
+        successful snapshot to avoid losing the sync result we already have.
+        """
+        deadline = time.monotonic() + timeout_sec
+        interval = 5.0
+        last_result: Any = initial_result
+
+        while time.monotonic() < deadline:
+            try:
+                resp = await client.get(
+                    f"{self.base_url}/v1/requests/{request_id}",
+                    headers=self._headers(),
+                )
+                if not resp.is_success:
+                    if last_result is not None:
+                        return last_result
+                    raise ToolError(
+                        "Failed to check job status",
+                        resp.status_code,
+                        resp.text,
+                    )
+                job = resp.json()
+                last_result = job.get("result", job)
+                if not self._is_phones_pending(last_result):
+                    return last_result
+            except (OneShotError, JobError):
+                raise
+            except Exception:
+                if last_result is not None:
+                    return last_result
+                raise
+            await asyncio.sleep(interval)
+
+        # Timeout — return the last snapshot. phones_pending is still True
+        # so the caller knows phones never arrived.
+        return last_result

{oneshot_python-0.8.3 → oneshot_python-0.9.0}/pyproject.toml

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

oneshot_python-0.9.0/tests/test_phones_pending.py

@@ -0,0 +1,347 @@
+"""Tests for the Apollo phone-reveal polling extension on OneShotClient.
+
+Apollo's phone numbers arrive asynchronously via a webhook minutes after the
+initial enrichment. The worker writes ``result.phones_pending = True`` so SDK
+clients can opt into a longer poll (``wait_for_phones=True``) until phones
+land. These tests verify:
+
+  1. The static ``_is_phones_pending`` shape detector
+  2. The ``_poll_for_phones`` async loop with mocked httpx responses
+  3. The ``_poll_job → _poll_for_phones`` decision branch (opt-in vs default)
+
+Run with:
+    cd packages/oneshot-python && uv run pytest tests/test_phones_pending.py -v
+"""
+
+import asyncio
+from typing import Any
+from unittest.mock import MagicMock
+
+import pytest
+
+from oneshot.client import OneShotClient
+
+# Deterministic test key (same one used by test_x402.py — never use with funds)
+TEST_PRIVATE_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
+TEST_BASE_URL = "http://test.local"
+
+
+def make_client() -> OneShotClient:
+    """Real OneShotClient with a stable test key. No network calls in tests
+    because we mock the httpx layer entirely."""
+    return OneShotClient(
+        private_key=TEST_PRIVATE_KEY,
+        base_url=TEST_BASE_URL,
+    )
+
+
+# ── Mock httpx.AsyncClient ──────────────────────────────────────────────────
+
+
+def _make_mock_response(status_code: int = 200, json_data: Any = None, text: str = "") -> MagicMock:
+    resp = MagicMock()
+    resp.is_success = 200 <= status_code < 300
+    resp.status_code = status_code
+    resp.json = MagicMock(return_value=json_data or {})
+    resp.text = text
+    return resp
+
+
+class _MockHttpxClient:
+    """Scriptable httpx.AsyncClient stand-in. Tests load `responses` with the
+    sequence of mock responses (or exceptions) and the get() method pops them.
+    """
+
+    def __init__(self, responses):
+        self.responses = list(responses)
+        self.calls = []
+
+    async def get(self, url, headers=None):
+        self.calls.append({"url": url, "headers": headers})
+        if not self.responses:
+            raise RuntimeError(f"Unexpected get to {url} (queue empty, {len(self.calls)} total calls)")
+        next_resp = self.responses.pop(0)
+        if isinstance(next_resp, Exception):
+            raise next_resp
+        return next_resp
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# _is_phones_pending shape detection
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+class TestIsPhonesPending:
+    """Locks the contract between the worker's result_data shape and the SDK.
+    If either side changes, these tests fail."""
+
+    detect = staticmethod(OneShotClient._is_phones_pending)
+
+    def test_false_for_non_dict(self):
+        assert self.detect(None) is False
+        assert self.detect("string") is False
+        assert self.detect(42) is False
+        assert self.detect([]) is False
+        assert self.detect(()) is False
+
+    def test_false_for_empty_dict(self):
+        assert self.detect({}) is False
+
+    def test_true_for_top_level_phones_pending(self):
+        # Shape used by enrich/profile, find_email — flatter result
+        assert self.detect({"full_name": "Jane", "phones_pending": True}) is True
+
+    def test_true_for_nested_result_phones_pending(self):
+        # Shape used by deep_research_person — wraps the person dict
+        assert self.detect({
+            "status": "completed",
+            "result": {"full_name": "Jane", "phones_pending": True},
+        }) is True
+
+    def test_false_when_explicitly_false(self):
+        assert self.detect({"phones_pending": False}) is False
+        assert self.detect({"result": {"phones_pending": False}}) is False
+
+    def test_false_when_missing(self):
+        # Non-Apollo providers never set phones_pending
+        assert self.detect({"full_name": "Jane", "phones": ["+1"]}) is False
+        assert self.detect({"result": {"full_name": "Jane"}}) is False
+
+    def test_strict_equality_only(self):
+        # Defensive: only literal True triggers waiting. A 'pending' string
+        # or a 1 won't accidentally trap a client in an infinite poll.
+        assert self.detect({"phones_pending": "pending"}) is False
+        assert self.detect({"phones_pending": 1}) is False
+        assert self.detect({"phones_pending": "true"}) is False
+
+    def test_does_not_scan_deeper_than_result(self):
+        # result.enrichment.phones_pending is intentionally NOT detected
+        assert self.detect({"result": {"enrichment": {"phones_pending": True}}}) is False
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# _poll_for_phones polling loop
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+class TestPollForPhones:
+    """Exercises _poll_for_phones directly with a scripted mock httpx client.
+    Patches asyncio.sleep so multi-poll tests don't take 15+ seconds of real
+    wall time."""
+
+    @pytest.mark.asyncio
+    async def test_returns_immediately_when_phones_pending_false(self):
+        client = _MockHttpxClient([
+            _make_mock_response(200, {
+                "request_id": "req-1",
+                "status": "completed",
+                "result": {"result": {"phones": ["+15551234567"], "phones_pending": False}},
+            }),
+        ])
+        sdk = make_client()
+        out = await sdk._poll_for_phones(client, "req-1", 60)
+        assert out["result"]["phones"] == ["+15551234567"]
+        assert out["result"]["phones_pending"] is False
+        assert len(client.calls) == 1
+
+    @pytest.mark.asyncio
+    async def test_polls_until_phones_arrive(self, monkeypatch):
+        async def fast_sleep(_):
+            return None
+        monkeypatch.setattr(asyncio, "sleep", fast_sleep)
+
+        client = _MockHttpxClient([
+            _make_mock_response(200, {"result": {"result": {"phones_pending": True}}}),
+            _make_mock_response(200, {"result": {"result": {"phones_pending": True}}}),
+            _make_mock_response(200, {
+                "result": {"result": {"phones": ["+15559999999"], "phones_pending": False}},
+            }),
+        ])
+        sdk = make_client()
+        out = await sdk._poll_for_phones(client, "req-1", 60)
+        assert len(client.calls) == 3
+        assert out["result"]["phones"] == ["+15559999999"]
+
+    @pytest.mark.asyncio
+    async def test_returns_initial_result_on_first_fetch_failure(self, monkeypatch):
+        async def fast_sleep(_):
+            return None
+        monkeypatch.setattr(asyncio, "sleep", fast_sleep)
+
+        client = _MockHttpxClient([RuntimeError("network down")])
+        sdk = make_client()
+        initial = {"result": {"full_name": "Jane", "phones_pending": True, "apollo_person_id": "abc"}}
+        out = await sdk._poll_for_phones(client, "req-1", 60, initial_result=initial)
+        # Soft-failed on first fetch, returned the snapshot we passed in
+        assert out is initial
+        assert len(client.calls) == 1
+
+    @pytest.mark.asyncio
+    async def test_returns_last_snapshot_on_transient_failure_after_success(self, monkeypatch):
+        async def fast_sleep(_):
+            return None
+        monkeypatch.setattr(asyncio, "sleep", fast_sleep)
+
+        client = _MockHttpxClient([
+            _make_mock_response(200, {
+                "result": {"result": {"full_name": "Jane", "phones_pending": True}},
+            }),
+            RuntimeError("transient blip"),
+        ])
+        sdk = make_client()
+        out = await sdk._poll_for_phones(client, "req-1", 60)
+        assert out["result"]["full_name"] == "Jane"
+        assert out["result"]["phones_pending"] is True
+
+    @pytest.mark.asyncio
+    async def test_returns_last_snapshot_on_http_500_after_success(self, monkeypatch):
+        async def fast_sleep(_):
+            return None
+        monkeypatch.setattr(asyncio, "sleep", fast_sleep)
+
+        client = _MockHttpxClient([
+            _make_mock_response(200, {
+                "result": {"result": {"phones_pending": True, "full_name": "Jane"}},
+            }),
+            _make_mock_response(500, text="internal error"),
+        ])
+        sdk = make_client()
+        out = await sdk._poll_for_phones(client, "req-1", 60)
+        assert out["result"]["full_name"] == "Jane"
+        assert out["result"]["phones_pending"] is True
+
+    @pytest.mark.asyncio
+    async def test_raises_when_first_fetch_fails_and_no_initial(self, monkeypatch):
+        async def fast_sleep(_):
+            return None
+        monkeypatch.setattr(asyncio, "sleep", fast_sleep)
+
+        client = _MockHttpxClient([RuntimeError("network down")])
+        sdk = make_client()
+        with pytest.raises(RuntimeError, match="network down"):
+            await sdk._poll_for_phones(client, "req-1", 60)
+
+    @pytest.mark.asyncio
+    async def test_returns_last_snapshot_on_timeout(self, monkeypatch):
+        # Tight 0.05s timeout — first poll completes, then deadline fires
+        async def fast_sleep(_):
+            return None
+        monkeypatch.setattr(asyncio, "sleep", fast_sleep)
+
+        client = _MockHttpxClient([
+            _make_mock_response(200, {
+                "result": {"result": {"phones_pending": True, "full_name": "Jane"}},
+            }),
+        ] * 10)  # plenty of responses, but timeout will end the loop
+        sdk = make_client()
+        out = await sdk._poll_for_phones(client, "req-1", 0.05)
+        assert out["result"]["phones_pending"] is True
+        assert out["result"]["full_name"] == "Jane"
+
+    @pytest.mark.asyncio
+    async def test_hits_correct_url_and_headers(self):
+        client = _MockHttpxClient([
+            _make_mock_response(200, {
+                "result": {"result": {"phones_pending": False, "phones": ["+15550000000"]}},
+            }),
+        ])
+        sdk = make_client()
+        await sdk._poll_for_phones(client, "req-1", 60)
+        assert client.calls[0]["url"] == f"{TEST_BASE_URL}/v1/requests/req-1"
+        # Real client sets X-Agent-ID to the wallet address derived from the test key
+        assert "X-Agent-ID" in client.calls[0]["headers"]
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# _poll_job → _poll_for_phones decision branch
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+class TestPollJobWaitForPhonesDecision:
+    """Verifies that _poll_job opts into _poll_for_phones only when both
+    wait_for_phones=True AND result.phones_pending=True. All other combinations
+    must return at status=completed without extension polling."""
+
+    @pytest.mark.asyncio
+    async def test_default_returns_at_completed_even_if_phones_pending(self, monkeypatch):
+        async def fast_sleep(_):
+            return None
+        monkeypatch.setattr(asyncio, "sleep", fast_sleep)
+
+        client = _MockHttpxClient([
+            _make_mock_response(200, {
+                "request_id": "req-1",
+                "status": "completed",
+                "result": {"result": {"full_name": "Jane", "phones_pending": True}},
+            }),
+        ])
+        sdk = make_client()
+        # wait_for_phones default = False
+        out = await sdk._poll_job(client, "req-1", 60)
+        # Returned even though phones_pending=true — caller didn't opt in
+        assert out["result"]["phones_pending"] is True
+        assert out["result"]["full_name"] == "Jane"
+        assert len(client.calls) == 1  # no extension polling
+
+    @pytest.mark.asyncio
+    async def test_wait_for_phones_triggers_extension_polling(self, monkeypatch):
+        async def fast_sleep(_):
+            return None
+        monkeypatch.setattr(asyncio, "sleep", fast_sleep)
+
+        client = _MockHttpxClient([
+            # First poll: status=completed but phones_pending=true
+            _make_mock_response(200, {
+                "request_id": "req-1",
+                "status": "completed",
+                "result": {"result": {"phones_pending": True, "apollo_person_id": "abc"}},
+            }),
+            # _poll_for_phones first poll: phones arrived
+            _make_mock_response(200, {
+                "request_id": "req-1",
+                "status": "completed",
+                "result": {"result": {"phones": ["+15551234567"], "phones_pending": False}},
+            }),
+        ])
+        sdk = make_client()
+        out = await sdk._poll_job(client, "req-1", 60, wait_for_phones=True)
+        assert out["result"]["phones"] == ["+15551234567"]
+        assert out["result"]["phones_pending"] is False
+        assert len(client.calls) == 2
+
+    @pytest.mark.asyncio
+    async def test_wait_for_phones_no_op_when_phones_already_present(self, monkeypatch):
+        async def fast_sleep(_):
+            return None
+        monkeypatch.setattr(asyncio, "sleep", fast_sleep)
+
+        client = _MockHttpxClient([
+            _make_mock_response(200, {
+                "request_id": "req-1",
+                "status": "completed",
+                "result": {"result": {"phones": ["+15551234567"], "phones_pending": False}},
+            }),
+        ])
+        sdk = make_client()
+        out = await sdk._poll_job(client, "req-1", 60, wait_for_phones=True)
+        # No extension polls — _poll_for_phones never invoked
+        assert out["result"]["phones"] == ["+15551234567"]
+        assert len(client.calls) == 1
+
+    @pytest.mark.asyncio
+    async def test_wait_for_phones_no_op_for_non_apollo_results(self, monkeypatch):
+        async def fast_sleep(_):
+            return None
+        monkeypatch.setattr(asyncio, "sleep", fast_sleep)
+
+        client = _MockHttpxClient([
+            _make_mock_response(200, {
+                "request_id": "req-1",
+                "status": "completed",
+                "result": {"result": {"full_name": "Jane", "provider": "prospeo"}},
+            }),
+        ])
+        sdk = make_client()
+        out = await sdk._poll_job(client, "req-1", 60, wait_for_phones=True)
+        assert out["result"]["full_name"] == "Jane"
+        assert len(client.calls) == 1

{oneshot_python-0.8.3 → oneshot_python-0.9.0}/uv.lock

@@ -549,7 +549,7 @@ wheels = [
 
 [[package]]
 name = "oneshot-python"
-version = "0.7.0"
+version = "0.8.3"
 source = { editable = "." }
 dependencies = [
     { name = "eth-account" },