hyperbrowser 0.51.0__py3-none-any.whl → 0.73.0__py3-none-any.whl

hyperbrowser/models/agents/browser_use.py

@@ -2,7 +2,7 @@ from typing import Any, Dict, List, Literal, Optional, Type, Union
 
 from pydantic import BaseModel, ConfigDict, Field
 
-from ..consts import BrowserUseLlm
+from ..consts import BrowserUseLlm, BrowserUseVersion
 from ..session import CreateSessionParams
 
 BrowserUseTaskStatus = Literal["pending", "running", "completed", "failed", "stopped"]
@@ -32,6 +32,9 @@ class StartBrowserUseTaskParams(BaseModel):
     )
 
     task: str
+    version: Optional[BrowserUseVersion] = Field(
+        default=None, serialization_alias="version"
+    )
     llm: Optional[BrowserUseLlm] = Field(default=None, serialization_alias="llm")
     session_id: Optional[str] = Field(default=None, serialization_alias="sessionId")
     validate_output: Optional[bool] = Field(
@@ -193,15 +196,79 @@ class BrowserUseAgentHistory(BaseModel):
     metadata: Optional[BrowserUseStepMetadata] = None
 
 
+# ===== 0.7.10-specific response models =====
+
+
+class BrowserUseAgentOutputV0710(BaseModel):
+    thinking: Optional[str] = None
+    evaluation_previous_goal: Optional[str] = None
+    memory: Optional[str] = None
+    next_goal: Optional[str] = None
+    action: list[dict]
+
+
+class BrowserUseActionResultV0710(BaseModel):
+    is_done: Optional[bool] = False
+    success: Optional[bool] = None
+    error: Optional[str] = None
+    metadata: Optional[dict] = None
+    attachments: Optional[list[str]] = None
+    long_term_memory: Optional[str] = None
+    extracted_content: Optional[str] = None
+    include_extracted_content_only_once: Optional[bool] = False
+    include_in_memory: bool = False
+
+
+class BrowserUseBrowserStateHistoryV0710(BaseModel):
+    url: str
+    title: str
+    tabs: list[dict]
+    interacted_element: Union[list[Union[dict, None]], list[None]]
+
+
+class BrowserUseStepMetadataV0710(BaseModel):
+    step_start_time: float
+    step_end_time: float
+    step_number: int
+
+
+class BrowserUseAgentHistoryV0710(BaseModel):
+    model_output: Union[BrowserUseAgentOutputV0710, None]
+    result: list[BrowserUseActionResultV0710]
+    state: BrowserUseBrowserStateHistoryV0710
+    metadata: Optional[BrowserUseStepMetadataV0710] = None
+
+
+# ===== latest response models =====
+
+BrowserUseAgentHistoryLatest = Dict[str, Any]
+
+BrowserUseStep = Union[
+    BrowserUseAgentHistory, BrowserUseAgentHistoryV0710, BrowserUseAgentHistoryLatest
+]
+
+
 class BrowserUseTaskData(BaseModel):
     model_config = ConfigDict(
         populate_by_alias=True,
     )
 
-    steps: list[BrowserUseAgentHistory]
+    steps: list[BrowserUseStep]
     final_result: Optional[str] = Field(default=None, alias="finalResult")
 
 
+class BrowserUseTaskMetadata(BaseModel):
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    input_tokens: Optional[int] = Field(default=None, alias="inputTokens")
+    output_tokens: Optional[int] = Field(default=None, alias="outputTokens")
+    num_task_steps_completed: Optional[int] = Field(
+        default=None, alias="numTaskStepsCompleted"
+    )
+
+
 class BrowserUseTaskResponse(BaseModel):
     """
     Response from a browser use task.
@@ -213,6 +280,20 @@ class BrowserUseTaskResponse(BaseModel):
 
     job_id: str = Field(alias="jobId")
     status: BrowserUseTaskStatus
+    metadata: Optional[BrowserUseTaskMetadata] = Field(default=None, alias="metadata")
     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")
+
+
+def cast_steps_for_version(
+    steps: List[BrowserUseStep], version: BrowserUseVersion
+) -> List[BrowserUseStep]:
+    if version == "0.1.40":
+        return [BrowserUseAgentHistory.model_validate(s) for s in steps]
+    elif version == "0.7.10":
+        return [BrowserUseAgentHistoryV0710.model_validate(s) for s in steps]
+    elif version == "latest":
+        return steps
+    else:
+        raise ValueError(f"Invalid version: {version}")

hyperbrowser/models/agents/claude_computer_use.py

@@ -48,6 +48,9 @@ class StartClaudeComputerUseTaskParams(BaseModel):
     api_keys: Optional[ClaudeComputerUseApiKeys] = Field(
         default=None, serialization_alias="apiKeys"
     )
+    use_computer_action: Optional[bool] = Field(
+        default=None, serialization_alias="useComputerAction"
+    )
 
 
 class StartClaudeComputerUseTaskResponse(BaseModel):
@@ -101,6 +104,18 @@ class ClaudeComputerUseTaskData(BaseModel):
     final_result: Optional[str] = Field(default=None, alias="finalResult")
 
 
+class ClaudeComputerUseTaskMetadata(BaseModel):
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    input_tokens: Optional[int] = Field(default=None, alias="inputTokens")
+    output_tokens: Optional[int] = Field(default=None, alias="outputTokens")
+    num_task_steps_completed: Optional[int] = Field(
+        default=None, alias="numTaskStepsCompleted"
+    )
+
+
 class ClaudeComputerUseTaskResponse(BaseModel):
     """
     Response from a Claude Computer Use task.
@@ -112,6 +127,9 @@ class ClaudeComputerUseTaskResponse(BaseModel):
 
     job_id: str = Field(alias="jobId")
     status: ClaudeComputerUseTaskStatus
+    metadata: Optional[ClaudeComputerUseTaskMetadata] = Field(
+        default=None, alias="metadata"
+    )
     data: Optional[ClaudeComputerUseTaskData] = Field(default=None, alias="data")
     error: Optional[str] = Field(default=None, alias="error")
     live_url: Optional[str] = Field(default=None, alias="liveUrl")

hyperbrowser/models/agents/cua.py

@@ -42,6 +42,9 @@ class StartCuaTaskParams(BaseModel):
         default=None, serialization_alias="useCustomApiKeys"
     )
     api_keys: Optional[CuaApiKeys] = Field(default=None, serialization_alias="apiKeys")
+    use_computer_action: Optional[bool] = Field(
+        default=None, serialization_alias="useComputerAction"
+    )
 
 
 class StartCuaTaskResponse(BaseModel):
@@ -131,6 +134,18 @@ class CuaTaskData(BaseModel):
     final_result: Optional[str] = Field(default=None, alias="finalResult")
 
 
+class CuaTaskMetadata(BaseModel):
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    input_tokens: Optional[int] = Field(default=None, alias="inputTokens")
+    output_tokens: Optional[int] = Field(default=None, alias="outputTokens")
+    num_task_steps_completed: Optional[int] = Field(
+        default=None, alias="numTaskStepsCompleted"
+    )
+
+
 class CuaTaskResponse(BaseModel):
     """
     Response from a CUA task.
@@ -142,6 +157,7 @@ class CuaTaskResponse(BaseModel):
 
     job_id: str = Field(alias="jobId")
     status: CuaTaskStatus
+    metadata: Optional[CuaTaskMetadata] = Field(default=None, alias="metadata")
     data: Optional[CuaTaskData] = Field(default=None, alias="data")
     error: Optional[str] = Field(default=None, alias="error")
     live_url: Optional[str] = Field(default=None, alias="liveUrl")

hyperbrowser/models/agents/gemini_computer_use.py

@@ -0,0 +1,135 @@
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ..session import CreateSessionParams
+from ..consts import GeminiComputerUseLlm
+
+GeminiComputerUseTaskStatus = Literal[
+    "pending", "running", "completed", "failed", "stopped"
+]
+
+
+class GeminiComputerUseApiKeys(BaseModel):
+    """
+    API keys for the Gemini Computer Use task.
+    """
+
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    google: Optional[str] = Field(default=None, serialization_alias="google")
+
+
+class StartGeminiComputerUseTaskParams(BaseModel):
+    """
+    Parameters for creating a new Gemini Computer Use task.
+    """
+
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    task: str
+    llm: Optional[GeminiComputerUseLlm] = Field(default=None, serialization_alias="llm")
+    session_id: Optional[str] = Field(default=None, serialization_alias="sessionId")
+    max_failures: Optional[int] = Field(default=None, serialization_alias="maxFailures")
+    max_steps: Optional[int] = Field(default=None, serialization_alias="maxSteps")
+    keep_browser_open: Optional[bool] = Field(
+        default=None, serialization_alias="keepBrowserOpen"
+    )
+    session_options: Optional[CreateSessionParams] = Field(
+        default=None, serialization_alias="sessionOptions"
+    )
+    use_custom_api_keys: Optional[bool] = Field(
+        default=None, serialization_alias="useCustomApiKeys"
+    )
+    use_computer_action: Optional[bool] = Field(
+        default=None, serialization_alias="useComputerAction"
+    )
+    api_keys: Optional[GeminiComputerUseApiKeys] = Field(
+        default=None, serialization_alias="apiKeys"
+    )
+
+
+class StartGeminiComputerUseTaskResponse(BaseModel):
+    """
+    Response from starting a Gemini Computer Use task.
+    """
+
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    job_id: str = Field(alias="jobId")
+    live_url: Optional[str] = Field(default=None, alias="liveUrl")
+
+
+class GeminiComputerUseTaskStatusResponse(BaseModel):
+    """
+    Response from getting a Gemini Computer Use task status.
+    """
+
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    status: GeminiComputerUseTaskStatus
+
+
+class GeminiComputerUseStepResponse(BaseModel):
+    """
+    Response from a single Gemini Computer Use step.
+    """
+
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    candidates: Optional[list[Any]] = Field(
+        default=None, serialization_alias="candidates"
+    )
+    model_version: Optional[str] = Field(
+        default=None, serialization_alias="modelVersion"
+    )
+
+
+class GeminiComputerUseTaskData(BaseModel):
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    steps: list[GeminiComputerUseStepResponse]
+    final_result: Optional[str] = Field(default=None, alias="finalResult")
+
+
+class GeminiComputerUseTaskMetadata(BaseModel):
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    input_tokens: Optional[int] = Field(default=None, alias="inputTokens")
+    output_tokens: Optional[int] = Field(default=None, alias="outputTokens")
+    num_task_steps_completed: Optional[int] = Field(
+        default=None, alias="numTaskStepsCompleted"
+    )
+
+
+class GeminiComputerUseTaskResponse(BaseModel):
+    """
+    Response from a Gemini Computer Use task.
+    """
+
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    job_id: str = Field(alias="jobId")
+    status: GeminiComputerUseTaskStatus
+    metadata: Optional[GeminiComputerUseTaskMetadata] = Field(
+        default=None, alias="metadata"
+    )
+    data: Optional[GeminiComputerUseTaskData] = Field(default=None, alias="data")
+    error: Optional[str] = Field(default=None, alias="error")
+    live_url: Optional[str] = Field(default=None, alias="liveUrl")

hyperbrowser/models/agents/hyper_agent.py

@@ -126,6 +126,16 @@ class HyperAgentTaskData(BaseModel):
     final_result: Optional[str] = Field(default=None, alias="finalResult")
 
 
+class HyperAgentTaskMetadata(BaseModel):
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    num_task_steps_completed: Optional[int] = Field(
+        default=None, alias="numTaskStepsCompleted"
+    )
+
+
 class HyperAgentTaskResponse(BaseModel):
     """
     Response from a HyperAgent task.
@@ -137,6 +147,7 @@ class HyperAgentTaskResponse(BaseModel):
 
     job_id: str = Field(alias="jobId")
     status: HyperAgentTaskStatus
+    metadata: Optional[HyperAgentTaskMetadata] = Field(default=None, alias="metadata")
     data: Optional[HyperAgentTaskData] = Field(default=None, alias="data")
     error: Optional[str] = Field(default=None, alias="error")
     live_url: Optional[str] = Field(default=None, alias="liveUrl")

hyperbrowser/models/computer_action.py

@@ -8,11 +8,20 @@ class ComputerAction(str, Enum):
 
     CLICK = "click"
     DRAG = "drag"
-    PRESS_KEYS = "press_keys"
+    HOLD_KEY = "hold_key"
+    MOUSE_DOWN = "mouse_down"
+    MOUSE_UP = "mouse_up"
     MOVE_MOUSE = "move_mouse"
+    PRESS_KEYS = "press_keys"
     SCREENSHOT = "screenshot"
     SCROLL = "scroll"
     TYPE_TEXT = "type_text"
+    GET_CLIPBOARD_TEXT = "get_clipboard_text"
+
+
+ComputerActionMouseButton = Literal[
+    "left", "right", "middle", "back", "forward", "wheel"
+]
 
 
 class Coordinate(BaseModel):
@@ -28,11 +37,9 @@ class ClickActionParams(BaseModel):
     model_config = ConfigDict(use_enum_values=True)
 
     action: Literal[ComputerAction.CLICK] = ComputerAction.CLICK
-    x: int
-    y: int
-    button: Literal["left", "right", "middle", "back", "forward", "wheel"] = Field(
-        default="left"
-    )
+    x: Optional[int] = Field(default=None)
+    y: Optional[int] = Field(default=None)
+    button: ComputerActionMouseButton = Field(default="left")
     num_clicks: int = Field(serialization_alias="numClicks", default=1)
     return_screenshot: bool = Field(
         serialization_alias="returnScreenshot", default=False
@@ -63,6 +70,43 @@ class PressKeysActionParams(BaseModel):
     )
 
 
+class HoldKeyActionParams(BaseModel):
+    """Parameters for hold key action."""
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    action: Literal[ComputerAction.HOLD_KEY] = ComputerAction.HOLD_KEY
+    key: str
+    duration: int
+    return_screenshot: bool = Field(
+        serialization_alias="returnScreenshot", default=False
+    )
+
+
+class MouseDownActionParams(BaseModel):
+    """Parameters for mouse down action."""
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    action: Literal[ComputerAction.MOUSE_DOWN] = ComputerAction.MOUSE_DOWN
+    button: ComputerActionMouseButton = Field(default="left")
+    return_screenshot: bool = Field(
+        serialization_alias="returnScreenshot", default=False
+    )
+
+
+class MouseUpActionParams(BaseModel):
+    """Parameters for mouse up action."""
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    action: Literal[ComputerAction.MOUSE_UP] = ComputerAction.MOUSE_UP
+    button: ComputerActionMouseButton = Field(default="left")
+    return_screenshot: bool = Field(
+        serialization_alias="returnScreenshot", default=False
+    )
+
+
 class MoveMouseActionParams(BaseModel):
     """Parameters for move mouse action."""
 
@@ -111,6 +155,19 @@ class TypeTextActionParams(BaseModel):
     )
 
 
+class GetClipboardTextActionParams(BaseModel):
+    """Parameters for get clipboard text action."""
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    action: Literal[ComputerAction.GET_CLIPBOARD_TEXT] = (
+        ComputerAction.GET_CLIPBOARD_TEXT
+    )
+    return_screenshot: bool = Field(
+        serialization_alias="returnScreenshot", default=False
+    )
+
+
 ComputerActionParams = Union[
     ClickActionParams,
     DragActionParams,
@@ -119,9 +176,24 @@ ComputerActionParams = Union[
     ScreenshotActionParams,
     ScrollActionParams,
     TypeTextActionParams,
+    HoldKeyActionParams,
+    MouseDownActionParams,
+    MouseUpActionParams,
+    GetClipboardTextActionParams,
 ]
 
 
+class ComputerActionResponseDataClipboardText(BaseModel):
+    """Data for get clipboard text action."""
+
+    model_config = ConfigDict(populate_by_alias=True)
+
+    clipboard_text: Optional[str] = Field(default=None, alias="clipboardText")
+
+
+ComputerActionResponseData = Union[ComputerActionResponseDataClipboardText]
+
+
 class ComputerActionResponse(BaseModel):
     """Response from computer action API."""
 
@@ -131,5 +203,6 @@ class ComputerActionResponse(BaseModel):
 
     success: bool
     screenshot: Optional[str] = None
+    data: Optional[ComputerActionResponseData] = None
     error: Optional[str] = None
     message: Optional[str] = None

hyperbrowser/models/consts.py

@@ -10,14 +10,22 @@ RecordingStatus = Literal[
 DownloadsStatus = Literal[
     "not_enabled", "pending", "in_progress", "completed", "failed"
 ]
+SessionEventLogType = Literal[
+    "captcha_detected", "captcha_solved", "captcha_error", "file_downloaded"
+]
 
 POLLING_ATTEMPTS = 5
 
+BrowserUseVersion = Literal["0.1.40", "0.7.10", "latest"]
+
 BrowserUseLlm = Literal[
     "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",
@@ -33,8 +41,19 @@ HyperAgentLlm = Literal[
     "gpt-4.1-nano",
 ]
 ClaudeComputerUseLlm = Literal[
-    "claude-3-7-sonnet-20250219",
+    "claude-haiku-4-5-20251001",
+    "claude-sonnet-4-5",
     "claude-sonnet-4-20250514",
+    "claude-3-7-sonnet-20250219",
+]
+GeminiComputerUseLlm = Literal["gemini-2.5-computer-use-preview-10-2025",]
+SessionRegion = Literal[
+    "us-central",
+    "asia-south",
+    "us-dev",
+    "europe-west",
+    "us-west",
+    "us-east",
 ]
 
 Country = Literal[

hyperbrowser/models/extract.py

@@ -55,6 +55,16 @@ class ExtractJobStatusResponse(BaseModel):
     status: ExtractJobStatus
 
 
+class ExtractJobMetadata(BaseModel):
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    input_tokens: Optional[int] = Field(default=None, alias="inputTokens")
+    output_tokens: Optional[int] = Field(default=None, alias="outputTokens")
+    num_pages_scraped: Optional[int] = Field(default=None, alias="numPagesScraped")
+
+
 class ExtractJobResponse(BaseModel):
     """
     Response from a extract job.
@@ -67,4 +77,5 @@ class ExtractJobResponse(BaseModel):
     job_id: str = Field(alias="jobId")
     status: ExtractJobStatus
     error: Optional[str] = None
+    metadata: Optional[ExtractJobMetadata] = None
     data: Optional[dict] = None

hyperbrowser/models/scrape.py

@@ -21,6 +21,25 @@ class ScreenshotOptions(BaseModel):
     format: Optional[ScrapeScreenshotFormat] = Field(
         default=None, serialization_alias="format"
     )
+    crop_to_content: Optional[bool] = Field(
+        default=None, serialization_alias="cropToContent"
+    )
+    crop_to_content_max_height: Optional[int] = Field(
+        default=None, serialization_alias="cropToContentMaxHeight"
+    )
+    crop_to_content_min_height: Optional[int] = Field(
+        default=None, serialization_alias="cropToContentMinHeight"
+    )
+    wait_for: Optional[int] = Field(default=None, serialization_alias="waitFor")
+
+
+class StorageStateOptions(BaseModel):
+    local_storage: Optional[dict[str, str]] = Field(
+        default=None, serialization_alias="localStorage"
+    )
+    session_storage: Optional[dict[str, str]] = Field(
+        default=None, serialization_alias="sessionStorage"
+    )
 
 
 class ScrapeOptions(BaseModel):
@@ -46,6 +65,9 @@ class ScrapeOptions(BaseModel):
     screenshot_options: Optional[ScreenshotOptions] = Field(
         default=None, serialization_alias="screenshotOptions"
     )
+    storage_state: Optional[StorageStateOptions] = Field(
+        default=None, serialization_alias="storageState"
+    )
 
 
 class StartScrapeJobParams(BaseModel):