feat: add cache-hit tracking to telemetry

Add from_cache boolean to UsageEvent so telemetry distinguishes cache
hits from fresh GPU analyses. Cached analyses are excluded from session
analysis_time_sec and from the report's average duration to avoid
skewing usage metrics.

- Add from_cache to UsageEvent dataclass
- Add from_cache parameter to TelemetryTracker.log_usage_event()
- Track and report cache hits in analyze_slides()
- Update telemetry report (text + HTML) with cached analysis count
- Add tests for all new functionality

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

scripts/telemetry_report.py

@@ -204,9 +204,13 @@ def generate_text_report(telemetry_dir: Path, date: Optional[str] = None) -> str
             set(u.get("session_hash") for u in usage if u.get("session_hash"))
         )
 
-        # Calculate average duration
+        # Cache hit tracking
+        cached_analyses = [c for c in completes if c.get("from_cache")]
+        fresh_analyses = [c for c in completes if not c.get("from_cache")]
+
+        # Calculate average duration (excluding cached analyses)
         durations = [
-            c.get("duration_sec", 0) for c in completes if c.get("duration_sec")
+            c.get("duration_sec", 0) for c in fresh_analyses if c.get("duration_sec")
         ]
         avg_duration = sum(durations) / len(durations) if durations else 0
 
@@ -215,6 +219,8 @@ def generate_text_report(telemetry_dir: Path, date: Optional[str] = None) -> str
         lines.append(f"Analyses completed: {len(completes)}")
         lines.append(f"Successful analyses: {len(successful)}")
         lines.append(f"Total slides processed: {total_slides}")
+        if cached_analyses:
+            lines.append(f"Cached analyses: {len(cached_analyses)}")
         lines.append(f"Unique sessions: {unique_sessions}")
         if avg_duration > 0:
             lines.append(f"Average analysis duration: {avg_duration:.1f}s")
@@ -431,6 +437,9 @@ def generate_html_report(telemetry_dir: Path, date: Optional[str] = None) -> str
             set(u.get("session_hash") for u in usage if u.get("session_hash"))
         )
 
+        # Cache hit tracking
+        cached_analyses = [c for c in completes if c.get("from_cache")]
+
         html.append("<h2>Usage Summary</h2>")
         html.append("<table>")
         html.append(f"<tr><td>Analyses started</td><td>{len(starts)}</td></tr>")
@@ -439,6 +448,10 @@ def generate_html_report(telemetry_dir: Path, date: Optional[str] = None) -> str
             f"<tr><td>Successful analyses</td><td class='success'>{len(successful)}</td></tr>"
         )
         html.append(f"<tr><td>Total slides</td><td>{total_slides}</td></tr>")
+        if cached_analyses:
+            html.append(
+                f"<tr><td>Cached analyses</td><td>{len(cached_analyses)}</td></tr>"
+            )
         html.append(f"<tr><td>Unique sessions</td><td>{unique_sessions}</td></tr>")
         html.append("</table>")
 

src/mosaic/tcga.py

@@ -696,9 +696,7 @@ def save_metadata_cache(
         )
     except Exception as e:
         # Truly unexpected errors
-        logger.exception(
-            f"Unexpected error saving metadata cache for {file_uuid}: {e}"
-        )
+        logger.exception(f"Unexpected error saving metadata cache for {file_uuid}: {e}")
 
 
 def load_metadata_cache(

src/mosaic/telemetry/events.py

@@ -65,6 +65,7 @@ class UsageEvent:
     gpu_type: Optional[str] = None  # From hardware.GPU_TYPE
     duration_sec: Optional[float] = None  # On completion only
     success: Optional[bool] = None  # On completion only
+    from_cache: Optional[bool] = None  # On completion only
     is_logged_in: Optional[bool] = None  # True if HF user logged in
     hf_username: Optional[str] = None  # Raw HF username (HF Spaces only)
     event_id: str = field(default_factory=_generate_event_id)

src/mosaic/telemetry/tracker.py

@@ -215,6 +215,7 @@ class TelemetryTracker:
         gpu_type: Optional[str] = None,
         duration_sec: Optional[float] = None,
         success: Optional[bool] = None,
+        from_cache: Optional[bool] = None,
         is_logged_in: Optional[bool] = None,
         hf_username: Optional[str] = None,
     ) -> None:
@@ -231,6 +232,7 @@ class TelemetryTracker:
             gpu_type: GPU type string
             duration_sec: Analysis duration (for analysis_complete only)
             success: Whether analysis succeeded (for analysis_complete only)
+            from_cache: True if result was served from cache (for analysis_complete only)
             is_logged_in: True if HF user logged in
             hf_username: HF username (HF Spaces only)
         """
@@ -248,6 +250,7 @@ class TelemetryTracker:
             gpu_type=gpu_type,
             duration_sec=duration_sec,
             success=success,
+            from_cache=from_cache,
             is_logged_in=is_logged_in,
             hf_username=hf_username,
         )
@@ -257,7 +260,9 @@ class TelemetryTracker:
         if event_type == "analysis_complete" and duration_sec is not None:
             with self._session_lock:
                 self._analysis_count += 1
-                self._analysis_time_sec += duration_sec
+                # Don't count duration if result was served from cache
+                if not from_cache:
+                    self._analysis_time_sec += duration_sec
 
     # =========================================================================
     # Resource Events

src/mosaic/ui/app.py

@@ -289,6 +289,7 @@ def analyze_slides(
     all_slide_masks = []
     all_aeon_results = []
     all_paladin_results = []
+    from_cache = False
 
     # Log analysis start event
     tracker.log_usage_event(
@@ -401,6 +402,7 @@ def analyze_slides(
                     cached = load_analysis_results(file_uuid, settings_hash)
                     if cached is not None:
                         slide_mask, aeon_results, paladin_results = cached
+                        from_cache = True
                         logger.info(
                             f"Using cached results for {file_uuid}/{settings_hash}"
                         )
@@ -429,9 +431,7 @@ def analyze_slides(
                         logger.info(
                             f"Batch mode: Loading models once for {len(slides)} slides"
                         )
-                        progress(
-                            0.0, desc="Loading models for batch processing"
-                        )
+                        progress(0.0, desc="Loading models for batch processing")
                         model_cache = load_all_models(
                             use_gpu=True, aggressive_memory_mgmt=None
                         )
@@ -514,6 +514,7 @@ def analyze_slides(
             slide_count=len(slides),
             duration_sec=duration_sec,
             success=True,
+            from_cache=from_cache if from_cache else None,
             gpu_type=GPU_TYPE,
             is_logged_in=user_info.is_logged_in,
             hf_username=user_info.username,

tests/telemetry/test_events.py

@@ -108,6 +108,37 @@ class TestUsageEvent:
         assert data["slide_count"] == 3
         assert data["session_hash"] is None
 
+    def test_from_cache_true(self):
+        """Test from_cache field on analysis_complete event."""
+        event = UsageEvent(
+            event_type="analysis_complete",
+            analysis_id="test-123",
+            session_hash=None,
+            slide_count=1,
+            duration_sec=2.0,
+            success=True,
+            from_cache=True,
+        )
+
+        assert event.from_cache is True
+        data = event.to_dict()
+        assert data["from_cache"] is True
+
+    def test_from_cache_default_none(self):
+        """Test that from_cache defaults to None for backward compat."""
+        event = UsageEvent(
+            event_type="analysis_complete",
+            analysis_id="test-123",
+            session_hash=None,
+            slide_count=1,
+            duration_sec=60.0,
+            success=True,
+        )
+
+        assert event.from_cache is None
+        data = event.to_dict()
+        assert data["from_cache"] is None
+
     def test_user_info_fields(self):
         """Test is_logged_in and hf_username fields in UsageEvent."""
         event = UsageEvent(

tests/telemetry/test_report.py

@@ -287,6 +287,81 @@ class TestGenerateTextReport:
         report = generate_text_report(tmp_path, date="2026-01-20")
         assert "for 2026-01-20" in report
 
+    def test_report_with_cached_analysis(self, tmp_path):
+        """Test report shows cached analysis count when present."""
+        daily_dir = tmp_path / "daily"
+        daily_dir.mkdir()
+
+        usage = [
+            {
+                "event_type": "analysis_start",
+                "slide_count": 1,
+                "session_hash": "s1",
+                "site_type": "Primary",
+                "seg_config": "TCGA",
+            },
+            {
+                "event_type": "analysis_complete",
+                "success": True,
+                "duration_sec": 2.0,
+                "slide_count": 1,
+                "from_cache": True,
+            },
+            {
+                "event_type": "analysis_start",
+                "slide_count": 1,
+                "session_hash": "s2",
+                "site_type": "Primary",
+                "seg_config": "TCGA",
+            },
+            {
+                "event_type": "analysis_complete",
+                "success": True,
+                "duration_sec": 120.0,
+                "slide_count": 1,
+            },
+        ]
+
+        file_path = daily_dir / "usage_2026-01-20.jsonl"
+        with open(file_path, "w", encoding="utf-8") as f:
+            for event in usage:
+                f.write(json.dumps(event) + "\n")
+
+        report = generate_text_report(tmp_path)
+        assert "Cached analyses: 1" in report
+        # Average duration should exclude cached analysis (2s),
+        # only include the fresh one (120s)
+        assert "Average analysis duration: 120.0s" in report
+
+    def test_report_without_cached_analysis(self, tmp_path):
+        """Test report omits cache stats when no cache hits."""
+        daily_dir = tmp_path / "daily"
+        daily_dir.mkdir()
+
+        usage = [
+            {
+                "event_type": "analysis_start",
+                "slide_count": 1,
+                "session_hash": "s1",
+                "site_type": "Primary",
+                "seg_config": "Biopsy",
+            },
+            {
+                "event_type": "analysis_complete",
+                "success": True,
+                "duration_sec": 60.0,
+                "slide_count": 1,
+            },
+        ]
+
+        file_path = daily_dir / "usage_2026-01-20.jsonl"
+        with open(file_path, "w", encoding="utf-8") as f:
+            for event in usage:
+                f.write(json.dumps(event) + "\n")
+
+        report = generate_text_report(tmp_path)
+        assert "Cached analyses" not in report
+
     def test_report_with_resources(self, tmp_path):
         """Test report with resource data."""
         daily_dir = tmp_path / "daily"
@@ -347,6 +422,34 @@ class TestGenerateHtmlReport:
         assert "Analyses started" in report
         assert "<td>1</td>" in report  # 1 analysis started
 
+    def test_html_with_cached_analysis(self, tmp_path):
+        """Test HTML report shows cached analysis count."""
+        daily_dir = tmp_path / "daily"
+        daily_dir.mkdir()
+
+        usage = [
+            {
+                "event_type": "analysis_start",
+                "slide_count": 1,
+                "session_hash": "s1",
+            },
+            {
+                "event_type": "analysis_complete",
+                "success": True,
+                "duration_sec": 2.0,
+                "slide_count": 1,
+                "from_cache": True,
+            },
+        ]
+
+        file_path = daily_dir / "usage_2026-01-20.jsonl"
+        with open(file_path, "w", encoding="utf-8") as f:
+            for event in usage:
+                f.write(json.dumps(event) + "\n")
+
+        report = generate_html_report(tmp_path)
+        assert "Cached analyses" in report
+
     def test_html_with_failures(self, tmp_path):
         """Test HTML report with failures."""
         daily_dir = tmp_path / "daily"

tests/telemetry/test_tracker.py

@@ -196,6 +196,55 @@ class TestUsageEvents:
         assert metrics["analysis_count"] == 2
         assert metrics["analysis_time_sec"] == 105.0
 
+    def test_log_usage_event_with_from_cache(self, tracker, temp_dir):
+        """Test that from_cache is persisted in usage events."""
+        tracker.log_usage_event(
+            event_type="analysis_complete",
+            analysis_id="test-cache",
+            slide_count=1,
+            duration_sec=2.0,
+            success=True,
+            from_cache=True,
+        )
+
+        usage_files = list((temp_dir / "daily").glob("usage_*.jsonl"))
+        with open(usage_files[0]) as f:
+            event = json.loads(f.read().strip())
+
+        assert event["from_cache"] is True
+
+    def test_cached_analysis_excludes_duration_from_metrics(self, tracker):
+        """Test that cached analyses don't count toward analysis_time_sec."""
+        tracker.log_app_start()
+        tracker.log_usage_event(
+            event_type="analysis_complete",
+            analysis_id="test-cache",
+            slide_count=1,
+            duration_sec=2.0,
+            success=True,
+            from_cache=True,
+        )
+
+        metrics = tracker._get_session_metrics()
+        assert metrics["analysis_count"] == 1
+        assert metrics["analysis_time_sec"] == 0.0
+
+    def test_fresh_analysis_includes_duration_in_metrics(self, tracker):
+        """Test that fresh analyses count toward analysis_time_sec."""
+        tracker.log_app_start()
+        tracker.log_usage_event(
+            event_type="analysis_complete",
+            analysis_id="test-fresh",
+            slide_count=1,
+            duration_sec=60.0,
+            success=True,
+            from_cache=False,
+        )
+
+        metrics = tracker._get_session_metrics()
+        assert metrics["analysis_count"] == 1
+        assert metrics["analysis_time_sec"] == 60.0
+
 
 class TestResourceEvents:
     """Tests for resource event logging."""

tests/test_tcga.py

@@ -766,7 +766,11 @@ class TestMetadataCache:
             mode = kwargs.get("mode")
             if mode is None and len(args) > 1:
                 mode = args[1]
-            if "metadata.json" in str(args[0]) and mode is not None and "w" in str(mode):
+            if (
+                "metadata.json" in str(args[0])
+                and mode is not None
+                and "w" in str(mode)
+            ):
                 raise PermissionError("No permission")
             return original_open(*args, **kwargs)