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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: predev-api
-Version: 1.0.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
@@ -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-1.0.0 → predev_api-1.1.0}/README.md

@@ -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-1.0.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__ = "1.0.0"
+__version__ = "1.1.0"
 __all__ = [
     "PredevAPI",
     "PredevAPIError",
     "AuthenticationError",
     "RateLimitError",
+    "SubscriptionRequiredError",
+    "InsufficientCreditsError",
+    "QueueFullError",
+    "BatchTooLargeError",
+    "exception_for_code",
     "ZippedDocsUrl",
     "SpecCoreFunctionality",
     "SpecTechStackItem",

{predev_api-1.0.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
 
 
@@ -625,7 +636,7 @@ class PredevAPI:
             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}/browser-agent/{batch_id}{qs}"
@@ -710,7 +721,7 @@ class PredevAPI:
                     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
@@ -782,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:
@@ -946,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-1.0.0 → predev_api-1.1.0/predev_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: predev-api
-Version: 1.0.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
@@ -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-1.0.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="1.0.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-1.0.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