captchakraken 2.8.0 → 3.0.0

package/python/src/captchakraken/config.py

@@ -1,28 +1,3 @@
-"""
-Central, model-agnostic configuration for CaptchaKraken.
-
-Every model-specific value lives here and is overridable via environment
-variables, so swapping the underlying model never requires touching the solver,
-planner, or CLI. The defaults point at the published unified captcha LoRA, but
-nothing in the codebase hard-codes a model name outside this module.
-
-The two variables MOST users ever set:
-  VLLM_BASE_URL           where inference requests go (local or a remote server)
-  CAPTCHA_KRAKEN_API_KEY  bearer token for that server
-
-Advanced / self-hosting overrides (only needed to change WHICH model is served):
-  CAPTCHA_BASE_MODEL      base weights vLLM loads         (HF id or local path)
-  CAPTCHA_LORA_ADAPTER    LoRA applied on top             (HF id or local path)
-  CAPTCHA_LORA_REVISION   adapter git revision to serve
-  CAPTCHA_LORA_NAME       served adapter name the client asks for as `model`
-
-Defaults for the model-identity values come from `pinned_model.json` (see
-`pinned()`), which records the model + prompt pair this release was validated
-against.
-  VLLM_PORT, VLLM_GPU_MEMORY_UTILIZATION, VLLM_MAX_MODEL_LEN, VLLM_MAX_LORA_RANK
-  CAPTCHA_KRAKEN_AUTOSTART=0   disable auto-starting a local server on first use
-"""
-
 import json
 import os
 from functools import lru_cache
@@ -34,39 +9,12 @@ _PINNED_MODEL_PATH = Path(__file__).with_name("pinned_model.json")
 
 @lru_cache(maxsize=1)
 def pinned() -> Dict[str, Any]:
-    """The pinned model manifest shipped with this release.
-
-    Defines the (base model, adapter, serving prompts) triple this version was
-    validated against. Env vars still override every value below — the manifest
-    supplies the DEFAULT and gives CI something to assert against, so an adapter
-    or prompt change is a reviewable diff instead of a silent drift.
-    """
     with _PINNED_MODEL_PATH.open(encoding="utf-8") as f:
         return json.load(f)
 
 
-# ── Inference endpoint ──────────────────────────────────────────────────────
 def base_url() -> str:
-    """OpenAI-compatible endpoint, e.g. http://localhost:8000/v1.
-
-    Precedence mirrors `api_key()` exactly — env, then the credentials file,
-    then the local default — because the two values are set together and a
-    reader who has learned one ordering should not have to learn a second.
-
-      1. VLLM_BASE_URL. An explicit override always wins; self-hosters and the
-         dev environment depend on this and must not be silently redirected.
-      2. The credentials file. Written by the MCP signup flow alongside the key,
-         so onboarding configures the endpoint in the same step and a hosted
-         user needs no env plumbing at all.
-      3. localhost. Unchanged, and still correct: someone with no credentials
-         file is by definition not a hosted user, so the self-hosted default is
-         the right guess for them.
-
-    The bug this closes: a camoufox user who signed up through the MCP had a
-    valid key and no endpoint, so every solve dialled a local port with nothing
-    behind it and failed with connection-refused — a message that says nothing
-    about the fact that their requests were meant to go to api.captchakraken.com.
-    """
+    """Env, then the credentials file, then localhost: a camoufox user who signed up through the MCP had a valid key and no endpoint, so every solve dialled a local port."""
     return (
         os.getenv("VLLM_BASE_URL")
         or _base_url_from_credentials_file()
@@ -74,8 +22,28 @@ def base_url() -> str:
     )
 
 
+# An exact host list, not "is it remote": a self-hoster's vLLM across the network is remote too, and asking
+# it for the hosted-only model 404s every request.
+_HOSTED_HOSTS = ("api.captchakraken.com",)
+
+
+def hosted_hosts() -> tuple:
+    extra = os.getenv("CAPTCHA_HOSTED_HOSTS", "")
+    return _HOSTED_HOSTS + tuple(
+        h.strip().lower() for h in extra.split(",") if h.strip())
+
+
+def is_hosted_endpoint(url: Optional[str] = None) -> bool:
+    from urllib.parse import urlparse
+
+    try:
+        host = (urlparse(url or base_url()).hostname or "").lower()
+    except Exception:
+        return False
+    return host in hosted_hosts()
+
+
 def state_dir() -> Path:
-    """Shared state dir for the pidfile, lockfile, server log, and credentials."""
     return Path(os.getenv("CAPTCHA_KRAKEN_STATE_DIR", str(Path.home() / ".captchakraken")))
 
 
@@ -83,33 +51,12 @@ def credentials_path() -> Path:
     return state_dir() / "credentials"
 
 
-# Names the credentials file may use for each value. Two spellings each, because
-# the file doubles as something a user can `source` — the VLLM_* names are the
-# env vars this module already honours, and the CAPTCHA_KRAKEN_* names are what
-# the product calls them. Accepting both costs nothing and spares anyone the
-# discovery that they picked the wrong one.
 _KEY_NAMES = ("CAPTCHA_KRAKEN_API_KEY", "VLLM_API_KEY")
 _BASE_URL_NAMES = ("CAPTCHA_KRAKEN_BASE_URL", "VLLM_BASE_URL")
 
 
 def _read_credentials_file() -> Dict[str, str]:
-    """Parse the file the MCP server's signup flow writes.
-
-    Hosted-API onboarding writes the key to a 0600 file rather than returning it
-    through the agent transcript, so it never lands in an LLM context window.
-    Reading it here is what lets a solve authenticate with NO env vars set.
-
-    Returns a mapping of recognised name -> value. The special key ``""`` holds a
-    BARE TOKEN — a file containing nothing but `ck_live_…`, which is what the
-    original single-value format was and what a user hand-writing this file is
-    most likely to produce. Dropping that would silently break every existing
-    credentials file, so it is still accepted and still means "the API key".
-
-    Deliberately tolerant of quoting and comments: the file is written by a
-    *separate* tool, and a format mismatch here surfaces as a baffling 401
-    rather than an obvious parse error. Returns {} whenever the file is missing
-    or unreadable — the self-hosted case, which must stay silent.
-    """
+    """Two spellings per key because the file doubles as something a user can `source`; the bare-token form stays because dropping it would silently break every existing file."""
     try:
         text = credentials_path().read_text(encoding="utf-8")
     except OSError:
@@ -123,20 +70,16 @@ def _read_credentials_file() -> Dict[str, str]:
         if "=" in line:
             name, _, value = line.partition("=")
             name = name.strip()
-            # An env-file with unrelated keys must not yield a bogus token.
             if name not in _KEY_NAMES and name not in _BASE_URL_NAMES:
                 continue
             found.setdefault(name, value.strip().strip("'\""))
         elif "" not in found:
-            # A bare token. Only the first such line counts; later prose in a
-            # hand-edited file must not overwrite the credential.
             found[""] = line.strip("'\"")
 
     return found
 
 
 def _first_present(values: Dict[str, str], names) -> str:
-    """First non-empty value among `names`, in the order given."""
     for name in names:
         value = values.get(name, "").strip()
         if value:
@@ -145,28 +88,18 @@ def _first_present(values: Dict[str, str], names) -> str:
 
 
 def _key_from_credentials_file() -> str:
-    """The API key from the credentials file, or "" if there isn't one."""
     values = _read_credentials_file()
     return _first_present(values, _KEY_NAMES) or values.get("", "").strip()
 
 
-def _base_url_from_credentials_file() -> str:
-    """The endpoint from the credentials file, or "" if it names none.
+# A bare token yields no endpoint on purpose: it would silently redirect a self-hoster who hand-wrote a local key here.
+
 
-    A bare-token file deliberately yields nothing here: it carries no endpoint,
-    and inventing the hosted one for it would silently redirect a self-hoster
-    who wrote a token into that file by hand.
-    """
+def _base_url_from_credentials_file() -> str:
     return _first_present(_read_credentials_file(), _BASE_URL_NAMES)
 
 
 def api_key() -> str:
-    """Bearer token, in precedence order.
-
-    Env first so an explicit override always wins, then the credentials file so
-    the MCP/hosted path needs no env plumbing at all, then "EMPTY" (which leaves
-    a self-hosted local vLLM open, as before).
-    """
     return (
         os.getenv("CAPTCHA_KRAKEN_API_KEY")
         or os.getenv("VLLM_API_KEY")
@@ -175,47 +108,10 @@ def api_key() -> str:
     )
 
 
-# ── Model identity (all overridable — the CLI itself is model-agnostic) ──────
-#
-# Precedence, for every value below:
-#
-#   1. The environment. An explicit override always wins — this is how you PIN
-#      to a specific model, and pinning is opt-in by design.
-#   2. models.json's `latest` entry. The default moves forward with the
-#      registry, so "the default download" and "the default prompt" advance
-#      together and cannot get out of step: prompts.resolve() reads the SAME
-#      entry to decide which prompt generation to send.
-#   3. pinned_model.json. The record of what this release was validated
-#      against, kept as the fallback so an older checkout or a hand-edited
-#      manifest still resolves.
-#
-# Order 2-before-3 is the behaviour change: `latest` leads. Today both name
-# CaptchaKraken_v1.1, so nothing moves until a newer model is registered — at
-# which point that IS the intent.
 def _registry_default(field: str) -> Optional[str]:
-    """`field` from the entry of the model this process will actually serve.
-
-    THE PIN DECIDES THE ENTRY, not just the adapter. This read `latest`
-    unconditionally, so `CAPTCHA_LORA_ADAPTER` moved the adapter and nothing
-    else: the base weights to load it onto, the served `lora_name` to put in
-    the request, and the revision all still came from whichever model happened
-    to be `latest`.
-
-    That was survivable while every registered model was a 9B on one base
-    answering to one served name. It stopped being survivable the day the
-    registry gained `CaptchaKraken/Abyss-27B` — a Qwen3.8-**27B** — because
-    pinning it downloaded a 9B base, tried to load a 27B adapter onto it, and
-    sent `captcha-v12` as the model name. Nothing in the client errors on that;
-    it errors deep inside vLLM as a shape mismatch, or not at all if the
-    endpoint happens to serve something by that name. Same shape for every
-    expert arm, whose whole point is a `lora_name` of its own.
-
-    An UNREGISTERED pin still falls back to `latest`. A self-hoster's own
-    adapter is not in our registry and never will be; changing what they
-    resolve to would be a break with no benefit.
-    """
+    """The pin decides the registry entry, not just the adapter: reading base/lora_name off `latest` once downloaded a 9B base for a pinned 27B adapter and failed deep in vLLM as a shape mismatch. An unregistered pin still falls back to `latest` for self-hosters."""
     try:
-        from . import prompts  # local: prompts imports nothing from config
+        from . import prompts
 
         models = prompts.registered_models()
         entry = None
@@ -226,7 +122,7 @@ def _registry_default(field: str) -> Optional[str]:
             entry = models.get(prompts.latest_model() or "")
         value = (entry or {}).get(field)
         return value if isinstance(value, str) else None
-    except Exception:  # noqa: BLE001 — a broken registry falls back, never raises
+    except Exception:
         return None
 
 
@@ -236,7 +132,6 @@ def base_model() -> str:
 
 
 def lora_adapter() -> str:
-    """HF repo id or local path of the captcha adapter served on top of the base."""
     from . import prompts
 
     return (os.getenv("CAPTCHA_LORA_ADAPTER") or prompts.latest_model()
@@ -244,19 +139,44 @@ def lora_adapter() -> str:
 
 
 def lora_revision() -> str:
-    """Git revision of the adapter repo to serve — pinning this is what makes
-    'the adapter this release was tested against' a reproducible statement."""
     return os.getenv("CAPTCHA_LORA_REVISION") or _registry_default("lora_revision") \
         or pinned()["lora_revision"]
 
 
 def lora_name() -> str:
-    """The served LoRA name the client sends as the `model` field."""
-    return os.getenv("CAPTCHA_LORA_NAME") or _registry_default("lora_name") \
-        or pinned()["lora_name"]
+    # Pin, then the hosted default, then the registry: `latest` leads pinned_model.json so download and prompt advance together.
+    pin = os.getenv("CAPTCHA_LORA_NAME")
+    if pin:
+        return pin
+    if is_hosted_endpoint():
+        hosted = _hosted_default_name()
+        if hosted:
+            return hosted
+    return _registry_default("lora_name") or pinned()["lora_name"]
+
+
+def _hosted_default_name() -> Optional[str]:
+    """Send the routing alias, not an arm: `abyss-general` is a lone expert with no `experts` of its own, and naming it would pin every family to the generalist and silently lose the routing."""
+    try:
+        from . import prompts
+
+        repo = prompts.hosted_default_model()
+        if not repo:
+            return None
+        aliases = [a for a, target in prompts.served_aliases().items()
+                   if target == repo and not a.startswith("_")]
+        for alias in aliases:
+            if prompts.experts(alias):
+                return alias
+        if aliases:
+            return aliases[0]
+        entry = prompts.registered_models().get(repo) or {}
+        value = entry.get("lora_name")
+        return value if isinstance(value, str) else None
+    except Exception:
+        return None
 
 
-# ── Local vLLM server knobs ─────────────────────────────────────────────────
 def port() -> int:
     return int(os.getenv("VLLM_PORT", "8000"))
 
@@ -274,15 +194,9 @@ def max_lora_rank() -> int:
 
 
 def autostart_enabled() -> bool:
-    """Whether to auto-launch a local server on first use (default on)."""
     return os.getenv("CAPTCHA_KRAKEN_AUTOSTART", "1") != "0"
 
 
 def extra_serve_args() -> list:
-    """Extra flags appended verbatim to `vllm serve` (space-separated).
-
-    Escape hatch for serving tweaks the config doesn't model directly — e.g.
-    `--enforce-eager` or a smaller `--max-num-seqs` to squeeze onto a tight GPU.
-    """
     raw = os.getenv("VLLM_EXTRA_ARGS", "").strip()
     return raw.split() if raw else []

package/python/src/captchakraken/errors.py

@@ -1,47 +1,19 @@
 """What the hosted API's refusals mean, in words a user can act on.
 
-The solver talks to an OpenAI-compatible endpoint that may be a local vLLM the
-user started themselves or the hosted CaptchaKraken gateway. Those two fail very
-differently, and until this module existed both were reported the same way:
-`vLLM 402 Payment Required at https://api.captchakraken.com/v1/chat/completions`.
-A camoufox user who has never heard of vLLM, run vLLM, or intended to run vLLM
-would hit that on the day their credits ran out.
-
-Two rules, both inherited from the gateway's own `src/errors.ts`:
-
- 1. BRANCH ON `error.code`, NEVER ON PROSE. The messages get reworded; the codes
-    are the contract. A client that pattern-matches "Out of credits" breaks the
-    day someone improves the wording.
-
- 2. AN UNRECOGNISED CODE MUST STILL PRODUCE A USEFUL MESSAGE. There are ten
-    codes today and there will be more. Enumerating them exhaustively here means
-    the eleventh is reported worse than the ten — so the fallback carries the
-    server's own `message` and `resolution_url` through, and only the phrasing
-    is lost.
-
-The self-hosted path is deliberately untouched: a local vLLM does not send this
-envelope, so `from_response` returns a message shaped like the old one and the
-401/403 hint about the bearer token survives. Nobody self-hosting sees a word
-about credits.
+Before this, a camoufox user out of credits read `vLLM 402 Payment Required at https://api.captchakraken.com/...`.
+Branch on `code`, never on prose; an unknown code carries the server's own message through, so the eleventh
+code is never reported worse than the ten. The self-hosted path (no envelope) is untouched.
 """
 
 from typing import Any, Dict, Optional
 
-# Where a user with no `resolution_url` in hand should be sent. Only used as a
-# fallback — the server almost always supplies a deep link that is better than
-# this, and when it does we prefer it.
+from .kinds import ErrorCode
+
 _DASHBOARD = "https://captchakraken.com/dashboard"
 _SUPPORT = "https://captchakraken.com/support"
 
 
 class CaptchaKrakenAPIError(RuntimeError):
-    """A refusal from the hosted API, already translated.
-
-    Carries the machine-readable parts alongside the message so a caller that
-    wants to react programmatically (retry on `rate_limited`, stop on
-    `insufficient_credits`) can do so without re-parsing anything. `str(e)` is
-    the human sentence and is what reaches a console.
-    """
 
     def __init__(
         self,
@@ -59,13 +31,6 @@ class CaptchaKrakenAPIError(RuntimeError):
         self.retry_after_seconds = retry_after_seconds
 
     def to_payload(self) -> Dict[str, Any]:
-        """The shape the CLI puts on stderr for the JS driver to pick up.
-
-        The JS half shells out to this CLI and can only see stdout/stderr, so
-        the structured fields would otherwise be flattened to a string at the
-        process boundary and have to be re-parsed out of prose — exactly the
-        thing rule 1 forbids.
-        """
         return {
             "error": str(self),
             "ck_error": {
@@ -78,15 +43,10 @@ class CaptchaKrakenAPIError(RuntimeError):
 
 
 def _retry_after(headers: Any) -> Optional[float]:
-    """Seconds from the `Retry-After` header, if it is the numeric form.
-
-    HTTP also permits an HTTP-date here. The gateway only ever sends deltas, and
-    guessing wrong about a date would produce a confidently incorrect "wait 3
-    seconds", so anything unparseable is dropped rather than approximated.
-    """
+    """Numeric form only: guessing wrong about an HTTP-date would produce a confident "wait 3 seconds"."""
     try:
         raw = headers.get("Retry-After")
-    except Exception:  # noqa: BLE001 — a mapping-ish object is all we assume
+    except Exception:
         return None
     if raw is None:
         return None
@@ -97,19 +57,13 @@ def _retry_after(headers: Any) -> Optional[float]:
 
 
 def _sentence(code: str, message: str, url: Optional[str], retry: Optional[float]) -> str:
-    """The user-facing line for a known code.
-
-    Every branch names CaptchaKraken. That is the entire point of this module:
-    the person reading it needs to know which product is refusing them before
-    anything else in the sentence can help.
-    """
-    if code == "insufficient_credits":
+    if code == ErrorCode.INSUFFICIENT_CREDITS:
         return (
             "CaptchaKraken: your account is out of credits, so this solve was refused. "
             f"Top up at {url or _DASHBOARD} and retry."
         )
 
-    if code == "solve_abandoned":
+    if code == ErrorCode.SOLVE_ABANDONED:
         return (
             "CaptchaKraken: this captcha attempt was served too many times without "
             "settling and has been abandoned. That usually means the IP reputation or "
@@ -118,24 +72,24 @@ def _sentence(code: str, message: str, url: Optional[str], retry: Optional[float
             "one per solve() call, so a new solve is enough)."
         )
 
-    if code == "rate_limited":
+    if code == ErrorCode.RATE_LIMITED:
         wait = f" Retry in about {retry:g}s." if retry else " Back off and retry."
         return f"CaptchaKraken: too many requests.{wait}"
 
-    if code == "account_suspended":
+    if code == ErrorCode.ACCOUNT_SUSPENDED:
         return (
             "CaptchaKraken: this account is suspended, so solving is disabled. "
             f"Contact support at {url or _SUPPORT}."
         )
 
-    if code == "request_too_large":
+    if code == ErrorCode.REQUEST_TOO_LARGE:
         return (
             "CaptchaKraken: the screenshot sent for this solve exceeded the request "
             f"size limit. ({message}) Capture the captcha element rather than the "
             "whole page if you are not already."
         )
 
-    if code in ("missing_api_key", "invalid_api_key"):
+    if code in (ErrorCode.MISSING_API_KEY, ErrorCode.INVALID_API_KEY):
         return (
             "CaptchaKraken: the API key was missing or not accepted. Set "
             "CAPTCHA_KRAKEN_API_KEY, or run the CaptchaKraken MCP server's "
@@ -143,49 +97,18 @@ def _sentence(code: str, message: str, url: Optional[str], retry: Optional[float
             f"Manage keys at {url or _DASHBOARD}."
         )
 
-    if code == "upstream_unavailable":
+    if code == ErrorCode.UPSTREAM_UNAVAILABLE:
         return (
             "CaptchaKraken: the solver fleet is temporarily unreachable. This is on "
             "our side, not yours — retry shortly."
         )
 
-    # The two LICENSED-MODEL refusals. Both are 'you named a model', and they
-    # are separate codes because the fix is completely different: one is a
-    # licence to obtain, the other is a fleet that has not started serving yet
-    # and nothing for the caller to do. Generic prose collapses them into "the
-    # solve failed", which is the reading that sends someone to buy a licence
-    # they already hold.
-    if code == "model_not_licensed":
-        return (
-            "CaptchaKraken: the model this request named is licensed, and this "
-            "account is not licensed for it. The request was refused rather than "
-            "answered by a different model — a silent substitution would be a "
-            "score you could not explain. Unset CAPTCHA_LORA_NAME (or the "
-            f"client's `model`) to use the standard hosted model. {message} "
-            f"Licensing: {url or _SUPPORT}."
-        )
-
-    if code == "model_not_serving":
-        return (
-            "CaptchaKraken: this account IS licensed for the model it named, but "
-            "the fleet is not serving it yet. Nothing is wrong with your account "
-            "and there is nothing to buy. Unset CAPTCHA_LORA_NAME (or the "
-            f"client's `model`) to use the standard hosted model meanwhile. {message}"
-        )
-
-    # `unrecognized_prompt`, `invalid_request`, and anything added after this was
-    # written. The server's own message is the best thing available, so it is
-    # carried through verbatim rather than replaced with a guess.
+    # Anything added after this was written: the server's message is the best thing available.
     tail = f" See {url}." if url else ""
     return f"CaptchaKraken: {message}{tail}"
 
 
 def from_response(resp: Any, url: str) -> Exception:
-    """Build the exception for a non-OK response, hosted or self-hosted.
-
-    Returns rather than raises so the caller's `raise` keeps the traceback
-    anchored at the request site, where it is useful.
-    """
     body_text = (getattr(resp, "text", "") or "")[:300]
     status = getattr(resp, "status_code", None)
 
@@ -194,7 +117,7 @@ def from_response(resp: Any, url: str) -> Exception:
         parsed = resp.json()
         if isinstance(parsed, dict) and isinstance(parsed.get("error"), dict):
             error = parsed["error"]
-    except Exception:  # noqa: BLE001 — a non-JSON body is the self-hosted case
+    except Exception:
         error = {}
 
     code = error.get("code")
@@ -210,8 +133,7 @@ def from_response(resp: Any, url: str) -> Exception:
             retry_after_seconds=retry,
         )
 
-    # No gateway envelope: a local vLLM, a proxy in between, or an HTML error
-    # page. Keep the pre-existing message so self-hosted debugging is unchanged.
+    # No gateway envelope: a local vLLM, a proxy, or an HTML error page. Self-hosted debugging is unchanged.
     hint = ""
     if status in (401, 403):
         hint = " — check CAPTCHA_KRAKEN_API_KEY is set and forwarded to the CLI"