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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: predev-api
-Version: 0.11.0
+Version: 0.12.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
@@ -38,18 +38,27 @@ Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
-# pre.dev Architect API - Python Client
+# pre.dev API — Python Client
 
-A Python client library for the [Pre.dev Architect API](https://docs.pre.dev). Generate comprehensive software specifications using AI-powered analysis.
+Python client for the [Pre.dev API](https://docs.pre.dev) — AI-powered software specs + browser automation.
 
 ## Features
 
-- 🚀 **Fast Spec**: Generate comprehensive specifications quickly - perfect for MVPs and prototypes
-- 🔍 **Deep Spec**: Generate ultra-detailed specifications for complex systems with enterprise-grade depth
-- ⚡ **Async Spec**: Non-blocking async methods for long-running requests
-- 📊 **Status Tracking**: Check the status of async specification generation requests
-- ✨ **Type Hints**: Full type annotations for better IDE support
-- 🛡️ **Error Handling**: Custom exceptions for different error scenarios
+**Specs**
+- 🚀 **Fast Spec**: Comprehensive specifications for MVPs and prototypes
+- 🔍 **Deep Spec**: Ultra-detailed specifications for complex systems
+- ⚡ **Async Spec**: Non-blocking async methods with status polling
+- 📄 File upload support (PDFs, docs, images as reference context)
+
+**Browser automation (NEW)**
+- 🌐 **Browser Tasks**: Scrape, fill forms, navigate pages with structured JSON output
+- 📡 **SSE streaming**: Watch execution live — screenshots, plans, actions
+- ⏱ **Async mode**: Fire-and-forget, poll for progress
+- 🔁 **Retrieval**: Get any past task with full timeline for audit/replay
+
+**Quality of life**
+- ✨ Full type hints
+- 🛡 Custom exceptions for auth / rate limit / API errors
 
 ## Installation
 
@@ -357,10 +366,6 @@ class SpecResponse:
 
     # Integration URLs (when completed)
     predevUrl: Optional[str] = None               # Link to pre.dev project
-    lovableUrl: Optional[str] = None              # Link to generate with Lovable
-    cursorUrl: Optional[str] = None               # Link to generate with Cursor
-    v0Url: Optional[str] = None                   # Link to generate with v0
-    boltUrl: Optional[str] = None                 # Link to generate with Bolt
 
     # Documentation (when doc_urls provided)
     zippedDocsUrls: Optional[List[ZippedDocsUrl]] = None
@@ -494,3 +499,157 @@ For more information about the Pre.dev Architect API, visit:
 ## Support
 
 For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/predotdev/predev-api).
+
+## 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.
+
+### Quick start
+
+```python
+from predev_api import PredevAPI
+
+client = PredevAPI(api_key="your_api_key")
+
+result = client.browser_tasks([
+    {
+        "url": "https://news.ycombinator.com",
+        "instruction": "Extract the top 5 stories",
+        "output": {
+            "type": "object",
+            "properties": {
+                "stories": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "title": {"type": "string"},
+                            "points": {"type": "number"},
+                        },
+                    },
+                },
+            },
+        },
+    }
+])
+
+for story in result["results"][0]["data"]["stories"]:
+    print(f"{story['title']} ({story['points']} pts)")
+```
+
+### Three execution modes
+
+#### 1. Sync (default) — wait for completion
+
+```python
+result = client.browser_tasks([
+    {"url": "https://example.com", "output": {"type": "object", "properties": {"heading": {"type": "string"}}}}
+])
+print(result["results"][0]["data"])  # {'heading': 'Example Domain'}
+print(result["totalCreditsUsed"])    # 0.1
+```
+
+#### 2. Stream (`stream=True`) — live timeline via SSE
+
+Yields events as the agent runs. Good for showing progress in a UI.
+
+```python
+for msg in client.browser_tasks(tasks, stream=True):
+    e, d = msg["event"], msg["data"]
+    if e == "task_event":
+        # navigation | screenshot | plan | action | validation | done
+        print(f"[{d['type']}]", d.get("data"))
+    elif e == "task_result":
+        print(f"Task {d['taskIndex']} done:", d.get("data"))
+    elif e == "done":
+        print("Batch complete:", d["totalCreditsUsed"], "credits")
+    elif e == "error":
+        print("Batch error:", d)
+```
+
+#### 3. Async (`run_async=True`) — fire-and-forget, poll for progress
+
+Returns the batch ID immediately. Use for long-running batches or background jobs.
+
+```python
+import time
+
+r = client.browser_tasks(tasks, run_async=True)
+# {"id": "batch_abc", "status": "processing", "completed": 0, "total": 3}
+
+while True:
+    state = client.get_browser_tasks(r["id"])
+    print(f"{state['completed']}/{state['total']}")
+    for done in state["results"]:
+        print(f"  ✓ {done['url']} -> {done.get('data')}")
+    if state["status"] == "completed":
+        break
+    time.sleep(1)
+```
+
+### Task shapes
+
+Each task's behavior is determined by which fields are set:
+
+| Fields | Shape | Example |
+|---|---|---|
+| `url` + `output` | **Scrape** | Extract structured data from a page |
+| `url` + `instruction` | **Act** | Click, navigate, search |
+| `url` + `instruction` + `input` | **Form fill** | Fill & submit a form |
+| `url` + `instruction` + `output` | **Act + extract** | Navigate then extract data |
+
+### Retrieving a batch with the full timeline
+
+Every task records navigation, screenshots, LLM plans, actions, validations. Retrieve for audit, replay, or debugging:
+
+```python
+import base64
+
+details = client.get_browser_tasks(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"]))
+        elif ev["type"] == "plan":
+            print(f"Iter {ev.get('iteration')} plan: {ev['data'].get('notes')}")
+```
+
+### Parallel batch example
+
+```python
+# Scrape 100 URLs with 20 browsers in parallel
+urls = [...100 urls...]
+result = client.browser_tasks(
+    [{"url": u, "output": {"type": "object", "properties": {"title": {"type": "string"}}}} for u in urls],
+    concurrency=20
+)
+print(f"{result['completed']}/{result['total']} done in {result['totalCreditsUsed']} credits")
+```
+
+### Browser task methods
+
+| 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 |
+
+### Task result statuses
+
+| Status | Meaning |
+|---|---|
+| `SUCCESS` | Task completed, data extracted |
+| `BLOCKED` | Page blocked automation (bot detection) |
+| `TIMEOUT` | Task exceeded time limit |
+| `LOOP` | Agent detected it was stuck in a loop |
+| `ERROR` | Unexpected error |
+| `NO_TARGET` | Could not find target elements |
+| `CAPTCHA_FAILED` | CAPTCHA solve failed |
+
+### Pricing
+
+- Minimum: **0.1 credits per task** ($0.01)
+- 10x margin on underlying LLM + sandbox compute
+- 1 credit = $0.10

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

@@ -1,15 +1,24 @@
-# pre.dev Architect API - Python Client
+# pre.dev API — Python Client
 
-A Python client library for the [Pre.dev Architect API](https://docs.pre.dev). Generate comprehensive software specifications using AI-powered analysis.
+Python client for the [Pre.dev API](https://docs.pre.dev) — AI-powered software specs + browser automation.
 
 ## Features
 
-- 🚀 **Fast Spec**: Generate comprehensive specifications quickly - perfect for MVPs and prototypes
-- 🔍 **Deep Spec**: Generate ultra-detailed specifications for complex systems with enterprise-grade depth
-- ⚡ **Async Spec**: Non-blocking async methods for long-running requests
-- 📊 **Status Tracking**: Check the status of async specification generation requests
-- ✨ **Type Hints**: Full type annotations for better IDE support
-- 🛡️ **Error Handling**: Custom exceptions for different error scenarios
+**Specs**
+- 🚀 **Fast Spec**: Comprehensive specifications for MVPs and prototypes
+- 🔍 **Deep Spec**: Ultra-detailed specifications for complex systems
+- ⚡ **Async Spec**: Non-blocking async methods with status polling
+- 📄 File upload support (PDFs, docs, images as reference context)
+
+**Browser automation (NEW)**
+- 🌐 **Browser Tasks**: Scrape, fill forms, navigate pages with structured JSON output
+- 📡 **SSE streaming**: Watch execution live — screenshots, plans, actions
+- ⏱ **Async mode**: Fire-and-forget, poll for progress
+- 🔁 **Retrieval**: Get any past task with full timeline for audit/replay
+
+**Quality of life**
+- ✨ Full type hints
+- 🛡 Custom exceptions for auth / rate limit / API errors
 
 ## Installation
 
@@ -317,10 +326,6 @@ class SpecResponse:
 
     # Integration URLs (when completed)
     predevUrl: Optional[str] = None               # Link to pre.dev project
-    lovableUrl: Optional[str] = None              # Link to generate with Lovable
-    cursorUrl: Optional[str] = None               # Link to generate with Cursor
-    v0Url: Optional[str] = None                   # Link to generate with v0
-    boltUrl: Optional[str] = None                 # Link to generate with Bolt
 
     # Documentation (when doc_urls provided)
     zippedDocsUrls: Optional[List[ZippedDocsUrl]] = None
@@ -454,3 +459,157 @@ For more information about the Pre.dev Architect API, visit:
 ## Support
 
 For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/predotdev/predev-api).
+
+## 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.
+
+### Quick start
+
+```python
+from predev_api import PredevAPI
+
+client = PredevAPI(api_key="your_api_key")
+
+result = client.browser_tasks([
+    {
+        "url": "https://news.ycombinator.com",
+        "instruction": "Extract the top 5 stories",
+        "output": {
+            "type": "object",
+            "properties": {
+                "stories": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "title": {"type": "string"},
+                            "points": {"type": "number"},
+                        },
+                    },
+                },
+            },
+        },
+    }
+])
+
+for story in result["results"][0]["data"]["stories"]:
+    print(f"{story['title']} ({story['points']} pts)")
+```
+
+### Three execution modes
+
+#### 1. Sync (default) — wait for completion
+
+```python
+result = client.browser_tasks([
+    {"url": "https://example.com", "output": {"type": "object", "properties": {"heading": {"type": "string"}}}}
+])
+print(result["results"][0]["data"])  # {'heading': 'Example Domain'}
+print(result["totalCreditsUsed"])    # 0.1
+```
+
+#### 2. Stream (`stream=True`) — live timeline via SSE
+
+Yields events as the agent runs. Good for showing progress in a UI.
+
+```python
+for msg in client.browser_tasks(tasks, stream=True):
+    e, d = msg["event"], msg["data"]
+    if e == "task_event":
+        # navigation | screenshot | plan | action | validation | done
+        print(f"[{d['type']}]", d.get("data"))
+    elif e == "task_result":
+        print(f"Task {d['taskIndex']} done:", d.get("data"))
+    elif e == "done":
+        print("Batch complete:", d["totalCreditsUsed"], "credits")
+    elif e == "error":
+        print("Batch error:", d)
+```
+
+#### 3. Async (`run_async=True`) — fire-and-forget, poll for progress
+
+Returns the batch ID immediately. Use for long-running batches or background jobs.
+
+```python
+import time
+
+r = client.browser_tasks(tasks, run_async=True)
+# {"id": "batch_abc", "status": "processing", "completed": 0, "total": 3}
+
+while True:
+    state = client.get_browser_tasks(r["id"])
+    print(f"{state['completed']}/{state['total']}")
+    for done in state["results"]:
+        print(f"  ✓ {done['url']} -> {done.get('data')}")
+    if state["status"] == "completed":
+        break
+    time.sleep(1)
+```
+
+### Task shapes
+
+Each task's behavior is determined by which fields are set:
+
+| Fields | Shape | Example |
+|---|---|---|
+| `url` + `output` | **Scrape** | Extract structured data from a page |
+| `url` + `instruction` | **Act** | Click, navigate, search |
+| `url` + `instruction` + `input` | **Form fill** | Fill & submit a form |
+| `url` + `instruction` + `output` | **Act + extract** | Navigate then extract data |
+
+### Retrieving a batch with the full timeline
+
+Every task records navigation, screenshots, LLM plans, actions, validations. Retrieve for audit, replay, or debugging:
+
+```python
+import base64
+
+details = client.get_browser_tasks(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"]))
+        elif ev["type"] == "plan":
+            print(f"Iter {ev.get('iteration')} plan: {ev['data'].get('notes')}")
+```
+
+### Parallel batch example
+
+```python
+# Scrape 100 URLs with 20 browsers in parallel
+urls = [...100 urls...]
+result = client.browser_tasks(
+    [{"url": u, "output": {"type": "object", "properties": {"title": {"type": "string"}}}} for u in urls],
+    concurrency=20
+)
+print(f"{result['completed']}/{result['total']} done in {result['totalCreditsUsed']} credits")
+```
+
+### Browser task methods
+
+| 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 |
+
+### Task result statuses
+
+| Status | Meaning |
+|---|---|
+| `SUCCESS` | Task completed, data extracted |
+| `BLOCKED` | Page blocked automation (bot detection) |
+| `TIMEOUT` | Task exceeded time limit |
+| `LOOP` | Agent detected it was stuck in a loop |
+| `ERROR` | Unexpected error |
+| `NO_TARGET` | Could not find target elements |
+| `CAPTCHA_FAILED` | CAPTCHA solve failed |
+
+### Pricing
+
+- Minimum: **0.1 credits per task** ($0.01)
+- 10x margin on underlying LLM + sandbox compute
+- 1 credit = $0.10

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

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

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

@@ -2,8 +2,9 @@
 Client for the Pre.dev Architect API
 """
 
-from typing import Optional, Dict, Any, Literal, List, Union, BinaryIO
+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
 
@@ -131,7 +132,7 @@ class SpecGraphNode:
     label: str = ""
     type: Optional[str] = None
     description: Optional[str] = None
-    level: Optional[str] = None
+    level: Optional[int] = None
     hours: Optional[float] = None
 
 
@@ -199,10 +200,6 @@ class SpecResponse:
     architectureInfographicUrl: Optional[str] = None
 
     predevUrl: Optional[str] = None
-    lovableUrl: Optional[str] = None
-    cursorUrl: Optional[str] = None
-    v0Url: Optional[str] = None
-    boltUrl: Optional[str] = None
 
     zippedDocsUrls: Optional[List['ZippedDocsUrl']] = None
 
@@ -611,6 +608,135 @@ class PredevAPI:
         except requests.RequestException as e:
             raise PredevAPIError(f"Request failed: {str(e)}") from e
 
+    def get_browser_tasks(
+        self,
+        batch_id: str,
+        include_events: bool = False
+    ) -> Dict[str, Any]:
+        """
+        Get the status + results of a browser tasks batch by ID.
+
+        Works for both in-progress and completed batches - use with 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
+            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}"
+        try:
+            response = requests.get(url, headers=self.headers, 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_tasks(
+        self,
+        tasks: List[Dict[str, Any]],
+        concurrency: Optional[int] = None,
+        stream: bool = False,
+        run_async: bool = False
+    ) -> Union[Dict[str, Any], Iterator[Dict[str, Any]]]:
+        """
+        Run browser 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.
+
+        Args:
+            tasks: Array of tasks. Each task has:
+                - url (str, required): URL to navigate to
+                - instruction (str, optional): What to do on the page
+                - input (dict, optional): Form values / input data
+                - output (dict, optional): JSON Schema for structured output
+            concurrency: Parallel browsers (default 5, max 20)
+            stream: If True, returns an iterator of SSE events instead of
+                    waiting for all tasks to complete
+
+        Returns:
+            Without stream: Dict with id, total, completed, results, totalCost, 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
+                - event='done': batch complete (data is the full result)
+                - event='error': fatal error
+
+        Example:
+            >>> # Standard mode
+            >>> result = client.browser_tasks([
+            ...     {"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):
+            ...     if msg["event"] == "done":
+            ...         print("Done:", msg["data"]["totalCreditsUsed"], "credits")
+        """
+        if stream:
+            return self._browser_tasks_stream(tasks, concurrency)
+
+        url = f"{self.base_url}/api/v1/browser-tasks"
+        payload: Dict[str, Any] = {"tasks": tasks}
+        if concurrency is not None:
+            payload["concurrency"] = concurrency
+        if run_async:
+            payload["async"] = True
+
+        try:
+            response = requests.post(
+                url,
+                headers=self.headers,
+                json=payload,
+                timeout=300
+            )
+            self._handle_response(response)
+            return response.json()
+        except requests.RequestException as e:
+            raise PredevAPIError(f"Request failed: {str(e)}") from e
+
+    def _browser_tasks_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"
+        payload: Dict[str, Any] = {"tasks": tasks, "stream": True}
+        if concurrency is not None:
+            payload["concurrency"] = concurrency
+
+        try:
+            response = requests.post(
+                url,
+                headers=self.headers,
+                json=payload,
+                stream=True,
+                timeout=300
+            )
+            self._handle_response(response)
+
+            current_event = ""
+            for line in response.iter_lines(decode_unicode=True):
+                if not line:
+                    continue
+                if line.startswith(":"):
+                    continue
+                if line.startswith("event: "):
+                    current_event = line[7:].strip()
+                elif line.startswith("data: ") and current_event:
+                    data = json.loads(line[6:])
+                    yield {"event": current_event, "data": data}
+                    current_event = ""
+        except requests.RequestException as e:
+            raise PredevAPIError(f"Request failed: {str(e)}") from e
+
     def _make_request(
         self,
         endpoint: str,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: predev-api
-Version: 0.11.0
+Version: 0.12.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
@@ -38,18 +38,27 @@ Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
-# pre.dev Architect API - Python Client
+# pre.dev API — Python Client
 
-A Python client library for the [Pre.dev Architect API](https://docs.pre.dev). Generate comprehensive software specifications using AI-powered analysis.
+Python client for the [Pre.dev API](https://docs.pre.dev) — AI-powered software specs + browser automation.
 
 ## Features
 
-- 🚀 **Fast Spec**: Generate comprehensive specifications quickly - perfect for MVPs and prototypes
-- 🔍 **Deep Spec**: Generate ultra-detailed specifications for complex systems with enterprise-grade depth
-- ⚡ **Async Spec**: Non-blocking async methods for long-running requests
-- 📊 **Status Tracking**: Check the status of async specification generation requests
-- ✨ **Type Hints**: Full type annotations for better IDE support
-- 🛡️ **Error Handling**: Custom exceptions for different error scenarios
+**Specs**
+- 🚀 **Fast Spec**: Comprehensive specifications for MVPs and prototypes
+- 🔍 **Deep Spec**: Ultra-detailed specifications for complex systems
+- ⚡ **Async Spec**: Non-blocking async methods with status polling
+- 📄 File upload support (PDFs, docs, images as reference context)
+
+**Browser automation (NEW)**
+- 🌐 **Browser Tasks**: Scrape, fill forms, navigate pages with structured JSON output
+- 📡 **SSE streaming**: Watch execution live — screenshots, plans, actions
+- ⏱ **Async mode**: Fire-and-forget, poll for progress
+- 🔁 **Retrieval**: Get any past task with full timeline for audit/replay
+
+**Quality of life**
+- ✨ Full type hints
+- 🛡 Custom exceptions for auth / rate limit / API errors
 
 ## Installation
 
@@ -357,10 +366,6 @@ class SpecResponse:
 
     # Integration URLs (when completed)
     predevUrl: Optional[str] = None               # Link to pre.dev project
-    lovableUrl: Optional[str] = None              # Link to generate with Lovable
-    cursorUrl: Optional[str] = None               # Link to generate with Cursor
-    v0Url: Optional[str] = None                   # Link to generate with v0
-    boltUrl: Optional[str] = None                 # Link to generate with Bolt
 
     # Documentation (when doc_urls provided)
     zippedDocsUrls: Optional[List[ZippedDocsUrl]] = None
@@ -494,3 +499,157 @@ For more information about the Pre.dev Architect API, visit:
 ## Support
 
 For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/predotdev/predev-api).
+
+## 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.
+
+### Quick start
+
+```python
+from predev_api import PredevAPI
+
+client = PredevAPI(api_key="your_api_key")
+
+result = client.browser_tasks([
+    {
+        "url": "https://news.ycombinator.com",
+        "instruction": "Extract the top 5 stories",
+        "output": {
+            "type": "object",
+            "properties": {
+                "stories": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "title": {"type": "string"},
+                            "points": {"type": "number"},
+                        },
+                    },
+                },
+            },
+        },
+    }
+])
+
+for story in result["results"][0]["data"]["stories"]:
+    print(f"{story['title']} ({story['points']} pts)")
+```
+
+### Three execution modes
+
+#### 1. Sync (default) — wait for completion
+
+```python
+result = client.browser_tasks([
+    {"url": "https://example.com", "output": {"type": "object", "properties": {"heading": {"type": "string"}}}}
+])
+print(result["results"][0]["data"])  # {'heading': 'Example Domain'}
+print(result["totalCreditsUsed"])    # 0.1
+```
+
+#### 2. Stream (`stream=True`) — live timeline via SSE
+
+Yields events as the agent runs. Good for showing progress in a UI.
+
+```python
+for msg in client.browser_tasks(tasks, stream=True):
+    e, d = msg["event"], msg["data"]
+    if e == "task_event":
+        # navigation | screenshot | plan | action | validation | done
+        print(f"[{d['type']}]", d.get("data"))
+    elif e == "task_result":
+        print(f"Task {d['taskIndex']} done:", d.get("data"))
+    elif e == "done":
+        print("Batch complete:", d["totalCreditsUsed"], "credits")
+    elif e == "error":
+        print("Batch error:", d)
+```
+
+#### 3. Async (`run_async=True`) — fire-and-forget, poll for progress
+
+Returns the batch ID immediately. Use for long-running batches or background jobs.
+
+```python
+import time
+
+r = client.browser_tasks(tasks, run_async=True)
+# {"id": "batch_abc", "status": "processing", "completed": 0, "total": 3}
+
+while True:
+    state = client.get_browser_tasks(r["id"])
+    print(f"{state['completed']}/{state['total']}")
+    for done in state["results"]:
+        print(f"  ✓ {done['url']} -> {done.get('data')}")
+    if state["status"] == "completed":
+        break
+    time.sleep(1)
+```
+
+### Task shapes
+
+Each task's behavior is determined by which fields are set:
+
+| Fields | Shape | Example |
+|---|---|---|
+| `url` + `output` | **Scrape** | Extract structured data from a page |
+| `url` + `instruction` | **Act** | Click, navigate, search |
+| `url` + `instruction` + `input` | **Form fill** | Fill & submit a form |
+| `url` + `instruction` + `output` | **Act + extract** | Navigate then extract data |
+
+### Retrieving a batch with the full timeline
+
+Every task records navigation, screenshots, LLM plans, actions, validations. Retrieve for audit, replay, or debugging:
+
+```python
+import base64
+
+details = client.get_browser_tasks(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"]))
+        elif ev["type"] == "plan":
+            print(f"Iter {ev.get('iteration')} plan: {ev['data'].get('notes')}")
+```
+
+### Parallel batch example
+
+```python
+# Scrape 100 URLs with 20 browsers in parallel
+urls = [...100 urls...]
+result = client.browser_tasks(
+    [{"url": u, "output": {"type": "object", "properties": {"title": {"type": "string"}}}} for u in urls],
+    concurrency=20
+)
+print(f"{result['completed']}/{result['total']} done in {result['totalCreditsUsed']} credits")
+```
+
+### Browser task methods
+
+| 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 |
+
+### Task result statuses
+
+| Status | Meaning |
+|---|---|
+| `SUCCESS` | Task completed, data extracted |
+| `BLOCKED` | Page blocked automation (bot detection) |
+| `TIMEOUT` | Task exceeded time limit |
+| `LOOP` | Agent detected it was stuck in a loop |
+| `ERROR` | Unexpected error |
+| `NO_TARGET` | Could not find target elements |
+| `CAPTCHA_FAILED` | CAPTCHA solve failed |
+
+### Pricing
+
+- Minimum: **0.1 credits per task** ($0.01)
+- 10x margin on underlying LLM + sandbox compute
+- 1 credit = $0.10

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

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