captchakraken 2.9.0 → 3.1.0

package/python/examples/with_local_gguf.py

@@ -0,0 +1,28 @@
+import os
+import sys
+
+from captchakraken import solve_captcha
+
+TEXT_CAPTCHAS = {"--text"}
+
+
+def main() -> int:
+    args = [a for a in sys.argv[1:] if a not in TEXT_CAPTCHAS]
+    if not args:
+        print(__doc__)
+        return 2
+    image = args[0]
+    text_mode = bool(TEXT_CAPTCHAS & set(sys.argv[1:]))
+
+    print(f"endpoint : {os.getenv('VLLM_BASE_URL', '(default)')}")
+    print(f"model    : {os.getenv('CAPTCHA_LORA_NAME', '(registry default)')}")
+    print(f"prompts  : {os.getenv('CAPTCHA_LORA_ADAPTER', '(latest)')}")
+
+    result = solve_captcha(image, text_mode=text_mode)
+
+    print(f"answer   : {result}")
+    return 0 if result else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/python/examples/with_playwright.py

@@ -1,20 +1,3 @@
-"""
-Vanilla Playwright + CaptchaKraken.
-
-No adapter, and no browser dependency in the package: the driver duck-types the
-Playwright surface, so a real `sync_playwright` page satisfies it as-is — as do
-patchright's and camoufox's.
-
-    pip install captchakraken playwright && playwright install chromium
-    export VLLM_BASE_URL=https://api.captchakraken.com/v1
-    export CAPTCHA_KRAKEN_API_KEY=ck_live_...
-    python examples/with_playwright.py [url]
-
-SYNC, NOT ASYNC. `PageSolver` mirrors the synchronous Playwright API. A sync
-handle cannot be driven from inside an event loop, so `async_playwright` pages
-cannot be solved — use `sync_playwright`, as here.
-"""
-
 import sys
 
 from playwright.sync_api import sync_playwright
@@ -30,9 +13,7 @@ def main() -> int:
         page = browser.new_page()
         page.goto(URL)
 
-        # ── the whole integration: construct, solve ──────────────────────────
         result = PageSolver().solve(page)
-        # ─────────────────────────────────────────────────────────────────────
 
         print("✅ solved" if result.is_solved else "❌ not solved")
         browser.close()

package/python/pyproject.toml

@@ -1,13 +1,13 @@
 [build-system]
-requires = ["hatchling"]
+requires = ["hatchling==1.32.0"]
 build-backend = "hatchling.build"
 
 [project]
 name = "captchakraken"
-version = "2.9.0"
+version = "3.1.0"
 description = "Captcha-solving engine and CLI: OpenCV grid detection plus a fine-tuned Qwen3.5-9B vision model, for image grids, click and drag puzzles, sliders, distorted text and animated challenges. Hosted API or self-hosted on vLLM."
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 # Source-available, NOT GPL. The CaptchaKraken Source-Available License permits
 # commercial use as an internal component but prohibits selling the solve itself,
 # thin-wrapper resale, and bundling it into a stealth browser someone else ships
@@ -23,7 +23,6 @@ classifiers = [
   "Development Status :: 5 - Production/Stable",
   "Intended Audience :: Developers",
   "Programming Language :: Python :: 3",
-  "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
@@ -40,29 +39,52 @@ classifiers = [
 # 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.
+# Pinned exactly, never ranged: a dependency changes when we decide it does.
+#
+# EVERY PIN MUST INSTALL ON `requires-python`'s FLOOR, not on the newest
+# interpreter that happens to be on your machine. numpy 2.5.3 was pinned here
+# from a 3.14 box and broke the then-3.10 leg outright — it declares
+# `Requires-Python >=3.12`, so pip could not find it at all.
+#
+# The floor is 3.11 as of 3.0.0, and it moved because the MOUSE moved: `cursory`
+# declares `Requires-Python >=3.11` and drags numpy 2.3.x with it, which declares
+# the same. Neither is a pin we could have chosen differently — 2.2.6 was the
+# newest numpy covering 3.10, and cursory does not run there at all. Resolve
+# against the floor before changing any of these, and see TRIBAL_KNOWLEDGE.md.
 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",
+  "pydantic==2.13.5",
+  "pillow==12.3.0",
+  # 2.3.x rather than 2.2.6 because `cursory` requires `numpy~=2.3.3` and the
+  # old pin was ours, not opencv's — opencv-python-headless asks only for
+  # `numpy>=2`. Moved deliberately as part of the major bump.
+  "numpy==2.3.5",
+  "opencv-python-headless==5.0.0.93",
+  "requests==2.34.2",
+  "python-dotenv==1.2.3",
+  # The mouse. LGPL-3.0-or-later, used as an ordinary installed dependency and
+  # never vendored or bundled, which is the arrangement the licence is written
+  # for — see NOTICE. Its TypeScript port `cursory-js` is the JS driver's
+  # dependency, and the two agree bit for bit on a seed.
+  "cursory==2.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.
+# torch is the version vllm 0.29.0 itself pins; any other value makes this
+# extra unresolvable rather than merely different.
 serve = [
-  "vllm>=0.6.3",
-  "torch>=2.0.0",
-  "transformers>=4.40.0",
-  "accelerate>=0.27.0",
-  "huggingface_hub>=0.23.0",
+  "vllm==0.29.0",
+  "torch==2.13.0",
+  "transformers==5.17.0",
+  "accelerate==1.15.0",
+  "huggingface_hub==1.30.0",
 ]
 dev = [
-  "pytest>=7.0.0",
-  "mypy>=1.0.0",
-  "ruff>=0.1.0",
+  "pytest==9.1.1",
+  "pytest-cov==7.1.0",
+  "mypy==2.3.1",
+  "ruff==0.16.6",
 ]
 
 [project.scripts]
@@ -78,12 +100,39 @@ Changelog = "https://github.com/JWriter20/CaptchaKraken/blob/main/CHANGELOG.md"
 [tool.hatch.build.targets.wheel]
 packages = ["src/captchakraken"]
 
+# AGENTS.md lives beside pyproject.toml, not inside the package, so the wheel
+# would not carry it. An agent that only ever sees `site-packages/captchakraken`
+# is exactly the reader it is written for, so it is copied in.
+[tool.hatch.build.targets.wheel.force-include]
+"AGENTS.md" = "captchakraken/AGENTS.md"
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["src"]
 
+# Coverage is NOT in addopts on purpose: the rule here is to run the failing
+# test rather than the suite, and a threshold measured over one test would fail
+# every time. CI asks for it explicitly.
+[tool.coverage.run]
+source = ["captchakraken"]
+branch = true
+
+[tool.coverage.report]
+precision = 2
+# The floor is the value measured over the suite as it stands, rounded down to a
+# whole percent — not the 90% the spec asks for. A gate that is red the day it
+# lands blocks every pull request and teaches people to route around it; the
+# real distance to 90% is recorded in TRIBAL_KNOWLEDGE.md so it cannot be
+# forgotten. Raise this as coverage rises, never lower it.
+#
+# 53 -> 58: dead code removed (the denominator shrank) plus behaviour tests on
+# the overlay, the checkbox detector, the wait-gate metric, the CLI wire format
+# and the worker protocol. Measured 58.33% on 3.11 and 58.31% on 3.12; the floor
+# is the lower, rounded down.
+fail_under = 69
+
 [tool.mypy]
-python_version = "3.10"
+python_version = "3.11"
 warn_return_any = false
 warn_unused_configs = true
 disallow_untyped_defs = false

package/python/src/captchakraken/__init__.py

@@ -1,20 +1,6 @@
-"""
-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.
-"""
-
 from pathlib import Path
 
-try:  # pragma: no cover
+try:
     from dotenv import load_dotenv
 
     project_root = Path(__file__).resolve().parent.parent
@@ -32,16 +18,20 @@ from .action_types import (
 from .image_processor import ImageProcessor
 from .overlay import add_overlays_to_image
 
-# The hosted API's refusal type. Outside the try below on purpose: `errors`
-# imports nothing but `typing`, and docs/hosted-api.md tells every caller to
-# branch on its `.code` — a recipe that has to work in both ports, and in a
-# minimal install that has no serving stack.
 from .errors import CaptchaKrakenAPIError
+from .kinds import (
+    ActionKind,
+    Availability,
+    ErrorCode,
+    HumanizationMode,
+    KeyframeMode,
+    Outcome,
+    PauseKind,
+    PromptFamily,
+    RetryMode,
+    Vendor,
+)
 
-# How gestures are PERFORMED — mouse, touch, or nothing. Deliberately outside
-# the try below: `humanize` imports only `trajectory`, so it has no dependency
-# floor at all, and a caller writing a custom Humanizer must be able to import
-# the base class without the serving stack installed.
 from .humanize import (
     AppiumTouchBackend,
     CdpTouchBackend,
@@ -53,33 +43,30 @@ from .humanize import (
     TouchscreenTouchBackend,
 )
 
-# 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
+try:
     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
+    from .selectors import SELECTORS, VendorSelectors
     from .watcher import CaptchaWatcher
 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]
-    CaptchaWatcher = None  # type: ignore[assignment,misc]
-    SolveResult = None  # type: ignore[assignment,misc]
-    solve_captcha_on_page = None  # type: ignore[assignment]
+    ActionPlanner = None
+    CaptchaSolver = None
+    solve_captcha = None
+    PageSolver = None
+    SELECTORS = None
+    VendorSelectors = None
+    CaptchaWatcher = None
+    SolveResult = None
+    solve_captcha_on_page = None
 
 __all__ = [
     "CaptchaSolver",
     "solve_captcha",
     "PageSolver",
+    "SELECTORS",
+    "VendorSelectors",
     "CaptchaWatcher",
     "SolveResult",
     "solve_captcha_on_page",
@@ -100,11 +87,16 @@ __all__ = [
     "CdpTouchBackend",
     "AppiumTouchBackend",
     "TouchscreenTouchBackend",
+    "ActionKind",
+    "Availability",
+    "ErrorCode",
+    "HumanizationMode",
+    "KeyframeMode",
+    "Outcome",
+    "PauseKind",
+    "PromptFamily",
+    "RetryMode",
+    "Vendor",
 ]
 
-# KEEP IN STEP with python/pyproject.toml and js/package.json — the two ports
-# ship together (rule 1c) and this is the only one importable code can read.
-# It said 2.6.0 while the wheel on PyPI said 2.6.1, so anyone gating on the
-# runtime attribute saw a version that had not been current for weeks.
-# tests/test_public_contract.py compares all three.
-__version__ = "2.9.0"
+__version__ = "3.1.0"

package/python/src/captchakraken/action_types.py

@@ -2,12 +2,10 @@ from typing import List, Literal, Optional, Union, Tuple
 
 from pydantic import BaseModel, RootModel
 
+from .kinds import ActionKind
+
 
 class BoundingBox(RootModel):
-    """
-    Strongly typed bounding box: [x1, y1, x2, y2] in percentages (0.0 to 1.0).
-    Acts like a list for convenience but ensures exactly 4 float elements.
-    """
     root: Tuple[float, float, float, float]
 
     def __iter__(self):
@@ -21,57 +19,37 @@ class BoundingBox(RootModel):
 
 
 class Action(BaseModel):
-    action: str
-    # ANIMATED CHALLENGES ONLY. Path to the keyframe the model chose to act on, and
-    # its 1-based number in the set that was sent.
-    #
-    # Why an action carries a picture: on an animated puzzle the target is only
-    # present part of the time, so these coordinates are correct only while the
-    # widget looks the way it did in that keyframe. The driver therefore holds the
-    # mouse until the live neighbourhood around the click point matches the same
-    # neighbourhood of this file, then clicks. Without it the click fires on
-    # whatever happens to be on screen, which for a fading sprite is usually
-    # background.
-    #
-    # Absent on every still puzzle, where there is no moment to wait for. Both are
-    # set together or not at all — a number with no image cannot be waited on, and
-    # an image with no number cannot be reported.
+    action: ActionKind
     await_keyframe: Optional[str] = None
     frame: Optional[int] = None
 
 
 class ClickAction(Action):
-    action: Literal["click"]
-    target_bounding_boxes: List[BoundingBox] # List of [x1, y1, x2, y2] in percentages
+    action: Literal[ActionKind.CLICK]
+    target_bounding_boxes: List[BoundingBox]
 
 
 class DragAction(Action):
-    action: Literal["drag"]
-    # Optional, not merely defaulted: a PUZZLE-PIECE SLIDER is carried as a drag
-    # with source_bounding_box explicitly None, and pydantic validates a value
-    # that is passed even when it equals the default. Declaring these as bare
-    # `BoundingBox = None` made constructing a slide raise ValidationError —
-    # every slide puzzle, at the moment of acting on a correct answer.
-    source_bounding_box: Optional[BoundingBox] = None  # [x1, y1, x2, y2] in percentages
-    target_bounding_box: Optional[BoundingBox] = None  # [x1, y1, x2, y2] in percentages
+    action: Literal[ActionKind.DRAG]
+    # `Optional[...] = None`, never a bare `BoundingBox = None`: pydantic validates a passed value even when it
+    # equals the default, and the bare form made every slide (a drag with no source) raise ValidationError.
+    source_bounding_box: Optional[BoundingBox] = None
+    target_bounding_box: Optional[BoundingBox] = None
 
 
 class TypeAction(Action):
-    """Type text into an input."""
-    action: Literal["type"]
+    action: Literal[ActionKind.TYPE]
     text: str
-    target_bounding_box: Optional[BoundingBox] = None  # [x1, y1, x2, y2] in percentages
+    target_bounding_box: Optional[BoundingBox] = None
 
 
 class WaitAction(Action):
-    """Wait for a specified duration."""
-    action: Literal["wait"]
+    action: Literal[ActionKind.WAIT]
     duration_ms: int
 
 
 class DoneAction(Action):
-    """Signal that the captcha is solved or no further actions are needed."""
-    action: Literal["done"]
+    action: Literal[ActionKind.DONE]
 
 
 CaptchaAction = Union[ClickAction, DragAction, TypeAction, WaitAction, DoneAction]