captchakraken 3.2.0__tar.gz → 4.0.0__tar.gz

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

@@ -1,6 +1,6 @@
 # captchakraken (PyPI)
 
-The Python **engine and CLI**: OpenCV grid detection plus a planner that asks a
+The Python **engine and CLI**: CPU element detection plus a planner that asks a
 fine-tuned vision model what to do, and a page driver that performs it in a
 Playwright browser.
 
@@ -64,7 +64,7 @@ captchakraken path/to/captcha.png    # prints a JSON click plan
 
 Other CLI modes, all printing JSON: `captchakraken server start|stop|status|run`
 manages a local vLLM server, `captchakraken fetch` updates weights and the
-serving stack together, and the OpenCV tool calls (`find-grid`, `find-checkbox`,
+serving stack together, and the detector tool calls (`find-grid`, `find-checkbox`,
 `get-numbered-grid`, `detect-selected`, …) are exposed one per subcommand. The
 module docstring of `captchakraken/cli.py` lists every mode with its arguments.
 
@@ -111,15 +111,11 @@ generation and the weights drift apart.
 - **Never print an API key** into a transcript, a log, or a commit. Use
   `create_api_key`, which writes it to disk instead. `captchakraken.env` and
   `.env` hold keys and are never committed.
-- **Abyss is what our hosted API serves, and it is never downloadable.** The
-  current client names an Abyss expert on every request to our endpoint and is
-  answered by Abyss; an older client, or a request that names no model, gets
-  Twilight v1.2, because its prompts belong to that generation. Nothing about it
-  is gated on the account. Do not suggest weights, a download or a workaround
-  for it, and do not quote accuracy figures for it — none are published. Verify
-  what is serving with `GET /v1/models`.
-- **Respect the licence.** Building automation with this is fine; selling the
-  solve, or shipping it inside a browser or automation product, is not. See
+- **Midnight V2 4B Q4 is the default self-hosted and hosted model.** The v2
+  weights are downloadable under LGPL-3.0-only. Older clients keep using their
+  registered chat-completion model because the protocols are not interchangeable.
+- **Respect the licence.** CaptchaKraken and all its models are LGPL-3.0-only;
+  commercial use and integration are permitted under those terms. See
   [LICENSE](./LICENSE) and
   [docs/licensing.md](https://github.com/CaptchaKraken/CaptchaKraken/blob/main/docs/licensing.md).
 - **Changing this package's own code?** Its rules are in

captchakraken-4.0.0/LICENSE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

{captchakraken-3.2.0 → captchakraken-4.0.0}/NOTICE

@@ -1,10 +1,10 @@
 CaptchaKraken
-Copyright (c) 2026 CaptchaKraken LLC. All rights reserved.
+Copyright (c) 2026 CaptchaKraken LLC.
 
 This product includes third-party software. The notices below are required by
-those components' licences and do not change the terms of the CaptchaKraken
-Source-Available License, which governs everything in this repository that is
-not listed here.
+those components' licences and do not change the terms of the GNU Lesser
+General Public License, version 3 only (LGPL-3.0-only), which governs
+everything in this repository that is not listed here.
 
 ────────────────────────────────────────────────────────────────────────────
 Cursory  —  mouse trajectory generation

captchakraken-4.0.0/PKG-INFO

@@ -0,0 +1,372 @@
+Metadata-Version: 2.5
+Name: captchakraken
+Version: 4.0.0
+Summary: 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.
+Project-URL: Homepage, https://captchakraken.com
+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:                    GNU LESSER GENERAL PUBLIC LICENSE
+                               Version 3, 29 June 2007
+        
+         Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+         Everyone is permitted to copy and distribute verbatim copies
+         of this license document, but changing it is not allowed.
+        
+        
+          This version of the GNU Lesser General Public License incorporates
+        the terms and conditions of version 3 of the GNU General Public
+        License, supplemented by the additional permissions listed below.
+        
+          0. Additional Definitions.
+        
+          As used herein, "this License" refers to version 3 of the GNU Lesser
+        General Public License, and the "GNU GPL" refers to version 3 of the GNU
+        General Public License.
+        
+          "The Library" refers to a covered work governed by this License,
+        other than an Application or a Combined Work as defined below.
+        
+          An "Application" is any work that makes use of an interface provided
+        by the Library, but which is not otherwise based on the Library.
+        Defining a subclass of a class defined by the Library is deemed a mode
+        of using an interface provided by the Library.
+        
+          A "Combined Work" is a work produced by combining or linking an
+        Application with the Library.  The particular version of the Library
+        with which the Combined Work was made is also called the "Linked
+        Version".
+        
+          The "Minimal Corresponding Source" for a Combined Work means the
+        Corresponding Source for the Combined Work, excluding any source code
+        for portions of the Combined Work that, considered in isolation, are
+        based on the Application, and not on the Linked Version.
+        
+          The "Corresponding Application Code" for a Combined Work means the
+        object code and/or source code for the Application, including any data
+        and utility programs needed for reproducing the Combined Work from the
+        Application, but excluding the System Libraries of the Combined Work.
+        
+          1. Exception to Section 3 of the GNU GPL.
+        
+          You may convey a covered work under sections 3 and 4 of this License
+        without being bound by section 3 of the GNU GPL.
+        
+          2. Conveying Modified Versions.
+        
+          If you modify a copy of the Library, and, in your modifications, a
+        facility refers to a function or data to be supplied by an Application
+        that uses the facility (other than as an argument passed when the
+        facility is invoked), then you may convey a copy of the modified
+        version:
+        
+           a) under this License, provided that you make a good faith effort to
+           ensure that, in the event an Application does not supply the
+           function or data, the facility still operates, and performs
+           whatever part of its purpose remains meaningful, or
+        
+           b) under the GNU GPL, with none of the additional permissions of
+           this License applicable to that copy.
+        
+          3. Object Code Incorporating Material from Library Header Files.
+        
+          The object code form of an Application may incorporate material from
+        a header file that is part of the Library.  You may convey such object
+        code under terms of your choice, provided that, if the incorporated
+        material is not limited to numerical parameters, data structure
+        layouts and accessors, or small macros, inline functions and templates
+        (ten or fewer lines in length), you do both of the following:
+        
+           a) Give prominent notice with each copy of the object code that the
+           Library is used in it and that the Library and its use are
+           covered by this License.
+        
+           b) Accompany the object code with a copy of the GNU GPL and this license
+           document.
+        
+          4. Combined Works.
+        
+          You may convey a Combined Work under terms of your choice that,
+        taken together, effectively do not restrict modification of the
+        portions of the Library contained in the Combined Work and reverse
+        engineering for debugging such modifications, if you also do each of
+        the following:
+        
+           a) Give prominent notice with each copy of the Combined Work that
+           the Library is used in it and that the Library and its use are
+           covered by this License.
+        
+           b) Accompany the Combined Work with a copy of the GNU GPL and this license
+           document.
+        
+           c) For a Combined Work that displays copyright notices during
+           execution, include the copyright notice for the Library among
+           these notices, as well as a reference directing the user to the
+           copies of the GNU GPL and this license document.
+        
+           d) Do one of the following:
+        
+               0) Convey the Minimal Corresponding Source under the terms of this
+               License, and the Corresponding Application Code in a form
+               suitable for, and under terms that permit, the user to
+               recombine or relink the Application with a modified version of
+               the Linked Version to produce a modified Combined Work, in the
+               manner specified by section 6 of the GNU GPL for conveying
+               Corresponding Source.
+        
+               1) Use a suitable shared library mechanism for linking with the
+               Library.  A suitable mechanism is one that (a) uses at run time
+               a copy of the Library already present on the user's computer
+               system, and (b) will operate properly with a modified version
+               of the Library that is interface-compatible with the Linked
+               Version.
+        
+           e) Provide Installation Information, but only if you would otherwise
+           be required to provide such information under section 6 of the
+           GNU GPL, and only to the extent that such information is
+           necessary to install and execute a modified version of the
+           Combined Work produced by recombining or relinking the
+           Application with a modified version of the Linked Version. (If
+           you use option 4d0, the Installation Information must accompany
+           the Minimal Corresponding Source and Corresponding Application
+           Code. If you use option 4d1, you must provide the Installation
+           Information in the manner specified by section 6 of the GNU GPL
+           for conveying Corresponding Source.)
+        
+          5. Combined Libraries.
+        
+          You may place library facilities that are a work based on the
+        Library side by side in a single library together with other library
+        facilities that are not Applications and are not covered by this
+        License, and convey such a combined library under terms of your
+        choice, if you do both of the following:
+        
+           a) Accompany the combined library with a copy of the same work based
+           on the Library, uncombined with any other library facilities,
+           conveyed under the terms of this License.
+        
+           b) Give prominent notice with the combined library that part of it
+           is a work based on the Library, and explaining where to find the
+           accompanying uncombined form of the same work.
+        
+          6. Revised Versions of the GNU Lesser General Public License.
+        
+          The Free Software Foundation may publish revised and/or new versions
+        of the GNU Lesser General Public License from time to time. Such new
+        versions will be similar in spirit to the present version, but may
+        differ in detail to address new problems or concerns.
+        
+          Each version is given a distinguishing version number. If the
+        Library as you received it specifies that a certain numbered version
+        of the GNU Lesser General Public License "or any later version"
+        applies to it, you have the option of following the terms and
+        conditions either of that published version or of any later version
+        published by the Free Software Foundation. If the Library as you
+        received it does not specify a version number of the GNU Lesser
+        General Public License, you may choose any version of the GNU Lesser
+        General Public License ever published by the Free Software Foundation.
+        
+          If the Library as you received it specifies that a proxy can decide
+        whether future versions of the GNU Lesser General Public License shall
+        apply, that proxy's public statement of acceptance of any version is
+        permanent authorization for you to choose that version for the
+        Library.
+License-File: LICENSE
+License-File: NOTICE
+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 :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
+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 :: Browsers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: av==18.1.0
+Requires-Dist: cursory==2.1.0
+Requires-Dist: numpy==2.3.5
+Requires-Dist: onnxruntime==1.31.1
+Requires-Dist: pillow==13.0.0
+Requires-Dist: pydantic==2.13.5
+Requires-Dist: python-dotenv==1.2.3
+Requires-Dist: requests==2.34.2
+Requires-Dist: scipy==1.17.1
+Provides-Extra: dev
+Requires-Dist: mypy==2.3.1; extra == 'dev'
+Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
+Requires-Dist: pytest==9.1.1; extra == 'dev'
+Requires-Dist: ruff==0.16.6; extra == 'dev'
+Provides-Extra: serve
+Requires-Dist: accelerate==1.15.0; extra == 'serve'
+Requires-Dist: huggingface-hub==1.30.0; extra == 'serve'
+Requires-Dist: torch==2.13.0; extra == 'serve'
+Requires-Dist: transformers==5.17.0; extra == 'serve'
+Requires-Dist: vllm==0.29.0; extra == 'serve'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <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/CaptchaKraken/CaptchaKraken">CaptchaKraken</a>.
+</p>
+
+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.
+
+Run the model on **your own hardware**, or point it at the **hosted API** and run
+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/CaptchaKraken/CaptchaKraken)**.
+
+## Watch it work
+
+<p align="center">
+  <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/CaptchaKraken/CaptchaKraken/main/docs/assets/demo/geetest_slide.webp" width="260"
+       alt="A live GeeTest slide jigsaw challenge being solved end to end">
+</p>
+
+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.
+
+**More puzzle types**, as video and with the full method, at
+[captchakraken.com](https://captchakraken.com) and in the
+[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 |
+| **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 |
+| **BotDetect, MTCaptcha, Yandex** | Distorted text — read and typed, not clicked |
+| **Cloudflare Turnstile** | Via the checkbox flow (free on the hosted API) |
+
+**44 puzzle types**, driven end to end in CI against generated fixtures on both
+the TypeScript and Python ports. Animated challenges are recorded, sliced into
+keyframes and answered with the frame the action belongs to.
+
+## Install
+
+```bash
+pip install captchakraken            # client: CPU element detection + vLLM HTTP planner
+pip install "captchakraken[serve]"   # + the serving stack (vLLM/torch) to self-host
+```
+
+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/CaptchaKraken/CaptchaKraken) installs `[serve]`,
+downloads the weights, and writes an env file for you.
+
+## No GPU? Use the hosted API
+
+Point the client at `https://api.captchakraken.com/v1` and run no model at all.
+Sign in at [captchakraken.com/signin](https://captchakraken.com/signin) for a
+`ck_live_…` key, or let the MCP server write one for you:
+
+```bash
+claude mcp add captchakraken -- npx -y captchakraken-mcp
+# then call sign_in, then create_api_key
+```
+
+`create_api_key` writes the key and the endpoint to `~/.captchakraken/credentials`,
+which the client reads on its own — **no environment variables needed**.
+
+## Hands-off server
+
+The vLLM server is managed for you. On your first solve, if the configured
+endpoint is **local** and nothing is listening, a server is started
+automatically and reused. Point `VLLM_BASE_URL` at a server you already run to
+skip local management entirely.
+
+```bash
+captchakraken server start | stop | status | run
+```
+
+## Usage
+
+```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 recaptcha
+```
+
+```python
+from captchakraken import CaptchaSolver
+
+solver = CaptchaSolver()          # connects to / auto-starts a local vLLM
+actions = solver.solve("captcha.png")
+```
+
+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)
+
+Everything model-specific lives in `captchakraken.config` and is env-overridable
+— the solver never hard-codes a model.
+
+| Variable | Meaning | Default |
+|---|---|---|
+| `VLLM_BASE_URL` | Inference endpoint | `~/.captchakraken/credentials`, else `http://localhost:8000/v1` |
+| `CAPTCHA_KRAKEN_API_KEY` | Bearer token (`VLLM_API_KEY` also accepted) | `~/.captchakraken/credentials`, else `EMPTY` |
+| `CAPTCHA_BASE_MODEL` | Base weights vLLM loads | `RedHatAI/Qwen3.5-9B-FP8-dynamic` |
+| `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`
+dispatches real touch events with finger kinematics and never touches
+`page.mouse`; `none` goes straight to the DOM effect. Set it in code (which wins
+over the env var, because the right mode is a property of the page you are
+driving), and pass your own object to override ours entirely:
+
+```python
+from captchakraken import PageSolver
+from captchakraken.page_solver import PageSolverConfig
+
+PageSolver(config=PageSolverConfig(humanization="mobile"))
+PageSolver(config=PageSolverConfig(humanization="none"))
+PageSolver(config=PageSolverConfig(humanizer=my_own))
+
+# A real handset over Appium / Selenium — W3C touch pointer actions.
+PageSolver(config=PageSolverConfig(
+    humanization="mobile",
+    touch_driver=driver,
+    touch_transform={"scale": 3.0, "origin": (0, 132)},   # CSS px -> screen px
+))
+```
+
+## License
+
+**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.

{captchakraken-3.2.0 → captchakraken-4.0.0}/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.