added hf dataset to collect metrics

.env.example

@@ -35,3 +35,19 @@ KIOSK_LLM_SYSTEM_PROMPT="You are a conversational receptionist for the Northwest
 
 # Style guidelines (required - ensures speech-friendly responses)
 KIOSK_LLM_STYLE="Warm, welcoming tone for a spoken receptionist. Prefer short, plain sentences suitable for text-to-speech and avoid stage directions or annotations like *in a warm voice*."
+
+# =============================================================================
+# Hugging Face Dataset Persistence (optional - for metrics/history across restarts)
+# =============================================================================
+
+# HF dataset repo for chat history (e.g. monish563/kiosk-api-metrics)
+# KIOSK_HF_DATASET_REPO=monish563/kiosk-api-metrics
+
+# HF token with write access to the dataset (use HF Secrets on Spaces)
+# KIOSK_HF_TOKEN=your-hf-token
+
+# Path within the dataset repo (default: chat_history)
+# KIOSK_HF_DATASET_PATH=chat_history
+
+# Sync interval in minutes (default: 10)
+# KIOSK_HF_SYNC_INTERVAL_MINUTES=10

README.md

@@ -61,8 +61,10 @@ Deploy this API as a public endpoint so your manager (or STT/TTS systems) can se
 | `KIOSK_LLM_STYLE` | No | Style guidelines for TTS-friendly responses |
 | `OPENAI_API_KEY` | No | If using `provider: "openai"` |
 | `GEMINI_API_KEY` | No | If using `provider: "gemini"` |
+| `KIOSK_HF_DATASET_REPO` | No | HF dataset for persistence (e.g. `monish563/kiosk-api-metrics`) |
+| `KIOSK_HF_TOKEN` | No* | HF token with write access (required if dataset repo is set) |
 
-*At least one LLM API key (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `GEMINI_API_KEY`) is required.
+*At least one LLM API key is required. `KIOSK_HF_TOKEN` is required if `KIOSK_HF_DATASET_REPO` is set.
 
 ### 3. Endpoint URL for your manager
 

backend/main.py

@@ -7,6 +7,12 @@ import os
 import threading
 import time
 import warnings
+
+try:
+    from huggingface_hub import CommitScheduler, hf_hub_download
+except ImportError:
+    CommitScheduler = None  # type: ignore
+    hf_hub_download = None  # type: ignore
 from functools import lru_cache
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
@@ -71,6 +77,7 @@ app.add_middleware(
 
 _orchestrator_lock = threading.Lock()
 logger = logging.getLogger(__name__)
+_hf_scheduler = None
 
 
 class QueryPayload(BaseModel):
@@ -129,10 +136,99 @@ def _load_env_once() -> None:
 
 
 def _get_env_value(name: Optional[str]) -> str:
-    """Read environment variable."""
+    """
+    Read environment variables with an HF Spaces secret fallback.
+    HF Secrets expose values as HF_<NAME>, so check both keys.
+    """
     if not name:
         return ""
-    return os.getenv(name, "").strip()
+    direct = os.getenv(name, "").strip()
+    if direct:
+        return direct
+    return os.getenv(f"HF_{name}", "").strip()
+
+
+def _maybe_download_existing_history() -> None:
+    """Download existing chat history from HF dataset on startup."""
+    repo_id = os.getenv("KIOSK_HF_DATASET_REPO", "").strip()
+    if not repo_id or hf_hub_download is None:
+        return
+
+    _load_env_once()
+    token = _get_env_value("KIOSK_HF_TOKEN") or os.getenv("HF_TOKEN", "").strip()
+    path_in_repo = os.getenv("KIOSK_HF_DATASET_PATH", "chat_history").strip()
+    filename = f"{path_in_repo}/{HISTORY_FILE.name}" if path_in_repo else HISTORY_FILE.name
+
+    try:
+        import shutil
+
+        downloaded = hf_hub_download(
+            repo_id=repo_id,
+            repo_type="dataset",
+            filename=filename,
+            token=token or None,
+        )
+        HISTORY_FILE.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy(downloaded, HISTORY_FILE)
+        logger.info(
+            "Downloaded chat history from HF dataset: repo=%s file=%s",
+            repo_id,
+            filename,
+        )
+    except Exception as exc:
+        logger.info("No existing chat history to download (starting fresh): %s", exc)
+
+
+def _maybe_start_hf_sync() -> None:
+    """Start optional HF dataset syncing for chat history."""
+    global _hf_scheduler
+
+    if _hf_scheduler is not None:
+        return
+
+    repo_id = os.getenv("KIOSK_HF_DATASET_REPO", "").strip()
+    if not repo_id or CommitScheduler is None:
+        return
+
+    _load_env_once()
+    token = _get_env_value("KIOSK_HF_TOKEN") or os.getenv("HF_TOKEN", "").strip()
+    path_in_repo = os.getenv("KIOSK_HF_DATASET_PATH", "chat_history").strip()
+    interval_minutes = float(os.getenv("KIOSK_HF_SYNC_INTERVAL_MINUTES", "10"))
+
+    try:
+        _hf_scheduler = CommitScheduler(
+            repo_id=repo_id,
+            repo_type="dataset",
+            folder_path=str(DATA_DIR),
+            path_in_repo=path_in_repo,
+            token=token or None,
+            allow_patterns=[HISTORY_FILE.name],
+            every=interval_minutes,
+        )
+        logger.info(
+            "Started HF CommitScheduler for chat history: repo=%s path=%s interval=%sm",
+            repo_id,
+            path_in_repo or ".",
+            interval_minutes,
+        )
+    except Exception as exc:
+        warnings.warn(f"Unable to start HF sync: {exc}")
+
+
+def _run_startup_tasks_in_background() -> None:
+    """Run HF download and sync in a background thread so the server starts immediately."""
+    def _run() -> None:
+        try:
+            _maybe_download_existing_history()
+            _maybe_start_hf_sync()
+        except Exception as exc:
+            logger.warning("Background startup tasks failed: %s", exc)
+
+    t = threading.Thread(target=_run, daemon=True)
+    t.start()
+
+
+_run_startup_tasks_in_background()
 
 
 def _is_placeholder(value: Optional[str]) -> bool:

requirements.txt

@@ -11,3 +11,6 @@ requests>=2.31.0
 
 # Utilities
 python-dotenv>=1.0.0
+
+# HF dataset persistence (optional)
+huggingface_hub>=0.23.0