captchakraken 2.2.0 → 2.3.0

package/python/LICENSE

@@ -0,0 +1,105 @@
+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
+--------------------------------------------------------------------------------

package/python/README.md

@@ -68,4 +68,6 @@ Everything model-specific lives in `captchakraken.config` and is env-overridable
 
 ## License
 
-GPL-3.0-or-later.
+**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).

package/python/pyproject.toml

@@ -4,17 +4,21 @@ build-backend = "hatchling.build"
 
 [project]
 name = "captchakraken"
-version = "2.2.0"
+version = "2.3.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" }
+# Source-available, NOT GPL. The CaptchaKraken Source-Available License permits
+# commercial use as an internal component but prohibits selling the solve itself
+# or thin-wrapper resale — see LICENSE. (GPL-3.0 would wrongly permit reselling.)
+license = { file = "LICENSE" }
 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",
+  "License :: Other/Proprietary License",
 ]
 
 # Core = the lightweight CLIENT: OpenCV grid detection + the HTTP planner that

package/python/src/captchakraken/__init__.py

@@ -40,14 +40,26 @@ from .overlay import add_overlays_to_image
 try:  # pragma: no cover - exercised only when the serving stack is installed
     from .planner import ActionPlanner
     from .solver import CaptchaSolver, solve_captcha
+
+    # The page driver sits behind the same guard: it imports `solver`, so it has
+    # the same dependency floor. It needs NO browser package of its own — the
+    # caller supplies the Playwright-compatible page (see page_solver's module
+    # docstring on why we duck-type rather than import one).
+    from .page_solver import PageSolver, SolveResult, solve_captcha_on_page
 except ModuleNotFoundError:
     ActionPlanner = None  # type: ignore[assignment,misc]
     CaptchaSolver = None  # type: ignore[assignment,misc]
     solve_captcha = None  # type: ignore[assignment]
+    PageSolver = None  # type: ignore[assignment,misc]
+    SolveResult = None  # type: ignore[assignment,misc]
+    solve_captcha_on_page = None  # type: ignore[assignment]
 
 __all__ = [
     "CaptchaSolver",
     "solve_captcha",
+    "PageSolver",
+    "SolveResult",
+    "solve_captcha_on_page",
     "ActionPlanner",
     "ImageProcessor",
     "CaptchaAction",
@@ -58,4 +70,4 @@ __all__ = [
     "add_overlays_to_image",
 ]
 
-__version__ = "2.0.0"
+__version__ = "2.3.0"

package/python/src/captchakraken/cli.py

@@ -42,11 +42,18 @@ Modes:
         these — a local server auto-starts on the first solve (disable with
         CAPTCHA_KRAKEN_AUTOSTART=0). Point VLLM_BASE_URL at your own server to
         skip local management entirely.
+
+  captchakraken fetch [--weights-only|--engine-only] [--no-restart] [--dry-run]
+        Update in one step: pull the latest CaptchaKraken model from the HF org
+        (https://huggingface.co/CaptchaKraken) AND upgrade the vLLM serving
+        stack, then restart a running local server so it takes effect. Use this
+        to get new model revisions + engine fixes without re-running setup.sh.
 """
 
 import argparse
 import json
 import os
+import subprocess
 import sys
 
 from .solver import CaptchaSolver, UnsupportedCaptchaError
@@ -372,6 +379,7 @@ def _handle_serve() -> bool:
       find-grid               {image}                       -> grid_boxes | null
       grid-cell-states        {a, b}                        -> states | {grid: null}
       grid-cell-states-fixed  {a, b, grid_boxes}            -> states
+      check-movement          {a, b, threshold?}            -> {has_movement: bool}
 
     Unknown cmd / malformed line -> an {ok:false} response (the process keeps
     running). EOF on stdin ends the loop cleanly. All heavy detection delegates
@@ -396,6 +404,15 @@ def _handle_serve() -> bool:
             if not grid_boxes:
                 raise ValueError("empty grid_boxes")
             return _compute_grid_cell_states(req["a"], req["b"], grid_boxes)
+        if cmd == "check-movement":
+            # Freshness check for the JS solver: did the captcha frame change
+            # (tiles faded in / refreshed) between the screenshot we sent the
+            # model and now? Same primitive the one-shot `check-movement` uses.
+            from .image_processor import ImageProcessor
+
+            threshold = float(req.get("threshold", 0.005))
+            moved = ImageProcessor.detect_movement(req["a"], req["b"], threshold)
+            return {"has_movement": bool(moved)}
         raise ValueError(f"unknown cmd: {cmd!r}")
 
     # Signal readiness so the JS side knows imports are done before it polls.
@@ -560,9 +577,55 @@ def _handle_server_commands() -> bool:
     return True
 
 
+def _handle_fetch() -> bool:
+    """`captchakraken fetch` — pull the latest published weights from the HF org
+    and refresh the vLLM serving stack, restarting a running local server so the
+    update takes effect. See updater.fetch for the full behavior."""
+    if len(sys.argv) <= 1 or sys.argv[1] not in {"fetch", "update"}:
+        return False
+
+    flags = set(sys.argv[2:])
+    unknown = flags - {"--weights-only", "--engine-only", "--no-restart", "--dry-run"}
+    if unknown:
+        print(
+            json.dumps({"error": f"unknown fetch flag(s): {sorted(unknown)} "
+                                 "(use --weights-only|--engine-only|--no-restart|--dry-run)"}),
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    if "--weights-only" in flags and "--engine-only" in flags:
+        print(json.dumps({"error": "--weights-only and --engine-only are mutually exclusive"}),
+              file=sys.stderr)
+        sys.exit(2)
+
+    from . import updater
+
+    weights = "--engine-only" not in flags
+    engine = "--weights-only" not in flags
+    try:
+        result = updater.fetch(
+            weights=weights,
+            engine=engine,
+            restart="--no-restart" not in flags,
+            dry_run="--dry-run" in flags,
+        )
+        print(json.dumps(result))
+        return True
+    except subprocess.CalledProcessError as e:
+        print(json.dumps({"error": f"fetch step failed (exit {e.returncode}): "
+                                   f"{' '.join(e.cmd) if isinstance(e.cmd, list) else e.cmd}"}),
+              file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(json.dumps({"error": str(e)}), file=sys.stderr)
+        sys.exit(1)
+
+
 def main():
     if _handle_server_commands():
         return
+    if _handle_fetch():
+        return
     if _handle_movement_commands():
         return
     if _handle_move_commands():

package/python/src/captchakraken/config.py

@@ -13,12 +13,36 @@ The two variables MOST users ever set:
 Advanced / self-hosting overrides (only needed to change WHICH model is served):
   CAPTCHA_BASE_MODEL      base weights vLLM loads         (HF id or local path)
   CAPTCHA_LORA_ADAPTER    LoRA applied on top             (HF id or local path)
+  CAPTCHA_LORA_REVISION   adapter git revision to serve
   CAPTCHA_LORA_NAME       served adapter name the client asks for as `model`
+
+Defaults for the model-identity values come from `pinned_model.json` (see
+`pinned()`), which records the model + prompt pair this release was validated
+against.
   VLLM_PORT, VLLM_GPU_MEMORY_UTILIZATION, VLLM_MAX_MODEL_LEN, VLLM_MAX_LORA_RANK
   CAPTCHA_KRAKEN_AUTOSTART=0   disable auto-starting a local server on first use
 """
 
+import json
 import os
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Dict
+
+_PINNED_MODEL_PATH = Path(__file__).with_name("pinned_model.json")
+
+
+@lru_cache(maxsize=1)
+def pinned() -> Dict[str, Any]:
+    """The pinned model manifest shipped with this release.
+
+    Defines the (base model, adapter, serving prompts) triple this version was
+    validated against. Env vars still override every value below — the manifest
+    supplies the DEFAULT and gives CI something to assert against, so an adapter
+    or prompt change is a reviewable diff instead of a silent drift.
+    """
+    with _PINNED_MODEL_PATH.open(encoding="utf-8") as f:
+        return json.load(f)
 
 
 # ── Inference endpoint ──────────────────────────────────────────────────────
@@ -27,23 +51,81 @@ def base_url() -> str:
     return os.getenv("VLLM_BASE_URL", f"http://localhost:{port()}/v1")
 
 
+def state_dir() -> Path:
+    """Shared state dir for the pidfile, lockfile, server log, and credentials."""
+    return Path(os.getenv("CAPTCHA_KRAKEN_STATE_DIR", str(Path.home() / ".captchakraken")))
+
+
+def credentials_path() -> Path:
+    return state_dir() / "credentials"
+
+
+def _key_from_credentials_file() -> str:
+    """Key written by the MCP server's signup flow (or a future `login` command).
+
+    Hosted-API onboarding writes the key to a 0600 file rather than returning it
+    through the agent transcript, so it never lands in an LLM context window.
+    Reading it here is what lets a solve authenticate with NO env vars set.
+
+    Deliberately tolerant of a bare token, an env-file line, or surrounding
+    quotes: the file is written by a *separate* tool, and a format mismatch here
+    would surface as a baffling 401 rather than an obvious parse error.
+    Returns "" whenever the file is missing, unreadable, or has no usable line.
+    """
+    try:
+        text = credentials_path().read_text(encoding="utf-8")
+    except OSError:
+        return ""
+
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" in line:
+            name, _, value = line.partition("=")
+            # An env-file with unrelated keys must not yield a bogus token.
+            if name.strip() not in {"CAPTCHA_KRAKEN_API_KEY", "VLLM_API_KEY"}:
+                continue
+            line = value.strip()
+        return line.strip("'\"")
+
+    return ""
+
+
 def api_key() -> str:
-    return os.getenv("CAPTCHA_KRAKEN_API_KEY") or os.getenv("VLLM_API_KEY") or "EMPTY"
+    """Bearer token, in precedence order.
+
+    Env first so an explicit override always wins, then the credentials file so
+    the MCP/hosted path needs no env plumbing at all, then "EMPTY" (which leaves
+    a self-hosted local vLLM open, as before).
+    """
+    return (
+        os.getenv("CAPTCHA_KRAKEN_API_KEY")
+        or os.getenv("VLLM_API_KEY")
+        or _key_from_credentials_file()
+        or "EMPTY"
+    )
 
 
 # ── Model identity (all overridable — the CLI itself is model-agnostic) ──────
 def base_model() -> str:
-    return os.getenv("CAPTCHA_BASE_MODEL", "Qwen/Qwen3.5-9B")
+    return os.getenv("CAPTCHA_BASE_MODEL", pinned()["base_model"])
 
 
 def lora_adapter() -> str:
     """HF repo id or local path of the captcha adapter served on top of the base."""
-    return os.getenv("CAPTCHA_LORA_ADAPTER", "CaptchaKraken/CaptchaKraken_v1")
+    return os.getenv("CAPTCHA_LORA_ADAPTER", pinned()["lora_adapter"])
+
+
+def lora_revision() -> str:
+    """Git revision of the adapter repo to serve — pinning this is what makes
+    'the adapter this release was tested against' a reproducible statement."""
+    return os.getenv("CAPTCHA_LORA_REVISION", pinned()["lora_revision"])
 
 
 def lora_name() -> str:
     """The served LoRA name the client sends as the `model` field."""
-    return os.getenv("CAPTCHA_LORA_NAME", "captcha")
+    return os.getenv("CAPTCHA_LORA_NAME", pinned()["lora_name"])
 
 
 # ── Local vLLM server knobs ─────────────────────────────────────────────────