captchakraken 2.1.0

package/dist/token-usage.d.ts

@@ -0,0 +1,15 @@
+import { TokenUsage } from './types';
+export interface ModelPricing {
+    inputPricePerM: number;
+    outputPricePerM: number;
+    cachedInputPricePerM: number;
+}
+export declare const PRICING: Record<string, ModelPricing>;
+export declare function estimateCost(usage: TokenUsage): number;
+export declare function aggregateTokenUsage(usages: TokenUsage[]): {
+    modelName: string;
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens: number;
+    estimatedCost: number;
+};

package/dist/token-usage.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRICING = void 0;
+exports.estimateCost = estimateCost;
+exports.aggregateTokenUsage = aggregateTokenUsage;
+exports.PRICING = {
+    'gemini-3-pro-preview': {
+        inputPricePerM: 2.00,
+        outputPricePerM: 12.00,
+        cachedInputPricePerM: 0.20,
+    },
+    'gemini-3-flash-preview': {
+        inputPricePerM: 0.50,
+        outputPricePerM: 3.00,
+        cachedInputPricePerM: 0.05,
+    },
+    'gemini-2.5-pro': {
+        inputPricePerM: 1.25,
+        outputPricePerM: 10.00,
+        cachedInputPricePerM: 0.125,
+    },
+    'gemini-2.5-flash': {
+        inputPricePerM: 0.30,
+        outputPricePerM: 2.50,
+        cachedInputPricePerM: 0.03,
+    },
+    'gemini-2.5-flash-preview': {
+        inputPricePerM: 0.30,
+        outputPricePerM: 2.50,
+        cachedInputPricePerM: 0.03,
+    },
+    'gemini-2.5-flash-lite': {
+        inputPricePerM: 0.10,
+        outputPricePerM: 0.40,
+        cachedInputPricePerM: 0.01,
+    },
+    'gemini-2.5-flash-lite-preview': {
+        inputPricePerM: 0.10,
+        outputPricePerM: 0.40,
+        cachedInputPricePerM: 0.01,
+    },
+    'gemini-2.0-flash': {
+        inputPricePerM: 0.10,
+        outputPricePerM: 0.40,
+        cachedInputPricePerM: 0.025,
+    },
+    'gemini-2.5-computer-use-preview-10-2025': {
+        inputPricePerM: 1.25,
+        outputPricePerM: 10.00,
+        cachedInputPricePerM: 0.025,
+    }
+};
+// The CaptchaKraken CLI (vLLM/OpenAI shape) emits `prompt_tokens` /
+// `completion_tokens`, while older Gemini-path usages used `input_tokens` /
+// `output_tokens`. Normalize both so aggregation never produces NaN.
+function inTok(u) {
+    return (u.input_tokens ?? u.prompt_tokens ?? 0);
+}
+function outTok(u) {
+    return (u.output_tokens ?? u.completion_tokens ?? 0);
+}
+function cachedTok(u) {
+    return (u.cached_input_tokens ?? u.prompt_tokens_details?.cached_tokens ?? 0);
+}
+function estimateCost(usage) {
+    const model = usage.model;
+    // Default to gemini-2.5-flash pricing if unknown
+    const pricing = exports.PRICING[model] || exports.PRICING['gemini-2.5-flash'];
+    const inputCost = (inTok(usage) / 1000000) * pricing.inputPricePerM;
+    const outputCost = (outTok(usage) / 1000000) * pricing.outputPricePerM;
+    const cachedCost = (cachedTok(usage) / 1000000) * pricing.cachedInputPricePerM;
+    return inputCost + outputCost + cachedCost;
+}
+function aggregateTokenUsage(usages) {
+    if (usages.length === 0) {
+        return {
+            modelName: 'none',
+            inputTokens: 0,
+            outputTokens: 0,
+            cachedInputTokens: 0,
+            estimatedCost: 0,
+        };
+    }
+    const modelName = usages[0].model;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cachedInputTokens = 0;
+    let estimatedCost = 0;
+    for (const usage of usages) {
+        inputTokens += inTok(usage);
+        outputTokens += outTok(usage);
+        cachedInputTokens += cachedTok(usage);
+        estimatedCost += estimateCost(usage);
+    }
+    return {
+        modelName,
+        inputTokens,
+        outputTokens,
+        cachedInputTokens,
+        estimatedCost,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,248 @@
+/**
+ * Lifecycle event emitted by {@link CaptchaKrakenConfig.onStep}. One is fired
+ * before any interaction (`stage: 'initial'`) and one after every executed
+ * action (click batch, drag, wait, submit) plus per dynamic-grid round, so a
+ * caller can record the exact sequence of intermediate stages, time them, and
+ * count steps without scraping CAPTCHA_DEBUG dumps.
+ */
+export interface SolveStepEvent {
+    /** 1-based monotonically increasing step index across the whole solve. */
+    index: number;
+    /**
+     * Coarse stage kind:
+     *  - `initial`  : screenshot taken before any action (baseline)
+     *  - `click`    : after a click (or batch of clicks) was executed
+     *  - `drag`     : after a drag was executed
+     *  - `wait`     : after a CLI-requested wait elapsed
+     *  - `submit`   : after the Verify/Next/Submit button was clicked
+     *  - `round`    : a dynamic reCAPTCHA 3x3 round boundary (pre-solve snapshot)
+     */
+    stage: 'initial' | 'click' | 'drag' | 'wait' | 'submit' | 'round';
+    /** Short human label, e.g. "round-2:clicked 3 tile(s)". */
+    label: string;
+    /**
+     * Absolute path to a PNG screenshot of the captcha element at this step.
+     * The file is owned by the callback once emitted — the solver does NOT
+     * delete it (copy/move it where you need it). Null if the screenshot failed.
+     */
+    screenshotPath: string | null;
+    /** Detected puzzle vendor, if known. */
+    puzzleSource?: 'hcaptcha' | 'recaptcha' | 'unknown';
+    /**
+     * Which captcha frame this screenshot is of:
+     *  - `checkbox`  : the anchor "I'm not a robot" widget (no puzzle yet)
+     *  - `challenge` : the open image/grid challenge frame (the real puzzle)
+     *  - `unknown`   : could not be determined from the frame src
+     * Recorders that only want the actual solve (not the pre-challenge checkbox
+     * clicks) filter to `challenge`.
+     */
+    frameRole?: 'checkbox' | 'challenge' | 'unknown';
+    /** Outer solve-loop attempt this step belongs to. */
+    attempt: number;
+    /** ms since solve() started. */
+    elapsedMs: number;
+    /** Free-form per-stage detail (action payload, clicked cells, etc.). */
+    meta?: Record<string, any>;
+}
+export interface CaptchaKrakenConfig {
+    /**
+     * Optional observer fired at each intermediate solve stage. Receives a
+     * baseline screenshot before any action and one after every executed action.
+     * Use it to capture intermediate-stage screenshots, count steps, and time
+     * each phase. The callback may be async; the solver awaits it. Errors thrown
+     * by the callback are swallowed (never fail a solve because logging failed).
+     *
+     * The PNG at `event.screenshotPath` is owned by the callback once emitted —
+     * the solver will not delete it.
+     */
+    onStep?: (event: SolveStepEvent) => void | Promise<void>;
+    /**
+     * Path to the bundled CaptchaKraken CLI root.
+     *
+     * Usually you do NOT need to set this. If omitted, the solver will auto-resolve the
+     * `python/` directory (the captchakraken package) shipped inside this npm package.
+     */
+    repoPath?: string;
+    /**
+     * Command to run python (default: 'python' or 'python3').
+     */
+    pythonCommand?: string;
+    /**
+     * vLLM LoRA name to invoke (default: 'captcha' — our bbox-aware LoRA).
+     * Override if you've registered a different module with the vLLM server.
+     */
+    model?: string;
+    /**
+     * Bearer token for the vLLM server (also picked up from VLLM_API_KEY env).
+     */
+    apiKey?: string;
+    /**
+     * Starting mouse position (default: { x: 100, y: 100 }).
+     * HIGHLY RECOMMENDED to set this, prevents jumping around of the cursor when solving.
+     */
+    startingMousePosition?: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Automatically re-check for newly opened / next-step captchas after each solve
+     * attempt (e.g., clicking a checkbox opens an image challenge).
+     *
+     * Default: 10
+     */
+    maxSolveLoops?: number;
+    /**
+     * Delay (ms) after executing actions before re-detecting captchas.
+     * Useful to allow challenge frames / new images to appear.
+     *
+     * Default: 1200
+     */
+    postSolveDelayMs?: number;
+    /**
+     * Overall time limit (ms) for the entire solve loop.
+     *
+     * Default: 120000 (2 minutes)
+     */
+    overallSolveTimeoutMs?: number;
+    /**
+     * Poll interval (ms) for the reCAPTCHA grid-cell-load wait — how often the
+     * solver re-screenshots the grid while waiting for tiles to stop fading in.
+     * Doubles as the inter-frame gap for the settle change-detector, so keep it
+     * comfortably above zero.
+     *
+     * Default: 250
+     */
+    gridLoadPollIntervalMs?: number;
+    /**
+     * Overall timeout (ms) for the reCAPTCHA grid-cell-load wait. On timeout the
+     * solver proceeds to screenshot anyway (best-effort).
+     *
+     * Default: 8000
+     */
+    gridLoadTimeoutMs?: number;
+    /**
+     * reCAPTCHA 3x3 dynamic puzzles only. After clicking a round of tiles, the
+     * max time (ms) to wait for at least one clicked blank/fading tile to finish
+     * loading before re-screenshotting and re-solving. On timeout the solver
+     * proceeds anyway (best-effort, backstopped by overallSolveTimeoutMs).
+     *
+     * Default: 6000
+     */
+    recaptchaDynamicFadeWaitMs?: number;
+    /**
+     * reCAPTCHA 3x3 dynamic puzzles only. Minimum gap (ms) between the two frames
+     * the fade detectors diff, and the poll cadence for waitForAnyClickedTileLoaded
+     * / currentLoadingCells. Kept comfortably above zero so two consecutive frames
+     * during a slow fade differ enough for the change detector to fire (frames
+     * captured back-to-back can look identical mid-fade and read as "loaded").
+     *
+     * Default: 250
+     */
+    recaptchaDynamicFadePollMs?: number;
+    /**
+     * reCAPTCHA 3x3 dynamic puzzles only. Grace window (ms) after clicking during
+     * which the solver watches the clicked tiles for the ONSET of a blank/fade
+     * before deciding the puzzle is solved. reCAPTCHA keeps a clicked tile
+     * SELECTED (showing its old image + a blue badge) for a couple of seconds and
+     * only THEN blanks it to swap in a replacement, so the window must comfortably
+     * exceed that delay or we submit while the refresh is still pending. If no
+     * clicked tile goes blank/changing within this window, the puzzle is treated
+     * as solved.
+     *
+     * Default: 4000
+     */
+    recaptchaFadeOnsetGraceMs?: number;
+    /**
+     * reCAPTCHA 3x3 dynamic puzzles only. Cap on the number of
+     * click → refresh → re-solve rounds within a single puzzle, independent of
+     * maxSolveLoops.
+     *
+     * Default: 8
+     */
+    recaptchaMaxDynamicRounds?: number;
+    /**
+     * reCAPTCHA 3x3 dynamic puzzles only. When true, the solver hovers the mouse
+     * over the just-clicked blank/fading tiles (in click order) while waiting for
+     * them to reload, mimicking a human. Disable to skip the hover behavior.
+     *
+     * Default: true
+     */
+    recaptchaTileHoverEnabled?: boolean;
+    /**
+     * While the model is generating a solution (the main idle window), drift the
+     * cursor over the challenge area with human-like trajectories instead of
+     * leaving it frozen. Cancelled the instant the model responds. Set false to
+     * keep the cursor still during inference.
+     *
+     * Default: true
+     */
+    idleMouseWander?: boolean;
+    /**
+     * After an action, the max time (ms) to watch for the solve outcome — the
+     * vendor's solved signal (checkbox checked / response token) or a freshly
+     * rendered next round — before falling back to a full re-detect. Returning as
+     * soon as the solved signal appears avoids re-entering the solve pipeline on a
+     * challenge frame that is merely animating closed.
+     *
+     * Default: 4000
+     */
+    postSolveOutcomeTimeoutMs?: number;
+}
+export interface BoundingBox {
+    0: number;
+    1: number;
+    2: number;
+    3: number;
+}
+export interface ClickAction {
+    action: 'click';
+    /**
+     * One or more normalized [x1, y1, x2, y2] bboxes (0–1 fractions of the
+     * screenshot). Each entry produces one click. Emitted by v2 CLI for both
+     * grid selections and click-puzzle points.
+     */
+    target_bounding_boxes?: Array<[number, number, number, number]>;
+    /** Legacy v1 fields kept for backwards-compat with older CLI builds. */
+    target_number?: number | null;
+    target_bounding_box?: [number, number, number, number] | null;
+    target_coordinates?: [number, number] | null;
+}
+export interface DragAction {
+    action: 'drag';
+    source_bounding_box: [number, number, number, number];
+    target_bounding_box: [number, number, number, number];
+}
+export interface DoneAction {
+    action: 'done';
+}
+export interface WaitAction {
+    action: 'wait';
+    duration_ms: number;
+}
+export type CaptchaAction = ClickAction | WaitAction | DragAction | DoneAction;
+export type SolverResult = CaptchaAction | CaptchaAction[];
+export interface TokenUsage {
+    input_tokens: number;
+    output_tokens: number;
+    cached_input_tokens?: number;
+    model: string;
+}
+export interface CliResponse {
+    actions: SolverResult;
+    token_usage: TokenUsage[];
+}
+export interface Vector {
+    x: number;
+    y: number;
+}
+export interface SolveResult {
+    isSolved: boolean;
+    finalMousePosition: Vector;
+    tokenUsage: {
+        modelName: string;
+        inputTokens: number;
+        outputTokens: number;
+        cachedInputTokens: number;
+        estimatedCost: number;
+    };
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "captchakraken",
+  "version": "2.1.0",
+  "description": "Browser-agnostic Playwright/Puppeteer captcha solver. Detects the captcha, reads the grid with a fine-tuned Qwen3.5-9B vision model on vLLM, and clicks through to a token.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "python",
+    "scripts"
+  ],
+  "scripts": {
+    "prebuild": "node scripts/copy-python.mjs",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "tsc --noEmit -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "postinstall": "node scripts/setup-python.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JWriter20/CaptchaKraken.git",
+    "directory": "js"
+  },
+  "keywords": [
+    "captcha",
+    "recaptcha",
+    "hcaptcha",
+    "playwright",
+    "puppeteer",
+    "automation",
+    "vllm",
+    "qwen"
+  ],
+  "author": "Jake Writer",
+  "license": "GPL-3.0-or-later",
+  "type": "commonjs",
+  "bugs": {
+    "url": "https://github.com/JWriter20/CaptchaKraken/issues"
+  },
+  "homepage": "https://github.com/JWriter20/CaptchaKraken#readme",
+  "devDependencies": {
+    "@types/node": "^24.10.2",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "cursory-ts": "^1.0.0"
+  }
+}

package/python/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"]

package/python/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.

package/python/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.