Add opt-in usage telemetry to a private HF dataset

Logs upload, translate, edit, download, navigate, resume, and prompt
events to billingsmoore/stui-usage, gated by a per-session opt-out
checkbox in Settings and disclosed on the landing page. Also stops
tracking CLAUDE.md and any .claude/ directory — those are local
development aids now, not shared repo content.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

.gitignore

@@ -4,3 +4,5 @@ __pycache__/
 .venv/
 venv/
 .pytest_cache/
+CLAUDE.md
+.claude/

CLAUDE.md

@@ -1,121 +0,0 @@
-# CLAUDE.md
-
-This file guides Claude Code (or any future session) working in this
-repository. This project is a **standalone, simplified fork** of
-`TranslationUI` (from the `Garchen` monorepo) — it is intentionally
-detached: no submodule relationship, no shared git history, no HuggingFace
-dataset dependencies. Everything needed to understand and run it lives here.
-
-## What this app is
-
-A minimal Gradio app for translating Tibetan Buddhist texts into English.
-Upload a `.txt`, `.docx`, or `.pdf` file → it's split into segments →
-translate each segment (or all at once) → edit inline → download the result.
-
-Compared to the original `TranslationUI` this app deliberately drops:
-- Video/audio playback and Google Drive import (no media, ever)
-- Subtitle formats (SRT/VTT) and timestamp-based segments — plain text in, plain text out
-- Multi-language target selection (English only)
-- Per-language prompt files and a separate post-edit pass (one prompt, no post-edit)
-- HuggingFace-dataset-backed project storage and versioned prompt history
-  (no `HF_TOKEN`, no `datasets`/`huggingface_hub` write dependency — state
-  lives only in the browser session; prompt edits are a local file)
-
-## Architecture
-
-```
-app.py                    Gradio UI (Blocks), wires handlers to components
-handlers.py                Event handlers + in-memory session state (gr.State)
-styles.py                  Minimal CSS (no floating video player JS anymore)
-translation_prompt.txt     The one editable translation prompt (Garchen Rinpoche voice/glossary)
-engine/
-  chunking.py               Plain-text -> segment list (paragraph, then shad/whitespace splitting)
-  formats.py                Read .txt/.docx/.pdf; write .txt/.docx/.json
-  prompt.py                 Read/write/reset translation_prompt.txt (local file only)
-  translate.py              Backend dispatcher (OpenRouter vs local CPU model) + batching/progress
-  openrouter_backend.py      OpenRouter API calls, retries, server-side model fallback, batch prompt building
-  local_backend.py           CPU fallback: AutoModelForSeq2SeqLM "billingsmoore/mlotsawa-ground-base"
-```
-
-## Translation backend selection
-
-`engine/translate.py::_resolve_key()` decides per-call:
-- An OpenRouter API key was typed into the UI, **or** `OPENROUTER_API_KEY` is set (env var / `.env`)
-  → use OpenRouter, with the prompt in `translation_prompt.txt` (editable in Settings) and the model
-  picked in the dropdown. The dropdown is populated by `engine/openrouter_backend.py::list_model_choices()`,
-  which live-fetches OpenRouter's `/models` catalog and puts `CURATED_MODELS` (a small hand-picked,
-  known-good-for-translation set) at the top, followed by the rest of the text-output catalog
-  alphabetically — falls back to just `CURATED_MODELS` if the fetch fails (offline, OpenRouter down).
-  `CURATED_MODELS` also doubles as the `models` fallback array OpenRouter is given per request, so it
-  retries server-side against another good model if the chosen one errors out.
-- No key anywhere → use the local CPU model `billingsmoore/mlotsawa-ground-base` via
-  `AutoModelForSeq2SeqLM.generate()` directly (see `engine/local_backend.py`). This is a plain finetuned
-  T5 seq2seq model — it does **not** read `translation_prompt.txt` at all. First call downloads the
-  model (~a few hundred MB) and is slow on CPU; it stays cached in memory for the life of the process.
-  This model was introduced in ["Optimizing T5 for Lightweight Tibetan-English Translation"](https://doi.org/10.21203/rs.3.rs-7409829/v1)
-  (Moore & Lauren, 2025); its training/eval code is at
-  [optimizing-t5-tibetan-english-mt](https://github.com/billingsmoore/optimizing-t5-tibetan-english-mt).
-
-**Why not `pipeline("translation", ...)`:** that's the model card's documented usage, but the
-`"translation"` pipeline task was removed in `transformers>=5` (raises `Unknown task translation`).
-Instead `local_backend.py` reads the model's own `model.config.task_specific_params["translation_bo_to_en"]`
-(prefix `"translate Tibetan to English: "`, `num_beams=4`, `max_length=300`) and calls `generate()`
-directly — verified to reproduce the model card's example output exactly, and works on any transformers
-version that ships `AutoModelForSeq2SeqLM`/`AutoTokenizer`. Don't "fix" this back to `pipeline(...)`
-without first checking what transformers version is actually installed.
-
-## Segmentation
-
-`engine/chunking.py::split_into_segments()`: splits on blank-line paragraph breaks, then (for any
-paragraph longer than `max_chars`, default 400) on Tibetan sentence-ending shad marks (`།` `༎`), then
-falls back to plain whitespace word-chunking for any single "sentence" still too long. There is no
-timestamp concept anywhere in this app — segments are just `{"source": str, "target": str}` dicts.
-
-## Running it
-
-```bash
-pip install -r requirements.txt
-python app.py
-```
-Opens on `http://localhost:7860`. Put `OPENROUTER_API_KEY=...` in a `.env` file to default to
-OpenRouter without typing a key into the UI each time.
-
-## Testing
-
-```bash
-pip install -r requirements-dev.txt
-pytest
-```
-
-`tests/` covers chunking, file I/O (txt/docx/pdf load+export, JSON resume),
-prompt storage, the OpenRouter backend (model curation/fetch-fallback, request
-retry/fallback logic, batch prompt building/parsing — all with `requests`
-mocked, no real network calls or API key needed), the backend dispatcher, the
-local CPU backend (with `torch`/`transformers` stubbed via `sys.modules` so
-the suite doesn't require installing those heavy deps), the Gradio event
-handlers, and a smoke test that the Blocks graph in `app.py` builds without
-error. `samples/sample_tibetan.{txt,docx,pdf}` are real Tibetan-script fixture
-files (a well-known refuge/bodhicitta verse, the four immeasurables, and a
-dedication verse) used by the format-loading tests and useful for manually
-exercising the upload flow.
-
-A `pre-push` git hook (`.githooks/pre-push`) runs the full suite and blocks
-the push if anything fails. It's already installed into `.git/hooks/pre-push`
-in this working copy; on a fresh clone, install it with either
-`git config core.hooksPath .githooks` or `cp .githooks/pre-push .git/hooks/`.
-
-## Conventions to keep
-
-- No comments explaining *what* code does — only *why*, when non-obvious (mirrors the parent repo's style).
-- Don't reintroduce HuggingFace dataset persistence, subtitle timing, or multi-language prompt files —
-  those were removed on purpose to keep this app simple. If a future ask needs them, treat it as a
-  deliberate scope expansion, not a bug to fix.
-- This repo has no relationship to `Garchen`'s git history — it's fine to `git init` here and commit
-  independently.
-
-## Remotes
-
-Two remotes, same dual-remote convention as `Garchen`: `origin` = GitHub
-(https://github.com/billingsmoore/SimpleTranslationUI, source of truth) and `space` = the deployed
-Hugging Face Space (https://huggingface.co/spaces/billingsmoore/SimpleTranslationUI). Push to `origin`
-for normal commits; push to `space` (`git push space main:main`) to actually redeploy the Space.

app.py

@@ -9,6 +9,7 @@ from engine import DEFAULT_MODEL, list_model_choices
 from styles import CSS
 from handlers import (
     MAX_SLOTS,
+    _handle_cancel_translate,
     _handle_download_click,
     _handle_get_files,
     _handle_next,
@@ -20,6 +21,7 @@ from handlers import (
     _read_prompt,
     _reset_prompt,
     _save_prompt,
+    _set_usage_tracking,
     _translate_all,
     _translate_one,
 )
@@ -43,7 +45,9 @@ def build_app() -> gr.Blocks:
             "the translation prompt below) and generally lower translation quality. For higher-quality, instruction-"
             "following translation, add an **OpenRouter API key** in Settings and pick a model "
             "from the dropdown — this calls OpenRouter's API (usage is billed to your OpenRouter "
-            "account) and uses the editable translation prompt."
+            "account) and uses the editable translation prompt.\n\n"
+            "Usage of this space may be monitored for research purposes. You can opt out of this "
+            "in Settings."
         )
 
         with gr.Row():
@@ -59,6 +63,10 @@ def build_app() -> gr.Blocks:
             )
 
         with gr.Accordion("Settings", open=False):
+            usage_tracking_checkbox = gr.Checkbox(
+                label="Allow usage tracking for research purposes",
+                value=True,
+            )
             with gr.Row():
                 openrouter_api_key = gr.Textbox(
                     label="OpenRouter API Key (optional)",
@@ -142,7 +150,7 @@ def build_app() -> gr.Blocks:
             inputs=[app_state, openrouter_api_key, openrouter_model, *slot_sources, *slot_targets],
             outputs=translate_all_outputs,
         )
-        cancel_btn.click(fn=None, cancels=[translate_event])
+        cancel_btn.click(_handle_cancel_translate, inputs=[app_state], outputs=[app_state], cancels=[translate_event])
 
         save_btn.click(_handle_save, inputs=edit_inputs, outputs=[app_state, status_output])
         download_btn.click(
@@ -171,8 +179,12 @@ def build_app() -> gr.Blocks:
                 outputs=[app_state, slot_targets[i]],
             )
 
-        save_prompt_btn.click(_save_prompt, inputs=[prompt_box], outputs=[prompt_status])
-        reset_prompt_btn.click(_reset_prompt, inputs=[], outputs=[prompt_box, prompt_status])
+        save_prompt_btn.click(_save_prompt, inputs=[app_state, prompt_box], outputs=[app_state, prompt_status])
+        reset_prompt_btn.click(_reset_prompt, inputs=[app_state], outputs=[app_state, prompt_box, prompt_status])
+
+        usage_tracking_checkbox.change(
+            _set_usage_tracking, inputs=[app_state, usage_tracking_checkbox], outputs=[app_state],
+        )
 
     return demo
 

engine/__init__.py

@@ -12,6 +12,7 @@ from .formats import (
     parse_json,
 )
 from .prompt import read_prompt, save_prompt, reset_prompt, PROMPT_PATH
+from .usage_store import log_event
 from .translate import (
     CURATED_MODELS,
     DEFAULT_MODEL,

engine/usage_store.py

@@ -0,0 +1,63 @@
+"""Usage telemetry, written as one event per file to the billingsmoore/stui-usage
+HuggingFace dataset (private). Tracks uploads, translations, and edits so we can
+study how the app is actually used; users can opt out per-session in Settings.
+
+Each event is an independent commit (no shared index to read-modify-write),
+so concurrent sessions never race each other. Fails open (returns False /
+no-op and logs a warning) if HF_TOKEN isn't set, the dataset repo doesn't
+exist yet, or the network call fails — usage logging must never break the
+translation workflow.
+"""
+
+import json
+import os
+import uuid
+from datetime import datetime, timezone
+
+DATASET_REPO_ID = "billingsmoore/stui-usage"
+
+
+def _hf_token() -> str | None:
+    return os.environ.get("HF_TOKEN") or None
+
+
+def _ensure_dataset(token: str) -> None:
+    from huggingface_hub import HfApi
+    HfApi(token=token).create_repo(
+        repo_id=DATASET_REPO_ID, repo_type="dataset", private=True, exist_ok=True,
+    )
+
+
+def log_event(event_type: str, session_id: str, payload: dict) -> bool:
+    """Write one usage event. Returns True on success, False if skipped/failed."""
+    token = _hf_token()
+    if not token or not session_id:
+        return False
+    try:
+        from huggingface_hub import CommitOperationAdd, HfApi
+        _ensure_dataset(token)
+
+        now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+        record = {
+            "event": event_type,
+            "session_id": session_id,
+            "timestamp": now,
+            **payload,
+        }
+        path_in_repo = f"events/{session_id}/{now}_{event_type}_{uuid.uuid4().hex[:8]}.json"
+
+        HfApi(token=token).create_commit(
+            repo_id=DATASET_REPO_ID,
+            repo_type="dataset",
+            operations=[
+                CommitOperationAdd(
+                    path_in_repo=path_in_repo,
+                    path_or_fileobj=json.dumps(record, ensure_ascii=False, indent=2).encode("utf-8"),
+                ),
+            ],
+            commit_message=f"{event_type} event ({session_id})",
+        )
+        return True
+    except Exception as e:
+        print(f"[WARN] Could not log usage event {event_type!r}: {e}")
+        return False

handlers.py

@@ -4,6 +4,7 @@ import math
 import os
 import tempfile
 import threading
+import uuid
 import zipfile
 from pathlib import Path
 
@@ -14,6 +15,7 @@ from engine import (
     export_to_json,
     export_to_txt,
     load_source_file,
+    log_event,
     parse_json,
     read_prompt,
     reset_prompt,
@@ -29,7 +31,25 @@ MAX_SLOTS = 25
 # ── State ─────────────────────────────────────────────────────────────────────
 
 def _make_state() -> dict:
-    return {"page": 0, "segments": [], "has_translation": False, "label": "output"}
+    return {
+        "page": 0,
+        "segments": [],
+        "has_translation": False,
+        "label": "output",
+        "session_id": uuid.uuid4().hex,
+        "usage_tracking_enabled": True,
+    }
+
+
+def _log(state: dict, event_type: str, payload: dict) -> None:
+    if not state.get("usage_tracking_enabled", True):
+        return
+    log_event(event_type, state.get("session_id", ""), payload)
+
+
+def _set_usage_tracking(state: dict, enabled: bool):
+    state["usage_tracking_enabled"] = enabled
+    return state
 
 
 def _save_page_edits(state: dict, sources: list, targets: list) -> dict:
@@ -115,6 +135,13 @@ def _load_source(source_file, state):
     state["label"] = label
     state["has_translation"] = False
 
+    _log(state, "upload", {
+        "filename": Path(path).name,
+        "file_type": Path(path).suffix.lstrip("."),
+        "segment_count": len(segments),
+        "segments": [{"source": seg.get("source", "")} for seg in segments],
+    })
+
     return (*_load_page(state), gr.update(visible=True))
 
 
@@ -140,6 +167,16 @@ def _load_resume_json(resume_file, state):
 
     state["has_translation"] = any(seg.get("target") for seg in state["segments"])
     state["page"] = 0
+
+    _log(state, "resume", {
+        "filename": Path(path).name,
+        "segment_count": len(state["segments"]),
+        "segments": [
+            {"source": seg.get("source", ""), "target": seg.get("target", "")}
+            for seg in state["segments"]
+        ],
+    })
+
     return _load_page(state)
 
 
@@ -189,6 +226,13 @@ def _handle_save(state, *slot_values):
     sources = list(slot_values[:MAX_SLOTS])
     targets = list(slot_values[MAX_SLOTS:])
     state = _save_page_edits(state, sources, targets)
+
+    n = min(MAX_SLOTS, len(state["segments"]) - state["page"] * MAX_SLOTS)
+    _log(state, "edit", {
+        "segment_count": max(n, 0),
+        "segments": [{"source": sources[i], "target": targets[i]} for i in range(max(n, 0))],
+    })
+
     return state, gr.update(value="Saved.", visible=True)
 
 
@@ -223,6 +267,15 @@ def _handle_get_files(state, selected_labels):
         for path in chosen:
             zf.write(path, arcname=os.path.basename(path))
 
+    _log(state, "download", {
+        "formats": list(selected_labels or []),
+        "segment_count": len(segments),
+        "segments": [
+            {"source": seg.get("source", ""), "target": seg.get("target", "")}
+            for seg in segments
+        ],
+    })
+
     return gr.update(value=zip_path, visible=True), gr.update(visible=False), gr.update(visible=False)
 
 
@@ -240,6 +293,13 @@ def _translate_one(state: dict, slot_idx: int, source: str, api_key: str, model:
         segments[actual_idx]["target"] = text
         state["segments"] = segments
 
+    backend = f"openrouter:{model}" if using_openrouter(api_key) else "local_cpu"
+    _log(state, "translate", {
+        "backend": backend,
+        "segment_count": 1,
+        "segments": [{"source": source, "target": text}],
+    })
+
     return state, gr.update(value=text)
 
 
@@ -289,23 +349,36 @@ def _translate_all(state, api_key, model, *slot_values):
     if errors:
         status += f" {len(errors)} error(s)."
 
+    _log(state, "translate", {
+        "backend": backend,
+        "segment_count": count,
+        "segments": [{"source": seg.get("source", ""), "target": seg.get("target", "")} for seg in segments],
+    })
+
     yield (*_load_page(state), gr.update(value=status, visible=True))
 
 
+def _handle_cancel_translate(state: dict):
+    _log(state, "translate_cancel", {})
+    return state
+
+
 # ── Prompt management ─────────────────────────────────────────────────────────
 
 def _read_prompt() -> str:
     return read_prompt()
 
 
-def _save_prompt(text: str):
+def _save_prompt(state: dict, text: str):
     save_prompt(text)
-    return gr.update(value="Prompt saved.")
+    _log(state, "prompt_save", {"prompt": text})
+    return state, gr.update(value="Prompt saved.")
 
 
-def _reset_prompt():
+def _reset_prompt(state: dict):
     text = reset_prompt()
-    return gr.update(value=text), gr.update(value="Prompt reset to default.")
+    _log(state, "prompt_reset", {})
+    return state, gr.update(value=text), gr.update(value="Prompt reset to default.")
 
 
 # ── Navigation ��───────────────────────────────────────────────────────────────
@@ -316,6 +389,7 @@ def _handle_prev(state, *slot_values):
     state = _save_page_edits(state, sources, targets)
     if state["page"] > 0:
         state["page"] -= 1
+    _log(state, "navigate", {"direction": "prev", "page": state["page"]})
     return _load_page(state)
 
 
@@ -327,4 +401,5 @@ def _handle_next(state, *slot_values):
     total_pages = math.ceil(total / MAX_SLOTS) if total else 1
     if state["page"] < total_pages - 1:
         state["page"] += 1
+    _log(state, "navigate", {"direction": "next", "page": state["page"]})
     return _load_page(state)

requirements.txt

@@ -2,6 +2,7 @@ gradio>=6.9.0
 spaces
 requests
 python-dotenv
+huggingface_hub
 transformers
 torch
 sentencepiece

tests/test_handlers.py

@@ -10,6 +10,13 @@ import handlers as h
 SAMPLES_DIR = Path(__file__).parent.parent / "samples"
 
 
+@pytest.fixture(autouse=True)
+def no_hf_token(monkeypatch):
+    """Usage logging fails open without HF_TOKEN, so tests that don't
+    explicitly mock log_event still can't make a real network call."""
+    monkeypatch.delenv("HF_TOKEN", raising=False)
+
+
 def _segments(*sources):
     return [{"source": s, "target": ""} for s in sources]
 
@@ -18,7 +25,24 @@ def _segments(*sources):
 
 def test_make_state_defaults():
     state = h._make_state()
-    assert state == {"page": 0, "segments": [], "has_translation": False, "label": "output"}
+    assert state["page"] == 0
+    assert state["segments"] == []
+    assert state["has_translation"] is False
+    assert state["label"] == "output"
+    assert state["usage_tracking_enabled"] is True
+    assert state["session_id"]
+
+
+def test_make_state_generates_unique_session_ids():
+    assert h._make_state()["session_id"] != h._make_state()["session_id"]
+
+
+def test_set_usage_tracking_toggles_flag():
+    state = h._make_state()
+    state = h._set_usage_tracking(state, False)
+    assert state["usage_tracking_enabled"] is False
+    state = h._set_usage_tracking(state, True)
+    assert state["usage_tracking_enabled"] is True
 
 
 def test_save_page_edits_writes_current_page_slots():
@@ -157,6 +181,29 @@ def test_load_source_txt_populates_segments():
     assert result[-1]["visible"] is True
 
 
+def test_load_source_logs_upload_event():
+    state = h._make_state()
+    path = str(SAMPLES_DIR / "sample_tibetan.txt")
+    with patch.object(h, "log_event") as mock_log:
+        h._load_source(path, state)
+    mock_log.assert_called_once()
+    event_type, session_id, payload = mock_log.call_args[0]
+    assert event_type == "upload"
+    assert session_id == state["session_id"]
+    assert payload["filename"] == "sample_tibetan.txt"
+    assert payload["file_type"] == "txt"
+    assert payload["segment_count"] == len(state["segments"])
+
+
+def test_load_source_skips_logging_when_tracking_disabled():
+    state = h._make_state()
+    state["usage_tracking_enabled"] = False
+    path = str(SAMPLES_DIR / "sample_tibetan.txt")
+    with patch.object(h, "log_event") as mock_log:
+        h._load_source(path, state)
+    mock_log.assert_not_called()
+
+
 def test_load_source_bad_file_hides_editor_and_does_not_raise(tmp_path):
     bad_path = tmp_path / "bad.rtf"
     bad_path.write_text("nope", encoding="utf-8")
@@ -259,24 +306,61 @@ def test_handle_save_persists_edits_and_shows_status():
     state = h._make_state()
     state["segments"] = _segments("a")
     slot_values = ["edited"] + [""] * (h.MAX_SLOTS - 1) + ["translated"] + [""] * (h.MAX_SLOTS - 1)
-    new_state, status = h._handle_save(state, *slot_values)
+    with patch.object(h, "log_event"):
+        new_state, status = h._handle_save(state, *slot_values)
     assert new_state["segments"][0] == {"source": "edited", "target": "translated"}
     assert status["value"] == "Saved."
 
 
+def test_handle_save_logs_edit_event():
+    state = h._make_state()
+    state["segments"] = _segments("a")
+    slot_values = ["edited"] + [""] * (h.MAX_SLOTS - 1) + ["translated"] + [""] * (h.MAX_SLOTS - 1)
+    with patch.object(h, "log_event") as mock_log:
+        h._handle_save(state, *slot_values)
+    event_type, session_id, payload = mock_log.call_args[0]
+    assert event_type == "edit"
+    assert session_id == state["session_id"]
+    assert payload["segments"] == [{"source": "edited", "target": "translated"}]
+
+
+def test_handle_save_skips_logging_when_tracking_disabled():
+    state = h._make_state()
+    state["usage_tracking_enabled"] = False
+    state["segments"] = _segments("a")
+    slot_values = [""] * h.MAX_SLOTS * 2
+    with patch.object(h, "log_event") as mock_log:
+        h._handle_save(state, *slot_values)
+    mock_log.assert_not_called()
+
+
 # ── translation handlers ──────────────────────────────────────────────────
 
 def test_translate_one_updates_state_and_returns_text():
     state = h._make_state()
     state["segments"] = _segments("source text")
     state["page"] = 0
-    with patch.object(h, "_engine_translate_one", return_value="translated!") as mock_translate:
+    with patch.object(h, "_engine_translate_one", return_value="translated!") as mock_translate, \
+         patch.object(h, "log_event"):
         new_state, update = h._translate_one(state, 0, "source text", "api-key", "model-x")
     assert update["value"] == "translated!"
     assert new_state["segments"][0]["target"] == "translated!"
     mock_translate.assert_called_once_with("source text", "api-key", "model-x")
 
 
+def test_translate_one_logs_translate_event():
+    state = h._make_state()
+    state["segments"] = _segments("source text")
+    with patch.object(h, "_engine_translate_one", return_value="translated!"), \
+         patch.object(h, "using_openrouter", return_value=True), \
+         patch.object(h, "log_event") as mock_log:
+        h._translate_one(state, 0, "source text", "api-key", "model-x")
+    event_type, session_id, payload = mock_log.call_args[0]
+    assert event_type == "translate"
+    assert payload["backend"] == "openrouter:model-x"
+    assert payload["segments"] == [{"source": "source text", "target": "translated!"}]
+
+
 def test_translate_one_records_error_in_target():
     state = h._make_state()
     state["segments"] = _segments("source text")
@@ -311,7 +395,8 @@ def test_translate_all_reports_completion_status():
         return segments, []
 
     with patch.object(h, "translate_segments", side_effect=fake_translate_segments), \
-         patch.object(h, "using_openrouter", return_value=True):
+         patch.object(h, "using_openrouter", return_value=True), \
+         patch.object(h, "log_event") as mock_log:
         results = list(h._translate_all(state, "api-key", "model-x", *slot_values))
 
     final = results[-1]
@@ -320,6 +405,11 @@ def test_translate_all_reports_completion_status():
     final_state = final[0]
     assert [s["target"] for s in final_state["segments"]] == ["A", "B"]
 
+    event_type, session_id, payload = mock_log.call_args[0]
+    assert event_type == "translate"
+    assert payload["segment_count"] == 2
+    assert payload["segments"] == [{"source": "a", "target": "A"}, {"source": "b", "target": "B"}]
+
 
 def test_translate_all_reports_errors_in_status():
     state = h._make_state()
@@ -371,10 +461,108 @@ def test_read_save_reset_prompt_roundtrip(monkeypatch, tmp_path):
 
     assert h._read_prompt() == "default"
 
-    status = h._save_prompt("edited")
+    state = h._make_state()
+    _, status = h._save_prompt(state, "edited")
     assert status["value"] == "Prompt saved."
     assert h._read_prompt() == "edited"
 
-    box_update, status_update = h._reset_prompt()
+    _, box_update, status_update = h._reset_prompt(state)
     assert box_update["value"] == "default"
     assert status_update["value"] == "Prompt reset to default."
+
+
+def test_save_prompt_logs_prompt_save_event():
+    state = h._make_state()
+    with patch.object(h, "log_event") as mock_log:
+        h._save_prompt(state, "new prompt text")
+    event_type, session_id, payload = mock_log.call_args[0]
+    assert event_type == "prompt_save"
+    assert session_id == state["session_id"]
+    assert payload["prompt"] == "new prompt text"
+
+
+def test_reset_prompt_logs_prompt_reset_event():
+    state = h._make_state()
+    with patch.object(h, "log_event") as mock_log:
+        h._reset_prompt(state)
+    event_type, session_id, payload = mock_log.call_args[0]
+    assert event_type == "prompt_reset"
+    assert session_id == state["session_id"]
+
+
+# ── other interaction logging ───────────────────────────────────────────────
+
+def test_load_resume_json_logs_resume_event():
+    state = h._make_state()
+    state["segments"] = _segments("a", "b", "c")
+    resume_content = json.dumps([
+        {"source": "a", "target": "A"},
+        {"source": "b", "target": ""},
+        {"source": "c", "target": "C"},
+    ])
+    import tempfile
+    with tempfile.NamedTemporaryFile(suffix=".json", mode="w", delete=False) as f:
+        f.write(resume_content)
+        path = f.name
+
+    with patch.object(h, "log_event") as mock_log:
+        h._load_resume_json(path, state)
+
+    event_type, session_id, payload = mock_log.call_args[0]
+    assert event_type == "resume"
+    assert payload["filename"] == Path(path).name
+    assert payload["segment_count"] == 3
+    assert payload["segments"] == [
+        {"source": "a", "target": "A"},
+        {"source": "b", "target": ""},
+        {"source": "c", "target": "C"},
+    ]
+
+
+def test_handle_get_files_logs_download_event():
+    state = h._make_state()
+    state["segments"] = [{"source": "src", "target": "tgt"}]
+    state["label"] = "lbl"
+    with patch.object(h, "log_event") as mock_log:
+        h._handle_get_files(state, ["Translation (TXT)"])
+    event_type, session_id, payload = mock_log.call_args[0]
+    assert event_type == "download"
+    assert payload["formats"] == ["Translation (TXT)"]
+    assert payload["segments"] == [{"source": "src", "target": "tgt"}]
+
+
+def test_handle_get_files_no_selection_does_not_log():
+    state = h._make_state()
+    state["segments"] = [{"source": "src", "target": "tgt"}]
+    with patch.object(h, "log_event") as mock_log:
+        h._handle_get_files(state, [])
+    mock_log.assert_not_called()
+
+
+def test_handle_prev_and_next_log_navigate_events():
+    state = h._make_state()
+    state["segments"] = _segments(*[f"s{i}" for i in range(h.MAX_SLOTS + 3)])
+    state["page"] = 0
+    slot_values = [""] * h.MAX_SLOTS * 2
+
+    with patch.object(h, "log_event") as mock_log:
+        result = h._handle_next(state, *slot_values)
+    new_state = result[0]
+    event_type, session_id, payload = mock_log.call_args[0]
+    assert event_type == "navigate"
+    assert payload == {"direction": "next", "page": 1}
+
+    with patch.object(h, "log_event") as mock_log:
+        h._handle_prev(new_state, *slot_values)
+    event_type, session_id, payload = mock_log.call_args[0]
+    assert event_type == "navigate"
+    assert payload == {"direction": "prev", "page": 0}
+
+
+def test_handle_cancel_translate_logs_event():
+    state = h._make_state()
+    with patch.object(h, "log_event") as mock_log:
+        h._handle_cancel_translate(state)
+    event_type, session_id, payload = mock_log.call_args[0]
+    assert event_type == "translate_cancel"
+    assert session_id == state["session_id"]

tests/test_usage_store.py

@@ -0,0 +1,68 @@
+"""Unit tests for engine.usage_store — usage telemetry written to the
+billingsmoore/stui-usage HuggingFace dataset (private). All huggingface_hub
+calls are mocked; no test in this file talks to the network.
+"""
+
+import json
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from engine import usage_store
+
+
+@pytest.fixture(autouse=True)
+def no_token(monkeypatch):
+    monkeypatch.delenv("HF_TOKEN", raising=False)
+
+
+@pytest.fixture
+def with_token(monkeypatch):
+    monkeypatch.setenv("HF_TOKEN", "fake-token")
+
+
+class TestNoToken:
+    def test_log_event_returns_false_without_network_call(self):
+        with patch("huggingface_hub.HfApi") as mock_api:
+            assert usage_store.log_event("upload", "session-1", {"foo": "bar"}) is False
+            mock_api.assert_not_called()
+
+
+class TestLogEvent:
+    def test_no_session_id_returns_false_without_network_call(self, with_token):
+        with patch("huggingface_hub.HfApi") as mock_api:
+            assert usage_store.log_event("upload", "", {"foo": "bar"}) is False
+            mock_api.assert_not_called()
+
+    def test_writes_single_commit_with_expected_fields(self, with_token):
+        mock_api_instance = MagicMock()
+        with patch("huggingface_hub.HfApi", return_value=mock_api_instance):
+            ok = usage_store.log_event("translate", "session-1", {"backend": "local_cpu", "segment_count": 2})
+
+        assert ok is True
+        mock_api_instance.create_repo.assert_called_once_with(
+            repo_id=usage_store.DATASET_REPO_ID, repo_type="dataset", private=True, exist_ok=True,
+        )
+        mock_api_instance.create_commit.assert_called_once()
+        _, kwargs = mock_api_instance.create_commit.call_args
+        assert kwargs["repo_id"] == usage_store.DATASET_REPO_ID
+        assert kwargs["repo_type"] == "dataset"
+
+        operations = kwargs["operations"]
+        assert len(operations) == 1
+        op = operations[0]
+        assert op.path_in_repo.startswith("events/session-1/")
+        assert op.path_in_repo.endswith(".json")
+
+        payload = json.loads(op.path_or_fileobj.decode("utf-8"))
+        assert payload["event"] == "translate"
+        assert payload["session_id"] == "session-1"
+        assert payload["backend"] == "local_cpu"
+        assert payload["segment_count"] == 2
+        assert "timestamp" in payload
+
+    def test_network_error_fails_open(self, with_token):
+        mock_api_instance = MagicMock()
+        mock_api_instance.create_commit.side_effect = Exception("network error")
+        with patch("huggingface_hub.HfApi", return_value=mock_api_instance):
+            assert usage_store.log_event("edit", "session-1", {}) is False