captchakraken 2.6.1 → 2.9.0

package/python/src/captchakraken/solver.py

@@ -24,7 +24,6 @@ v1 had a SAM3-backed tool-using planner with detect/segment/drag-refine; it
 lives on the `v1-old-architecture` branch.
 """
 
-import math
 import os
 import shutil
 import sys
@@ -112,6 +111,47 @@ class DebugManager:
             return None
 
 
+#: The only cell counts a registered grid puzzle has. `find_grid` is a lattice
+#: detector, not a catalogue — it allows rectangles and any dimension from
+#: MIN_GRID_DIM up — so it will happily report 12 or 20 cells on a click puzzle's
+#: header/footer bands. Anything not in here is a false positive by construction,
+#: and it is also a board the model has never seen: the training pipeline's own
+#: `grid_overlay.detect_cells` refuses every count but these two.
+GRID_CELL_SHAPES = {9: (3, 3), 16: (4, 4)}
+
+#: Cell counts each vendor actually ships, for the vendors the driver can name.
+#: Only reCAPTCHA has a 4x4; hCaptcha's single grid puzzle is 3x3, so 16 cells on
+#: an hCaptcha board is a contradiction rather than a close call. Measured on real
+#: captures, that one line removes four of the five non-grid boards that clear
+#: both find_grid and _is_real_grid today.
+#:
+#: A vendor NOT in this table — `unknown`, or anything new — gets every shape.
+#: `unknown` is what the driver reports for GeeTest and Prosopo, both of which
+#: ship real 3x3 grids, and it is what the one-shot image API defaults to, which
+#: is the path the offline grader uses to score reCAPTCHA 4x4. Narrowing it would
+#: stop scoring a whole puzzle type while looking like a tightening.
+VENDOR_GRID_CELLS = {
+    "hcaptcha": frozenset({9}),
+    "recaptcha": frozenset({9, 16}),
+}
+
+
+def _grid_dims(n_cells, puzzle_source="unknown"):
+    """(rows, cols) if this detection could be a grid we ship, else None.
+
+    None means "do not solve this as a grid" — the caller falls through to the
+    click/drag path, which is what the board actually is. It is deliberately not
+    an exception: a false positive here is an ordinary event, not an error.
+    """
+    shape = GRID_CELL_SHAPES.get(n_cells)
+    if shape is None:
+        return None
+    allowed = VENDOR_GRID_CELLS.get(puzzle_source)
+    if allowed is not None and n_cells not in allowed:
+        return None
+    return shape
+
+
 class CaptchaSolver:
     """v2 solver: OpenCV grid detection + vLLM `captcha` LoRA."""
 
@@ -120,13 +160,15 @@ class CaptchaSolver:
         model: Optional[str] = None,
         provider: str = "captchaKrakenApi",
         api_key: Optional[str] = None,
+        expert: Optional[str] = None,
     ):
         self.debug = DebugManager(DEBUG)
         # `provider` kept for argv compatibility with the v1 CLI signature.
         if provider not in {"captchaKrakenApi"}:
             self.debug.log(f"Provider {provider!r} ignored; v2 only supports captchaKrakenApi.")
         self.planner = ActionPlanner(
-            model=model, api_key=api_key, debug_callback=self.debug.log
+            model=model, api_key=api_key, debug_callback=self.debug.log,
+            expert=expert,
         )
         self.image_processor = ImageProcessor(None, self.planner, self.debug)
         self._image_size: Optional[Tuple[int, int]] = None
@@ -183,9 +225,22 @@ class CaptchaSolver:
 
         with timed("solver.find_grid"):
             grid_boxes = find_grid(cv_image_path)
-        if grid_boxes and self._is_real_grid(cv_image_path, grid_boxes):
+        # The SHAPE gate runs before the content gate: a lattice no vendor ships
+        # is not a grid whatever its cells look like, and saying so here keeps
+        # `_solve_grid` from ever being handed dimensions it would have to invent.
+        dims = _grid_dims(len(grid_boxes), puzzle_source) if grid_boxes else None
+        if grid_boxes and dims and self._is_real_grid(cv_image_path, grid_boxes):
             self.debug.log(f"Detected grid with {len(grid_boxes)} cells")
-            return self._solve_grid(cv_image_path, grid_boxes, retry_mode=retry_mode)
+            return self._solve_grid(cv_image_path, grid_boxes, dims[0], dims[1],
+                                    retry_mode=retry_mode)
+        elif grid_boxes and not dims:
+            # e.g. a 16-cell lattice on an hCaptcha board (it ships no 4x4), or a
+            # 12-cell one on anything. Fall through to the click path, which is
+            # what this puzzle is.
+            self.debug.log(
+                f"find_grid returned {len(grid_boxes)} cells, which is not a shape "
+                f"{puzzle_source} ships — not solving as a grid."
+            )
         elif grid_boxes:
             # find_grid latched onto e.g. an hCaptcha click-puzzle's
             # header/footer bands. Reject — only true grids are supported.
@@ -403,11 +458,6 @@ class CaptchaSolver:
             if not stds:
                 return False
 
-            n = len(grid_boxes)
-            side = 3 if n == 9 else 4 if n == 16 else int(round(n ** 0.5))
-            rows = [stds[i * side:(i + 1) * side] for i in range(side)]
-            cols = [stds[i::side] for i in range(side)]
-
             self.debug.log(
                 f"_is_real_grid: per-cell stddev = {[round(s, 1) for s in stds]}"
             )
@@ -430,7 +480,7 @@ class CaptchaSolver:
             # colour is its own; a sprite board shares one board colour behind
             # every cell, so the medians collapse onto a single value.
             # Measured over the real captures: iconcrush and gobang 0.0-0.8,
-            # against 14.9 (recaptcha_grid_4x4) up to 93.0 (geetest_v4_nine)
+            # against 14.9 (a reCAPTCHA 4x4 grid) up to 93.0 (a GeeTest v4 icon board)
             # for the five true grid families. The threshold sits in an 18x
             # gap, which is why it is a fixed number rather than a tuned one.
             medians = []
@@ -459,46 +509,35 @@ class CaptchaSolver:
                 )
                 return False
 
-            FLAT = 20.0
-            # Build a side×side flat-mask (1 = flat cell, 0 = rich cell).
-            flat_mask = [[1 if stds[r * side + c] < FLAT else 0
-                          for c in range(side)] for r in range(side)]
-            flat_count = sum(sum(row) for row in flat_mask)
-
-            # Heuristic: in a *real* captcha grid, flat tiles (sky, asphalt)
-            # always form a spatially contiguous blob (top-left sky stack,
-            # bottom road row, etc.) because the underlying image is a single
-            # photo split into tiles. In a click-puzzle false grid, the flat
-            # cells are the **left + right margins** of the middle row,
-            # separated by the rich photo cell — non-contiguous.
+            # THE FLAT-CELL CONTIGUITY HEURISTIC IS GONE, and it was the only
+            # thing rejecting real grids.
             #
-            # Use 4-connected components on flat cells. If we get more than
-            # one component with >=1 cell each, it's the click-puzzle pattern.
-            def components(mask):
-                seen = [[False] * side for _ in range(side)]
-                comps = 0
-                for r in range(side):
-                    for c in range(side):
-                        if mask[r][c] and not seen[r][c]:
-                            comps += 1
-                            stack = [(r, c)]
-                            while stack:
-                                y, x = stack.pop()
-                                if seen[y][x] or not mask[y][x]:
-                                    continue
-                                seen[y][x] = True
-                                for dy, dx in ((1, 0), (-1, 0), (0, 1), (0, -1)):
-                                    ny, nx = y + dy, x + dx
-                                    if 0 <= ny < side and 0 <= nx < side:
-                                        stack.append((ny, nx))
-                return comps
-
-            if flat_count >= 2 and components(flat_mask) >= 2:
-                self.debug.log(
-                    f"_is_real_grid: flat cells form >=2 disjoint components "
-                    "→ reject (click-puzzle pattern)."
-                )
-                return False
+            # It assumed flat tiles in a genuine photo grid always form ONE
+            # contiguous blob (a top-left sky stack, a bottom road row), because
+            # the board is a single photo cut up; a click-puzzle false grid puts
+            # its flat cells in the left and right margins of the middle row,
+            # which is two components. True of the boards it was written for,
+            # and false of plenty of photographs — a subject centred against
+            # plain sky leaves two flat corners and nothing between them.
+            #
+            # MEASURED over every real capture we hold, restricted to lattices
+            # `_grid_dims` actually accepts (9 or 16 cells — a 25-cell gobang
+            # board never reaches this function as a grid decision):
+            #
+            #     rule                     grid false neg   board false pos
+            #     spread + mean-stddev        2/1748 0.11%       0/269 0.00%
+            #     ...plus contiguity         40/1748 2.29%       0/269 0.00%
+            #
+            # It cost 38 real grids and caught nothing the two checks above did
+            # not already catch — 19 of those were a reCAPTCHA 4x4 grid alone,
+            # 5.5% of that family, every one of them sent to the click path to
+            # be asked for coordinates on a board answered with cell numbers.
+            # Nothing errors when that happens; the reply is simply graded
+            # against a gold it cannot match.
+            #
+            # The median-colour spread check above supersedes it and is a much
+            # cleaner separation (an 18x gap rather than a topological guess),
+            # which is why this is a deletion and not a retuning.
             return True
         except Exception as e:
             self.debug.log(f"_is_real_grid check errored ({e}); accepting grid.")
@@ -508,17 +547,18 @@ class CaptchaSolver:
         self,
         image_path: str,
         grid_boxes: List[Tuple[int, int, int, int]],
+        rows: int,
+        cols: int,
         retry_mode: Optional[str] = None,
     ) -> Union[ClickAction, DoneAction, WaitAction]:
-        n = len(grid_boxes)
-        if n == 9:
-            rows, cols = 3, 3
-        elif n == 16:
-            rows, cols = 4, 4
-        else:
-            cols = int(math.sqrt(n))
-            rows = math.ceil(n / cols)
-        self.debug.log(f"grid {rows}x{cols} ({n} cells)")
+        # The shape is PASSED IN, already cleared by `_grid_dims`. It used to be
+        # derived here, and the derivation had an `else` branch that turned any
+        # unrecognised count into `cols = int(sqrt(n)); rows = ceil(n / cols)` —
+        # so a 12-cell false positive became a 4x3 board, got stamped with twelve
+        # numbers, and was answered with cell ids. No such board can exist in the
+        # training corpus, because the generator's own detector refuses every
+        # count but 9 and 16.
+        self.debug.log(f"grid {rows}x{cols} ({len(grid_boxes)} cells)")
 
         cv_selected: List[int] = []
         cv_loading: List[int] = []

package/python/src/captchakraken/timing.py

@@ -56,9 +56,14 @@ class PhaseBudget:
     monitor spent 31s of it" is. Always on — it is a few dict updates per phase
     against multi-second waits — but only PRINTED under CAPTCHA_TIMINGS=1.
 
-    Phases may nest (a burst contains its screenshots); only the outermost of a
-    given name accumulates, so the totals stay a partition of the solve rather
-    than double-counting.
+    Phases may nest (a burst contains its screenshots). Only the outermost of a
+    GIVEN NAME accumulates, so re-entering one cannot double-count it — but a
+    phase nested inside a differently-named one counts under both, deliberately:
+    the cursor drifting over the widget WHILE the model generates is genuinely
+    both `mouse` and `inference`, and hiding either would misreport what the
+    solve was doing. The totals are therefore an attribution, not a partition,
+    and can exceed the elapsed time. `report()` prints the residual as
+    `(unattributed)` and it can go negative when they do.
     """
 
     def __init__(self) -> None: