captchakraken 3.0.0__tar.gz → 3.2.0__tar.gz

{captchakraken-3.0.0 → captchakraken-3.2.0}/AGENTS.md

@@ -9,7 +9,7 @@ browser — bring your own — and every inference goes to a model endpoint you
 point it at. The `serve` extra is what turns this box into that endpoint.
 
 Repo, guides and the full agent guide:
-<https://github.com/JWriter20/CaptchaKraken>
+<https://github.com/CaptchaKraken/CaptchaKraken>
 
 ---
 
@@ -71,10 +71,15 @@ module docstring of `captchakraken/cli.py` lists every mode with its arguments.
 ## 4. Errors
 
 `PageSolver.solve()` raises from `captchakraken.page_solver`:
-`NoCaptchaFoundError` (no interactive widget — usually not a failure),
-`UnsupportedChallengeError`, `AnimatedChallengeError` (the challenge could not
-be *recorded*), `PageClosedError`, and `CaptchaSolveError`, which is the base
-class of the other four — catch it last or it swallows them. The TypeScript
+`NoCaptchaFoundError` (no interactive widget appeared within
+`detection_timeout_ms` — usually not a failure), `VendorBlockedError` (the
+vendor refused to serve this client at all), `UnsupportedChallengeError`,
+`AnimatedChallengeError` (the challenge could not be *recorded*),
+`PageClosedError`, and `CaptchaSolveError`, which is the base class of the
+other five — catch it last or it swallows them. Apart from a vendor refusal, a
+closed page and the time budget, a solve only gives up once every one of
+`max_solve_loops` has been spent. `result.verdicts` holds the vendor's own
+answer to each round where its answer-check response is readable. The TypeScript
 port raises none of these; it exports one error class and throws plain `Error`
 otherwise.
 
@@ -100,7 +105,7 @@ generation and the weights drift apart.
 
 - **Never invent a number.** Every accuracy, latency and price figure we publish
   is on one page —
-  [docs/benchmarks.md](https://github.com/JWriter20/CaptchaKraken/blob/main/docs/benchmarks.md).
+  [docs/benchmarks.md](https://github.com/CaptchaKraken/CaptchaKraken/blob/main/docs/benchmarks.md).
   Quote it as written; do not derive, round, or convert anything, and do not
   read a static-image rate as a promise about a browser run.
 - **Never print an API key** into a transcript, a log, or a commit. Use
@@ -116,7 +121,7 @@ generation and the weights drift apart.
 - **Respect the licence.** Building automation with this is fine; selling the
   solve, or shipping it inside a browser or automation product, is not. See
   [LICENSE](./LICENSE) and
-  [docs/licensing.md](https://github.com/JWriter20/CaptchaKraken/blob/main/docs/licensing.md).
+  [docs/licensing.md](https://github.com/CaptchaKraken/CaptchaKraken/blob/main/docs/licensing.md).
 - **Changing this package's own code?** Its rules are in
-  [CONTRIBUTING.md](https://github.com/JWriter20/CaptchaKraken/blob/main/CONTRIBUTING.md),
+  [CONTRIBUTING.md](https://github.com/CaptchaKraken/CaptchaKraken/blob/main/CONTRIBUTING.md),
   not here.

{captchakraken-3.0.0 → captchakraken-3.2.0}/LICENSE

@@ -141,5 +141,5 @@ This text is a license, not legal advice. If the boundary between a permitted
 "value-add" product and a prohibited "thin wrapper", or between using the
 Software with a browser and shipping it as part of one, is unclear for your use
 case, ask by opening an issue or messaging the maintainer on GitHub:
-https://github.com/JWriter20/CaptchaKraken
+https://github.com/CaptchaKraken/CaptchaKraken
 --------------------------------------------------------------------------------

{captchakraken-3.0.0 → captchakraken-3.2.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: captchakraken
-Version: 3.0.0
+Version: 3.2.0
 Summary: Captcha-solving engine and CLI: OpenCV grid detection plus a fine-tuned Qwen3.5-9B vision model, for image grids, click and drag puzzles, sliders, distorted text and animated challenges. Hosted API or self-hosted on vLLM.
 Project-URL: Homepage, https://captchakraken.com
-Project-URL: Documentation, https://github.com/JWriter20/CaptchaKraken#readme
-Project-URL: Source, https://github.com/JWriter20/CaptchaKraken
-Project-URL: Issues, https://github.com/JWriter20/CaptchaKraken/issues
-Project-URL: Changelog, https://github.com/JWriter20/CaptchaKraken/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/CaptchaKraken/CaptchaKraken#readme
+Project-URL: Source, https://github.com/CaptchaKraken/CaptchaKraken
+Project-URL: Issues, https://github.com/CaptchaKraken/CaptchaKraken/issues
+Project-URL: Changelog, https://github.com/CaptchaKraken/CaptchaKraken/blob/main/CHANGELOG.md
 Author: Jake Writer
 License: CaptchaKraken Source-Available License v1.1
         Copyright (c) 2026 CaptchaKraken LLC. All rights reserved.
@@ -151,11 +151,11 @@ License: CaptchaKraken Source-Available License v1.1
         "value-add" product and a prohibited "thin wrapper", or between using the
         Software with a browser and shipping it as part of one, is unclear for your use
         case, ask by opening an issue or messaging the maintainer on GitHub:
-        https://github.com/JWriter20/CaptchaKraken
+        https://github.com/CaptchaKraken/CaptchaKraken
         --------------------------------------------------------------------------------
 License-File: LICENSE
 License-File: NOTICE
-Keywords: anti-bot,browser-automation,captcha,captcha-solver,computer-vision,geetest,hcaptcha,ocr,playwright,qwen,recaptcha,scraping,tencent-captcha,turnstile,vllm,yidun
+Keywords: anti-bot,browser-automation,captcha,captcha-solver,computer-vision,geetest,ocr,playwright,qwen,recaptcha,scraping,tencent-captcha,turnstile,vllm,yidun
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: Other/Proprietary License
@@ -191,14 +191,14 @@ Requires-Dist: vllm==0.29.0; extra == 'serve'
 Description-Content-Type: text/markdown
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/JWriter20/CaptchaKraken/main/docs/assets/logo-card.png" alt="CaptchaKraken" width="128" height="128">
+  <img src="https://raw.githubusercontent.com/CaptchaKraken/CaptchaKraken/main/docs/assets/logo-card.png" alt="CaptchaKraken" width="128" height="128">
 </p>
 
 <h1 align="center">captchakraken</h1>
 
 <p align="center">
   <b>A captcha solver for browser automation.</b><br>
-  The Python engine and CLI behind <a href="https://github.com/JWriter20/CaptchaKraken">CaptchaKraken</a>.
+  The Python engine and CLI behind <a href="https://github.com/CaptchaKraken/CaptchaKraken">CaptchaKraken</a>.
 </p>
 
 OpenCV tile detection plus a fine-tuned **Qwen3.5-9B** vision model. Give it a
@@ -211,34 +211,31 @@ nothing at all.
 
 > For demo videos, accuracy numbers, the browser driver, and the full
 > self-hosting guide, see the main repo
-> **[CaptchaKraken](https://github.com/JWriter20/CaptchaKraken)**.
+> **[CaptchaKraken](https://github.com/CaptchaKraken/CaptchaKraken)**.
 
 ## Watch it work
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/JWriter20/CaptchaKraken/main/docs/assets/demo/hcaptcha_grid.webp" width="260"
-       alt="A live hCaptcha image select challenge being solved end to end">
-  <img src="https://raw.githubusercontent.com/JWriter20/CaptchaKraken/main/docs/assets/demo/recaptcha_4x4.webp" width="260"
+  <img src="https://raw.githubusercontent.com/CaptchaKraken/CaptchaKraken/main/docs/assets/demo/recaptcha_4x4.webp" width="260"
        alt="A live reCAPTCHA 4×4 tile grid challenge being solved end to end">
-  <img src="https://raw.githubusercontent.com/JWriter20/CaptchaKraken/main/docs/assets/demo/geetest_slide.webp" width="260"
+  <img src="https://raw.githubusercontent.com/CaptchaKraken/CaptchaKraken/main/docs/assets/demo/geetest_slide.webp" width="260"
        alt="A live GeeTest slide jigsaw challenge being solved end to end">
 </p>
 
-hCaptcha image select 12/12 in 10.5s · reCAPTCHA 4×4 tile grid 9/10 in 8.7s · GeeTest slide jigsaw 10/10 in 7.6s — median of the solved attempts, measured 2026-08-19 on **captcha-v12**
+reCAPTCHA 4×4 tile grid 9/10 in 8.7s · GeeTest slide jigsaw 10/10 in 7.6s — median of the solved attempts, measured 2026-08-19 on **captcha-v12**
 against each vendor's own public demo page. Counts rather than percentages
 because ten attempts is not a percentage. Idle time is cut from the clips, so
 they run shorter than the solves they show.
 
-**Ten more puzzle types**, as video and with the full method, at
+**More puzzle types**, as video and with the full method, at
 [captchakraken.com](https://captchakraken.com) and in the
-[main repo](https://github.com/JWriter20/CaptchaKraken#watch-it-work).
+[main repo](https://github.com/CaptchaKraken/CaptchaKraken#watch-it-work).
 
 ## What it solves
 
 | Vendor | Puzzles |
 |---|---|
 | **reCAPTCHA** | 3×3 and 4×4 image grids, including the dynamic re-deal |
-| **hCaptcha** | Image grids, click, drag, connect-the-path, tetris-fit, animated |
 | **GeeTest** v3 + v4 | Slide, icon, nine, svg, gobang, iconcrush |
 | **NetEase Yidun** | Jigsaw, picture-click, icon-click |
 | **Tencent, Lemin, Prosopo** | Slide, cropped-image and grid flows |
@@ -259,7 +256,7 @@ pip install "captchakraken[serve]"   # + the serving stack (vLLM/torch) to self-
 The base install is lightweight — everything you need to solve captchas against
 a vLLM server (local or remote). The `[serve]` extra pulls the heavy stack only
 if you want to run the model yourself. The one-command
-[`setup.sh`](https://github.com/JWriter20/CaptchaKraken) installs `[serve]`,
+[`setup.sh`](https://github.com/CaptchaKraken/CaptchaKraken) installs `[serve]`,
 downloads the weights, and writes an env file for you.
 
 ## No GPU? Use the hosted API
@@ -292,7 +289,7 @@ captchakraken server start | stop | status | run
 ```bash
 # Solve an image/video: classify → find_grid → plan. Prints the click actions.
 captchakraken path/to/captcha.png
-captchakraken path/to/captcha.png --puzzle-source hcaptcha
+captchakraken path/to/captcha.png --puzzle-source recaptcha
 ```
 
 ```python

{captchakraken-3.0.0 → captchakraken-3.2.0}/README.md

@@ -1,12 +1,12 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/JWriter20/CaptchaKraken/main/docs/assets/logo-card.png" alt="CaptchaKraken" width="128" height="128">
+  <img src="https://raw.githubusercontent.com/CaptchaKraken/CaptchaKraken/main/docs/assets/logo-card.png" alt="CaptchaKraken" width="128" height="128">
 </p>
 
 <h1 align="center">captchakraken</h1>
 
 <p align="center">
   <b>A captcha solver for browser automation.</b><br>
-  The Python engine and CLI behind <a href="https://github.com/JWriter20/CaptchaKraken">CaptchaKraken</a>.
+  The Python engine and CLI behind <a href="https://github.com/CaptchaKraken/CaptchaKraken">CaptchaKraken</a>.
 </p>
 
 OpenCV tile detection plus a fine-tuned **Qwen3.5-9B** vision model. Give it a
@@ -19,34 +19,31 @@ nothing at all.
 
 > For demo videos, accuracy numbers, the browser driver, and the full
 > self-hosting guide, see the main repo
-> **[CaptchaKraken](https://github.com/JWriter20/CaptchaKraken)**.
+> **[CaptchaKraken](https://github.com/CaptchaKraken/CaptchaKraken)**.
 
 ## Watch it work
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/JWriter20/CaptchaKraken/main/docs/assets/demo/hcaptcha_grid.webp" width="260"
-       alt="A live hCaptcha image select challenge being solved end to end">
-  <img src="https://raw.githubusercontent.com/JWriter20/CaptchaKraken/main/docs/assets/demo/recaptcha_4x4.webp" width="260"
+  <img src="https://raw.githubusercontent.com/CaptchaKraken/CaptchaKraken/main/docs/assets/demo/recaptcha_4x4.webp" width="260"
        alt="A live reCAPTCHA 4×4 tile grid challenge being solved end to end">
-  <img src="https://raw.githubusercontent.com/JWriter20/CaptchaKraken/main/docs/assets/demo/geetest_slide.webp" width="260"
+  <img src="https://raw.githubusercontent.com/CaptchaKraken/CaptchaKraken/main/docs/assets/demo/geetest_slide.webp" width="260"
        alt="A live GeeTest slide jigsaw challenge being solved end to end">
 </p>
 
-hCaptcha image select 12/12 in 10.5s · reCAPTCHA 4×4 tile grid 9/10 in 8.7s · GeeTest slide jigsaw 10/10 in 7.6s — median of the solved attempts, measured 2026-08-19 on **captcha-v12**
+reCAPTCHA 4×4 tile grid 9/10 in 8.7s · GeeTest slide jigsaw 10/10 in 7.6s — median of the solved attempts, measured 2026-08-19 on **captcha-v12**
 against each vendor's own public demo page. Counts rather than percentages
 because ten attempts is not a percentage. Idle time is cut from the clips, so
 they run shorter than the solves they show.
 
-**Ten more puzzle types**, as video and with the full method, at
+**More puzzle types**, as video and with the full method, at
 [captchakraken.com](https://captchakraken.com) and in the
-[main repo](https://github.com/JWriter20/CaptchaKraken#watch-it-work).
+[main repo](https://github.com/CaptchaKraken/CaptchaKraken#watch-it-work).
 
 ## What it solves
 
 | Vendor | Puzzles |
 |---|---|
 | **reCAPTCHA** | 3×3 and 4×4 image grids, including the dynamic re-deal |
-| **hCaptcha** | Image grids, click, drag, connect-the-path, tetris-fit, animated |
 | **GeeTest** v3 + v4 | Slide, icon, nine, svg, gobang, iconcrush |
 | **NetEase Yidun** | Jigsaw, picture-click, icon-click |
 | **Tencent, Lemin, Prosopo** | Slide, cropped-image and grid flows |
@@ -67,7 +64,7 @@ pip install "captchakraken[serve]"   # + the serving stack (vLLM/torch) to self-
 The base install is lightweight — everything you need to solve captchas against
 a vLLM server (local or remote). The `[serve]` extra pulls the heavy stack only
 if you want to run the model yourself. The one-command
-[`setup.sh`](https://github.com/JWriter20/CaptchaKraken) installs `[serve]`,
+[`setup.sh`](https://github.com/CaptchaKraken/CaptchaKraken) installs `[serve]`,
 downloads the weights, and writes an env file for you.
 
 ## No GPU? Use the hosted API
@@ -100,7 +97,7 @@ captchakraken server start | stop | status | run
 ```bash
 # Solve an image/video: classify → find_grid → plan. Prints the click actions.
 captchakraken path/to/captcha.png
-captchakraken path/to/captcha.png --puzzle-source hcaptcha
+captchakraken path/to/captcha.png --puzzle-source recaptcha
 ```
 
 ```python

{captchakraken-3.0.0 → captchakraken-3.2.0}/examples/README.md

@@ -1,16 +1,15 @@
 # Examples (Python)
 
-Two runnable demos that drive a real stealth browser
+A runnable demo that drives 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 /
+screenshots the challenge, runs the **engine** on it, and prints 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
+> The Python port is the engine (detection + planner). This demo validates 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.
@@ -58,7 +57,6 @@ python examples/with_local_gguf.py path/to/text-captcha.png --text
 
 ```bash
 python examples/demoRecaptcha.py
-python examples/demoHcaptcha.py
 HEADLESS=0 python examples/demoRecaptcha.py    # watch the browser
 ```
 
@@ -74,7 +72,7 @@ HEADLESS=0 python examples/demoRecaptcha.py    # watch the browser
 ```
 
 `gen speed` = model output tokens ÷ solve seconds. Failure reasons the harness
-reports: unreachable vLLM server, an unsupported hCaptcha puzzle (drag/video),
+reports: unreachable vLLM server, a challenge type the solver does not handle,
 the challenge iframe never appearing, or the model returning no matching tiles.
 
 ## Playwright, and the auto-solver

{captchakraken-3.0.0 → captchakraken-3.2.0}/examples/_harness.py

@@ -24,8 +24,7 @@ def spec_from_argv(default: DemoSpec, argv=None) -> DemoSpec:
     ap.add_argument("url", nargs="?", default=default.url,
                     help=f"page to solve (default: {default.url})")
     ap.add_argument("--vendor", default=default.vendor,
-                    choices=("hcaptcha", "recaptcha"),
-                    help="only affects failure wording; the solver auto-detects")
+                    help="label recorded in the report; the solver auto-detects")
     ap.add_argument("--name", default=None, help="label for the report")
     ap.add_argument("--headed", action="store_true",
                     help="show the browser (same as HEADLESS=0)")
@@ -74,12 +73,9 @@ def _tokens(usage) -> tuple[int, int]:
     return inp, out
 
 
-def _explain(vendor: str, solved: bool, err) -> str:
+def _explain(solved: bool, err) -> str:
     msg = str(err or "").lower()
     if "unsupported" in msg or "cannot solve" in msg:
-        if vendor == "hcaptcha":
-            return ("hCaptcha served a challenge type the solver does not handle "
-                    "yet (drag / video / choose-the-card) — re-run for a grid.")
         return "Not a supported challenge type — re-run to try again."
     if "no captcha" in msg or "nocaptchafound" in msg:
         return ("No captcha widget was found on that page. Check the URL, or "
@@ -128,15 +124,15 @@ def run_demo(spec: DemoSpec) -> None:
                 ok = bool(result.is_solved)
                 inp, out = _tokens(result.token_usage)
                 if not ok:
-                    reason = _explain(spec.vendor, ok, None)
+                    reason = _explain(ok, None)
             except CaptchaSolveError as e:
                 err = e
-                reason = _explain(spec.vendor, False, e)
+                reason = _explain(False, e)
             finally:
                 video_path = _finish_video(page)
     except Exception as e:
         err = e
-        reason = _explain(spec.vendor, False, e)
+        reason = _explain(False, e)
 
     tps = out / solve_s if out and solve_s > 0 else 0.0
     _report(spec, ok=ok, total_s=time.time() - t0, solve_s=solve_s,

{captchakraken-3.0.0 → captchakraken-3.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "captchakraken"
-version = "3.0.0"
+version = "3.2.0"
 description = "Captcha-solving engine and CLI: OpenCV grid detection plus a fine-tuned Qwen3.5-9B vision model, for image grids, click and drag puzzles, sliders, distorted text and animated challenges. Hosted API or self-hosted on vLLM."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -15,7 +15,7 @@ requires-python = ">=3.11"
 license = { file = "LICENSE" }
 authors = [{ name = "Jake Writer" }]
 keywords = [
-  "captcha", "captcha-solver", "recaptcha", "hcaptcha", "geetest", "turnstile",
+  "captcha", "captcha-solver", "recaptcha", "geetest", "turnstile",
   "yidun", "tencent-captcha", "playwright", "browser-automation", "scraping",
   "anti-bot", "vllm", "qwen", "computer-vision", "ocr",
 ]
@@ -92,10 +92,10 @@ captchakraken = "captchakraken.cli:main"
 
 [project.urls]
 Homepage = "https://captchakraken.com"
-Documentation = "https://github.com/JWriter20/CaptchaKraken#readme"
-Source = "https://github.com/JWriter20/CaptchaKraken"
-Issues = "https://github.com/JWriter20/CaptchaKraken/issues"
-Changelog = "https://github.com/JWriter20/CaptchaKraken/blob/main/CHANGELOG.md"
+Documentation = "https://github.com/CaptchaKraken/CaptchaKraken#readme"
+Source = "https://github.com/CaptchaKraken/CaptchaKraken"
+Issues = "https://github.com/CaptchaKraken/CaptchaKraken/issues"
+Changelog = "https://github.com/CaptchaKraken/CaptchaKraken/blob/main/CHANGELOG.md"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/captchakraken"]

{captchakraken-3.0.0 → captchakraken-3.2.0}/src/captchakraken/__init__.py

@@ -30,7 +30,9 @@ from .kinds import (
     PromptFamily,
     RetryMode,
     Vendor,
+    Verdict,
 )
+from .verdicts import RoundVerdict
 
 from .humanize import (
     AppiumTouchBackend,
@@ -96,7 +98,9 @@ __all__ = [
     "PauseKind",
     "PromptFamily",
     "RetryMode",
+    "RoundVerdict",
     "Vendor",
+    "Verdict",
 ]
 
-__version__ = "3.0.0"
+__version__ = "3.2.0"

{captchakraken-3.0.0 → captchakraken-3.2.0}/src/captchakraken/cli.py

@@ -177,7 +177,10 @@ def _report_outcome(args):
     try:
         from .planner import ActionPlanner
 
-        return {"reported": bool(ActionPlanner().report_outcome(args[0], Outcome(args[1]) == Outcome.SOLVED))}
+        planner = ActionPlanner()
+        reported = planner.report_outcome(args[0], Outcome(args[1]) == Outcome.SOLVED)
+        # `supported` false is the self-hosted 404, which tells the driver to stop spawning this.
+        return {"reported": bool(reported), "supported": planner.outcome_supported}
     except Exception as exc:
         return {"reported": False, "error": str(exc)}
 
@@ -185,6 +188,7 @@ def _report_outcome(args):
 def _serve(args):
     """Persistent CV worker: one JSON request per stdin line, one JSON reply per stdout line."""
     from .image_processor import ImageProcessor
+    from .tool_calls.find_checkbox import find_checkbox
     from .tool_calls.find_grid import find_grid
 
     def handle(req):
@@ -206,6 +210,8 @@ def _serve(args):
             return match_region(req["ref"], req["live"], float(req["cx"]), float(req["cy"]), req.get("tolerance"))
         if cmd == "board-painted":
             return board_painted(req["image"], req.get("floor"), req.get("box"))
+        if cmd == "find-checkbox":
+            return find_checkbox(req["image"])
         if cmd == "track-piece":
             return track_piece(req["before"], req["after"], req.get("exclude"), req.get("travel") or 0.0)
         raise ValueError(f"unknown cmd: {cmd!r}")

{captchakraken-3.0.0 → captchakraken-3.2.0}/src/captchakraken/kinds.py

@@ -104,6 +104,15 @@ class Outcome(StrEnum):
     FAILED = "failed"
 
 
+class Verdict(StrEnum):
+    """What the vendor's own server answered a round: BLOCKED is a refusal to serve at all, not a wrong answer."""
+
+    ACCEPTED = "accepted"
+    REJECTED = "rejected"
+    NEW_CHALLENGE = "new-challenge"
+    BLOCKED = "blocked"
+
+
 class Phase(StrEnum):
     """Timing phases. Only INFERENCE and MOUSE are productive; everything else is waiting."""