captchakraken 2.0.0__tar.gz

captchakraken-2.0.0/.gitignore

@@ -0,0 +1,44 @@
+node_modules
+dist
+*.log
+.DS_Store
+.env
+.npmrc
+test-results
+playwright-report
+debug_runs/
+test_logs/
+
+# generated by setup.sh
+captchakraken.env
+
+# python port
+python/.venv
+python/build/
+python/dist/
+**/__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# js port: the python engine is copied in at build time from the sibling
+# repo-root python/ (single source of truth) — never commit the copy.
+js/python/
+js/dist/
+js/node_modules/
+
+# test-run artifacts
+hcaptcha_5x_attempt_*.png
+hcaptcha_5x_summary.json
+captcha_video_summary.json
+server_log.txt
+
+# demo recorder (tests/record_demos.spec.ts) transients. Curated clips that the
+# README embeds live in docs/demos/ (committed); everything else is throwaway.
+record_demos_summary.json
+record_demos_*_summary.json
+record_demos*.log
+run_full_record.out
+run_full_record.sh
+*_video_attempt_*.png
+captcha_videos/

captchakraken-2.0.0/Dockerfile

@@ -0,0 +1,41 @@
+# CaptchaKraken vLLM server image.
+#
+# Serves the base model + captcha LoRA over an OpenAI-compatible endpoint on
+# :8000. The image bakes in the `captchakraken[serve]` stack and (optionally)
+# the weights, then hands off to `captchakraken server run`, which execs
+# `vllm serve` assembled entirely from the env-overridable config — so you can
+# repoint it at any base model / adapter without editing this file.
+#
+#   docker build -t captchakraken-vllm .
+#   docker run --gpus all -p 8000:8000 --ipc=host \
+#     -e VLLM_API_KEY=your_key captchakraken-vllm
+FROM pytorch/pytorch:2.7.0-cuda12.8-cudnn9-devel
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y \
+    git ninja-build libgl1 libglib2.0-0 wget ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install the package + serving extra (vllm/torch/transformers/accelerate/hf).
+COPY . /app/captchakraken
+RUN pip install --upgrade pip && pip install "/app/captchakraken[serve]"
+
+# Model identity — all overridable at build/run time (model-agnostic image).
+ARG HF_TOKEN
+ENV HF_TOKEN=${HF_TOKEN}
+ENV CAPTCHA_BASE_MODEL="Qwen/Qwen3.5-9B"
+ENV CAPTCHA_LORA_ADAPTER="CaptchaKraken/CaptchaKraken_v1"
+ENV CAPTCHA_LORA_NAME="captcha"
+ENV VLLM_GPU_MEMORY_UTILIZATION="0.80"
+ENV VLLM_PORT=8000
+
+# Bake weights into the image (best-effort; falls back to runtime download).
+RUN python3 -c "import os; from huggingface_hub import snapshot_download; \
+    token = os.getenv('HF_TOKEN'); \
+    snapshot_download(os.getenv('CAPTCHA_BASE_MODEL'), token=token); \
+    snapshot_download(os.getenv('CAPTCHA_LORA_ADAPTER'), token=token)" \
+    || echo "Warning: model prefetch failed; weights download at first run."
+
+EXPOSE 8000
+CMD ["captchakraken", "server", "run"]

captchakraken-2.0.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: captchakraken
+Version: 2.0.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.

captchakraken-2.0.0/README.md

@@ -0,0 +1,71 @@
+# 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.

captchakraken-2.0.0/examples/README.md

@@ -0,0 +1,68 @@
+# Examples (Python)
+
+Two runnable demos that drive a real stealth browser
+([camoufox](https://github.com/JWriter20/camoufox)) to a live captcha demo site,
+screenshot the challenge, run the **engine** on it, and print token speed /
+total time / outcome:
+
+| File | Site |
+|---|---|
+| `demoRecaptcha.py` | Google reCAPTCHA v2 demo |
+| `demoHcaptcha.py` | hCaptcha demo |
+
+> The Python port is the engine (detection + planner). These demos validate the
+> engine + model + server on a real challenge frame. Full click-replay and
+> multi-round verification in a live page are what the TypeScript port
+> (`captchakraken`) does end-to-end.
+
+## Setup
+
+```bash
+cd python
+pip install -e ".[serve]"         # engine + serving stack (use ".[]" for a remote server)
+pip install camoufox              # example-only dep
+```
+
+### The camoufox binary (from your fork)
+
+Uses the **camoufox binary from the fork's releases**:
+[JWriter20/camoufox → Releases](https://github.com/JWriter20/camoufox/releases).
+
+1. Download the latest release asset for your OS/arch and extract it.
+2. Point the demo at the extracted `camoufox` executable:
+
+```bash
+export CAMOUFOX_BINARY=/path/to/camoufox/camoufox      # your fork binary
+```
+
+If `CAMOUFOX_BINARY` is unset, camoufox falls back to its default binary
+(`python -m camoufox fetch`).
+
+### Point at a model
+
+```bash
+source ../captchakraken.env       # VLLM_BASE_URL + CAPTCHA_KRAKEN_API_KEY
+```
+
+## Run
+
+```bash
+python examples/demoRecaptcha.py
+python examples/demoHcaptcha.py
+HEADLESS=0 python examples/demoRecaptcha.py    # watch the browser
+```
+
+## Reading the report
+
+```
+  result        : ✓ engine produced a solution
+  click plan: 4 tile(s)/target(s)
+  total time    : 6.1s (solve: 3.4s)
+  tokens        : 812 in / 34 out
+  gen speed     : ~10.0 tok/s
+  reason        : <only on failure — unsupported puzzle, unreachable server, …>
+```
+
+`gen speed` = model output tokens ÷ solve seconds. Failure reasons the harness
+reports: unreachable vLLM server, an unsupported hCaptcha puzzle (drag/video),
+the challenge iframe never appearing, or the model returning no matching tiles.

captchakraken-2.0.0/examples/_harness.py

@@ -0,0 +1,158 @@
+"""
+Shared runner for the CaptchaKraken Python demos.
+
+The Python port is the *engine* (OpenCV detection + the vLLM planner). These demos
+launch a real stealth browser (camoufox, using the binary from your fork —
+JWriter20/camoufox releases; see README.md), navigate to a captcha demo site,
+open the challenge, screenshot it, and run the engine on that frame. They report
+token-generation speed, total time, and whether the engine produced a valid
+solution — plus a best-effort reason when it didn't.
+
+Note: full click-replay + multi-round verification in a live page is what the
+TypeScript port (`captchakraken`) does end-to-end. Here we validate the
+engine + model + server on a real challenge frame.
+"""
+
+import os
+import tempfile
+import time
+from dataclasses import dataclass
+
+from camoufox.sync_api import Camoufox
+
+from captchakraken import CaptchaSolver
+from captchakraken.action_types import ClickAction
+from captchakraken.solver import UnsupportedCaptchaError
+
+
+@dataclass
+class DemoSpec:
+    name: str
+    url: str
+    vendor: str  # "recaptcha" | "hcaptcha"
+
+
+def _launch_kwargs() -> dict:
+    kw = dict(headless=os.getenv("HEADLESS", "1") != "0", humanize=True, geoip=False)
+    # Point camoufox at YOUR fork's binary. If unset, camoufox uses its default
+    # cached binary (`python -m camoufox fetch`).
+    binary = os.getenv("CAMOUFOX_BINARY") or os.getenv("CAMOUFOX_EXECUTABLE_PATH")
+    if binary:
+        kw["executable_path"] = binary
+    return kw
+
+
+def _capture_challenge(page, spec: DemoSpec) -> str:
+    """Reach the challenge iframe and screenshot it to a temp PNG. Returns the path.
+
+    Raises RuntimeError with a human message if the challenge never appears.
+    """
+    out = tempfile.NamedTemporaryFile(suffix=".png", delete=False).name
+
+    if spec.vendor == "recaptcha":
+        anchor = page.wait_for_selector('iframe[src*="/recaptcha/api2/anchor"]', timeout=30_000)
+        frame = anchor.content_frame()
+        frame.click("#recaptcha-anchor", timeout=15_000)
+        challenge = page.wait_for_selector('iframe[src*="/recaptcha/api2/bframe"]', timeout=30_000)
+        # Let the tiles paint.
+        page.wait_for_timeout(2500)
+        challenge.screenshot(path=out)
+        return out
+
+    if spec.vendor == "hcaptcha":
+        box = page.wait_for_selector('iframe[src*="hcaptcha.com"][src*="checkbox"], iframe[title*="checkbox"]',
+                                     timeout=30_000)
+        box.content_frame().click("#checkbox, div[role=checkbox]", timeout=15_000)
+        challenge = page.wait_for_selector('iframe[title*="hCaptcha challenge"], iframe[src*="hcaptcha.com"][src*="frame=challenge"]',
+                                           timeout=30_000)
+        page.wait_for_timeout(2500)
+        challenge.screenshot(path=out)
+        return out
+
+    raise RuntimeError(f"unknown vendor {spec.vendor!r}")
+
+
+def _tokens_per_sec(solver: CaptchaSolver, elapsed_s: float) -> tuple[int, int, float]:
+    """(input_tokens, output_tokens, tokens/sec) from the planner's usage log."""
+    inp = out = 0
+    for u in getattr(solver.planner, "token_usage", []) or []:
+        inp += int(u.get("prompt_tokens", 0) or 0)
+        out += int(u.get("completion_tokens", 0) or 0)
+    tps = out / elapsed_s if out and elapsed_s > 0 else 0.0
+    return inp, out, tps
+
+
+def _explain(vendor: str, err: Exception) -> str:
+    msg = str(err).lower()
+    if isinstance(err, UnsupportedCaptchaError) or "cannot solve" in msg or "unsupported" in msg:
+        if vendor == "hcaptcha":
+            return ("hCaptcha served a non-grid challenge (drag / video / choose-the-card). "
+                    "The engine handles image grids + checkboxes only — re-run to try for a grid.")
+        return "Not a supported grid/checkbox challenge — re-run to try again."
+    if "vllm" in msg or "connection" in msg or "refused" in msg or "max retries" in msg:
+        return ("Could not reach the vLLM server — is it up and is VLLM_BASE_URL correct? "
+                "(A local server auto-starts only if captchakraken[serve] is installed.)")
+    if "timeout" in msg or "wait_for_selector" in msg:
+        return "The challenge iframe never appeared (slow network, blocked widget, or the checkbox auto-passed)."
+    return str(err) or "Unknown failure."
+
+
+def run_demo(spec: DemoSpec) -> None:
+    t0 = time.time()
+    ok = False
+    reason = None
+    inp = out = 0
+    tps = 0.0
+    solve_s = 0.0
+    plan_desc = "-"
+
+    try:
+        with Camoufox(**_launch_kwargs()) as browser:
+            page = browser.new_page()
+            page.goto(spec.url, wait_until="domcontentloaded", timeout=60_000)
+            shot = _capture_challenge(page, spec)
+
+            solver = CaptchaSolver()
+            s0 = time.time()
+            try:
+                actions = solver.solve(shot, puzzle_source=spec.vendor)
+            finally:
+                solve_s = time.time() - s0
+            inp, out, tps = _tokens_per_sec(solver, solve_s)
+
+            acts = actions if isinstance(actions, list) else [actions]
+            clicks = [a for a in acts if isinstance(a, ClickAction) and (a.target_bounding_boxes or [])]
+            n_tiles = sum(len(a.target_bounding_boxes or []) for a in clicks)
+            if n_tiles > 0:
+                ok = True
+                plan_desc = f"click plan: {n_tiles} tile(s)/target(s)"
+            else:
+                plan_desc = f"actions: {[type(a).__name__ for a in acts]}"
+                reason = ("The model returned no tiles to click — either none matched the prompt, "
+                          "or the challenge frame wasn't a clean grid. Re-run to try again.")
+    except Exception as err:  # noqa: BLE001 — demo: report, don't traceback
+        reason = _explain(spec.vendor, err)
+
+    _report(spec, ok=ok, total_s=time.time() - t0, solve_s=solve_s,
+            inp=inp, out=out, tps=tps, plan=plan_desc, reason=reason)
+
+
+def _fmt(s: float) -> str:
+    return f"{s:.1f}s" if s >= 1 else f"{int(s * 1000)}ms"
+
+
+def _report(spec, *, ok, total_s, solve_s, inp, out, tps, plan, reason):
+    line = "─" * 52
+    print(f"\n{line}")
+    print(f"  CaptchaKraken demo (engine) — {spec.name}")
+    print(f"  {spec.url}")
+    print(line)
+    print(f"  result        : {'✓ engine produced a solution' if ok else '✗ no solution'}")
+    print(f"  {plan}")
+    print(f"  total time    : {_fmt(total_s)}   (solve: {_fmt(solve_s)})")
+    print(f"  tokens        : {inp} in / {out} out")
+    print(f"  gen speed     : {f'~{tps:.1f} tok/s' if tps > 0 else 'n/a'}")
+    if reason:
+        print(f"  reason        : {reason}")
+    print(f"{line}\n")
+    raise SystemExit(0 if ok else 1)

captchakraken-2.0.0/examples/demoHcaptcha.py

@@ -0,0 +1,20 @@
+"""
+Engine demo: run CaptchaKraken on the standard hCaptcha demo page.
+
+    pip install -e ".[serve]"     # engine + serving stack (or [.] against a remote server)
+    pip install camoufox && python -m camoufox fetch   # or set CAMOUFOX_BINARY to your fork binary
+    source ../captchakraken.env    # VLLM_BASE_URL + CAPTCHA_KRAKEN_API_KEY
+    python examples/demoHcaptcha.py
+
+Note: hCaptcha randomly serves non-grid puzzles (drag / video / choose-the-card),
+which the engine does not handle yet — the report says so; re-run for a grid.
+"""
+
+from _harness import DemoSpec, run_demo
+
+if __name__ == "__main__":
+    run_demo(DemoSpec(
+        name="hCaptcha",
+        url="https://accounts.hcaptcha.com/demo",
+        vendor="hcaptcha",
+    ))

captchakraken-2.0.0/examples/demoRecaptcha.py

@@ -0,0 +1,17 @@
+"""
+Engine demo: run CaptchaKraken on Google's standard reCAPTCHA v2 demo page.
+
+    pip install -e ".[serve]"     # engine + serving stack (or [.] against a remote server)
+    pip install camoufox && python -m camoufox fetch   # or set CAMOUFOX_BINARY to your fork binary
+    source ../captchakraken.env    # VLLM_BASE_URL + CAPTCHA_KRAKEN_API_KEY
+    python examples/demoRecaptcha.py
+"""
+
+from _harness import DemoSpec, run_demo
+
+if __name__ == "__main__":
+    run_demo(DemoSpec(
+        name="reCAPTCHA v2",
+        url="https://www.google.com/recaptcha/api2/demo",
+        vendor="recaptcha",
+    ))

captchakraken-2.0.0/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "captchakraken"
+version = "2.0.0"
+description = "Self-hosted captcha solver: OpenCV grid detection + a fine-tuned Qwen3.5-9B vision LoRA served on vLLM."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "GPL-3.0-or-later" }
+authors = [{ name = "Jake Writer" }]
+keywords = ["captcha", "recaptcha", "hcaptcha", "vllm", "qwen", "computer-vision", "automation"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+# Core = the lightweight CLIENT: OpenCV grid 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.
+dependencies = [
+  "pydantic>=2.0.0",
+  "pillow>=10.0.0",
+  "numpy>=1.24.0",
+  "opencv-python-headless>=4.10.0",
+  "requests>=2.31.0",
+  "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+# Self-hosting: install this to RUN a local vLLM server (the setup script does
+# `pip install "captchakraken[serve]"`). Not needed to call a remote server.
+serve = [
+  "vllm>=0.6.3",
+  "torch>=2.0.0",
+  "transformers>=4.40.0",
+  "accelerate>=0.27.0",
+  "huggingface_hub>=0.23.0",
+]
+dev = [
+  "pytest>=7.0.0",
+  "mypy>=1.0.0",
+  "ruff>=0.1.0",
+]
+
+[project.scripts]
+captchakraken = "captchakraken.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/JWriter20/CaptchaKraken"
+Issues = "https://github.com/JWriter20/CaptchaKraken/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/captchakraken"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = false
+warn_unused_configs = true
+disallow_untyped_defs = false
+check_untyped_defs = false
+ignore_missing_imports = true
+no_implicit_optional = false
+exclude = ["build/", "dist/"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = ["E501"]

captchakraken-2.0.0/src/captchakraken/__init__.py

@@ -0,0 +1,61 @@
+"""
+CaptchaKraken — OpenCV grid detection + a fine-tuned Qwen3.5-9B vision LoRA
+served on vLLM.
+
+Usage:
+    from captchakraken import CaptchaSolver
+    solver = CaptchaSolver()   # auto-starts / connects to a local vLLM server
+    actions = solver.solve("captcha.png")
+
+Model/endpoint defaults live in `captchakraken.config` and are fully
+env-overridable (VLLM_BASE_URL, CAPTCHA_LORA_ADAPTER, …); the solver itself is
+model-agnostic. The legacy v1 stack (SAM3 grounding, multi-provider planner,
+detect/segment/drag-refine) lives on the `v1-old-architecture` branch.
+"""
+
+from pathlib import Path
+
+try:  # pragma: no cover
+    from dotenv import load_dotenv
+
+    project_root = Path(__file__).resolve().parent.parent
+    load_dotenv(project_root / ".env")
+except Exception:
+    pass
+
+from .action_types import (
+    CaptchaAction,
+    ClickAction,
+    DragAction,
+    TypeAction,
+    WaitAction,
+)
+from .image_processor import ImageProcessor
+from .overlay import add_overlays_to_image
+
+# The planner (requests) and solver (torch/vllm/transformers) pull in the heavy
+# serving stack. Keep them optional so leaf modules — e.g. tool_calls.find_grid,
+# which needs only cv2 + numpy + pillow — can be imported in a minimal env (CI's
+# hermetic grid-detection test) without the full GPU dependency set installed.
+try:  # pragma: no cover - exercised only when the serving stack is installed
+    from .planner import ActionPlanner
+    from .solver import CaptchaSolver, solve_captcha
+except ModuleNotFoundError:
+    ActionPlanner = None  # type: ignore[assignment,misc]
+    CaptchaSolver = None  # type: ignore[assignment,misc]
+    solve_captcha = None  # type: ignore[assignment]
+
+__all__ = [
+    "CaptchaSolver",
+    "solve_captcha",
+    "ActionPlanner",
+    "ImageProcessor",
+    "CaptchaAction",
+    "ClickAction",
+    "DragAction",
+    "TypeAction",
+    "WaitAction",
+    "add_overlays_to_image",
+]
+
+__version__ = "2.0.0"