langchain-scrapeunblocker 0.1.0__tar.gz

langchain_scrapeunblocker-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+
+# Publishes on every GitHub Release through PyPI Trusted Publishing (OIDC):
+# no API token anywhere. The trusted publisher points at this repo, this
+# workflow (publish.yml) and the environment "pypi".
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[test]" && pytest
+      - run: pip install build && python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

langchain_scrapeunblocker-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,20 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[test]"
+      - run: pytest -v

langchain_scrapeunblocker-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.venv/

langchain_scrapeunblocker-0.1.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+First release: `ScrapeUnblockerMarkdown`, `ScrapeUnblockerSearchAndRead`, `ScrapeUnblockerGoogleSearch`, `ScrapeUnblockerParsedData`, `ScrapeUnblockerListPlugins`, `ScrapeUnblockerRunPlugin` and `ScrapeUnblockerToolkit`, sync and async, passing LangChain's standard tool tests.

langchain_scrapeunblocker-0.1.0/CLAUDE.md

@@ -0,0 +1,17 @@
+<!-- HQ-SESSION-GUARD v1 (managed from ScrapeUnblocker/headquarters - do not remove) -->
+# HQ SESSION GUARD (Claude - MANDATORY, READ FIRST)
+
+This repo is part of the ScrapeUnblocker ecosystem. All development on it is governed by the central
+`headquarters` repo (`ScrapeUnblocker/headquarters`) - its CLAUDE.md carries the global rules
+(branch/push policy, lint gates, credentials handling, worklog, deploy runbooks).
+
+- **If the headquarters CLAUDE.md IS loaded in your context** (the session was started from the local
+  `headquarters` folder - you can see its "ScrapeUnblocker - Valdymo pultas (Headquarters)" instructions),
+  this guard is satisfied: work normally under those rules.
+- **If it is NOT loaded** (Claude was launched directly in this repo or anywhere else): treat this repo as
+  **READ-ONLY**. Do NOT edit files, do NOT commit, do NOT push, do NOT create branches or tags, and do NOT
+  run deploys from here. Tell the developer: ScrapeUnblocker development sessions must be started from the
+  local `headquarters` folder (clone of `ScrapeUnblocker/headquarters`) so the global rules load - then stop.
+- Reading, searching, running read-only commands and explaining code is always allowed.
+- **Exemption:** sanctioned headless server agents (self-heal / scout / parts-monitor / no-code crawler etc.
+  running on our servers) follow their own playbooks and are NOT bound by this guard.

langchain_scrapeunblocker-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScrapeUnblocker
+
+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.

langchain_scrapeunblocker-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.5
+Name: langchain-scrapeunblocker
+Version: 0.1.0
+Summary: LangChain tools for ScrapeUnblocker: read any web page as Markdown or JSON, search Google, run 100+ site scrapers
+Project-URL: Homepage, https://scrapeunblocker.com?utm_source=pypi&utm_medium=integration&utm_campaign=langchain
+Project-URL: Documentation, https://github.com/ScrapeUnblocker/langchain-scrapeunblocker#readme
+Project-URL: Source, https://github.com/ScrapeUnblocker/langchain-scrapeunblocker
+Project-URL: Issues, https://github.com/ScrapeUnblocker/langchain-scrapeunblocker/issues
+Author-email: ScrapeUnblocker <info@scrapeunblocker.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,langchain,llm,markdown,scraping,serp,tools,web-scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: langchain-core<2.0.0,>=0.3.0
+Requires-Dist: scrapeunblocker>=0.18.6
+Provides-Extra: test
+Requires-Dist: langchain-tests==1.1.9; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# langchain-scrapeunblocker
+
+[![PyPI](https://img.shields.io/pypi/v/langchain-scrapeunblocker)](https://pypi.org/project/langchain-scrapeunblocker/)
+[![Test](https://github.com/ScrapeUnblocker/langchain-scrapeunblocker/actions/workflows/test.yml/badge.svg)](https://github.com/ScrapeUnblocker/langchain-scrapeunblocker/actions/workflows/test.yml)
+
+LangChain tools for [ScrapeUnblocker](https://scrapeunblocker.com?utm_source=github&utm_medium=integration&utm_campaign=langchain): give your agent live web data. Read any public page in a real browser as clean Markdown or structured JSON, search Google, and run 100+ ready-made site scrapers (Amazon, Walmart, eBay, Google Maps, YouTube, Zillow, Indeed and more), including pages behind Cloudflare, DataDome, PerimeterX and Akamai.
+
+## Install
+
+```bash
+pip install -U langchain-scrapeunblocker
+export SCRAPEUNBLOCKER_API_KEY="your-api-key"
+```
+
+Get a key at [app.scrapeunblocker.com](https://app.scrapeunblocker.com?utm_source=github&utm_medium=integration&utm_campaign=langchain) - a free account comes with 500 requests to start.
+
+## Use with an agent
+
+```python
+from langchain.agents import create_agent
+from langchain_scrapeunblocker import ScrapeUnblockerToolkit
+
+agent = create_agent(
+    "anthropic:claude-sonnet-5-5",
+    tools=ScrapeUnblockerToolkit().get_tools(),
+)
+result = agent.invoke(
+    {"messages": [{"role": "user", "content": "What does the Echo Dot cost on amazon.com today?"}]}
+)
+print(result["messages"][-1].content)
+```
+
+## Tools
+
+| Tool | Name the model sees | What it does | Billed |
+|------|---------------------|--------------|--------|
+| `ScrapeUnblockerMarkdown` | `scrapeunblocker_markdown` | A page as clean Markdown (main content, absolute links) | 1 request |
+| `ScrapeUnblockerSearchAndRead` | `scrapeunblocker_search_and_read` | Google search plus the top 1-5 results read as Markdown, in one call | 1 + 1 per page |
+| `ScrapeUnblockerGoogleSearch` | `scrapeunblocker_google_search` | Organic results, AI Overview, People also ask, related searches | 1 per result page |
+| `ScrapeUnblockerParsedData` | `scrapeunblocker_parsed_data` | Structured JSON from a product, article or listing page | 1 request |
+| `ScrapeUnblockerListPlugins` | `scrapeunblocker_list_plugins` | Search the catalog of 100+ site scrapers | free |
+| `ScrapeUnblockerRunPlugin` | `scrapeunblocker_run_plugin` | Run a site scraper and get its JSON | per plugin |
+
+Use them one by one:
+
+```python
+from langchain_scrapeunblocker import ScrapeUnblockerMarkdown, ScrapeUnblockerRunPlugin
+
+ScrapeUnblockerMarkdown().invoke({"url": "https://example.com"})
+
+ScrapeUnblockerRunPlugin().invoke(
+    {"plugin": "youtube_transcript", "params": {"video": "dQw4w9WgXcQ"}}
+)
+```
+
+`ScrapeUnblockerGoogleSearch`, `ScrapeUnblockerParsedData` and `ScrapeUnblockerRunPlugin` return `content_and_artifact`: the model gets a compact text or JSON, and the full API response is on the `ToolMessage`'s `artifact` for your code. Called with a tool call, they return that message:
+
+```python
+from langchain_scrapeunblocker import ScrapeUnblockerGoogleSearch
+
+msg = ScrapeUnblockerGoogleSearch().invoke(
+    {"name": "scrapeunblocker_google_search", "args": {"query": "langchain"}, "id": "1", "type": "tool_call"}
+)
+msg.content    # what the model reads
+msg.artifact   # the whole results page: ads, knowledge panel, local, shopping, videos...
+```
+
+Every tool takes an optional `proxy_country` (ISO code such as `"US"` or `"DE"`) to make the request from that country, and works with `ainvoke` too.
+
+The plugin catalog comes from the installed [`scrapeunblocker`](https://pypi.org/project/scrapeunblocker/) SDK: `pip install -U scrapeunblocker` picks up new plugins without a new release of this package.
+
+## Configuration
+
+| Argument | Default | |
+|----------|---------|---|
+| `api_key` | `SCRAPEUNBLOCKER_API_KEY` (or `SCRAPEUNBLOCKER_KEY`) | Your API key |
+| `timeout` | `180` | Seconds per API call; protected pages can take a while |
+| `max_retries` | `2` | Retries for 429 and 502-504 |
+| `max_chars` | `100000` (Markdown), `60000` (JSON) | Longer results are cut, with a note saying so |
+
+`ScrapeUnblockerToolkit(include_plugins=False)` leaves out the two plugin tools.
+
+Failed calls come back to the model as text it can act on (for example "the page itself answered 404, do not retry"), not as exceptions. Set `handle_tool_error=False` on a tool to raise instead.
+
+## Links
+
+- [ScrapeUnblocker docs](https://docs.scrapeunblocker.com?utm_source=github&utm_medium=integration&utm_campaign=langchain)
+- [Site plugins](https://docs.scrapeunblocker.com/plugins/overview?utm_source=github&utm_medium=integration&utm_campaign=langchain)
+- [Python SDK](https://github.com/ScrapeUnblocker/scrapeunblocker-python)
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest                                 # unit tests, no network
+SCRAPEUNBLOCKER_API_KEY=... pytest tests/integration_tests   # real API calls
+```
+
+## License
+
+MIT

langchain_scrapeunblocker-0.1.0/README.md

@@ -0,0 +1,101 @@
+# langchain-scrapeunblocker
+
+[![PyPI](https://img.shields.io/pypi/v/langchain-scrapeunblocker)](https://pypi.org/project/langchain-scrapeunblocker/)
+[![Test](https://github.com/ScrapeUnblocker/langchain-scrapeunblocker/actions/workflows/test.yml/badge.svg)](https://github.com/ScrapeUnblocker/langchain-scrapeunblocker/actions/workflows/test.yml)
+
+LangChain tools for [ScrapeUnblocker](https://scrapeunblocker.com?utm_source=github&utm_medium=integration&utm_campaign=langchain): give your agent live web data. Read any public page in a real browser as clean Markdown or structured JSON, search Google, and run 100+ ready-made site scrapers (Amazon, Walmart, eBay, Google Maps, YouTube, Zillow, Indeed and more), including pages behind Cloudflare, DataDome, PerimeterX and Akamai.
+
+## Install
+
+```bash
+pip install -U langchain-scrapeunblocker
+export SCRAPEUNBLOCKER_API_KEY="your-api-key"
+```
+
+Get a key at [app.scrapeunblocker.com](https://app.scrapeunblocker.com?utm_source=github&utm_medium=integration&utm_campaign=langchain) - a free account comes with 500 requests to start.
+
+## Use with an agent
+
+```python
+from langchain.agents import create_agent
+from langchain_scrapeunblocker import ScrapeUnblockerToolkit
+
+agent = create_agent(
+    "anthropic:claude-sonnet-5-5",
+    tools=ScrapeUnblockerToolkit().get_tools(),
+)
+result = agent.invoke(
+    {"messages": [{"role": "user", "content": "What does the Echo Dot cost on amazon.com today?"}]}
+)
+print(result["messages"][-1].content)
+```
+
+## Tools
+
+| Tool | Name the model sees | What it does | Billed |
+|------|---------------------|--------------|--------|
+| `ScrapeUnblockerMarkdown` | `scrapeunblocker_markdown` | A page as clean Markdown (main content, absolute links) | 1 request |
+| `ScrapeUnblockerSearchAndRead` | `scrapeunblocker_search_and_read` | Google search plus the top 1-5 results read as Markdown, in one call | 1 + 1 per page |
+| `ScrapeUnblockerGoogleSearch` | `scrapeunblocker_google_search` | Organic results, AI Overview, People also ask, related searches | 1 per result page |
+| `ScrapeUnblockerParsedData` | `scrapeunblocker_parsed_data` | Structured JSON from a product, article or listing page | 1 request |
+| `ScrapeUnblockerListPlugins` | `scrapeunblocker_list_plugins` | Search the catalog of 100+ site scrapers | free |
+| `ScrapeUnblockerRunPlugin` | `scrapeunblocker_run_plugin` | Run a site scraper and get its JSON | per plugin |
+
+Use them one by one:
+
+```python
+from langchain_scrapeunblocker import ScrapeUnblockerMarkdown, ScrapeUnblockerRunPlugin
+
+ScrapeUnblockerMarkdown().invoke({"url": "https://example.com"})
+
+ScrapeUnblockerRunPlugin().invoke(
+    {"plugin": "youtube_transcript", "params": {"video": "dQw4w9WgXcQ"}}
+)
+```
+
+`ScrapeUnblockerGoogleSearch`, `ScrapeUnblockerParsedData` and `ScrapeUnblockerRunPlugin` return `content_and_artifact`: the model gets a compact text or JSON, and the full API response is on the `ToolMessage`'s `artifact` for your code. Called with a tool call, they return that message:
+
+```python
+from langchain_scrapeunblocker import ScrapeUnblockerGoogleSearch
+
+msg = ScrapeUnblockerGoogleSearch().invoke(
+    {"name": "scrapeunblocker_google_search", "args": {"query": "langchain"}, "id": "1", "type": "tool_call"}
+)
+msg.content    # what the model reads
+msg.artifact   # the whole results page: ads, knowledge panel, local, shopping, videos...
+```
+
+Every tool takes an optional `proxy_country` (ISO code such as `"US"` or `"DE"`) to make the request from that country, and works with `ainvoke` too.
+
+The plugin catalog comes from the installed [`scrapeunblocker`](https://pypi.org/project/scrapeunblocker/) SDK: `pip install -U scrapeunblocker` picks up new plugins without a new release of this package.
+
+## Configuration
+
+| Argument | Default | |
+|----------|---------|---|
+| `api_key` | `SCRAPEUNBLOCKER_API_KEY` (or `SCRAPEUNBLOCKER_KEY`) | Your API key |
+| `timeout` | `180` | Seconds per API call; protected pages can take a while |
+| `max_retries` | `2` | Retries for 429 and 502-504 |
+| `max_chars` | `100000` (Markdown), `60000` (JSON) | Longer results are cut, with a note saying so |
+
+`ScrapeUnblockerToolkit(include_plugins=False)` leaves out the two plugin tools.
+
+Failed calls come back to the model as text it can act on (for example "the page itself answered 404, do not retry"), not as exceptions. Set `handle_tool_error=False` on a tool to raise instead.
+
+## Links
+
+- [ScrapeUnblocker docs](https://docs.scrapeunblocker.com?utm_source=github&utm_medium=integration&utm_campaign=langchain)
+- [Site plugins](https://docs.scrapeunblocker.com/plugins/overview?utm_source=github&utm_medium=integration&utm_campaign=langchain)
+- [Python SDK](https://github.com/ScrapeUnblocker/scrapeunblocker-python)
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest                                 # unit tests, no network
+SCRAPEUNBLOCKER_API_KEY=... pytest tests/integration_tests   # real API calls
+```
+
+## License
+
+MIT

langchain_scrapeunblocker-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-scrapeunblocker"
+dynamic = ["version"]
+description = "LangChain tools for ScrapeUnblocker: read any web page as Markdown or JSON, search Google, run 100+ site scrapers"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = ["langchain", "scraping", "web-scraping", "agents", "llm", "serp", "markdown", "tools"]
+authors = [{ name = "ScrapeUnblocker", email = "info@scrapeunblocker.com" }]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = ["langchain-core>=0.3.0,<2.0.0", "scrapeunblocker>=0.18.6"]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-asyncio>=0.23", "langchain-tests==1.1.9"]
+
+[project.urls]
+Homepage = "https://scrapeunblocker.com?utm_source=pypi&utm_medium=integration&utm_campaign=langchain"
+Documentation = "https://github.com/ScrapeUnblocker/langchain-scrapeunblocker#readme"
+Source = "https://github.com/ScrapeUnblocker/langchain-scrapeunblocker"
+Issues = "https://github.com/ScrapeUnblocker/langchain-scrapeunblocker/issues"
+
+[tool.hatch.version]
+path = "src/langchain_scrapeunblocker/version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langchain_scrapeunblocker"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests/unit_tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

langchain_scrapeunblocker-0.1.0/src/langchain_scrapeunblocker/__init__.py

@@ -0,0 +1,27 @@
+"""LangChain integration for ScrapeUnblocker: live web data for agents.
+
+Read any page as Markdown or structured JSON in a real browser, search Google,
+and run 100+ ready-made site scrapers. See https://docs.scrapeunblocker.com
+"""
+
+from langchain_scrapeunblocker.toolkit import ScrapeUnblockerToolkit
+from langchain_scrapeunblocker.tools import (
+    ScrapeUnblockerGoogleSearch,
+    ScrapeUnblockerListPlugins,
+    ScrapeUnblockerMarkdown,
+    ScrapeUnblockerParsedData,
+    ScrapeUnblockerRunPlugin,
+    ScrapeUnblockerSearchAndRead,
+)
+from langchain_scrapeunblocker.version import __version__
+
+__all__ = [
+    "ScrapeUnblockerGoogleSearch",
+    "ScrapeUnblockerListPlugins",
+    "ScrapeUnblockerMarkdown",
+    "ScrapeUnblockerParsedData",
+    "ScrapeUnblockerRunPlugin",
+    "ScrapeUnblockerSearchAndRead",
+    "ScrapeUnblockerToolkit",
+    "__version__",
+]

langchain_scrapeunblocker-0.1.0/src/langchain_scrapeunblocker/_base.py

@@ -0,0 +1,139 @@
+"""Shared plumbing for the ScrapeUnblocker tools: the API key, the SDK clients
+and turning SDK errors into text an agent can act on."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+from langchain_core.tools import BaseTool, ToolException
+from pydantic import Field, PrivateAttr, SecretStr, model_validator
+from scrapeunblocker import AsyncClient, Client
+from scrapeunblocker.exceptions import (
+    AuthenticationError,
+    BlockedError,
+    PaymentRequiredError,
+    RateLimitError,
+    ScrapeTimeoutError,
+    ScrapeUnblockerError,
+    TargetNotFoundError,
+)
+
+from langchain_scrapeunblocker.version import __version__
+
+DEFAULT_BASE_URL = "https://api.scrapeunblocker.com"
+# Checked in this order; the SDK itself reads only the second.
+API_KEY_ENV_VARS = ("SCRAPEUNBLOCKER_API_KEY", "SCRAPEUNBLOCKER_KEY")
+SIGNUP_URL = (
+    "https://app.scrapeunblocker.com"
+    "?utm_source=langchain&utm_medium=integration&utm_campaign=langchain"
+)
+
+
+def _key_from_env() -> Optional[str]:
+    for name in API_KEY_ENV_VARS:
+        value = os.environ.get(name)
+        if value:
+            return value
+    return None
+
+
+def cap_text(text: str, max_chars: int, hint: str) -> str:
+    """Cut `text` to `max_chars`, saying so, so the agent knows it is partial."""
+    if len(text) <= max_chars:
+        return text
+    return f"{text[:max_chars]}\n\n[Cut at {max_chars} of {len(text)} characters. {hint}]"
+
+
+def error_text(err: BaseException) -> str:
+    """What the agent is told when a call fails, with what to do next."""
+    if isinstance(err, TargetNotFoundError):
+        return (
+            f"The page itself answered {err.origin_status} (not found or gone). "
+            "It was billed as one request; do not retry the same URL."
+        )
+    if isinstance(err, AuthenticationError):
+        return (
+            "ScrapeUnblocker rejected the API key, or the account has no active plan. "
+            f"Check the key or pick a plan at {SIGNUP_URL}"
+        )
+    if isinstance(err, PaymentRequiredError):
+        return f"The ScrapeUnblocker account is out of credits or over its limit: {err}"
+    if isinstance(err, BlockedError):
+        return f"The site blocked this request even through ScrapeUnblocker: {err}. Not billed."
+    if isinstance(err, RateLimitError):
+        return "Too many requests at once for this API key. Wait a moment and try again."
+    if isinstance(err, ScrapeTimeoutError):
+        return "The page took too long to load. Try again, or try a simpler URL."
+    return f"ScrapeUnblocker request failed: {err}"
+
+
+class ScrapeUnblockerBaseTool(BaseTool):
+    """Base class: owns the API key and the ScrapeUnblocker SDK clients."""
+
+    api_key: Optional[SecretStr] = Field(default=None)
+    """ScrapeUnblocker API key. Read from ``SCRAPEUNBLOCKER_API_KEY`` (or
+    ``SCRAPEUNBLOCKER_KEY``) when not passed."""
+
+    base_url: str = DEFAULT_BASE_URL
+    """API host. Rarely needed."""
+
+    timeout: float = 180.0
+    """Seconds to wait for one API call. Protected pages can take a while."""
+
+    max_retries: int = 2
+    """Retries for transient failures (429, 502-504, network errors)."""
+
+    handle_tool_error: bool = True
+    """Failed calls come back to the agent as text instead of raising."""
+
+    _client: Optional[Client] = PrivateAttr(default=None)
+    _aclient: Optional[AsyncClient] = PrivateAttr(default=None)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _api_key_from_env(cls, values: Any) -> Any:
+        if isinstance(values, dict) and not values.get("api_key"):
+            key = _key_from_env()
+            if key:
+                values = {**values, "api_key": key}
+        return values
+
+    def _key(self) -> str:
+        if self.api_key is None or not self.api_key.get_secret_value():
+            raise ToolException(
+                "No ScrapeUnblocker API key. Pass api_key=... or set SCRAPEUNBLOCKER_API_KEY. "
+                f"Get a key at {SIGNUP_URL}"
+            )
+        return self.api_key.get_secret_value()
+
+    @staticmethod
+    def _name_this_package(client: Any) -> None:
+        # The API counts calls per client library by User-Agent token.
+        try:
+            headers = client._http.headers
+            headers["User-Agent"] = f"{headers.get('User-Agent', '')} langchain-scrapeunblocker/{__version__}".strip()
+        except AttributeError:
+            pass
+
+    @property
+    def client(self) -> Client:
+        if self._client is None:
+            self._client = Client(
+                self._key(), base_url=self.base_url, timeout=self.timeout, max_retries=self.max_retries
+            )
+            self._name_this_package(self._client)
+        return self._client
+
+    @property
+    def aclient(self) -> AsyncClient:
+        if self._aclient is None:
+            self._aclient = AsyncClient(
+                self._key(), base_url=self.base_url, timeout=self.timeout, max_retries=self.max_retries
+            )
+            self._name_this_package(self._aclient)
+        return self._aclient
+
+    @staticmethod
+    def _fail(err: ScrapeUnblockerError) -> ToolException:
+        return ToolException(error_text(err))

langchain_scrapeunblocker-0.1.0/src/langchain_scrapeunblocker/_catalog.py

@@ -0,0 +1,106 @@
+"""The site plugin catalog, read from the installed ``scrapeunblocker`` SDK.
+
+The SDK has one generated method per public plugin, with its parameters and a
+docstring. Reading them here keeps this package in step with the SDK: a new
+plugin needs an SDK upgrade, not a release of this package.
+"""
+
+from __future__ import annotations
+
+import inspect
+from functools import lru_cache
+from typing import Any, Dict, List, NamedTuple, Optional
+
+from langchain_core.tools import ToolException
+from scrapeunblocker import Client
+
+# Plugins the SDK still has methods for but we do not offer.
+_HIDDEN_PREFIXES = ("temu_",)
+# Client methods that are not plugins.
+_NOT_PLUGINS = frozenset(
+    {
+        "close",
+        "plugin",
+        "get_page_source",
+        "get_markdown",
+        "get_parsed",
+        "get_page_with_cookies",
+        "get_image",
+        "serp",
+    }
+)
+_SUMMARY_MAX = 110
+_LIST_MAX = 40
+
+
+class Plugin(NamedTuple):
+    name: str
+    summary: str
+    doc: str
+    params: List[str]
+    signature: inspect.Signature
+
+
+def _summary(doc: str) -> str:
+    first = " ".join(doc.split("\n\n", 1)[0].split())
+    return first if len(first) <= _SUMMARY_MAX else first[: _SUMMARY_MAX - 3].rstrip() + "..."
+
+
+@lru_cache(maxsize=1)
+def plugins() -> Dict[str, Plugin]:
+    found: Dict[str, Plugin] = {}
+    for name, member in inspect.getmembers(Client, inspect.isfunction):
+        if name.startswith("_") or name in _NOT_PLUGINS or name.startswith(_HIDDEN_PREFIXES):
+            continue
+        sig = inspect.signature(member)
+        params = [p for p in sig.parameters if p != "self" and sig.parameters[p].kind != inspect.Parameter.VAR_KEYWORD]
+        doc = inspect.getdoc(member) or ""
+        found[name] = Plugin(name, _summary(doc), doc, params, sig)
+    return found
+
+
+def _line(p: Plugin) -> str:
+    return f"- {p.name}({', '.join(p.params)}): {p.summary}"
+
+
+def describe(query: Optional[str] = None) -> str:
+    """The catalog text for scrapeunblocker_list_plugins."""
+    catalog = plugins()
+    q = (query or "").strip().lower()
+    if q in catalog:
+        p = catalog[q]
+        return f"{p.name}({', '.join(p.params)})\n\n{p.doc}"
+    if not q:
+        # Names only: with summaries the whole list is too long for one tool result.
+        return (
+            f"{len(catalog)} plugins. Search with a word (e.g. 'amazon', 'reviews', 'jobs') to see what "
+            "they do, or pass an exact name for its parameters.\n\n" + ", ".join(catalog)
+        )
+    words = q.split()
+    matches = [p for p in catalog.values() if all(w in f"{p.name} {p.summary}".lower() for w in words)]
+    if not matches:
+        return f'No plugin matches "{query}". Call scrapeunblocker_list_plugins with no query to see all of them.'
+    shown = matches[:_LIST_MAX]
+    more = f" (showing {_LIST_MAX}; narrow the query)" if len(matches) > _LIST_MAX else ""
+    return f'{len(matches)} plugins match "{query}"{more}:\n\n' + "\n".join(_line(p) for p in shown)
+
+
+def check_call(name: str, params: Dict[str, Any]) -> Dict[str, Any]:
+    """The keyword arguments for plugin `name`, or a ToolException the agent can fix."""
+    p = plugins().get(name)
+    if p is None:
+        raise ToolException(
+            f'There is no plugin "{name}". Find the right name with scrapeunblocker_list_plugins.'
+        )
+    if not isinstance(params, dict):
+        raise ToolException("params must be an object of parameter names to values.")
+    unknown = sorted(set(params) - set(p.params))
+    if unknown:
+        raise ToolException(
+            f"{name} has no parameter {', '.join(unknown)}. Its parameters: {', '.join(p.params) or 'none'}."
+        )
+    try:
+        p.signature.bind(None, **params)
+    except TypeError as err:
+        raise ToolException(f"Wrong parameters for {name}: {err}. Its parameters: {', '.join(p.params)}.") from err
+    return params