Accept TypedDict/dict params across managers (keep Pydantic compat)

Author: shrisukhani

README.md

@@ -107,6 +107,39 @@ def main():
 main()
 ```
 
+### Passing parameters
+
+Every manager method that takes a params object accepts **either** a plain
+dictionary (recommended — you get editor autocomplete via the `*Dict`
+`TypedDict` types) **or** the existing Pydantic params class. Both produce
+identical requests, so existing code keeps working after upgrading.
+
+```python
+from hyperbrowser import Hyperbrowser
+from hyperbrowser.models import StartScrapeJobParams  # still supported
+
+client = Hyperbrowser(api_key="test-key")
+
+# New: plain dict with snake_case keys (autocompletes against StartScrapeJobParamsDict)
+client.scrape.start_and_wait(
+    {
+        "url": "https://example.com",
+        "scrape_options": {"formats": ["markdown"], "only_main_content": True},
+    }
+)
+
+# Existing: Pydantic params object — unchanged
+client.scrape.start_and_wait(
+    StartScrapeJobParams(
+        url="https://example.com",
+        scrape_options={"formats": ["markdown"], "only_main_content": True},
+    )
+)
+```
+
+For extraction and structured web-fetch outputs, the `schema` field still
+accepts a Pydantic model class or a raw JSON schema dict, exactly as before.
+
 ## Sandboxes
 
 The sync and async clients expose the same sandbox APIs through `client.sandboxes`.

hyperbrowser/client/managers/async_manager/agents/browser_use.py

@@ -1,7 +1,10 @@
 import asyncio
+from typing import Union
+
 import jsonref
 
 from hyperbrowser.exceptions import HyperbrowserError
+from .....models.params import coerce_to_model, StartBrowserUseTaskParamsDict
 
 from .....models import (
     POLLING_ATTEMPTS,
@@ -18,8 +21,9 @@ def __init__(self, client):
         self._client = client
 
     async def start(
-        self, params: StartBrowserUseTaskParams
+        self, params: Union[StartBrowserUseTaskParams, StartBrowserUseTaskParamsDict]
     ) -> StartBrowserUseTaskResponse:
+        params = coerce_to_model(StartBrowserUseTaskParams, params)
         if params.output_model_schema:
             if hasattr(params.output_model_schema, "model_json_schema"):
                 params.output_model_schema = jsonref.replace_refs(
@@ -52,7 +56,7 @@ async def stop(self, job_id: str) -> BasicResponse:
         return BasicResponse(**response.data)
 
     async def start_and_wait(
-        self, params: StartBrowserUseTaskParams
+        self, params: Union[StartBrowserUseTaskParams, StartBrowserUseTaskParamsDict]
     ) -> BrowserUseTaskResponse:
         job_start_resp = await self.start(params)
         job_id = job_start_resp.job_id

hyperbrowser/client/managers/async_manager/agents/claude_computer_use.py

@@ -1,4 +1,7 @@
 import asyncio
+from typing import Union
+
+from .....models.params import coerce_to_model, StartClaudeComputerUseTaskParamsDict
 
 from hyperbrowser.exceptions import HyperbrowserError
 
@@ -17,11 +20,16 @@ def __init__(self, client):
         self._client = client
 
     async def start(
-        self, params: StartClaudeComputerUseTaskParams
+        self,
+        params: Union[
+            StartClaudeComputerUseTaskParams, StartClaudeComputerUseTaskParamsDict
+        ],
     ) -> StartClaudeComputerUseTaskResponse:
         response = await self._client.transport.post(
             self._client._build_url("/task/claude-computer-use"),
-            data=params.model_dump(exclude_none=True, by_alias=True),
+            data=coerce_to_model(StartClaudeComputerUseTaskParams, params).model_dump(
+                exclude_none=True, by_alias=True
+            ),
         )
         return StartClaudeComputerUseTaskResponse(**response.data)
 
@@ -44,7 +52,10 @@ async def stop(self, job_id: str) -> BasicResponse:
         return BasicResponse(**response.data)
 
     async def start_and_wait(
-        self, params: StartClaudeComputerUseTaskParams
+        self,
+        params: Union[
+            StartClaudeComputerUseTaskParams, StartClaudeComputerUseTaskParamsDict
+        ],
     ) -> ClaudeComputerUseTaskResponse:
         job_start_resp = await self.start(params)
         job_id = job_start_resp.job_id

hyperbrowser/client/managers/async_manager/agents/cua.py

@@ -1,4 +1,7 @@
 import asyncio
+from typing import Union
+
+from .....models.params import coerce_to_model, StartCuaTaskParamsDict
 
 from hyperbrowser.exceptions import HyperbrowserError
 
@@ -16,10 +19,14 @@ class CuaManager:
     def __init__(self, client):
         self._client = client
 
-    async def start(self, params: StartCuaTaskParams) -> StartCuaTaskResponse:
+    async def start(
+        self, params: Union[StartCuaTaskParams, StartCuaTaskParamsDict]
+    ) -> StartCuaTaskResponse:
         response = await self._client.transport.post(
             self._client._build_url("/task/cua"),
-            data=params.model_dump(exclude_none=True, by_alias=True),
+            data=coerce_to_model(StartCuaTaskParams, params).model_dump(
+                exclude_none=True, by_alias=True
+            ),
         )
         return StartCuaTaskResponse(**response.data)
 
@@ -41,7 +48,9 @@ async def stop(self, job_id: str) -> BasicResponse:
         )
         return BasicResponse(**response.data)
 
-    async def start_and_wait(self, params: StartCuaTaskParams) -> CuaTaskResponse:
+    async def start_and_wait(
+        self, params: Union[StartCuaTaskParams, StartCuaTaskParamsDict]
+    ) -> CuaTaskResponse:
         job_start_resp = await self.start(params)
         job_id = job_start_resp.job_id
         if not job_id:

hyperbrowser/client/managers/async_manager/agents/gemini_computer_use.py

@@ -1,4 +1,7 @@
 import asyncio
+from typing import Union
+
+from .....models.params import coerce_to_model, StartGeminiComputerUseTaskParamsDict
 
 from hyperbrowser.exceptions import HyperbrowserError
 
@@ -17,11 +20,16 @@ def __init__(self, client):
         self._client = client
 
     async def start(
-        self, params: StartGeminiComputerUseTaskParams
+        self,
+        params: Union[
+            StartGeminiComputerUseTaskParams, StartGeminiComputerUseTaskParamsDict
+        ],
     ) -> StartGeminiComputerUseTaskResponse:
         response = await self._client.transport.post(
             self._client._build_url("/task/gemini-computer-use"),
-            data=params.model_dump(exclude_none=True, by_alias=True),
+            data=coerce_to_model(StartGeminiComputerUseTaskParams, params).model_dump(
+                exclude_none=True, by_alias=True
+            ),
         )
         return StartGeminiComputerUseTaskResponse(**response.data)
 
@@ -44,7 +52,10 @@ async def stop(self, job_id: str) -> BasicResponse:
         return BasicResponse(**response.data)
 
     async def start_and_wait(
-        self, params: StartGeminiComputerUseTaskParams
+        self,
+        params: Union[
+            StartGeminiComputerUseTaskParams, StartGeminiComputerUseTaskParamsDict
+        ],
     ) -> GeminiComputerUseTaskResponse:
         job_start_resp = await self.start(params)
         job_id = job_start_resp.job_id

hyperbrowser/client/managers/async_manager/agents/grok_computer_use.py

@@ -1,4 +1,7 @@
 import asyncio
+from typing import Union
+
+from .....models.params import coerce_to_model, StartGrokComputerUseTaskParamsDict
 
 from hyperbrowser.exceptions import HyperbrowserError
 
@@ -17,11 +20,16 @@ def __init__(self, client):
         self._client = client
 
     async def start(
-        self, params: StartGrokComputerUseTaskParams
+        self,
+        params: Union[
+            StartGrokComputerUseTaskParams, StartGrokComputerUseTaskParamsDict
+        ],
     ) -> StartGrokComputerUseTaskResponse:
         response = await self._client.transport.post(
             self._client._build_url("/task/grok-computer-use"),
-            data=params.model_dump(exclude_none=True, by_alias=True),
+            data=coerce_to_model(StartGrokComputerUseTaskParams, params).model_dump(
+                exclude_none=True, by_alias=True
+            ),
         )
         return StartGrokComputerUseTaskResponse(**response.data)
 
@@ -44,7 +52,10 @@ async def stop(self, job_id: str) -> BasicResponse:
         return BasicResponse(**response.data)
 
     async def start_and_wait(
-        self, params: StartGrokComputerUseTaskParams
+        self,
+        params: Union[
+            StartGrokComputerUseTaskParams, StartGrokComputerUseTaskParamsDict
+        ],
     ) -> GrokComputerUseTaskResponse:
         job_start_resp = await self.start(params)
         job_id = job_start_resp.job_id

hyperbrowser/client/managers/async_manager/agents/hyper_agent.py

@@ -1,4 +1,7 @@
 import asyncio
+from typing import Union
+
+from .....models.params import coerce_to_model, StartHyperAgentTaskParamsDict
 
 from hyperbrowser.exceptions import HyperbrowserError
 
@@ -17,11 +20,13 @@ def __init__(self, client):
         self._client = client
 
     async def start(
-        self, params: StartHyperAgentTaskParams
+        self, params: Union[StartHyperAgentTaskParams, StartHyperAgentTaskParamsDict]
     ) -> StartHyperAgentTaskResponse:
         response = await self._client.transport.post(
             self._client._build_url("/task/hyper-agent"),
-            data=params.model_dump(exclude_none=True, by_alias=True),
+            data=coerce_to_model(StartHyperAgentTaskParams, params).model_dump(
+                exclude_none=True, by_alias=True
+            ),
         )
         return StartHyperAgentTaskResponse(**response.data)
 
@@ -44,7 +49,7 @@ async def stop(self, job_id: str) -> BasicResponse:
         return BasicResponse(**response.data)
 
     async def start_and_wait(
-        self, params: StartHyperAgentTaskParams
+        self, params: Union[StartHyperAgentTaskParams, StartHyperAgentTaskParamsDict]
     ) -> HyperAgentTaskResponse:
         job_start_resp = await self.start(params)
         job_id = job_start_resp.job_id

hyperbrowser/client/managers/async_manager/crawl.py

@@ -1,6 +1,12 @@
 import asyncio
+from typing import Union
 
 from hyperbrowser.models.consts import POLLING_ATTEMPTS
+from ....models.params import (
+    coerce_to_model,
+    GetCrawlJobParamsDict,
+    StartCrawlJobParamsDict,
+)
 from ....models.crawl import (
     CrawlJobResponse,
     CrawlJobStatus,
@@ -16,7 +22,10 @@ class CrawlManager:
     def __init__(self, client):
         self._client = client
 
-    async def start(self, params: StartCrawlJobParams) -> StartCrawlJobResponse:
+    async def start(
+        self, params: Union[StartCrawlJobParams, StartCrawlJobParamsDict]
+    ) -> StartCrawlJobResponse:
+        params = coerce_to_model(StartCrawlJobParams, params)
         response = await self._client.transport.post(
             self._client._build_url("/crawl"),
             data=params.model_dump(exclude_none=True, by_alias=True),
@@ -30,16 +39,21 @@ async def get_status(self, job_id: str) -> CrawlJobStatusResponse:
         return CrawlJobStatusResponse(**response.data)
 
     async def get(
-        self, job_id: str, params: GetCrawlJobParams = GetCrawlJobParams()
+        self,
+        job_id: str,
+        params: Union[GetCrawlJobParams, GetCrawlJobParamsDict] = GetCrawlJobParams(),
     ) -> CrawlJobResponse:
+        params = coerce_to_model(GetCrawlJobParams, params)
         response = await self._client.transport.get(
             self._client._build_url(f"/crawl/{job_id}"),
             params=params.model_dump(exclude_none=True, by_alias=True),
         )
         return CrawlJobResponse(**response.data)
 
     async def start_and_wait(
-        self, params: StartCrawlJobParams, return_all_pages: bool = True
+        self,
+        params: Union[StartCrawlJobParams, StartCrawlJobParamsDict],
+        return_all_pages: bool = True,
     ) -> CrawlJobResponse:
         job_start_resp = await self.start(params)
         job_id = job_start_resp.job_id

hyperbrowser/client/managers/async_manager/extension.py

@@ -1,15 +1,19 @@
 import os
-from typing import List
+from typing import List, Union
 
 from hyperbrowser.exceptions import HyperbrowserError
+from hyperbrowser.models.params import coerce_to_model, CreateExtensionParamsDict
 from hyperbrowser.models.extension import CreateExtensionParams, ExtensionResponse
 
 
 class ExtensionManager:
     def __init__(self, client):
         self._client = client
 
-    async def create(self, params: CreateExtensionParams) -> ExtensionResponse:
+    async def create(
+        self, params: Union[CreateExtensionParams, CreateExtensionParamsDict]
+    ) -> ExtensionResponse:
+        params = coerce_to_model(CreateExtensionParams, params)
         file_path = params.file_path
         params.file_path = None
 

hyperbrowser/client/managers/async_manager/extract.py

@@ -1,6 +1,9 @@
 import asyncio
+from typing import Union
+
 from hyperbrowser.exceptions import HyperbrowserError
 from hyperbrowser.models.consts import POLLING_ATTEMPTS
+from hyperbrowser.models.params import coerce_to_model, StartExtractJobParamsDict
 from hyperbrowser.models.extract import (
     ExtractJobResponse,
     ExtractJobStatusResponse,
@@ -14,7 +17,10 @@ class ExtractManager:
     def __init__(self, client):
         self._client = client
 
-    async def start(self, params: StartExtractJobParams) -> StartExtractJobResponse:
+    async def start(
+        self, params: Union[StartExtractJobParams, StartExtractJobParamsDict]
+    ) -> StartExtractJobResponse:
+        params = coerce_to_model(StartExtractJobParams, params)
         if not params.schema_ and not params.prompt:
             raise HyperbrowserError("Either schema or prompt must be provided")
         if params.schema_:
@@ -41,7 +47,9 @@ async def get(self, job_id: str) -> ExtractJobResponse:
         )
         return ExtractJobResponse(**response.data)
 
-    async def start_and_wait(self, params: StartExtractJobParams) -> ExtractJobResponse:
+    async def start_and_wait(
+        self, params: Union[StartExtractJobParams, StartExtractJobParamsDict]
+    ) -> ExtractJobResponse:
         job_start_resp = await self.start(params)
         job_id = job_start_resp.job_id
         if not job_id: