fix: use cached_slide_count instead of from_cache boolean for accurate telemetry

Replace boolean from_cache flag with integer cached_slide_count to properly
track cache hits at the slide level instead of batch level. This fixes
incorrect average duration calculation for mixed batches (some cached,
some fresh slides).

Previous behavior:
- Mixed batch (3 cached, 7 fresh) with 70s duration was excluded from
average if any slide was cached

New behavior:
- Only fully cached batches (all slides cached) are excluded from average
- Mixed batches are correctly included in average duration
- Reports now show total cached slides and cache hit rate percentage

Changes:
- UsageEvent: from_cache (bool) -> cached_slide_count (int)
- TelemetryTracker: Updated session metrics to check if all slides cached
- UI: Track cached_slides and fresh_slides counters separately
- Reports: Show 'Cached slides: X' and 'Cache hit rate: Y%'
- Tests: Updated all tests to use new cached_slide_count field

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

scripts/telemetry_report.py

@@ -205,10 +205,19 @@ def generate_text_report(telemetry_dir: Path, date: Optional[str] = None) -> str
         )
 
         # 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")]
+        total_cached_slides = sum(
+            c.get("cached_slide_count", 0) for c in completes if c.get("cached_slide_count")
+        )
+        fully_cached_analyses = [
+            c for c in completes
+            if c.get("cached_slide_count") and c.get("cached_slide_count") == c.get("slide_count", 0)
+        ]
+        fresh_analyses = [
+            c for c in completes
+            if not c.get("cached_slide_count") or c.get("cached_slide_count") < c.get("slide_count", 0)
+        ]
 
-        # Calculate average duration (excluding cached analyses)
+        # Calculate average duration (excluding fully cached analyses)
         durations = [
             c.get("duration_sec", 0) for c in fresh_analyses if c.get("duration_sec")
         ]
@@ -219,8 +228,10 @@ 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)}")
+        if total_cached_slides > 0:
+            lines.append(f"Cached slides: {total_cached_slides}")
+            cache_rate = (total_cached_slides / total_slides * 100) if total_slides > 0 else 0
+            lines.append(f"Cache hit rate: {cache_rate:.1f}%")
         lines.append(f"Unique sessions: {unique_sessions}")
         if avg_duration > 0:
             lines.append(f"Average analysis duration: {avg_duration:.1f}s")
@@ -438,7 +449,9 @@ def generate_html_report(telemetry_dir: Path, date: Optional[str] = None) -> str
         )
 
         # Cache hit tracking
-        cached_analyses = [c for c in completes if c.get("from_cache")]
+        total_cached_slides = sum(
+            c.get("cached_slide_count", 0) for c in completes if c.get("cached_slide_count")
+        )
 
         html.append("<h2>Usage Summary</h2>")
         html.append("<table>")
@@ -448,9 +461,13 @@ 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:
+        if total_cached_slides > 0:
+            html.append(
+                f"<tr><td>Cached slides</td><td>{total_cached_slides}</td></tr>"
+            )
+            cache_rate = (total_cached_slides / total_slides * 100) if total_slides > 0 else 0
             html.append(
-                f"<tr><td>Cached analyses</td><td>{len(cached_analyses)}</td></tr>"
+                f"<tr><td>Cache hit rate</td><td>{cache_rate:.1f}%</td></tr>"
             )
         html.append(f"<tr><td>Unique sessions</td><td>{unique_sessions}</td></tr>")
         html.append("</table>")

src/mosaic/telemetry/events.py

@@ -65,7 +65,9 @@ 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
+    cached_slide_count: Optional[int] = (
+        None  # Number of cached slides (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,7 +215,7 @@ class TelemetryTracker:
         gpu_type: Optional[str] = None,
         duration_sec: Optional[float] = None,
         success: Optional[bool] = None,
-        from_cache: Optional[bool] = None,
+        cached_slide_count: Optional[int] = None,
         is_logged_in: Optional[bool] = None,
         hf_username: Optional[str] = None,
     ) -> None:
@@ -232,7 +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)
+            cached_slide_count: Number of slides served from cache (for analysis_complete only)
             is_logged_in: True if HF user logged in
             hf_username: HF username (HF Spaces only)
         """
@@ -250,7 +250,7 @@ class TelemetryTracker:
             gpu_type=gpu_type,
             duration_sec=duration_sec,
             success=success,
-            from_cache=from_cache,
+            cached_slide_count=cached_slide_count,
             is_logged_in=is_logged_in,
             hf_username=hf_username,
         )
@@ -260,8 +260,13 @@ class TelemetryTracker:
         if event_type == "analysis_complete" and duration_sec is not None:
             with self._session_lock:
                 self._analysis_count += 1
-                # Don't count duration if result was served from cache
-                if not from_cache:
+                # Don't count duration if ALL slides were served from cache
+                is_fully_cached = (
+                    cached_slide_count is not None
+                    and slide_count > 0
+                    and cached_slide_count == slide_count
+                )
+                if not is_fully_cached:
                     self._analysis_time_sec += duration_sec
 
     # =========================================================================

src/mosaic/ui/app.py

@@ -289,7 +289,8 @@ def analyze_slides(
     all_slide_masks = []
     all_aeon_results = []
     all_paladin_results = []
-    from_cache = False
+    cached_slides = 0
+    fresh_slides = 0
 
     # Log analysis start event
     tracker.log_usage_event(
@@ -402,7 +403,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
+                        cached_slides += 1
                         logger.info(
                             f"Using cached results for {file_uuid}/{settings_hash}"
                         )
@@ -416,6 +417,7 @@ def analyze_slides(
 
             # If no cached results, run analysis
             if slide_mask is None or aeon_results is None or paladin_results is None:
+                fresh_slides += 1
                 # Lazy model loading: load on first cache miss
                 if model_cache is None:
                     if IS_T4_GPU:
@@ -514,7 +516,7 @@ def analyze_slides(
             slide_count=len(slides),
             duration_sec=duration_sec,
             success=True,
-            from_cache=from_cache if from_cache else None,
+            cached_slide_count=cached_slides if cached_slides > 0 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,24 +108,24 @@ 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."""
+    def test_cached_slide_count(self):
+        """Test cached_slide_count field on analysis_complete event."""
         event = UsageEvent(
             event_type="analysis_complete",
             analysis_id="test-123",
             session_hash=None,
-            slide_count=1,
+            slide_count=10,
             duration_sec=2.0,
             success=True,
-            from_cache=True,
+            cached_slide_count=3,
         )
 
-        assert event.from_cache is True
+        assert event.cached_slide_count == 3
         data = event.to_dict()
-        assert data["from_cache"] is True
+        assert data["cached_slide_count"] == 3
 
-    def test_from_cache_default_none(self):
-        """Test that from_cache defaults to None for backward compat."""
+    def test_cached_slide_count_default_none(self):
+        """Test that cached_slide_count defaults to None."""
         event = UsageEvent(
             event_type="analysis_complete",
             analysis_id="test-123",
@@ -135,9 +135,9 @@ class TestUsageEvent:
             success=True,
         )
 
-        assert event.from_cache is None
+        assert event.cached_slide_count is None
         data = event.to_dict()
-        assert data["from_cache"] is None
+        assert data["cached_slide_count"] is None
 
     def test_user_info_fields(self):
         """Test is_logged_in and hf_username fields in UsageEvent."""

tests/telemetry/test_report.py

@@ -288,11 +288,12 @@ class TestGenerateTextReport:
         assert "for 2026-01-20" in report
 
     def test_report_with_cached_analysis(self, tmp_path):
-        """Test report shows cached analysis count when present."""
+        """Test report shows cached slide count and cache hit rate."""
         daily_dir = tmp_path / "daily"
         daily_dir.mkdir()
 
         usage = [
+            # Batch 1: Fully cached (1/1 slides cached)
             {
                 "event_type": "analysis_start",
                 "slide_count": 1,
@@ -305,8 +306,9 @@ class TestGenerateTextReport:
                 "success": True,
                 "duration_sec": 2.0,
                 "slide_count": 1,
-                "from_cache": True,
+                "cached_slide_count": 1,  # Fully cached
             },
+            # Batch 2: Fresh (0/1 slides cached)
             {
                 "event_type": "analysis_start",
                 "slide_count": 1,
@@ -319,6 +321,7 @@ class TestGenerateTextReport:
                 "success": True,
                 "duration_sec": 120.0,
                 "slide_count": 1,
+                # No cached_slide_count = 0 cached
             },
         ]
 
@@ -328,8 +331,10 @@ class TestGenerateTextReport:
                 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),
+        # Should show 1 cached slide out of 2 total
+        assert "Cached slides: 1" in report
+        assert "Cache hit rate: 50.0%" in report
+        # Average duration should exclude fully cached batch (2s),
         # only include the fresh one (120s)
         assert "Average analysis duration: 120.0s" in report
 
@@ -360,7 +365,8 @@ class TestGenerateTextReport:
                 f.write(json.dumps(event) + "\n")
 
         report = generate_text_report(tmp_path)
-        assert "Cached analyses" not in report
+        assert "Cached slides" not in report
+        assert "Cache hit rate" not in report
 
     def test_report_with_resources(self, tmp_path):
         """Test report with resource data."""
@@ -423,7 +429,7 @@ class TestGenerateHtmlReport:
         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."""
+        """Test HTML report shows cached slide count and hit rate."""
         daily_dir = tmp_path / "daily"
         daily_dir.mkdir()
 
@@ -438,7 +444,7 @@ class TestGenerateHtmlReport:
                 "success": True,
                 "duration_sec": 2.0,
                 "slide_count": 1,
-                "from_cache": True,
+                "cached_slide_count": 1,
             },
         ]
 
@@ -448,7 +454,8 @@ class TestGenerateHtmlReport:
                 f.write(json.dumps(event) + "\n")
 
         report = generate_html_report(tmp_path)
-        assert "Cached analyses" in report
+        assert "Cached slides" in report
+        assert "Cache hit rate" in report
 
     def test_html_with_failures(self, tmp_path):
         """Test HTML report with failures."""

tests/telemetry/test_tracker.py

@@ -196,49 +196,49 @@ 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."""
+    def test_log_usage_event_with_cached_slides(self, tracker, temp_dir):
+        """Test that cached_slide_count is persisted in usage events."""
         tracker.log_usage_event(
             event_type="analysis_complete",
             analysis_id="test-cache",
-            slide_count=1,
-            duration_sec=2.0,
+            slide_count=10,
+            duration_sec=50.0,
             success=True,
-            from_cache=True,
+            cached_slide_count=3,
         )
 
         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
+        assert event["cached_slide_count"] == 3
 
-    def test_cached_analysis_excludes_duration_from_metrics(self, tracker):
-        """Test that cached analyses don't count toward analysis_time_sec."""
+    def test_fully_cached_analysis_excludes_duration_from_metrics(self, tracker):
+        """Test that fully 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,
+            slide_count=5,
             duration_sec=2.0,
             success=True,
-            from_cache=True,
+            cached_slide_count=5,  # All slides cached
         )
 
         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."""
+    def test_mixed_cache_analysis_includes_duration_in_metrics(self, tracker):
+        """Test that mixed analyses (some cached) count toward analysis_time_sec."""
         tracker.log_app_start()
         tracker.log_usage_event(
             event_type="analysis_complete",
-            analysis_id="test-fresh",
-            slide_count=1,
+            analysis_id="test-mixed",
+            slide_count=10,
             duration_sec=60.0,
             success=True,
-            from_cache=False,
+            cached_slide_count=3,  # Only 3/10 cached
         )
 
         metrics = tracker._get_session_metrics()