captchakraken 3.0.0 → 3.2.0

package/python/src/captchakraken/planner.py

@@ -63,6 +63,15 @@ _CLIENT_ENV = "CAPTCHA_KRAKEN_CLIENT"
 # One id per solve lets the gateway cap an attempt's billable rounds.
 _SESSION_HEADER = "X-CK-Session"
 _SESSION_ENV = "CAPTCHA_KRAKEN_SESSION"
+# Which vendor and which site a hosted solve was for, so the outcome ledger can say where solves fail. The site is
+# a hostname only: a path or query can carry a user's own data.
+_VENDOR_HEADER = "X-CK-Vendor"
+_VENDOR_ENV = "CAPTCHA_KRAKEN_VENDOR"
+# The host the widget itself was served from (its iframe's), so a failure can be reproduced against the same widget.
+_WIDGET_HOST_HEADER = "X-CK-Widget-Host"
+_WIDGET_HOST_ENV = "CAPTCHA_KRAKEN_WIDGET_HOST"
+_SITE_HEADER = "X-CK-Site"
+_SITE_ENV = "CAPTCHA_KRAKEN_SITE"
 
 # On by default; `captureOptOut` is the server half. Tier 3 sets it to 0 for ~100 solves a run.
 _REPORT_OUTCOME_ENV = "CAPTCHA_REPORT_OUTCOME"
@@ -70,12 +79,17 @@ _REPORT_OUTCOME_ENV = "CAPTCHA_REPORT_OUTCOME"
 # Extra headers may not rewrite these: pinning one X-CK-Session forever would escape the per-attempt billing cap.
 _EXTRA_HEADERS_ENV = "CAPTCHA_KRAKEN_EXTRA_HEADERS"
 _PROTECTED_HEADERS = frozenset(
-    {"authorization", "content-type", _CLIENT_HEADER.lower(), _SESSION_HEADER.lower()}
+    h.lower() for h in ("authorization", "content-type", _CLIENT_HEADER, _SESSION_HEADER, _VENDOR_HEADER, _SITE_HEADER,
+                        _WIDGET_HOST_HEADER)
 )
 
 _HEADER_VALUE_MAX = 128
 
 
+def _warn(message: str) -> None:
+    print(f"[captchakraken] warning: {message}", file=sys.stderr, flush=True)
+
+
 _VALID_HEADER_NAME = re.compile(r"^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$")
 
 
@@ -106,8 +120,11 @@ def _extra_headers(raw: str) -> Dict[str, str]:
     return out
 
 
-def routing_headers(env=None) -> Dict[str, str]:
-    """Each header is derived on its own: a malformed priority must not drop the attribution headers and understate a partner's revenue share."""
+def routing_headers(env=None, hosted: bool = False) -> Dict[str, str]:
+    """Each header is derived on its own: a malformed priority must not drop the attribution headers and understate a partner's revenue share.
+
+    Vendor and site go to the hosted API only; a self-hosted endpoint has no ledger to read them.
+    """
     env = os.environ if env is None else env
     headers: Dict[str, str] = {}
 
@@ -118,7 +135,11 @@ def routing_headers(env=None) -> Dict[str, str]:
         except ValueError:
             pass
 
-    for header, var in ((_CLIENT_HEADER, _CLIENT_ENV), (_SESSION_HEADER, _SESSION_ENV)):
+    attribution = ((_CLIENT_HEADER, _CLIENT_ENV), (_SESSION_HEADER, _SESSION_ENV))
+    if hosted:
+        attribution += ((_VENDOR_HEADER, _VENDOR_ENV), (_SITE_HEADER, _SITE_ENV),
+                        (_WIDGET_HOST_HEADER, _WIDGET_HOST_ENV))
+    for header, var in attribution:
         value = _clean_header_value(env.get(var) or "")
         if value:
             headers[header] = value
@@ -162,6 +183,29 @@ def _sampling_from_env() -> Dict[str, Any]:
         return {}
 
 
+#: The ceiling on one ask, and the old hardcoded value. Measured why it matters: against the hosted
+#: endpoint a single request hung and returned "the write operation timed out" after ~124s, inside a
+#: solve whose whole budget was 45s + 29s of recording — the attempt ran 143s. A timeout longer than
+#: the budget it sits inside cannot protect it, so callers with a deadline pass their own.
+DEFAULT_REQUEST_TIMEOUT_S: float = 120.0
+#: Never ask for less than this: a keyframe ask carries six images and a short timeout would turn a
+#: busy endpoint into a guaranteed failure rather than a slow success.
+MIN_REQUEST_TIMEOUT_S: float = 10.0
+
+
+# Set by a driver that has already warned, so the engine it starts per round does not repeat it.
+_MODEL_WARNING_ENV = "CAPTCHA_KRAKEN_MODEL_WARNING"
+_legacy_model_warned = False
+
+
+def _warn_legacy_model_once(model: str) -> None:
+    global _legacy_model_warned
+    if _legacy_model_warned or (os.environ.get(_MODEL_WARNING_ENV) or "").strip() == "0":
+        return
+    _legacy_model_warned = True
+    print(f"[captchakraken] {prompts.LEGACY_MODEL_WARNING.format(model=model)}", file=sys.stderr)
+
+
 class ActionPlanner:
 
     def __init__(
@@ -176,8 +220,14 @@ class ActionPlanner:
 
         self.model = model or config.lora_name()
         self.base_url = base_url or config.base_url()
+        if config.is_hosted_endpoint(self.base_url) and prompts.is_legacy_hosted_name(self.model):
+            _warn_legacy_model_once(self.model)
         self.api_key = api_key or config.api_key()
         self.sampling: Dict[str, Any] = {}
+        #: Seconds a single ask may take. The CALLER owns this: a solve has a budget, and a request
+        #: that outlives it cannot be cancelled once it is in flight — the deadline is only read
+        #: between steps. Left alone it is the old ceiling; `PageSolver` lowers it to what remains.
+        self.request_timeout_s: float = DEFAULT_REQUEST_TIMEOUT_S
         _prompt_key = (self.model if prompts.canonical_model_id(self.model)
                        else config.lora_adapter())
         self.prompts = prompts.resolve(_prompt_key)
@@ -189,7 +239,7 @@ class ActionPlanner:
             prompts.route(_prompt_key, None, pin=self.expert)
         self._server_ensured = False
         self._http = requests.Session()
-        self._outcome_supported = True
+        self.outcome_supported = True
 
     def _model_for(self, family: Optional[PromptFamily]) -> str:
         if not self.experts:
@@ -200,11 +250,13 @@ class ActionPlanner:
     _OUTCOME_TIMEOUT_S = 3.0
 
     def report_outcome(self, session_id: Optional[str], solved: bool) -> bool:
-        """A 404 disables it for the planner's lifetime: a self-hosted vLLM has no /solve-outcome."""
-        if not session_id or not self._outcome_supported:
+        """A 404 from a self-hosted endpoint disables it for the planner's lifetime, since vLLM has no /solve-outcome.
+        From the hosted API every failure is a fault and is warned about every time, never silently switched off."""
+        if not session_id or not self.outcome_supported:
             return False
         if os.getenv(_REPORT_OUTCOME_ENV, "1") == "0":
             return False
+        hosted = config.is_hosted_endpoint(self.base_url)
         url = f"{self.base_url}{self._OUTCOME_PATH}"
         try:
             resp = self._http.post(
@@ -212,18 +264,21 @@ class ActionPlanner:
                 headers={
                     "Authorization": f"Bearer {self.api_key}",
                     "Content-Type": "application/json",
+                    **routing_headers(hosted=hosted),
                 },
                 json={"session": session_id, "solved": bool(solved)},
                 timeout=self._OUTCOME_TIMEOUT_S,
             )
         except Exception as exc:
-            self._log(f"outcome report failed: {exc}")
+            (_warn if hosted else self._log)(f"outcome report failed: {exc}")
             return False
-        if resp.status_code == 404:
-            self._outcome_supported = False
+        if resp.status_code == 404 and not hosted:
+            self.outcome_supported = False
             self._log("outcome reporting: endpoint has no /solve-outcome; disabled")
             return False
         ok = 200 <= resp.status_code < 300
+        if not ok and hosted:
+            _warn(f"outcome report for session {session_id} was refused: HTTP {resp.status_code} from {url}")
         self._log(f"outcome report {session_id} solved={solved} -> {resp.status_code}")
         return ok
 
@@ -278,7 +333,7 @@ class ActionPlanner:
         headers = {
             "Authorization": f"Bearer {self.api_key}",
             "Content-Type": "application/json",
-            **routing_headers(),
+            **routing_headers(hosted=config.is_hosted_endpoint(self.base_url)),
         }
 
         if not self._server_ensured:
@@ -292,7 +347,8 @@ class ActionPlanner:
         self._log(f"POST {url} model={model} max_tokens={max_tokens} "
                   f"images={len(parts)}")
 
-        resp = self._http.post(url, headers=headers, json=payload, timeout=120)
+        resp = self._http.post(url, headers=headers, json=payload,
+                               timeout=self.request_timeout_s or DEFAULT_REQUEST_TIMEOUT_S)
 
         if not resp.ok:
             raise errors.from_response(resp, url)

package/python/src/captchakraken/prompts.py

@@ -414,6 +414,30 @@ def experts(model: Optional[str]) -> Dict[PromptFamily, str]:
     return out
 
 
+#: Printed once when a hosted request names a model the endpoint no longer routes. The JS port prints the same
+#: text (`model-name.ts`, pinned by test_the_legacy_model_warning_is_one_text.py).
+LEGACY_MODEL_WARNING = ("The hosted API answers the model name '{model}' with an older model. Remove the model "
+                        "pin (CAPTCHA_LORA_NAME or the model option) to use the current one.")
+
+
+def routed_names() -> set:
+    """Every name a current client puts on the wire to the hosted API: each routing alias and its expert arms."""
+    out = set()
+    for alias in served_aliases():
+        if alias.startswith("_"):
+            continue
+        arms = experts(alias)
+        if arms:
+            out.add(alias)
+            out.update(arms.values())
+    return out
+
+
+def is_legacy_hosted_name(model: Optional[str]) -> bool:
+    """A name the hosted API serves with an older model: neither a routing alias nor one of its arms."""
+    return bool(model) and model not in routed_names()
+
+
 def route(model: Optional[str], family: Optional[PromptFamily], *,
           pin: Optional[str] = None) -> str:
     """An unknown pin raises (a benchmark that silently measured the generalist is a number nobody can catch); an unknown family degrades to the generalist."""

package/python/src/captchakraken/selectors.py

@@ -26,6 +26,8 @@ class VendorSelectors:
     response: Optional[str] = None
     # Inside the checkbox frame: the box shows accepted. Demo pages do not always fill `response`.
     checked: Optional[str] = None
+    # Inside the checkbox frame: the box itself, clicked from the DOM. A vendor without one is found on a photograph.
+    box: Sequence[str] = ()
     # On the host page: the vendor painted its success state. Visibility is part of the test (see TRIBAL_KNOWLEDGE.md).
     accepted: Optional[str] = None
     # Inside the challenge frame: a new round has painted, with text.
@@ -36,6 +38,10 @@ class VendorSelectors:
     submit: Sequence[str] = ()
     # Inside the challenge frame: verdict banners and what each means.
     banners: Sequence[Tuple[str, RecaptchaBanner]] = ()
+    # Inside the challenge frame: the vendor refusing to serve this client at all. Nothing after it can succeed.
+    blocked: Sequence[str] = ()
+    # On the host page: the vendor's frames that are never interactive, so a page showing only these has no widget.
+    passive: Sequence[str] = ()
     # Inside the widget, and its enclosing fieldset/form: the answer box of a typed captcha.
     text_input: Sequence[str] = ()
     # Inside the widget: the knob a slide must start on; a drag from the piece moves nothing.
@@ -51,6 +57,7 @@ SELECTORS: Mapping[Vendor, VendorSelectors] = {
         checkbox=('iframe[src*="recaptcha/api2/anchor"]:not([src*="size=invisible"])',),
         response='[name="g-recaptcha-response"]',
         checked=".recaptcha-checkbox-checked",
+        box=("#recaptcha-anchor",),
         fresh=".rc-imageselect-instructions, #rc-imageselect",
         submit=("#recaptcha-verify-button",),
         banners=(
@@ -58,6 +65,8 @@ SELECTORS: Mapping[Vendor, VendorSelectors] = {
             (".rc-imageselect-error-dynamic-more", RecaptchaBanner.DYNAMIC_MORE),
             (".rc-imageselect-incorrect-response", RecaptchaBanner.REJECTED),
         ),
+        blocked=(".rc-doscaptcha-header-text",),
+        passive=('iframe[src*="size=invisible"]',),
     ),
     # Keyed on the `hcaptcha` substring, not the apex host: challenges are served off newassets.hcaptcha.com.
     Vendor.HCAPTCHA: VendorSelectors(
@@ -66,6 +75,7 @@ SELECTORS: Mapping[Vendor, VendorSelectors] = {
         checkbox=('iframe[src*="hcaptcha"][src*="frame=checkbox"]',),
         response='[name="h-captcha-response"]',
         checked='#checkbox[aria-checked="true"]',
+        box=("#checkbox",),
         fresh=".prompt-text",
         images=(".task-image .image", ".task .image", ".challenge-example img", ".image-wrapper img"),
         submit=(".button-submit",),

package/python/src/captchakraken/tool_calls/find_checkbox.py

@@ -37,6 +37,10 @@ def find_checkbox(image_path: str) -> Optional[Tuple[int, int, int, int]]:
         if not (0.001 * image_area < area < 0.05 * image_area):
             continue
 
+        # Every checkbox widget puts its box at the left; a square on the right is a logo or a badge.
+        if x + w / 2 > width / 2:
+            continue
+
         contour_area = cv2.contourArea(cnt)
         extent = contour_area / area
         if extent < 0.8:

package/python/src/captchakraken/tool_calls/find_grid.py

@@ -937,6 +937,25 @@ def _axis_candidates(lines, total):
     return cand
 
 
+# How near a cell's midpoint a detected gutter must sit, as a fraction of the pitch, to say the cell is two cells.
+HALVED_CELL_TOL = 0.12
+
+
+def _halves_a_finer_lattice(positions, pitch, kept_lines):
+    """True when a detected gutter splits EVERY cell of this axis down its middle.
+
+    Tall tiles fail the square-cell gate as themselves, but every other gutter spaces cells two tiles wide that
+    pass it, so a 6x3 board read as a 3x3 of tile pairs.
+    """
+    if not positions or pitch <= 0:
+        return False
+    lines = sorted(positions)
+    mids = ([lines[0] - pitch / 2.0] + [(a + b) / 2.0 for a, b in zip(lines, lines[1:])]
+            + [lines[-1] + pitch / 2.0])
+    tol = HALVED_CELL_TOL * pitch
+    return all(any(abs(l.midline_pos - m) <= tol for l in kept_lines) for m in mids)
+
+
 def extract_grid_from_lines(h_lines, v_lines, h, w, lab=None):
     """Every colour gate is RELATIVE, so a grid of any uniform border colour is detectable."""
     h_keep = _corroborate(h_lines, v_lines, h)
@@ -990,6 +1009,9 @@ def extract_grid_from_lines(h_lines, v_lines, h, w, lab=None):
                     v_col = np.mean([l.color_lab for l in vlns], axis=0)
                     if _de(h_col, v_col) > XAXIS_COLOR_TOL:
                         continue
+                    if (_halves_a_finer_lattice(vpos, vd, v_keep_int)
+                            or _halves_a_finer_lattice(hpos, hd, h_keep_int)):
+                        continue
                     slant = np.tan(h_ang)
                     ang_inc = abs(h_ang + v_ang) * 200
                     hsorted = sorted(hpos); vsorted = sorted(vpos)

package/python/src/captchakraken/verdicts.py

@@ -0,0 +1,154 @@
+"""The vendor's own answer to each submitted round, read off the wire. Mirrored in js/src/verdicts.ts.
+
+Every shape below was recorded against the vendor's public demo page, never inferred: a DOM done-signal can only
+say "something changed", while the answer-check response says whether the round was taken. A vendor with no
+readable answer (Turnstile, and the rest of the table) is judged by the DOM signals in the page driver instead.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Callable, List, Mapping, Optional, Sequence, Tuple
+
+from .kinds import Verdict, Vendor
+
+# The vendors' own HTTP refusal: hCaptcha's frame words a 429 as "Your computer or network has sent too many requests".
+_TOO_MANY_REQUESTS = 429
+
+
+@dataclass(frozen=True)
+class RoundVerdict:
+    vendor: Vendor
+    verdict: Verdict
+
+
+def _json(body: str) -> Any:
+    try:
+        return json.loads(body)
+    except ValueError:
+        return None
+
+
+def _pass_field(body: str) -> Optional[Verdict]:
+    """A JSON object whose boolean `pass` is the verdict."""
+    data = _json(body)
+    passed = data.get("pass") if isinstance(data, dict) else None
+    return None if not isinstance(passed, bool) else Verdict.ACCEPTED if passed else Verdict.REJECTED
+
+
+def _xssi_array(body: str) -> Optional[List[Any]]:
+    """A JSON array behind the `)]}'` anti-hijacking line."""
+    data = _json(body.split("\n", 1)[1] if body.startswith(")]}'") and "\n" in body else body)
+    return data if isinstance(data, list) and data else None
+
+
+def _user_verify(body: str) -> Optional[Verdict]:
+    """`["uvresp", token, 1, lifetime, ...]` when taken; `["uvresp", context, 0, ..., ["rresp", ...next board]]` when refused."""
+    data = _xssi_array(body)
+    if data is None or data[0] != "uvresp" or len(data) < 3:
+        return None
+    return {1: Verdict.ACCEPTED, 0: Verdict.REJECTED}.get(data[2]) if type(data[2]) is int else None
+
+
+def _new_board(body: str) -> Optional[Verdict]:
+    data = _xssi_array(body)
+    return Verdict.NEW_CHALLENGE if data is not None and data[0] == "rresp" else None
+
+
+def _jsonp_result(body: str) -> Optional[Verdict]:
+    """`callback({...})` whose `data.result` is the verdict."""
+    start, end = body.find("("), body.rfind(")")
+    data = _json(body[start + 1:end]) if 0 <= start < end else None
+    result = (data.get("data") or {}).get("result") if isinstance(data, dict) and data.get("status") == "success" else None
+    return {"success": Verdict.ACCEPTED, "fail": Verdict.REJECTED}.get(result) if isinstance(result, str) else None
+
+
+def _url_only(_body: str) -> Optional[Verdict]:
+    return Verdict.NEW_CHALLENGE
+
+
+@dataclass(frozen=True)
+class VerdictEndpoint:
+    # A URL substring naming the vendor's own endpoint.
+    marker: str
+    read: Callable[[str], Optional[Verdict]]
+
+
+# Only a vendor listed here has a readable answer; the rest are judged by the DOM done-signals.
+VERDICT_ENDPOINTS: Mapping[Vendor, Sequence[VerdictEndpoint]] = {
+    # The deal endpoint's body is encrypted, so its URL is the whole signal.
+    Vendor.HCAPTCHA: (VerdictEndpoint("hcaptcha.com/checkcaptcha/", _pass_field),
+                      VerdictEndpoint("hcaptcha.com/getcaptcha/", _url_only)),
+    Vendor.RECAPTCHA: (VerdictEndpoint("/recaptcha/api2/userverify", _user_verify),
+                       VerdictEndpoint("/recaptcha/api2/reload", _new_board)),
+    Vendor.GEETEST: (VerdictEndpoint("geetest.com/verify", _jsonp_result),
+                     VerdictEndpoint("geetest.com/load", _url_only)),
+}
+
+
+def endpoint_for(url: str) -> Optional[Tuple[Vendor, VerdictEndpoint]]:
+    """(vendor, endpoint) whose marker the URL carries, so a listener reads only the bodies it can judge."""
+    return next(((vendor, e) for vendor, endpoints in VERDICT_ENDPOINTS.items() for e in endpoints
+                 if e.marker in url), None)
+
+
+def read_verdict(url: str, status: int, body: str) -> Optional[RoundVerdict]:
+    found = endpoint_for(url)
+    if found is None:
+        return None
+    vendor, endpoint = found
+    if status == _TOO_MANY_REQUESTS:
+        return RoundVerdict(vendor, Verdict.BLOCKED)
+    verdict = endpoint.read(body) if 200 <= status < 300 else None
+    return RoundVerdict(vendor, verdict) if verdict is not None else None
+
+
+class VerdictLog:
+    """Every verdict the page's network carries while a solve runs.
+
+    A page-level listener sees the vendors' cross-origin frames too. It is optional: a page object with no `on`
+    records nothing, and the driver then judges every round by the DOM, as it always has.
+    """
+
+    def __init__(self, page: Any) -> None:
+        self.verdicts: List[RoundVerdict] = []
+        self._read = 0
+        self._page = page
+        self._attached = False
+        try:
+            page.on("response", self._on_response)
+            self._attached = True
+        except Exception:
+            pass
+
+    def _on_response(self, response: Any) -> None:
+        try:
+            url, status = response.url, response.status
+            if endpoint_for(url) is None:
+                return
+            # Decoded leniently, as a browser's text() is: one deal endpoint answers in ciphertext, and its URL alone
+            # is the signal.
+            body = response.body().decode("utf-8", "replace") if status != _TOO_MANY_REQUESTS else ""
+        except Exception:
+            return
+        verdict = read_verdict(url, status, body)
+        if verdict is not None:
+            self.verdicts.append(verdict)
+
+    def fresh(self) -> List[RoundVerdict]:
+        """The verdicts that arrived since the last call."""
+        new, self._read = self.verdicts[self._read:], len(self.verdicts)
+        return new
+
+    def decisive(self) -> Optional[Verdict]:
+        """The last accept or reject, which is what the round came to."""
+        return next((v.verdict for v in reversed(self.verdicts)
+                     if v.verdict in (Verdict.ACCEPTED, Verdict.REJECTED)), None)
+
+    def close(self) -> None:
+        if self._attached:
+            try:
+                self._page.remove_listener("response", self._on_response)
+            except Exception:
+                pass

package/python/Dockerfile

@@ -1,41 +0,0 @@
-# CaptchaKraken vLLM server image.
-#
-# Serves the base model + captcha LoRA over an OpenAI-compatible endpoint on
-# :8000. The image bakes in the `captchakraken[serve]` stack and (optionally)
-# the weights, then hands off to `captchakraken server run`, which execs
-# `vllm serve` assembled entirely from the env-overridable config — so you can
-# repoint it at any base model / adapter without editing this file.
-#
-#   docker build -t captchakraken-vllm .
-#   docker run --gpus all -p 8000:8000 --ipc=host \
-#     -e VLLM_API_KEY=your_key captchakraken-vllm
-FROM pytorch/pytorch:2.7.0-cuda12.8-cudnn9-devel
-
-WORKDIR /app
-
-RUN apt-get update && apt-get install -y \
-    git ninja-build libgl1 libglib2.0-0 wget ffmpeg \
-    && rm -rf /var/lib/apt/lists/*
-
-# Install the package + serving extra (vllm/torch/transformers/accelerate/hf).
-COPY . /app/captchakraken
-RUN pip install --upgrade pip && pip install "/app/captchakraken[serve]"
-
-# Model identity — all overridable at build/run time (model-agnostic image).
-ARG HF_TOKEN
-ENV HF_TOKEN=${HF_TOKEN}
-ENV CAPTCHA_BASE_MODEL="Qwen/Qwen3.5-9B"
-ENV CAPTCHA_LORA_ADAPTER="CaptchaKraken/CaptchaKraken_v1"
-ENV CAPTCHA_LORA_NAME="captcha"
-ENV VLLM_GPU_MEMORY_UTILIZATION="0.80"
-ENV VLLM_PORT=8000
-
-# Bake weights into the image (best-effort; falls back to runtime download).
-RUN python3 -c "import os; from huggingface_hub import snapshot_download; \
-    token = os.getenv('HF_TOKEN'); \
-    snapshot_download(os.getenv('CAPTCHA_BASE_MODEL'), token=token); \
-    snapshot_download(os.getenv('CAPTCHA_LORA_ADAPTER'), token=token)" \
-    || echo "Warning: model prefetch failed; weights download at first run."
-
-EXPOSE 8000
-CMD ["captchakraken", "server", "run"]

package/python/examples/README.md

@@ -1,114 +0,0 @@
-# Examples (Python)
-
-Two runnable demos that drive a real stealth browser
-([camoufox](https://github.com/JWriter20/camoufox)) to a live captcha demo site,
-screenshot the challenge, run the **engine** on it, and print token speed /
-total time / outcome:
-
-| File | Site |
-|---|---|
-| `demoRecaptcha.py` | Google reCAPTCHA v2 demo |
-| `demoHcaptcha.py` | hCaptcha demo |
-
-> The Python port is the engine (detection + planner). These demos validate the
-> engine + model + server on a real challenge frame. Full click-replay and
-> multi-round verification in a live page are what the TypeScript port
-> (`captchakraken`) does end-to-end.
-
-## Setup
-
-```bash
-cd python
-pip install -e ".[serve]"         # engine + serving stack (use ".[]" for a remote server)
-pip install camoufox              # example-only dep
-```
-
-### The camoufox binary (from your fork)
-
-Uses the **camoufox binary from the fork's releases**:
-[JWriter20/camoufox → Releases](https://github.com/JWriter20/camoufox/releases).
-
-1. Download the latest release asset for your OS/arch and extract it.
-2. Point the demo at the extracted `camoufox` executable:
-
-```bash
-export CAMOUFOX_BINARY=/path/to/camoufox/camoufox      # your fork binary
-```
-
-If `CAMOUFOX_BINARY` is unset, camoufox falls back to its default binary
-(`python -m camoufox fetch`).
-
-### Point at a model
-
-```bash
-source ../captchakraken.env       # VLLM_BASE_URL + CAPTCHA_KRAKEN_API_KEY
-```
-
-Running the model locally on **Ollama** or **LM Studio** instead? Those load
-GGUF, so they need the GGUF build rather than the AWQ/FP8 downloads — see
-[Self-hosting → GGUF](../../docs/self-hosting.md#gguf-for-ollama-lm-studio-and-llamacpp),
-then check the wiring with one image and no browser:
-
-```bash
-python examples/with_local_gguf.py path/to/captcha.png
-python examples/with_local_gguf.py path/to/text-captcha.png --text
-```
-
-## Run
-
-```bash
-python examples/demoRecaptcha.py
-python examples/demoHcaptcha.py
-HEADLESS=0 python examples/demoRecaptcha.py    # watch the browser
-```
-
-## Reading the report
-
-```
-  result        : ✓ engine produced a solution
-  click plan: 4 tile(s)/target(s)
-  total time    : 6.1s (solve: 3.4s)
-  tokens        : 812 in / 34 out
-  gen speed     : ~10.0 tok/s
-  reason        : <only on failure — unsupported puzzle, unreachable server, …>
-```
-
-`gen speed` = model output tokens ÷ solve seconds. Failure reasons the harness
-reports: unreachable vLLM server, an unsupported hCaptcha puzzle (drag/video),
-the challenge iframe never appearing, or the model returning no matching tiles.
-
-## Playwright, and the auto-solver
-
-| File | What it shows |
-|---|---|
-| `with_playwright.py` | Vanilla Playwright — no adapter, 2 added lines |
-| `watch_playwright.py` | The auto-solver: install once, solves as they appear |
-
-```bash
-pip install playwright && playwright install chromium
-
-export VLLM_BASE_URL=https://api.captchakraken.com/v1
-export CAPTCHA_KRAKEN_API_KEY=ck_live_...
-
-python examples/with_playwright.py
-python examples/watch_playwright.py https://your.site/page 60
-```
-
-Use `sync_playwright`, not `async_playwright`: `PageSolver` mirrors the
-synchronous API, and a sync handle cannot be driven from inside an event loop.
-
-## There is no Puppeteer path in Python
-
-The TypeScript port ships `fromPuppeteer()` because Puppeteer is a first-class
-Node library. Python has no equivalent worth pointing you at:
-
-- **pyppeteer** last released 2.0.0 in **February 2024**, and pins
-  `urllib3 <2.0.0` and `websockets <11.0` — which conflicts directly with
-  CaptchaKraken's own `requests` dependency, so the two cannot co-install
-  cleanly.
-- It is **async-only**, and this driver is synchronous. Even resolving the
-  dependency conflict, a sync `PageSolver` cannot be driven from asyncio.
-
-Playwright *is* the Python answer, and `patchright` and `camoufox` are the
-stealth-patched builds of it — all three duck-type identically, so the examples
-above work unchanged with any of them.