Add CI, tests, and improve SDK docs and schemas

Co-authored-by: Shri Sukhani <shrisukhani@users.noreply.github.com>

Author: cursoragent

.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - master
+      - "cursor/**"
+
+jobs:
+  lint-test-build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.12"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install . pytest ruff build
+
+      - name: Lint
+        run: python -m ruff check .
+
+      - name: Test
+        run: python -m pytest -q
+
+      - name: Build package
+        run: python -m build

README.md

@@ -1,105 +1,128 @@
 # Hyperbrowser Python SDK
 
-Checkout the full documentation [here](https://hyperbrowser.ai/docs)
+Python SDK for the Hyperbrowser API.
 
-## Installation
+- Full docs: https://hyperbrowser.ai/docs
+- Package: https://pypi.org/project/hyperbrowser/
 
-Currently Hyperbrowser supports creating a browser session in two ways:
+## Requirements
 
-- Async Client
-- Sync Client
+- Python `>=3.9`
 
-It can be installed from `pypi` by running :
+## Installation
 
-```shell
+```bash
 pip install hyperbrowser
 ```
 
 ## Configuration
 
-Both the sync and async client follow similar configuration params
+You can pass credentials directly, or use environment variables.
+
+```bash
+export HYPERBROWSER_API_KEY="your_api_key"
+export HYPERBROWSER_BASE_URL="https://api.hyperbrowser.ai" # optional
+```
+
+## Clients
 
-### API Key
-The API key can be configured either from the constructor arguments or environment variables using `HYPERBROWSER_API_KEY`
+The SDK provides both sync and async clients with mirrored APIs:
 
-## Usage
+- `Hyperbrowser` (sync)
+- `AsyncHyperbrowser` (async)
 
-### Async
+### Sync quickstart
+
+```python
+from hyperbrowser import Hyperbrowser
+
+with Hyperbrowser(api_key="your_api_key") as client:
+    session = client.sessions.create()
+    print(session.id, session.ws_endpoint)
+    client.sessions.stop(session.id)
+```
+
+### Async quickstart
 
 ```python
 import asyncio
-from pyppeteer import connect
 from hyperbrowser import AsyncHyperbrowser
 
-HYPERBROWSER_API_KEY = "test-key"
-
-async def main():
-    async with AsyncHyperbrowser(api_key=HYPERBROWSER_API_KEY) as client:
+async def main() -> None:
+    async with AsyncHyperbrowser(api_key="your_api_key") as client:
         session = await client.sessions.create()
+        print(session.id, session.ws_endpoint)
+        await client.sessions.stop(session.id)
 
-        ws_endpoint = session.ws_endpoint
-        browser = await connect(browserWSEndpoint=ws_endpoint, defaultViewport=None)
+asyncio.run(main())
+```
 
-        # Get pages
-        pages = await browser.pages()
-        if not pages:
-            raise Exception("No pages available")
+## Main manager surface
 
-        page = pages[0]
+Both clients expose:
 
-        # Navigate to a website
-        print("Navigating to Hacker News...")
-        await page.goto("https://news.ycombinator.com/")
-        page_title = await page.title()
-        print("Page title:", page_title)
+- `client.sessions`
+- `client.scrape` (+ `client.scrape.batch`)
+- `client.crawl`
+- `client.extract`
+- `client.web` (+ `client.web.batch_fetch`, `client.web.crawl`)
+- `client.agents` (`browser_use`, `cua`, `claude_computer_use`, `gemini_computer_use`, `hyper_agent`)
+- `client.profiles`
+- `client.extensions`
+- `client.team`
+- `client.computer_action`
 
-        await page.close()
-        await browser.disconnect()
-        await client.sessions.stop(session.id)
-        print("Session completed!")
+## Job polling (`start_and_wait`)
 
-# Run the asyncio event loop
-asyncio.get_event_loop().run_until_complete(main())
-```
-### Sync
+Long-running APIs expose `start_and_wait(...)`.
+
+These methods now support explicit polling controls:
+
+- `poll_interval_seconds` (default `2.0`)
+- `max_wait_seconds` (default `600.0`)
+
+Example:
 
 ```python
-from playwright.sync_api import sync_playwright
 from hyperbrowser import Hyperbrowser
+from hyperbrowser.models import StartExtractJobParams
+
+with Hyperbrowser(api_key="your_api_key") as client:
+    result = client.extract.start_and_wait(
+        StartExtractJobParams(
+            urls=["https://hyperbrowser.ai"],
+            prompt="Extract the main headline",
+        ),
+        poll_interval_seconds=1.5,
+        max_wait_seconds=300,
+    )
+    print(result.status, result.data)
+```
 
-HYPERBROWSER_API_KEY = "test-key"
+## Error handling
 
-def main():
-    client = Hyperbrowser(api_key=HYPERBROWSER_API_KEY)
-    session = client.sessions.create()
+SDK errors are raised as `HyperbrowserError`.
 
-    ws_endpoint = session.ws_endpoint
-
-    # Launch Playwright and connect to the remote browser
-    with sync_playwright() as p:
-        browser = p.chromium.connect_over_cdp(ws_endpoint)
-        context = browser.new_context()
-        
-        # Get the first page or create a new one
-        if len(context.pages) == 0:
-            page = context.new_page()
-        else:
-            page = context.pages[0]
-        
-        # Navigate to a website
-        print("Navigating to Hacker News...")
-        page.goto("https://news.ycombinator.com/")
-        page_title = page.title()
-        print("Page title:", page_title)
-        
-        page.close()
-        browser.close()
-        print("Session completed!")
-    client.sessions.stop(session.id)
+```python
+from hyperbrowser import Hyperbrowser
+from hyperbrowser.exceptions import HyperbrowserError
 
-# Run the asyncio event loop
-main()
+try:
+    with Hyperbrowser(api_key="invalid") as client:
+        client.team.get_credit_info()
+except HyperbrowserError as exc:
+    print(exc)
 ```
+
+## Development
+
+```bash
+pip install -e . pytest ruff build
+python -m ruff check .
+python -m pytest -q
+python -m build
+```
+
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+MIT — see [LICENSE](LICENSE).

hyperbrowser/client/sync.py

@@ -40,3 +40,9 @@ def __init__(
 
     def close(self) -> None:
         self.transport.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()

hyperbrowser/py.typed

@@ -0,0 +1 @@
+

hyperbrowser/tools/schema.py

@@ -32,12 +32,7 @@ def get_scrape_options(formats: Optional[List[scrape_types]] = None):
                 "description": "Whether to only return the main content of the page. If true, only the main content of the page will be returned, excluding any headers, navigation menus,footers, or other non-main content.",
             },
         },
-        "required": [
-            "include_tags",
-            "exclude_tags",
-            "only_main_content",
-            "formats",
-        ],
+        "required": [],
         "additionalProperties": False,
     }
 
@@ -51,7 +46,7 @@ def get_scrape_options(formats: Optional[List[scrape_types]] = None):
         },
         "scrape_options": get_scrape_options(),
     },
-    "required": ["url", "scrape_options"],
+    "required": ["url"],
     "additionalProperties": False,
 }
 
@@ -103,15 +98,7 @@ def get_scrape_options(formats: Optional[List[scrape_types]] = None):
         },
         "scrape_options": get_scrape_options(),
     },
-    "required": [
-        "url",
-        "max_pages",
-        "follow_links",
-        "ignore_sitemap",
-        "exclude_patterns",
-        "include_patterns",
-        "scrape_options",
-    ],
+    "required": ["url"],
     "additionalProperties": False,
 }
 
@@ -130,15 +117,18 @@ def get_scrape_options(formats: Optional[List[scrape_types]] = None):
             "description": "A prompt describing how you want the data structured, or what you want to extract from the urls provided. Can also be used to guide the extraction process. For multi-source queries, structure this prompt to request unified, comparative, or aggregated information across all provided URLs.",
         },
         "schema": {
-            "type": "string",
-            "description": "A strict json schema you want the returned data to be structured as. For multi-source extraction, design this schema to accommodate information from all URLs in a single structure. Ensure that this is a proper json schema, and the root level should be of type 'object'.",
+            "anyOf": [
+                {"type": "object"},
+                {"type": "string"},
+            ],
+            "description": "A strict JSON schema for the response shape. This can be either a JSON object schema or a JSON string that can be parsed into an object schema. For multi-source extraction, design this schema to accommodate information from all URLs in a single structure.",
         },
         "max_links": {
             "type": "number",
             "description": "The maximum number of links to look for if performing a crawl for any given url in the urls list.",
         },
     },
-    "required": ["urls", "prompt", "schema", "max_links"],
+    "required": ["urls"],
     "additionalProperties": False,
 }
 
@@ -147,12 +137,19 @@ def get_scrape_options(formats: Optional[List[scrape_types]] = None):
     "enum": [
         "gpt-4o",
         "gpt-4o-mini",
+        "gpt-4.1",
+        "gpt-4.1-mini",
+        "gpt-5",
+        "gpt-5-mini",
+        "claude-sonnet-4-5",
+        "claude-sonnet-4-20250514",
         "claude-3-7-sonnet-20250219",
         "claude-3-5-sonnet-20241022",
         "claude-3-5-haiku-20241022",
         "gemini-2.0-flash",
+        "gemini-2.5-flash",
     ],
-    "default": "gemini-2.0-flash",
+    "default": "gemini-2.5-flash",
 }
 
 BROWSER_USE_SCHEMA = {
@@ -164,27 +161,21 @@ def get_scrape_options(formats: Optional[List[scrape_types]] = None):
         },
         "llm": {
             **BROWSER_USE_LLM_SCHEMA,
-            "description": "The language model (LLM) instance to use for generating actions. Default to gemini-2.0-flash.",
+            "description": "The language model (LLM) instance to use for generating actions. Defaults to gemini-2.5-flash.",
         },
         "planner_llm": {
             **BROWSER_USE_LLM_SCHEMA,
-            "description": "The language model to use specifically for planning future actions, can differ from the main LLM. Default to gemini-2.0-flash.",
+            "description": "The language model to use specifically for planning future actions, can differ from the main LLM. Defaults to gemini-2.5-flash.",
         },
         "page_extraction_llm": {
             **BROWSER_USE_LLM_SCHEMA,
-            "description": "The language model to use for extracting structured data from webpages. Default to gemini-2.0-flash.",
+            "description": "The language model to use for extracting structured data from webpages. Defaults to gemini-2.5-flash.",
         },
         "keep_browser_open": {
             "type": "boolean",
             "description": "When enabled, keeps the browser session open after task completion.",
         },
     },
-    "required": [
-        "task",
-        "llm",
-        "planner_llm",
-        "page_extraction_llm",
-        "keep_browser_open",
-    ],
+    "required": ["task"],
     "additionalProperties": False,
 }

pyproject.toml

@@ -10,14 +10,15 @@ homepage = "https://github.com/hyperbrowserai/python-sdk"
 repository = "https://github.com/hyperbrowserai/python-sdk"
 
 [tool.poetry.dependencies]
-python = "^3.8"
+python = ">=3.9,<4.0"
 pydantic = ">=2.0,<3"
 httpx = ">=0.23.0,<1"
 jsonref = ">=1.1.0"
 
 
 [tool.poetry.group.dev.dependencies]
 ruff = "^0.3.0"
+pytest = "^8.0.0"
 
 
 [build-system]