Metadata-Version: 2.5
Name: captchakraken
Version: 2.8.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
Author: Jake Writer
License: CaptchaKraken Source-Available License v1.1
        Copyright (c) 2026 CaptchaKraken LLC. All rights reserved.
        
        This license governs use of the CaptchaKraken software in this repository and of
        the associated machine-learning model weights and LoRA adapters published by the
        copyright holder (collectively, the "Software"). By using the Software you agree
        to these terms. If you do not agree, do not use the Software.
        
        ================================================================================
        1. GRANT
        ================================================================================
        Subject to the restrictions below, you are granted a worldwide, royalty-free,
        non-exclusive license to use, copy, modify, and distribute the Software, and to
        incorporate it into your own products and services.
        
        ================================================================================
        2. PERMITTED USES
        ================================================================================
        You MAY use the Software for:
        
          (a) Personal, non-commercial use, research, and education.
        
          (b) Commercial use INSIDE a larger product or service that delivers
              substantial value BEYOND captcha solving itself — that is, where captcha
              solving is an internal, enabling component rather than the product.
        
          Illustrative (non-exhaustive) examples of PERMITTED commercial use:
              - Web scrapers and data-collection pipelines.
              - Browser automation you build and operate for your own purposes.
              - QA, testing, and accessibility tooling.
              - Any application where the captcha solve is a means to an end the user
                is actually paying for.
        
          (c) RUNNING the Software alongside a stealth, anti-detection, or antidetect
              browser — Camoufox, Puppeteer, Playwright, or any similar tool — to
              automate your own work, commercially or otherwise. Section 3(d) restricts
              SHIPPING the Software as a feature of such a browser to other people. It
              does not restrict USING it with one.
        
        ================================================================================
        3. PROHIBITED USES
        ================================================================================
        You MAY NOT, without a separate written commercial agreement from the copyright
        holder:
        
          (a) Sell, resell, rent, or otherwise offer for a fee any captcha-SOLVING
              service, product, or API whose primary value is solving captchas,
              where that service is powered by the Software or its model outputs.
        
          (b) Distribute "thin wrappers" around the Software whose primary purpose is
              captcha solving — including but not limited to browser extensions,
              hosted endpoints, SaaS products, or CLIs that simply expose the
              Software's solving capability to end users.
        
          (c) Expose, proxy, or relay the responses or outputs of the Software's LoRA
              models (e.g. bounding boxes, tile selections, click plans) through a paid
              or public API as a captcha-solving service.
        
          (d) Embed, bundle, preinstall, or otherwise ship the Software — or a client,
              wrapper, plugin, or extension for it — as a captcha-solving capability of
              any stealth browser, anti-detection or antidetect browser, browser
              profile or identity manager, or browser-automation product or platform
              that you distribute, host, or otherwise offer to third parties. This
              applies whether the Software ships inside your distribution, is fetched
              on demand, or is merely wired up and advertised as a supported
              integration, and it applies whether or not you charge for it.
        
              This restriction is about DISTRIBUTION, not use. Nothing in it limits
              Section 2(c): a person who uses such a browser may install and run the
              Software with it freely.
        
          In short: you may BUILD WITH this Software, and you may USE it with whatever
          browser you like — but you may not SELL THE SOLVE, and you may not SHIP THE
          SOLVE as a feature of a stealth browser or automation product you hand to
          other people.
        
        ================================================================================
        4. MODEL OUTPUTS
        ================================================================================
        Outputs produced by the model weights/adapters are subject to Sections 2 and 3
        to the same extent as the Software itself. Reselling or API-relaying those
        outputs as a captcha-solving service is prohibited under Section 3(c).
        
        ================================================================================
        5. REDISTRIBUTION
        ================================================================================
        If you redistribute the Software (modified or not), you must retain this license
        and this notice, and you must not remove or alter the restrictions in Section 3.
        The right to redistribute granted by Section 1 is subject to Section 3(d).
        
        ================================================================================
        6. TRADEMARKS
        ================================================================================
        This license does not grant permission to use the trade names, trademarks, or
        product names of the copyright holder, except as required to describe the origin
        of the Software.
        
        ================================================================================
        7. NO WARRANTY
        ================================================================================
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
        FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
        COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER
        IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN
        CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
        ================================================================================
        8. RESPONSIBLE USE
        ================================================================================
        You are responsible for ensuring your use of the Software complies with all
        applicable laws, the terms of service of any site you interact with, and
        applicable anti-fraud and computer-access statutes. The copyright holder does
        not endorse using the Software to violate any third party's terms or rights.
        
        ================================================================================
        9. COMMERCIAL LICENSING
        ================================================================================
        For uses prohibited under Section 3 — including selling captcha-solving as a
        service, and shipping the Software as a built-in capability of a stealth browser
        or automation product — contact the copyright holder to discuss a separate
        commercial license. These uses are licensable; they are not categorically
        refused.
        
        ================================================================================
        10. VERSION HISTORY
        ================================================================================
        v1.1 — Section 3(d) added: shipping the Software as a captcha-solving feature of
               a stealth/anti-detection browser or automation product distributed to
               third parties now requires a commercial license. Section 2(c) added to
               make clear that USING the Software with such a browser remains permitted.
               The v1.0 text listed "stealth / anti-detection browsers" as an
               illustrative PERMITTED commercial use; that example is removed.
        v1.0 — Initial release.
        
        Each version applies to the releases distributed under it. Copies obtained under
        v1.0 remain governed by v1.0.
        
        --------------------------------------------------------------------------------
        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
        --------------------------------------------------------------------------------
License-File: LICENSE
Keywords: anti-bot,browser-automation,captcha,captcha-solver,computer-vision,geetest,hcaptcha,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
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
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.10
Requires-Dist: numpy>=1.24.0
Requires-Dist: opencv-python-headless>=4.10.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: serve
Requires-Dist: accelerate>=0.27.0; extra == 'serve'
Requires-Dist: huggingface-hub>=0.23.0; extra == 'serve'
Requires-Dist: torch>=2.0.0; extra == 'serve'
Requires-Dist: transformers>=4.40.0; extra == 'serve'
Requires-Dist: vllm>=0.6.3; 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">
</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>.
</p>

OpenCV tile 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/JWriter20/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"
       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"
       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**
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
[captchakraken.com](https://captchakraken.com) and in the
[main repo](https://github.com/JWriter20/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 |
| **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: OpenCV 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/JWriter20/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 hcaptcha
```

```python
from captchakraken import CaptchaSolver

solver = CaptchaSolver()          # connects to / auto-starts a local vLLM
actions = solver.solve("captcha.png")
```

Pure-OpenCV tool subcommands (no model): `find-grid`, `find-checkbox`,
`detect-selected`, `grid-cell-states`, `find-move`, `find-movable`, 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_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

**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.
