captchakraken 2.6.1 → 2.9.0

package/python/src/captchakraken/pinned_model.json

@@ -12,8 +12,9 @@
     "serving prompt fails CI until someone consciously re-pins \u2014 which forces",
     "the question 'does the pinned adapter still expect this prompt?'.",
     "",
-    "To ship a new adapter: update lora_adapter/lora_revision, re-run the Tier 2",
-    "static-image gate against it, and update prompt_sha256 if the prompts moved."
+    "To ship a new adapter: update lora_adapter/lora_revision, re-run the",
+    "static-image accuracy gate against it, and update prompt_sha256 if the",
+    "prompts moved."
   ],
   "base_model": "RedHatAI/Qwen3.5-9B-FP8-dynamic",
   "lora_adapter": "CaptchaKraken/CaptchaKraken-Lora-v1.2",

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.
@@ -124,6 +124,14 @@ _CLIENT_ENV = "CAPTCHA_KRAKEN_CLIENT"
 _SESSION_HEADER = "X-CK-Session"
 _SESSION_ENV = "CAPTCHA_KRAKEN_SESSION"
 
+# Report whether the widget accepted, once per solve. "0" turns it off.
+#
+# ON by default because the report is what makes a failed solve improvable, and
+# because it is the only way a hosted account's failures can be found at all.
+# Opting out here stops the CLIENT sending it; `captureOptOut` on the account is
+# the server-side half, and either one alone is enough to keep nothing.
+_REPORT_OUTCOME_ENV = "CAPTCHA_REPORT_OUTCOME"
+
 # Arbitrary extra headers, as "Name: value" pairs separated by newlines or
 # commas. Empty and absent by default.
 #
@@ -266,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:
@@ -275,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."""
 
@@ -284,6 +352,7 @@ class ActionPlanner:
         debug_callback: Optional[Any] = None,
         base_url: Optional[str] = None,
         api_key: Optional[str] = None,
+        expert: Optional[str] = None,
         **_: Any,
     ):
         self.debug_callback = debug_callback
@@ -294,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
@@ -309,9 +387,102 @@ class ActionPlanner:
         # the same key: an adapter reads a puzzle at the pixel band it trained
         # under. Resolved once per planner — see the note above.
         self.pixel_budget = prompts.pixel_budget(_prompt_key)
+        # WHICH ADAPTER answers each prompt family. Empty for every model that
+        # is not routed, which is every model published so far — `_model_for`
+        # then returns `self.model` for every request and the wire is unchanged.
+        #
+        # Resolved once, like the two above, and for a stronger reason: the pin
+        # is validated here, so `--expert grid` against a single-adapter model
+        # fails when the solver is BUILT rather than on the first grid it meets.
+        self.expert = (expert if expert is not None
+                       else prompts.expert_pin())
+        self.experts = prompts.experts(_prompt_key)
+        if self.expert:
+            # Raises on an unknown family, and on a pin against an unrouted
+            # model. Both are configuration errors, and a benchmark that
+            # quietly measured the generalist while reporting an expert is the
+            # exact class of silent mispairing models.json exists to prevent.
+            prompts.route(_prompt_key, None, pin=self.expert)
         # Auto-start a local vLLM server on the first request if one isn't up
         # (no-op for a healthy or remote endpoint). Guarded so we only try once.
         self._server_ensured = False
+        # ONE connection, reused for every round of every solve this planner
+        # serves. `requests.post` opens a fresh TCP connection each call — and
+        # to a hosted endpoint a TLS handshake with it. Measured against the
+        # gate's own endpoint: 258ms per request connectionless vs 144ms
+        # pooled, so every inference was paying ~110ms to re-dial a server it
+        # had just finished talking to. A multi-round grid pays it per round.
+        #
+        # The planner is per-PageSolver and a PageSolver is reusable across
+        # solves, so a caller who keeps one keeps the connection warm too.
+        self._http = requests.Session()
+        # Latched off by the first 404 — see `report_outcome`.
+        self._outcome_supported = True
+
+    def _model_for(self, family: Optional[str]) -> str:
+        """The `model` string for a request in `family`.
+
+        `self.model` whenever the model is not routed, so a caller may pass a
+        family unconditionally. A routed model with no expert for this family
+        degrades to the generalist — never to another expert, never to an
+        error (docs/MOE_LORA_DESIGN.md §11).
+        """
+        if not self.experts:
+            return self.model
+        return prompts.route(self.model, family, pin=self.expert) or self.model
+
+    # ── the solve's own verdict, sent back ─────────────────────────────────
+    #
+    # THE ONE THING THE SERVER CANNOT SEE. A wrong answer reaches the gateway as
+    # a 200 with well-formed JSON in it; only this driver watched the widget.
+    # Without this report the hosted API cannot tell a solved captcha from a
+    # failed one, and the failures — the exact boards the model is worst at, on
+    # real sites — are the one dataset that cannot be collected any other way.
+    #
+    # BEST-EFFORT, ALWAYS. It runs after the solve is over and its result is
+    # already decided, so nothing it does can change the answer the caller gets.
+    # Every failure is swallowed: a self-hosted vLLM has no such route, a
+    # network blip is not the caller's problem, and an exception here would turn
+    # a successful solve into a raised one.
+    #
+    # ONE 404 IS ENOUGH. A self-hosted endpoint answers 404 forever, so the
+    # first one latches this off for the life of the planner rather than paying
+    # a round trip per solve to be told the same thing again.
+    _OUTCOME_PATH = "/solve-outcome"
+    _OUTCOME_TIMEOUT_S = 3.0
+
+    def report_outcome(self, session_id: Optional[str], solved: bool) -> bool:
+        """Tell the API whether the widget accepted. True if it was delivered.
+
+        Never raises. The return value is for tests and for `--debug`; no caller
+        should branch on it.
+        """
+        if not session_id or not self._outcome_supported:
+            return False
+        if os.getenv(_REPORT_OUTCOME_ENV, "1") == "0":
+            return False
+        url = f"{self.base_url}{self._OUTCOME_PATH}"
+        try:
+            resp = self._http.post(
+                url,
+                headers={
+                    "Authorization": f"Bearer {self.api_key}",
+                    "Content-Type": "application/json",
+                },
+                json={"session": session_id, "solved": bool(solved)},
+                timeout=self._OUTCOME_TIMEOUT_S,
+            )
+        except Exception as exc:  # noqa: BLE001 — see the note above
+            self._log(f"outcome report failed: {exc}")
+            return False
+        if resp.status_code == 404:
+            # Not an error: this endpoint does not serve the route. Stop asking.
+            self._outcome_supported = False
+            self._log("outcome reporting: endpoint has no /solve-outcome; disabled")
+            return False
+        ok = 200 <= resp.status_code < 300
+        self._log(f"outcome report {session_id} solved={solved} -> {resp.status_code}")
+        return ok
 
     def _log(self, message: str) -> None:
         if DEBUG:
@@ -319,11 +490,14 @@ class ActionPlanner:
         if self.debug_callback:
             self.debug_callback(f"[Planner] {message}")
 
-    def _chat_with_image(self, prompt: str, image_path: str, max_tokens: int = 512) -> str:
-        return self._chat_with_images(prompt, [image_path], max_tokens=max_tokens)
+    def _chat_with_image(self, prompt: str, image_path: str, max_tokens: int = 512,
+                         family: Optional[str] = None) -> str:
+        return self._chat_with_images(prompt, [image_path], max_tokens=max_tokens,
+                                      family=family)
 
     def _chat_with_images(
-        self, prompt: str, image_paths: List[str], max_tokens: int = 512
+        self, prompt: str, image_paths: List[str], max_tokens: int = 512,
+        family: Optional[str] = None,
     ) -> str:
         """One request carrying N images followed by the prompt.
 
@@ -355,8 +529,13 @@ 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": self.model,
+            "model": model,
             "messages": messages,
             "temperature": 0,
             "max_tokens": max_tokens,
@@ -365,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(),
         }
 
@@ -387,11 +572,11 @@ class ActionPlanner:
             self._server_ensured = True
 
         url = f"{self.base_url}/chat/completions"
-        self._log(f"POST {url} model={self.model} max_tokens={max_tokens} "
+        self._log(f"POST {url} model={model} max_tokens={max_tokens} "
                   f"images={len(parts)}")
 
         with timed("planner.chat"):
-            resp = requests.post(url, headers=headers, json=payload, timeout=120)
+            resp = self._http.post(url, headers=headers, json=payload, timeout=120)
 
         # Surface auth / billing / server errors as something the reader can act
         # on, instead of letting resp.json() blow up with a cryptic "Expecting
@@ -531,7 +716,8 @@ class ActionPlanner:
                   "Return the complete list of cell numbers that match the description, "
                   "including any matches you may have overlooked."
             )
-        raw = self._chat_with_image(prompt, image_path, max_tokens=128)
+        raw = self._chat_with_image(prompt, image_path, max_tokens=128,
+                                    family="grid")
         out = self._normalize_grid(self._parse_json(raw), total)
         self._log(f"grid selection -> {out}")
         return out
@@ -592,7 +778,8 @@ class ActionPlanner:
         into ClickAction / DragAction / TypeAction.
         """
         prompt = self.prompts.text_prompt() if text_mode else self.prompts.action_prompt
-        raw = self._chat_with_image(prompt, image_path, max_tokens=512)
+        raw = self._chat_with_image(prompt, image_path, max_tokens=512,
+                                    family="text" if text_mode else "pixel")
         data = self._parse_json(raw)
         actions = self._normalize_pixel(data)
         self._log(f"pixel actions -> {actions}")
@@ -618,7 +805,8 @@ class ActionPlanner:
         # so this raises a clear error there instead of sending a v1 model a
         # keyframe request it was never trained to read.
         prompt = self.prompts.video_prompt(len(keyframe_paths))
-        raw = self._chat_with_images(prompt, list(keyframe_paths), max_tokens=512)
+        raw = self._chat_with_images(prompt, list(keyframe_paths), max_tokens=512,
+                                     family="video")
         data = self._parse_json(raw)
         actions = self._normalize_pixel(data)
         frame = self._normalize_frame(data, len(keyframe_paths))

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
@@ -247,6 +247,80 @@ def canonical_model_id(model: Optional[str]) -> Optional[str]:
     return alias if isinstance(alias, str) else None
 
 
+# ── availability: can these weights be obtained at all? ─────────────────────
+#
+# Same registry, same reason as prompt_version and pixel_budget: it is a fact
+# about the MODEL, and the one place that already decides what an unpinned
+# client downloads. See models.json's header comment.
+
+PUBLIC = "public"
+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 — 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
+#: release gate reads this file by AST so it can run in a training venv with no
+#: client installed, and `ast.literal_eval` cannot follow a name. A tuple of
+#: names reads as "unset" to the gate, which is the check silently not running.
+#: `tests/test_prompt_registry.py` pins that all four constants agree.
+AVAILABILITIES = ("public", "private", "licensed")
+
+
+def availability(model: Optional[str]) -> str:
+    """`"public"`, `"private"` or `"licensed"` for `model`. Absent means public.
+
+    The three answer ONE question — can these weights be obtained, and by whom:
+
+      public     on the Hub, by anyone.
+      private    on the Hub in a PRIVATE repo. The bytes exist and `fetch`
+                 pulls them, but only for a token this account has authorised.
+                 Everyone else gets 401/404 from the Hub, which is the right
+                 answer and not something to pre-empt with a refusal.
+      licensed   no Hub repo at all. Hosted API or a licence we issue.
+
+    `private` is the newest and it is NOT a softer `licensed`. They differ in
+    what an authorised holder can do, which is the whole reason the field is
+    not a boolean: a licensed model has nothing to download however good your
+    credentials are, so refusing early is a KINDNESS — it replaces a
+    `RepositoryNotFoundError` that reads as "you are not logged in" with the
+    truth. Doing the same to a private model would be a lie, and would make our
+    own admin token unable to pull weights it is entitled to.
+
+    An unregistered model is public too: it is not ours, and refusing to
+    download a stranger's adapter because we have never heard of it would break
+    every self-hoster who trained their own.
+    """
+    entry = registered_models().get(canonical_model_id(model) or "") or {}
+    value = entry.get("availability")
+    return value if isinstance(value, str) and value else PUBLIC
+
+
+def is_licensed(model: Optional[str]) -> bool:
+    """True if these weights are NOT OBTAINABLE AT ALL — hosted API or licence.
+
+    Fails CLOSED on an unrecognised value. A registry that says `"licenced"`
+    must not hand out a proprietary model because of a spelling.
+
+    False for `private`: those weights are downloadable, by the holder of a
+    token we authorised. Proprietary and unobtainable are different facts, and
+    this function answers the second one — `requires_auth` answers the first.
+    """
+    return availability(model) not in (PUBLIC, PRIVATE)
+
+
+def requires_auth(model: Optional[str]) -> bool:
+    """True if pulling these weights needs a token we authorised.
+
+    Separate from `is_licensed` because the two diverge exactly where it
+    matters: a `private` model needs a token AND can be fetched with one, a
+    `licensed` model needs no token because there is nothing to fetch.
+    """
+    return availability(model) == PRIVATE
+
+
 # ── prompt sets ─────────────────────────────────────────────────────────────
 
 @dataclass
@@ -479,6 +553,114 @@ def pixel_budget(model: Optional[str]) -> PixelBudget:
     return DEFAULT_PIXEL_BUDGET
 
 
+# ─── expert routing: WHICH ADAPTER answers this prompt family ───────────────
+#
+# Same registry, same reason again, one more axis. 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").
+#
+# It lives HERE rather than in the solver for the 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 published model today declares no `experts`, so `experts()` returns {},
+# `route()` returns the name the caller already had, and the bytes on the wire
+# are identical.
+
+EXPERT_ENV = "CAPTCHA_EXPERT"
+
+#: The prompt families, which are also the only keys an `experts` map may
+#: carry. `pixel` is the click/drag family — `PromptSet.action_prompt` — and is
+#: spelled that way rather than `action_pixel` because it is what ckgate's
+#: PROMPT_MARKERS already calls it, and two spellings of one router is how a
+#: family ends up unrouted on one side.
+PROMPT_FAMILIES = ("pixel", "grid", "video", "text")
+
+
+def experts(model: Optional[str]) -> Dict[str, str]:
+    """Prompt family -> served adapter name, for a ROUTED model.
+
+    `{}` for anything that is not routed, which is every model published so
+    far. Callers apply it unconditionally; an empty map is a no-op.
+
+    Unknown family keys are DROPPED rather than passed through. A typo in the
+    registry would otherwise be a name nothing ever selects — invisible,
+    because the fallback below is a working solve at a slightly worse score,
+    which is the exact failure mode this whole module exists to prevent.
+    """
+    repo_id = canonical_model_id(model)
+    entry = (registered_models().get(repo_id) or {}) if repo_id else {}
+    mapping = entry.get("experts")
+    if not isinstance(mapping, dict):
+        return {}
+    out = {}
+    for family in PROMPT_FAMILIES:
+        name = mapping.get(family)
+        if isinstance(name, str) and name:
+            out[family] = name
+    for key in mapping:
+        if key not in PROMPT_FAMILIES and not str(key).startswith("_"):
+            _warn(f"model {repo_id!r} declares an expert for unknown prompt "
+                  f"family {key!r}; have {', '.join(PROMPT_FAMILIES)}. It will "
+                  "never be selected.")
+    return out
+
+
+def route(model: Optional[str], family: Optional[str], *,
+          pin: Optional[str] = None) -> str:
+    """The `model` string to put on the wire for one request.
+
+    `model` is what the caller would have sent — a served name or a repo id —
+    and is returned unchanged whenever the model is not routed, which is what
+    keeps every existing deployment byte-identical.
+
+    `pin` forces one family for every request, whatever `family` says. That is
+    what a gate wants: serve one arm, grade the types it owns, serve the next.
+    An unknown `pin` RAISES, because a benchmark that silently measured the
+    generalist and reported it as the expert is a number nobody can catch.
+
+    An unrecognised or unmapped `family` degrades to `model` — the generalist —
+    never to another expert and never to an error. A caller prompting in their
+    own words is the expected case for a shipped model, and the day the
+    generation-2 `text` family reached ckgate without a marker, refusing it cost
+    every distorted-text solve in production for a day.
+    """
+    if pin is not None:
+        pin = pin.strip()
+    if pin:
+        if pin not in PROMPT_FAMILIES:
+            raise ValueError(
+                f"unknown expert {pin!r}; have {', '.join(PROMPT_FAMILIES)}")
+        family = pin
+    mapping = experts(model)
+    if not mapping:
+        if pin:
+            raise ValueError(
+                f"expert {pin!r} was requested but model {model!r} declares no "
+                "experts — it serves one adapter under one name. Drop the "
+                "expert, or point the client at a routed model.")
+        return model or ""
+    return mapping.get(family or "") or model or ""
+
+
+def _env_str(name: str) -> Optional[str]:
+    """Like `_env_int`, and read through the same indirection for the same
+    second reason: `test_public_contract.py` finds environment variables by
+    grepping for `os.environ.get(<NAME>)`, so naming the CONSTANT there records
+    `EXPERT_ENV` in the published env list as though it were a variable anyone
+    could set. The literal is picked up from the assignment above instead."""
+    return (os.environ.get(name) or "").strip() or None
+
+
+def expert_pin() -> Optional[str]:
+    """`CAPTCHA_EXPERT`, or None. Empty and unset are the same thing."""
+    return _env_str(EXPERT_ENV)
+
+
 def clear_cache() -> None:
     _cache.clear()
     global _REGISTRY

package/python/src/captchakraken/server_manager.py

@@ -170,11 +170,16 @@ def ensure_server(base_url: "str | None" = None) -> None:
     """
     base_url = base_url or config.base_url()
 
-    if is_healthy(base_url):
-        return
+    # REMOTE FIRST. There is nothing to ensure about a server we do not manage,
+    # so asking it for /health before deciding that is a round trip spent to
+    # reach a `return` — and up to `timeout=2.0` of it against a hosted gateway
+    # that serves no /health at all. Paid once per ActionPlanner, which for a
+    # caller using `solve_captcha_on_page` is once per solve.
     if not is_local(base_url):
-        # Remote server we don't manage: let the actual request raise a clear
-        # connection error rather than silently trying to boot vLLM locally.
+        # Let the actual request raise a clear connection error rather than
+        # silently trying to boot vLLM locally.
+        return
+    if is_healthy(base_url):
         return
     if not config.autostart_enabled():
         return