hyperbrowser 0.33.0__py3-none-any.whl → 0.35.0__py3-none-any.whl

hyperbrowser/client/managers/sync_manager/session.py

@@ -40,7 +40,8 @@ class SessionManager:
         self, params: SessionListParams = SessionListParams()
     ) -> SessionListResponse:
         response = self._client.transport.get(
-            self._client._build_url("/sessions"), params=params.__dict__
+            self._client._build_url("/sessions"),
+            params=params.model_dump(exclude_none=True, by_alias=True),
         )
         return SessionListResponse(**response.data)
 

hyperbrowser/client/sync.py

@@ -1,15 +1,15 @@
 from typing import Optional
 
+from ..config import ClientConfig
+from ..transport.sync import SyncTransport
+from .base import HyperbrowserBase
+from .managers.sync_manager.agents import Agents
+from .managers.sync_manager.crawl import CrawlManager
+from .managers.sync_manager.extension import ExtensionManager
 from .managers.sync_manager.extract import ExtractManager
 from .managers.sync_manager.profile import ProfileManager
-from .managers.sync_manager.session import SessionManager
 from .managers.sync_manager.scrape import ScrapeManager
-from .managers.sync_manager.crawl import CrawlManager
-from .managers.sync_manager.beta import Beta
-from .managers.sync_manager.extension import ExtensionManager
-from .base import HyperbrowserBase
-from ..transport.sync import SyncTransport
-from ..config import ClientConfig
+from .managers.sync_manager.session import SessionManager
 
 
 class Hyperbrowser(HyperbrowserBase):
@@ -30,7 +30,7 @@ class Hyperbrowser(HyperbrowserBase):
         self.extract = ExtractManager(self)
         self.profiles = ProfileManager(self)
         self.extensions = ExtensionManager(self)
-        self.beta = Beta(self)
+        self.agents = Agents(self)
 
     def close(self) -> None:
         self.transport.close()

hyperbrowser/models/__init__.py

@@ -1,142 +1,151 @@
+from .agents.browser_use import (
+    BrowserUseTaskData,
+    BrowserUseTaskResponse,
+    BrowserUseTaskStatusResponse,
+    StartBrowserUseTaskParams,
+    StartBrowserUseTaskResponse,
+)
 from .consts import (
-    ScrapeFormat,
-    ScrapeWaitUntil,
-    ScrapePageStatus,
-    ScrapeScreenshotFormat,
-    RecordingStatus,
-    DownloadsStatus,
+    ISO639_1,
     POLLING_ATTEMPTS,
+    BrowserUseLlm,
     Country,
+    DownloadsStatus,
     OperatingSystem,
     Platform,
-    ISO639_1,
+    RecordingStatus,
+    ScrapeFormat,
+    ScrapePageStatus,
+    ScrapeScreenshotFormat,
+    ScrapeWaitUntil,
     State,
-    BrowserUseLlm,
 )
 from .crawl import (
+    CrawledPage,
+    CrawlJobResponse,
     CrawlJobStatus,
+    CrawlJobStatusResponse,
     CrawlPageStatus,
+    GetCrawlJobParams,
     StartCrawlJobParams,
     StartCrawlJobResponse,
-    CrawledPage,
-    GetCrawlJobParams,
-    CrawlJobResponse,
 )
 from .extension import CreateExtensionParams, ExtensionResponse
 from .extract import (
+    ExtractJobResponse,
     ExtractJobStatus,
+    ExtractJobStatusResponse,
     StartExtractJobParams,
     StartExtractJobResponse,
-    ExtractJobResponse,
 )
 from .profile import (
     CreateProfileResponse,
-    ProfileResponse,
     ProfileListParams,
     ProfileListResponse,
+    ProfileResponse,
 )
 from .scrape import (
-    ScrapeJobStatus,
-    ScreenshotOptions,
-    ScrapeOptions,
-    StartScrapeJobParams,
-    StartScrapeJobResponse,
+    BatchScrapeJobResponse,
+    BatchScrapeJobStatusResponse,
+    GetBatchScrapeJobParams,
+    ScrapedPage,
     ScrapeJobData,
     ScrapeJobResponse,
+    ScrapeJobStatus,
+    ScrapeJobStatusResponse,
+    ScrapeOptions,
+    ScreenshotOptions,
     StartBatchScrapeJobParams,
-    ScrapedPage,
-    GetBatchScrapeJobParams,
     StartBatchScrapeJobResponse,
-    BatchScrapeJobResponse,
+    StartScrapeJobParams,
+    StartScrapeJobResponse,
 )
 from .session import (
-    SessionStatus,
     BasicResponse,
+    CreateSessionParams,
+    CreateSessionProfile,
+    GetSessionDownloadsUrlResponse,
+    GetSessionRecordingUrlResponse,
+    ScreenConfig,
     Session,
     SessionDetail,
     SessionListParams,
     SessionListResponse,
-    ScreenConfig,
-    CreateSessionProfile,
-    CreateSessionParams,
     SessionRecording,
-    GetSessionRecordingUrlResponse,
-    GetSessionDownloadsUrlResponse,
-)
-from .beta.agents.browser_use import (
-    StartBrowserUseTaskParams,
-    StartBrowserUseTaskResponse,
-    BrowserUseTaskStatusResponse,
-    BrowserUseTaskData,
-    BrowserUseTaskResponse,
+    SessionStatus,
 )
 
 __all__ = [
     # consts
-    "BrowserUseLlm",
-    "ScrapeFormat",
-    "ScrapeWaitUntil",
-    "ScrapePageStatus",
-    "ScrapeScreenshotFormat",
-    "RecordingStatus",
-    "DownloadsStatus",
+    "ISO639_1",
     "POLLING_ATTEMPTS",
+    "BrowserUseLlm",
     "Country",
+    "DownloadsStatus",
     "OperatingSystem",
     "Platform",
-    "ISO639_1",
+    "RecordingStatus",
+    "ScrapeFormat",
+    "ScrapePageStatus",
+    "ScrapeScreenshotFormat",
+    "ScrapeWaitUntil",
     "State",
+    # agents
+    "BrowserUseTaskStatus",
+    "BrowserUseTaskData",
+    "BrowserUseTaskResponse",
+    "BrowserUseTaskStatusResponse",
+    "StartBrowserUseTaskParams",
+    "StartBrowserUseTaskResponse",
     # crawl
+    "CrawledPage",
+    "CrawlJobResponse",
     "CrawlJobStatus",
+    "CrawlJobStatusResponse",
     "CrawlPageStatus",
+    "GetCrawlJobParams",
     "StartCrawlJobParams",
     "StartCrawlJobResponse",
-    "CrawledPage",
-    "GetCrawlJobParams",
-    "CrawlJobResponse",
     # extension
     "CreateExtensionParams",
     "ExtensionResponse",
     # extract
+    "ExtractJobResponse",
     "ExtractJobStatus",
+    "ExtractJobStatusResponse",
     "StartExtractJobParams",
     "StartExtractJobResponse",
-    "ExtractJobResponse",
     # profile
     "CreateProfileResponse",
-    "ProfileResponse",
     "ProfileListParams",
     "ProfileListResponse",
+    "ProfileResponse",
     # scrape
-    "ScrapeJobStatus",
-    "ScreenshotOptions",
-    "ScrapeOptions",
-    "StartScrapeJobParams",
-    "StartScrapeJobResponse",
+    "BatchScrapeJobResponse",
+    "BatchScrapeJobStatusResponse",
+    "GetBatchScrapeJobParams",
+    "ScrapedPage",
     "ScrapeJobData",
     "ScrapeJobResponse",
+    "ScrapeJobStatus",
+    "ScrapeJobStatusResponse",
+    "ScrapeOptions",
+    "ScreenshotOptions",
     "StartBatchScrapeJobParams",
-    "ScrapedPage",
-    "GetBatchScrapeJobParams",
     "StartBatchScrapeJobResponse",
-    "BatchScrapeJobResponse",
+    "StartScrapeJobParams",
+    "StartScrapeJobResponse",
     # session
-    "SessionStatus",
     "BasicResponse",
+    "CreateSessionParams",
+    "CreateSessionProfile",
+    "GetSessionDownloadsUrlResponse",
+    "GetSessionRecordingUrlResponse",
+    "ScreenConfig",
     "Session",
     "SessionDetail",
     "SessionListParams",
     "SessionListResponse",
-    "ScreenConfig",
-    "CreateSessionProfile",
-    "CreateSessionParams",
     "SessionRecording",
-    "GetSessionRecordingUrlResponse",
-    "GetSessionDownloadsUrlResponse",
-    # agents
-    "StartBrowserUseTaskParams",
-    "StartBrowserUseTaskResponse",
-    "BrowserUseTaskStatusResponse",
-    "BrowserUseTaskData",
-    "BrowserUseTaskResponse",
+    "SessionStatus",
 ]

hyperbrowser/models/{beta/agents → agents}/browser_use.py

@@ -1,8 +1,9 @@
 from typing import Literal, Optional, Union
+
 from pydantic import BaseModel, ConfigDict, Field
 
-from ...consts import BrowserUseLlm
-from ...session import CreateSessionParams
+from ..consts import BrowserUseLlm
+from ..session import CreateSessionParams
 
 BrowserUseTaskStatus = Literal["pending", "running", "completed", "failed", "stopped"]
 
@@ -182,3 +183,4 @@ class BrowserUseTaskResponse(BaseModel):
     data: Optional[BrowserUseTaskData] = Field(default=None, alias="data")
     error: Optional[str] = Field(default=None, alias="error")
     live_url: Optional[str] = Field(default=None, alias="liveUrl")
+    live_url: Optional[str] = Field(default=None, alias="liveUrl")

hyperbrowser/models/crawl.py

@@ -47,6 +47,18 @@ class StartCrawlJobResponse(BaseModel):
     job_id: str = Field(alias="jobId")
 
 
+class CrawlJobStatusResponse(BaseModel):
+    """
+    Response from getting the status of a crawl job.
+    """
+
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    status: CrawlJobStatus
+
+
 class CrawledPage(BaseModel):
     """
     Data from a crawled page.

hyperbrowser/models/extract.py

@@ -43,6 +43,18 @@ class StartExtractJobResponse(BaseModel):
     job_id: str = Field(alias="jobId")
 
 
+class ExtractJobStatusResponse(BaseModel):
+    """
+    Response from getting the status of a extract job.
+    """
+
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    status: ExtractJobStatus
+
+
 class ExtractJobResponse(BaseModel):
     """
     Response from a extract job.

hyperbrowser/models/scrape.py

@@ -78,6 +78,18 @@ class StartScrapeJobResponse(BaseModel):
     job_id: str = Field(alias="jobId")
 
 
+class ScrapeJobStatusResponse(BaseModel):
+    """
+    Response from getting the status of a scrape job.
+    """
+
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    status: ScrapeJobStatus
+
+
 class ScrapeJobData(BaseModel):
     """
     Data from a scraped site.
@@ -119,6 +131,18 @@ class StartBatchScrapeJobParams(BaseModel):
     )
 
 
+class BatchScrapeJobStatusResponse(BaseModel):
+    """
+    Response from getting the status of a batch scrape job.
+    """
+
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    status: ScrapeJobStatus
+
+
 class ScrapedPage(BaseModel):
     """
     A scraped page.

hyperbrowser/tools/__init__.py

@@ -1,17 +1,22 @@
 import json
+from hyperbrowser.models.agents.browser_use import StartBrowserUseTaskParams
 from hyperbrowser.models.crawl import StartCrawlJobParams
 from hyperbrowser.models.extract import StartExtractJobParams
 from hyperbrowser.models.scrape import StartScrapeJobParams
 from hyperbrowser import Hyperbrowser, AsyncHyperbrowser
 
 from .openai import (
+    BROWSER_USE_TOOL_OPENAI,
     EXTRACT_TOOL_OPENAI,
     SCRAPE_TOOL_OPENAI,
+    SCREENSHOT_TOOL_OPENAI,
     CRAWL_TOOL_OPENAI,
 )
 from .anthropic import (
+    BROWSER_USE_TOOL_ANTHROPIC,
     EXTRACT_TOOL_ANTHROPIC,
     SCRAPE_TOOL_ANTHROPIC,
+    SCREENSHOT_TOOL_ANTHROPIC,
     CRAWL_TOOL_ANTHROPIC,
 )
 
@@ -31,6 +36,21 @@ class WebsiteScrapeTool:
         return resp.data.markdown if resp.data and resp.data.markdown else ""
 
 
+class WebsiteScreenshotTool:
+    openai_tool_definition = SCREENSHOT_TOOL_OPENAI
+    anthropic_tool_definition = SCREENSHOT_TOOL_ANTHROPIC
+
+    @staticmethod
+    def runnable(hb: Hyperbrowser, params: dict) -> str:
+        resp = hb.scrape.start_and_wait(params=StartScrapeJobParams(**params))
+        return resp.data.screenshot if resp.data and resp.data.screenshot else ""
+
+    @staticmethod
+    async def async_runnable(hb: AsyncHyperbrowser, params: dict) -> str:
+        resp = await hb.scrape.start_and_wait(params=StartScrapeJobParams(**params))
+        return resp.data.screenshot if resp.data and resp.data.screenshot else ""
+
+
 class WebsiteCrawlTool:
     openai_tool_definition = CRAWL_TOOL_OPENAI
     anthropic_tool_definition = CRAWL_TOOL_ANTHROPIC
@@ -79,8 +99,28 @@ class WebsiteExtractTool:
         return json.dumps(resp.data) if resp.data else ""
 
 
+class BrowserUseTool:
+    openai_tool_definition = BROWSER_USE_TOOL_OPENAI
+    anthropic_tool_definition = BROWSER_USE_TOOL_ANTHROPIC
+
+    @staticmethod
+    def runnable(hb: Hyperbrowser, params: dict) -> str:
+        resp = hb.agents.browser_use.start_and_wait(
+            params=StartBrowserUseTaskParams(**params)
+        )
+        return resp.data.final_result if resp.data and resp.data.final_result else ""
+
+    @staticmethod
+    async def async_runnable(hb: AsyncHyperbrowser, params: dict) -> str:
+        resp = await hb.agents.browser_use.start_and_wait(
+            params=StartBrowserUseTaskParams(**params)
+        )
+        return resp.data.final_result if resp.data and resp.data.final_result else ""
+
+
 __all__ = [
     "WebsiteScrapeTool",
     "WebsiteCrawlTool",
     "WebsiteExtractTool",
+    "BrowserUseTool",
 ]

hyperbrowser/tools/anthropic.py

@@ -1,7 +1,13 @@
 from typing import Dict, Union, Optional
 from typing_extensions import Literal, Required, TypeAlias, TypedDict
 
-from hyperbrowser.tools.schema import CRAWL_SCHEMA, EXTRACT_SCHEMA, SCRAPE_SCHEMA
+from hyperbrowser.tools.schema import (
+    BROWSER_USE_SCHEMA,
+    CRAWL_SCHEMA,
+    EXTRACT_SCHEMA,
+    SCRAPE_SCHEMA,
+    SCREENSHOT_SCHEMA,
+)
 
 
 class CacheControlEphemeralParam(TypedDict, total=False):
@@ -49,6 +55,12 @@ SCRAPE_TOOL_ANTHROPIC: ToolParam = {
     "description": "Scrape content from a webpage and return the content in markdown format",
 }
 
+SCREENSHOT_TOOL_ANTHROPIC: ToolParam = {
+    "input_schema": SCREENSHOT_SCHEMA,
+    "name": "screenshot_webpage",
+    "description": "Scrape content from a webpage and return the content in screenshot format",
+}
+
 CRAWL_TOOL_ANTHROPIC: ToolParam = {
     "input_schema": CRAWL_SCHEMA,
     "name": "crawl_website",
@@ -60,3 +72,9 @@ EXTRACT_TOOL_ANTHROPIC: ToolParam = {
     "name": "extract_data",
     "description": "Extract data in a structured format from multiple URLs in a single function call. IMPORTANT: When information must be gathered from multiple sources (such as comparing items, researching topics across sites, or answering questions that span multiple webpages), ALWAYS include all relevant URLs in ONE function call. This enables comprehensive answers with cross-referenced information. Returns data as a json string.",
 }
+
+BROWSER_USE_TOOL_ANTHROPIC: ToolParam = {
+    "input_schema": BROWSER_USE_SCHEMA,
+    "name": "browser_use",
+    "description": "Have an AI agent use a browser to perform a task on the web.",
+}

hyperbrowser/tools/openai.py

@@ -1,7 +1,13 @@
 from typing import Dict, Optional
 from typing_extensions import Literal, Required, TypedDict, TypeAlias
 
-from hyperbrowser.tools.schema import CRAWL_SCHEMA, EXTRACT_SCHEMA, SCRAPE_SCHEMA
+from hyperbrowser.tools.schema import (
+    BROWSER_USE_SCHEMA,
+    CRAWL_SCHEMA,
+    EXTRACT_SCHEMA,
+    SCRAPE_SCHEMA,
+    SCREENSHOT_SCHEMA,
+)
 
 FunctionParameters: TypeAlias = Dict[str, object]
 
@@ -58,6 +64,16 @@ SCRAPE_TOOL_OPENAI: ChatCompletionToolParam = {
     },
 }
 
+SCREENSHOT_TOOL_OPENAI: ChatCompletionToolParam = {
+    "type": "function",
+    "function": {
+        "name": "screenshot_webpage",
+        "description": "Scrape content from a webpage and return the content in screenshot format",
+        "parameters": SCREENSHOT_SCHEMA,
+        "strict": True,
+    },
+}
+
 CRAWL_TOOL_OPENAI: ChatCompletionToolParam = {
     "type": "function",
     "function": {
@@ -77,3 +93,13 @@ EXTRACT_TOOL_OPENAI: ChatCompletionToolParam = {
         "strict": True,
     },
 }
+
+BROWSER_USE_TOOL_OPENAI: ChatCompletionToolParam = {
+    "type": "function",
+    "function": {
+        "name": "browser_use",
+        "description": "Have an AI agent use a browser to perform a task on the web.",
+        "parameters": BROWSER_USE_SCHEMA,
+        "strict": True,
+    },
+}

hyperbrowser/tools/schema.py

@@ -1,38 +1,63 @@
-SCRAPE_OPTIONS = {
-    "type": "object",
-    "description": "The options for the scrape",
-    "properties": {
-        "include_tags": {
-            "type": "array",
-            "items": {
+from typing import Literal, List
+
+scrape_types = Literal["markdown", "screenshot"]
+
+
+def get_scrape_options(formats: List[scrape_types] = ["markdown"]):
+    return {
+        "type": "object",
+        "description": "The options for the scrape",
+        "properties": {
+            "format": {
                 "type": "string",
+                "description": "The format of the content to scrape",
+                "enum": formats,
             },
-            "description": "An array of HTML tags, classes, or IDs to include in the scraped content. Only elements matching these selectors will be returned.",
-        },
-        "exclude_tags": {
-            "type": "array",
-            "items": {
-                "type": "string",
+            "include_tags": {
+                "type": "array",
+                "items": {
+                    "type": "string",
+                },
+                "description": "An array of HTML tags, classes, or IDs to include in the scraped content. Only elements matching these selectors will be returned.",
+            },
+            "exclude_tags": {
+                "type": "array",
+                "items": {
+                    "type": "string",
+                },
+                "description": "An array of HTML tags, classes, or IDs to exclude from the scraped content. Elements matching these selectors will be omitted from the response.",
+            },
+            "only_main_content": {
+                "type": "boolean",
+                "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.",
             },
-            "description": "An array of HTML tags, classes, or IDs to exclude from the scraped content. Elements matching these selectors will be omitted from the response.",
         },
-        "only_main_content": {
-            "type": "boolean",
-            "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", "format"],
+        "additionalProperties": False,
+    }
+
+
+SCRAPE_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "url": {
+            "type": "string",
+            "description": "The URL of the website to scrape",
         },
+        "scrape_options": get_scrape_options(),
     },
-    "required": ["include_tags", "exclude_tags", "only_main_content"],
+    "required": ["url", "scrape_options"],
     "additionalProperties": False,
 }
 
-SCRAPE_SCHEMA = {
+SCREENSHOT_SCHEMA = {
     "type": "object",
     "properties": {
         "url": {
             "type": "string",
             "description": "The URL of the website to scrape",
         },
-        "scrape_options": SCRAPE_OPTIONS,
+        "scrape_options": get_scrape_options(["screenshot"]),
     },
     "required": ["url", "scrape_options"],
     "additionalProperties": False,
@@ -71,7 +96,7 @@ CRAWL_SCHEMA = {
             },
             "description": "An array of regular expressions or wildcard patterns specifying which URLs should be included in the crawl. Only pages whose URLs' path match one of these path patterns will be visited. Example: ['/admin', '/careers/*']",
         },
-        "scrape_options": SCRAPE_OPTIONS,
+        "scrape_options": get_scrape_options(),
     },
     "required": [
         "url",
@@ -111,3 +136,50 @@ EXTRACT_SCHEMA = {
     "required": ["urls", "prompt", "schema", "max_links"],
     "additionalProperties": False,
 }
+
+BROWSER_USE_LLM_SCHEMA = {
+    "type": "string",
+    "enum": [
+        "gpt-4o",
+        "gpt-4o-mini",
+        "claude-3-7-sonnet-20250219",
+        "claude-3-5-sonnet-20241022",
+        "claude-3-5-haiku-20241022",
+        "gemini-2.0-flash",
+    ],
+    "default": "gemini-2.0-flash",
+}
+
+BROWSER_USE_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "task": {
+            "type": "string",
+            "description": "The text description of the task to be performed by the agent.",
+        },
+        "llm": {
+            **BROWSER_USE_LLM_SCHEMA,
+            "description": "The language model (LLM) instance to use for generating actions. Default to gemini-2.0-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.",
+        },
+        "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.",
+        },
+        "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",
+    ],
+    "additionalProperties": False,
+}

{hyperbrowser-0.33.0.dist-info → hyperbrowser-0.35.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: hyperbrowser
-Version: 0.33.0
+Version: 0.35.0
 Summary: Python SDK for hyperbrowser
 License: MIT
 Author: Nikhil Shahi
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: httpx (>=0.23.0,<1)
+Requires-Dist: jsonref (>=1.1.0)
 Requires-Dist: pydantic (>=2.0,<3)
 Project-URL: Homepage, https://github.com/hyperbrowserai/python-sdk
 Project-URL: Repository, https://github.com/hyperbrowserai/python-sdk