Trim comments; server-key gate, usage log, store=True for retrievable summaries

api.py

@@ -49,6 +49,47 @@ progress_map: Dict[str, Dict[str, int]] = {}
 # Add a lock for thread-safe access to progress_map
 progress_lock = threading.Lock()
 
+USAGE_LOG_PATH = os.path.join("visualizations", "openai_usage_log.jsonl")
+_usage_log_lock = threading.Lock()
+
+
+def _log_openai_call(
+    endpoint: str,
+    model: str,
+    article: Optional[str],
+    used_server_key: bool,
+    prompt_chars: int,
+    response_chars: int,
+    usage: Optional[Dict[str, Any]] = None,
+    extra: Optional[Dict[str, Any]] = None,
+) -> None:
+    """Append one line describing an OpenAI call to the log. Best-effort:
+    failures are swallowed so logging can never break the request."""
+    record: Dict[str, Any] = {
+        "ts": _utc_now_iso(),
+        "endpoint": endpoint,
+        "model": model,
+        "article": article,
+        "used_server_key": bool(used_server_key),
+        "prompt_chars": int(prompt_chars),
+        "response_chars": int(response_chars),
+    }
+    if usage:
+        record["usage"] = usage
+    if extra:
+        record.update(extra)
+    try:
+        with _usage_log_lock:
+            with open(USAGE_LOG_PATH, "a", encoding="utf-8") as f:
+                f.write(json.dumps(record, ensure_ascii=False) + "\n")
+    except Exception as log_err:  # pragma: no cover - logging must never throw
+        print(f"[warn] failed to write usage log: {log_err}")
+
+
+def _utc_now_iso() -> str:
+    from datetime import datetime, timezone
+    return datetime.now(timezone.utc).isoformat()
+
 # Initialize FastAPI app
 app = FastAPI(title="Wiki Revision Classifier API")
 
@@ -173,8 +214,7 @@ async def classify_article(payload: ClassifyPayload, background_tasks: Backgroun
     Start classification in the background and return immediately.
     Uses the flexible-linker pipeline + OpenAI Batch API (single batch).
     """
-    # The classification pipeline runs on the user's own key — never the
-    # server secret. The demo path doesn't hit /classify at all.
+    # Classification always runs on the user's own key.
     api_key = _resolve_api_key(payload.api_key, allow_secret_fallback=False)
     model_name = payload.model or "gpt-5-mini"
 
@@ -588,10 +628,8 @@ class SummarizePayload(BaseModel):
     section_ids: Optional[List[int]] = None  # grouped_idx values; None = all sections
     api_key: Optional[str] = None
     model: Optional[str] = "gpt-5.4"
-    # Whether this summary may use the server's OPENAI_API_KEY secret. True
-    # only for the demo pages (their summaries run on the provided secret key).
-    # False for summaries on a user-generated page or an uploaded CSV, which
-    # must run on the user's own key.
+    # Set only for the built-in demo pages; other summaries run on the user's
+    # own key.
     use_server_key: bool = False
     # When the dataset lives only in the user's browser (CSV they uploaded),
     # the frontend filters rows itself and sends just the matching explanation
@@ -789,6 +827,7 @@ def generate_evolution_summary(
     client = openai.OpenAI(api_key=api_key)
     completion = client.chat.completions.create(
         model="gpt-5.4",
+        store=True,
         messages=[
             {
                 "role": "system",
@@ -802,9 +841,33 @@ def generate_evolution_summary(
         ],
     )
     text = completion.choices[0].message.content or ""
+    _log_openai_call(
+        endpoint="evolution",
+        model="gpt-5.4",
+        article=None,
+        used_server_key=False,
+        prompt_chars=len(user_prompt),
+        response_chars=len(text),
+        usage=_usage_dict(completion),
+    )
     return text.strip() or None
 
 
+def _usage_dict(completion: Any) -> Optional[Dict[str, Any]]:
+    """Pull token counts out of a chat completion response, if present."""
+    usage = getattr(completion, "usage", None)
+    if usage is None:
+        return None
+    try:
+        return {
+            "prompt_tokens": getattr(usage, "prompt_tokens", None),
+            "completion_tokens": getattr(usage, "completion_tokens", None),
+            "total_tokens": getattr(usage, "total_tokens", None),
+        }
+    except Exception:
+        return None
+
+
 @app.post("/summarize")
 async def summarize_edits(payload: SummarizePayload) -> Dict[str, Any]:
     """
@@ -812,6 +875,28 @@ async def summarize_edits(payload: SummarizePayload) -> Dict[str, Any]:
     section-group) cell using a fast OpenAI model. Used by interactive chart
     drill-downs.
     """
+    # The server key is limited to demo articles served from the bundled
+    # dataset.
+    if payload.use_server_key:
+        if payload.article not in DEMOS:
+            raise HTTPException(
+                status_code=403,
+                detail=(
+                    "The server API key may only be used for built-in demo "
+                    f"articles. '{payload.article}' is not a demo — supply your "
+                    "own OpenAI key for this request."
+                ),
+            )
+        if payload.explanations is not None:
+            raise HTTPException(
+                status_code=403,
+                detail=(
+                    "The server API key may not be used with client-supplied "
+                    "explanations. Demo summaries are computed from the server's "
+                    "bundled dataset only."
+                ),
+            )
+
     # Normalize the label set. A combined request (by-section "All edit types"
     # cell) carries multiple labels; a single-label request carries just one.
     # `combined_labels` is the deduped, sorted set we match/summarize over;
@@ -1063,10 +1148,9 @@ async def summarize_edits(payload: SummarizePayload) -> Dict[str, Any]:
             + "\n\n".join(f"- {s}" for s in snippets_for_prompt)
         )
 
+    billed_server_key = payload.use_server_key and not (payload.api_key or "").strip()
     try:
         import openai
-        # Demo summaries fall back to the server secret; summaries on a
-        # user-generated page or uploaded CSV require the user's own key.
         client = openai.OpenAI(
             api_key=_resolve_api_key(
                 payload.api_key, allow_secret_fallback=payload.use_server_key
@@ -1074,6 +1158,7 @@ async def summarize_edits(payload: SummarizePayload) -> Dict[str, Any]:
         )
         completion = client.chat.completions.create(
             model="gpt-5.4",
+            store=True,
             messages=[
                 {
                     "role": "system",
@@ -1087,6 +1172,23 @@ async def summarize_edits(payload: SummarizePayload) -> Dict[str, Any]:
             ],
         )
         summary_text = completion.choices[0].message.content or ""
+        _log_openai_call(
+            endpoint="summarize",
+            model="gpt-5.4",
+            article=payload.article,
+            used_server_key=billed_server_key,
+            prompt_chars=len(user_prompt),
+            response_chars=len(summary_text),
+            usage=_usage_dict(completion),
+            extra={
+                "labels": combined_labels,
+                "period_key": payload.period_key,
+                "snippet_count": len(snippets_for_prompt),
+                "client_supplied_explanations": client_snippets is not None,
+            },
+        )
+    except HTTPException:
+        raise
     except Exception as e:
         raise HTTPException(status_code=502, detail=f"OpenAI request failed: {e}")
 
@@ -1125,6 +1227,42 @@ async def get_progress(article: str) -> Dict[str, Any]:
         "error": article_progress.get("error"),
     }
 
+
+@app.get("/usage-log")
+async def get_usage_log(token: str, limit: int = 500) -> Dict[str, Any]:
+    """Return recent usage-log entries. Requires a valid token."""
+    expected = (
+        os.environ.get("USAGE_LOG_TOKEN", "").strip()
+        or os.environ.get("OPENAI_API_KEY", "").strip()
+    )
+    if not expected or token.strip() != expected:
+        raise HTTPException(status_code=403, detail="Invalid or missing token.")
+
+    if not os.path.exists(USAGE_LOG_PATH):
+        return {"entries": [], "total_entries": 0, "server_key_calls": 0}
+
+    entries: List[Dict[str, Any]] = []
+    server_key_calls = 0
+    with _usage_log_lock:
+        with open(USAGE_LOG_PATH, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    rec = json.loads(line)
+                except Exception:
+                    continue
+                entries.append(rec)
+                if rec.get("used_server_key"):
+                    server_key_calls += 1
+
+    return {
+        "total_entries": len(entries),
+        "server_key_calls": server_key_calls,
+        "entries": entries[-max(0, limit):],
+    }
+
 # Serve the built React app at "/".
 # This must be registered AFTER all API routes so /prepare, /classify, /progress, /results,
 # /files still take precedence.