Upload 6 files

DATASET_COLLECTION_GUIDANCE.md

@@ -1,7 +1,7 @@
 # Dataset Collection Guidance
 
-**Applies to:** `scikit-plots/ai-assistant-contributions` (HuggingFace Dataset)  
-**Version:** 1.0  
+**Applies to:** `scikit-plots/ai-assistant-contributions` (HuggingFace Dataset)
+**Version:** 1.0
 **Maintained by:** scikit-plots maintainers
 
 ---

_shared_logic.py

@@ -156,7 +156,7 @@ import json
 import os
 from typing import Any, Literal
 
-__all__ = [
+__all__ = [  # noqa: RUF022
     # Version
     "PROXY_VERSION",
     # Constants — routing / timeout
@@ -303,20 +303,20 @@ HFTokenType = Literal["fine-grained", "read", "write", "unknown"]
 
 #: New-style fine-grained HF token.  Permissions defined at creation time.
 #: Declare via env var: ``HF_TOKEN_TYPE=fine-grained``.
-HF_TOKEN_TYPE_FINE_GRAINED: str = "fine-grained"
+HF_TOKEN_TYPE_FINE_GRAINED: str = "fine-grained"  # noqa: S105
 
 #: Classic HF read token.  Read + Inference API; no write capability.
 #: Declare via env var: ``HF_TOKEN_TYPE=read``.
-HF_TOKEN_TYPE_READ: str = "read"
+HF_TOKEN_TYPE_READ: str = "read"  # noqa: S105
 
 #: Classic HF write token.  All read permissions + repo push capability.
 #: Declare via env var: ``HF_TOKEN_TYPE=write`` or ``HF_WRITE_TOKEN_TYPE=write``.
-HF_TOKEN_TYPE_WRITE: str = "write"
+HF_TOKEN_TYPE_WRITE: str = "write"  # noqa: S105
 
 #: Sentinel: token type not declared and could not be inferred.
 #: Runtime operations are not blocked, but :func:`_validate_token_config` omits
 #: least-privilege warnings because the type is unknown.
-HF_TOKEN_TYPE_UNKNOWN: str = "unknown"
+HF_TOKEN_TYPE_UNKNOWN: str = "unknown"  # noqa: S105
 
 #: Token types that are appropriate for HF Serverless Inference API calls
 #: (Path 3) and private HF Space access (Path 2).
@@ -326,11 +326,13 @@ HF_TOKEN_TYPE_UNKNOWN: str = "unknown"
 #: a startup warning when a write token is used where a read / fine-grained
 #: token is the correct choice.  The ``"unknown"`` sentinel is included so
 #: that un-declared tokens do not trigger false-positive warnings.
-HF_INFERENCE_TOKEN_TYPES: frozenset[str] = frozenset({
-    HF_TOKEN_TYPE_FINE_GRAINED,
-    HF_TOKEN_TYPE_READ,
-    HF_TOKEN_TYPE_UNKNOWN,
-})
+HF_INFERENCE_TOKEN_TYPES: frozenset[str] = frozenset(
+    {
+        HF_TOKEN_TYPE_FINE_GRAINED,
+        HF_TOKEN_TYPE_READ,
+        HF_TOKEN_TYPE_UNKNOWN,
+    }
+)
 
 #: Token types that can push commits to HuggingFace repos and datasets.
 #:
@@ -338,10 +340,12 @@ HF_INFERENCE_TOKEN_TYPES: frozenset[str] = frozenset({
 #: returns HTTP 403 / 401.  ``"unknown"`` is excluded so that
 #: :func:`_validate_token_config` can flag a read token configured as the write
 #: token as a hard error rather than silently failing at request time.
-HF_WRITE_TOKEN_TYPES: frozenset[str] = frozenset({
-    HF_TOKEN_TYPE_FINE_GRAINED,
-    HF_TOKEN_TYPE_WRITE,
-})
+HF_WRITE_TOKEN_TYPES: frozenset[str] = frozenset(
+    {
+        HF_TOKEN_TYPE_FINE_GRAINED,
+        HF_TOKEN_TYPE_WRITE,
+    }
+)
 
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -673,10 +677,10 @@ def _classify_token_type(
     # Normalise accepted declared-type values (tolerate minor formatting variants).
     _declared_map: dict[str, HFTokenType] = {
         "fine-grained": "fine-grained",
-        "finegrained":  "fine-grained",
+        "finegrained": "fine-grained",
         "fine_grained": "fine-grained",
-        "read":         "read",
-        "write":        "write",
+        "read": "read",
+        "write": "write",
     }
     if declared_type:
         normalised = _declared_map.get(declared_type.lower().strip())
@@ -854,7 +858,8 @@ def _validate_token_config(
     Read token for writes → ERROR:
 
     >>> msgs = _validate_token_config(
-    ...     "hf_tok", "hf_readtok",
+    ...     "hf_tok",
+    ...     "hf_readtok",
     ...     training_dataset_repo="org/dataset",
     ...     hf_write_token_type="read",
     ... )
@@ -908,6 +913,7 @@ def _validate_token_config(
 
     return messages
 
+
 def _resolve_upstream_url(
     body: bytes,
     *,
@@ -1189,19 +1195,19 @@ def load_proxy_env() -> dict[str, Any]:
     )
 
     return {
-        "backend_url":      os.environ.get("BACKEND_URL", "").strip(),
-        "hf_token":         _hf_token,
+        "backend_url": os.environ.get("BACKEND_URL", "").strip(),
+        "hf_token": _hf_token,
         # Dedicated write token for dataset push operations.
         # Principle of least privilege: set HF_WRITE_TOKEN to a write-scoped
         # fine-grained token so HF_TOKEN can remain read-only / inference-only.
         # Falls back to hf_token when absent for backward compatibility.
-        "hf_write_token":        _hf_write_token,
-        "hf_dataset_token":      _hf_write_token or _hf_token,
+        "hf_write_token": _hf_write_token,
+        "hf_dataset_token": _hf_write_token or _hf_token,
         # Token type metadata — used by _validate_token_config at startup.
         # Operators can override auto-detection by setting HF_TOKEN_TYPE /
         # HF_WRITE_TOKEN_TYPE to "fine-grained", "read", or "write".
-        "hf_token_type":         _hf_token_type,
-        "hf_write_token_type":   _hf_write_token_type,
+        "hf_token_type": _hf_token_type,
+        "hf_write_token_type": _hf_write_token_type,
         "hf_base": os.environ.get("HF_BASE", DEFAULT_HF_BASE).rstrip("/"),
         "default_model": (
             os.environ.get("DEFAULT_MODEL", DEFAULT_MODEL).strip() or DEFAULT_MODEL

app.py

@@ -1,3 +1,10 @@
+# scikitplot/_externals/_sphinx_ext/_sphinx_ai_assistant/_hf_spaces_proxy/app.py
+#
+# flake8: noqa: D213
+#
+# Authors: The scikit-plots developers
+# SPDX-License-Identifier: BSD-3-Clause
+#
 # scikit-plots/ai  ·  _hf_spaces_proxy/app.py  v6.1.0
 #
 # Thin OpenAI-compatible reverse proxy for sphinx-ai-assistant.
@@ -117,6 +124,7 @@ import asyncio
 import json
 import logging
 import os
+import time as _time
 import uuid
 from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
@@ -128,50 +136,30 @@ from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse, Response, StreamingResponse
 
 # _shared_logic.py must live alongside this file.
-try:
-    from _shared_logic import (  # type: ignore[import]
-        DEFAULT_HF_BASE,
-        DEFAULT_HF_SPACES_MODEL_NAMESPACES,
-        DEFAULT_HF_SPACES_MODEL_URL,
-        DEFAULT_MAX_BODY_BYTES,
-        DEFAULT_MODEL,
-        DEFAULT_PATH2_READ_TIMEOUT,
-        DEFAULT_PATH3_READ_TIMEOUT,
-        DEFAULT_PROXY_TIMEOUT,
-        PROXY_VERSION,
-        _classify_token_type,
-        _resolve_upstream_url,
-        _safe_float,
-        _safe_int,
-        _token_log_fragment,
-        _validate_env,
-        _validate_token_config,
-    )
-except ImportError:
-    from .._shared_logic import (  # type: ignore[import]
-        DEFAULT_HF_BASE,
-        DEFAULT_HF_SPACES_MODEL_NAMESPACES,
-        DEFAULT_HF_SPACES_MODEL_URL,
-        DEFAULT_MAX_BODY_BYTES,
-        DEFAULT_MODEL,
-        DEFAULT_PATH2_READ_TIMEOUT,
-        DEFAULT_PATH3_READ_TIMEOUT,
-        DEFAULT_PROXY_TIMEOUT,
-        PROXY_VERSION,
-        _classify_token_type,
-        _resolve_upstream_url,
-        _safe_float,
-        _safe_int,
-        _token_log_fragment,
-        _validate_env,
-        _validate_token_config,
-    )
-
+from ._shared_logic import (  # type: ignore[import]
+    DEFAULT_HF_BASE,
+    DEFAULT_HF_SPACES_MODEL_NAMESPACES,
+    DEFAULT_HF_SPACES_MODEL_URL,
+    DEFAULT_MAX_BODY_BYTES,
+    DEFAULT_MODEL,
+    DEFAULT_PATH2_READ_TIMEOUT,
+    DEFAULT_PATH3_READ_TIMEOUT,
+    DEFAULT_PROXY_TIMEOUT,
+    PROXY_VERSION,
+    _classify_token_type,
+    _resolve_upstream_url,
+    _safe_float,
+    _safe_int,
+    _token_log_fragment,
+    _validate_env,
+    _validate_token_config,
+)
 
 # ─────────────────────────────────────────────────────────────────────────────
 # Helpers — placed before configuration so they are available at module scope
 # ─────────────────────────────────────────────────────────────────────────────
 
+
 def _client_ip(request: Request) -> str:
     """Extract the real client IP from the request.
 
@@ -204,6 +192,7 @@ def _client_ip(request: Request) -> str:
 # Logging
 # ─────────────────────────────────────────────────────────────────────────────
 
+
 class _StructuredFormatter(logging.Formatter):
     """Emit one JSON object per log record to stdout.
 
@@ -224,10 +213,10 @@ class _StructuredFormatter(logging.Formatter):
 
     def format(self, record: logging.LogRecord) -> str:  # noqa: A003
         payload: dict = {
-            "ts":     self.formatTime(record, datefmt="%Y-%m-%dT%H:%M:%S"),
-            "level":  record.levelname,
+            "ts": self.formatTime(record, datefmt="%Y-%m-%dT%H:%M:%S"),
+            "level": record.levelname,
             "logger": record.name,
-            "event":  record.getMessage(),
+            "event": record.getMessage(),
         }
         if record.exc_info:
             payload["exc_info"] = self.formatException(record.exc_info)
@@ -372,7 +361,9 @@ _path3_timeout_secs: float = _safe_float(
 #: TCP handshake timeout in seconds.
 #: Uses ``_safe_float`` — a non-numeric env var logs a warning and falls back
 #: to the default rather than raising ``ValueError`` at startup.
-_connect_timeout_secs: float = _safe_float(os.environ.get("PROXY_CONNECT_TIMEOUT"), 10.0)
+_connect_timeout_secs: float = _safe_float(
+    os.environ.get("PROXY_CONNECT_TIMEOUT"), 10.0
+)
 #: Request body upload timeout in seconds.
 _write_timeout_secs: float = _safe_float(os.environ.get("PROXY_WRITE_TIMEOUT"), 30.0)
 #: Connection pool acquire timeout in seconds.
@@ -437,7 +428,7 @@ MAX_CONTRIBUTION_RECORDS: int = 100
 #: When the dict would exceed this size a full sweep removes all entries whose
 #: sliding window has expired before the new entry is stored.  This bounds
 #: memory to O(_MAX_RL_ENTRIES) even under a slow-drip unique-IP scan that
-#: never re-uses the same address.  Value chosen to be generous for legitimate
+#: never reuses the same address.  Value chosen to be generous for legitimate
 #: traffic (thousands of real users) while preventing unbounded growth.
 _MAX_RL_ENTRIES: int = 10_000
 
@@ -554,7 +545,11 @@ async def _lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
         HF_SPACES_MODEL_URL or None,
         list(HF_SPACES_MODEL_NAMESPACES),
         _token_log_fragment(HF_TOKEN, token_type=HF_TOKEN_TYPE),
-        _token_log_fragment(HF_WRITE_TOKEN, token_type=HF_WRITE_TOKEN_TYPE) if HF_WRITE_TOKEN else "<using-hf-token-fallback>",
+        (
+            _token_log_fragment(HF_WRITE_TOKEN, token_type=HF_WRITE_TOKEN_TYPE)
+            if HF_WRITE_TOKEN
+            else "<using-hf-token-fallback>"
+        ),
         DEFAULT_MODEL,
     )
     logger.info(
@@ -964,11 +959,11 @@ async def root() -> JSONResponse:
             "status": "ok",
             "service": f"sphinx-ai-assistant proxy v{PROXY_VERSION}",
             "routing": {
-                "path_1_backend_url":       BACKEND_URL or None,
-                "path_2_model_space_url":   HF_SPACES_MODEL_URL or None,
-                "path_2_namespaces":        list(HF_SPACES_MODEL_NAMESPACES),
-                "path_3_hf_api_base":       HF_BASE,
-                "path_3_hf_token_set":      bool(HF_TOKEN),
+                "path_1_backend_url": BACKEND_URL or None,
+                "path_2_model_space_url": HF_SPACES_MODEL_URL or None,
+                "path_2_namespaces": list(HF_SPACES_MODEL_NAMESPACES),
+                "path_3_hf_api_base": HF_BASE,
+                "path_3_hf_token_set": bool(HF_TOKEN),
             },
             "tokens": {
                 # Never expose token values — only whether each slot is filled.
@@ -977,17 +972,17 @@ async def root() -> JSONResponse:
                 # reading Space logs.  Possible values: fine-grained | read | write |
                 # unknown.  "unknown" means the type could not be inferred — set
                 # HF_TOKEN_TYPE / HF_WRITE_TOKEN_TYPE in Space secrets to resolve.
-                "hf_token_set":         bool(HF_TOKEN),
-                "hf_token_type":        HF_TOKEN_TYPE,
-                "hf_write_token_set":   bool(HF_WRITE_TOKEN),
-                "hf_write_token_type":  HF_WRITE_TOKEN_TYPE,
+                "hf_token_set": bool(HF_TOKEN),
+                "hf_token_type": HF_TOKEN_TYPE,
+                "hf_write_token_set": bool(HF_WRITE_TOKEN),
+                "hf_write_token_type": HF_WRITE_TOKEN_TYPE,
                 # True when HF_WRITE_TOKEN is set; False means writes fall
                 # back to HF_TOKEN (single-token mode, less secure).
                 "least_privilege_mode": bool(HF_WRITE_TOKEN),
             },
             "training": {
-                "dataset_repo":             TRAINING_DATASET_REPO or None,
-                "contribute_ready":         bool(TRAINING_DATASET_REPO and HF_DATASET_TOKEN),
+                "dataset_repo": TRAINING_DATASET_REPO or None,
+                "contribute_ready": bool(TRAINING_DATASET_REPO and HF_DATASET_TOKEN),
                 "feedback_persist_enabled": FEEDBACK_PERSIST_ENABLED,
             },
             "timeouts": {
@@ -999,13 +994,13 @@ async def root() -> JSONResponse:
             },
             "cors_origins": _allowed_origins,
             "endpoints": {
-                "chat":      "POST /v1/chat/completions  (primary)",
-                "share":     "POST /v1/share             (conversation share)",
+                "chat": "POST /v1/chat/completions  (primary)",
+                "share": "POST /v1/share             (conversation share)",
                 "share_get": "GET  /v1/share/{uuid}      (retrieve shared snapshot)",
-                "feedback":  "POST /v1/feedback          (rating persistence)",
-                "training":  "POST /v1/contribute        (GDPR-gated training data)",
-                "alias":     "POST /                     (path-agnostic alias)",
-                "health":    "GET  /health               (liveness probe)",
+                "feedback": "POST /v1/feedback          (rating persistence)",
+                "training": "POST /v1/contribute        (GDPR-gated training data)",
+                "alias": "POST /                     (path-agnostic alias)",
+                "health": "GET  /health               (liveness probe)",
                 "head_root": "HEAD /                     (health-monitor probe)",
                 "head_health": "HEAD /health             (health-monitor probe)",
             },
@@ -1086,7 +1081,7 @@ async def chat_completions_alias(body: bytes = Depends(_validated_body)) -> Resp
 
 
 @app.post("/v1/contribute")
-async def contribute(request: Request) -> JSONResponse:
+async def contribute(request: Request) -> JSONResponse:  # noqa: PLR0912
     """Accept a training data contribution from the AI assistant browser widget.
 
     Parameters
@@ -1125,8 +1120,6 @@ async def contribute(request: Request) -> JSONResponse:
     traffic level this is acceptable; if throughput grows, wrap in
     ``asyncio.get_event_loop().run_in_executor(None, ...)`` instead.
     """
-    import time as _time
-
     # Body size guard
     raw = await request.body()
     if len(raw) > DEFAULT_MAX_BODY_BYTES:
@@ -1176,12 +1169,14 @@ async def contribute(request: Request) -> JSONResponse:
     async with _contrib_rl_lock:
         now = _time.time()
         count, window_start = _contrib_rl.get(client_ip, (0, now))
-        if now - window_start > 3600:
+        if now - window_start > 3600:  # noqa: PLR2004
             count, window_start = 0, now
         count += 1
         _contrib_rl[client_ip] = (count, window_start)
-        if count > 5:
-            logger.warning(json.dumps({"event": "contribute.ratelimit", "ip": client_ip}))
+        if count > 5:  # noqa: PLR2004
+            logger.warning(
+                json.dumps({"event": "contribute.ratelimit", "ip": client_ip})
+            )
             raise HTTPException(
                 status_code=429,
                 detail="Rate limit exceeded. Maximum 5 contributions per hour.",
@@ -1209,7 +1204,7 @@ async def contribute(request: Request) -> JSONResponse:
     # HF_DATASET_TOKEN resolves to HF_WRITE_TOKEN when set, else HF_TOKEN.
     # This ensures the inference token (HF_TOKEN, read-only) is never used
     # for dataset write operations when a dedicated write token is available.
-    from huggingface_hub import CommitOperationAdd, HfApi
+    from huggingface_hub import CommitOperationAdd, HfApi  # noqa: PLC0415
 
     api = HfApi(token=HF_DATASET_TOKEN)
     session_id: str = payload.get("sessionId", "")
@@ -1217,23 +1212,23 @@ async def contribute(request: Request) -> JSONResponse:
         json.dumps(
             {
                 **rec,
-                "_sessionId":      session_id,
-                "_page":           payload.get("page", ""),
-                "_model":          payload.get("model"),
+                "_sessionId": session_id,
+                "_page": payload.get("page", ""),
+                "_model": payload.get("model"),
                 "_consentVersion": payload.get("consentVersion"),
-                "_ts":             int(_time.time() * 1000),
+                "_ts": int(_time.time() * 1000),
                 # Provenance tag: distinguishes records that arrived via the
                 # explicit GDPR-gated "Contribute" button (end-of-session) from
                 # records that arrived via the immediate per-answer rating button
                 # (POST /v1/feedback).  Training pipelines MUST prefer
                 # "contribution" over "feedback" when both exist for the same
                 # dedup key.  See DATASET_COLLECTION_GUIDANCE.md.
-                "_source":         "contribution",
+                "_source": "contribution",
                 # Stable dedup key: "{conversationSessionId}:{answerIndex}".
                 # Identical key format used by /v1/feedback (when
                 # FEEDBACK_PERSIST_ENABLED=true) so a simple equality check
                 # across folders is sufficient to detect cross-source duplicates.
-                "_dedup_key":      f"{session_id}:{rec.get('answerIndex', '')}",
+                "_dedup_key": f"{session_id}:{rec.get('answerIndex', '')}",
             },
             ensure_ascii=False,
         )
@@ -1246,12 +1241,16 @@ async def contribute(request: Request) -> JSONResponse:
         # the dataset; fail fast with a clear error before touching HuggingFace.
         if not rows_jsonl.strip():
             logger.error(
-                json.dumps({
-                    "event":   "contribute.empty_jsonl",
-                    "records": len(records),
-                    "detail":  "rows_jsonl is empty after serialising records; "
-                               "aborting HF commit to prevent corrupt dataset file.",
-                })
+                json.dumps(
+                    {
+                        "event": "contribute.empty_jsonl",
+                        "records": len(records),
+                        "detail": (
+                            "rows_jsonl is empty after serialising records; "
+                            "aborting HF commit to prevent corrupt dataset file."
+                        ),
+                    }
+                )
             )
             raise HTTPException(
                 status_code=422,
@@ -1288,7 +1287,9 @@ async def contribute(request: Request) -> JSONResponse:
             detail="Failed to store contribution. Try again later.",
         ) from exc
 
-    logger.info(json.dumps({"event": "contribute.write", "rows": len(records), "ip": client_ip}))
+    logger.info(
+        json.dumps({"event": "contribute.write", "rows": len(records), "ip": client_ip})
+    )
     return JSONResponse({"contributed": True, "rows": len(records)})
 
 
@@ -1335,8 +1336,6 @@ async def share(request: Request) -> JSONResponse:
     permissive than ``/v1/contribute`` because share payloads are user-facing
     outputs, not GDPR-sensitive training data.
     """
-    import time as _time
-
     # Body size guard
     raw = await request.body()
     if len(raw) > DEFAULT_MAX_BODY_BYTES:
@@ -1365,11 +1364,11 @@ async def share(request: Request) -> JSONResponse:
     async with _share_rl_lock:
         now = _time.time()
         count, window_start = _share_rl.get(client_ip, (0, now))
-        if now - window_start > 3600:
+        if now - window_start > 3600:  # noqa: PLR2004
             count, window_start = 0, now
         count += 1
         _share_rl[client_ip] = (count, window_start)
-        if count > 10:
+        if count > 10:  # noqa: PLR2004
             logger.warning(json.dumps({"event": "share.ratelimit", "ip": client_ip}))
             raise HTTPException(
                 status_code=429,
@@ -1384,21 +1383,28 @@ async def share(request: Request) -> JSONResponse:
 
     # Store in memory; evict expired entries lazily on each write.
     async with _share_store_lock:
-        expired_keys = [k for k, v in _share_store.items() if v["expiresAt_ts"] < now_ts]
+        expired_keys = [
+            k for k, v in _share_store.items() if v["expiresAt_ts"] < now_ts
+        ]
         for k in expired_keys:
             del _share_store[k]
         _share_store[share_id] = {
-            "content":     content,
-            "mimeType":    mime_type,
-            "ext":         ext,
-            "title":       title,
+            "content": content,
+            "mimeType": mime_type,
+            "ext": ext,
+            "title": title,
             "expiresAt_ts": expires_ts,
-            "expiresAt":   expires_iso,
+            "expiresAt": expires_iso,
         }
 
     logger.info(
         json.dumps(
-            {"event": "share.create", "id": share_id, "ip": client_ip, "ttl_days": ttl_days}
+            {
+                "event": "share.create",
+                "id": share_id,
+                "ip": client_ip,
+                "ttl_days": ttl_days,
+            }
         )
     )
 
@@ -1434,8 +1440,6 @@ async def share_get(share_id: str) -> Response:
     **User note** — Shares are stored in process memory only.  A Space
     restart clears all shares, returning 404 for previously valid links.
     """
-    import time as _time
-
     async with _share_store_lock:
         entry = _share_store.get(share_id)
 
@@ -1452,7 +1456,9 @@ async def share_get(share_id: str) -> Response:
         status_code=200,
         media_type=entry.get("mimeType", "text/html;charset=utf-8"),
         headers={
-            "Content-Disposition": f'inline; filename="share{entry.get("ext", ".html")}"',
+            "Content-Disposition": (
+                f'inline; filename="share{entry.get("ext", ".html")}"'
+            ),
         },
     )
 
@@ -1521,8 +1527,6 @@ async def feedback(request: Request) -> JSONResponse:
     the ``feedback`` record — the GDPR-gated explicit contribution is the
     higher-quality signal.
     """
-    import time as _time
-
     # Body size guard
     raw = await request.body()
     if len(raw) > DEFAULT_MAX_BODY_BYTES:
@@ -1534,7 +1538,9 @@ async def feedback(request: Request) -> JSONResponse:
         raise HTTPException(status_code=400, detail=f"Invalid JSON: {exc}") from exc
 
     if not isinstance(payload, dict):
-        raise HTTPException(status_code=422, detail="Feedback body must be a JSON object.")
+        raise HTTPException(
+            status_code=422, detail="Feedback body must be a JSON object."
+        )
 
     # ── Distinguish retraction tombstones from regular ratings ───────────────
     # Retractions are system-generated housekeeping records that invalidate a
@@ -1562,13 +1568,13 @@ async def feedback(request: Request) -> JSONResponse:
         logger.info(
             json.dumps(
                 {
-                    "event":          "feedback.retract",
-                    "ip":             client_ip,
-                    "prevSessionId":  payload.get("prevSessionId"),
+                    "event": "feedback.retract",
+                    "ip": client_ip,
+                    "prevSessionId": payload.get("prevSessionId"),
                     "conversationId": payload.get("conversationId"),
-                    "answerIndex":    payload.get("answerIndex"),
-                    "ts":             payload.get("ts"),
-                    "persist":        FEEDBACK_PERSIST_ENABLED,
+                    "answerIndex": payload.get("answerIndex"),
+                    "ts": payload.get("ts"),
+                    "persist": FEEDBACK_PERSIST_ENABLED,
                 }
             )
         )
@@ -1586,12 +1592,14 @@ async def feedback(request: Request) -> JSONResponse:
                 for k in expired:
                     del _feedback_rl[k]
             count, window_start = _feedback_rl.get(client_ip, (0, now))
-            if now - window_start > 3600:
+            if now - window_start > 3600:  # noqa: PLR2004
                 count, window_start = 0, now
             count += 1
             _feedback_rl[client_ip] = (count, window_start)
-            if count > 30:
-                logger.warning(json.dumps({"event": "feedback.ratelimit", "ip": client_ip}))
+            if count > 30:  # noqa: PLR2004
+                logger.warning(
+                    json.dumps({"event": "feedback.ratelimit", "ip": client_ip})
+                )
                 raise HTTPException(
                     status_code=429,
                     detail="Rate limit exceeded. Maximum 30 feedback submissions per hour.",
@@ -1601,15 +1609,15 @@ async def feedback(request: Request) -> JSONResponse:
         logger.info(
             json.dumps(
                 {
-                    "event":          "feedback.receive",
-                    "ip":             client_ip,
-                    "ratingValue":    payload.get("ratingValue"),
-                    "model":          payload.get("model"),
+                    "event": "feedback.receive",
+                    "ip": client_ip,
+                    "ratingValue": payload.get("ratingValue"),
+                    "model": payload.get("model"),
                     "conversationId": payload.get("conversationId"),
-                    "answerIndex":    payload.get("answerIndex"),
-                    "page":           payload.get("page"),
-                    "ts":             payload.get("ts"),
-                    "persist":        FEEDBACK_PERSIST_ENABLED,
+                    "answerIndex": payload.get("answerIndex"),
+                    "page": payload.get("page"),
+                    "ts": payload.get("ts"),
+                    "persist": FEEDBACK_PERSIST_ENABLED,
                 }
             )
         )
@@ -1627,7 +1635,7 @@ async def feedback(request: Request) -> JSONResponse:
     # rating also wasn't persisted, so there is nothing to suppress.
     if FEEDBACK_PERSIST_ENABLED and TRAINING_DATASET_REPO and HF_DATASET_TOKEN:
         try:
-            from huggingface_hub import CommitOperationAdd, HfApi
+            from huggingface_hub import CommitOperationAdd, HfApi  # noqa: PLC0415
 
             # ``conversationId`` is the stable per-page-load session UUID that
             # the JS widget sets as ``detail.conversationId = _sessionId``.
@@ -1641,7 +1649,7 @@ async def feedback(request: Request) -> JSONResponse:
             record = json.dumps(
                 {
                     **payload,
-                    "_ts":         int(_time.time() * 1000),
+                    "_ts": int(_time.time() * 1000),
                     # Provenance — training pipelines must discard "feedback"
                     # records whenever a "contribution" record exists for the
                     # same _dedup_key.  Retraction tombstones also use
@@ -1650,11 +1658,11 @@ async def feedback(request: Request) -> JSONResponse:
                     # overrides retraction).  deduplicate_dataset.py filters
                     # action="retract" winners from the clean output.
                     # See DATASET_COLLECTION_GUIDANCE.md §3 and §8.
-                    "_source":     "feedback",
+                    "_source": "feedback",
                     # "{conversationId}:{answerIndex}" — identical key format
                     # to contribution records; equality check is sufficient to
                     # detect cross-source duplicates.
-                    "_dedup_key":  f"{conversation_id}:{answer_index}",
+                    "_dedup_key": f"{conversation_id}:{answer_index}",
                 },
                 ensure_ascii=False,
             )
@@ -1681,10 +1689,10 @@ async def feedback(request: Request) -> JSONResponse:
             logger.info(
                 json.dumps(
                     {
-                        "event":       "feedback.persist_ok",
-                        "retract":     is_retract,
-                        "dedup_key":   f"{conversation_id}:{answer_index}",
-                        "ip":          client_ip,
+                        "event": "feedback.persist_ok",
+                        "retract": is_retract,
+                        "dedup_key": f"{conversation_id}:{answer_index}",
+                        "ip": client_ip,
                     }
                 )
             )
@@ -1692,9 +1700,7 @@ async def feedback(request: Request) -> JSONResponse:
             # Never propagate — the JS widget does not read the response body
             # and the user's rating must always be acknowledged with 200.
             logger.error(
-                json.dumps(
-                    {"event": "feedback.persist_fail", "error": str(exc)}
-                )
+                json.dumps({"event": "feedback.persist_fail", "error": str(exc)})
             )
 
     return JSONResponse({"ok": True})