predev-api 0.12.0__tar.gz → 1.1.0__tar.gz

{predev_api-0.12.0/predev_api.egg-info → predev_api-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: predev-api
-Version: 0.12.0
+Version: 1.1.0
 Summary: Python client for the Pre.dev Architect API - Generate comprehensive software specifications
 Home-page: https://github.com/predotdev/predev-api
 Author: Pre.dev
@@ -502,7 +502,7 @@ For issues, questions, or contributions, please visit the [GitHub repository](ht
 
 ## Browser Tasks
 
-Run browser automation — scrape data, fill forms, navigate pages, extract structured data. Each task navigates a URL, optionally performs actions, and returns typed JSON.
+Run browser automation — navigate, interact, and/or extract data from any web page. Each task navigates a URL, performs actions, and optionally returns typed JSON.
 
 ### Quick start
 
@@ -511,7 +511,7 @@ from predev_api import PredevAPI
 
 client = PredevAPI(api_key="your_api_key")
 
-result = client.browser_tasks([
+result = client.browser_agent([
     {
         "url": "https://news.ycombinator.com",
         "instruction": "Extract the top 5 stories",
@@ -542,7 +542,7 @@ for story in result["results"][0]["data"]["stories"]:
 #### 1. Sync (default) — wait for completion
 
 ```python
-result = client.browser_tasks([
+result = client.browser_agent([
     {"url": "https://example.com", "output": {"type": "object", "properties": {"heading": {"type": "string"}}}}
 ])
 print(result["results"][0]["data"])  # {'heading': 'Example Domain'}
@@ -554,7 +554,7 @@ print(result["totalCreditsUsed"])    # 0.1
 Yields events as the agent runs. Good for showing progress in a UI.
 
 ```python
-for msg in client.browser_tasks(tasks, stream=True):
+for msg in client.browser_agent(tasks, stream=True):
     e, d = msg["event"], msg["data"]
     if e == "task_event":
         # navigation | screenshot | plan | action | validation | done
@@ -574,11 +574,11 @@ Returns the batch ID immediately. Use for long-running batches or background job
 ```python
 import time
 
-r = client.browser_tasks(tasks, run_async=True)
+r = client.browser_agent(tasks, run_async=True)
 # {"id": "batch_abc", "status": "processing", "completed": 0, "total": 3}
 
 while True:
-    state = client.get_browser_tasks(r["id"])
+    state = client.get_browser_agent(r["id"])
     print(f"{state['completed']}/{state['total']}")
     for done in state["results"]:
         print(f"  ✓ {done['url']} -> {done.get('data')}")
@@ -600,27 +600,27 @@ Each task's behavior is determined by which fields are set:
 
 ### Retrieving a batch with the full timeline
 
-Every task records navigation, screenshots, LLM plans, actions, validations. Retrieve for audit, replay, or debugging:
+Every task records navigation, screenshots, LLM plans, actions, validations. Retrieve for audit, replay, or debugging. Screenshots are uploaded to a CDN during execution — retrieved events contain `data["url"]`, not base64.
 
 ```python
-import base64
-
-details = client.get_browser_tasks(batch_id, include_events=True)
+details = client.get_browser_agent(batch_id, include_events=True)
 for result in details["results"]:
     for ev in result.get("events", []):
         if ev["type"] == "screenshot":
-            with open(f"screenshot_iter{ev.get('iteration')}.jpg", "wb") as f:
-                f.write(base64.b64decode(ev["data"]["base64"]))
+            # ev["data"]["url"] is a permanent CDN URL. Use directly in an <img>.
+            print(f"Iter {ev.get('iteration')} screenshot:", ev["data"]["url"])
         elif ev["type"] == "plan":
             print(f"Iter {ev.get('iteration')} plan: {ev['data'].get('notes')}")
 ```
 
+> **Note:** The live SSE stream (`stream=True`) still sends screenshots inline as base64 (`ev["data"]["base64"]`) so live UIs render instantly. The retrieval path (`get_browser_agent`) always returns CDN URLs.
+
 ### Parallel batch example
 
 ```python
 # Scrape 100 URLs with 20 browsers in parallel
 urls = [...100 urls...]
-result = client.browser_tasks(
+result = client.browser_agent(
     [{"url": u, "output": {"type": "object", "properties": {"title": {"type": "string"}}}} for u in urls],
     concurrency=20
 )
@@ -631,10 +631,10 @@ print(f"{result['completed']}/{result['total']} done in {result['totalCreditsUse
 
 | Method | Returns | Use when |
 |---|---|---|
-| `browser_tasks(tasks, concurrency=N)` | dict | Default — wait for completion |
-| `browser_tasks(tasks, stream=True)` | iterator of SSE dicts | Live UI showing execution timeline |
-| `browser_tasks(tasks, run_async=True)` | dict (empty results, returned immediately) | Long batches, background jobs |
-| `get_browser_tasks(batch_id, include_events=False)` | dict | Poll progress or retrieve a completed batch |
+| `browser_agent(tasks, concurrency=N)` | dict | Default — wait for completion |
+| `browser_agent(tasks, stream=True)` | iterator of SSE dicts | Live UI showing execution timeline |
+| `browser_agent(tasks, run_async=True)` | dict (empty results, returned immediately) | Long batches, background jobs |
+| `get_browser_agent(batch_id, include_events=False)` | dict | Poll progress or retrieve a completed batch |
 
 ### Task result statuses
 
@@ -653,3 +653,51 @@ print(f"{result['completed']}/{result['total']} done in {result['totalCreditsUse
 - Minimum: **0.1 credits per task** ($0.01)
 - 10x margin on underlying LLM + sandbox compute
 - 1 credit = $0.10
+
+### Error handling
+
+The browser-task endpoints raise typed exceptions for the most common
+gating cases. Every billing-gate exception carries an `action_url` — a
+deep link back to pre.dev that auto-opens the right modal (subscribe /
+buy credits) when the user lands there:
+
+```python
+from predev_api import (
+    PredevAPI,
+    InsufficientCreditsError,
+    SubscriptionRequiredError,
+    RateLimitError,
+    QueueFullError,
+)
+import webbrowser
+
+client = PredevAPI(api_key="your_pre.dev_api_key")
+
+try:
+    client.browser_agent([{"url": "https://example.com", "instruction": "extract h1"}])
+except InsufficientCreditsError as e:
+    # Send the user to the credits modal — `action_url` is the canonical link.
+    if e.action_url:
+        webbrowser.open(e.action_url)
+except SubscriptionRequiredError as e:
+    if e.action_url:
+        webbrowser.open(e.action_url)
+except RateLimitError:
+    pass  # back off and retry
+except QueueFullError:
+    pass  # wait for in-flight tasks to drain
+```
+
+Mid-stream errors on the SSE stream raise the same typed exceptions, so a
+`for msg in client.browser_agent(..., stream=True):` loop wrapped in
+`try/except` is enough — no special event handling required.
+
+| Exception | HTTP | `code` |
+|---|---|---|
+| `SubscriptionRequiredError` | 402 | `SUBSCRIPTION_REQUIRED` |
+| `InsufficientCreditsError` | 402 | `INSUFFICIENT_CREDITS` |
+| `RateLimitError` | 429 | `RATE_LIMITED` |
+| `QueueFullError` | 429 | `QUEUE_FULL` |
+| `BatchTooLargeError` | 400 | `BATCH_TOO_LARGE` |
+| `AuthenticationError` | 401 | — |
+| `PredevAPIError` | other | — |

{predev_api-0.12.0 → predev_api-1.1.0}/README.md

@@ -462,7 +462,7 @@ For issues, questions, or contributions, please visit the [GitHub repository](ht
 
 ## Browser Tasks
 
-Run browser automation — scrape data, fill forms, navigate pages, extract structured data. Each task navigates a URL, optionally performs actions, and returns typed JSON.
+Run browser automation — navigate, interact, and/or extract data from any web page. Each task navigates a URL, performs actions, and optionally returns typed JSON.
 
 ### Quick start
 
@@ -471,7 +471,7 @@ from predev_api import PredevAPI
 
 client = PredevAPI(api_key="your_api_key")
 
-result = client.browser_tasks([
+result = client.browser_agent([
     {
         "url": "https://news.ycombinator.com",
         "instruction": "Extract the top 5 stories",
@@ -502,7 +502,7 @@ for story in result["results"][0]["data"]["stories"]:
 #### 1. Sync (default) — wait for completion
 
 ```python
-result = client.browser_tasks([
+result = client.browser_agent([
     {"url": "https://example.com", "output": {"type": "object", "properties": {"heading": {"type": "string"}}}}
 ])
 print(result["results"][0]["data"])  # {'heading': 'Example Domain'}
@@ -514,7 +514,7 @@ print(result["totalCreditsUsed"])    # 0.1
 Yields events as the agent runs. Good for showing progress in a UI.
 
 ```python
-for msg in client.browser_tasks(tasks, stream=True):
+for msg in client.browser_agent(tasks, stream=True):
     e, d = msg["event"], msg["data"]
     if e == "task_event":
         # navigation | screenshot | plan | action | validation | done
@@ -534,11 +534,11 @@ Returns the batch ID immediately. Use for long-running batches or background job
 ```python
 import time
 
-r = client.browser_tasks(tasks, run_async=True)
+r = client.browser_agent(tasks, run_async=True)
 # {"id": "batch_abc", "status": "processing", "completed": 0, "total": 3}
 
 while True:
-    state = client.get_browser_tasks(r["id"])
+    state = client.get_browser_agent(r["id"])
     print(f"{state['completed']}/{state['total']}")
     for done in state["results"]:
         print(f"  ✓ {done['url']} -> {done.get('data')}")
@@ -560,27 +560,27 @@ Each task's behavior is determined by which fields are set:
 
 ### Retrieving a batch with the full timeline
 
-Every task records navigation, screenshots, LLM plans, actions, validations. Retrieve for audit, replay, or debugging:
+Every task records navigation, screenshots, LLM plans, actions, validations. Retrieve for audit, replay, or debugging. Screenshots are uploaded to a CDN during execution — retrieved events contain `data["url"]`, not base64.
 
 ```python
-import base64
-
-details = client.get_browser_tasks(batch_id, include_events=True)
+details = client.get_browser_agent(batch_id, include_events=True)
 for result in details["results"]:
     for ev in result.get("events", []):
         if ev["type"] == "screenshot":
-            with open(f"screenshot_iter{ev.get('iteration')}.jpg", "wb") as f:
-                f.write(base64.b64decode(ev["data"]["base64"]))
+            # ev["data"]["url"] is a permanent CDN URL. Use directly in an <img>.
+            print(f"Iter {ev.get('iteration')} screenshot:", ev["data"]["url"])
         elif ev["type"] == "plan":
             print(f"Iter {ev.get('iteration')} plan: {ev['data'].get('notes')}")
 ```
 
+> **Note:** The live SSE stream (`stream=True`) still sends screenshots inline as base64 (`ev["data"]["base64"]`) so live UIs render instantly. The retrieval path (`get_browser_agent`) always returns CDN URLs.
+
 ### Parallel batch example
 
 ```python
 # Scrape 100 URLs with 20 browsers in parallel
 urls = [...100 urls...]
-result = client.browser_tasks(
+result = client.browser_agent(
     [{"url": u, "output": {"type": "object", "properties": {"title": {"type": "string"}}}} for u in urls],
     concurrency=20
 )
@@ -591,10 +591,10 @@ print(f"{result['completed']}/{result['total']} done in {result['totalCreditsUse
 
 | Method | Returns | Use when |
 |---|---|---|
-| `browser_tasks(tasks, concurrency=N)` | dict | Default — wait for completion |
-| `browser_tasks(tasks, stream=True)` | iterator of SSE dicts | Live UI showing execution timeline |
-| `browser_tasks(tasks, run_async=True)` | dict (empty results, returned immediately) | Long batches, background jobs |
-| `get_browser_tasks(batch_id, include_events=False)` | dict | Poll progress or retrieve a completed batch |
+| `browser_agent(tasks, concurrency=N)` | dict | Default — wait for completion |
+| `browser_agent(tasks, stream=True)` | iterator of SSE dicts | Live UI showing execution timeline |
+| `browser_agent(tasks, run_async=True)` | dict (empty results, returned immediately) | Long batches, background jobs |
+| `get_browser_agent(batch_id, include_events=False)` | dict | Poll progress or retrieve a completed batch |
 
 ### Task result statuses
 
@@ -613,3 +613,51 @@ print(f"{result['completed']}/{result['total']} done in {result['totalCreditsUse
 - Minimum: **0.1 credits per task** ($0.01)
 - 10x margin on underlying LLM + sandbox compute
 - 1 credit = $0.10
+
+### Error handling
+
+The browser-task endpoints raise typed exceptions for the most common
+gating cases. Every billing-gate exception carries an `action_url` — a
+deep link back to pre.dev that auto-opens the right modal (subscribe /
+buy credits) when the user lands there:
+
+```python
+from predev_api import (
+    PredevAPI,
+    InsufficientCreditsError,
+    SubscriptionRequiredError,
+    RateLimitError,
+    QueueFullError,
+)
+import webbrowser
+
+client = PredevAPI(api_key="your_pre.dev_api_key")
+
+try:
+    client.browser_agent([{"url": "https://example.com", "instruction": "extract h1"}])
+except InsufficientCreditsError as e:
+    # Send the user to the credits modal — `action_url` is the canonical link.
+    if e.action_url:
+        webbrowser.open(e.action_url)
+except SubscriptionRequiredError as e:
+    if e.action_url:
+        webbrowser.open(e.action_url)
+except RateLimitError:
+    pass  # back off and retry
+except QueueFullError:
+    pass  # wait for in-flight tasks to drain
+```
+
+Mid-stream errors on the SSE stream raise the same typed exceptions, so a
+`for msg in client.browser_agent(..., stream=True):` loop wrapped in
+`try/except` is enough — no special event handling required.
+
+| Exception | HTTP | `code` |
+|---|---|---|
+| `SubscriptionRequiredError` | 402 | `SUBSCRIPTION_REQUIRED` |
+| `InsufficientCreditsError` | 402 | `INSUFFICIENT_CREDITS` |
+| `RateLimitError` | 429 | `RATE_LIMITED` |
+| `QueueFullError` | 429 | `QUEUE_FULL` |
+| `BatchTooLargeError` | 400 | `BATCH_TOO_LARGE` |
+| `AuthenticationError` | 401 | — |
+| `PredevAPIError` | other | — |

{predev_api-0.12.0 → predev_api-1.1.0}/predev_api/__init__.py

@@ -27,14 +27,28 @@ from .client import (
     AlternativeTechStackItemApi,
     SpecEnrichedTechStackItem,
 )
-from .exceptions import PredevAPIError, AuthenticationError, RateLimitError
+from .exceptions import (
+    PredevAPIError,
+    AuthenticationError,
+    RateLimitError,
+    SubscriptionRequiredError,
+    InsufficientCreditsError,
+    QueueFullError,
+    BatchTooLargeError,
+    exception_for_code,
+)
 
-__version__ = "0.11.1"
+__version__ = "1.1.0"
 __all__ = [
     "PredevAPI",
     "PredevAPIError",
     "AuthenticationError",
     "RateLimitError",
+    "SubscriptionRequiredError",
+    "InsufficientCreditsError",
+    "QueueFullError",
+    "BatchTooLargeError",
+    "exception_for_code",
     "ZippedDocsUrl",
     "SpecCoreFunctionality",
     "SpecTechStackItem",

{predev_api-0.12.0 → predev_api-1.1.0}/predev_api/client.py

@@ -6,7 +6,16 @@ from typing import Optional, Dict, Any, Literal, List, Union, BinaryIO, Iterator
 from dataclasses import dataclass
 import json
 import requests
-from .exceptions import PredevAPIError, AuthenticationError, RateLimitError
+from .exceptions import (
+    PredevAPIError,
+    AuthenticationError,
+    RateLimitError,
+    SubscriptionRequiredError,
+    InsufficientCreditsError,
+    QueueFullError,
+    BatchTooLargeError,
+    exception_for_code,
+)
 
 
 @dataclass
@@ -132,7 +141,9 @@ class SpecGraphNode:
     label: str = ""
     type: Optional[str] = None
     description: Optional[str] = None
-    level: Optional[int] = None
+    # userFlowGraph: BFS depth from roles (roles = 0, flows >= 1, None when
+    # unreachable). architectureGraph: C4 diagram level ("C1" | "C2").
+    level: Optional[Union[int, str]] = None
     hours: Optional[float] = None
 
 
@@ -608,27 +619,27 @@ class PredevAPI:
         except requests.RequestException as e:
             raise PredevAPIError(f"Request failed: {str(e)}") from e
 
-    def get_browser_tasks(
+    def get_browser_agent(
         self,
         batch_id: str,
         include_events: bool = False
     ) -> Dict[str, Any]:
         """
-        Get the status + results of a browser tasks batch by ID.
+        Get the status + results of a browser-agent batch by ID.
 
-        Works for both in-progress and completed batches - use with async=True
+        Works for both in-progress and completed batches - use with run_async=True
         submissions to poll for progress. Set include_events=True to get the
         full timeline (screenshots, plans, actions, validations) for each task.
 
         Args:
-            batch_id: The batch ID returned from browser_tasks
+            batch_id: The batch ID returned from browser_agent()
             include_events: Include full event timeline (can be large due to screenshots)
 
         Returns:
-            Dict with id, total, completed, results, totalCost, totalCreditsUsed, status
+            Dict with id, total, completed, results, totalCreditsUsed, status
         """
         qs = "?includeEvents=true" if include_events else ""
-        url = f"{self.base_url}/api/v1/browser-tasks/{batch_id}{qs}"
+        url = f"{self.base_url}/browser-agent/{batch_id}{qs}"
         try:
             response = requests.get(url, headers=self.headers, timeout=60)
             self._handle_response(response)
@@ -636,7 +647,55 @@ class PredevAPI:
         except requests.RequestException as e:
             raise PredevAPIError(f"Request failed: {str(e)}") from e
 
-    def browser_tasks(
+    def list_browser_agents(
+        self,
+        limit: Optional[int] = None,
+        skip: Optional[int] = None,
+        status: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        List browser-agent runs for the authenticated caller. Sorted by most recent.
+
+        Args:
+            limit: Page size (1-100, default 20)
+            skip: Offset for pagination
+            status: Optional filter ('processing' | 'completed')
+
+        Returns:
+            Dict with keys: batches, total, hasMore
+        """
+        params: Dict[str, Any] = {}
+        if limit is not None:
+            params["limit"] = limit
+        if skip is not None:
+            params["skip"] = skip
+        if status is not None:
+            params["status"] = status
+        url = f"{self.base_url}/list-browser-agents"
+        try:
+            response = requests.get(url, headers=self.headers, params=params, timeout=60)
+            self._handle_response(response)
+            return response.json()
+        except requests.RequestException as e:
+            raise PredevAPIError(f"Request failed: {str(e)}") from e
+
+    def browser_agent_status(self) -> Dict[str, Any]:
+        """
+        Caller's live queue snapshot. Useful for watching in-flight work
+        against the per-user queue cap (1000 live tasks).
+
+        Returns:
+            Dict with keys: userId, running, claimed, pending, total, cap
+        """
+        url = f"{self.base_url}/browser-agent-status"
+        try:
+            response = requests.get(url, headers=self.headers, timeout=30)
+            self._handle_response(response)
+            return response.json()
+        except requests.RequestException as e:
+            raise PredevAPIError(f"Request failed: {str(e)}") from e
+
+    def browser_agent(
         self,
         tasks: List[Dict[str, Any]],
         concurrency: Optional[int] = None,
@@ -644,7 +703,7 @@ class PredevAPI:
         run_async: bool = False
     ) -> Union[Dict[str, Any], Iterator[Dict[str, Any]]]:
         """
-        Run browser automation tasks - scrape data, fill forms, navigate pages.
+        Run browser-agent automation tasks - scrape data, fill forms, navigate pages.
 
         Always pass an array of tasks (even for a single task). Each task has a
         url and optional instruction, input, and output schema.
@@ -658,9 +717,11 @@ class PredevAPI:
             concurrency: Parallel browsers (default 5, max 20)
             stream: If True, returns an iterator of SSE events instead of
                     waiting for all tasks to complete
+            run_async: If True, returns immediately with the batch id; poll
+                    get_browser_agent(id) for progress.
 
         Returns:
-            Without stream: Dict with id, total, completed, results, totalCost, totalCreditsUsed
+            Without stream: Dict with id, total, completed, results, totalCreditsUsed
             With stream: Iterator yielding dicts with 'event' and 'data' keys:
                 - event='task_event': real-time events (navigation, screenshot, plan, action, etc.)
                 - event='task_result': a single task completed
@@ -669,20 +730,20 @@ class PredevAPI:
 
         Example:
             >>> # Standard mode
-            >>> result = client.browser_tasks([
+            >>> result = client.browser_agent([
             ...     {"url": "https://example.com", "output": {"type": "object", "properties": {"heading": {"type": "string"}}}}
             ... ])
             >>> print(result["results"][0]["data"])
             >>>
             >>> # Stream mode
-            >>> for msg in client.browser_tasks([...], stream=True):
+            >>> for msg in client.browser_agent([...], stream=True):
             ...     if msg["event"] == "done":
             ...         print("Done:", msg["data"]["totalCreditsUsed"], "credits")
         """
         if stream:
-            return self._browser_tasks_stream(tasks, concurrency)
+            return self._browser_agent_stream(tasks, concurrency)
 
-        url = f"{self.base_url}/api/v1/browser-tasks"
+        url = f"{self.base_url}/browser-agent"
         payload: Dict[str, Any] = {"tasks": tasks}
         if concurrency is not None:
             payload["concurrency"] = concurrency
@@ -701,13 +762,13 @@ class PredevAPI:
         except requests.RequestException as e:
             raise PredevAPIError(f"Request failed: {str(e)}") from e
 
-    def _browser_tasks_stream(
+    def _browser_agent_stream(
         self,
         tasks: List[Dict[str, Any]],
         concurrency: Optional[int] = None
     ) -> Iterator[Dict[str, Any]]:
-        """SSE streaming implementation for browser_tasks."""
-        url = f"{self.base_url}/api/v1/browser-tasks"
+        """SSE streaming implementation for browser_agent."""
+        url = f"{self.base_url}/browser-agent"
         payload: Dict[str, Any] = {"tasks": tasks, "stream": True}
         if concurrency is not None:
             payload["concurrency"] = concurrency
@@ -732,6 +793,18 @@ class PredevAPI:
                     current_event = line[7:].strip()
                 elif line.startswith("data: ") and current_event:
                     data = json.loads(line[6:])
+                    # Mid-stream `error` events carry the same
+                    # `{ error, code, actionUrl? }` shape the REST endpoints
+                    # do — surface them as typed exceptions so callers can
+                    # `except InsufficientCreditsError` cleanly.
+                    if current_event == "error" and isinstance(data, dict):
+                        raise exception_for_code(
+                            data.get("code"),
+                            data.get("error")
+                            or data.get("message")
+                            or "Browser agent error",
+                            data.get("actionUrl") or data.get("action_url"),
+                        )
                     yield {"event": current_event, "data": data}
                     current_event = ""
         except requests.RequestException as e:
@@ -896,22 +969,45 @@ class PredevAPI:
             return {"file": (filename, file)}
 
     def _handle_response(self, response: requests.Response) -> None:
-        """Handle API response and raise appropriate exceptions."""
+        """Handle API response and raise appropriate exceptions.
+
+        Browser-task gating errors come back as a structured body
+        ``{"error": ..., "code": ..., "actionUrl": ...}`` (HTTP 402 / 429 /
+        400). We parse the body before short-circuiting on status code so
+        ``code: SUBSCRIPTION_REQUIRED`` becomes :class:`SubscriptionRequiredError`
+        with its ``action_url`` populated, instead of a generic
+        :class:`PredevAPIError`.
+        """
         if response.status_code == 200:
             return
 
+        # Try to parse the structured error body up front.
+        error_body = None
+        error_message = "Unknown error"
+        try:
+            error_body = response.json()
+            error_message = (
+                error_body.get("error")
+                or error_body.get("message")
+                or str(error_body)
+            )
+        except Exception:
+            error_message = response.text or f"HTTP {response.status_code}"
+
+        # Structured `code` wins — covers SUBSCRIPTION_REQUIRED /
+        # INSUFFICIENT_CREDITS / QUEUE_FULL / BATCH_TOO_LARGE / RATE_LIMITED.
+        if isinstance(error_body, dict) and error_body.get("code"):
+            raise exception_for_code(
+                error_body["code"],
+                error_message,
+                error_body.get("actionUrl") or error_body.get("action_url"),
+            )
+
         if response.status_code == 401:
             raise AuthenticationError("Invalid API key")
 
         if response.status_code == 429:
-            raise RateLimitError("Rate limit exceeded")
-
-        try:
-            error_data = response.json()
-            error_message = error_data.get("error") or error_data.get(
-                "message") or str(error_data)
-        except Exception:
-            error_message = response.text or "Unknown error"
+            raise RateLimitError(error_message)
 
         raise PredevAPIError(
             f"API request failed with status {response.status_code}: {error_message}"

predev_api-1.1.0/predev_api/exceptions.py

@@ -0,0 +1,86 @@
+"""
+Custom exceptions for the Pre.dev API client.
+
+Browser-task gating errors carry the same shape as the Node SDK:
+``code`` selects a typed exception, and ``action_url`` is a deep link
+back to pre.dev that auto-opens the right billing modal (subscribe /
+buy credits) when the user lands there. Older endpoints just return
+``{"error": "..."}`` and surface as ``PredevAPIError``.
+"""
+
+from typing import Optional
+
+
+class PredevAPIError(Exception):
+    """Base exception for Pre.dev API errors."""
+    pass
+
+
+class AuthenticationError(PredevAPIError):
+    """Raised when authentication fails (HTTP 401)."""
+    pass
+
+
+class RateLimitError(PredevAPIError):
+    """Raised when a request is rate-limited (HTTP 429, ``code: RATE_LIMITED``)."""
+    pass
+
+
+class SubscriptionRequiredError(PredevAPIError):
+    """HTTP 402, ``code: SUBSCRIPTION_REQUIRED``.
+
+    Trial limit reached on this API key — the user needs an active
+    subscription to keep running browser-agent tasks.
+
+    ``action_url``, when present, is a deep link back to pre.dev that
+    auto-opens the subscribe modal.
+    """
+
+    def __init__(self, message: str, action_url: Optional[str] = None):
+        super().__init__(message)
+        self.action_url = action_url
+
+
+class InsufficientCreditsError(PredevAPIError):
+    """HTTP 402, ``code: INSUFFICIENT_CREDITS``.
+
+    Subscription is fine but the credit balance is too low to cover this
+    request. ``action_url`` deep-links to the credit-purchase modal.
+    """
+
+    def __init__(self, message: str, action_url: Optional[str] = None):
+        super().__init__(message)
+        self.action_url = action_url
+
+
+class QueueFullError(PredevAPIError):
+    """HTTP 429, ``code: QUEUE_FULL`` — too many in-flight tasks for this user."""
+    pass
+
+
+class BatchTooLargeError(PredevAPIError):
+    """HTTP 400, ``code: BATCH_TOO_LARGE`` — request had more tasks than the per-batch maximum."""
+    pass
+
+
+def exception_for_code(
+    code: Optional[str],
+    message: str,
+    action_url: Optional[str] = None,
+) -> PredevAPIError:
+    """Map a structured error ``code`` to the right typed exception.
+
+    Falls back to :class:`PredevAPIError` for unknown codes so callers
+    that just want ``str(e)`` keep working.
+    """
+    if code == "SUBSCRIPTION_REQUIRED":
+        return SubscriptionRequiredError(message, action_url)
+    if code == "INSUFFICIENT_CREDITS":
+        return InsufficientCreditsError(message, action_url)
+    if code == "QUEUE_FULL":
+        return QueueFullError(message)
+    if code == "BATCH_TOO_LARGE":
+        return BatchTooLargeError(message)
+    if code == "RATE_LIMITED":
+        return RateLimitError(message)
+    return PredevAPIError(message)

{predev_api-0.12.0 → predev_api-1.1.0/predev_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: predev-api
-Version: 0.12.0
+Version: 1.1.0
 Summary: Python client for the Pre.dev Architect API - Generate comprehensive software specifications
 Home-page: https://github.com/predotdev/predev-api
 Author: Pre.dev
@@ -502,7 +502,7 @@ For issues, questions, or contributions, please visit the [GitHub repository](ht
 
 ## Browser Tasks
 
-Run browser automation — scrape data, fill forms, navigate pages, extract structured data. Each task navigates a URL, optionally performs actions, and returns typed JSON.
+Run browser automation — navigate, interact, and/or extract data from any web page. Each task navigates a URL, performs actions, and optionally returns typed JSON.
 
 ### Quick start
 
@@ -511,7 +511,7 @@ from predev_api import PredevAPI
 
 client = PredevAPI(api_key="your_api_key")
 
-result = client.browser_tasks([
+result = client.browser_agent([
     {
         "url": "https://news.ycombinator.com",
         "instruction": "Extract the top 5 stories",
@@ -542,7 +542,7 @@ for story in result["results"][0]["data"]["stories"]:
 #### 1. Sync (default) — wait for completion
 
 ```python
-result = client.browser_tasks([
+result = client.browser_agent([
     {"url": "https://example.com", "output": {"type": "object", "properties": {"heading": {"type": "string"}}}}
 ])
 print(result["results"][0]["data"])  # {'heading': 'Example Domain'}
@@ -554,7 +554,7 @@ print(result["totalCreditsUsed"])    # 0.1
 Yields events as the agent runs. Good for showing progress in a UI.
 
 ```python
-for msg in client.browser_tasks(tasks, stream=True):
+for msg in client.browser_agent(tasks, stream=True):
     e, d = msg["event"], msg["data"]
     if e == "task_event":
         # navigation | screenshot | plan | action | validation | done
@@ -574,11 +574,11 @@ Returns the batch ID immediately. Use for long-running batches or background job
 ```python
 import time
 
-r = client.browser_tasks(tasks, run_async=True)
+r = client.browser_agent(tasks, run_async=True)
 # {"id": "batch_abc", "status": "processing", "completed": 0, "total": 3}
 
 while True:
-    state = client.get_browser_tasks(r["id"])
+    state = client.get_browser_agent(r["id"])
     print(f"{state['completed']}/{state['total']}")
     for done in state["results"]:
         print(f"  ✓ {done['url']} -> {done.get('data')}")
@@ -600,27 +600,27 @@ Each task's behavior is determined by which fields are set:
 
 ### Retrieving a batch with the full timeline
 
-Every task records navigation, screenshots, LLM plans, actions, validations. Retrieve for audit, replay, or debugging:
+Every task records navigation, screenshots, LLM plans, actions, validations. Retrieve for audit, replay, or debugging. Screenshots are uploaded to a CDN during execution — retrieved events contain `data["url"]`, not base64.
 
 ```python
-import base64
-
-details = client.get_browser_tasks(batch_id, include_events=True)
+details = client.get_browser_agent(batch_id, include_events=True)
 for result in details["results"]:
     for ev in result.get("events", []):
         if ev["type"] == "screenshot":
-            with open(f"screenshot_iter{ev.get('iteration')}.jpg", "wb") as f:
-                f.write(base64.b64decode(ev["data"]["base64"]))
+            # ev["data"]["url"] is a permanent CDN URL. Use directly in an <img>.
+            print(f"Iter {ev.get('iteration')} screenshot:", ev["data"]["url"])
         elif ev["type"] == "plan":
             print(f"Iter {ev.get('iteration')} plan: {ev['data'].get('notes')}")
 ```
 
+> **Note:** The live SSE stream (`stream=True`) still sends screenshots inline as base64 (`ev["data"]["base64"]`) so live UIs render instantly. The retrieval path (`get_browser_agent`) always returns CDN URLs.
+
 ### Parallel batch example
 
 ```python
 # Scrape 100 URLs with 20 browsers in parallel
 urls = [...100 urls...]
-result = client.browser_tasks(
+result = client.browser_agent(
     [{"url": u, "output": {"type": "object", "properties": {"title": {"type": "string"}}}} for u in urls],
     concurrency=20
 )
@@ -631,10 +631,10 @@ print(f"{result['completed']}/{result['total']} done in {result['totalCreditsUse
 
 | Method | Returns | Use when |
 |---|---|---|
-| `browser_tasks(tasks, concurrency=N)` | dict | Default — wait for completion |
-| `browser_tasks(tasks, stream=True)` | iterator of SSE dicts | Live UI showing execution timeline |
-| `browser_tasks(tasks, run_async=True)` | dict (empty results, returned immediately) | Long batches, background jobs |
-| `get_browser_tasks(batch_id, include_events=False)` | dict | Poll progress or retrieve a completed batch |
+| `browser_agent(tasks, concurrency=N)` | dict | Default — wait for completion |
+| `browser_agent(tasks, stream=True)` | iterator of SSE dicts | Live UI showing execution timeline |
+| `browser_agent(tasks, run_async=True)` | dict (empty results, returned immediately) | Long batches, background jobs |
+| `get_browser_agent(batch_id, include_events=False)` | dict | Poll progress or retrieve a completed batch |
 
 ### Task result statuses
 
@@ -653,3 +653,51 @@ print(f"{result['completed']}/{result['total']} done in {result['totalCreditsUse
 - Minimum: **0.1 credits per task** ($0.01)
 - 10x margin on underlying LLM + sandbox compute
 - 1 credit = $0.10
+
+### Error handling
+
+The browser-task endpoints raise typed exceptions for the most common
+gating cases. Every billing-gate exception carries an `action_url` — a
+deep link back to pre.dev that auto-opens the right modal (subscribe /
+buy credits) when the user lands there:
+
+```python
+from predev_api import (
+    PredevAPI,
+    InsufficientCreditsError,
+    SubscriptionRequiredError,
+    RateLimitError,
+    QueueFullError,
+)
+import webbrowser
+
+client = PredevAPI(api_key="your_pre.dev_api_key")
+
+try:
+    client.browser_agent([{"url": "https://example.com", "instruction": "extract h1"}])
+except InsufficientCreditsError as e:
+    # Send the user to the credits modal — `action_url` is the canonical link.
+    if e.action_url:
+        webbrowser.open(e.action_url)
+except SubscriptionRequiredError as e:
+    if e.action_url:
+        webbrowser.open(e.action_url)
+except RateLimitError:
+    pass  # back off and retry
+except QueueFullError:
+    pass  # wait for in-flight tasks to drain
+```
+
+Mid-stream errors on the SSE stream raise the same typed exceptions, so a
+`for msg in client.browser_agent(..., stream=True):` loop wrapped in
+`try/except` is enough — no special event handling required.
+
+| Exception | HTTP | `code` |
+|---|---|---|
+| `SubscriptionRequiredError` | 402 | `SUBSCRIPTION_REQUIRED` |
+| `InsufficientCreditsError` | 402 | `INSUFFICIENT_CREDITS` |
+| `RateLimitError` | 429 | `RATE_LIMITED` |
+| `QueueFullError` | 429 | `QUEUE_FULL` |
+| `BatchTooLargeError` | 400 | `BATCH_TOO_LARGE` |
+| `AuthenticationError` | 401 | — |
+| `PredevAPIError` | other | — |

{predev_api-0.12.0 → predev_api-1.1.0}/setup.py

@@ -9,7 +9,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="predev-api",
-    version="0.12.0",
+    version="1.1.0",
     author="Pre.dev",
     author_email="support@pre.dev",
     description="Python client for the Pre.dev Architect API - Generate comprehensive software specifications",

predev_api-0.12.0/predev_api/exceptions.py

@@ -1,18 +0,0 @@
-"""
-Custom exceptions for the Pre.dev API client
-"""
-
-
-class PredevAPIError(Exception):
-    """Base exception for Pre.dev API errors."""
-    pass
-
-
-class AuthenticationError(PredevAPIError):
-    """Raised when authentication fails."""
-    pass
-
-
-class RateLimitError(PredevAPIError):
-    """Raised when rate limit is exceeded."""
-    pass