crawlerkit-core 0.1.0__tar.gz

crawlerkit_core-0.1.0/LICENSE

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

crawlerkit_core-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: crawlerkit-core
+Version: 0.1.0
+Summary: Browserless crawler base: curl_cffi transport, TLS/AIA, identity, proxy, captcha, BaseCrawler/BaseParser.
+Author-email: Lucas Caovilla <lucasgrisac@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/lucascaovilla/crawlerkit
+Project-URL: Repository, https://github.com/lucascaovilla/crawlerkit
+Project-URL: Documentation, https://github.com/lucascaovilla/crawlerkit#readme
+Project-URL: Issues, https://github.com/lucascaovilla/crawlerkit/issues
+Keywords: crawler,scraping,curl_cffi,tls,fingerprint,captcha,browserless
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: curl_cffi>=0.7
+Requires-Dist: browserforge>=1.2
+Requires-Dist: cryptography>=42
+Requires-Dist: certifi>=2024.0
+Requires-Dist: selectolax>=0.3
+Requires-Dist: lxml>=5.0
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: structlog>=24.1
+Requires-Dist: tenacity>=8.2
+Requires-Dist: weasyprint>=60
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Requires-Dist: commitizen>=3.27; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
+Dynamic: license-file
+
+# crawlerkit-core
+
+[![PyPI version](https://img.shields.io/pypi/v/crawlerkit-core.svg)](https://pypi.org/project/crawlerkit-core/)
+[![Python versions](https://img.shields.io/pypi/pyversions/crawlerkit-core.svg)](https://pypi.org/project/crawlerkit-core/)
+[![CI](https://github.com/lucascaovilla/crawlerkit/actions/workflows/ci.yml/badge.svg)](https://github.com/lucascaovilla/crawlerkit/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+A **standalone, browserless** crawler base (`crawlerkit.core`): fingerprinted **curl_cffi** transport,
+per-host TLS with **AIA repair** + `.pfx` client certs, **browserforge** identity (UA snapped to the
+impersonate target), proxy providers, a pluggable **captcha** registry, an error taxonomy with
+retry+rotation, and the `BaseCrawler.flow()` / `BaseParser.parse()` hooks. Zero non-PyPI dependencies —
+`parse()` returns **your own type**, not one the library dictates.
+
+## Install
+
+```bash
+pip install crawlerkit-core
+```
+
+## Use
+
+```python
+from crawlerkit.core import BaseCrawler, BaseParser, RawResponse, Transport, Profile
+from crawlerkit.core.captcha import default_registry, McaptchaPowSolver, mcaptcha_hint
+from crawlerkit.core.proxy import StaticProxyProvider, BrightDataProxyProvider
+from crawlerkit.core.errors import BlockedError, TransientError, raise_for_block
+```
+
+**HTTP is curl_cffi only — `requests` is never used.** Deps: curl_cffi, browserforge, cryptography,
+certifi, selectolax, lxml, beautifulsoup4, weasyprint, structlog, tenacity.
+
+**Build a crawler:** [GETTING_STARTED.md](GETTING_STARTED.md). **Run the demos:**
+[`examples/`](examples/) (`quotes.py` — a full crawl+parse; `fingerprint_demo.py` — identity proof).
+Reference: [`docs/`](docs/) (identity, transport-tls, proxy, captcha, cracking-govbr-turnstile, errors,
+api). License: MIT.

crawlerkit_core-0.1.0/README.md

@@ -0,0 +1,35 @@
+# crawlerkit-core
+
+[![PyPI version](https://img.shields.io/pypi/v/crawlerkit-core.svg)](https://pypi.org/project/crawlerkit-core/)
+[![Python versions](https://img.shields.io/pypi/pyversions/crawlerkit-core.svg)](https://pypi.org/project/crawlerkit-core/)
+[![CI](https://github.com/lucascaovilla/crawlerkit/actions/workflows/ci.yml/badge.svg)](https://github.com/lucascaovilla/crawlerkit/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+A **standalone, browserless** crawler base (`crawlerkit.core`): fingerprinted **curl_cffi** transport,
+per-host TLS with **AIA repair** + `.pfx` client certs, **browserforge** identity (UA snapped to the
+impersonate target), proxy providers, a pluggable **captcha** registry, an error taxonomy with
+retry+rotation, and the `BaseCrawler.flow()` / `BaseParser.parse()` hooks. Zero non-PyPI dependencies —
+`parse()` returns **your own type**, not one the library dictates.
+
+## Install
+
+```bash
+pip install crawlerkit-core
+```
+
+## Use
+
+```python
+from crawlerkit.core import BaseCrawler, BaseParser, RawResponse, Transport, Profile
+from crawlerkit.core.captcha import default_registry, McaptchaPowSolver, mcaptcha_hint
+from crawlerkit.core.proxy import StaticProxyProvider, BrightDataProxyProvider
+from crawlerkit.core.errors import BlockedError, TransientError, raise_for_block
+```
+
+**HTTP is curl_cffi only — `requests` is never used.** Deps: curl_cffi, browserforge, cryptography,
+certifi, selectolax, lxml, beautifulsoup4, weasyprint, structlog, tenacity.
+
+**Build a crawler:** [GETTING_STARTED.md](GETTING_STARTED.md). **Run the demos:**
+[`examples/`](examples/) (`quotes.py` — a full crawl+parse; `fingerprint_demo.py` — identity proof).
+Reference: [`docs/`](docs/) (identity, transport-tls, proxy, captcha, cracking-govbr-turnstile, errors,
+api). License: MIT.

crawlerkit_core-0.1.0/crawlerkit/core/__init__.py

@@ -0,0 +1,6 @@
+from .base_crawler import BaseCrawler, RawResponse
+from .base_parser import BaseParser
+from .identity import Profile
+from .transport import Transport
+
+__all__ = ["BaseCrawler", "BaseParser", "RawResponse", "Transport", "Profile"]

crawlerkit_core-0.1.0/crawlerkit/core/base_crawler.py

@@ -0,0 +1,126 @@
+"""BaseCrawler — the crawl stage. A new target fills one hook: flow()."""
+
+import random
+import time
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+import structlog
+from bs4 import BeautifulSoup
+
+from .captcha.base import CaptchaRegistry, Challenge, default_registry
+from .errors import BlockedError, PermanentError, TransientError
+from .identity import Profile, pick
+from .proxy import NullProxyProvider, ProxyProvider
+from .transport import Transport
+
+log = structlog.get_logger(__name__)
+
+
+@dataclass
+class RawResponse:
+    url: str
+    status: int
+    text: str
+    headers: dict = field(default_factory=dict)
+
+
+class BaseCrawler(ABC):
+    """Owns transport+identity+proxy+captcha; subclass implements only flow().
+
+    No business logic, no parsing here — crawl and return the raw response.
+    """
+
+    captcha_hint: Challenge | None = None  # known sitekey when the widget isn't inline
+
+    def __init__(
+        self,
+        *,
+        proxy_provider: ProxyProvider | None = None,
+        registry: CaptchaRegistry | None = None,
+        verify: bool = True,
+        profile: Profile | None = None,
+        client_cert: str | None = None,
+        max_attempts: int = 3,
+    ):
+        self._proxy_provider = proxy_provider or NullProxyProvider()
+        self._verify = verify
+        self._client_cert = client_cert
+        self._fixed_profile = profile
+        self.max_attempts = max_attempts
+        self.registry = registry or default_registry()
+        self._build_transport()
+
+    def _build_transport(self) -> None:
+        """(Re)create identity + proxy lease + transport — on init and on each rotation."""
+        self.profile = self._fixed_profile or pick()
+        self.proxy = self._proxy_provider.lease()
+        self.transport = Transport(
+            self.profile, self.proxy, verify=self._verify, client_cert=self._client_cert
+        )
+
+    def _rotate(self) -> None:
+        log.info("rotate_identity_proxy")
+        self._build_transport()
+
+    # --- helpers exposed to flow() ---
+    def get(self, url: str, **kw):
+        return self.transport.get(url, **kw)
+
+    def post(self, url: str, **kw):
+        return self.transport.post(url, **kw)
+
+    def solve_captcha(self, source) -> str | None:
+        """detect+solve; returns a token, None (no challenge), or raises UnsupportedCaptcha."""
+        solved = self.registry.solve(source, self.transport, hint=self.captcha_hint)
+        return solved.token if solved else None
+
+    def hidden_fields(self, html: str) -> dict:
+        """All hidden inputs of the form (JSF ViewState / WebForms __VIEWSTATE postback state)."""
+        try:
+            soup = BeautifulSoup(html, "lxml")
+        except Exception:  # noqa: BLE001
+            soup = BeautifulSoup(html, "html.parser")
+        form = soup.find("form") if soup else None
+        scope = form or soup
+        hidden: dict[str, str] = {}
+        if scope:
+            for inp in scope.find_all("input"):
+                name = inp.get("name")
+                if name and (inp.get("type") == "hidden" or "ViewState" in name or "VIEWSTATE" in name.upper()):
+                    hidden[name] = inp.get("value", "")
+        return hidden
+
+    # --- the only required hook ---
+    @abstractmethod
+    def flow(self, params: dict) -> RawResponse:
+        ...
+
+    def run(self, params: dict) -> RawResponse:
+        """Run flow() with retry + rotation. TransientError -> back off, retry (same identity);
+        BlockedError -> rotate identity+proxy, then retry; PermanentError -> fail fast."""
+        last: Exception | None = None
+        for attempt in range(1, self.max_attempts + 1):
+            try:
+                log.info("crawl_start", crawler=type(self).__name__, attempt=attempt)
+                raw = self.flow(params)
+                log.info("crawl_done", status=raw.status, bytes=len(raw.text))
+                return raw
+            except PermanentError:
+                raise
+            except BlockedError as e:
+                last = e
+                log.warning("blocked", attempt=attempt, error=str(e))
+                if attempt < self.max_attempts:
+                    self._rotate()
+                    self._backoff(attempt)
+            except TransientError as e:
+                last = e
+                log.warning("transient", attempt=attempt, error=str(e))
+                if attempt < self.max_attempts:
+                    self._backoff(attempt)
+        raise last or RuntimeError("crawl failed with no captured error")
+
+    @staticmethod
+    def _backoff(attempt: int, cap: float = 30.0) -> None:
+        time.sleep(min(2.0**attempt + random.uniform(0, 1), cap))

crawlerkit_core-0.1.0/crawlerkit/core/base_parser.py

@@ -0,0 +1,77 @@
+"""BaseParser — the parse stage. A new target fills one hook: parse().
+
+Pure + item-local: no network beyond fetching static assets for the optional PDF, no
+cross-item state. Operates on the RawResponse the crawler returned (or a replayed one).
+"""
+
+from abc import ABC, abstractmethod
+from typing import Generic, TypeVar
+from urllib.parse import urlparse
+
+import structlog
+
+from .base_crawler import RawResponse
+
+log = structlog.get_logger(__name__)
+
+#: What ``parse()`` yields — your own model, a dataclass, a ``dict``, anything.
+#: crawlerkit-core stays dependency-free: it never dictates the output type.
+T = TypeVar("T")
+
+# Print fixups: hide leftover form inputs, landscape, fit wide tables.
+_PDF_FIXUP_CSS = """
+input { display: none !important; }
+@page { size: A4 landscape; margin: 1.2cm; }
+table { font-size: 9px; table-layout: fixed; width: 100%; }
+td, th { overflow-wrap: anywhere; }
+"""
+
+
+def render_pdf(html: str, base_url: str) -> bytes:
+    """HTML -> PDF (WeasyPrint, no browser). Fetches remote CSS over a verified, AIA-repaired
+    TLS connection (curl_cffi + crawlerkit.core.tls). No `requests`."""
+    from curl_cffi import requests as cffi
+    from weasyprint import CSS, HTML, default_url_fetcher
+
+    from . import tls
+
+    def fetcher(url: str, **kw):
+        if url.startswith(("http://", "https://")):
+            host = urlparse(url).hostname or ""
+            try:
+                r = cffi.get(url, verify=tls.build_ca_bundle(host), timeout=30, impersonate="chrome131")
+                ct = r.headers.get("content-type", "")
+                out = {"string": r.content, "redirected_url": str(r.url)}
+                mime = ct.split(";")[0].strip()
+                if mime:
+                    out["mime_type"] = mime
+                return out
+            except Exception as e:  # noqa: BLE001 — a missing asset must not kill the PDF
+                log.warning("pdf_asset_skipped", url=url, error=str(e))
+                return {"string": b"", "mime_type": "text/plain"}
+        return default_url_fetcher(url, **kw)
+
+    return HTML(string=html, base_url=base_url, url_fetcher=fetcher).write_pdf(
+        stylesheets=[CSS(string=_PDF_FIXUP_CSS)]
+    )
+
+
+class BaseParser(ABC, Generic[T]):
+    """Parse stage. Subclass with your own item type: ``class MyParser(BaseParser[MyModel])``
+    (or ``BaseParser[dict]``). ``parse()`` returns ``list[T]``; the type is yours, not the lib's."""
+
+    render_pdf_enabled: bool = True
+
+    @abstractmethod
+    def parse(self, raw: RawResponse) -> list[T]:
+        ...
+
+    def pdf(self, raw: RawResponse) -> bytes | None:
+        if not self.render_pdf_enabled:
+            return None
+        return render_pdf(raw.text, base_url=raw.url)
+
+    def run(self, raw: RawResponse) -> tuple[list[T], bytes | None]:
+        items = self.parse(raw)
+        log.info("parse_done", count=len(items))
+        return items, self.pdf(raw)

crawlerkit_core-0.1.0/crawlerkit/core/captcha/__init__.py

@@ -0,0 +1,34 @@
+from .base import (
+    CaptchaRegistry,
+    CaptchaServiceError,
+    Challenge,
+    Solved,
+    UnsupportedCaptcha,
+    default_registry,
+)
+from .govbr import GovBrSolver
+from .llm_image import LlmImageSolver
+from .mcaptcha import McaptchaPowSolver, mcaptcha_hint
+from .token_adapters import HcaptchaSolver, RecaptchaV2Solver, RecaptchaV3Solver, TokenProvider
+from .turnstile import TurnstileSolver
+
+__all__ = [
+    "Challenge",
+    "Solved",
+    "UnsupportedCaptcha",
+    "CaptchaServiceError",
+    "CaptchaRegistry",
+    "default_registry",
+    # own solvers
+    "McaptchaPowSolver",
+    "mcaptcha_hint",
+    "LlmImageSolver",
+    # browserless stubs (TODO crack)
+    "TurnstileSolver",
+    "GovBrSolver",
+    # optional token-adapters (opt-in)
+    "TokenProvider",
+    "RecaptchaV2Solver",
+    "RecaptchaV3Solver",
+    "HcaptchaSolver",
+]

crawlerkit_core-0.1.0/crawlerkit/core/captcha/base.py

@@ -0,0 +1,90 @@
+"""Captcha detection + a registry of our own solvers.
+
+Three outcomes when a source (HTML or response) is checked:
+  - no challenge        -> registry.solve returns None
+  - challenge + solver  -> Solved{token, expires_at}
+  - challenge, no solver -> raise UnsupportedCaptcha
+
+A solver produces a token; the backend (compute / LLM-image / JS-runtime) is its own business.
+Tokens are single-use and solved on submit (never pre-solved).
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional, Protocol, runtime_checkable
+
+
+@dataclass
+class Challenge:
+    kind: str
+    params: dict = field(default_factory=dict)
+
+
+@dataclass
+class Solved:
+    token: str
+    expires_at: float | None = None  # absolute epoch seconds, from the challenge's own ttl
+
+
+class UnsupportedCaptcha(Exception):
+    def __init__(self, kind: str):
+        super().__init__(f"no solver registered for captcha kind: {kind}")
+        self.kind = kind
+
+
+class CaptchaServiceError(Exception):
+    """The captcha backend returned an unexpected/error response (often transient)."""
+
+
+@runtime_checkable
+class Solver(Protocol):
+    kind: str
+
+    @classmethod
+    def detect(cls, text: str) -> Optional[Challenge]:
+        ...
+
+    def solve(self, challenge: Challenge, transport) -> Solved:
+        ...
+
+
+class CaptchaRegistry:
+    def __init__(self) -> None:
+        self._solvers: dict[str, Solver] = {}
+
+    def register(self, solver: Solver) -> "CaptchaRegistry":
+        self._solvers[solver.kind] = solver
+        return self
+
+    def detect(self, source) -> Optional[Challenge]:
+        text = source if isinstance(source, str) else getattr(source, "text", "") or ""
+        for solver in self._solvers.values():
+            ch = solver.detect(text)
+            if ch is not None:
+                return ch
+        return None
+
+    def solve(self, source, transport, *, hint: Optional[Challenge] = None) -> Optional[Solved]:
+        challenge = self.detect(source) or hint
+        if challenge is None:
+            return None
+        solver = self._solvers.get(challenge.kind)
+        if solver is None:
+            raise UnsupportedCaptcha(challenge.kind)
+        return solver.solve(challenge, transport)
+
+
+def default_registry() -> CaptchaRegistry:
+    """Registry with the built-in own-solvers: mCaptcha PoW (working) + gov.br/Turnstile
+    browserless stubs (detect works, solve raises NotImplementedError until cracked).
+    Optional token-adapters (reCAPTCHA/hCaptcha) and the LLM image solver are opt-in —
+    register them yourself when configured."""
+    from .govbr import GovBrSolver
+    from .mcaptcha import McaptchaPowSolver
+    from .turnstile import TurnstileSolver
+
+    return (
+        CaptchaRegistry()
+        .register(McaptchaPowSolver())
+        .register(TurnstileSolver())
+        .register(GovBrSolver())
+    )

crawlerkit_core-0.1.0/crawlerkit/core/captcha/govbr.py

@@ -0,0 +1,40 @@
+"""gov.br (sso.acesso.gov.br) — BROWSERLESS solver scaffold.
+
+gov.br SSO is the fleet's most common gate (~79 repos) and is browser-only in atlas today.
+`detect()` works now; `solve()` is a TODO for a manual, browserless crack — fails loudly.
+"""
+
+import re
+
+from .base import Challenge, Solved
+
+_SIGNATURE = re.compile(r"sso\.acesso\.gov\.br|acesso\.gov\.br|\bgovbr\b", re.I)
+_SITEKEY_RE = re.compile(r'data-sitekey=["\']([0-9A-Za-z_-]{8,})["\']')
+
+
+class GovBrSolver:
+    kind = "govbr"
+
+    @classmethod
+    def detect(cls, text: str):
+        text = text or ""
+        if not _SIGNATURE.search(text):
+            return None
+        m = _SITEKEY_RE.search(text)  # gov.br embeds hCaptcha/reCAPTCHA
+        return Challenge(kind=cls.kind, params={"sitekey": m.group(1) if m else None})
+
+    def solve(self, challenge: Challenge, transport) -> Solved:
+        # TODO(crawlerkit): implement the BROWSERLESS gov.br SSO authentication.
+        # gov.br (sso.acesso.gov.br) is JS-heavy and gated by a captcha (hCaptcha/reCAPTCHA) plus
+        # fingerprint checks. Browserless approach to fill in here:
+        #   1. Drive the SSO step sequence with the verified curl_cffi transport, carrying cookies
+        #      across redirects (login -> authorize -> callback).
+        #   2. Solve the embedded captcha via the registry (hCaptcha/reCAPTCHA token solver) OR a
+        #      JS-runtime crack of the gov.br challenge script (QuickJS/Node + DOM shim seeded from
+        #      the active Profile + proxy IP).
+        #   3. Complete the OAuth/SSO redirect; return Solved(token=<session cookie / SSO assertion>).
+        # Note: some gov.br services accept ICP-Brasil mutual-TLS client certs — see crawlerkit.core.tls.
+        raise NotImplementedError(
+            f"browserless gov.br solve is a TODO (params={challenge.params!r}) "
+            "— implement the SSO/JS-runtime crack"
+        )

crawlerkit_core-0.1.0/crawlerkit/core/captcha/llm_image.py

@@ -0,0 +1,46 @@
+"""Own image-captcha solver: fetch the challenge image over the verified transport, classify with
+a pluggable vision LLM, return the answer/token. Provider-agnostic — inject a `classify` callable
+`(image_bytes, prompt) -> str`. Prompts ported from atlas's GPT solver.
+
+Image captchas are target-specific, so the crawler builds the Challenge with the image location
+(`params["image_url"]` or `params["image_bytes"]`); `detect()` returns None.
+"""
+
+from .base import CaptchaServiceError, Challenge, Solved
+
+OCR_PROMPT = (
+    "This image is a CAPTCHA. Read the characters exactly. Respond with ONLY the characters "
+    "(letters/digits), no spaces, no explanation."
+)
+# 3x3 / 4x4 grid-selection prompts (hCaptcha / reCAPTCHA) are available for grid challenges;
+# port the full set from atlas chatgpt_captcha_solver.py when wiring a grid flow.
+GRID_3X3_PROMPT = (
+    "A reference image sits above a 3x3 grid (tiles numbered 1-9, left-to-right, top-to-bottom). "
+    "Return the tile numbers that clearly and fully match the reference, separated by '/', e.g. '2/5/9'. "
+    "If none match, return 'none'. No other text."
+)
+
+
+class LlmImageSolver:
+    kind = "image"
+
+    def __init__(self, classify, *, prompt: str = OCR_PROMPT):
+        # classify: Callable[[bytes, str], str]
+        self._classify = classify
+        self._prompt = prompt
+
+    @classmethod
+    def detect(cls, text: str):
+        return None  # the crawler constructs the image Challenge explicitly
+
+    def solve(self, challenge: Challenge, transport) -> Solved:
+        img = challenge.params.get("image_bytes")
+        if img is None:
+            url = challenge.params.get("image_url")
+            if not url:
+                raise CaptchaServiceError("LlmImageSolver needs params['image_url'] or ['image_bytes']")
+            img = transport.get(url, timeout=30).content
+        answer = (self._classify(img, challenge.params.get("prompt", self._prompt)) or "").strip()
+        if not answer:
+            raise CaptchaServiceError("vision LLM returned an empty answer")
+        return Solved(token=answer)