captchakraken 2.8.0 → 2.9.0

package/python/src/captchakraken/planner.py

@@ -29,13 +29,13 @@ DEBUG = os.getenv("CAPTCHA_DEBUG", "0") == "1"
 # The pixel floor the adapters are TRAINED at, and therefore the floor an image
 # has to clear before it is worth sending.
 #
-# Training exports `MIN_PIXELS=200704` (448², in the finetune repo's
-# scripts/train_unified.sh), so anything smaller is enlarged before the vision
+# Training exports `MIN_PIXELS=200704` (448², in the training repo's
+# the training pipeline), so anything smaller is enlarged before the vision
 # encoder sees it. Serving did none of that: vLLM runs with no
 # `--mm-processor-kwargs` and this client used to re-encode the file unchanged,
 # so a small captcha arrived at a geometry the model was never tuned on. It
 # fails as plausible-but-wrong coordinates, never as an error — measured on real
-# geetest_v3_slide captures (277x285), predictions landed 80-105 px from the
+# a GeeTest v3 slider captures (277x285), predictions landed 80-105 px from the
 # hand label at native size and 1-4 px away once upscaled.
 #
 # A FLOOR, NOT A RESIZE. Images already above it are passed through byte-for-byte;
@@ -92,9 +92,9 @@ def _encode_image(path: str,
     im.save(buf, "PNG")
     return "image/png", base64.b64encode(buf.getvalue()).decode()
 
-# Header the fleet's haproxy front (on the reverse-proxy EC2) routes on. When a
+# Header the fleet's the gateway front (on the reverse-proxy EC2) routes on. When a
 # caller sets CAPTCHA_REQUEST_PRIORITY to a positive int, every request carries
-# `X-JH-Priority: <n>`; haproxy sends anything above its threshold (5) straight
+# `X-JH-Priority: <n>`; the gateway sends anything above its threshold (5) straight
 # to the backup GPUs so it never competes with production traffic on the main
 # 5090. The tier-2 CI gate sets this — its traffic is throwaway and must stay
 # off the primary.
@@ -274,7 +274,7 @@ def video_action_prompt(n_keyframes: int) -> str:
 
     The count is in the text because the model has no other way to know how many
     images arrived — frame identities live in the prompt, not in the image payload.
-    Mirrors `instructions.video_instruction` in the finetune repo exactly.
+    Mirrors `instructions.video_instruction` in the training repo exactly.
     """
     n = int(n_keyframes)
     if n < 1:
@@ -283,6 +283,66 @@ def video_action_prompt(n_keyframes: int) -> str:
     return VIDEO_ACTION_PROMPT_TEMPLATE.format(n=n, listing=listing)
 
 
+#: Sampling temperature per RE-ASK of a board the vendor refused, first entry
+#: first. THE ONE COPY: the JS port reaches this through `CAPTCHA_RESAMPLE_LEVEL`
+#: rather than carrying its own numbers, because a schedule written down twice is
+#: a schedule the two ports can disagree about — and the driver gate drives both
+#: and averages them.
+#:
+#: GREEDY ONLY, AND THAT IS A MEASUREMENT, NOT AN OVERSIGHT. Heating the re-ask
+#: was tried: `(0.0, 0.35, 0.7)`, escalating each time a board came back with the
+#: answer it had already given. On five puzzle types that a greedy driver passes,
+#: the escalating one scored 0/5 against 4/5, and the median FAILED attempt cost
+#: 24.0s against 13.9s. Two things went wrong and they compound:
+#:
+#:   1. A hotter sample is a WORSE answer. The greedy read is the best single
+#:      guess this model has; the schedule spends rounds walking away from it.
+#:   2. It defeats the give-up rule. `_no_progress_rounds` counts IDENTICAL
+#:      answers, so making each re-ask differ resets the counter — the attempt
+#:      stops bailing at round 3 and runs to the round ceiling instead. Slower
+#:      failures, not fewer.
+#:
+#: The plumbing stays because the LEVEL is the right thing to travel; what was
+#: wrong was the trigger. A re-ask should be driven by the vendor actually
+#: refusing the answer — read off the network response — and not by the model
+#: agreeing with itself, which is only ever evidence that decoding is
+#: deterministic. Add temperatures here when that signal exists to gate them.
+RESAMPLE_TEMPERATURES = (0.0,)
+
+
+def sampling_for_level(level: int) -> Dict[str, Any]:
+    """Decode overrides for the `level`-th re-ask of one board.
+
+    Level 0 is greedy and returns {}, so a first look is byte-identical to what
+    this client has always sent. Past that it carries a temperature AND a seed:
+    the temperature is what makes a second sample possible at all, and the seed
+    is what makes two re-asks at one temperature two samples rather than one
+    sample twice.
+    """
+    temps = RESAMPLE_TEMPERATURES or (0.0,)
+    temp = temps[min(max(level, 0), len(temps) - 1)]
+    if not temp:
+        return {}
+    return {"temperature": temp, "seed": 1000 + level}
+
+
+def _sampling_from_env() -> Dict[str, Any]:
+    """The JS port's re-ask level, which arrives as an env var.
+
+    That port drives its own round loop and spawns this CLI once per round, so
+    a fresh process has no memory of how many times the board has already been
+    read. Passing the LEVEL rather than the temperature keeps the schedule in
+    one place — see `RESAMPLE_TEMPERATURES`.
+    """
+    raw = os.environ.get("CAPTCHA_RESAMPLE_LEVEL", "").strip()
+    if not raw:
+        return {}
+    try:
+        return sampling_for_level(int(raw))
+    except ValueError:
+        return {}
+
+
 class ActionPlanner:
     """Thin client for the vLLM `captcha` LoRA."""
 
@@ -303,6 +363,15 @@ class ActionPlanner:
         self.model = model or config.lora_name()
         self.base_url = base_url or config.base_url()
         self.api_key = api_key or config.api_key()
+        #: Decode overrides merged into every request payload, or empty.
+        #:
+        #: The page driver sets this while RE-ASKING a board the vendor already
+        #: refused, so that the second look is a second SAMPLE rather than the
+        #: same arithmetic run twice — see
+        #: `PageSolverConfig.resample_temperatures`. Empty by default and
+        #: cleared the moment a fresh board arrives, because greedy is the best
+        #: single guess and every solve that works today works on it.
+        self.sampling: Dict[str, Any] = {}
         # Prompts follow the MODEL, not this client's release. Resolve by the
         # served name first (a hosted endpoint serves `captcha`, not a repo id,
         # and models.json maps the alias back), falling back to the adapter repo
@@ -461,6 +530,10 @@ class ActionPlanner:
         ]
 
         model = self._model_for(family)
+        # `sampling` is set by the page driver when it is RE-ASKING a board the
+        # vendor already refused — see `PageSolverConfig.resample_temperatures`.
+        # Absent (the normal case, and every first look) it is greedy exactly as
+        # before, so nothing about a solve that works today changes.
         payload = {
             "model": model,
             "messages": messages,
@@ -471,13 +544,19 @@ class ActionPlanner:
             # level is the documented way.
             "chat_template_kwargs": {"enable_thinking": False},
         }
+        # In-process the driver sets `sampling` directly; the JS port drives
+        # its own loop and spawns this as a CLI, so its level arrives in the
+        # environment. Explicit beats inherited when both are present.
+        sampling = self.sampling or _sampling_from_env()
+        if sampling:
+            payload.update(sampling)
 
         headers = {
             "Authorization": f"Bearer {self.api_key}",
             "Content-Type": "application/json",
             # Fleet routing: absent unless CAPTCHA_REQUEST_PRIORITY is set (see
             # routing_headers). Low-priority batch traffic is steered to the
-            # backup GPUs by the haproxy front on this header.
+            # backup GPUs by the gateway front on this header.
             **routing_headers(),
         }
 

package/python/src/captchakraken/prompts.py

@@ -5,7 +5,7 @@ Why this exists
 The prompt a captcha model is sent has to be the prompt it was trained on. When
 they drift, nothing errors — the model answers in a schema the client does not
 recognise and puzzles silently fail. That has happened: see failure-mode 3 in
-the finetune repo's `scripts/check_prompt_parity.py`, where the shipped prompt
+the training repo's release parity gate, where the shipped prompt
 kept asking for the legacy `output`/`simulate_drag`/PascalCase schema long after
 the LoRA had been retrained on `action: drag`/`drags[]`.
 
@@ -48,14 +48,14 @@ _PROMPTS_FILE_ENV = "CAPTCHA_PROMPTS_FILE"
 _DISABLE_FETCH_ENV = "CAPTCHA_PROMPTS_NO_FETCH"
 
 # The newest generation this client ships built-ins for. NOT "the version to
-# send" — that is per model, resolved below. This exists so the finetune repo
+# send" — that is per model, resolved below. This exists so the training repo
 # can ask "do you speak the generation I am training?" without importing us.
 LATEST_PROMPT_VERSION = "2"
 
 
 # ── built-in templates, one entry per generation in service ─────────────────
 #
-# A PURE LITERAL, deliberately: the finetune repo's check_prompt_parity.py reads
+# A PURE LITERAL, deliberately: the training repo's release parity gate reads
 # it by AST without importing this package (which pulls in pydantic/cv2 that the
 # training venv need not have). Keep it literal — an f-string, a .join(), or a
 # reference to another constant makes it unreadable to that gate, and the gate
@@ -68,7 +68,7 @@ LATEST_PROMPT_VERSION = "2"
 #   2 — adds the PUZZLE PIECE SLIDER clause and the animated + text families.
 #       Byte-identical to src/synthetic/reasoning/instructions.py
 #       ::PIXEL_INSTRUCTION_TEMPLATE, ::VIDEO_INSTRUCTION_TEMPLATE and
-#       ::TEXT_INSTRUCTION in the finetune repo at PROMPT_VERSION 2.
+#       ::TEXT_INSTRUCTION in the training repo at PROMPT_VERSION 2.
 #
 # Do not edit a published generation's text. Ever. Those models are frozen and
 # so are their prompts; a change here is a change to what an already-shipped
@@ -258,7 +258,7 @@ PRIVATE = "private"
 LICENSED = "licensed"
 #: Anything outside this set is a typo, and a typo must not read as "public".
 #: The whole class of bug this file exists to prevent is a field that fails
-#: open — `check_prompt_parity.py` rejects an unknown value at release time,
+#: open — the release parity gate rejects an unknown value at release time,
 #: and `is_licensed` below treats one as licensed rather than guessing.
 #:
 #: Spelled out as literals rather than `(PUBLIC, PRIVATE, LICENSED)`: the

package/python/src/captchakraken/solver.py

@@ -480,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 = []
@@ -529,7 +529,7 @@ class CaptchaSolver:
             #     ...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 recaptcha_grid_4x4 alone,
+            # 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