captchakraken 2.6.0 → 2.8.0

package/python/src/captchakraken/__init__.py

@@ -32,6 +32,27 @@ 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
+
+# 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,
+    Humanizer,
+    MobileHumanizer,
+    MouseHumanizer,
+    NullHumanizer,
+    TouchBackend,
+    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
@@ -70,6 +91,20 @@ __all__ = [
     "TypeAction",
     "WaitAction",
     "add_overlays_to_image",
+    "CaptchaKrakenAPIError",
+    "Humanizer",
+    "MouseHumanizer",
+    "MobileHumanizer",
+    "NullHumanizer",
+    "TouchBackend",
+    "CdpTouchBackend",
+    "AppiumTouchBackend",
+    "TouchscreenTouchBackend",
 ]
 
-__version__ = "2.6.0"
+# 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.8.0"

package/python/src/captchakraken/cli.py

@@ -505,6 +505,8 @@ def _handle_solve_animated() -> bool:
                              "rate the training data was collected at).")
     parser.add_argument("--model", default=None)
     parser.add_argument("--api-key", default=None)
+    parser.add_argument("--expert", default=None,
+                        choices=["pixel", "grid", "video", "text"])
     args = parser.parse_args(sys.argv[2:])
 
     frames = _frames_in(args.frames_dir)
@@ -527,7 +529,8 @@ def _handle_solve_animated() -> bool:
             paths = [str(os.path.abspath(p))
                      for p in write_keyframes(kfset, kf_dir, stem="challenge")]
 
-            solver = CaptchaSolver(model=args.model, api_key=args.api_key)
+            solver = CaptchaSolver(model=args.model, api_key=args.api_key,
+                                   expert=args.expert)
             result = solver.solve_keyframes(paths)
 
         action_data = [a.model_dump() for a in result]
@@ -630,6 +633,44 @@ def _handle_match_region() -> bool:
     return True
 
 
+def _handle_report_outcome() -> bool:
+    """`captchakraken report-outcome <session-id> solved|failed`
+
+    Tell the hosted API whether the widget accepted this solve. The one fact the
+    server cannot see for itself: a wrong answer arrives there as a 200 with
+    well-formed JSON in it, and only the driver watched the widget.
+
+    THIS EXISTS FOR THE TypeScript PORT. The Python driver calls
+    `planner.report_outcome` in-process at the end of `PageSolver.solve`; the TS
+    driver spawns the CLI, which is the same subprocess boundary every other
+    model call already crosses. One implementation of the endpoint, the
+    credential and the extra headers, rather than a second copy in TypeScript
+    that agrees with this one until one of them is edited — the drift
+    `model-name.ts` already exists to prevent, on the same seam.
+
+    ALWAYS EXITS 0. The caller is a `finally` block in a driver whose solve has
+    already finished, so there is no outcome here worth failing over, and a
+    non-zero exit would make a self-hosted user's logs report an error on every
+    solve. What happened is on stdout for anyone who wants it.
+    """
+    if len(sys.argv) <= 1 or sys.argv[1] != "report-outcome":
+        return False
+    if len(sys.argv) < 4 or sys.argv[3] not in ("solved", "failed"):
+        print(json.dumps({
+            "error": "Usage: captchakraken report-outcome <session-id> solved|failed"
+        }), file=sys.stderr)
+        sys.exit(1)
+    delivered = False
+    try:
+        from .planner import ActionPlanner
+        delivered = ActionPlanner().report_outcome(sys.argv[2], sys.argv[3] == "solved")
+    except Exception as exc:  # noqa: BLE001 — see the docstring
+        print(json.dumps({"reported": False, "error": str(exc)}))
+        return True
+    print(json.dumps({"reported": bool(delivered)}))
+    return True
+
+
 def _handle_tool_commands() -> bool:
     if len(sys.argv) <= 1:
         return False
@@ -841,6 +882,8 @@ def main():
         return
     if _handle_track_piece():
         return
+    if _handle_report_outcome():
+        return
 
     parser = argparse.ArgumentParser(description="CaptchaKraken v2 (vLLM)")
     parser.add_argument("image_path", help="Path to the captcha image or video")
@@ -867,8 +910,11 @@ def main():
         "--puzzle-source",
         default="unknown",
         choices=["hcaptcha", "recaptcha", "unknown"],
-        help="Vendor hint from the Playwright wrapper. hCaptcha skips grid detection "
-        "(find_grid false-positives on the header/footer bands of click puzzles).",
+        help="Vendor hint from the Playwright wrapper. Constrains which grid "
+        "shapes a detection may be solved as: hCaptcha ships only a 3x3, so a "
+        "16-cell lattice on one is a false positive (find_grid latches onto the "
+        "header/footer bands of click puzzles). An unrecognised or absent hint "
+        "allows every shape, which is what GeeTest and Prosopo boards report.",
     )
     parser.add_argument(
         "--retry-mode",
@@ -879,6 +925,17 @@ def main():
         "images'). Switches the grid prompt to a more aggressive variant that "
         "instructs the LoRA to look at the full grid for tiles it missed.",
     )
+    parser.add_argument(
+        "--expert",
+        default=None,
+        choices=["pixel", "grid", "video", "text"],
+        help="Force one expert of a ROUTED model (Abyss) instead of letting the "
+        "prompt family choose. Routing is automatic and this is the override a "
+        "benchmark needs: serve one arm, grade the types it owns, serve the "
+        "next. Refused against a model that serves a single adapter, because "
+        "quietly measuring the generalist and reporting it as the expert is a "
+        "number nobody can catch. Also settable as CAPTCHA_EXPERT.",
+    )
     parser.add_argument(
         "--text-mode",
         action="store_true",
@@ -897,7 +954,8 @@ def main():
 
     try:
         with timed("cli.total"):
-            solver = CaptchaSolver(model=args.model, api_key=args.api_key)
+            solver = CaptchaSolver(model=args.model, api_key=args.api_key,
+                                   expert=args.expert)
             result = solver.solve(
                 args.image_path,
                 puzzle_source=args.puzzle_source,

package/python/src/captchakraken/config.py

@@ -193,11 +193,37 @@ def api_key() -> str:
 # CaptchaKraken_v1.1, so nothing moves until a newer model is registered — at
 # which point that IS the intent.
 def _registry_default(field: str) -> Optional[str]:
-    """`field` from the registry's `latest` model entry, or None."""
+    """`field` from the entry of the model this process will actually serve.
+
+    THE PIN DECIDES THE ENTRY, not just the adapter. This read `latest`
+    unconditionally, so `CAPTCHA_LORA_ADAPTER` moved the adapter and nothing
+    else: the base weights to load it onto, the served `lora_name` to put in
+    the request, and the revision all still came from whichever model happened
+    to be `latest`.
+
+    That was survivable while every registered model was a 9B on one base
+    answering to one served name. It stopped being survivable the day the
+    registry gained `CaptchaKraken/Abyss-27B` — a Qwen3.8-**27B** — because
+    pinning it downloaded a 9B base, tried to load a 27B adapter onto it, and
+    sent `captcha-v12` as the model name. Nothing in the client errors on that;
+    it errors deep inside vLLM as a shape mismatch, or not at all if the
+    endpoint happens to serve something by that name. Same shape for every
+    expert arm, whose whole point is a `lora_name` of its own.
+
+    An UNREGISTERED pin still falls back to `latest`. A self-hoster's own
+    adapter is not in our registry and never will be; changing what they
+    resolve to would be a break with no benefit.
+    """
     try:
         from . import prompts  # local: prompts imports nothing from config
 
-        entry = prompts.registered_models().get(prompts.latest_model() or "")
+        models = prompts.registered_models()
+        entry = None
+        pin = os.getenv("CAPTCHA_LORA_ADAPTER") or os.getenv("CAPTCHA_LORA_NAME")
+        if pin:
+            entry = models.get(prompts.canonical_model_id(pin) or "")
+        if entry is None:
+            entry = models.get(prompts.latest_model() or "")
         value = (entry or {}).get(field)
         return value if isinstance(value, str) else None
     except Exception:  # noqa: BLE001 — a broken registry falls back, never raises

package/python/src/captchakraken/errors.py

@@ -149,6 +149,30 @@ def _sentence(code: str, message: str, url: Optional[str], retry: Optional[float
             "our side, not yours — retry shortly."
         )
 
+    # The two LICENSED-MODEL refusals. Both are 'you named a model', and they
+    # are separate codes because the fix is completely different: one is a
+    # licence to obtain, the other is a fleet that has not started serving yet
+    # and nothing for the caller to do. Generic prose collapses them into "the
+    # solve failed", which is the reading that sends someone to buy a licence
+    # they already hold.
+    if code == "model_not_licensed":
+        return (
+            "CaptchaKraken: the model this request named is licensed, and this "
+            "account is not licensed for it. The request was refused rather than "
+            "answered by a different model — a silent substitution would be a "
+            "score you could not explain. Unset CAPTCHA_LORA_NAME (or the "
+            f"client's `model`) to use the standard hosted model. {message} "
+            f"Licensing: {url or _SUPPORT}."
+        )
+
+    if code == "model_not_serving":
+        return (
+            "CaptchaKraken: this account IS licensed for the model it named, but "
+            "the fleet is not serving it yet. Nothing is wrong with your account "
+            "and there is nothing to buy. Unset CAPTCHA_LORA_NAME (or the "
+            f"client's `model`) to use the standard hosted model meanwhile. {message}"
+        )
+
     # `unrecognized_prompt`, `invalid_request`, and anything added after this was
     # written. The server's own message is the best thing available, so it is
     # carried through verbatim rather than replaced with a guess.