feat: add Hugging Face-compatible logging infrastructure (#9)

- New `beacon_logging.py` module with rotating JSON file handler and
a console handler using HF's `%(levelname)s:%(name)s:%(message)s`
format. Controlled via `BEACON_LOG_LEVEL` / `BEACON_LOG_DIR` env vars.
- `clinical_trials_guru.py`: logs patient intake profile JSON (INFO) and
full ClinicalTrials.gov request payload + per-page response metadata (DEBUG/INFO).
- `app.py`: logs patient intake profile JSON (INFO) after web-UI intake.

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: KevinIsInCoding <KevinIsInCoding@users.noreply.github.com>

app.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
+import dataclasses
 import datetime
 import json
 from typing import Generator
 
 import anthropic
 import gradio as gr
+from beacon_logging import get_logger
 from dotenv import load_dotenv
 
 from clinical_trials_guru import (
@@ -24,6 +26,8 @@ from translations import LANGUAGE_DIRECTIVE, LANGUAGES, UI
 
 load_dotenv()
 
+_logger = get_logger("app")
+
 
 def _intake_turn(
     user_text: str, messages: list, lang: str = "en"
@@ -68,6 +72,10 @@ def _intake_turn(
             include_observational=data.get("include_observational", False),
             lang=lang,
         )
+        _logger.info(
+            "Patient intake complete (web)",
+            extra={"data": {"intake_summary": dataclasses.asdict(profile)}},
+        )
         return text or UI[lang]["got_it"], messages, profile
 
     return text, messages, None

beacon_logging.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import json
+import logging
+import logging.handlers
+import os
+from datetime import datetime, timezone
+
+# Mirrors Hugging Face's LOG_LEVEL convention; use BEACON_ prefix to avoid collisions.
+_LOG_LEVEL = os.getenv("BEACON_LOG_LEVEL", "WARNING").upper()
+_LOG_DIR = os.getenv("BEACON_LOG_DIR", "logs")
+
+_configured = False
+
+
+class _JSONFormatter(logging.Formatter):
+    """Structured JSON lines for the rotating file handler."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        entry: dict = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+        if hasattr(record, "data"):
+            entry["data"] = record.data
+        return json.dumps(entry, default=str)
+
+
+def _setup() -> None:
+    global _configured
+    if _configured:
+        return
+    _configured = True
+
+    level = getattr(logging, _LOG_LEVEL, logging.WARNING)
+
+    root = logging.getLogger("beacon")
+    root.setLevel(logging.DEBUG)  # individual handlers apply their own level
+    root.propagate = False
+
+    # Console — same format string as HuggingFace transformers/datasets
+    console = logging.StreamHandler()
+    console.setLevel(level)
+    console.setFormatter(logging.Formatter("%(levelname)s:%(name)s:%(message)s"))
+    root.addHandler(console)
+
+    # Rotating JSON file — always DEBUG so nothing is silently dropped
+    os.makedirs(_LOG_DIR, exist_ok=True)
+    fh = logging.handlers.RotatingFileHandler(
+        os.path.join(_LOG_DIR, "beacon.log"),
+        maxBytes=10 * 1024 * 1024,
+        backupCount=5,
+        encoding="utf-8",
+    )
+    fh.setLevel(logging.DEBUG)
+    fh.setFormatter(_JSONFormatter())
+    root.addHandler(fh)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Return a ``beacon.<name>`` logger, configuring handlers on first call."""
+    _setup()
+    return logging.getLogger(f"beacon.{name}")

clinical_trials_guru.py

@@ -3,9 +3,10 @@ from __future__ import annotations
 import json
 import math
 import time
-from dataclasses import dataclass, field
+from dataclasses import asdict, dataclass, field
 from typing import Optional, TypedDict
 
+from beacon_logging import get_logger
 from translations import LANGUAGE_DIRECTIVE
 
 import anthropic
@@ -17,6 +18,8 @@ from rich.panel import Panel
 from rich.text import Text
 from langgraph.graph import StateGraph, START, END
 
+_logger = get_logger("clinical_trials_guru")
+
 CTGOV_BASE = "https://clinicaltrials.gov/api/v2/studies"
 INTAKE_MODEL = "claude-sonnet-4-6"
 RESEARCH_MODEL = "claude-opus-4-7"
@@ -344,6 +347,11 @@ def search_trials_api(
     else:
         params["aggFilters"] = "studyType:int"
 
+    _logger.info(
+        "ClinicalTrials.gov API request",
+        extra={"data": {"endpoint": CTGOV_BASE, "params": dict(params)}},
+    )
+
     all_studies: list[dict] = []
     while True:
         for attempt in range(3):
@@ -358,12 +366,21 @@ def search_trials_api(
                 wait = 2 ** attempt
                 console.print(f"[yellow]API warning:[/yellow] {exc} — retrying in {wait}s (attempt {attempt + 1}/3)…")
                 time.sleep(wait)
-        all_studies.extend(body.get("studies", []))
+        page_studies = body.get("studies", [])
+        all_studies.extend(page_studies)
         next_token = body.get("nextPageToken")
+        _logger.debug(
+            "ClinicalTrials.gov API page received",
+            extra={"data": {"page_count": len(page_studies), "has_next_page": bool(next_token)}},
+        )
         if not next_token:
             break
         params["pageToken"] = next_token
 
+    _logger.info(
+        "ClinicalTrials.gov API response complete",
+        extra={"data": {"total_studies": len(all_studies)}},
+    )
     return all_studies
 
 
@@ -477,7 +494,7 @@ def run_intake_agent(client: anthropic.Anthropic) -> PatientProfile:
             except Exception as exc:
                 console.print(f"[yellow]Warning:[/yellow] Geocoding failed ({exc}) — coordinates set to 0,0.")
                 lat, lon = 0.0, 0.0
-            return PatientProfile(
+            profile = PatientProfile(
                 disease=data["disease"],
                 age=data["age"],
                 onset_months=data["onset_months"],
@@ -492,6 +509,11 @@ def run_intake_agent(client: anthropic.Anthropic) -> PatientProfile:
                 include_eap=data.get("include_eap", False),
                 include_observational=data.get("include_observational", False),
             )
+            _logger.info(
+                "Patient intake complete (CLI)",
+                extra={"data": {"intake_summary": asdict(profile)}},
+            )
+            return profile
 
         messages.append({"role": "assistant", "content": response.content})
         user_input = input("\nYou: ").strip() or "(no response)"