captchakraken 2.8.0 → 3.0.0

package/python/src/captchakraken/timing.py

@@ -1,80 +1,37 @@
-"""
-Lightweight timing utilities.
-
-Enable with env var:
-  CAPTCHA_TIMINGS=1
+"""Where one solve's wall-clock went, by phase. Always collected, printed under CAPTCHA_TIMINGS=1.
 
-This prints a single-line timing record to stderr for each instrumented step.
+Always on because a budget you have to opt into is one nobody has when the slow solve happens.
 """
 
 from __future__ import annotations
 
 import os
-import sys
 import time
 from contextlib import contextmanager
-from typing import Iterator, Optional
-
-
-def timings_enabled() -> bool:
-    return os.getenv("CAPTCHA_TIMINGS", "0") == "1"
+from typing import Dict, Iterator, List
 
+from .kinds import Phase
 
-@contextmanager
-def timed(label: str, extra: Optional[str] = None) -> Iterator[None]:
-    """
-    Context manager that prints:
-      [TIMING] <label>: <ms>ms (<extra>)
-    to stderr when CAPTCHA_TIMINGS=1.
-    """
-    if not timings_enabled():
-        yield
-        return
+# Only a second the model is thinking in or the mouse is travelling in is worth spending; every other
+# phase is the driver waiting on a clock, and a candidate for deletion or overlap.
+PRODUCTIVE = frozenset({Phase.INFERENCE, Phase.MOUSE})
 
-    t0 = time.perf_counter()
-    try:
-        yield
-    finally:
-        dt_ms = (time.perf_counter() - t0) * 1000.0
-        suffix = f" ({extra})" if extra else ""
-        print(f"[TIMING] {label}: {dt_ms:.2f}ms{suffix}", file=sys.stderr)
 
-
-#: What a phase's time COUNTS AS, when asking how much of a solve was useful.
-#:
-#: Only two kinds of second are worth spending: one the model is thinking in,
-#: and one the mouse is travelling in (which has to look human, so it cannot be
-#: rushed). Everything else is the driver waiting on a clock, and every such
-#: wait is a candidate for deletion or for overlapping with something real.
-PRODUCTIVE = {"inference", "mouse"}
+def timings_enabled() -> bool:
+    return os.getenv("CAPTCHA_TIMINGS", "0") == "1"
 
 
 class PhaseBudget:
-    """Where one solve's wall-clock went, by phase.
-
-    Exists because "the solve took 77s" is not actionable and "the settle
-    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 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:
-        self.totals: dict = {}
-        self.counts: dict = {}
-        self._open: list = []
+        self.totals: Dict[Phase, float] = {}
+        self.counts: Dict[Phase, int] = {}
+        self._open: List[Phase] = []
         self._t0 = time.perf_counter()
 
     @contextmanager
-    def phase(self, name: str) -> Iterator[None]:
-        if name in self._open:          # nested re-entry: attribute it to the outer one
+    def phase(self, name: Phase) -> Iterator[None]:
+        # Only the outermost entry of a name accumulates; nesting under another name counts under both.
+        if name in self._open:
             yield
             return
         self._open.append(name)
@@ -83,16 +40,9 @@ class PhaseBudget:
             yield
         finally:
             self._open.remove(name)
-            dt = (time.perf_counter() - t0) * 1000.0
-            self.totals[name] = self.totals.get(name, 0.0) + dt
-            self.counts[name] = self.counts.get(name, 0) + 1
+            self.add(name, (time.perf_counter() - t0) * 1000.0)
 
-    def add(self, name: str, ms: float) -> None:
-        """Record a measured span directly.
-
-        For blocks that would need re-indenting to sit under `phase()` — the
-        accounting is not worth reshaping working control flow over.
-        """
+    def add(self, name: Phase, ms: float) -> None:
         self.totals[name] = self.totals.get(name, 0.0) + ms
         self.counts[name] = self.counts.get(name, 0) + 1
 
@@ -102,16 +52,12 @@ class PhaseBudget:
     def report(self) -> str:
         total = self.elapsed_ms()
         useful = sum(v for k, v in self.totals.items() if k in PRODUCTIVE)
-        rows = sorted(self.totals.items(), key=lambda kv: -kv[1])
-        lines = [f"[BUDGET] solve {total / 1000:.1f}s — "
-                 f"{useful / 1000:.1f}s useful ({100 * useful / total if total else 0:.0f}%), "
-                 f"{(total - useful) / 1000:.1f}s waiting"]
-        for name, ms in rows:
+        lines = [f"[BUDGET] solve {total / 1000:.1f}s — {useful / 1000:.1f}s useful "
+                 f"({100 * useful / total if total else 0:.0f}%), {(total - useful) / 1000:.1f}s waiting"]
+        for name, ms in sorted(self.totals.items(), key=lambda kv: -kv[1]):
             tag = "*" if name in PRODUCTIVE else " "
             lines.append(f"[BUDGET] {tag} {name:22s} {ms / 1000:6.2f}s  x{self.counts[name]}")
         unattributed = total - sum(self.totals.values())
         if unattributed > 50:
             lines.append(f"[BUDGET]   {'(unattributed)':22s} {unattributed / 1000:6.2f}s")
         return "\n".join(lines)
-
-

package/python/src/captchakraken/tool_calls/board_painted.py

@@ -0,0 +1,47 @@
+"""Has the widget painted its puzzle yet, or are we photographing the rebuild hole?
+
+Measured on gt4.geetest.com's slide demo (2026-09-12): 6 of 52 requests carried a board with under 5% ink and
+every one came back dead centre. The settle gate cannot catch it because a blank panel is perfectly still.
+Structure is measured, not ink, because geetest_v4_svg is line art on white. A caller must treat False as
+"wait a moment longer", never "give up": a gate that can refuse to ever take a picture is worse than the blank one.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Sequence
+
+# Trimmed in from every edge: the caption and icon row are chrome that paints early, on a blank board too.
+CENTRE_BOX = (0.15, 0.25, 0.85, 0.75)
+
+# Below this is JPEG noise and anti-aliasing on a flat fill.
+LEVEL_DELTA = 12
+
+# Blank-versus-anything, not a puzzle density: measured 0.000-0.004 blank against 0.19-0.56 painted.
+TEXTURE_FLOOR = 0.015
+
+
+def centre_texture(path: str, box: Optional[Sequence[float]] = None) -> Optional[float]:
+    import cv2
+    import numpy as np
+
+    img = cv2.imread(path, cv2.IMREAD_GRAYSCALE)
+    if img is None:
+        return None
+    h, w = img.shape[:2]
+    b = tuple(box) if box is not None else CENTRE_BOX
+    x1, y1 = int(b[0] * w), int(b[1] * h)
+    x2, y2 = int(b[2] * w), int(b[3] * h)
+    if x2 - x1 < 8 or y2 - y1 < 8:
+        return None
+    region = img[y1:y2, x1:x2].astype("int16")
+    ground = float(np.median(region))
+    return float((abs(region - ground) > LEVEL_DELTA).mean())
+
+
+def board_is_painted(path: str, floor: Optional[float] = None,
+                     box: Optional[Sequence[float]] = None) -> dict:
+    f = TEXTURE_FLOOR if floor is None else float(floor)
+    t = centre_texture(path, box)
+    if t is None:
+        return {"painted": None, "texture": None, "floor": f}
+    return {"painted": bool(t >= f), "texture": round(t, 5), "floor": f}

package/python/src/captchakraken/tool_calls/find_checkbox.py

@@ -1,72 +1,62 @@
+"""Where the driver clicks first, before any model runs. Neither a false positive nor a false negative raises."""
+
 import cv2
 import numpy as np
 from typing import Optional, Tuple
 
 def find_checkbox(image_path: str) -> Optional[Tuple[int, int, int, int]]:
-    """
-    Detects a checkbox in the image using lightweight computer vision techniques.
-    Returns the (x, y, w, h) of the best candidate or None.
-    """
     img = cv2.imread(image_path)
     if img is None:
         return None
 
     gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
-    
-    # Simple thresholding - efficient and works well for high contrast line art like checkboxes
+
     _, binary = cv2.threshold(gray, 200, 255, cv2.THRESH_BINARY_INV)
-    
+
     contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
-    
+
     height, width = img.shape[:2]
     image_area = width * height
-    
+
     candidates = []
-    
+
     for cnt in contours:
         x, y, w, h = cv2.boundingRect(cnt)
         area = w * h
         aspect_ratio = float(w) / h
         
-        # Filter based on properties
-        
-        # 1. Aspect ratio should be close to 1 (square)
+
         if not (0.8 < aspect_ratio < 1.2):
             continue
-            
-        # 2. Minimum absolute size (to avoid noise/text periods)
+
+        # Below 20px a glyph is indistinguishable from a box.
         if w < 20 or h < 20:
             continue
 
-        # 3. Area relative to image size
+        # Above 5% of the image it is a panel or the challenge frame, not the checkbox inside one.
         if not (0.001 * image_area < area < 0.05 * image_area):
             continue
-            
-        # 4. Solidity/Extent
+
         contour_area = cv2.contourArea(cnt)
         extent = contour_area / area
-        if extent < 0.8: # Stricter extent to avoid complex shapes
+        if extent < 0.8:
             continue
 
-        # 5. Content check - Checkboxes are usually empty (white/solid)
-        # Crop margin to avoid border
-        roi = gray[y+5:y+h-5, x+5:x+w-5] 
+        # A checkbox is empty inside; without this the first tile of a 3x3 grid gets clicked as the widget.
+        roi = gray[y+5:y+h-5, x+5:x+w-5]
         if roi.size > 0:
             std_dev = np.std(roi)
-            if std_dev > 35.0: # High variance means complex content (image)
+            if std_dev > 35.0:
                 continue
 
         candidates.append((x, y, w, h))
-        
-    # Heuristic: Checkbox captchas typically have 1 single checkbox.
-    # If we find many candidates, it's likely a grid or something else.
+
+    # Many candidates means a grid, not a checkbox page.
     if len(candidates) > 2:
         return None
-        
+
     if not candidates:
         return None
-        
-    # Return the largest candidate (most likely the main checkbox)
+
     best_candidate = max(candidates, key=lambda c: c[2] * c[3])
     return best_candidate
-