Switch usage logger to HF Dataset repo via CommitScheduler

Replace /data/ CSV logging with CommitScheduler that writes JSONL
locally and auto-pushes to hetchyy/recitation-logs dataset every
5 minutes. Falls back to local-only logging without HF token.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.gitignore

@@ -12,6 +12,8 @@ CLAUDE.md
 
 data/phonemizer_mappings.json
 
+usage_logs/
+
 # Ignore all README files except the top-level/main README.*
 # This ignores any README, README.md, etc. in subfolders but not the one at project root
 !README*

utils/usage_logger.py

@@ -1,50 +1,56 @@
 """
-Usage logger for HF Spaces persistent storage.
+Usage logger that pushes to a HF Dataset repo.
 
-Logs technical errors and per-segment recitation data to CSV files
-in /data/ (HF Spaces persistent directory). Silently no-ops if
-/data/ doesn't exist (local dev).
+Writes JSONL files locally and uses CommitScheduler to auto-push
+to hetchyy/recitation-logs every 5 minutes in a background thread.
+Falls back to local-only logging if CommitScheduler can't initialize.
 """
 
-import csv
 import hashlib
-import os
+import json
 import threading
+from contextlib import contextmanager
 from datetime import datetime
+from pathlib import Path
 from typing import Optional, Tuple
+from uuid import uuid4
 
-DATA_DIR = "/data"
-ERROR_LOG = os.path.join(DATA_DIR, "error_log.csv")
-RECITATION_LOG = os.path.join(DATA_DIR, "recitation_log.csv")
+# Local folder for log files
+LOG_DIR = Path("usage_logs")
+LOG_DIR.mkdir(parents=True, exist_ok=True)
 
-_lock = threading.Lock()
+# UUID-suffixed files to avoid collision across Space restarts
+ERROR_LOG_PATH = LOG_DIR / f"error_log-{uuid4()}.jsonl"
+RECITATION_LOG_PATH = LOG_DIR / f"recitation_log-{uuid4()}.jsonl"
 
-ERROR_FIELDS = ["timestamp", "user_id", "verse_ref", "error_message"]
-RECITATION_FIELDS = [
-    "timestamp",
-    "user_id",
-    "verse_ref",
-    "segment_ref",
-    "canonical_text",
-    "canonical_phonemes",
-    "detected_phonemes",
-]
+# CommitScheduler pushes LOG_DIR → data/ in the dataset repo
+# Wrapped in try/except so local dev without HF token still works
+_scheduler = None
+try:
+    from huggingface_hub import CommitScheduler
 
+    _scheduler = CommitScheduler(
+        repo_id="hetchyy/recitation-logs",
+        repo_type="dataset",
+        folder_path=LOG_DIR,
+        path_in_repo="data",
+        private=True,
+    )
+except Exception:
+    pass
 
-def _append_row(filepath: str, fieldnames: list, row: dict) -> None:
-    """Append a row to a CSV file, creating it with headers if needed."""
-    if not os.path.isdir(DATA_DIR):
-        return
-    try:
-        with _lock:
-            file_exists = os.path.exists(filepath)
-            with open(filepath, "a", newline="", encoding="utf-8") as f:
-                writer = csv.DictWriter(f, fieldnames=fieldnames)
-                if not file_exists:
-                    writer.writeheader()
-                writer.writerow(row)
-    except Exception:
-        pass
+_fallback_lock = threading.Lock()
+
+
+@contextmanager
+def _get_lock():
+    """Use scheduler lock if available, otherwise fallback."""
+    if _scheduler is not None:
+        with _scheduler.lock:
+            yield
+    else:
+        with _fallback_lock:
+            yield
 
 
 def get_user_id(request) -> str:
@@ -75,12 +81,18 @@ def get_user_id(request) -> str:
 
 def log_error(user_id: str, verse_ref: str, error_message: str) -> None:
     """Log a technical error that occurred during analysis."""
-    _append_row(ERROR_LOG, ERROR_FIELDS, {
-        "timestamp": datetime.now().isoformat(),
-        "user_id": user_id,
-        "verse_ref": verse_ref or "",
-        "error_message": error_message or "",
-    })
+    try:
+        with _get_lock():
+            with ERROR_LOG_PATH.open("a") as f:
+                json.dump({
+                    "timestamp": datetime.now().isoformat(),
+                    "user_id": user_id,
+                    "verse_ref": verse_ref or "",
+                    "error_message": error_message or "",
+                }, f)
+                f.write("\n")
+    except Exception:
+        pass
 
 
 def log_recitation(
@@ -92,12 +104,18 @@ def log_recitation(
     detected_phonemes: Tuple[str, ...],
 ) -> None:
     """Log a single segment's recitation data after analysis."""
-    _append_row(RECITATION_LOG, RECITATION_FIELDS, {
-        "timestamp": datetime.now().isoformat(),
-        "user_id": user_id,
-        "verse_ref": verse_ref or "",
-        "segment_ref": segment_ref or "",
-        "canonical_text": canonical_text or "",
-        "canonical_phonemes": " ".join(canonical_phonemes) if canonical_phonemes else "",
-        "detected_phonemes": " ".join(detected_phonemes) if detected_phonemes else "",
-    })
+    try:
+        with _get_lock():
+            with RECITATION_LOG_PATH.open("a") as f:
+                json.dump({
+                    "timestamp": datetime.now().isoformat(),
+                    "user_id": user_id,
+                    "verse_ref": verse_ref or "",
+                    "segment_ref": segment_ref or "",
+                    "canonical_text": canonical_text or "",
+                    "canonical_phonemes": " ".join(canonical_phonemes) if canonical_phonemes else "",
+                    "detected_phonemes": " ".join(detected_phonemes) if detected_phonemes else "",
+                }, f)
+                f.write("\n")
+    except Exception:
+        pass