lmfpd 0.1.0__tar.gz

lmfpd-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+node_modules/
+.DS_Store
+dist/
+target/
+.venv/
+web/public/data/
+web/.generated/
+*.tsbuildinfo
+*.log
+.vercel/
+.wrangler/
+.dev.vars
+.dev.vars.*
+.env
+.env.*
+*.lock/
+data/.pending-enrollment/
+data/.enrollments/
+data/.training/
+runs/
+research/
+docs/build/
+docs/.react-router/
+docs/.source/
+# Python research tools can import historical product code.
+__pycache__/
+*.pyc

lmfpd-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.5
+Name: lmfpd
+Version: 0.1.0
+Summary: Language-model fingerprint detection: offline scoring, challenges, and live detection.
+Project-URL: Homepage, https://lm.ikale.io
+Project-URL: Repository, https://github.com/Ikaleio/lm-detector
+Project-URL: Issues, https://github.com/Ikaleio/lm-detector/issues
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx[socks]>=0.28
+Requires-Dist: numpy>=1.26
+Requires-Dist: zstandard>=0.23
+Description-Content-Type: text/markdown
+
+# lmfpd (Python)
+
+Language-model fingerprint detection: score saved replies against the lmfpd reference bank, generate challenge
+prompts, and run one live detection round against an OpenAI- or Anthropic-compatible API.
+
+Documentation: https://lm.ikale.io/docs/en/sdk
+
+## Install and build
+
+```sh
+pip install lmfpd
+uv build                   # from sdk/python; writes the sdist and wheel to dist/
+```
+
+Python 3.10 or newer. Dependencies: `httpx` (with SOCKS support), `zstandard`, and `numpy`.
+
+## Loading reference data
+
+`lmfpd.load(source=DEFAULT_DATA_URLS, cache=None, ttl=86400.0)` is the one entry point.
+
+- **Local directory:** a single `source` that is not an `http://` or `https://` URL is a directory holding
+  `unified_bank.json` and `shared_detector.bin` (for example `projects/data`). It is read as is, with no cache and no
+  network.
+- **URLs:** sources are tried in order: `https://lm.ikale.io/data/`, then the mainland-China mirror
+  `https://cdn.jsdmirror.com/npm/lmfpd-data@latest/`. Only `bundle.json` and the detector are downloaded (about
+  3.6 MB compressed, 4.5 MB uncompressed). Files are not checksum-verified.
+- **Cache:** one file, `cache`, defaulting to `<OS cache dir>/lmfpd/data.bin` (`$XDG_CACHE_HOME`,
+  `~/Library/Caches`, `%LOCALAPPDATA%`, or `~/.cache`). Its modification time is the last check against the sources.
+  - With a cache, `load()` returns it at once. When the last check is `ttl` seconds old or more (0 checks on every
+    load), a background thread
+    fetches `bundle.json` and, only if the detector changed, the new detector for the next load. Failures there are
+    ignored.
+  - Without a cache, or with a damaged one, `load()` downloads before returning and raises
+    `lmfpd: cannot download reference data from ...` when every source fails.
+
+HTTP requests honor `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY` (including `socks5h://`), and `NO_PROXY`.
+
+## API
+
+Results are plain dicts with the same keys in every lmfpd SDK; `lmfpd.Analysis`, `Sample`, and `DetectResult` are
+their `TypedDict`s. Invalid input raises `lmfpd.LmfpdError`.
+
+- `load(source, cache, ttl) -> Detector`: load reference data from URLs (cached) or a local directory.
+- `Detector.built_at`: the data build identifier.
+- `Detector.analyze(outputs, strict=False) -> Analysis`: score one to three `{"text", "expected_count"}` replies.
+- `Detector.detect(base_url, api_key, model, *, api="responses", effort="", service_tier="default", stream=True,
+  strict=False, count=3, parallel=3, timeout=120.0) -> DetectResult`: send `count` challenges and score the replies.
+  `api` is `responses`, `chat_completions`, or `messages`.
+- `generate_challenges(count=3) -> list[Challenge]`: random challenge prompts.
+- `parse_numbers(text) -> list[int]`: the numbers 1 to 355 of the longest run in a reply.
+- `build_request(config, prompt) -> dict`: the URL, headers, and body `detect` sends for one prompt.
+- `request_sample(config, challenge) -> Sample`: send one challenge and check the reply.
+
+`config` dicts use the `detect` keyword names (`base_url`, `api_key`, `model`, `api`, ...).
+
+```python
+import lmfpd
+
+detector = lmfpd.load()
+result = detector.detect("https://api.openai.com/v1", "sk-...", "gpt-5")
+print(result["analysis"]["prediction"] if result["analysis"] else result["error"])
+```

lmfpd-0.1.0/README.md

@@ -0,0 +1,62 @@
+# lmfpd (Python)
+
+Language-model fingerprint detection: score saved replies against the lmfpd reference bank, generate challenge
+prompts, and run one live detection round against an OpenAI- or Anthropic-compatible API.
+
+Documentation: https://lm.ikale.io/docs/en/sdk
+
+## Install and build
+
+```sh
+pip install lmfpd
+uv build                   # from sdk/python; writes the sdist and wheel to dist/
+```
+
+Python 3.10 or newer. Dependencies: `httpx` (with SOCKS support), `zstandard`, and `numpy`.
+
+## Loading reference data
+
+`lmfpd.load(source=DEFAULT_DATA_URLS, cache=None, ttl=86400.0)` is the one entry point.
+
+- **Local directory:** a single `source` that is not an `http://` or `https://` URL is a directory holding
+  `unified_bank.json` and `shared_detector.bin` (for example `projects/data`). It is read as is, with no cache and no
+  network.
+- **URLs:** sources are tried in order: `https://lm.ikale.io/data/`, then the mainland-China mirror
+  `https://cdn.jsdmirror.com/npm/lmfpd-data@latest/`. Only `bundle.json` and the detector are downloaded (about
+  3.6 MB compressed, 4.5 MB uncompressed). Files are not checksum-verified.
+- **Cache:** one file, `cache`, defaulting to `<OS cache dir>/lmfpd/data.bin` (`$XDG_CACHE_HOME`,
+  `~/Library/Caches`, `%LOCALAPPDATA%`, or `~/.cache`). Its modification time is the last check against the sources.
+  - With a cache, `load()` returns it at once. When the last check is `ttl` seconds old or more (0 checks on every
+    load), a background thread
+    fetches `bundle.json` and, only if the detector changed, the new detector for the next load. Failures there are
+    ignored.
+  - Without a cache, or with a damaged one, `load()` downloads before returning and raises
+    `lmfpd: cannot download reference data from ...` when every source fails.
+
+HTTP requests honor `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY` (including `socks5h://`), and `NO_PROXY`.
+
+## API
+
+Results are plain dicts with the same keys in every lmfpd SDK; `lmfpd.Analysis`, `Sample`, and `DetectResult` are
+their `TypedDict`s. Invalid input raises `lmfpd.LmfpdError`.
+
+- `load(source, cache, ttl) -> Detector`: load reference data from URLs (cached) or a local directory.
+- `Detector.built_at`: the data build identifier.
+- `Detector.analyze(outputs, strict=False) -> Analysis`: score one to three `{"text", "expected_count"}` replies.
+- `Detector.detect(base_url, api_key, model, *, api="responses", effort="", service_tier="default", stream=True,
+  strict=False, count=3, parallel=3, timeout=120.0) -> DetectResult`: send `count` challenges and score the replies.
+  `api` is `responses`, `chat_completions`, or `messages`.
+- `generate_challenges(count=3) -> list[Challenge]`: random challenge prompts.
+- `parse_numbers(text) -> list[int]`: the numbers 1 to 355 of the longest run in a reply.
+- `build_request(config, prompt) -> dict`: the URL, headers, and body `detect` sends for one prompt.
+- `request_sample(config, challenge) -> Sample`: send one challenge and check the reply.
+
+`config` dicts use the `detect` keyword names (`base_url`, `api_key`, `model`, `api`, ...).
+
+```python
+import lmfpd
+
+detector = lmfpd.load()
+result = detector.detect("https://api.openai.com/v1", "sk-...", "gpt-5")
+print(result["analysis"]["prediction"] if result["analysis"] else result["error"])
+```

lmfpd-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "lmfpd"
+version = "0.1.0"
+description = "Language-model fingerprint detection: offline scoring, challenges, and live detection."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+    "httpx[socks]>=0.28",
+    "numpy>=1.26",
+    "zstandard>=0.23",
+]
+
+[project.urls]
+Homepage = "https://lm.ikale.io"
+Repository = "https://github.com/Ikaleio/lm-detector"
+Issues = "https://github.com/Ikaleio/lm-detector/issues"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"

lmfpd-0.1.0/scripts/conformance.py

@@ -0,0 +1,143 @@
+"""Checks the Python SDK against sdk/conformance. Usage: conformance.py <conformance dir> <data dir>"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+
+import lmfpd
+
+failures = 0
+
+
+def dump(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+
+
+def is_number(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def compare(file: str, name: str, expected: Any, actual: Any, path: str = "$") -> None:
+    """Reports every mismatch. Numbers match within a relative 1e-9; everything else must be identical."""
+    global failures
+
+    def fail() -> None:
+        global failures
+        failures += 1
+        print(f"FAIL {file}:{name}: {path} expected {dump(expected)} got {dump(actual)}")
+
+    if is_number(expected) and is_number(actual):
+        if not abs(expected - actual) <= 1e-9 * max(1, abs(expected), abs(actual)):
+            fail()
+    elif isinstance(expected, list) and isinstance(actual, (list, tuple)):
+        if len(expected) != len(actual):
+            return fail()
+        for i, (item, other) in enumerate(zip(expected, actual)):
+            compare(file, name, item, other, f"{path}[{i}]")
+    elif isinstance(expected, dict) and isinstance(actual, dict):
+        if sorted(expected) != sorted(actual):
+            return fail()
+        for key in sorted(expected):
+            compare(file, name, expected[key], actual[key], f"{path}.{key}")
+    elif type(expected) is not type(actual) or expected != actual:
+        fail()
+
+
+def serve(cases: list[dict[str, Any]]) -> ThreadingHTTPServer:
+    """Serves every POST under `/<case name>/` with that case's canned response."""
+
+    class Handler(BaseHTTPRequestHandler):
+        def do_POST(self) -> None:
+            self.rfile.read(int(self.headers.get("Content-Length") or 0))
+            item = next((c for c in cases if self.path.startswith(f"/{c['name']}/")), None)
+            if item is None:
+                return self.reply(404, "text/plain", "not found")
+            response = item["response"]
+            self.reply(response["status"], response["content_type"], response["body"])
+
+        def do_GET(self) -> None:
+            self.reply(404, "text/plain", "not found")
+
+        def reply(self, status: int, content_type: str, body: str) -> None:
+            data = body.encode("utf-8")
+            self.send_response(status)
+            self.send_header("Content-Type", content_type)
+            self.send_header("Content-Length", str(len(data)))
+            self.send_header("Connection", "close")
+            self.end_headers()
+            self.wfile.write(data)
+
+        def log_message(self, *args: Any) -> None:
+            pass
+
+    server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    return server
+
+
+def main() -> int:
+    if len(sys.argv) != 3:
+        print("Usage: conformance.py <conformance dir> <data dir>")
+        return 2
+    directory, data_dir = Path(sys.argv[1]), sys.argv[2]
+
+    def fixture(name: str) -> Any:
+        return json.loads((directory / name).read_text("utf-8"))
+
+    templates = files("lmfpd").joinpath("templates.json").read_bytes()
+    if templates != (directory / "templates.json").read_bytes():
+        compare("templates.json", "copy", "byte-equal to conformance/templates.json", "different")
+
+    parse = fixture("parse.json")
+    for i, item in enumerate(parse):
+        compare("parse.json", str(i), item["numbers"], lmfpd.parse_numbers(item["text"]))
+
+    requests = fixture("requests.json")
+    for item in requests:
+        try:
+            actual: Any = lmfpd.build_request(item["config"], item["prompt"])
+        except lmfpd.LmfpdError as error:
+            actual = {"error": str(error)}
+        compare("requests.json", item["name"], item["expected"], actual)
+
+    # The mock server is local; keep any proxy from the environment away from it.
+    for variable in ("NO_PROXY", "no_proxy"):
+        os.environ[variable] = ",".join(filter(None, ["127.0.0.1", os.environ.get(variable)]))
+    streams = fixture("streams.json")["cases"]
+    server = serve(streams)
+    try:
+        port = server.server_address[1]
+        for item in streams:
+            sample = dict(lmfpd.request_sample({
+                "base_url": f"http://127.0.0.1:{port}/{item['name']}", "api_key": "test-key", "model": "test-model",
+                "api": item["api"], "stream": item["stream"], "strict": item["strict"], "timeout": 10,
+            }, {"id": "conformance", "prompt": "conformance", "expected_count": item["expected_count"]}))
+            del sample["expected_count"]
+            compare("streams.json", item["name"], item["expected"], sample)
+    finally:
+        server.shutdown()
+        server.server_close()
+
+    analyze = fixture("analyze.json")
+    detector = lmfpd.load(data_dir)
+    if detector.built_at != analyze["data"]["built_at"]:
+        print("FAIL analyze.json: analyze.json was generated for another data build; run bun run sdk:generate")
+        return 1
+    for item in analyze["cases"]:
+        compare("analyze.json", item["name"], item["expected"], detector.analyze(item["outputs"], item["strict"]))
+
+    if failures:
+        return 1
+    print(f"ok analyze={len(analyze['cases'])} parse={len(parse)} requests={len(requests)} streams={len(streams)}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

lmfpd-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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)