langchain-webextract 0.1.0__tar.gz

langchain_webextract-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+dist-local/
+.venv/
+__pycache__/
+*.egg-info/
+.env
+.env.*
+.pytest_cache/

langchain_webextract-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TAINCHENG, L.L.C.
+
+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_webextract-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.5
+Name: langchain-webextract
+Version: 0.1.0
+Summary: LangChain tools for WebExtract: extract_url (Markdown + product/price/tables JSON) and page_markdown. Pay per call with x402, prepaid key, or free tier.
+Project-URL: Homepage, https://webextract.dev
+Project-URL: Documentation, https://webextract.dev/docs
+Project-URL: Source, https://github.com/nyx464664816-stack/webextract
+Project-URL: Issues, https://github.com/nyx464664816-stack/webextract/issues
+Author: TAINCHENG, L.L.C.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: langchain,markdown,tools,web-scraping,webextract,x402
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: langchain-core<2,>=0.3
+Requires-Dist: webextract-sdk<0.2,>=0.1.0
+Description-Content-Type: text/markdown
+
+# langchain-webextract
+
+LangChain tools for [WebExtract](https://webextract.dev). The tool names and outputs match the WebExtract MCP tools:
+
+- `extract_url`: clean Markdown plus fixed-schema JSON (metadata, product and price with `price_detail`, tables). $0.005 or 1 credit.
+- `page_markdown`: clean Markdown only. $0.002 or 0.4 credit.
+
+```bash
+pip install langchain-webextract
+```
+
+This also installs the core client from PyPI `webextract-sdk` (imported as `webextract`). For x402 pay per call add `pip install "webextract-sdk[x402]"`.
+
+```python
+from langchain_webextract import WebExtractExtractUrl, WebExtractPageMarkdown, get_webextract_tools
+from webextract import WebExtract
+
+tools = get_webextract_tools()                                    # free tier, or WEBEXTRACT_API_KEY if set
+tools = get_webextract_tools(api_key="lx_...")                     # prepaid credits (SecretStr field)
+tools = get_webextract_tools(client=WebExtract(api_key="lx_..."))  # prepaid credits
+print(WebExtractPageMarkdown().invoke({"url": "https://example.com"}))
+```
+
+**x402 pay per call (async).** Build the paying client with the official x402 SDK, then hand it over. This package never sees the private key.
+
+```python
+from webextract import AsyncWebExtract
+tool = WebExtractExtractUrl(async_client=AsyncWebExtract(payment_client=x402_httpx_client))
+await tool.ainvoke({"url": "https://web-scraping.dev/product/1"})
+```
+
+The tools return a JSON string. By default, API errors come back to the model as `{"ok": false, "error": {"error", "status", "message", "charged", "reason", "hint", ...}}`, so an agent can react to `free_limit_reached`, `robots_disallowed` and so on. Set `on_error="raise"` to raise `webextract.WebExtractError` subclasses instead.
+
+## Tests
+
+```bash
+pytest --disable-socket --allow-unix-socket tests/unit_tests                  # mocks + langchain-tests ToolsUnitTests
+pytest --disable-socket --allow-unix-socket tests/integration_tests           # ToolsIntegrationTests, offline (mocked API)
+WEBEXTRACT_SANDBOX_TESTS=1 X402_TESTNET_ENV_FILE=/path/to/testnet.env \
+  pytest tests/integration_tests/test_standard_sandbox.py                     # live sandbox, Base Sepolia TEST USDC only
+```
+
+License: MIT © TAINCHENG, L.L.C.

langchain_webextract-0.1.0/README.md

@@ -0,0 +1,43 @@
+# langchain-webextract
+
+LangChain tools for [WebExtract](https://webextract.dev). The tool names and outputs match the WebExtract MCP tools:
+
+- `extract_url`: clean Markdown plus fixed-schema JSON (metadata, product and price with `price_detail`, tables). $0.005 or 1 credit.
+- `page_markdown`: clean Markdown only. $0.002 or 0.4 credit.
+
+```bash
+pip install langchain-webextract
+```
+
+This also installs the core client from PyPI `webextract-sdk` (imported as `webextract`). For x402 pay per call add `pip install "webextract-sdk[x402]"`.
+
+```python
+from langchain_webextract import WebExtractExtractUrl, WebExtractPageMarkdown, get_webextract_tools
+from webextract import WebExtract
+
+tools = get_webextract_tools()                                    # free tier, or WEBEXTRACT_API_KEY if set
+tools = get_webextract_tools(api_key="lx_...")                     # prepaid credits (SecretStr field)
+tools = get_webextract_tools(client=WebExtract(api_key="lx_..."))  # prepaid credits
+print(WebExtractPageMarkdown().invoke({"url": "https://example.com"}))
+```
+
+**x402 pay per call (async).** Build the paying client with the official x402 SDK, then hand it over. This package never sees the private key.
+
+```python
+from webextract import AsyncWebExtract
+tool = WebExtractExtractUrl(async_client=AsyncWebExtract(payment_client=x402_httpx_client))
+await tool.ainvoke({"url": "https://web-scraping.dev/product/1"})
+```
+
+The tools return a JSON string. By default, API errors come back to the model as `{"ok": false, "error": {"error", "status", "message", "charged", "reason", "hint", ...}}`, so an agent can react to `free_limit_reached`, `robots_disallowed` and so on. Set `on_error="raise"` to raise `webextract.WebExtractError` subclasses instead.
+
+## Tests
+
+```bash
+pytest --disable-socket --allow-unix-socket tests/unit_tests                  # mocks + langchain-tests ToolsUnitTests
+pytest --disable-socket --allow-unix-socket tests/integration_tests           # ToolsIntegrationTests, offline (mocked API)
+WEBEXTRACT_SANDBOX_TESTS=1 X402_TESTNET_ENV_FILE=/path/to/testnet.env \
+  pytest tests/integration_tests/test_standard_sandbox.py                     # live sandbox, Base Sepolia TEST USDC only
+```
+
+License: MIT © TAINCHENG, L.L.C.

langchain_webextract-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-webextract"
+version = "0.1.0"
+description = "LangChain tools for WebExtract: extract_url (Markdown + product/price/tables JSON) and page_markdown. Pay per call with x402, prepaid key, or free tier."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "TAINCHENG, L.L.C." }]
+keywords = ["langchain", "tools", "webextract", "web-scraping", "markdown", "x402"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Topic :: Internet :: WWW/HTTP",
+  "Typing :: Typed",
+]
+dependencies = ["webextract-sdk>=0.1.0,<0.2", "langchain-core>=0.3,<2"]
+
+
+[project.urls]
+Homepage = "https://webextract.dev"
+Documentation = "https://webextract.dev/docs"
+Source = "https://github.com/nyx464664816-stack/webextract"
+Issues = "https://github.com/nyx464664816-stack/webextract/issues"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/langchain_webextract", "tests/**/*.py", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langchain_webextract"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[dependency-groups]
+test = ["pytest>=8", "pytest-asyncio>=0.23", "pytest-socket>=0.7", "langchain-tests>=1.1,<2"]
+test_integration = ["x402[evm,httpx,requests]>=2.25,<3"]

langchain_webextract-0.1.0/src/langchain_webextract/__init__.py

@@ -0,0 +1,8 @@
+"""LangChain tools for WebExtract (https://webextract.dev)."""
+from webextract import AsyncWebExtract, WebExtract, WebExtractError
+
+from .tools import WebExtractExtractUrl, WebExtractInput, WebExtractPageMarkdown, get_webextract_tools
+
+__version__ = "0.1.0"
+__all__ = ["WebExtractExtractUrl", "WebExtractPageMarkdown", "WebExtractInput", "get_webextract_tools",
+           "WebExtract", "AsyncWebExtract", "WebExtractError", "__version__"]

langchain_webextract-0.1.0/src/langchain_webextract/tools.py

@@ -0,0 +1,97 @@
+"""LangChain tools for WebExtract. Tool names and outputs match the MCP tools (extract_url, page_markdown)."""
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Literal, Optional, Type
+
+from langchain_core.callbacks import AsyncCallbackManagerForToolRun, CallbackManagerForToolRun
+from langchain_core.tools import BaseTool
+from langchain_core.utils import secret_from_env
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, SecretStr, field_validator
+
+from webextract import TOOL_DESCRIPTIONS, AsyncWebExtract, WebExtract, WebExtractError
+
+
+class WebExtractInput(BaseModel):
+    """Input for the WebExtract tools."""
+
+    url: str = Field(description=TOOL_DESCRIPTIONS["url"])
+
+    @field_validator("url")
+    @classmethod
+    def _http_url(cls, v: str) -> str:
+        v = v.strip()
+        if not (v.startswith("http://") or v.startswith("https://")):
+            raise ValueError("url must be an absolute http(s) URL")
+        return v
+
+
+class _WebExtractBaseTool(BaseTool):
+    """Shared plumbing. Pass ``client`` (sync) and/or ``async_client``; with neither, a free-tier sync client
+    is created (X-Billing: free, 50 calls/day per IP). For x402 pay-per-call pass
+    ``async_client=AsyncWebExtract(payment_client=x402HttpxClient(...))``."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    args_schema: Type[BaseModel] = WebExtractInput
+    client: Optional[WebExtract] = None
+    async_client: Optional[AsyncWebExtract] = None
+    api_key: Optional[SecretStr] = Field(default_factory=secret_from_env("WEBEXTRACT_API_KEY", default=None))
+    """Prepaid key (Stripe credits). Defaults to the WEBEXTRACT_API_KEY env var. Only used when no client is given."""
+    billing: Optional[Literal["key", "free", "x402", "x402-testnet"]] = None
+    """Billing for the built-in client (default: key if api_key is set, else free). x402 needs a client with payment_client."""
+    base_url: Optional[str] = None
+    on_error: Literal["return", "raise"] = "return"
+    """"return": API errors (402 reason, failed fetch, bad url) come back to the model as a JSON string
+    {"ok": false, "error": {...}}. "raise": re-raise the WebExtractError."""
+    _endpoint: str = PrivateAttr(default="")
+
+    def _sync(self) -> WebExtract:
+        if self.client is None:
+            if self.async_client is not None:
+                raise RuntimeError("only async_client is configured; call the tool with ainvoke()")
+            use_key = self.api_key is not None and self.billing in (None, "key")
+            self.client = WebExtract(api_key=self.api_key.get_secret_value() if use_key else None,
+                                     billing=self.billing or ("key" if use_key else "free"), base_url=self.base_url)
+        return self.client
+
+    def _fail(self, e: WebExtractError) -> str:
+        if self.on_error == "raise":
+            raise e
+        return json.dumps({"ok": False, "error": e.to_dict()})
+
+    def _run(self, url: str, run_manager: Optional[CallbackManagerForToolRun] = None) -> str:
+        try:
+            r = getattr(self._sync(), self._endpoint)(url)
+        except WebExtractError as e:
+            return self._fail(e)
+        return json.dumps(r.data, ensure_ascii=False)
+
+    async def _arun(self, url: str, run_manager: Optional[AsyncCallbackManagerForToolRun] = None) -> str:
+        if self.async_client is None:
+            return await super()._arun(url, run_manager=run_manager)  # runs _run in a thread
+        try:
+            r = await getattr(self.async_client, self._endpoint)(url)
+        except WebExtractError as e:
+            return self._fail(e)
+        return json.dumps(r.data, ensure_ascii=False)
+
+
+class WebExtractExtractUrl(_WebExtractBaseTool):
+    """Markdown + fixed-schema JSON (metadata, product/price incl. price_detail, tables) for a URL. $0.005 or 1 credit."""
+
+    name: str = "extract_url"
+    description: str = TOOL_DESCRIPTIONS["extract_url"]
+    _endpoint: str = PrivateAttr(default="extract")
+
+
+class WebExtractPageMarkdown(_WebExtractBaseTool):
+    """Clean Markdown for a URL. $0.002 or 0.4 credit."""
+
+    name: str = "page_markdown"
+    description: str = TOOL_DESCRIPTIONS["page_markdown"]
+    _endpoint: str = PrivateAttr(default="markdown")
+
+
+def get_webextract_tools(**kwargs: Any) -> List[BaseTool]:
+    """Both tools sharing the same clients/options, e.g. ``get_webextract_tools(client=WebExtract(api_key=...))``."""
+    return [WebExtractExtractUrl(**kwargs), WebExtractPageMarkdown(**kwargs)]

langchain_webextract-0.1.0/tests/_fixtures.py

@@ -0,0 +1,39 @@
+"""Canned API responses (shapes copied from the live API, schema_version 1.0 + 2026-10-21 additive fields)."""
+import json
+
+import httpx
+
+from webextract import AsyncWebExtract, WebExtract
+
+EXTRACT = {
+    "url": "https://web-scraping.dev/product/1", "final_url": "https://web-scraping.dev/product/1",
+    "fetched_at": "2026-10-21T11:00:00.000Z", "schema_version": "1.0", "content_source": "raw_html",
+    "markdown": "# Box of Chocolate Candy\n\n...", "markdown_truncated": False, "word_count": 120,
+    "metadata": {"title": "Box of Chocolate Candy", "description": None, "authors": [], "published_at": None, "modified_at": None,
+                 "site_name": None, "language": "en", "canonical_url": None, "image": None, "type": "product"},
+    "product": {"name": "Box of Chocolate Candy", "brand": None, "sku": None, "gtin": None, "description": None, "image": None,
+                "price": 9.99, "price_high": None, "currency": "USD", "availability": "InStock", "rating": None, "source": "json-ld",
+                "price_detail": {"status": "resolved", "currency": "USD", "currency_basis": "declared",
+                                 "prices": [{"type": "sale", "amount": 9.99, "currency": "USD", "method": "dom"},
+                                            {"type": "list", "amount": 12.99, "currency": "USD", "method": "dom"}],
+                                 "unresolved": None, "warnings": []}},
+    "tables": [],
+}
+MARKDOWN = {"url": "https://example.com", "final_url": "https://example.com/", "fetched_at": "2026-10-21T11:00:00.000Z",
+            "content_source": "raw_html", "title": "Example Domain", "markdown": "# Example Domain\n\n...", "markdown_truncated": False,
+            "word_count": 25}
+FREE_LIMIT = {"error": "payment_required", "reason": "free_limit_reached", "message": "Free daily limit reached"}
+
+
+def _handler(status=200, body=None):
+    def h(req: httpx.Request) -> httpx.Response:
+        payload = body if body is not None else (MARKDOWN if req.url.path.endswith("/markdown") else EXTRACT)
+        headers = {"x-payment-reason": payload["reason"]} if status == 402 else {}
+        return httpx.Response(status, content=json.dumps(payload), headers={"content-type": "application/json", **headers})
+    return h
+
+
+def mock_clients(status=200, body=None):
+    t = _handler(status, body)
+    return {"client": WebExtract(http_client=httpx.Client(transport=httpx.MockTransport(t))),
+            "async_client": AsyncWebExtract(http_client=httpx.AsyncClient(transport=httpx.MockTransport(t)))}

langchain_webextract-0.1.0/tests/integration_tests/test_standard_offline.py

@@ -0,0 +1,51 @@
+"""LangChain standard integration tests (ToolsIntegrationTests) run OFFLINE: the WebExtract HTTP API is
+replaced by httpx.MockTransport with real response shapes. Includes an error variant (402 free_limit_reached)
+to prove the tool never raises on API errors by default."""
+from typing import Any, Dict, Type
+
+from langchain_tests.integration_tests import ToolsIntegrationTests
+
+from langchain_webextract import WebExtractExtractUrl, WebExtractPageMarkdown
+from tests._fixtures import FREE_LIMIT, mock_clients
+
+
+class TestExtractUrlOffline(ToolsIntegrationTests):
+    @property
+    def tool_constructor(self) -> Type[WebExtractExtractUrl]:
+        return WebExtractExtractUrl
+
+    @property
+    def tool_constructor_params(self) -> Dict[str, Any]:
+        return mock_clients()
+
+    @property
+    def tool_invoke_params_example(self) -> Dict[str, Any]:
+        return {"url": "https://web-scraping.dev/product/1"}
+
+
+class TestPageMarkdownOffline(ToolsIntegrationTests):
+    @property
+    def tool_constructor(self) -> Type[WebExtractPageMarkdown]:
+        return WebExtractPageMarkdown
+
+    @property
+    def tool_constructor_params(self) -> Dict[str, Any]:
+        return mock_clients()
+
+    @property
+    def tool_invoke_params_example(self) -> Dict[str, Any]:
+        return {"url": "https://example.com"}
+
+
+class TestExtractUrlOffline402(ToolsIntegrationTests):
+    @property
+    def tool_constructor(self) -> Type[WebExtractExtractUrl]:
+        return WebExtractExtractUrl
+
+    @property
+    def tool_constructor_params(self) -> Dict[str, Any]:
+        return mock_clients(402, FREE_LIMIT)
+
+    @property
+    def tool_invoke_params_example(self) -> Dict[str, Any]:
+        return {"url": "https://web-scraping.dev/product/1"}

langchain_webextract-0.1.0/tests/integration_tests/test_standard_sandbox.py

@@ -0,0 +1,87 @@
+"""LangChain standard integration tests against the LIVE WebExtract SANDBOX (Base Sepolia test USDC only).
+
+Opt-in: set WEBEXTRACT_SANDBOX_TESTS=1 and X402_TESTNET_ENV_FILE=<path to a mode-600 .env with
+X402_TESTNET_PRIVATE_KEY>. Only eip155:84532 is registered with the x402 SDK and billing is x402-testnet,
+so nothing can be signed for a mainnet requirement. The key is never printed. Each run makes 4 test payments
+per tool (sync + async, with and without ToolCall)."""
+import json
+import os
+import stat
+import time
+from typing import Any, Dict, Type
+
+import pytest
+from langchain_core.messages import ToolCall
+from langchain_core.tools import BaseTool
+from langchain_tests.integration_tests import ToolsIntegrationTests
+
+from langchain_webextract import WebExtractExtractUrl, WebExtractPageMarkdown
+from webextract import AsyncWebExtract, WebExtract
+
+NET = "eip155:84532"
+pytestmark = pytest.mark.skipif(os.environ.get("WEBEXTRACT_SANDBOX_TESTS") != "1", reason="set WEBEXTRACT_SANDBOX_TESTS=1 to run live sandbox tests")
+
+
+def _key() -> str:
+    path = os.environ["X402_TESTNET_ENV_FILE"]
+    if os.stat(path).st_mode & (stat.S_IRWXG | stat.S_IRWXO):
+        raise RuntimeError("testnet .env must be mode 600")
+    with open(path) as f:
+        return next(l.split("=", 1)[1].strip() for l in f if l.startswith("X402_TESTNET_PRIVATE_KEY="))
+
+
+def sandbox_clients() -> Dict[str, Any]:
+    from eth_account import Account
+    from x402 import x402Client, x402ClientSync
+    from x402.http.clients import x402_requests, x402HttpxClient
+    from x402.mechanisms.evm.exact import ExactEvmScheme
+
+    acct = Account.from_key(_key())
+    sync_x, async_x = x402ClientSync(), x402Client()
+    sync_x.register(NET, ExactEvmScheme(signer=acct))
+    async_x.register(NET, ExactEvmScheme(signer=acct))
+    return {"client": WebExtract(payment_client=x402_requests(sync_x), billing="x402-testnet", timeout=60),
+            "async_client": AsyncWebExtract(payment_client=x402HttpxClient(async_x, timeout=60), billing="x402-testnet", timeout=60)}
+
+
+@pytest.fixture(autouse=True)
+def _pace():
+    """The sandbox allows 20 requests/minute per IP and every x402 call is 2 HTTP requests
+    (unpaid 402, then the signed retry), so stay at <= ~9 paid calls per minute."""
+    yield
+    time.sleep(float(os.environ.get("WEBEXTRACT_SANDBOX_PACE_S", "7")))
+
+
+class _Live(ToolsIntegrationTests):
+    @property
+    def tool_constructor_params(self) -> Dict[str, Any]:
+        # on_error="raise": any 402/422/429 from the sandbox fails the standard tests instead of being
+        # returned to the "model" as an error object, so a green run means every call was paid and served.
+        return {**sandbox_clients(), "on_error": "raise"}
+
+    def test_live_result_is_success(self, tool: BaseTool) -> None:
+        """Extra (not in the standard suite): the live sandbox call must succeed, not come back as an error object."""
+        msg = tool.invoke(ToolCall(name=tool.name, args=self.tool_invoke_params_example, id="1", type="tool_call"))
+        out = json.loads(msg.content)
+        assert out.get("ok") is not False, out
+        assert out["markdown"] and out.get("content_source") in (None, "raw_html")
+
+
+class TestPageMarkdownSandbox(_Live):
+    @property
+    def tool_constructor(self) -> Type[WebExtractPageMarkdown]:
+        return WebExtractPageMarkdown
+
+    @property
+    def tool_invoke_params_example(self) -> Dict[str, Any]:
+        return {"url": "https://example.com"}
+
+
+class TestExtractUrlSandbox(_Live):
+    @property
+    def tool_constructor(self) -> Type[WebExtractExtractUrl]:
+        return WebExtractExtractUrl
+
+    @property
+    def tool_invoke_params_example(self) -> Dict[str, Any]:
+        return {"url": "https://web-scraping.dev/product/1"}

langchain_webextract-0.1.0/tests/unit_tests/test_standard.py

@@ -0,0 +1,41 @@
+"""LangChain standard unit tests (langchain-tests ToolsUnitTests). No network."""
+from typing import Any, Dict, Tuple, Type
+
+from langchain_tests.unit_tests import ToolsUnitTests
+
+from langchain_webextract import WebExtractExtractUrl, WebExtractPageMarkdown
+
+EXAMPLE = {"url": "https://web-scraping.dev/product/1"}
+ENV = ({"WEBEXTRACT_API_KEY": "lx_test_env_key"}, {}, {"api_key": "lx_test_env_key"})
+
+
+class TestExtractUrlStandard(ToolsUnitTests):
+    @property
+    def tool_constructor(self) -> Type[WebExtractExtractUrl]:
+        return WebExtractExtractUrl
+
+    @property
+    def tool_constructor_params(self) -> Dict[str, Any]:
+        return {}
+
+    @property
+    def tool_invoke_params_example(self) -> Dict[str, Any]:
+        return EXAMPLE
+
+    @property
+    def init_from_env_params(self) -> Tuple[Dict[str, str], Dict[str, Any], Dict[str, Any]]:
+        return ENV
+
+
+class TestPageMarkdownStandard(ToolsUnitTests):
+    @property
+    def tool_constructor(self) -> Type[WebExtractPageMarkdown]:
+        return WebExtractPageMarkdown
+
+    @property
+    def tool_invoke_params_example(self) -> Dict[str, Any]:
+        return {"url": "https://example.com"}
+
+    @property
+    def init_from_env_params(self) -> Tuple[Dict[str, str], Dict[str, Any], Dict[str, Any]]:
+        return ENV

langchain_webextract-0.1.0/tests/unit_tests/test_tools.py

@@ -0,0 +1,82 @@
+"""Unit tests with mocked HTTP. No network, no money."""
+import asyncio
+import json
+
+import httpx
+import pytest
+from pydantic import ValidationError
+
+from langchain_webextract import WebExtractExtractUrl, WebExtractPageMarkdown, get_webextract_tools
+from webextract import AsyncWebExtract, TargetFetchError, WebExtract
+
+MD = {"url": "https://a.test/", "final_url": "https://a.test/", "title": "A", "markdown": "# A"}
+EX = {"url": "u", "final_url": "u", "markdown": "# A", "metadata": {}, "tables": [], "product": None, "product_unresolved": {"reason": "listing_page"}}
+
+
+def transport(status, body, headers=None, calls=None):
+    def h(req):
+        if calls is not None:
+            calls.append(req)
+        return httpx.Response(status, json=body, headers=headers or {})
+    return httpx.MockTransport(h)
+
+
+def sync(status, body, headers=None, calls=None, **kw):
+    return WebExtract(http_client=httpx.Client(transport=transport(status, body, headers, calls)), **kw)
+
+
+def test_names_and_schema():
+    a, b = get_webextract_tools(client=sync(200, MD))
+    assert (a.name, b.name) == ("extract_url", "page_markdown")
+    assert "url" in a.args and "Markdown" in a.description
+    assert a.tool_call_schema.model_json_schema()["required"] == ["url"]
+
+
+def test_extract_invoke_returns_json_string():
+    calls = []
+    out = json.loads(WebExtractExtractUrl(client=sync(200, EX, None, calls)).invoke({"url": "https://a.test/"}))
+    assert out["product_unresolved"]["reason"] == "listing_page" and calls[0].url.path == "/v1/extract"
+
+
+def test_markdown_invoke_with_key():
+    calls = []
+    out = json.loads(WebExtractPageMarkdown(client=sync(200, MD, None, calls, api_key="lx_k")).invoke({"url": "https://a.test/"}))
+    assert out["markdown"] == "# A" and calls[0].headers["authorization"] == "Bearer lx_k"
+
+
+def test_invalid_url_rejected_before_http():
+    calls = []
+    with pytest.raises(ValidationError):
+        WebExtractPageMarkdown(client=sync(200, MD, None, calls)).invoke({"url": "nope"})
+    assert calls == []
+
+
+def test_402_returned_as_error_json():
+    t = WebExtractExtractUrl(client=sync(402, {"error": "payment_required", "reason": "free_limit_reached", "message": "limit"}, {"x-payment-reason": "free_limit_reached"}))
+    out = json.loads(t.invoke({"url": "https://a.test/"}))
+    assert out["ok"] is False and out["error"]["reason"] == "free_limit_reached" and out["error"]["charged"] is False
+
+
+def test_on_error_raise():
+    t = WebExtractExtractUrl(client=sync(451, {"error": "robots_disallowed", "message": "robots", "charged": False}), on_error="raise")
+    with pytest.raises(TargetFetchError):
+        t.invoke({"url": "https://a.test/"})
+
+
+def test_async_client_used_by_ainvoke():
+    calls = []
+    ac = AsyncWebExtract(http_client=httpx.AsyncClient(transport=transport(200, MD, None, calls)))
+    out = json.loads(asyncio.run(WebExtractPageMarkdown(async_client=ac).ainvoke({"url": "https://a.test/"})))
+    assert out["markdown"] == "# A" and calls[0].url.path == "/v1/markdown"
+
+
+def test_sync_invoke_with_only_async_client_is_clear_error():
+    ac = AsyncWebExtract(http_client=httpx.AsyncClient(transport=transport(200, MD)))
+    with pytest.raises(RuntimeError, match="ainvoke"):
+        WebExtractPageMarkdown(async_client=ac).invoke({"url": "https://a.test/"})
+
+
+def test_ainvoke_falls_back_to_sync_client():
+    calls = []
+    out = json.loads(asyncio.run(WebExtractPageMarkdown(client=sync(200, MD, None, calls)).ainvoke({"url": "https://a.test/"})))
+    assert out["markdown"] == "# A" and len(calls) == 1