Support mapping-based tool response fields

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

Author: cursoragent

hyperbrowser/tools/__init__.py

@@ -1,4 +1,5 @@
 import json
+from collections.abc import Mapping as MappingABC
 from typing import Any, Dict, Mapping
 
 from hyperbrowser.exceptions import HyperbrowserError
@@ -133,15 +134,30 @@ def _read_optional_tool_response_field(
 ) -> str:
     if response_data is None:
         return ""
-    try:
-        field_value = getattr(response_data, field_name)
-    except HyperbrowserError:
-        raise
-    except Exception as exc:
-        raise HyperbrowserError(
-            f"Failed to read {tool_name} response field '{field_name}'",
-            original_error=exc,
-        ) from exc
+    if isinstance(response_data, MappingABC):
+        try:
+            field_value = response_data[field_name]
+        except KeyError:
+            return ""
+        except HyperbrowserError:
+            raise
+        except Exception as exc:
+            raise HyperbrowserError(
+                f"Failed to read {tool_name} response field '{field_name}'",
+                original_error=exc,
+            ) from exc
+    else:
+        try:
+            field_value = getattr(response_data, field_name)
+        except AttributeError:
+            return ""
+        except HyperbrowserError:
+            raise
+        except Exception as exc:
+            raise HyperbrowserError(
+                f"Failed to read {tool_name} response field '{field_name}'",
+                original_error=exc,
+            ) from exc
     if field_value is None:
         return ""
     if not isinstance(field_value, str):
@@ -152,8 +168,22 @@ def _read_optional_tool_response_field(
 
 
 def _read_crawl_page_field(page: Any, *, field_name: str, page_index: int) -> Any:
+    if isinstance(page, MappingABC):
+        try:
+            return page[field_name]
+        except KeyError:
+            return None
+        except HyperbrowserError:
+            raise
+        except Exception as exc:
+            raise HyperbrowserError(
+                f"Failed to read crawl tool page field '{field_name}' at index {page_index}",
+                original_error=exc,
+            ) from exc
     try:
         return getattr(page, field_name)
+    except AttributeError:
+        return None
     except HyperbrowserError:
         raise
     except Exception as exc:

tests/test_tools_response_handling.py

@@ -1,4 +1,5 @@
 import asyncio
+from collections.abc import Mapping
 from types import SimpleNamespace
 from typing import Any, Optional
 
@@ -149,6 +150,45 @@ def test_scrape_tool_rejects_non_string_markdown_field():
         WebsiteScrapeTool.runnable(client, {"url": "https://example.com"})
 
 
+def test_scrape_tool_supports_mapping_response_data():
+    client = _SyncScrapeClient(_Response(data={"markdown": "from mapping"}))
+
+    output = WebsiteScrapeTool.runnable(client, {"url": "https://example.com"})
+
+    assert output == "from mapping"
+
+
+def test_scrape_tool_returns_empty_for_missing_mapping_markdown_field():
+    client = _SyncScrapeClient(_Response(data={"other": "value"}))
+
+    output = WebsiteScrapeTool.runnable(client, {"url": "https://example.com"})
+
+    assert output == ""
+
+
+def test_scrape_tool_wraps_mapping_field_read_failures():
+    class _BrokenMapping(Mapping[str, object]):
+        def __iter__(self):
+            yield "markdown"
+
+        def __len__(self) -> int:
+            return 1
+
+        def __getitem__(self, key: str) -> object:
+            _ = key
+            raise RuntimeError("cannot read mapping field")
+
+    client = _SyncScrapeClient(_Response(data=_BrokenMapping()))
+
+    with pytest.raises(
+        HyperbrowserError,
+        match="Failed to read scrape tool response field 'markdown'",
+    ) as exc_info:
+        WebsiteScrapeTool.runnable(client, {"url": "https://example.com"})
+
+    assert exc_info.value.original_error is not None
+
+
 def test_screenshot_tool_rejects_non_string_screenshot_field():
     client = _SyncScrapeClient(_Response(data=SimpleNamespace(screenshot=123)))
 
@@ -185,6 +225,48 @@ def markdown(self) -> str:
     assert exc_info.value.original_error is not None
 
 
+def test_crawl_tool_supports_mapping_page_items():
+    client = _SyncCrawlClient(
+        _Response(data=[{"url": "https://example.com", "markdown": "mapping body"}])
+    )
+
+    output = WebsiteCrawlTool.runnable(client, {"url": "https://example.com"})
+
+    assert "Url: https://example.com" in output
+    assert "mapping body" in output
+
+
+def test_crawl_tool_skips_mapping_pages_without_markdown_key():
+    client = _SyncCrawlClient(_Response(data=[{"url": "https://example.com"}]))
+
+    output = WebsiteCrawlTool.runnable(client, {"url": "https://example.com"})
+
+    assert output == ""
+
+
+def test_crawl_tool_wraps_mapping_page_value_read_failures():
+    class _BrokenPage(Mapping[str, object]):
+        def __iter__(self):
+            yield "markdown"
+
+        def __len__(self) -> int:
+            return 1
+
+        def __getitem__(self, key: str) -> object:
+            _ = key
+            raise RuntimeError("cannot read page field")
+
+    client = _SyncCrawlClient(_Response(data=[_BrokenPage()]))
+
+    with pytest.raises(
+        HyperbrowserError,
+        match="Failed to read crawl tool page field 'markdown' at index 0",
+    ) as exc_info:
+        WebsiteCrawlTool.runnable(client, {"url": "https://example.com"})
+
+    assert exc_info.value.original_error is not None
+
+
 def test_crawl_tool_rejects_non_string_page_urls():
     client = _SyncCrawlClient(
         _Response(data=[SimpleNamespace(url=42, markdown="body")])
@@ -233,6 +315,14 @@ def test_browser_use_tool_rejects_non_string_final_result():
         BrowserUseTool.runnable(client, {"task": "search docs"})
 
 
+def test_browser_use_tool_supports_mapping_response_data():
+    client = _SyncBrowserUseClient(_Response(data={"final_result": "mapping output"}))
+
+    output = BrowserUseTool.runnable(client, {"task": "search docs"})
+
+    assert output == "mapping output"
+
+
 def test_async_scrape_tool_wraps_response_data_read_failures():
     async def run() -> None:
         client = _AsyncScrapeClient(