Metadata-Version: 2.4
Name: captchakraken
Version: 2.4.0
Summary: Self-hosted captcha solver: OpenCV grid detection + a fine-tuned Qwen3.5-9B vision LoRA served on vLLM.
Project-URL: Homepage, https://github.com/JWriter20/CaptchaKraken
Project-URL: Issues, https://github.com/JWriter20/CaptchaKraken/issues
Author: Jake Writer
License: CaptchaKraken Source-Available License v1.0
        Copyright (c) 2026 JobHarvest / JWriter20. 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.
              - Stealth / anti-detection browsers and browser automation frameworks
                that use the Software as one internal capability.
              - QA, testing, and accessibility tooling.
              - Any application where the captcha solve is a means to an end the user
                is actually paying for.
        
        ================================================================================
        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.
        
          In short: you may BUILD WITH this Software, but you may not SELL THE SOLVE.
        
        ================================================================================
        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.
        
        ================================================================================
        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 — contact the copyright holder to discuss a separate commercial license.
        
        --------------------------------------------------------------------------------
        This text is a license, not legal advice. If the boundary between a permitted
        "value-add" product and a prohibited "thin wrapper" 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: automation,captcha,computer-vision,hcaptcha,qwen,recaptcha,vllm
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
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

# captchakraken

The Python engine + CLI behind [CaptchaKraken](https://github.com/JWriter20/CaptchaKraken):
OpenCV grid detection + a fine-tuned **Qwen3.5-9B** vision LoRA served on
**vLLM**. Given a screenshot of a captcha grid, it locates the tiles and returns
the click plan. Ships the `captchakraken` command.

> For demo videos, accuracy numbers, the browser driver, and the full
> self-hosting guide, see the main repo
> **[CaptchaKraken](https://github.com/JWriter20/CaptchaKraken)**.

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

## 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 | `http://localhost:8000/v1` |
| `CAPTCHA_KRAKEN_API_KEY` | Bearer token (`VLLM_API_KEY` also accepted) | `EMPTY` |
| `CAPTCHA_BASE_MODEL` | Base weights vLLM loads | `Qwen/Qwen3.5-9B` |
| `CAPTCHA_LORA_ADAPTER` | Captcha adapter (HF id or path) | `CaptchaKraken/CaptchaKraken_v1` |
| `CAPTCHA_LORA_NAME` | Served adapter name the client requests | `captcha` |
| `CAPTCHA_KRAKEN_AUTOSTART` | `0` disables local auto-start | `1` |

## License

**CaptchaKraken Source-Available License v1.0** — see [LICENSE](./LICENSE).
Build *with* it (scrapers, stealth browsers, QA tooling); you may **not sell the
solve itself** or ship a thin wrapper (browser extension, hosted solving API).
