llama-index-tools-snaprender 0.1.0__tar.gz

llama_index_tools_snaprender-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+node_modules/
+dist/
+*.tgz
+.DS_Store
+*.pyc
+__pycache__/
+.venv/
+*.egg-info/
+drafts/
+.npmrc
+*.mcpb
+.mcpregistry_*

llama_index_tools_snaprender-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SnapRender
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

llama_index_tools_snaprender-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: llama-index-tools-snaprender
+Version: 0.1.0
+Summary: LlamaIndex tools for SnapRender: website screenshots the agent can see, and rendered pages as markdown
+Project-URL: Homepage, https://snap-render.com
+Project-URL: Documentation, https://snap-render.com/docs
+Project-URL: Source, https://github.com/User0856/snaprender-integrations/tree/main/llamaindex
+Author-email: SnapRender <support@snap-render.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,llama-index,llamaindex,markdown,screenshot,snaprender,tools,web-scraping,website-screenshot
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <4.0,>=3.9
+Requires-Dist: httpx>=0.24
+Requires-Dist: llama-index-core<0.15,>=0.13.0
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Requires-Dist: respx>=0.21; extra == 'test'
+Description-Content-Type: text/markdown
+
+# llama-index-tools-snaprender
+
+[LlamaIndex](https://www.llamaindex.ai) tools for [SnapRender](https://snap-render.com). Your agent can take screenshots of web pages and read rendered pages as markdown. Pages load in a real Chrome browser with ads and cookie banners removed, and the screenshot goes back to the model as an image block it can look at.
+
+- `take_screenshot`: capture a URL or raw HTML (desktop, phone or tablet, viewport or full page). Returns a text summary plus an `ImageBlock`.
+- `extract_content`: read a page after JavaScript runs, as markdown, main article text, plain text, links or metadata.
+
+Both tools have async versions, used automatically by async agents.
+
+The free plan includes 200 captures a month. Get a key at [app.snap-render.com/auth/signup](https://app.snap-render.com/auth/signup).
+
+## Install
+
+```bash
+pip install llama-index-tools-snaprender
+export SNAPRENDER_API_KEY=sk_live_...
+```
+
+## Usage
+
+```python
+import asyncio
+
+from llama_index.core.agent.workflow import FunctionAgent
+from llama_index.llms.anthropic import Anthropic
+from llama_index.tools.snaprender import SnapRenderToolSpec
+
+agent = FunctionAgent(
+    tools=SnapRenderToolSpec().to_tool_list(),
+    llm=Anthropic(model="claude-sonnet-5-5"),
+    system_prompt="You can look at web pages with take_screenshot and read them with extract_content.",
+)
+
+
+async def main() -> None:
+    response = await agent.run(
+        "Take a screenshot of https://www.llamaindex.ai on an iPhone (device iphone_14) "
+        "and tell me what the first screen shows."
+    )
+    print(response)
+
+
+asyncio.run(main())
+```
+
+Use any LLM integration that accepts images in tool results. Note (Nov 2026): `llama-index-llms-anthropic` 0.12.3 fails with the `anthropic` SDK 2.x (`'typing.Union' object is not callable`) before any tool runs; `pip install "anthropic<2"` works until a fix ships.
+
+Call the tools directly too:
+
+```python
+spec = SnapRenderToolSpec()
+blocks = spec.take_screenshot(url="https://example.com", full_page=True)  # [TextBlock, ImageBlock]
+markdown = spec.extract_content(url="https://example.com", type="article")
+```
+
+## Tool inputs
+
+`take_screenshot` (pass `url` or `html`): `format` (`jpeg` default at quality 80, `png`, `webp`), `full_page`, `lazy_load`, `device` (`iphone_14`, `iphone_15_pro`, `pixel_7`, `ipad_pro`, `macbook_pro`), `width` and `height` (CSS px, default 1280x800), `dark_mode`, `delay` (ms), `quality`, `hide_selectors`, `click_selector`, `block_ads` and `block_cookie_banners` (both default true), `cache` (accept a copy from the last 24 hours, free; default false).
+
+`extract_content`: `url`, `type` (`markdown` default, `article`, `text`, `html`, `links`, `metadata`), `selector`, `max_length` (default 100000), `delay`, `block_ads`, `block_cookie_banners`, `cache`.
+
+Captures render at 2x device scale, so a 1280 px viewport gives a 2560 px wide image. When an image is over `max_image_bytes` (default 5 MB) or `max_image_dimension` (default 8000 px), the tool returns only the text summary and tells the model to retry with `full_page=False` or a smaller viewport.
+
+## Options
+
+```python
+SnapRenderToolSpec(
+    api_key=None,                # default: SNAPRENDER_API_KEY
+    base_url="https://app.snap-render.com",
+    timeout=90.0,                # seconds
+    max_retries=1,               # after a per-minute rate limit, waits Retry-After (up to 60 s)
+    max_image_bytes=5_000_000,
+    max_image_dimension=8000,
+    get_api_key=None,            # callable returning a key at call time
+)
+```
+
+## Errors
+
+Failed requests raise `SnapRenderError` with `status`, `code` and the API's message, for example `SnapRender 422 TARGET_UNREACHABLE: The target website could not be reached...`. Agents pass the message to the model so it can explain or try another URL. Failed renders do not use a capture. Monthly quota errors are never retried.
+
+The tools cannot reach localhost, private networks or pages behind a login. If a capture of your own site shows a security check page, see [snap-render.com/docs/allow-snaprender](https://snap-render.com/docs/allow-snaprender).
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest                                        # unit tests, no network
+SNAPRENDER_TEST_KEY=sk_live_... pytest tests/test_live.py   # live API tests
+```
+
+## Links
+
+- API docs: [snap-render.com/docs](https://snap-render.com/docs)
+- MCP server (Claude, Cursor and other MCP clients): [snaprender-mcp](https://www.npmjs.com/package/snaprender-mcp)
+- Support: support@snap-render.com
+
+MIT License

llama_index_tools_snaprender-0.1.0/README.md

@@ -0,0 +1,98 @@
+# llama-index-tools-snaprender
+
+[LlamaIndex](https://www.llamaindex.ai) tools for [SnapRender](https://snap-render.com). Your agent can take screenshots of web pages and read rendered pages as markdown. Pages load in a real Chrome browser with ads and cookie banners removed, and the screenshot goes back to the model as an image block it can look at.
+
+- `take_screenshot`: capture a URL or raw HTML (desktop, phone or tablet, viewport or full page). Returns a text summary plus an `ImageBlock`.
+- `extract_content`: read a page after JavaScript runs, as markdown, main article text, plain text, links or metadata.
+
+Both tools have async versions, used automatically by async agents.
+
+The free plan includes 200 captures a month. Get a key at [app.snap-render.com/auth/signup](https://app.snap-render.com/auth/signup).
+
+## Install
+
+```bash
+pip install llama-index-tools-snaprender
+export SNAPRENDER_API_KEY=sk_live_...
+```
+
+## Usage
+
+```python
+import asyncio
+
+from llama_index.core.agent.workflow import FunctionAgent
+from llama_index.llms.anthropic import Anthropic
+from llama_index.tools.snaprender import SnapRenderToolSpec
+
+agent = FunctionAgent(
+    tools=SnapRenderToolSpec().to_tool_list(),
+    llm=Anthropic(model="claude-sonnet-5-5"),
+    system_prompt="You can look at web pages with take_screenshot and read them with extract_content.",
+)
+
+
+async def main() -> None:
+    response = await agent.run(
+        "Take a screenshot of https://www.llamaindex.ai on an iPhone (device iphone_14) "
+        "and tell me what the first screen shows."
+    )
+    print(response)
+
+
+asyncio.run(main())
+```
+
+Use any LLM integration that accepts images in tool results. Note (Nov 2026): `llama-index-llms-anthropic` 0.12.3 fails with the `anthropic` SDK 2.x (`'typing.Union' object is not callable`) before any tool runs; `pip install "anthropic<2"` works until a fix ships.
+
+Call the tools directly too:
+
+```python
+spec = SnapRenderToolSpec()
+blocks = spec.take_screenshot(url="https://example.com", full_page=True)  # [TextBlock, ImageBlock]
+markdown = spec.extract_content(url="https://example.com", type="article")
+```
+
+## Tool inputs
+
+`take_screenshot` (pass `url` or `html`): `format` (`jpeg` default at quality 80, `png`, `webp`), `full_page`, `lazy_load`, `device` (`iphone_14`, `iphone_15_pro`, `pixel_7`, `ipad_pro`, `macbook_pro`), `width` and `height` (CSS px, default 1280x800), `dark_mode`, `delay` (ms), `quality`, `hide_selectors`, `click_selector`, `block_ads` and `block_cookie_banners` (both default true), `cache` (accept a copy from the last 24 hours, free; default false).
+
+`extract_content`: `url`, `type` (`markdown` default, `article`, `text`, `html`, `links`, `metadata`), `selector`, `max_length` (default 100000), `delay`, `block_ads`, `block_cookie_banners`, `cache`.
+
+Captures render at 2x device scale, so a 1280 px viewport gives a 2560 px wide image. When an image is over `max_image_bytes` (default 5 MB) or `max_image_dimension` (default 8000 px), the tool returns only the text summary and tells the model to retry with `full_page=False` or a smaller viewport.
+
+## Options
+
+```python
+SnapRenderToolSpec(
+    api_key=None,                # default: SNAPRENDER_API_KEY
+    base_url="https://app.snap-render.com",
+    timeout=90.0,                # seconds
+    max_retries=1,               # after a per-minute rate limit, waits Retry-After (up to 60 s)
+    max_image_bytes=5_000_000,
+    max_image_dimension=8000,
+    get_api_key=None,            # callable returning a key at call time
+)
+```
+
+## Errors
+
+Failed requests raise `SnapRenderError` with `status`, `code` and the API's message, for example `SnapRender 422 TARGET_UNREACHABLE: The target website could not be reached...`. Agents pass the message to the model so it can explain or try another URL. Failed renders do not use a capture. Monthly quota errors are never retried.
+
+The tools cannot reach localhost, private networks or pages behind a login. If a capture of your own site shows a security check page, see [snap-render.com/docs/allow-snaprender](https://snap-render.com/docs/allow-snaprender).
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest                                        # unit tests, no network
+SNAPRENDER_TEST_KEY=sk_live_... pytest tests/test_live.py   # live API tests
+```
+
+## Links
+
+- API docs: [snap-render.com/docs](https://snap-render.com/docs)
+- MCP server (Claude, Cursor and other MCP clients): [snaprender-mcp](https://www.npmjs.com/package/snaprender-mcp)
+- Support: support@snap-render.com
+
+MIT License

llama_index_tools_snaprender-0.1.0/llama_index/tools/snaprender/__init__.py

@@ -0,0 +1,3 @@
+from llama_index.tools.snaprender.base import SnapRenderError, SnapRenderToolSpec, __version__
+
+__all__ = ["SnapRenderToolSpec", "SnapRenderError", "__version__"]

llama_index_tools_snaprender-0.1.0/llama_index/tools/snaprender/base.py

@@ -0,0 +1,359 @@
+"""SnapRender tool spec: website screenshots and rendered page content for LlamaIndex agents."""
+
+
+import asyncio
+import os
+import struct
+import time
+from typing import Any, Callable, Dict, List, Literal, Optional, Tuple, Union
+
+import httpx
+from llama_index.core.base.llms.types import ImageBlock, TextBlock
+from llama_index.core.tools.tool_spec.base import BaseToolSpec
+
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://app.snap-render.com"
+SIGNUP_URL = "https://app.snap-render.com/auth/signup"
+
+Device = Literal["iphone_14", "iphone_15_pro", "pixel_7", "ipad_pro", "macbook_pro"]
+ImageFormat = Literal["jpeg", "png", "webp"]
+ExtractType = Literal["markdown", "text", "html", "article", "links", "metadata"]
+
+
+class SnapRenderError(Exception):
+    """A failed SnapRender request, with the API's status, code and message."""
+
+    def __init__(self, status: int, code: str, message: str, retry_after: Optional[float] = None):
+        super().__init__(f"SnapRender {status} {code}: {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+        self.retry_after = retry_after
+
+
+def image_size(data: bytes) -> Optional[Tuple[int, int]]:
+    """Read (width, height) from PNG, JPEG or WebP bytes without decoding the image."""
+    if len(data) >= 24 and data[:8] == b"\x89PNG\r\n\x1a\n":
+        return struct.unpack(">II", data[16:24])
+    if len(data) >= 4 and data[:2] == b"\xff\xd8":
+        i = 2
+        while i + 9 < len(data):
+            if data[i] != 0xFF:
+                i += 1
+                continue
+            marker = data[i + 1]
+            if marker in (0xD8, 0x01) or 0xD0 <= marker <= 0xD7:
+                i += 2
+                continue
+            length = struct.unpack(">H", data[i + 2 : i + 4])[0]
+            if 0xC0 <= marker <= 0xCF and marker not in (0xC4, 0xC8, 0xCC):
+                h, w = struct.unpack(">HH", data[i + 5 : i + 9])
+                return w, h
+            i += 2 + length
+        return None
+    if len(data) >= 30 and data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        chunk = data[12:16]
+        if chunk == b"VP8X":
+            w = 1 + int.from_bytes(data[24:27], "little")
+            h = 1 + int.from_bytes(data[27:30], "little")
+            return w, h
+        if chunk == b"VP8L":
+            b = int.from_bytes(data[21:25], "little")
+            return (b & 0x3FFF) + 1, ((b >> 14) & 0x3FFF) + 1
+        if chunk == b"VP8 ":
+            w = int.from_bytes(data[26:28], "little") & 0x3FFF
+            h = int.from_bytes(data[28:30], "little") & 0x3FFF
+            return w, h
+    return None
+
+
+def _compact(params: Dict[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in params.items() if v is not None}
+
+
+def _error_from(response: httpx.Response) -> SnapRenderError:
+    code = f"HTTP_{response.status_code}"
+    message = response.reason_phrase or "Request failed."
+    try:
+        err = response.json().get("error") or {}
+        code = err.get("code") or code
+        message = err.get("message") or message
+    except Exception:
+        pass
+    retry_after: Optional[float] = None
+    try:
+        retry_after = float(response.headers.get("Retry-After", ""))
+    except ValueError:
+        pass
+    return SnapRenderError(response.status_code, code, message, retry_after)
+
+
+class SnapRenderToolSpec(BaseToolSpec):
+    """SnapRender tools: take website screenshots the model can see, and read rendered pages.
+
+    Pages load in a real Chrome browser with ads and cookie banners removed.
+    The free plan includes 200 captures a month: https://app.snap-render.com/auth/signup
+    """
+
+    spec_functions = [
+        ("take_screenshot", "atake_screenshot"),
+        ("extract_content", "aextract_content"),
+    ]
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 90.0,
+        max_retries: int = 1,
+        max_image_bytes: int = 5_000_000,
+        max_image_dimension: int = 8000,
+        get_api_key: Optional[Callable[[], str]] = None,
+    ) -> None:
+        """Create the tool spec.
+
+        Args:
+            api_key: SnapRender API key. Defaults to the SNAPRENDER_API_KEY environment variable.
+            base_url: API base URL.
+            timeout: Request timeout in seconds (full-page captures can be slow).
+            max_retries: Retries after a per-minute rate limit (HTTP 429 RATE_LIMITED), waiting as
+                long as Retry-After says (up to 60 s). Monthly quota errors are never retried.
+            max_image_bytes: Largest image sent to the model; bigger captures return a text note.
+            max_image_dimension: Largest width or height in pixels sent to the model.
+            get_api_key: Optional callable that returns a key at call time (secret stores).
+        """
+        self._api_key = api_key
+        self._get_api_key = get_api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._max_image_bytes = max_image_bytes
+        self._max_image_dimension = max_image_dimension
+
+    # -- key and HTTP ---------------------------------------------------------------
+
+    def _key(self) -> str:
+        key = self._api_key or (self._get_api_key() if self._get_api_key else None)
+        key = key or os.environ.get("SNAPRENDER_API_KEY")
+        if key:
+            return key
+        # TODO(agent-trial): when the keyless agent trial key ships (POST /v1/agent-trial,
+        # returns an sk_trial_ key), mint and cache one here instead of raising.
+        raise SnapRenderError(
+            401,
+            "MISSING_API_KEY",
+            "No API key. Set SNAPRENDER_API_KEY or pass api_key. "
+            f"Get a free key (200 captures a month) at {SIGNUP_URL}",
+        )
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "X-API-Key": self._key(),
+            "Content-Type": "application/json",
+            "User-Agent": f"llama-index-tools-snaprender/{__version__}",
+        }
+
+    def _retry_wait(self, error: SnapRenderError, attempt: int) -> Optional[float]:
+        if error.code != "RATE_LIMITED" or attempt >= self._max_retries:
+            return None
+        wait = error.retry_after or 5.0
+        return wait if wait <= 60 else None
+
+    def _post(self, path: str, body: Dict[str, Any]) -> httpx.Response:
+        attempt = 0
+        while True:
+            with httpx.Client(timeout=self._timeout) as client:
+                response = client.post(f"{self._base_url}{path}", json=body, headers=self._headers())
+            if response.is_success:
+                return response
+            error = _error_from(response)
+            wait = self._retry_wait(error, attempt)
+            if wait is None:
+                raise error
+            attempt += 1
+            time.sleep(wait)
+
+    async def _apost(self, path: str, body: Dict[str, Any]) -> httpx.Response:
+        attempt = 0
+        while True:
+            async with httpx.AsyncClient(timeout=self._timeout) as client:
+                response = await client.post(f"{self._base_url}{path}", json=body, headers=self._headers())
+            if response.is_success:
+                return response
+            error = _error_from(response)
+            wait = self._retry_wait(error, attempt)
+            if wait is None:
+                raise error
+            attempt += 1
+            await asyncio.sleep(wait)
+
+    # -- result shaping -------------------------------------------------------------
+
+    def _screenshot_body(self, **params: Any) -> Dict[str, Any]:
+        url, html = params.get("url"), params.get("html")
+        if bool(url) == bool(html):
+            raise ValueError("Pass exactly one of url or html.")
+        fmt = params.get("format") or "jpeg"
+        params["format"] = fmt
+        if params.get("quality") is None and fmt != "png":
+            params["quality"] = 80
+        params["response_type"] = "binary"
+        return _compact(params)
+
+    def _screenshot_blocks(self, source: str, response: httpx.Response) -> List[Union[TextBlock, ImageBlock]]:
+        data = response.content
+        media_type = response.headers.get("Content-Type", "image/jpeg").split(";")[0]
+        size = image_size(data)
+        remaining = response.headers.get("X-Remaining-Credits")
+        summary = f"Screenshot of {source} ("
+        if size:
+            summary += f"{size[0]}x{size[1]} px, "
+        summary += f"{len(data)} bytes, cache {response.headers.get('X-Cache', 'MISS')}"
+        if remaining is not None:
+            summary += f", {remaining} captures left this period"
+        summary += ")."
+        if len(data) > self._max_image_bytes:
+            summary += (
+                f" Image is over the {self._max_image_bytes} byte limit for the model and was left out. "
+                "Try full_page false, a smaller viewport, or format jpeg with lower quality."
+            )
+            return [TextBlock(text=summary)]
+        if size and max(size) > self._max_image_dimension:
+            summary += (
+                f" Image is over the {self._max_image_dimension} px limit for the model and was left out. "
+                "Try full_page false or a shorter viewport."
+            )
+            return [TextBlock(text=summary)]
+        return [TextBlock(text=summary), ImageBlock(image=data, image_mimetype=media_type)]
+
+    @staticmethod
+    def _extract_text(response: httpx.Response) -> str:
+        data = response.json()
+        content = data.get("content")
+        if not isinstance(content, str):
+            import json
+
+            content = json.dumps(content, indent=2, ensure_ascii=False)
+        meta = f"type {data.get('type')}"
+        if data.get("wordCount"):
+            meta += f", {data['wordCount']} words"
+        return f"{content}\n\n---\nSource: {data.get('url')} ({meta})"
+
+    # -- tools ----------------------------------------------------------------------
+
+    def take_screenshot(
+        self,
+        url: Optional[str] = None,
+        html: Optional[str] = None,
+        format: Optional[ImageFormat] = None,
+        full_page: Optional[bool] = None,
+        lazy_load: Optional[bool] = None,
+        device: Optional[Device] = None,
+        width: Optional[int] = None,
+        height: Optional[int] = None,
+        dark_mode: Optional[bool] = None,
+        delay: Optional[int] = None,
+        quality: Optional[int] = None,
+        hide_selectors: Optional[str] = None,
+        click_selector: Optional[str] = None,
+        block_ads: Optional[bool] = None,
+        block_cookie_banners: Optional[bool] = None,
+        cache: Optional[bool] = None,
+    ) -> List[Union[TextBlock, ImageBlock]]:
+        """Capture a screenshot of a public web page (or raw HTML) in a real Chrome browser and look at it.
+
+        Use it to check layout, visuals, a phone view (device) or a whole page (full_page).
+        Ads and cookie banners are removed by default. Cannot reach localhost, private
+        networks or pages behind a login.
+
+        Args:
+            url: Public http or https URL to capture. Use this or html, not both.
+            html: Raw HTML to render instead of a URL (max 2 MB).
+            format: Image format: jpeg (default, smallest), png or webp.
+            full_page: Capture the whole scrollable page instead of the first screen.
+            lazy_load: With full_page, scroll first so lazy-loaded images appear. Slower.
+            device: Emulate iphone_14, iphone_15_pro, pixel_7, ipad_pro or macbook_pro. Omit for desktop.
+            width: Viewport width in CSS pixels (320-3840, default 1280).
+            height: Viewport height in CSS pixels (200-10000, default 800).
+            dark_mode: Emulate prefers-color-scheme: dark.
+            delay: Extra wait in milliseconds after load (0-10000).
+            quality: JPEG or WebP quality (1-100).
+            hide_selectors: Comma-separated CSS selectors to hide before capture.
+            click_selector: CSS selector to click before capture.
+            block_ads: Block ads and trackers (default true).
+            block_cookie_banners: Remove cookie consent banners (default true).
+            cache: Accept a copy from the last 24 hours (free). Default false: render now.
+        """
+        params = {k: v for k, v in locals().items() if k != "self"}
+        body = self._screenshot_body(**params)
+        return self._screenshot_blocks(url or "html", self._post("/v1/screenshot", body))
+
+    async def atake_screenshot(
+        self,
+        url: Optional[str] = None,
+        html: Optional[str] = None,
+        format: Optional[ImageFormat] = None,
+        full_page: Optional[bool] = None,
+        lazy_load: Optional[bool] = None,
+        device: Optional[Device] = None,
+        width: Optional[int] = None,
+        height: Optional[int] = None,
+        dark_mode: Optional[bool] = None,
+        delay: Optional[int] = None,
+        quality: Optional[int] = None,
+        hide_selectors: Optional[str] = None,
+        click_selector: Optional[str] = None,
+        block_ads: Optional[bool] = None,
+        block_cookie_banners: Optional[bool] = None,
+        cache: Optional[bool] = None,
+    ) -> List[Union[TextBlock, ImageBlock]]:
+        """Async version of take_screenshot."""
+        params = {k: v for k, v in locals().items() if k != "self"}
+        body = self._screenshot_body(**params)
+        return self._screenshot_blocks(url or "html", await self._apost("/v1/screenshot", body))
+
+    def extract_content(
+        self,
+        url: str,
+        type: Optional[ExtractType] = None,
+        selector: Optional[str] = None,
+        max_length: Optional[int] = None,
+        delay: Optional[int] = None,
+        block_ads: Optional[bool] = None,
+        block_cookie_banners: Optional[bool] = None,
+        cache: Optional[bool] = None,
+    ) -> str:
+        """Read a public web page after it renders in a real browser and return its content.
+
+        JavaScript runs and cookie banners are removed, so it reads pages that plain HTTP
+        fetches get wrong.
+
+        Args:
+            url: Public http or https URL to read.
+            type: markdown (default, full page), article (main text only), text, html,
+                links (list of links) or metadata (title, description, Open Graph).
+            selector: CSS selector to read only part of the page, e.g. 'main'.
+            max_length: Maximum characters to return (default 100000).
+            delay: Extra wait in milliseconds after load (0-10000).
+            block_ads: Block ads and trackers (default true).
+            block_cookie_banners: Remove cookie consent banners (default true).
+            cache: Accept a cached result from the last 24 hours. Default false.
+        """
+        params = _compact({k: v for k, v in locals().items() if k != "self"})
+        return self._extract_text(self._post("/v1/extract", params))
+
+    async def aextract_content(
+        self,
+        url: str,
+        type: Optional[ExtractType] = None,
+        selector: Optional[str] = None,
+        max_length: Optional[int] = None,
+        delay: Optional[int] = None,
+        block_ads: Optional[bool] = None,
+        block_cookie_banners: Optional[bool] = None,
+        cache: Optional[bool] = None,
+    ) -> str:
+        """Async version of extract_content."""
+        params = _compact({k: v for k, v in locals().items() if k != "self"})
+        return self._extract_text(await self._apost("/v1/extract", params))

llama_index_tools_snaprender-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "llama-index-tools-snaprender"
+version = "0.1.0"
+description = "LlamaIndex tools for SnapRender: website screenshots the agent can see, and rendered pages as markdown"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9,<4.0"
+authors = [{ name = "SnapRender", email = "support@snap-render.com" }]
+keywords = ["llama-index", "llamaindex", "tools", "agent", "screenshot", "website-screenshot", "web-scraping", "markdown", "snaprender"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "llama-index-core>=0.13.0,<0.15",
+    "httpx>=0.24",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7", "pytest-asyncio>=0.23", "respx>=0.21"]
+
+[project.urls]
+Homepage = "https://snap-render.com"
+Documentation = "https://snap-render.com/docs"
+Source = "https://github.com/User0856/snaprender-integrations/tree/main/llamaindex"
+
+[tool.hatch.build.targets.sdist]
+include = ["llama_index/", "README.md", "LICENSE", "tests/"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["llama_index"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

llama_index_tools_snaprender-0.1.0/tests/test_live.py

@@ -0,0 +1,65 @@
+"""Live API tests. Run only when SNAPRENDER_TEST_KEY or SNAPRENDER_API_KEY is set (about 8 captures)."""
+
+import os
+import time
+
+import pytest
+from llama_index.core.base.llms.types import ImageBlock
+
+from llama_index.tools.snaprender import SnapRenderError, SnapRenderToolSpec
+
+KEY = os.environ.get("SNAPRENDER_TEST_KEY") or os.environ.get("SNAPRENDER_API_KEY")
+pytestmark = pytest.mark.skipif(not KEY, reason="no SnapRender key in the environment")
+
+
+@pytest.fixture(autouse=True)
+def pace():
+    # The free plan allows 10 requests a minute.
+    yield
+    time.sleep(6.5)
+
+
+@pytest.fixture
+def spec():
+    return SnapRenderToolSpec(api_key=KEY)
+
+
+def test_screenshot_jpeg(spec):
+    blocks = spec.take_screenshot(url="https://example.com")
+    assert "2560x1600 px" in blocks[0].text
+    assert isinstance(blocks[1], ImageBlock) and blocks[1].image_mimetype == "image/jpeg"
+
+
+def test_screenshot_device_png(spec):
+    blocks = spec.take_screenshot(url="https://example.com", device="pixel_7", format="png")
+    assert blocks[1].image_mimetype == "image/png"
+
+
+def test_screenshot_html_full_page_dark(spec):
+    blocks = spec.take_screenshot(html="<h1>Hello from LlamaIndex</h1>", full_page=True, dark_mode=True, width=640, height=360)
+    assert blocks[0].text.startswith("Screenshot of html") and len(blocks) == 2
+
+
+async def test_async_webp(spec):
+    blocks = await spec.atake_screenshot(url="https://example.com", format="webp", quality=60)
+    assert blocks[1].image_mimetype == "image/webp"
+
+
+def test_unreachable(spec):
+    with pytest.raises(SnapRenderError) as info:
+        spec.take_screenshot(url="https://nonexistent-domain-snaprender-test-123.com")
+    assert info.value.code == "TARGET_UNREACHABLE"
+
+
+def test_bad_key():
+    with pytest.raises(SnapRenderError) as info:
+        SnapRenderToolSpec(api_key="sk_live_invalid").take_screenshot(url="https://example.com")
+    assert info.value.status == 401
+
+
+def test_extract(spec):
+    assert "documentation examples" in spec.extract_content(url="https://example.com", max_length=5000)
+
+
+async def test_async_extract_links(spec):
+    assert "iana.org" in await spec.aextract_content(url="https://example.com", type="links")

llama_index_tools_snaprender-0.1.0/tests/test_snaprender.py

@@ -0,0 +1,173 @@
+import base64
+import json
+import struct
+
+import httpx
+import pytest
+import respx
+from llama_index.core.base.llms.types import ImageBlock, TextBlock
+from llama_index.core.tools.tool_spec.base import BaseToolSpec
+
+from llama_index.tools.snaprender import SnapRenderError, SnapRenderToolSpec
+from llama_index.tools.snaprender.base import image_size
+
+PNG = base64.b64decode(
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="
+)
+API = "https://app.snap-render.com"
+
+
+def png_of_size(width: int, height: int) -> bytes:
+    return PNG[:16] + struct.pack(">II", width, height) + PNG[24:]
+
+
+def test_is_a_tool_spec_with_sync_and_async_tools():
+    tools = SnapRenderToolSpec(api_key="k").to_tool_list()
+    assert isinstance(SnapRenderToolSpec(api_key="k"), BaseToolSpec)
+    assert [t.metadata.name for t in tools] == ["take_screenshot", "extract_content"]
+    assert all(t.async_fn is not None for t in tools)
+    device = tools[0].metadata.get_parameters_dict()["properties"]["device"]
+    assert device["anyOf"][0]["enum"] == ["iphone_14", "iphone_15_pro", "pixel_7", "ipad_pro", "macbook_pro"]
+
+
+@respx.mock
+def test_take_screenshot_posts_defaults_and_returns_image_block():
+    route = respx.post(f"{API}/v1/screenshot").mock(
+        return_value=httpx.Response(
+            200, content=PNG, headers={"Content-Type": "image/jpeg", "X-Cache": "MISS", "X-Remaining-Credits": "41"}
+        )
+    )
+    blocks = SnapRenderToolSpec(api_key="sk_test").take_screenshot(url="https://example.com", device="iphone_14")
+    request = route.calls.last.request
+    assert request.headers["X-API-Key"] == "sk_test"
+    assert request.headers["User-Agent"].startswith("llama-index-tools-snaprender/")
+    assert json.loads(request.content) == {
+        "url": "https://example.com",
+        "device": "iphone_14",
+        "format": "jpeg",
+        "quality": 80,
+        "response_type": "binary",
+    }
+    assert isinstance(blocks[0], TextBlock)
+    assert "1x1 px" in blocks[0].text and "41 captures left" in blocks[0].text
+    assert isinstance(blocks[1], ImageBlock)
+    assert blocks[1].image_mimetype == "image/jpeg"
+
+
+@respx.mock
+def test_png_sends_no_quality():
+    route = respx.post(f"{API}/v1/screenshot").mock(return_value=httpx.Response(200, content=PNG))
+    SnapRenderToolSpec(api_key="k").take_screenshot(url="https://a.test", format="png")
+    assert "quality" not in json.loads(route.calls.last.request.content)
+
+
+def test_url_or_html_exactly_one():
+    spec = SnapRenderToolSpec(api_key="k")
+    with pytest.raises(ValueError):
+        spec.take_screenshot()
+    with pytest.raises(ValueError):
+        spec.take_screenshot(url="https://a.test", html="<p>")
+
+
+def test_reads_env_key(monkeypatch):
+    monkeypatch.setenv("SNAPRENDER_API_KEY", "sk_env")
+    assert SnapRenderToolSpec()._key() == "sk_env"
+
+
+def test_missing_key_explains_free_plan(monkeypatch):
+    monkeypatch.delenv("SNAPRENDER_API_KEY", raising=False)
+    with pytest.raises(SnapRenderError, match="200 captures a month"):
+        SnapRenderToolSpec()._key()
+
+
+def test_get_api_key_callable(monkeypatch):
+    monkeypatch.delenv("SNAPRENDER_API_KEY", raising=False)
+    assert SnapRenderToolSpec(get_api_key=lambda: "sk_cb")._key() == "sk_cb"
+
+
+@respx.mock
+def test_api_error_code_and_message():
+    respx.post(f"{API}/v1/screenshot").mock(
+        return_value=httpx.Response(
+            422, json={"error": {"code": "TARGET_UNREACHABLE", "message": "The target website could not be reached."}}
+        )
+    )
+    with pytest.raises(SnapRenderError) as info:
+        SnapRenderToolSpec(api_key="k").take_screenshot(url="https://nope.test")
+    assert info.value.status == 422 and info.value.code == "TARGET_UNREACHABLE"
+    assert "could not be reached" in str(info.value)
+
+
+@respx.mock
+def test_non_json_error():
+    respx.post(f"{API}/v1/screenshot").mock(return_value=httpx.Response(502, text="error code: 502"))
+    with pytest.raises(SnapRenderError, match="502 HTTP_502"):
+        SnapRenderToolSpec(api_key="k").take_screenshot(url="https://a.test")
+
+
+@respx.mock
+def test_retries_once_after_rate_limit(monkeypatch):
+    monkeypatch.setattr("time.sleep", lambda s: None)
+    route = respx.post(f"{API}/v1/screenshot").mock(
+        side_effect=[
+            httpx.Response(429, json={"error": {"code": "RATE_LIMITED", "message": "Slow down."}}, headers={"Retry-After": "3"}),
+            httpx.Response(200, content=PNG),
+        ]
+    )
+    blocks = SnapRenderToolSpec(api_key="k").take_screenshot(url="https://a.test")
+    assert route.call_count == 2 and isinstance(blocks[1], ImageBlock)
+
+
+@respx.mock
+def test_never_retries_quota(monkeypatch):
+    monkeypatch.setattr("time.sleep", lambda s: None)
+    route = respx.post(f"{API}/v1/screenshot").mock(
+        return_value=httpx.Response(429, json={"error": {"code": "QUOTA_EXCEEDED", "message": "Monthly limit."}})
+    )
+    with pytest.raises(SnapRenderError, match="QUOTA_EXCEEDED"):
+        SnapRenderToolSpec(api_key="k").take_screenshot(url="https://a.test")
+    assert route.call_count == 1
+
+
+@respx.mock
+def test_tall_image_left_out_with_reason():
+    respx.post(f"{API}/v1/screenshot").mock(return_value=httpx.Response(200, content=png_of_size(2560, 16000)))
+    blocks = SnapRenderToolSpec(api_key="k").take_screenshot(url="https://a.test", full_page=True)
+    assert len(blocks) == 1 and "8000 px limit" in blocks[0].text
+
+
+@respx.mock
+def test_extract_markdown_and_links():
+    route = respx.post(f"{API}/v1/extract").mock(
+        side_effect=[
+            httpx.Response(200, json={"url": "https://a.test", "type": "markdown", "content": "# Hi", "wordCount": 1}),
+            httpx.Response(200, json={"url": "https://a.test", "type": "links", "content": [{"href": "https://b.test", "text": "B"}]}),
+        ]
+    )
+    spec = SnapRenderToolSpec(api_key="k")
+    assert spec.extract_content(url="https://a.test", selector="main") == "# Hi\n\n---\nSource: https://a.test (type markdown, 1 words)"
+    assert json.loads(route.calls[0].request.content) == {"url": "https://a.test", "selector": "main"}
+    assert '"href": "https://b.test"' in spec.extract_content(url="https://a.test", type="links")
+
+
+@respx.mock
+async def test_async_tools():
+    respx.post(f"{API}/v1/screenshot").mock(return_value=httpx.Response(200, content=PNG, headers={"Content-Type": "image/png"}))
+    respx.post(f"{API}/v1/extract").mock(return_value=httpx.Response(200, json={"url": "u", "type": "text", "content": "x"}))
+    spec = SnapRenderToolSpec(api_key="k")
+    blocks = await spec.atake_screenshot(html="<h1>Hi</h1>")
+    assert blocks[0].text.startswith("Screenshot of html") and blocks[1].image_mimetype == "image/png"
+    assert (await spec.aextract_content(url="u")).startswith("x")
+
+
+@respx.mock
+async def test_function_tool_output_carries_image_block():
+    respx.post(f"{API}/v1/screenshot").mock(return_value=httpx.Response(200, content=PNG, headers={"Content-Type": "image/png"}))
+    tool = SnapRenderToolSpec(api_key="k").to_tool_list()[0]
+    output = await tool.acall(url="https://example.com")
+    assert [b.block_type for b in output.blocks] == ["text", "image"]
+
+
+def test_image_size():
+    assert image_size(png_of_size(1280, 800)) == (1280, 800)
+    assert image_size(b"nope") is None