captchakraken 2.6.0 → 2.8.0

package/python/src/captchakraken/keyframes.py

@@ -511,6 +511,96 @@ def _detect_cycle(
     return state_reps, per_frame
 
 
+def _drop_smeared(
+    frames: Sequence[np.ndarray], indices: Sequence[int], params: KeyframeParams
+) -> List[int]:
+    """Drop an index caught BETWEEN two holds, when both of them are already
+    represented in the cut.
+
+    These clips hold a picture, swap, hold the next. An evenly spaced sample can
+    land on the instant of the swap — a board part-way between two states, which
+    is a picture the puzzle never actually shows. If the model already has the
+    board before the swap AND the board after it, that frame adds nothing but a
+    smear; if either endpoint is missing, it is the only thing standing in for a
+    state and must stay.
+
+    THE MACHINERY ALREADY EXISTED AND THIS PATH NEVER ASKED IT. `_anchor_runs`
+    plus `min_hold_frames` is how `_detect_cycle` separates holds from
+    transitions (it labels the latter -1 in `frame_states`), and
+    `min_hold_frames` had exactly one reader — inside `_detect_cycle`. On the
+    `even` path the parameter was declared, serialised into every manifest, and
+    inert.
+
+    WHY THE TEST IS "BOTH NEIGHBOURING HOLDS ARE KEPT" AND NOT A PIXEL DIFF.
+    Two earlier versions were measured against both trees and both were wrong:
+
+      * *Snap to the nearest held frame* turned `[0, 16, 39]` into `[0, 16]` on
+        six eval clips, dropping a SCREEN. A page that never reaches the model is
+        unanswerable whenever the target lived on it.
+      * *Drop when some other still is within `distinct_ratio`* cut
+        `hcaptcha_tile_flip_video` from 6 stills to 3, because two boards of that
+        puzzle differ by ONE TILE — well inside `distinct_ratio` — so a diff
+        threshold cannot tell "the same picture again" from "the next board".
+        EXPECTED_SLICING says it directly: fewer than 6 "means dedup merged two
+        boards that differ only by the tile mid-flip, and that tile is frequently
+        the answer".
+
+    Anchoring on the HOLDS either side asks the question that actually matters —
+    does the model already see both ends of this swap — and needs no threshold of
+    its own.
+
+    A clip with no holds at all (a rotation, a continuous fade, anything in
+    permanent motion) has no transitions to speak of and is returned untouched.
+    """
+    runs = _anchor_runs(frames, params.steady_ratio)
+    holds = [(s, e) for (s, e) in runs if (e - s + 1) >= params.min_hold_frames]
+    if not holds:
+        return list(indices)               # nothing holds; nothing is a smear
+
+    # Holds showing the same picture are ONE state — the same merge
+    # `_detect_cycle` does, at the same threshold. It matters here because a
+    # cycle revisits: on a real `icon_2x2` clip the hold at 53..74 is the
+    # opening board coming back, so the still at index 0 already covers it.
+    # Counting holds instead of states kept a smear whose neighbouring picture
+    # was on screen the whole time.
+    state_of_hold: List[int] = []
+    reps: List[int] = []
+    for start, end in holds:
+        rep = _medoid(frames, list(range(start, end + 1)))
+        for k, existing in enumerate(reps):
+            if frame_diff_ratio(frames[rep], frames[existing]) <= params.steady_ratio:
+                state_of_hold.append(k)
+                break
+        else:
+            reps.append(rep)
+            state_of_hold.append(len(reps) - 1)
+
+    def hold_of(i: int) -> Optional[int]:
+        for k, (s, e) in enumerate(holds):
+            if s <= i <= e:
+                return k
+        return None
+
+    covered = {state_of_hold[h] for h in (hold_of(i) for i in indices)
+               if h is not None}
+    kept: List[int] = []
+    for i in indices:
+        if hold_of(i) is not None:
+            kept.append(i)
+            continue
+        before = max((k for k, (s, e) in enumerate(holds) if e < i), default=None)
+        after = min((k for k, (s, e) in enumerate(holds) if s > i), default=None)
+        # Only a swap BETWEEN two kept holds is redundant. A transition at the
+        # very start or end of a clip has an endpoint that was never recorded,
+        # so it is evidence of a state and stays.
+        if before is not None and after is not None \
+                and state_of_hold[before] in covered \
+                and state_of_hold[after] in covered:
+            continue
+        kept.append(i)
+    return kept
+
+
 def extract_keyframes(
     frames: Sequence[np.ndarray],
     *,
@@ -548,12 +638,21 @@ def extract_keyframes(
         )
 
     indices = _even_indices(n, p.max_keyframes)
+    # BEFORE dedup, so a smear does not spend budget a real state could use...
+    indices = _drop_smeared(frames, indices, p)
     if p.dedupe:
         # Applied to `even` only. `cycle` states are distinct by construction (the
         # merge in `_detect_cycle` uses this same threshold) and `static` is one
         # frame, so there is nothing to remove; and dropping a cycle keyframe here
         # would desynchronise `frame_states`, which indexes keyframes by position.
         indices = _distinct_indices(frames, indices, p)
+        # ...AND AFTER, because `_distinct_indices` BACKFILLS. Dedup frees
+        # budget and the backfill walks the clip for anything not already
+        # represented — which is exactly what a smeared frame is, so it gets
+        # picked straight back up. Measured on a 3-hold fixture: filtering only
+        # before dedup returned [0, 10, 12, 21, 25] with 10 and 21 the two
+        # smears the first pass had just removed.
+        indices = _drop_smeared(frames, indices, p)
     return KeyframeSet(
         mode="even",
         keyframes=[

package/python/src/captchakraken/models.json

@@ -6,10 +6,9 @@
     "Why a map and not a constant: a model answers in whatever schema its prompt",
     "asks for. Send a version-1 model the version-2 prompt and nothing errors —",
     "it just answers worse, on every puzzle, silently. That is exactly the",
-    "2026-07-18 regression (failure-mode 3 in the finetune repo's",
-    "scripts/check_prompt_parity.py), 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[].",
+    "2026-07-18 regression, 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[].",
     "",
     "Hardcoding one generation makes that inevitable the moment a new model",
     "trains on different prompts: updating the constants breaks every already-",
@@ -27,10 +26,9 @@
     "never see `latest`, so they are not silently moved onto prompts they cannot",
     "produce.",
     "",
-    "Adding a model: add its entry here IN THE SAME COMMIT as publishing it. The",
-    "finetune repo's check_prompt_parity.py fails if any registered model names a",
-    "prompt_version this client ships no built-ins for, so an unmapped model",
-    "cannot reach a release.",
+    "Adding a model: add its entry here IN THE SAME COMMIT as publishing it. A",
+    "release gate fails if any registered model names a prompt_version this",
+    "client ships no built-ins for, so an unmapped model cannot reach a release.",
     "",
     "`pixel_budget` is the same idea for RESOLUTION. Qwen reads MIN_PIXELS /",
     "MAX_PIXELS from the environment and clamps each image's AREA into that band,",
@@ -47,7 +45,80 @@
     "",
     "Omit it and the client keeps its historical behaviour (floor at 448 squared,",
     "no ceiling). Absent means UNKNOWN, not zero — set it only where it has been",
-    "measured or the training run is known."
+    "measured or the training run is known.",
+    "",
+    "`availability` says whether the WEIGHTS are obtainable. Two values:",
+    "  \"public\"   — on the Hub; anyone may download and self-host it. This is",
+    "               the default when the field is absent, so every entry that",
+    "               predates the field keeps its meaning exactly.",
+    "  \"private\"  — ON THE HUB, in a PRIVATE repo. The bytes exist and",
+    "               `captchakraken fetch` pulls them; the Hub answers 401 to",
+    "               everyone whose token this account has not authorised. That",
+    "               refusal belongs to the Hub, not to us, so the client does",
+    "               NOT pre-empt it — doing so would stop our own admin token",
+    "               from fetching weights it is entitled to.",
+    "",
+    "               It is NOT a softer `licensed`, and the difference is what an",
+    "               authorised holder can do: a licensed model has nothing to",
+    "               download however good your credentials are. `latest` may",
+    "               never be private either — an unpinned self-hoster would get",
+    "               a 401 instead of a model — and check_prompt_parity.py says so.",
+    "",
+    "  \"licensed\" — NOT downloadable by anyone. Reachable only through",
+    "               api.captchakraken.com, or by a holder of a licence we issue.",
+    "               There is no Hub repo to point CAPTCHA_LORA_ADAPTER at, and",
+    "               `captchakraken fetch` refuses rather than 404ing at the Hub.",
+    "",
+    "Why it lives HERE and not only in a policy doc: this file is already the one",
+    "place that decides what an unpinned client downloads and what prompts it",
+    "sends. A second list of 'models you may not publish' kept somewhere else",
+    "would be a list that drifts, and the drift is silent in the direction that",
+    "costs the most. The finetune repo's publisher reads this field and REFUSES",
+    "to upload a licensed model to the Hub; check_prompt_parity.py refuses to let",
+    "`latest` be one, because an unpinned self-hoster would resolve to weights",
+    "they cannot obtain.",
+    "",
+    "`experts` is the fourth axis, and the newest. A ROUTED model is not one",
+    "adapter: Abyss is four LoRAs behind one endpoint, and the thing that picks",
+    "between them is the PROMPT FAMILY the request is about to send — grid,",
+    "pixel, video, text. See docs/MOE_LORA_DESIGN.md §11: the router is the",
+    "prompt family and it already exists, so no DOM access, no image classifier",
+    "and no cooperation from the caller is needed to reach the right expert.",
+    "",
+    "It lives here for the same reason prompt_version does. WHICH EXPERTS EXIST",
+    "IS A FACT ABOUT THE MODEL. A client that hardcoded four names would send",
+    "them to v1.2 — which serves one adapter under one name — and every request",
+    "would 404 on a model the endpoint has never heard of. ABSENT MEANS NOT",
+    "ROUTED, and that is the whole backwards-compatibility story: every model",
+    "published so far declares no `experts`, so the client sends the single",
+    "`lora_name` on every request exactly as it did before this field existed.",
+    "",
+    "An unmapped or unrecognised family degrades to the model's own",
+    "`lora_name` — the GENERALIST — never to another expert and never to an",
+    "error. The day the generation-2 `text` family reached ckgate without a",
+    "marker, refusing it cost every distorted-text solve in production for a",
+    "day; a caller prompting in their own words is the expected case for a",
+    "shipped model, not a 400.",
+    "",
+    "Each expert name must resolve — through `served_aliases` or as a repo id —",
+    "to a REGISTERED entry declaring the same `prompt_version` and the same",
+    "`pixel_budget` as the model that routes to it. check_prompt_parity.py",
+    "enforces that. It is what makes aliasing four arms onto one entry safe",
+    "rather than convenient: the four share a base, a schema and a band today",
+    "(measured, not assumed — runs 20260906-0142xx all carry prompt generation",
+    "2 and a flat 518400 band), and the day one of them trains at a different",
+    "generation or a different band the gate refuses the alias and that arm has",
+    "to graduate to an entry of its own. A divergence that resolved silently",
+    "through a shared entry would be the 2026-07-18 regression with four models",
+    "in it instead of one.",
+    "",
+    "The four arms are on the wire training as this is written (runs",
+    "20260906-0142xx) and none of them is published yet, so the `experts` map",
+    "below names weights that do not exist. That is the same deliberate",
+    "arming as `Abyss` itself — registered before it existed so the licence",
+    "gates were armed rather than retrofitted — and it costs nothing, because",
+    "an expert name only ever reaches the wire for a caller who asked for a",
+    "routed model in the first place."
   ],
   "latest": "CaptchaKraken/CaptchaKraken-Lora-v1.2",
   "models": {
@@ -61,7 +132,7 @@
         "min": 518400,
         "max": 518400
       },
-      "note": "Run 20260812-005302 (ready-to-deploy). PUBLIC on the Hub under Source-Available License v1.1, and the first published generation-2 model. TRAINED with floor 448^2 / ceiling 720^2, but MEASURED best served at a flat 720^2 — floor == ceiling, so every image arrives at exactly one size. Tier 2 overall 0.6115 -> 0.6412 across the full 1458-sample real eval and reCAPTCHA 3x3 exact 0.648 -> 0.715, against run-to-run noise of +/-0.001. Swept 2026-08-18 over 448/576/640/704/720/736/768/896/1024^2: the plateau is 704-736^2 and it falls off above 768^2, where a 400x580 portrait capture runs more than 40% past the ViT's 48x48 position grid. Note 640^2 is where that grid is exactly saturated and it scores WORSE (0.6357) — mild extrapolation plus real pixels beats staying inside the grid. Was served as `captcha-v12` while absent from this file, which resolved it to generation 1 prompts against generation-2 weights — the failure this file exists to prevent."
+      "note": "PUBLIC on the Hub under Source-Available License v1.1, and the first published generation-2 model. TRAINED with floor 448^2 / ceiling 720^2, but MEASURED best served at a flat 720^2 — floor == ceiling, so every image arrives at exactly one size and the band cannot drift. The band was chosen by sweeping the serving floor over 448/576/640/704/720/736/768/896/1024^2 and scoring each arm: the plateau is 704-736^2, and it falls off above 768^2, where a 400x580 portrait capture runs more than 40% past the ViT's 48x48 position grid. Do not \"just use the ViT's native grid\": 640^2 is where that grid is exactly saturated for a portrait capture, and it scores WORSE than 720^2 — mild position-embedding extrapolation plus real pixels beats staying inside the grid. Was served as `captcha-v12` while absent from this file, which resolved it to generation 1 prompts against generation-2 weights — the failure this file exists to prevent."
     },
     "CaptchaKraken/Twilight-v1.2-FP8": {
       "prompt_version": "2",
@@ -110,11 +181,76 @@
       "kind": "merged",
       "lora_name": "captcha",
       "note": "Ships its own prompts.json; this entry keeps it resolvable offline."
+    },
+    "CaptchaKraken/Abyss": {
+      "availability": "licensed",
+      "prompt_version": "2",
+      "kind": "lora",
+      "base_model": "Qwen/Qwen3.5-9B",
+      "lora_name": "abyss-general",
+      "pixel_budget": {
+        "min": 518400,
+        "max": 518400
+      },
+      "experts": {
+        "grid": "abyss-grid",
+        "pixel": "abyss-general",
+        "video": "abyss-video",
+        "text": "abyss-text"
+      },
+      "note": "IN DEVELOPMENT. Never published, never downloadable — see `availability`. Registered before it exists so the licence gates are armed rather than retrofitted after the first artifact is sitting on a disk: the publisher, the parity gate and `captchakraken fetch` all read this entry, and a rule added the day it is first needed is a rule that was absent on the day it was first needed. Being nameable is not being downloadable: `availability` is what refuses the weights, and the two are independent on purpose — a licence holder DOES name this model, which is why it and each of its experts has a served_aliases entry. ABYSS IS THE ROUTED 9B, NOT THE 27B. It was going to be a single Qwen3.8-27B adapter; that model was trained (run 20260903-235101) and did not earn its cost, so the product became the four-expert mixture on Qwen3.5-9B that docs/MOE_LORA_DESIGN.md §7 and §10 specify. A routed 27B may be a later generation of this same name; it would be a new entry when it exists, because the base model is what a self-hoster loads. `lora_name` is `abyss-general` rather than a fifth name: the generalist IS the fallback for any family `experts` does not map, so pointing the two at one adapter is what makes §11’s “degrade to the generalist, never 400” true with one fewer resident LoRA slot — and slots are the binding constraint (§10, five names against `--max-loras`). prompt_version 2 and the flat 518400 band are what all four arms are training at TODAY (verified against training_runs/20260906-0142xx/run.json, min_pixels == max_pixels == 518400); CONFIRM BOTH from the run records at publish time and re-record here in the publishing commit, and if any arm has diverged give that arm its own entry — check_prompt_parity.py refuses the shared alias rather than resolving it silently."
+    },
+    "CaptchaKraken/Abyss-27B": {
+      "availability": "private",
+      "prompt_version": "2",
+      "kind": "lora",
+      "base_model": "Qwen/Qwen3.8-27B",
+      "lora_revision": "main",
+      "lora_name": "abyss-27b",
+      "pixel_budget": {
+        "min": 518400,
+        "max": 518400
+      },
+      "note": "PRIVATE on the Hub. The single-adapter 27B that Abyss started as — run 20260903-235101, re-gated as 20260906-025040. NOT the routed model and not one of its arms: it is a Qwen3.8-27B, and the base model is what a self-hoster loads, so it could never share the `CaptchaKraken/Abyss` entry however similar the product story is. Kept because it is measured and it wins: Tier 2 gated_overall 0.6699 against the v1.2 baseline's 0.6456, solved 0.7113, forgetting 0.0052. What it did not win was its COST — see the `CaptchaKraken/Abyss` note — which is a statement about serving economics, not about the weights, and is exactly why the weights are archived rather than deleted. Band and generation are the run's own (min_pixels == max_pixels == 518400, PROMPT_VERSION 2), read from training_runs/20260906-025040/model.json rather than assumed."
+    },
+    "CaptchaKraken/Abyss-grid": {
+      "availability": "private",
+      "prompt_version": "2",
+      "kind": "lora",
+      "base_model": "Qwen/Qwen3.5-9B",
+      "lora_revision": "main",
+      "lora_name": "abyss-grid",
+      "pixel_budget": {
+        "min": 518400,
+        "max": 518400
+      },
+      "note": "PRIVATE on the Hub. The 'grid' expert arm of the routed CaptchaKraken/Abyss, from run 20260906-014318. Tier 2 gated_overall 0.7223 against a 0.6644 baseline, solved 0.6719, forgetting 0; Tier 3 9/10 pairs. Its run reads `blocked` for a TIER 1 failure that was this repo's own test harness (a module its sys.path insertion made unclassifiable, fixed in 79201f9aa) and not the model — the tier that judges the weights passed. It has its OWN entry rather than an alias onto the router because it now has its own weights at its own repo id, and `experts` names what goes ON THE WIRE — an alias would resolve a real, separately fetchable adapter to another model's entry. It still declares the router's prompt generation and pixel band, which is what check_prompt_parity.py requires of every expert and what makes the mixture coherent."
+    },
+    "CaptchaKraken/Abyss-text": {
+      "availability": "private",
+      "prompt_version": "2",
+      "kind": "lora",
+      "base_model": "Qwen/Qwen3.5-9B",
+      "lora_revision": "main",
+      "lora_name": "abyss-text",
+      "pixel_budget": {
+        "min": 518400,
+        "max": 518400
+      },
+      "note": "PRIVATE on the Hub. The 'text' expert arm of the routed CaptchaKraken/Abyss, from run 20260906-014253. Tier 2 gated_overall 0.8750 against a 0.8375 baseline, solved 0.8750, forgetting 0; Tier 3 5/6 pairs. `passed-partial` because the run is type-narrowed by construction — an arm trains on its own families — which disqualifies `ready-to-deploy` and says nothing bad about it. It has its OWN entry rather than an alias onto the router because it now has its own weights at its own repo id, and `experts` names what goes ON THE WIRE — an alias would resolve a real, separately fetchable adapter to another model's entry. It still declares the router's prompt generation and pixel band, which is what check_prompt_parity.py requires of every expert and what makes the mixture coherent."
     }
   },
   "served_aliases": {
-    "_comment": "A hosted endpoint serves a bare name, not a repo id. Map it back so prompt resolution works for callers who only ever see the alias.",
-    "captcha": "CaptchaKraken/CaptchaKraken_v1.1",
-    "captcha-v12": "CaptchaKraken/CaptchaKraken-Lora-v1.2"
+    "_comment": "A hosted endpoint serves a bare name, not a repo id. Map it back so prompt resolution works for callers who only ever see the alias. api.captchakraken.com now serves ONE model behind the permanent public name `captcha`, whatever the caller sends, so `captcha` means whichever adapter is current there — today CaptchaKraken-Lora-v1.2 — and NOT the v1.1 weights that share the name as a local vLLM alias. Self-hosters resolve by repo id via CAPTCHA_LORA_ADAPTER and are unaffected. Move this in the same change as the gateway's CKGATE_UPSTREAM_MODEL or the hosted model answers a prompt generation it was not trained on.",
+    "captcha": "CaptchaKraken/CaptchaKraken-Lora-v1.2",
+    "captcha-v12": "CaptchaKraken/CaptchaKraken-Lora-v1.2",
+    "_comment_abyss": "`abyss` is here for the OPPOSITE reason to the two above, and it is not a contradiction of `availability: licensed`. An alias says which model a served NAME means; availability says whether its weights can be downloaded. A licence holder does name this model — the hosted API accepts it from a licensed key and lists it to them on /v1/models so their SDK can — and without this line `canonical_model_id('abyss')` is None, so their prompts resolve through the `latest` fallback: the exact model/generation mispairing this file exists to prevent, silent, and only accidentally right while `latest` happens to share the generation. It does NOT make the weights fetchable; `captchakraken fetch` reads availability and refuses this name, which is also the clear error a self-hoster who typed it deserves.",
+    "abyss": "CaptchaKraken/Abyss",
+    "_comment_abyss_experts": "The four expert arms. These are the names that go ON THE WIRE — a routed request for a grid names `abyss-grid`, never `abyss` — so without these lines `canonical_model_id` returns None for the string the client actually sent, and prompt resolution falls through to the `latest` fallback on every routed solve. That is the mispairing `abyss` itself is here to prevent, one level down and four times over. Aliasing four arms onto one entry rather than giving each its own is deliberate and CHECKED: they share a base, a prompt generation and a pixel band today, and check_prompt_parity.py requires every expert name to resolve to a registered entry declaring the SAME prompt_version and pixel_budget as the router — so the day an arm trains at another generation or another band, the gate refuses the alias and that arm has to graduate to an entry of its own.",
+    "abyss-grid": "CaptchaKraken/Abyss-grid",
+    "abyss-general": "CaptchaKraken/Abyss",
+    "abyss-video": "CaptchaKraken/Abyss",
+    "abyss-text": "CaptchaKraken/Abyss-text",
+    "abyss-27b": "CaptchaKraken/Abyss-27B"
   }
 }