captchakraken 2.8.0 → 3.0.0

package/python/src/captchakraken/kinds.py

@@ -0,0 +1,152 @@
+"""Every closed set of names the two ports agree on. Mirrored in js/src/kinds.ts; keep both in the same order."""
+from enum import StrEnum
+
+
+class Vendor(StrEnum):
+    """`puzzle_source` everywhere. UNKNOWN must stay permissive: GeeTest and Prosopo report it, and so does the offline grader."""
+
+    HCAPTCHA = "hcaptcha"
+    RECAPTCHA = "recaptcha"
+    TURNSTILE = "turnstile"
+    GEETEST = "geetest"
+    TENCENT = "tencent"
+    YIDUN = "yidun"
+    YANDEX = "yandex"
+    LEMIN = "lemin"
+    PROSOPO = "prosopo"
+    MTCAPTCHA = "mtcaptcha"
+    BOTDETECT = "botdetect"
+    UNKNOWN = "unknown"
+
+
+class ActionKind(StrEnum):
+    CLICK = "click"
+    DRAG = "drag"
+    TYPE = "type"
+    WAIT = "wait"
+    DONE = "done"
+
+
+class PixelAnswerKind(StrEnum):
+    """What the pixel parser reads off the model's text before it becomes an action."""
+
+    CLICK = "click"
+    DRAG = "drag"
+    SLIDE = "slide"
+    TYPE = "type"
+
+
+class RetryMode(StrEnum):
+    MISSED_TILES = "missed-tiles"
+
+
+class SettleVerdict(StrEnum):
+    SETTLED = "settled"
+    ANIMATED = "animated"
+    TIMEOUT = "timeout"
+
+
+class PaintVerdict(StrEnum):
+    PAINTED = "painted"
+    BLANK = "blank"
+    UNKNOWN = "unknown"
+
+
+class KeyframeMode(StrEnum):
+    """EVEN means the slicer could not prove recurrence, not that the board is still."""
+
+    STATIC = "static"
+    CYCLE = "cycle"
+    EVEN = "even"
+
+
+class RecaptchaBanner(StrEnum):
+    SELECT_MORE = "select-more"
+    DYNAMIC_MORE = "dynamic-more"
+    REJECTED = "rejected"
+
+
+class PromptFamily(StrEnum):
+    """One expert per family; `pixel` is spelled to match ckgate's prompt markers."""
+
+    PIXEL = "pixel"
+    GRID = "grid"
+    VIDEO = "video"
+    TEXT = "text"
+
+
+class Availability(StrEnum):
+    """PRIVATE is not a softer LICENSED: refusing a private model early would stop an authorised token from fetching weights."""
+
+    PUBLIC = "public"
+    PRIVATE = "private"
+    LICENSED = "licensed"
+
+
+class HumanizationMode(StrEnum):
+    MOUSE = "mouse"
+    MOBILE = "mobile"
+    NONE = "none"
+
+
+class PauseKind(StrEnum):
+    TAP = "tap"
+    BETWEEN = "between"
+    GRAB = "grab"
+    DROP = "drop"
+    PROBE = "probe"
+    SETTLE = "settle"
+    KEY = "key"
+
+
+class Outcome(StrEnum):
+    SOLVED = "solved"
+    FAILED = "failed"
+
+
+class Phase(StrEnum):
+    """Timing phases. Only INFERENCE and MOUSE are productive; everything else is waiting."""
+
+    INFERENCE = "inference"
+    MOUSE = "mouse"
+    SCREENSHOT = "screenshot"
+    DETECT = "detect"
+    SETTLE = "settle"
+    BURST = "burst"
+    GRID = "grid"
+    GRID_LOAD = "grid-load"
+    FADE_WAIT = "fade-wait"
+    BOARD_PAINT = "board-paint"
+    HCAPTCHA_IMAGES = "hcaptcha-images"
+    AWAIT_NEXT_ROUND = "await-next-round"
+    AWAIT_VERDICT = "await-verdict"
+    POST_SUBMIT_DELAY = "post-submit-delay"
+
+
+class FrameRole(StrEnum):
+    CHECKBOX = "checkbox"
+    CHALLENGE = "challenge"
+    UNKNOWN = "unknown"
+
+
+class LabelPosition(StrEnum):
+    TOP_LEFT = "top-left"
+    CENTER = "center"
+    TOP_RIGHT = "top-right"
+    BOTTOM_LEFT = "bottom-left"
+    BOTTOM_RIGHT = "bottom-right"
+
+
+class ErrorCode(StrEnum):
+    """The hosted API's machine-readable codes. Unknown codes still carry the server's message through; this is not a filter."""
+
+    MISSING_API_KEY = "missing_api_key"
+    INVALID_API_KEY = "invalid_api_key"
+    ACCOUNT_SUSPENDED = "account_suspended"
+    INSUFFICIENT_CREDITS = "insufficient_credits"
+    RATE_LIMITED = "rate_limited"
+    SOLVE_ABANDONED = "solve_abandoned"
+    UNRECOGNIZED_PROMPT = "unrecognized_prompt"
+    INVALID_REQUEST = "invalid_request"
+    REQUEST_TOO_LARGE = "request_too_large"
+    UPSTREAM_UNAVAILABLE = "upstream_unavailable"

package/python/src/captchakraken/models.json

@@ -62,10 +62,10 @@
     "               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.",
+    "               a 401 instead of a model — and the release parity gate says so.",
     "",
-    "  \"licensed\" — NOT downloadable by anyone. Reachable only through",
-    "               api.captchakraken.com, or by a holder of a licence we issue.",
+    "  \"licensed\" — NOT downloadable without a licence we issue. Served to",
+    "               every account through api.captchakraken.com.",
     "               There is no Hub repo to point CAPTCHA_LORA_ADAPTER at, and",
     "               `captchakraken fetch` refuses rather than 404ing at the Hub.",
     "",
@@ -73,8 +73,8 @@
     "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",
+    "costs the most. The publisher reads this field and REFUSES",
+    "to upload a licensed model to the Hub; the release parity gate refuses to let",
     "`latest` be one, because an unpinned self-hoster would resolve to weights",
     "they cannot obtain.",
     "",
@@ -102,7 +102,7 @@
     "",
     "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",
+    "`pixel_budget` as the model that routes to it. The release parity gate",
     "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",
@@ -121,6 +121,28 @@
     "routed model in the first place."
   ],
   "latest": "CaptchaKraken/CaptchaKraken-Lora-v1.2",
+  "_comment_hosted_default": [
+    "WHAT THE HOSTED ENDPOINT IS ASKED FOR, which is not what gets DOWNLOADED.",
+    "",
+    "`latest` is the download default: the repo a self-hoster pulls and serves.",
+    "`hosted_default` is the served NAME a client sends when it is talking to",
+    "our API. They were one field until Abyss, and one field cannot express",
+    "this: Abyss is hosted-only, so naming it as `latest` would point every",
+    "self-hoster at weights they are not licensed to download, while leaving it",
+    "out would mean the hosted endpoint never serves the better model.",
+    "",
+    "This is also what makes the rollout version-gated without a version",
+    "header. A client that ships this file asks for `abyss`; one that predates",
+    "it asks for whatever its own registry says and keeps getting v1.2. Nothing",
+    "server-side has to know which is which.",
+    "",
+    "Only consulted for an endpoint that is OURS \u2014 see config.is_hosted_endpoint.",
+    "A self-hosted vLLM, local or remote, resolves from `latest` exactly as",
+    "before, because it serves whatever its operator loaded and asking it for",
+    "`abyss` would 404."
+  ],
+  "hosted_default": "CaptchaKraken/Abyss",
+  
   "models": {
     "CaptchaKraken/CaptchaKraken-Lora-v1.2": {
       "prompt_version": "2",
@@ -132,7 +154,7 @@
         "min": 518400,
         "max": 518400
       },
-      "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."
+      "note": "Generation 2, and the first published one. Trained over a range of input sizes but 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 and scoring each setting; the plateau is 704-736^2 and it falls off above 768^2, where a portrait capture runs well past the vision tower's position grid. Note that the vision tower's native grid is NOT the best setting — mild position-embedding extrapolation over real pixels beats staying inside the grid."
     },
     "CaptchaKraken/Twilight-v1.2-FP8": {
       "prompt_version": "2",
@@ -142,7 +164,7 @@
         "min": 518400,
         "max": 518400
       },
-      "note": "CaptchaKraken-Lora-v1.2 merged into Qwen/Qwen3.5-9B at FP8-dynamic. The weights the hosted API answers with. Generation 2, same band as the adapter it is made from: a merge that resolved to a different prompt generation or a different pixel budget than its own LoRA would be the 2026-07-18 regression with extra steps."
+      "note": "CaptchaKraken-Lora-v1.2 merged into Qwen/Qwen3.5-9B at FP8-dynamic. Generation 2, same pixel band as the adapter it is made from — a merge that resolved to a different prompt generation or a different band than its own LoRA is exactly the mispairing this file exists to prevent."
     },
     "CaptchaKraken/Sunlight-v1.2-AWQ-4bit": {
       "prompt_version": "2",
@@ -154,13 +176,23 @@
       },
       "note": "CaptchaKraken-Lora-v1.2 merged into Qwen/Qwen3.5-9B at AWQ 4-bit. Generation 2. Quantization changes the weights, not the schema they answer in, so the prompt generation and the pixel budget are the adapter's."
     },
+    "CaptchaKraken/CaptchaKraken-v1.2-GGUF": {
+      "prompt_version": "2",
+      "kind": "merged",
+      "lora_name": "CaptchaKraken/CaptchaKraken-v1.2-GGUF",
+      "pixel_budget": {
+        "min": 518400,
+        "max": 518400
+      },
+      "note": "CaptchaKraken-Lora-v1.2 merged into Qwen/Qwen3.5-9B and converted to GGUF, for llama.cpp and Ollama. ONE entry covers every quantisation in that repo: Q4_K_M, Q8_0 and F16 differ in weight precision, not in the schema they answer or the resolution they read at, so all three share this generation and this band. The vision tower ships beside them as a separate F16 projector and is never quantised — a runtime that loads the weights without it is text-only and cannot see a puzzle at all. Ollama names a model after whatever it was pulled or created as, and that name is what reaches us as `model`; an unrecognised one resolves through CAPTCHA_LORA_ADAPTER instead, which is why the self-hosting guide sets it."
+    },
     "CaptchaKraken/CaptchaKraken_v1.1": {
       "prompt_version": "1",
       "kind": "lora",
       "base_model": "RedHatAI/Qwen3.5-9B-FP8-dynamic",
       "lora_revision": "main",
       "lora_name": "captcha",
-      "note": "Currently served in production. PRIVATE on the Hub, so prompts.json can never be fetched for it — this entry is the only thing that maps it to a prompt generation."
+      "note": "Generation 1. Private on the Hub, so prompts.json cannot be fetched for it — this entry is the only thing that maps it to a prompt generation."
     },
     "CaptchaKraken/CaptchaKrakenV1_Lora": {
       "prompt_version": "1",
@@ -168,19 +200,19 @@
       "base_model": "RedHatAI/Qwen3.5-9B-FP8-dynamic",
       "lora_revision": "main",
       "lora_name": "captcha",
-      "note": "Published before prompts.json existed — no such file in the repo, so it resolves from here."
+      "note": "Generation-1 LoRA on Qwen3.5-9B. Superseded by v1.2; kept registered so an existing pin keeps resolving to the prompts it was trained on."
     },
     "CaptchaKraken/Sunlight-AWQ-4bit": {
       "prompt_version": "1",
       "kind": "merged",
       "lora_name": "captcha",
-      "note": "Ships its own prompts.json; this entry keeps it resolvable offline."
+      "note": "Generation 1 merged into the base model at AWQ 4-bit."
     },
     "CaptchaKraken/Twilight-FP8": {
       "prompt_version": "1",
       "kind": "merged",
       "lora_name": "captcha",
-      "note": "Ships its own prompts.json; this entry keeps it resolvable offline."
+      "note": "Generation 1 merged into the base model at FP8-dynamic."
     },
     "CaptchaKraken/Abyss": {
       "availability": "licensed",
@@ -198,7 +230,7 @@
         "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."
+      "note": "A routed mixture of four expert LoRAs on Qwen3.5-9B — grid, pixel, video and text — selected by prompt family. Hosted only: `availability` refuses the weights, and being nameable is not being downloadable. The current client names this model against our endpoint, which is why it and each of its arms has a served_aliases entry. `lora_name` is `abyss-general` rather than a fifth name because the generalist IS the fallback for any family `experts` does not map, so the two point at one adapter and the mixture needs one fewer resident LoRA slot."
     },
     "CaptchaKraken/Abyss-27B": {
       "availability": "private",
@@ -211,7 +243,7 @@
         "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."
+      "note": "A single-adapter Qwen3.8-27B. NOT the routed Abyss and not one of its arms — the base model is what a self-hoster loads, so it could never share that entry. Archived rather than served."
     },
     "CaptchaKraken/Abyss-grid": {
       "availability": "private",
@@ -224,7 +256,7 @@
         "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."
+      "note": "The 'grid' expert arm of the routed CaptchaKraken/Abyss. It has its own entry rather than an alias onto the router because it has its own weights at its own repo id, and `experts` names what goes on the wire. It declares the router's prompt generation and pixel band, which is what the parity gate requires of every arm and what makes the mixture coherent."
     },
     "CaptchaKraken/Abyss-text": {
       "availability": "private",
@@ -237,19 +269,45 @@
         "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."
+      "note": "The 'text' expert arm of the routed CaptchaKraken/Abyss. Own entry, own weights, and it declares the router's prompt generation and pixel band — see CaptchaKraken/Abyss-grid."
+    },
+    "CaptchaKraken/Abyss-video": {
+      "availability": "private",
+      "prompt_version": "2",
+      "kind": "lora",
+      "base_model": "Qwen/Qwen3.5-9B",
+      "lora_revision": "main",
+      "lora_name": "abyss-video",
+      "pixel_budget": {
+        "min": 518400,
+        "max": 518400
+      },
+      "note": "The 'video' expert arm of the routed CaptchaKraken/Abyss. Own entry, own weights, and it declares the router's prompt generation and pixel band — see CaptchaKraken/Abyss-grid."
+    },
+    "CaptchaKraken/Abyss-general": {
+      "availability": "private",
+      "prompt_version": "2",
+      "kind": "lora",
+      "base_model": "Qwen/Qwen3.5-9B",
+      "lora_revision": "main",
+      "lora_name": "abyss-general",
+      "pixel_budget": {
+        "min": 518400,
+        "max": 518400
+      },
+      "note": "The 'pixel' expert arm of the routed CaptchaKraken/Abyss and its generalist fallback: the router's own `lora_name` names this entry. Own entry, own weights, and it declares the router's prompt generation and pixel band — see CaptchaKraken/Abyss-grid."
     }
   },
   "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. 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.",
+    "_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. The hosted API serves one model behind the permanent public name `captcha`, whatever the caller sends, so `captcha` means whichever adapter is current there. Self-hosters resolve by repo id via CAPTCHA_LORA_ADAPTER and are unaffected. Move this in the same change as the gateway's 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.",
+    "_comment_abyss": "An alias says which model a served NAME means; `availability` says whether its weights can be downloaded. The two are independent. The current client names this model against our endpoint — the hosted API serves it to every account and lists it on /v1/models — and without this line prompt resolution falls through to the `latest` fallback, which is the model/generation mispairing this file exists to prevent. It does not make the weights fetchable.",
     "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.",
+    "_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 prompt resolution falls through to `latest` on every routed solve. Aliasing the arms onto one entry is deliberate and checked: they share a base, a prompt generation and a pixel band, and the parity gate 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 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-general": "CaptchaKraken/Abyss-general",
+    "abyss-video": "CaptchaKraken/Abyss-video",
     "abyss-text": "CaptchaKraken/Abyss-text",
     "abyss-27b": "CaptchaKraken/Abyss-27B"
   }