captchakraken 2.1.0

package/python/examples/_harness.py

@@ -0,0 +1,158 @@
+"""
+Shared runner for the CaptchaKraken Python demos.
+
+The Python port is the *engine* (OpenCV detection + the vLLM planner). These demos
+launch a real stealth browser (camoufox, using the binary from your fork —
+JWriter20/camoufox releases; see README.md), navigate to a captcha demo site,
+open the challenge, screenshot it, and run the engine on that frame. They report
+token-generation speed, total time, and whether the engine produced a valid
+solution — plus a best-effort reason when it didn't.
+
+Note: full click-replay + multi-round verification in a live page is what the
+TypeScript port (`captchakraken`) does end-to-end. Here we validate the
+engine + model + server on a real challenge frame.
+"""
+
+import os
+import tempfile
+import time
+from dataclasses import dataclass
+
+from camoufox.sync_api import Camoufox
+
+from captchakraken import CaptchaSolver
+from captchakraken.action_types import ClickAction
+from captchakraken.solver import UnsupportedCaptchaError
+
+
+@dataclass
+class DemoSpec:
+    name: str
+    url: str
+    vendor: str  # "recaptcha" | "hcaptcha"
+
+
+def _launch_kwargs() -> dict:
+    kw = dict(headless=os.getenv("HEADLESS", "1") != "0", humanize=True, geoip=False)
+    # Point camoufox at YOUR fork's binary. If unset, camoufox uses its default
+    # cached binary (`python -m camoufox fetch`).
+    binary = os.getenv("CAMOUFOX_BINARY") or os.getenv("CAMOUFOX_EXECUTABLE_PATH")
+    if binary:
+        kw["executable_path"] = binary
+    return kw
+
+
+def _capture_challenge(page, spec: DemoSpec) -> str:
+    """Reach the challenge iframe and screenshot it to a temp PNG. Returns the path.
+
+    Raises RuntimeError with a human message if the challenge never appears.
+    """
+    out = tempfile.NamedTemporaryFile(suffix=".png", delete=False).name
+
+    if spec.vendor == "recaptcha":
+        anchor = page.wait_for_selector('iframe[src*="/recaptcha/api2/anchor"]', timeout=30_000)
+        frame = anchor.content_frame()
+        frame.click("#recaptcha-anchor", timeout=15_000)
+        challenge = page.wait_for_selector('iframe[src*="/recaptcha/api2/bframe"]', timeout=30_000)
+        # Let the tiles paint.
+        page.wait_for_timeout(2500)
+        challenge.screenshot(path=out)
+        return out
+
+    if spec.vendor == "hcaptcha":
+        box = page.wait_for_selector('iframe[src*="hcaptcha.com"][src*="checkbox"], iframe[title*="checkbox"]',
+                                     timeout=30_000)
+        box.content_frame().click("#checkbox, div[role=checkbox]", timeout=15_000)
+        challenge = page.wait_for_selector('iframe[title*="hCaptcha challenge"], iframe[src*="hcaptcha.com"][src*="frame=challenge"]',
+                                           timeout=30_000)
+        page.wait_for_timeout(2500)
+        challenge.screenshot(path=out)
+        return out
+
+    raise RuntimeError(f"unknown vendor {spec.vendor!r}")
+
+
+def _tokens_per_sec(solver: CaptchaSolver, elapsed_s: float) -> tuple[int, int, float]:
+    """(input_tokens, output_tokens, tokens/sec) from the planner's usage log."""
+    inp = out = 0
+    for u in getattr(solver.planner, "token_usage", []) or []:
+        inp += int(u.get("prompt_tokens", 0) or 0)
+        out += int(u.get("completion_tokens", 0) or 0)
+    tps = out / elapsed_s if out and elapsed_s > 0 else 0.0
+    return inp, out, tps
+
+
+def _explain(vendor: str, err: Exception) -> str:
+    msg = str(err).lower()
+    if isinstance(err, UnsupportedCaptchaError) or "cannot solve" in msg or "unsupported" in msg:
+        if vendor == "hcaptcha":
+            return ("hCaptcha served a non-grid challenge (drag / video / choose-the-card). "
+                    "The engine handles image grids + checkboxes only — re-run to try for a grid.")
+        return "Not a supported grid/checkbox challenge — re-run to try again."
+    if "vllm" in msg or "connection" in msg or "refused" in msg or "max retries" in msg:
+        return ("Could not reach the vLLM server — is it up and is VLLM_BASE_URL correct? "
+                "(A local server auto-starts only if captchakraken[serve] is installed.)")
+    if "timeout" in msg or "wait_for_selector" in msg:
+        return "The challenge iframe never appeared (slow network, blocked widget, or the checkbox auto-passed)."
+    return str(err) or "Unknown failure."
+
+
+def run_demo(spec: DemoSpec) -> None:
+    t0 = time.time()
+    ok = False
+    reason = None
+    inp = out = 0
+    tps = 0.0
+    solve_s = 0.0
+    plan_desc = "-"
+
+    try:
+        with Camoufox(**_launch_kwargs()) as browser:
+            page = browser.new_page()
+            page.goto(spec.url, wait_until="domcontentloaded", timeout=60_000)
+            shot = _capture_challenge(page, spec)
+
+            solver = CaptchaSolver()
+            s0 = time.time()
+            try:
+                actions = solver.solve(shot, puzzle_source=spec.vendor)
+            finally:
+                solve_s = time.time() - s0
+            inp, out, tps = _tokens_per_sec(solver, solve_s)
+
+            acts = actions if isinstance(actions, list) else [actions]
+            clicks = [a for a in acts if isinstance(a, ClickAction) and (a.target_bounding_boxes or [])]
+            n_tiles = sum(len(a.target_bounding_boxes or []) for a in clicks)
+            if n_tiles > 0:
+                ok = True
+                plan_desc = f"click plan: {n_tiles} tile(s)/target(s)"
+            else:
+                plan_desc = f"actions: {[type(a).__name__ for a in acts]}"
+                reason = ("The model returned no tiles to click — either none matched the prompt, "
+                          "or the challenge frame wasn't a clean grid. Re-run to try again.")
+    except Exception as err:  # noqa: BLE001 — demo: report, don't traceback
+        reason = _explain(spec.vendor, err)
+
+    _report(spec, ok=ok, total_s=time.time() - t0, solve_s=solve_s,
+            inp=inp, out=out, tps=tps, plan=plan_desc, reason=reason)
+
+
+def _fmt(s: float) -> str:
+    return f"{s:.1f}s" if s >= 1 else f"{int(s * 1000)}ms"
+
+
+def _report(spec, *, ok, total_s, solve_s, inp, out, tps, plan, reason):
+    line = "─" * 52
+    print(f"\n{line}")
+    print(f"  CaptchaKraken demo (engine) — {spec.name}")
+    print(f"  {spec.url}")
+    print(line)
+    print(f"  result        : {'✓ engine produced a solution' if ok else '✗ no solution'}")
+    print(f"  {plan}")
+    print(f"  total time    : {_fmt(total_s)}   (solve: {_fmt(solve_s)})")
+    print(f"  tokens        : {inp} in / {out} out")
+    print(f"  gen speed     : {f'~{tps:.1f} tok/s' if tps > 0 else 'n/a'}")
+    if reason:
+        print(f"  reason        : {reason}")
+    print(f"{line}\n")
+    raise SystemExit(0 if ok else 1)

package/python/examples/demoHcaptcha.py

@@ -0,0 +1,20 @@
+"""
+Engine demo: run CaptchaKraken on the standard hCaptcha demo page.
+
+    pip install -e ".[serve]"     # engine + serving stack (or [.] against a remote server)
+    pip install camoufox && python -m camoufox fetch   # or set CAMOUFOX_BINARY to your fork binary
+    source ../captchakraken.env    # VLLM_BASE_URL + CAPTCHA_KRAKEN_API_KEY
+    python examples/demoHcaptcha.py
+
+Note: hCaptcha randomly serves non-grid puzzles (drag / video / choose-the-card),
+which the engine does not handle yet — the report says so; re-run for a grid.
+"""
+
+from _harness import DemoSpec, run_demo
+
+if __name__ == "__main__":
+    run_demo(DemoSpec(
+        name="hCaptcha",
+        url="https://accounts.hcaptcha.com/demo",
+        vendor="hcaptcha",
+    ))

package/python/examples/demoRecaptcha.py

@@ -0,0 +1,17 @@
+"""
+Engine demo: run CaptchaKraken on Google's standard reCAPTCHA v2 demo page.
+
+    pip install -e ".[serve]"     # engine + serving stack (or [.] against a remote server)
+    pip install camoufox && python -m camoufox fetch   # or set CAMOUFOX_BINARY to your fork binary
+    source ../captchakraken.env    # VLLM_BASE_URL + CAPTCHA_KRAKEN_API_KEY
+    python examples/demoRecaptcha.py
+"""
+
+from _harness import DemoSpec, run_demo
+
+if __name__ == "__main__":
+    run_demo(DemoSpec(
+        name="reCAPTCHA v2",
+        url="https://www.google.com/recaptcha/api2/demo",
+        vendor="recaptcha",
+    ))

package/python/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "captchakraken"
+version = "2.0.0"
+description = "Self-hosted captcha solver: OpenCV grid detection + a fine-tuned Qwen3.5-9B vision LoRA served on vLLM."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "GPL-3.0-or-later" }
+authors = [{ name = "Jake Writer" }]
+keywords = ["captcha", "recaptcha", "hcaptcha", "vllm", "qwen", "computer-vision", "automation"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+# Core = the lightweight CLIENT: OpenCV grid detection + the HTTP planner that
+# talks to a vLLM server (local or remote). This is all you need to SOLVE
+# captchas against an existing endpoint. The heavy serving stack (vllm/torch)
+# is deliberately NOT here — see the `serve` extra.
+dependencies = [
+  "pydantic>=2.0.0",
+  "pillow>=10.0.0",
+  "numpy>=1.24.0",
+  "opencv-python-headless>=4.10.0",
+  "requests>=2.31.0",
+  "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+# Self-hosting: install this to RUN a local vLLM server (the setup script does
+# `pip install "captchakraken[serve]"`). Not needed to call a remote server.
+serve = [
+  "vllm>=0.6.3",
+  "torch>=2.0.0",
+  "transformers>=4.40.0",
+  "accelerate>=0.27.0",
+  "huggingface_hub>=0.23.0",
+]
+dev = [
+  "pytest>=7.0.0",
+  "mypy>=1.0.0",
+  "ruff>=0.1.0",
+]
+
+[project.scripts]
+captchakraken = "captchakraken.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/JWriter20/CaptchaKraken"
+Issues = "https://github.com/JWriter20/CaptchaKraken/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/captchakraken"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = false
+warn_unused_configs = true
+disallow_untyped_defs = false
+check_untyped_defs = false
+ignore_missing_imports = true
+no_implicit_optional = false
+exclude = ["build/", "dist/"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = ["E501"]

package/python/src/captchakraken/__init__.py

@@ -0,0 +1,61 @@
+"""
+CaptchaKraken — OpenCV grid detection + a fine-tuned Qwen3.5-9B vision LoRA
+served on vLLM.
+
+Usage:
+    from captchakraken import CaptchaSolver
+    solver = CaptchaSolver()   # auto-starts / connects to a local vLLM server
+    actions = solver.solve("captcha.png")
+
+Model/endpoint defaults live in `captchakraken.config` and are fully
+env-overridable (VLLM_BASE_URL, CAPTCHA_LORA_ADAPTER, …); the solver itself is
+model-agnostic. The legacy v1 stack (SAM3 grounding, multi-provider planner,
+detect/segment/drag-refine) lives on the `v1-old-architecture` branch.
+"""
+
+from pathlib import Path
+
+try:  # pragma: no cover
+    from dotenv import load_dotenv
+
+    project_root = Path(__file__).resolve().parent.parent
+    load_dotenv(project_root / ".env")
+except Exception:
+    pass
+
+from .action_types import (
+    CaptchaAction,
+    ClickAction,
+    DragAction,
+    TypeAction,
+    WaitAction,
+)
+from .image_processor import ImageProcessor
+from .overlay import add_overlays_to_image
+
+# The planner (requests) and solver (torch/vllm/transformers) pull in the heavy
+# serving stack. Keep them optional so leaf modules — e.g. tool_calls.find_grid,
+# which needs only cv2 + numpy + pillow — can be imported in a minimal env (CI's
+# hermetic grid-detection test) without the full GPU dependency set installed.
+try:  # pragma: no cover - exercised only when the serving stack is installed
+    from .planner import ActionPlanner
+    from .solver import CaptchaSolver, solve_captcha
+except ModuleNotFoundError:
+    ActionPlanner = None  # type: ignore[assignment,misc]
+    CaptchaSolver = None  # type: ignore[assignment,misc]
+    solve_captcha = None  # type: ignore[assignment]
+
+__all__ = [
+    "CaptchaSolver",
+    "solve_captcha",
+    "ActionPlanner",
+    "ImageProcessor",
+    "CaptchaAction",
+    "ClickAction",
+    "DragAction",
+    "TypeAction",
+    "WaitAction",
+    "add_overlays_to_image",
+]
+
+__version__ = "2.0.0"

package/python/src/captchakraken/action_types.py

@@ -0,0 +1,56 @@
+from typing import List, Literal, Optional, Union, Tuple
+
+from pydantic import BaseModel, RootModel
+
+
+class BoundingBox(RootModel):
+    """
+    Strongly typed bounding box: [x1, y1, x2, y2] in percentages (0.0 to 1.0).
+    Acts like a list for convenience but ensures exactly 4 float elements.
+    """
+    root: Tuple[float, float, float, float]
+
+    def __iter__(self):
+        return iter(self.root)
+
+    def __getitem__(self, item):
+        return self.root[item]
+
+    def __len__(self):
+        return len(self.root)
+
+
+class Action(BaseModel):
+    action: str
+
+
+class ClickAction(Action):
+    action: Literal["click"]
+    target_bounding_boxes: List[BoundingBox] # List of [x1, y1, x2, y2] in percentages
+
+
+class DragAction(Action):
+    action: Literal["drag"]
+    source_bounding_box: BoundingBox = None  # [x1, y1, x2, y2] in percentages
+    target_bounding_box: BoundingBox = None  # [x1, y1, x2, y2] in percentages
+
+
+class TypeAction(Action):
+    """Type text into an input."""
+    action: Literal["type"]
+    text: str
+    target_bounding_box: BoundingBox = None  # [x1, y1, x2, y2] in percentages
+
+
+class WaitAction(Action):
+    """Wait for a specified duration."""
+    action: Literal["wait"]
+    duration_ms: int
+
+
+class DoneAction(Action):
+    """Signal that the captcha is solved or no further actions are needed."""
+    action: Literal["done"]
+
+
+CaptchaAction = Union[ClickAction, DragAction, TypeAction, WaitAction, DoneAction]