lmfpd 0.1.0__py3-none-any.whl

lmfpd/__init__.py

@@ -0,0 +1,94 @@
+"""The public API."""
+
+from __future__ import annotations
+
+import os
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Mapping, Sequence
+
+from . import _sampling
+from ._analysis import SCORING_FAILED, Scorer
+from ._challenge import generate_challenges
+from ._data import DEFAULT_DATA_URLS, load_data
+from ._features import parse_numbers
+from ._types import Analysis, Challenge, DetectResult, LmfpdError, Output, Sample
+
+
+class Detector:
+    """A loaded reference bank and detector. Create one with `load()`."""
+
+    __slots__ = ("_built_at", "_scorer")
+
+    def __init__(self, built_at: str, scorer: Scorer):
+        self._built_at = built_at
+        self._scorer = scorer
+
+    @property
+    def built_at(self) -> str:
+        """`built_at` of the reference bank, which identifies the data build."""
+        return self._built_at
+
+    def analyze(self, outputs: Sequence[Output], strict: bool = False) -> Analysis:
+        """Scores one to three saved replies. Three valid replies give a calibrated ranking; fewer give a partial
+        ranking unless `strict` is set."""
+        return self._scorer.analyze(outputs, strict)
+
+    def detect(self, base_url: str, api_key: str, model: str, *, api: str = "responses", effort: str = "",
+               service_tier: str = "default", stream: bool = True, strict: bool = False, count: int = 3,
+               parallel: int = 3, timeout: float = 120.0) -> DetectResult:
+        """Sends one round of challenges to the model API and scores the replies. Raises only on an invalid
+        config; request failures are reported in the samples and `error`."""
+        options = _sampling.detect_options({
+            "base_url": base_url, "api_key": api_key, "model": model, "api": api, "effort": effort,
+            "service_tier": service_tier, "stream": stream, "strict": strict, "count": count, "parallel": parallel,
+            "timeout": timeout,
+        })
+        challenges = generate_challenges(options.count)
+        with _sampling.client() as http, ThreadPoolExecutor(options.parallel) as pool:
+            samples = list(pool.map(lambda challenge: _sampling.sample(options, challenge, http), challenges))
+        accepted = sum(1 for s in samples if s["state"] in ("complete", "truncated"))
+        result: DetectResult = {"challenges": challenges, "samples": samples, "analysis": None, "error": None}
+        if not accepted or (options.strict and accepted != 3):
+            result["error"] = (f"Strict mode requires 3/3 successful samples; received {accepted}/3."
+                               if options.strict else "No valid samples. This round cannot be scored.")
+            return result
+        outputs: list[Output] = [{"text": s["text"] if s["state"] in ("complete", "truncated") else "",
+                                  "expected_count": s["expected_count"]} for s in samples]
+        try:
+            analysis = self._scorer.score(outputs, options.strict)
+        except Exception:
+            result["error"] = SCORING_FAILED
+            return result
+        result["analysis"] = analysis
+        if not analysis["results"]:
+            result["error"] = analysis["evidence"]["reason"]
+        return result
+
+
+def load(source: str | Sequence[str] = DEFAULT_DATA_URLS, cache: str | os.PathLike[str] | None = None,
+         ttl: float = 86400.0) -> Detector:
+    """Loads the reference data. A single source that is not an http(s) URL is a local directory with
+    `unified_bank.json` and `shared_detector.bin`, read as is. URL sources are tried in order behind the cache file
+    `cache` (default `<OS cache dir>/lmfpd/data.bin`): a cached copy is returned at once and, when last checked `ttl`
+    seconds ago or earlier (0 checks on every load), refreshed in the background for the next load. Without a cache it
+    downloads."""
+    return Detector(*load_data(source, cache, ttl))
+
+
+def build_request(config: Mapping[str, Any], prompt: str) -> dict[str, Any]:
+    """The HTTP request `detect` sends for one prompt: `{"url", "headers", "body"}`. Raises LmfpdError on an invalid
+    config."""
+    return _sampling.request_parts(_sampling.detect_options(config), prompt)
+
+
+def request_sample(config: Mapping[str, Any], challenge: Challenge) -> Sample:
+    """Sends one challenge and returns the checked reply. Request failures are reported in `error`."""
+    options = _sampling.detect_options(config)
+    with _sampling.client() as http:
+        return _sampling.sample(options, challenge, http)
+
+
+__all__ = [
+    "DEFAULT_DATA_URLS", "Analysis", "Challenge", "DetectResult", "Detector", "LmfpdError", "Output", "Sample",
+    "build_request", "generate_challenges", "load", "parse_numbers", "request_sample",
+]

lmfpd/_analysis.py

@@ -0,0 +1,162 @@
+"""Analysis in the canonical shape (port of `analyzeSharedOutputs`, `englishAnalysis`, and the SDK preprocessing)."""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Sequence
+
+import numpy as np
+
+from ._features import parse_numbers, raw_out_of_range_count
+from ._ranker import Ranker
+from ._types import Analysis, LmfpdError, Output
+
+SCORING_FAILED = "Scoring failed. Check that the reference bank and detector files are valid."
+INVALID_OUTPUTS = ("Each input round must contain one to three outputs with text and a positive integer "
+                   "expected_count.")
+_MAX_SAFE_INTEGER = 2 ** 53 - 1
+
+# Reference replies tend to have negative lag-1 autocorrelation and few steps of 20 or less. The limits are the
+# 99.5% quantiles over reference three-answer groups; a reply is rejected only when both signals exceed them.
+_AUTOCORRELATION_LIMIT = -0.23
+_SMALL_STEP_LIMIT = 0.05
+
+
+class Scorer:
+    """The ranker plus the bank metadata that names its models."""
+
+    def __init__(self, bank: dict[str, Any], detector: dict[str, Any]):
+        self.ranker = Ranker(detector)
+        self.models = [(m.get("id"), m.get("display_name"), m.get("family"), m.get("family_name"))
+                       for m in bank["models"]]
+        self.base_sha256 = detector["base_sha256"]
+        calibration = detector.get("calibration")
+        self.calibration = None if self.ranker.tau is None else {
+            "method": calibration["method"], "run": calibration["calibration_run"], "tau": calibration["tau"],
+            "sha256": detector.get("calibration_sha256"),
+        }
+
+    def _results(self, ranking: list[float], probabilities: list[float] | None) -> tuple[list[dict], int]:
+        # Stable: ties keep the bank order.
+        order = sorted(range(len(ranking)), key=lambda i: -ranking[i])
+        results = []
+        for i in order:
+            model, display_name, family, family_name = self.models[i]
+            results.append({"model": model, "display_name": display_name, "family": family,
+                            "family_name": family_name, "score": ranking[i],
+                            "probability": None if probabilities is None else probabilities[i]})
+        return results, order[0]
+
+    def score(self, outputs: Sequence[Output], strict: bool) -> Analysis:
+        """Scores outputs as given, like `analyzeSharedOutputs` followed by `englishAnalysis`."""
+        parsed = [parse_numbers(o["text"]) for o in outputs]
+        diagnostics = []
+        for index, (output, numbers) in enumerate(zip(outputs, parsed)):
+            minimum = max(80, math.ceil((output["expected_count"] or 0) * 0.55))
+            diagnostics.append({"index": index, "parsed_numbers": len(numbers), "minimum_numbers": minimum,
+                                "accepted": len(numbers) >= minimum,
+                                "raw_out_of_range_count": raw_out_of_range_count(output["text"])})
+        accepted = [numbers for numbers, d in zip(parsed, diagnostics) if d["accepted"]]
+        used = len(accepted)
+        sequence = _sequence_shape(accepted) if used else None
+        analysis: dict[str, Any] = {
+            "decision": "scored", "prediction": "", "prediction_name": "", "family_prediction": "",
+            "family_prediction_name": "", "results": [], "ranking_score": None, "probability": None,
+            "probability_status": "unavailable", "probability_scope": None, "calibration": None,
+            "used_outputs": used, "diagnostics": diagnostics, "sequence": sequence, "method": "shared-detector-v2",
+            "model_version": {"base_sha256": self.base_sha256},
+        }
+        not_model = {"decision": "not_model", "prediction_name": "Not a model reply", "evidence": _evidence(
+            "Not like a language model reply",
+            "Consecutive numbers change differently from the language-model replies in the reference bank. "
+            "Program-generated, sorted or shuffled numbers often do this. No ranking was produced.",
+            "sequence-shape")}
+        if not strict and 0 < used < 3 and len(outputs) <= 3:
+            if not sequence["model_like"]:
+                return {**analysis, **not_model}
+            ranking = self.ranker.rank(accepted).tolist()
+            results, first = self._results(ranking, None)
+            _, _, family, family_name = self.models[first]
+            return {**analysis, "method": "shared-ranker-partial-v1", "decision": "partial",
+                    "prediction": results[0]["model"], "prediction_name": results[0]["display_name"],
+                    "family_prediction": family, "family_prediction_name": family_name, "results": results,
+                    "ranking_score": ranking[first], "evidence": _evidence(
+                        "Partial sample ranking",
+                        f"Ranked {used} valid sample{'' if used == 1 else 's'}. "
+                        "Confidence requires three valid samples.",
+                        "partial-sample-ranking")}
+        if len(outputs) != 3 or used != 3:
+            return {**analysis, "decision": "unscorable", "prediction_name": "Not scored", "evidence": _evidence(
+                "Not enough valid samples",
+                f"Received {used}/3 valid samples. Three valid samples are required.",
+                "complete-three-answers")}
+        if not sequence["model_like"]:
+            return {**analysis, **not_model}
+        scores = self.ranker.rank(parsed)
+        calibrated_scores = self.ranker.calibrate(scores)
+        ranking = scores.tolist()
+        probabilities = None if calibrated_scores is None else calibrated_scores.tolist()
+        results, first = self._results(ranking, probabilities)
+        _, _, family, family_name = self.models[first]
+        calibrated = probabilities is not None
+        return {**analysis, "prediction": results[0]["model"], "prediction_name": results[0]["display_name"],
+                "family_prediction": family, "family_prediction_name": family_name, "results": results,
+                "ranking_score": ranking[first], "probability": results[0]["probability"],
+                "probability_status": "reference_calibrated" if calibrated else "unavailable",
+                "probability_scope": "reference-closed-set" if calibrated else None,
+                "calibration": dict(self.calibration) if calibrated else None,
+                "evidence": _evidence(
+                    "Calibrated ranking",
+                    "Confidence is a closed-set probability within the reference bank.",
+                    "reference-calibrated-ranking") if calibrated else _evidence(
+                    "Uncalibrated ranking",
+                    "The confidence calibration does not match this detector. Confidence is unavailable.",
+                    "uncalibrated-ranking")}
+
+    def analyze(self, outputs: Sequence[Output], strict: bool) -> Analysis:
+        """Scores saved replies like `fpd --input`: extra numbers are cut in relaxed mode, short replies count as
+        missing."""
+        if (not isinstance(outputs, (list, tuple)) or not 1 <= len(outputs) <= 3
+                or not all(_valid_output(item) for item in outputs)):
+            raise LmfpdError(INVALID_OUTPUTS)
+        prepared = []
+        for item in outputs:
+            text, expected = item["text"], item["expected_count"]
+            numbers = parse_numbers(text)
+            if not strict and len(numbers) > expected:
+                text = ", ".join(map(str, numbers[:expected]))
+            if len(numbers) < minimum_numbers(expected):
+                text = ""
+            prepared.append({"text": text, "expected_count": expected})
+        try:
+            return self.score(prepared, strict)
+        except Exception:
+            raise LmfpdError(SCORING_FAILED) from None
+
+
+def minimum_numbers(expected: int) -> int:
+    return max(80, math.ceil(expected * 0.55))
+
+
+def _valid_output(item: Any) -> bool:
+    if not isinstance(item, dict) or not isinstance(item.get("text"), str):
+        return False
+    expected = item.get("expected_count")
+    return isinstance(expected, int) and not isinstance(expected, bool) and 0 < expected <= _MAX_SAFE_INTEGER
+
+
+def _evidence(label: str, reason: str, method: str) -> dict[str, Any]:
+    return {"insufficient": True, "label": label, "reason": reason, "threshold": None, "method": method}
+
+
+def _sequence_shape(replies: Sequence[Sequence[int]]) -> dict[str, Any]:
+    autocorrelations, small_steps = [], []
+    for reply in replies:
+        n = np.asarray(reply, dtype=np.float64)
+        centered = n - n.mean()
+        variance = (centered * centered).mean()
+        autocorrelations.append((centered[1:] * centered[:-1]).mean() / variance if variance else 1.0)
+        small_steps.append(np.mean(np.abs(np.diff(n)) <= 20))
+    autocorrelation, small_step_share = float(np.median(autocorrelations)), float(np.median(small_steps))
+    return {"autocorrelation": autocorrelation, "small_step_share": small_step_share,
+            "model_like": autocorrelation <= _AUTOCORRELATION_LIMIT or small_step_share <= _SMALL_STEP_LIMIT}

lmfpd/_challenge.py

@@ -0,0 +1,38 @@
+"""Challenge prompts (port of shared/challenge-browser.js `generateChallenges`)."""
+
+from __future__ import annotations
+
+import json
+import secrets
+import uuid
+from functools import lru_cache
+from importlib.resources import files
+from typing import Any, Sequence
+
+from ._types import Challenge, LmfpdError
+
+
+@lru_cache(maxsize=1)
+def _languages() -> list[dict[str, Any]]:
+    return json.loads(files("lmfpd").joinpath("templates.json").read_text("utf-8"))["languages"]
+
+
+def _choose(values: Sequence[Any]) -> Any:
+    return values[secrets.randbelow(len(values))]
+
+
+def generate_challenges(count: int = 3) -> list[Challenge]:
+    """Random challenges in one of five languages, each asking for a distinct count from 292 to 332."""
+    if not isinstance(count, int) or isinstance(count, bool) or not 1 <= count <= 3:
+        raise LmfpdError("count must be an integer from 1 to 3.")
+    available = list(range(292, 333))
+    lengths = [available.pop(secrets.randbelow(len(available))) for _ in range(count)]
+    challenges: list[Challenge] = []
+    for index, length in enumerate(lengths):
+        language = _choose(_languages())
+        request = language["request"].replace("{action}", _choose(language["actions"])).replace("{count}", str(length))
+        prompt = language["space"].join([_choose(language["openings"]), request, language["rules"],
+                                         _choose(language["endings"]), _choose(language["separators"]),
+                                         language["start"]])
+        challenges.append({"id": f"probe-{index + 1}-{uuid.uuid4()}", "expected_count": length, "prompt": prompt})
+    return challenges

lmfpd/_codec.py

@@ -0,0 +1,30 @@
+"""Decoder for `shared_detector.bin` (port of shared/detector-codec.ts `decodeDetector`)."""
+
+from __future__ import annotations
+
+import json
+import struct
+from typing import Any
+
+import numpy as np
+
+
+def decode_detector(data: bytes) -> dict[str, Any]:
+    """Layout: u32 LE header length, JSON header, padding to 4 bytes, then float32 values stored byte-plane by
+    byte-plane (all first bytes, then all second bytes, ...). Header arrays are `{"$f32": offset, "n": length}` and
+    decode to float64 NumPy views of one shared array."""
+    (header_length,) = struct.unpack_from("<I", data, 0)
+    start = (4 + header_length + 3) // 4 * 4
+    size = len(data) - start
+    if size < 0 or size % 4:
+        raise ValueError("Truncated detector data.")
+    planes = np.frombuffer(data, dtype=np.uint8, count=size, offset=start).reshape(4, size // 4)
+    floats = np.ascontiguousarray(planes.T).view("<f4").reshape(-1).astype(np.float64)
+
+    def expand(value: dict[str, Any]) -> Any:
+        if "$f32" in value:
+            offset = value["$f32"]
+            return floats[offset:offset + value["n"]]
+        return value
+
+    return json.loads(bytes(data[4:4 + header_length]).decode("utf-8"), object_hook=expand)

lmfpd/_data.py

@@ -0,0 +1,183 @@
+"""Reference data: a local directory, or the published data behind a stale-while-revalidate cache file."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import secrets
+import struct
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import Any, Sequence, cast
+
+import httpx
+import numpy as np
+import zstandard
+
+from ._analysis import Scorer
+from ._codec import decode_detector
+from ._types import LmfpdError
+
+#: Data sources, tried in order. The mirror is JSDMirror, a jsDelivr mirror in mainland China, serving the
+#: `lmfpd-data` npm package with the same layout as the site's `/data/`.
+DEFAULT_DATA_URLS: tuple[str, ...] = (
+    "https://lm.ikale.io/data/",
+    "https://cdn.jsdmirror.com/npm/lmfpd-data@latest/",
+)
+# Bump when the bundle layout changes; older SDKs then refuse the data instead of misreading it.
+_DATA_SCHEMA = "lmfpd-data-v1"
+_DETECTOR_SCHEMA = "shared-detector-v2"
+_DETECTOR = "shared_detector.bin"
+_URL = re.compile(r"https?://", re.IGNORECASE)
+
+Data = tuple[str, Scorer]
+
+
+def default_cache() -> Path:
+    home = Path.home()
+    if os.environ.get("XDG_CACHE_HOME"):
+        root = Path(os.environ["XDG_CACHE_HOME"])
+    elif sys.platform == "darwin":
+        root = home / "Library" / "Caches"
+    elif sys.platform == "win32":
+        root = Path(os.environ.get("LOCALAPPDATA") or home / "AppData" / "Local")
+    else:
+        root = home / ".cache"
+    return root / "lmfpd" / "data.bin"
+
+
+def _supports(bank: Any, detector: Any) -> bool:
+    models = bank.get("models") if isinstance(bank, dict) else None
+    if not isinstance(models, list) or not isinstance(detector, dict):
+        return False
+    ids, counts = detector.get("model_ids"), detector.get("response_counts")
+    if (detector.get("schema") != _DETECTOR_SCHEMA or bank.get("built_at") != detector.get("bank_built_at")
+            or not isinstance(ids, list) or not isinstance(counts, (list, np.ndarray))
+            or len(models) != len(ids) or len(counts) < len(ids)):
+        return False
+    for model, model_id, count in zip(models, ids, counts):
+        response_count = model.get("response_count") if isinstance(model, dict) else None
+        if (not isinstance(model, dict) or model.get("id") != model_id or isinstance(response_count, bool)
+                or response_count != count):
+            return False
+    return True
+
+
+def _reference_data(bank: Any, detector: Any) -> Data:
+    """Scoring reads only `built_at` and the model names and counts from the bank. `bundle.json` repeats them at its
+    top level, so it can stand in for `unified_bank.json`."""
+    if not _supports(bank, detector):
+        raise LmfpdError("The reference bank does not match its detector.")
+    return bank["built_at"], Scorer(bank, detector)
+
+
+def _read_dir(directory: str) -> Data:
+    """Reads `unified_bank.json` and `shared_detector.bin` from a directory such as `projects/data`."""
+    parsed = []
+    for name, parse in (("unified_bank.json", json.loads), (_DETECTOR, decode_detector)):
+        path = os.path.join(directory, name)
+        try:
+            parsed.append(parse(Path(path).read_bytes()))
+        except Exception:
+            raise LmfpdError(f"Cannot read {path}.") from None
+    return _reference_data(*parsed)
+
+
+def _read_cache(path: Path) -> tuple[Data, str, float] | None:
+    """The cache file holds the u32 little-endian length of `bundle.json`, `bundle.json`, then `shared_detector.bin`.
+    Returns the data, its version, and the last check time; None when the cache is missing or damaged."""
+    try:
+        checked_at = path.stat().st_mtime
+        content = path.read_bytes()
+        (length,) = struct.unpack_from("<I", content, 0)
+        bundle = json.loads(content[4:4 + length])
+        data = _reference_data(bundle, decode_detector(content[4 + length:]))
+        return data, bundle["files"][_DETECTOR]["sha256"], checked_at
+    except Exception:
+        return None
+
+
+def _write_cache(path: Path, bundle: bytes, detector: bytes) -> None:
+    """Best effort: a failed write only means the next load downloads again."""
+    staging = path.with_name(f"{path.name}.tmp-{secrets.token_hex(8)}")
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        staging.write_bytes(struct.pack("<I", len(bundle)) + bundle + detector)
+        os.replace(staging, path)
+    except OSError:
+        try:
+            staging.unlink()
+        except OSError:
+            pass
+
+
+def _download(client: httpx.Client, url: str, seconds: float) -> bytes:
+    deadline = time.monotonic() + seconds
+    with client.stream("GET", url, timeout=seconds) as response:
+        if not 200 <= response.status_code < 300:
+            raise LmfpdError(f"HTTP {response.status_code}")
+        body = bytearray()
+        for chunk in response.iter_bytes():
+            body += chunk
+            if time.monotonic() > deadline:
+                raise LmfpdError(f"Timed out after {seconds:g}s.")
+        return bytes(body)
+
+
+def _refresh(sources: Sequence[str], cache: Path, cached_version: str | None = None) -> Data | None:
+    """Downloads the data from the first working source and caches it. Returns None when the source still serves
+    `cached_version`, after marking the cache as checked."""
+    failures = []
+    with httpx.Client(follow_redirects=True, trust_env=True) as client:
+        for source in sources:
+            try:
+                bundle_bytes = _download(client, f"{source}bundle.json", 10)
+                bundle = json.loads(bundle_bytes)
+                if bundle["schema"] != _DATA_SCHEMA or bundle["detector_schema"] != _DETECTOR_SCHEMA:
+                    raise LmfpdError(f"data schema {bundle['schema']}/{bundle['detector_schema']} is not supported "
+                                     "by this SDK version. Upgrade lmfpd.")
+                # The detector's SHA-256 names its version.
+                file = bundle["files"][_DETECTOR]
+                if file["sha256"] == cached_version:
+                    try:
+                        os.utime(cache)
+                    except OSError:
+                        pass
+                    return None
+                compressed = b"".join(_download(client, f"{source}chunks/{part}", 120) for part in file["parts"])
+                detector_bytes = zstandard.ZstdDecompressor().stream_reader(compressed,
+                                                                            read_across_frames=True).read()
+                data = _reference_data(bundle, decode_detector(detector_bytes))
+                _write_cache(cache, bundle_bytes, detector_bytes)
+                return data
+            except Exception as error:
+                failures.append(f"{source} ({str(error) or type(error).__name__})")
+    raise LmfpdError(f"lmfpd: cannot download reference data from {', '.join(failures)}")
+
+
+def load_data(source: str | Sequence[str], cache: str | os.PathLike[str] | None, ttl: float) -> Data:
+    """A single source that is not an http(s) URL is a local directory, read as is. For URLs, answers from the cache
+    file when there is one (stale-while-revalidate): a cache last checked `ttl` seconds ago or earlier is refreshed
+    in the background for the next load. Without a cache it downloads."""
+    sources = [source] if isinstance(source, str) else list(source)
+    if len(sources) == 1 and not _URL.match(sources[0]):
+        return _read_dir(sources[0])
+    path = Path(cache) if cache is not None else default_cache()
+    cached = _read_cache(path)
+    if cached is None:
+        # Without a cached version a successful refresh always returns data.
+        return cast(Data, _refresh(sources, path))
+    data, version, checked_at = cached
+    if time.time() - checked_at >= ttl:
+        threading.Thread(target=_refresh_quietly, args=(sources, path, version), daemon=True).start()
+    return data
+
+
+def _refresh_quietly(sources: Sequence[str], cache: Path, version: str) -> None:
+    try:
+        _refresh(sources, cache, version)
+    except Exception:
+        pass

lmfpd/_features.py

@@ -0,0 +1,142 @@
+"""Number parsing and feature blocks (port of shared/fingerprint-core.js and shared/positional.ts)."""
+
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+from typing import Sequence
+
+import numpy as np
+from numpy.lib.stride_tricks import sliding_window_view
+
+VALUE_MIN = 1
+VALUE_MAX = 355
+DIMENSION = VALUE_MAX - VALUE_MIN + 1
+ALPHA = 0.5
+
+# ASCII digits only: `\d` is Unicode in Python `re`.
+_DIGITS = re.compile(r"[0-9]+")
+_SIGNED = re.compile(r"-?[0-9]+")
+
+
+def _value(digits: str) -> int:
+    """The numeric value of a digit run, or -1 when it has more than three significant digits."""
+    if len(digits) > 3:
+        digits = digits.lstrip("0")
+        if len(digits) > 3:
+            return -1
+    return int(digits) if digits else 0
+
+
+@lru_cache(maxsize=4096)
+def _has_letter(separator: str) -> bool:
+    # Replies reuse a few separators, so the per-character test is cached.
+    return any(c.isalpha() for c in separator)
+
+
+def parse_numbers(text: str) -> list[int]:
+    """The numbers 1 to 355 of the longest run in a reply; letters between numbers split runs."""
+    text = str(text)
+    best: list[int] = []
+    current: list[int] = []
+    previous_end = 0
+    for match in _DIGITS.finditer(text):
+        start = match.start()
+        if current and start > previous_end and _has_letter(text[previous_end:start]):
+            if len(current) > len(best):
+                best = current
+            current = []
+        value = _value(match.group())
+        if VALUE_MIN <= value <= VALUE_MAX:
+            current.append(value)
+        previous_end = match.end()
+    return current if len(current) > len(best) else best
+
+
+def raw_out_of_range_count(text: str) -> int:
+    count = 0
+    for match in _SIGNED.finditer(text):
+        digits = match.group()
+        if digits[0] == "-":
+            count += 1
+        else:
+            value = _value(digits)
+            if value == 0 or value < 0 or value > VALUE_MAX:
+                count += 1
+    return count
+
+
+Vector = np.ndarray
+
+
+def hellinger_feature(numbers: np.ndarray) -> Vector:
+    """Smoothed Hellinger embedding of the value counts of `numbers` (an int array of values 1 to 355)."""
+    counts = np.bincount(numbers - VALUE_MIN, minlength=DIMENSION)
+    return np.sqrt((counts + ALPHA) / (len(numbers) + ALPHA * DIMENSION))
+
+
+def ordered_block_feature(numbers: np.ndarray) -> Vector:
+    """Value histograms of the four consecutive quarters, then the last-digit histogram, each Hellinger-scaled."""
+    base, remainder = divmod(len(numbers), 4)
+    bins = np.minimum(15, np.floor((numbers - 1) / 355 * 16).astype(np.intp))
+    pieces = []
+    start = 0
+    for index in range(4):
+        size = base + (1 if index < remainder else 0)
+        counts = np.bincount(bins[start:start + size], minlength=16) + 0.5
+        pieces.append(np.sqrt(counts / counts.sum()))
+        start += size
+    digits = np.bincount(numbers % 10, minlength=10) + 0.5
+    pieces.append(np.sqrt(digits / digits.sum()))
+    return np.concatenate(pieces)
+
+
+# Positional features. Block order is part of the detector format.
+POSITIONAL_WEIGHTS = (0.6, 0.15, 0.125, 0.125)
+_CENTRES = 1 + np.arange(24) * 354 / 23
+_LAGS = (1, 2, 3, 5, 8, 13, 21, 34)
+
+
+def _position_kernel(x: np.ndarray) -> Vector:
+    """Per feature (24 value kernels, 10 last-digit indicators), its mean product with the first three Legendre
+    polynomials of the position."""
+    n = len(x)
+    t = (np.arange(n) + 0.5) * 2 / n - 1
+    basis = np.stack([t, 0.5 * (3 * t * t - 1), 0.5 * (5 * t ** 3 - 3 * t)], axis=1)
+    kernels = np.exp(-0.5 * ((x[:, None] - _CENTRES) / 20) ** 2)
+    digits = (x[:, None] % 10 == np.arange(10)).astype(np.float64)
+    return (np.concatenate([kernels, digits], axis=1).T @ basis / n).reshape(-1)
+
+
+def _centred_transitions(symbols: np.ndarray, bins: int) -> Vector:
+    joint = np.bincount(symbols[:-1] * bins + symbols[1:], minlength=bins * bins) + 0.5
+    joint = (joint / (len(symbols) - 1 + 0.5 * bins * bins)).reshape(bins, bins)
+    return (joint - np.outer(joint.sum(axis=1), joint.sum(axis=0))).reshape(-1)
+
+
+def _sequence_features(x: np.ndarray) -> Vector:
+    n = len(x)
+    m = x.mean()
+    s = (x - m) / max(np.sqrt(((x - m) ** 2).mean()), 1)
+    out = []
+    for lag in _LAGS:
+        d = x[lag:] - x[:-lag]
+        magnitude = np.abs(d)
+        out += (np.mean(s[lag:] * s[:-lag]), magnitude.mean() / 355, np.mean(d > 0), np.mean(d == 0),
+                np.mean(magnitude <= 5), np.mean(magnitude <= 20))
+    transitions = [_centred_transitions(np.minimum(7, (x - 1) * 8 // 355), 8), _centred_transitions(x % 10, 10)]
+    difference = np.diff(x)
+    z_step = np.abs(np.diff(s))
+    out += (np.mean(np.sign(difference[1:]) == np.sign(difference[:-1])), np.mean(difference[1:] == difference[:-1]),
+            np.mean(x[:-1] % 10 == x[1:] % 10), np.mean(z_step > 1), np.mean(z_step > 2))
+    buckets = np.minimum(15, (x - 1) * 16 // 355)
+    for width in (4, 8, 16):
+        windows = np.sort(sliding_window_view(buckets, width), axis=1)
+        distinct = 1 + np.count_nonzero(np.diff(windows, axis=1), axis=1)
+        out.append(np.mean(distinct / width))
+    return np.concatenate([np.array(out[:48]), *transitions, np.array(out[48:])])
+
+
+def positional_features(numbers: np.ndarray) -> list[Vector]:
+    return [hellinger_feature(numbers), ordered_block_feature(numbers), _position_kernel(numbers),
+            _sequence_features(numbers)]