Upload 5 files

README.md

@@ -1,16 +1,16 @@
 ---
-pinned: false
 title: sphinx-ai-assistant proxy
 emoji: 🔁
 colorFrom: blue
 colorTo: green
-license: bsd-3-clause
-short_description: ai
+sdk: docker
+app_port: 7860
+pinned: false
 hf_oauth: true
 hf_oauth_scopes:
   - inference-api
-sdk: docker
-app_port: 7860
+license: bsd-3-clause
+short_description: ai
 ---
 
 # sphinx-ai-assistant proxy

_shared_logic.py

@@ -482,7 +482,9 @@ def _resolve_upstream_url(
     hf_base: str = DEFAULT_HF_BASE,
     default_model: str = DEFAULT_MODEL,
     hf_spaces_model_url: str = DEFAULT_HF_SPACES_MODEL_URL,
-    hf_spaces_model_namespaces: tuple[str, ...] | list[str] = DEFAULT_HF_SPACES_MODEL_NAMESPACES,
+    hf_spaces_model_namespaces: (
+        tuple[str, ...] | list[str]
+    ) = DEFAULT_HF_SPACES_MODEL_NAMESPACES,
     proxy_timeout: float = float(DEFAULT_PROXY_TIMEOUT),
     path2_read_timeout: float = DEFAULT_PATH2_READ_TIMEOUT,
     path3_read_timeout: float = DEFAULT_PATH3_READ_TIMEOUT,

app.py

@@ -97,6 +97,7 @@ Developer note — explicit error handling
 
 from __future__ import annotations
 
+import asyncio
 import json
 import logging
 import os
@@ -147,14 +148,76 @@ except ImportError:
     )
 
 
+# ─────────────────────────────────────────────────────────────────────────────
+# 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.
+
+    Parameters
+    ----------
+    request : fastapi.Request
+        Incoming HTTP request.
+
+    Returns
+    -------
+    str
+        Best-effort client IP string; ``"unknown"`` when unavailable.
+
+    Notes
+    -----
+    Developer: HF Spaces sits behind a proxy so ``request.client.host``
+    is the proxy IP, not the user IP.  ``X-Forwarded-For`` is the correct
+    source — take the FIRST value only (leftmost = original client;
+    rightmost values can be spoofed by intermediaries).
+    """
+    xff = request.headers.get("x-forwarded-for", "")
+    if xff:
+        return xff.split(",")[0].strip()
+    if request.client:
+        return request.client.host or "unknown"
+    return "unknown"
+
+
 # ─────────────────────────────────────────────────────────────────────────────
 # Logging
 # ─────────────────────────────────────────────────────────────────────────────
 
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s | %(levelname)-8s | %(name)s | %(message)s",
-)
+class _StructuredFormatter(logging.Formatter):
+    """Emit one JSON object per log record to stdout.
+
+    Parameters
+    ----------
+    *args, **kwargs
+        Forwarded to :class:`logging.Formatter`.
+
+    Notes
+    -----
+    Developer: JSON format is required for machine-parseable log ingestion
+    (HF Spaces log export, Datadog, etc.).  Text-format lines require regex
+    in log queries; JSON fields are natively queryable.
+
+    The ``exc_info`` key is omitted entirely when no exception is attached
+    so log consumers do not need to handle a null field on every record.
+    """
+
+    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,
+            "logger": record.name,
+            "event":  record.getMessage(),
+        }
+        if record.exc_info:
+            payload["exc_info"] = self.formatException(record.exc_info)
+        return json.dumps(payload, ensure_ascii=False)
+
+
+_handler = logging.StreamHandler()
+_handler.setFormatter(_StructuredFormatter())
+logging.root.handlers = [_handler]
+logging.root.setLevel(logging.INFO)
 logger = logging.getLogger(__name__)
 
 
@@ -172,23 +235,22 @@ HF_TOKEN: str = os.environ.get("HF_TOKEN", "").strip()
 HF_BASE: str = os.environ.get("HF_BASE", DEFAULT_HF_BASE).rstrip("/")
 
 #: Fallback model when request body omits ``model``.
-DEFAULT_MODEL = (
-    os.environ.get("DEFAULT_MODEL", DEFAULT_MODEL).strip() or DEFAULT_MODEL
-)
+DEFAULT_MODEL = os.environ.get("DEFAULT_MODEL", DEFAULT_MODEL).strip() or DEFAULT_MODEL
 
 #: Path 2 destination URL — the custom ai-model HF Space.
-HF_SPACES_MODEL_URL: str = (
-    os.environ.get("HF_SPACES_MODEL_URL", DEFAULT_HF_SPACES_MODEL_URL).strip()
-)
+HF_SPACES_MODEL_URL: str = os.environ.get(
+    "HF_SPACES_MODEL_URL", DEFAULT_HF_SPACES_MODEL_URL
+).strip()
 
 #: Parsed model owner namespaces routed to HF_SPACES_MODEL_URL (Path 2).
 _raw_namespaces: str = os.environ.get(
     "HF_SPACES_MODEL_NAMESPACES",
     ",".join(DEFAULT_HF_SPACES_MODEL_NAMESPACES),
 )
-HF_SPACES_MODEL_NAMESPACES: tuple[str, ...] = tuple(
-    ns.strip() for ns in _raw_namespaces.split(",") if ns.strip()
-) or DEFAULT_HF_SPACES_MODEL_NAMESPACES
+HF_SPACES_MODEL_NAMESPACES: tuple[str, ...] = (
+    tuple(ns.strip() for ns in _raw_namespaces.split(",") if ns.strip())
+    or DEFAULT_HF_SPACES_MODEL_NAMESPACES
+)
 
 #: Maximum accepted request body size (bytes).
 MAX_BODY_BYTES: int = _safe_int(
@@ -198,10 +260,12 @@ MAX_BODY_BYTES: int = _safe_int(
 
 # ── Per-path read timeouts ────────────────────────────────────────────────────
 #: Path 1 (BACKEND_URL) read timeout in seconds.
-_proxy_timeout_secs: float = float(_safe_int(
-    os.environ.get("PROXY_TIMEOUT"),
-    DEFAULT_PROXY_TIMEOUT,
-))
+_proxy_timeout_secs: float = float(
+    _safe_int(
+        os.environ.get("PROXY_TIMEOUT"),
+        DEFAULT_PROXY_TIMEOUT,
+    )
+)
 
 #: Path 2 (ai-model Space, CPU inference) read timeout in seconds.
 #: Default 600 s — covers 4-5 min CPU inference with 1 min headroom.
@@ -237,6 +301,22 @@ _allowed_origins: list[str] = (
     else [o.strip() for o in _raw_origins.split(",") if o.strip()]
 )
 
+#: HuggingFace Dataset repo for training contributions.
+#: Must be set if POST /v1/contribute is expected to succeed.
+TRAINING_DATASET_REPO: str = os.environ.get("TRAINING_DATASET_REPO", "").strip()
+
+#: Current consent version string.  Must match the JS constant _TRAINING_CONSENT_VERSION.
+#: Increment when the consent UI text changes materially.
+TRAINING_CONSENT_VERSION: str = "v1.0"
+
+#: Maximum records per contribution POST.
+MAX_CONTRIBUTION_RECORDS: int = 100
+
+#: In-memory per-IP rate-limit store for contribution endpoint.
+#: Keys: IP string.  Values: (count, window_start_timestamp).
+_contrib_rl: dict[str, tuple[int, float]] = {}
+_contrib_rl_lock = asyncio.Lock()
+
 
 # ─────────────────────────────────────────────────────────────────────────────
 # Startup validation — fail fast with actionable messages
@@ -334,7 +414,10 @@ app.add_middleware(
     CORSMiddleware,
     allow_origins=_allowed_origins,
     allow_methods=["GET", "POST", "OPTIONS"],
-    allow_headers=["Content-Type"],
+    # Authorization added for write endpoints (POST /v1/feedback, POST /v1/contribute)
+    # that validate a Bearer token.  Without this the browser preflight rejects
+    # requests containing Authorization headers before the handler runs.
+    allow_headers=["Content-Type", "Authorization"],
     allow_credentials=False,
 )
 
@@ -515,13 +598,15 @@ async def _forward(body: bytes) -> Response:
                 ) as upstream:
                     if upstream.status_code != 200:  # noqa: PLR2004
                         err_body = await upstream.aread()
-                        error_payload = json.dumps({
-                            "id":    f"err-{uuid.uuid4().hex}",
-                            "error": {
-                                "status":  upstream.status_code,
-                                "message": err_body.decode(errors="replace")[:500],
-                            },
-                        })
+                        error_payload = json.dumps(
+                            {
+                                "id": f"err-{uuid.uuid4().hex}",
+                                "error": {
+                                    "status": upstream.status_code,
+                                    "message": err_body.decode(errors="replace")[:500],
+                                },
+                            }
+                        )
                         yield f"data: {error_payload}\n\n".encode()
                     else:
                         async for chunk in upstream.aiter_bytes():
@@ -531,12 +616,14 @@ async def _forward(body: bytes) -> Response:
                 err_id = uuid.uuid4().hex
                 logger.warning(
                     "ReadTimeout after %.0f s on streaming request to %s [%s]",
-                    read_timeout_s, url, err_id,
+                    read_timeout_s,
+                    url,
+                    err_id,
                 )
                 yield f'data: {{"id":"err-{err_id}","error":{{"status":504,"message":'
                 yield (
                     f'"Upstream timed out after {read_timeout_s:.0f} s. '
-                    f'CPU inference can take 4-5 minutes. '
+                    f"CPU inference can take 4-5 minutes. "
                     f'If using the ai-model Space, the model may still be loading."}}}}\n\n'
                 ).encode()
 
@@ -555,7 +642,9 @@ async def _forward(body: bytes) -> Response:
                 err_id = uuid.uuid4().hex
                 logger.warning(
                     "RequestError on streaming request to %s: %s [%s]",
-                    url, exc, err_id,
+                    url,
+                    exc,
+                    err_id,
                 )
                 yield (
                     f'data: {{"id":"err-{err_id}","error":{{"status":502,"message":'
@@ -567,7 +656,7 @@ async def _forward(body: bytes) -> Response:
             status_code=200,
             media_type="text/event-stream",
             headers={
-                "Cache-Control":     "no-cache",
+                "Cache-Control": "no-cache",
                 "X-Accel-Buffering": "no",
             },
         )
@@ -580,13 +669,14 @@ async def _forward(body: bytes) -> Response:
     except httpx.ReadTimeout:
         logger.warning(
             "ReadTimeout after %.0f s on non-streaming request to %s",
-            read_timeout_s, url,
+            read_timeout_s,
+            url,
         )
         return JSONResponse(
             status_code=504,
             content={
                 "error": {
-                    "type":    "timeout_error",
+                    "type": "timeout_error",
                     "message": (
                         f"Upstream timed out after {read_timeout_s:.0f} s. "
                         "CPU inference on the ai-model Space can take 4-5 minutes. "
@@ -601,7 +691,7 @@ async def _forward(body: bytes) -> Response:
             status_code=504,
             content={
                 "error": {
-                    "type":    "timeout_error",
+                    "type": "timeout_error",
                     "message": (
                         f"Connection timed out reaching {url}. "
                         "The HF Space may be cold-starting — retry in 30 seconds."
@@ -615,7 +705,7 @@ async def _forward(body: bytes) -> Response:
             status_code=502,
             content={
                 "error": {
-                    "type":    "upstream_error",
+                    "type": "upstream_error",
                     "message": f"Failed to reach upstream: {type(exc).__name__}",
                 }
             },
@@ -650,30 +740,32 @@ async def root() -> JSONResponse:
     default 600 s).  ``path3`` corresponds to the HF Serverless API (GPU,
     default 120 s).
     """
-    return 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),
-        },
-        "timeouts": {
-            "path1_s": _proxy_timeout_secs,
-            "path2_s": _path2_timeout_secs,
-            "path3_s": _path3_timeout_secs,
-            "connect_s": _connect_timeout_secs,
-            "write_s": _write_timeout_secs,
-        },
-        "cors_origins": _allowed_origins,
-        "endpoints": {
-            "chat":   "POST /v1/chat/completions  (primary)",
-            "alias":  "POST /                     (path-agnostic alias)",
-            "health": "GET  /health               (liveness probe)",
-        },
-    })
+    return 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),
+            },
+            "timeouts": {
+                "path1_s": _proxy_timeout_secs,
+                "path2_s": _path2_timeout_secs,
+                "path3_s": _path3_timeout_secs,
+                "connect_s": _connect_timeout_secs,
+                "write_s": _write_timeout_secs,
+            },
+            "cors_origins": _allowed_origins,
+            "endpoints": {
+                "chat": "POST /v1/chat/completions  (primary)",
+                "alias": "POST /                     (path-agnostic alias)",
+                "health": "GET  /health               (liveness probe)",
+            },
+        }
+    )
 
 
 @app.get("/health")
@@ -746,3 +838,157 @@ async def chat_completions_alias(body: bytes = Depends(_validated_body)) -> Resp
     to the bare Space URL without the path suffix.
     """
     return await _forward(body)
+
+
+@app.post("/v1/contribute")
+async def contribute(request: Request) -> JSONResponse:
+    """Accept a training data contribution from the AI assistant browser widget.
+
+    Parameters
+    ----------
+    request : fastapi.Request
+        HTTP request.  Body must be JSON conforming to the contribution schema.
+
+    Returns
+    -------
+    fastapi.responses.JSONResponse
+        ``{"contributed": true, "rows": N}`` on success.
+
+    Raises
+    ------
+    fastapi.HTTPException
+        422 when consent is absent/false, schemaVersion is unsupported, or
+        records exceed the maximum allowed count.
+        429 when the IP rate limit is exceeded.
+        503 when the HF Dataset push fails.
+
+    Notes
+    -----
+    Developer: ``consentFlag`` and ``consentVersion`` are checked before any
+    other validation.  A missing or mismatched consent version is a hard
+    rejection — the UI must always send the current version string so that
+    old cached pages cannot submit records that would silently bypass a
+    consent-text update.
+
+    Developer: The in-memory rate-limit store (``_contrib_rl``) is per-process
+    only.  HF Spaces may run multiple replicas.  The limit (5 per hour) is
+    intentionally loose; the primary defence is the GDPR consent gate.
+
+    Developer: ``huggingface_hub.HfApi.commit`` is called synchronously inside
+    an async handler.  This blocks the event loop for the duration of the HTTP
+    round-trip to HF (~200 ms on a warm connection).  For the current 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:
+        raise HTTPException(status_code=413, detail="Payload too large.")
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise HTTPException(status_code=400, detail=f"Invalid JSON: {exc}") from exc
+
+    # Consent guard — GDPR Article 7: explicit consent required
+    if not payload.get("consentFlag"):
+        raise HTTPException(
+            status_code=422,
+            detail="consentFlag must be true.  Contribution requires explicit user consent.",
+        )
+    if payload.get("consentVersion") != TRAINING_CONSENT_VERSION:
+        raise HTTPException(
+            status_code=422,
+            detail=(
+                f"consentVersion {payload.get('consentVersion')!r} is not current. "
+                f"Expected {TRAINING_CONSENT_VERSION!r}. Reload the page and try again."
+            ),
+        )
+
+    # Schema version guard
+    supported_versions: frozenset[int] = frozenset({1})
+    if payload.get("schemaVersion") not in supported_versions:
+        raise HTTPException(
+            status_code=422,
+            detail=(
+                f"Unsupported schemaVersion {payload.get('schemaVersion')!r}. "
+                f"Supported: {sorted(supported_versions)}"
+            ),
+        )
+
+    records = payload.get("records", [])
+    if not isinstance(records, list):
+        raise HTTPException(status_code=422, detail="records must be a list.")
+    if len(records) > MAX_CONTRIBUTION_RECORDS:
+        raise HTTPException(
+            status_code=422,
+            detail=f"Too many records. Maximum {MAX_CONTRIBUTION_RECORDS} per request.",
+        )
+
+    # Per-IP rate limit: 5 contributions per hour
+    client_ip = _client_ip(request)
+    async with _contrib_rl_lock:
+        now = _time.time()
+        count, window_start = _contrib_rl.get(client_ip, (0, now))
+        if now - window_start > 3600:
+            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}))
+            raise HTTPException(
+                status_code=429,
+                detail="Rate limit exceeded. Maximum 5 contributions per hour.",
+                headers={"Retry-After": "3600"},
+            )
+
+    if not TRAINING_DATASET_REPO:
+        raise HTTPException(
+            status_code=503,
+            detail="Training endpoint not configured (TRAINING_DATASET_REPO not set).",
+        )
+    if not HF_TOKEN:
+        raise HTTPException(status_code=503, detail="HF_TOKEN not set.")
+
+    # Push to HF Dataset
+    from huggingface_hub import CommitOperationAdd, HfApi
+
+    api = HfApi(token=HF_TOKEN)
+    rows_jsonl = "\n".join(
+        json.dumps(
+            {
+                **rec,
+                "_sessionId":      payload.get("sessionId", ""),
+                "_page":           payload.get("page", ""),
+                "_model":          payload.get("model"),
+                "_consentVersion": payload.get("consentVersion"),
+                "_ts":             int(_time.time() * 1000),
+            },
+            ensure_ascii=False,
+        )
+        for rec in records
+        if isinstance(rec, dict)
+    )
+    filename = f"contributions/{int(_time.time() * 1000)}.jsonl"
+    try:
+        api.commit(
+            repo_id=TRAINING_DATASET_REPO,
+            repo_type="dataset",
+            operations=[
+                CommitOperationAdd(
+                    path_in_repo=filename,
+                    path_or_fileobj=rows_jsonl.encode(),
+                )
+            ],
+            commit_message=f"Add {len(records)} feedback record(s)",
+        )
+    except Exception as exc:
+        logger.error(json.dumps({"event": "contribute.hf_fail", "error": str(exc)}))
+        raise HTTPException(
+            status_code=503,
+            detail="Failed to store contribution. Try again later.",
+        ) from exc
+
+    logger.info(json.dumps({"event": "contribute.write", "rows": len(records), "ip": client_ip}))
+    return JSONResponse({"contributed": True, "rows": len(records)})

requirements.txt

@@ -1,4 +1,4 @@
-# scikit-plots/ai  ·  requirements.txt  v3.1.0
+# scikit-plots/ai  ·  requirements.txt  v3.2.0
 #
 # Pin with ~= (compatible release) to allow patch upgrades while preventing
 # breaking minor/major version changes across HF Space restarts.
@@ -11,3 +11,7 @@
 fastapi~=0.111.0
 uvicorn[standard]~=0.29.0
 httpx~=0.27.0
+# Required for POST /v1/contribute: push Q&A training records to a HF Dataset.
+# HF_TOKEN (Space secret) is used server-side; no token exposed to the browser.
+# Upper bound omitted — huggingface_hub follows semver and is stable across minors.
+huggingface_hub~=0.23.0