Metadata-Version: 2.4
Name: captchakraken
Version: 2.2.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: GPL-3.0-or-later
Keywords: automation,captcha,computer-vision,hcaptcha,qwen,recaptcha,vllm
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

GPL-3.0-or-later.
