hyperbrowser 0.44.0__py3-none-any.whl → 0.72.0__py3-none-any.whl

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

@@ -8,6 +8,20 @@ from ..session import CreateSessionParams
 HyperAgentTaskStatus = Literal["pending", "running", "completed", "failed", "stopped"]
 
 
+class HyperAgentApiKeys(BaseModel):
+    """
+    API keys for the HyperAgent task.
+    """
+
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    openai: Optional[str] = Field(default=None, serialization_alias="openai")
+    anthropic: Optional[str] = Field(default=None, serialization_alias="anthropic")
+    google: Optional[str] = Field(default=None, serialization_alias="google")
+
+
 class StartHyperAgentTaskParams(BaseModel):
     """
     Parameters for creating a new HyperAgent task.
@@ -27,6 +41,12 @@ class StartHyperAgentTaskParams(BaseModel):
     session_options: Optional[CreateSessionParams] = Field(
         default=None, serialization_alias="sessionOptions"
     )
+    use_custom_api_keys: Optional[bool] = Field(
+        default=None, serialization_alias="useCustomApiKeys"
+    )
+    api_keys: Optional[HyperAgentApiKeys] = Field(
+        default=None, serialization_alias="apiKeys"
+    )
 
 
 class StartHyperAgentTaskResponse(BaseModel):
@@ -106,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.
@@ -117,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

@@ -0,0 +1,208 @@
+from enum import Enum
+from typing import List, Literal, Optional, Union
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ComputerAction(str, Enum):
+    """Computer action types."""
+
+    CLICK = "click"
+    DRAG = "drag"
+    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):
+    """Coordinate model for drag actions."""
+
+    x: int
+    y: int
+
+
+class ClickActionParams(BaseModel):
+    """Parameters for click action."""
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    action: Literal[ComputerAction.CLICK] = ComputerAction.CLICK
+    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
+    )
+
+
+class DragActionParams(BaseModel):
+    """Parameters for drag action."""
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    action: Literal[ComputerAction.DRAG] = ComputerAction.DRAG
+    path: List[Coordinate]
+    return_screenshot: bool = Field(
+        serialization_alias="returnScreenshot", default=False
+    )
+
+
+class PressKeysActionParams(BaseModel):
+    """Parameters for press keys action."""
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    action: Literal[ComputerAction.PRESS_KEYS] = ComputerAction.PRESS_KEYS
+    keys: List[str]
+    return_screenshot: bool = Field(
+        serialization_alias="returnScreenshot", default=False
+    )
+
+
+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."""
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    action: Literal[ComputerAction.MOVE_MOUSE] = ComputerAction.MOVE_MOUSE
+    x: int = Field(ge=0)
+    y: int = Field(ge=0)
+    return_screenshot: bool = Field(
+        serialization_alias="returnScreenshot", default=False
+    )
+
+
+class ScreenshotActionParams(BaseModel):
+    """Parameters for screenshot action."""
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    action: Literal[ComputerAction.SCREENSHOT] = ComputerAction.SCREENSHOT
+
+
+class ScrollActionParams(BaseModel):
+    """Parameters for scroll action."""
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    action: Literal[ComputerAction.SCROLL] = ComputerAction.SCROLL
+    x: int
+    y: int
+    scroll_x: int = Field(serialization_alias="scrollX")
+    scroll_y: int = Field(serialization_alias="scrollY")
+    return_screenshot: bool = Field(
+        serialization_alias="returnScreenshot", default=False
+    )
+
+
+class TypeTextActionParams(BaseModel):
+    """Parameters for type text action."""
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    action: Literal[ComputerAction.TYPE_TEXT] = ComputerAction.TYPE_TEXT
+    text: str
+    return_screenshot: bool = Field(
+        serialization_alias="returnScreenshot", default=False
+    )
+
+
+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,
+    PressKeysActionParams,
+    MoveMouseActionParams,
+    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."""
+
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    success: bool
+    screenshot: Optional[str] = None
+    data: Optional[ComputerActionResponseData] = None
+    error: Optional[str] = None
+    message: Optional[str] = None

hyperbrowser/models/consts.py

@@ -10,16 +10,28 @@ 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",
     "claude-3-5-haiku-20241022",
     "gemini-2.0-flash",
+    "gemini-2.5-flash",
 ]
 HyperAgentLlm = Literal[
     "gpt-4o",
@@ -28,6 +40,21 @@ HyperAgentLlm = Literal[
     "gpt-4.1-mini",
     "gpt-4.1-nano",
 ]
+ClaudeComputerUseLlm = Literal[
+    "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[
     "AD",

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,21 @@ 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"
+    )
+
+
+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 +61,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):