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

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

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

{predev_api-0.12.0 → predev_api-1.0.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
 

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

@@ -29,7 +29,7 @@ from .client import (
 )
 from .exceptions import PredevAPIError, AuthenticationError, RateLimitError
 
-__version__ = "0.11.1"
+__version__ = "1.0.0"
 __all__ = [
     "PredevAPI",
     "PredevAPIError",

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

@@ -608,27 +608,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
         """
         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 +636,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 +692,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,6 +706,8 @@ 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
@@ -669,20 +719,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 +751,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

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

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

{predev_api-0.12.0 → predev_api-1.0.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.0.0",
     author="Pre.dev",
     author_email="support@pre.dev",
     description="Python client for the Pre.dev Architect API - Generate comprehensive software specifications",