captchakraken 3.2.1 → 4.0.0

package/python/README.md

@@ -9,7 +9,7 @@
   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
+CPU element detection plus a fine-tuned **Qwen3.5-9B** vision model. Give it a
 screenshot of a captcha and it returns the plan to solve it — which tiles to
 select, where to click, what to drag, how far to slide, or what text to type.
 Ships the `captchakraken` command.
@@ -57,7 +57,7 @@ keyframes and answered with the frame the action belongs to.
 ## Install
 
 ```bash
-pip install captchakraken            # client: OpenCV detection + vLLM HTTP planner
+pip install captchakraken            # client: CPU element detection + vLLM HTTP planner
 pip install "captchakraken[serve]"   # + the serving stack (vLLM/torch) to self-host
 ```
 
@@ -107,7 +107,7 @@ solver = CaptchaSolver()          # connects to / auto-starts a local vLLM
 actions = solver.solve("captcha.png")
 ```
 
-Pure-OpenCV tool subcommands (no model): `find-grid`, `find-checkbox`,
+Element-detector tool subcommands (CPU only, no planner model): `find-grid`, `find-checkbox`,
 `detect-selected`, `grid-cell-states`, and a persistent `serve` worker the browser driver polls.
 
 ## Configuration (model-agnostic)
@@ -123,6 +123,9 @@ Everything model-specific lives in `captchakraken.config` and is env-overridable
 | `CAPTCHA_LORA_ADAPTER` | Captcha adapter (HF id or path) | `CaptchaKraken/CaptchaKraken-Lora-v1.2` |
 | `CAPTCHA_LORA_NAME` | Served adapter name the client requests | `captcha-v12` |
 | `CAPTCHA_KRAKEN_AUTOSTART` | `0` disables local auto-start | `1` |
+| `CAPTCHA_KRAKEN_DETECTOR` | A local element-detector `.onnx` to run instead of downloading the released one | the released weights, fetched once |
+| `CAPTCHA_KRAKEN_DETECTOR_MODEL` | Which released detector runs: `lite` (MobileNetV3, about 100 ms a board on one vCPU), `standard` (ResNet-18), or `auto`; overrides `detector` in `captchakraken.config.json` | the config's `detector`, shipped as `auto`: `lite` on two usable CPUs or fewer (a container's CPU quota included), else one board is timed and `standard` runs when it fits in 200 ms |
+| `HF_TOKEN` | A Hugging Face token, sent only when downloading the detector weights from a private copy of their repo | unset: the download sends no credential |
 | `CAPTCHA_HUMANIZATION` | How gestures are performed: `mouse`, `mobile` or `none` | `mouse` |
 
 **How it moves** is a choice of input device, not a realism dial. `mobile`
@@ -149,9 +152,7 @@ PageSolver(config=PageSolverConfig(
 
 ## License
 
-**CaptchaKraken Source-Available License v1.1** — see [LICENSE](./LICENSE).
-Build *with* it (scrapers, QA tooling) and run it against **any** browser you
-like, stealth or not. You may **not sell the solve itself**, ship a thin wrapper
-(browser extension, hosted solving API), or **bundle it as a built-in feature of
-a stealth/antidetect browser you distribute** — using it with one is fine. Those
-three are licensable, not categorically refused: open an issue to ask.
+**LGPL-3.0-only** — see [LICENSE](./LICENSE). Use, modify and redistribute it,
+including in commercial and hosted services. If you distribute a modified
+version, keep the licence and copyright notices and make your changes available
+under LGPLv3.

package/python/pyproject.toml

@@ -4,14 +4,10 @@ build-backend = "hatchling.build"
 
 [project]
 name = "captchakraken"
-version = "3.2.1"
-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."
+version = "4.0.0"
+description = "Captcha-solving engine and CLI: a v2 pointer model and CNN element detector 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"
-# Source-available, NOT GPL. The CaptchaKraken Source-Available License permits
-# commercial use as an internal component but prohibits selling the solve itself,
-# thin-wrapper resale, and bundling it into a stealth browser someone else ships
-# — see LICENSE. (GPL-3.0 would wrongly permit all three.)
 license = { file = "LICENSE" }
 authors = [{ name = "Jake Writer" }]
 keywords = [
@@ -31,11 +27,11 @@ classifiers = [
   "Topic :: Scientific/Engineering :: Image Recognition",
   "Topic :: Internet :: WWW/HTTP :: Browsers",
   "Topic :: Software Development :: Testing",
-  "License :: Other/Proprietary License",
+  "License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)",
   "Typing :: Typed",
 ]
 
-# Core = the lightweight CLIENT: OpenCV grid detection + the HTTP planner that
+# Core = the lightweight CLIENT: CPU element 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.
@@ -53,19 +49,31 @@ classifiers = [
 # against the floor before changing any of these, and see TRIBAL_KNOWLEDGE.md.
 dependencies = [
   "pydantic==2.13.5",
-  "pillow==12.3.0",
+  "pillow==13.0.0",
   # 2.3.x rather than 2.2.6 because `cursory` requires `numpy~=2.3.3` and the
-  # old pin was ours, not opencv's — opencv-python-headless asks only for
-  # `numpy>=2`. Moved deliberately as part of the major bump.
+  # old pin was ours. Moved deliberately as part of the major bump.
   "numpy==2.3.5",
-  "opencv-python-headless==5.0.0.93",
+  # Runs the element detector (find_grid, find_checkbox) on the CPU. Its
+  # wheels cover CPython 3.11-3.14 on Linux x86_64/aarch64, Windows and Apple
+  # silicon macOS; there is NO Intel-macOS wheel, so the client does not
+  # install there. Weights are fetched at first use, not shipped (detector.py).
+  "onnxruntime==1.31.1",
+  # The slide and hold trackers' image arithmetic: smoothing, morphology,
+  # labelling, distance transforms and FFT correlation. 1.17.1 is the newest
+  # release whose Requires-Python (>=3.11) covers the floor; 1.18 needs 3.12.
+  "scipy==1.17.1",
+  # Decodes the first frame of a video passed to `solve` (.mp4, .avi, .webm).
+  # 18.1.0 is the newest release whose wheels (cp311-abi3) install on the
+  # 3.11 floor; 19.x declares `Requires-Python >=3.12`. It has no runtime
+  # dependencies, so it does not constrain numpy.
+  "av==18.1.0",
   "requests==2.34.2",
   "python-dotenv==1.2.3",
   # The mouse. LGPL-3.0-or-later, used as an ordinary installed dependency and
   # never vendored or bundled, which is the arrangement the licence is written
   # for — see NOTICE. Its TypeScript port `cursory-js` is the JS driver's
   # dependency, and the two agree bit for bit on a seed.
-  "cursory==2.0.0",
+  "cursory==2.1.0",
 ]
 
 [project.optional-dependencies]
@@ -90,6 +98,12 @@ dev = [
 [project.scripts]
 captchakraken = "captchakraken.cli:main"
 
+# vLLM loads general plugins in every process it starts (the API server and each
+# engine core), so the pointer model's architecture is known wherever a
+# checkpoint naming it is loaded. Inert unless vLLM is installed (`serve` extra).
+[project.entry-points."vllm.general_plugins"]
+captchakraken_pointer = "captchakraken.pointer.vllm_plugin:register"
+
 [project.urls]
 Homepage = "https://captchakraken.com"
 Documentation = "https://github.com/CaptchaKraken/CaptchaKraken#readme"

package/python/src/captchakraken/__init__.py

@@ -1,3 +1,6 @@
+"""The published surface: what a caller constructs, configures, receives or implements. Everything else is internal
+and can change in any release; add a name here only when a caller needs to write it."""
+
 from pathlib import Path
 
 try:
@@ -15,16 +18,18 @@ from .action_types import (
     TypeAction,
     WaitAction,
 )
-from .image_processor import ImageProcessor
-from .overlay import add_overlays_to_image
-
 from .errors import CaptchaKrakenAPIError
+from .humanize import (
+    Humanizer,
+    MobileHumanizer,
+    MouseHumanizer,
+    NullHumanizer,
+    TouchBackend,
+)
 from .kinds import (
     ActionKind,
-    Availability,
     ErrorCode,
     HumanizationMode,
-    KeyframeMode,
     Outcome,
     PauseKind,
     PromptFamily,
@@ -34,73 +39,65 @@ from .kinds import (
 )
 from .verdicts import RoundVerdict
 
-from .humanize import (
-    AppiumTouchBackend,
-    CdpTouchBackend,
-    Humanizer,
-    MobileHumanizer,
-    MouseHumanizer,
-    NullHumanizer,
-    TouchBackend,
-    TouchscreenTouchBackend,
-)
-
 try:
-    from .planner import ActionPlanner
     from .solver import CaptchaSolver, solve_captcha
 
-    from .page_solver import PageSolver, SolveResult, solve_captcha_on_page
-    from .selectors import SELECTORS, VendorSelectors
+    from .page_solver import CaptchaSolveError, PageSolver, PageSolverConfig, SolveResult, solve_captcha_on_page
+    from .selectors import DEFAULT_CONFIG_PATH, SelectorConfigError, VendorSelectors, load_config
     from .watcher import CaptchaWatcher
 except ModuleNotFoundError:
-    ActionPlanner = None
     CaptchaSolver = None
     solve_captcha = None
+    CaptchaSolveError = None
     PageSolver = None
-    SELECTORS = None
-    VendorSelectors = None
-    CaptchaWatcher = None
+    PageSolverConfig = None
     SolveResult = None
     solve_captcha_on_page = None
+    VendorSelectors = None
+    DEFAULT_CONFIG_PATH = None
+    SelectorConfigError = None
+    load_config = None
+    CaptchaWatcher = None
 
 __all__ = [
-    "CaptchaSolver",
-    "solve_captcha",
+    # Solving a page
     "PageSolver",
-    "SELECTORS",
-    "VendorSelectors",
-    "CaptchaWatcher",
+    "PageSolverConfig",
     "SolveResult",
+    "CaptchaSolveError",
     "solve_captcha_on_page",
-    "ActionPlanner",
-    "ImageProcessor",
+    "CaptchaWatcher",
+    # Solving an image
+    "CaptchaSolver",
+    "solve_captcha",
     "CaptchaAction",
     "ClickAction",
     "DragAction",
     "TypeAction",
     "WaitAction",
-    "add_overlays_to_image",
+    "ActionKind",
+    "RetryMode",
+    "PromptFamily",
+    # Configuration
+    "DEFAULT_CONFIG_PATH",
+    "SelectorConfigError",
+    "VendorSelectors",
+    "load_config",
+    "Vendor",
+    "HumanizationMode",
+    # Results and errors
+    "RoundVerdict",
+    "Outcome",
+    "Verdict",
+    "ErrorCode",
     "CaptchaKrakenAPIError",
+    # Humanizers: the built-in three, and what one of your own implements
     "Humanizer",
     "MouseHumanizer",
     "MobileHumanizer",
     "NullHumanizer",
     "TouchBackend",
-    "CdpTouchBackend",
-    "AppiumTouchBackend",
-    "TouchscreenTouchBackend",
-    "ActionKind",
-    "Availability",
-    "ErrorCode",
-    "HumanizationMode",
-    "KeyframeMode",
-    "Outcome",
     "PauseKind",
-    "PromptFamily",
-    "RetryMode",
-    "RoundVerdict",
-    "Vendor",
-    "Verdict",
 ]
 
-__version__ = "3.2.1"
+__version__ = "4.0.0"

package/python/src/captchakraken/action_types.py

@@ -22,6 +22,8 @@ class Action(BaseModel):
     action: ActionKind
     await_keyframe: Optional[str] = None
     frame: Optional[int] = None
+    # Seconds into the clip, on prompt generations that watch an animation as video; `frame` on earlier ones.
+    t: Optional[float] = None
 
 
 class ClickAction(Action):
@@ -52,4 +54,33 @@ class DoneAction(Action):
     action: Literal[ActionKind.DONE]
 
 
-CaptchaAction = Union[ClickAction, DragAction, TypeAction, WaitAction, DoneAction]
+class HoldAction(Action):
+    """Press on the box and keep pressing until the widget completes (prompt generation 3). When the model also named
+    where the fill starts and where to let go, the driver follows the fill along that line and releases at its end."""
+
+    action: Literal[ActionKind.HOLD]
+    target_bounding_box: BoundingBox
+    fill_from_bounding_box: Optional[BoundingBox] = None
+    fill_to_bounding_box: Optional[BoundingBox] = None
+
+
+class RefreshAction(Action):
+    """Load a new puzzle instead of solving this one (prompt generation 3). The box is the model's point on the
+    control, or None when it saw none; the driver presses the vendor's own control first either way."""
+
+    action: Literal[ActionKind.REFRESH]
+    target_bounding_box: Optional[BoundingBox] = None
+
+
+class SlideAction(Action):
+    """Press the handle and move it until the point on the part it moves reaches the target (prompt generation 3).
+    The driver tracks that part on screen and steers; nothing about the widget is read from its DOM."""
+
+    action: Literal[ActionKind.SLIDE]
+    handle_bounding_box: BoundingBox
+    source_bounding_box: BoundingBox
+    target_bounding_box: BoundingBox
+
+
+CaptchaAction = Union[ClickAction, DragAction, TypeAction, WaitAction, DoneAction, HoldAction, RefreshAction,
+                      SlideAction]