feat: show samples needed per class before a determination

Expose min_samples and samples_needed in the confidence-stats summary,
make the recommendation text state how many more samples are required,
and surface a 'N to go / ready' marker plus a determination progress
bar per class in the insights panel.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: chvvkumar

alpaca/confidence_stats.py

@@ -177,6 +177,8 @@ def summary(self) -> dict:
                     "max": e["max_conf"] if e["max_conf"] is not None else 0.0,
                     "buckets": list(e["buckets"]),
                     "bucket_pct": bucket_pct,
+                    "min_samples": MIN_SAMPLES,
+                    "samples_needed": max(0, MIN_SAMPLES - count),
                     "recommendation": rec,
                 })
                 if rec["severity"] in ("warn", "info"):
@@ -194,11 +196,16 @@ def summary(self) -> dict:
     def _recommend(count: int, mean: float, buckets: list) -> dict:
         """First matching condition wins."""
         if count == 0:
-            return {"severity": "none", "text": "Not yet observed."}
+            return {
+                "severity": "none",
+                "text": f"Not yet observed; {MIN_SAMPLES} samples needed before a determination can be made.",
+            }
         if count < MIN_SAMPLES:
+            remaining = MIN_SAMPLES - count
+            sample_word = "sample" if remaining == 1 else "samples"
             return {
                 "severity": "info",
-                "text": "Too few samples to judge; needs more observations.",
+                "text": f"Too few samples to judge; {remaining} more {sample_word} needed before a determination can be made.",
             }
         if mean < LOW_MEAN_PCT:
             return {

docs/EXTERNAL_API.md

@@ -304,6 +304,8 @@ Confidence values are percentages (0-100). The histogram divides confidence into
       "max": 71.2,
       "buckets": [0, 0, 1, 4, 12, 9, 6, 3, 2, 0],
       "bucket_pct": [0.0, 0.0, 2.7, 10.8, 32.4, 24.3, 16.2, 8.1, 5.4, 0.0],
+      "min_samples": 50,
+      "samples_needed": 13,
       "recommendation": {
         "severity": "warn",
         "text": "Low average confidence; collect and label more images for this class."
@@ -330,6 +332,8 @@ Confidence values are percentages (0-100). The histogram divides confidence into
 | `classes[].max` | number | Highest recorded confidence percentage |
 | `classes[].buckets` | array | 10 raw counts, one per 10-point confidence band |
 | `classes[].bucket_pct` | array | The same distribution as percentages of `count` |
+| `classes[].min_samples` | number | Sample count required before a determination is made (currently 50) |
+| `classes[].samples_needed` | number | Remaining samples to reach `min_samples` (0 once reached) |
 | `classes[].recommendation.severity` | string | `none`, `info`, `warn`, or `ok` |
 | `classes[].recommendation.text` | string | Suggested action for this class |
 | `advice` | array | Text recommendations for classes flagged `warn` or `info` |

templates/setup.html

@@ -1771,6 +1771,8 @@ <h3 style="color: rgb(248, 113, 113); font-size: 14px; font-weight: 600; margin-
                                 var color = ciSeverityColor(sev);
                                 var hasData = count > 0;
                                 var meanWidth = hasData ? Math.max(0, Math.min(100, mean)) : 0;
+                                var minSamples = (cls && typeof cls.min_samples === 'number') ? cls.min_samples : 0;
+                                var needed = (cls && typeof cls.samples_needed === 'number') ? cls.samples_needed : 0;
 
                                 var wrap = document.createElement('div');
                                 wrap.style.cssText = 'padding: 10px 12px; background: rgba(30, 41, 59, 0.4); border-radius: 6px; margin-bottom: 8px; border: 1px solid rgba(71, 85, 105, 0.5);';
@@ -1814,6 +1816,19 @@ <h3 style="color: rgb(248, 113, 113); font-size: 14px; font-weight: 600; margin-
                                 countEl.textContent = '(' + count + ')';
                                 summary.appendChild(countEl);
 
+                                var detEl = document.createElement('div');
+                                detEl.style.cssText = 'min-width: 64px; text-align: right; font-size: 10px; font-weight: 600; font-family: \'JetBrains Mono\', monospace;';
+                                if (needed > 0) {
+                                    detEl.textContent = needed + ' to go';
+                                    detEl.style.color = 'rgb(251, 191, 36)';
+                                    detEl.title = 'Needs ' + needed + ' more sample(s) to reach ' + minSamples + ' before a determination can be made';
+                                } else {
+                                    detEl.textContent = '✓ ready';
+                                    detEl.style.color = 'rgb(52, 211, 153)';
+                                    detEl.title = 'Reached ' + minSamples + ' samples; a determination can be made';
+                                }
+                                summary.appendChild(detEl);
+
                                 wrap.appendChild(summary);
 
                                 if (rec.text) {
@@ -1827,6 +1842,23 @@ <h3 style="color: rgb(248, 113, 113); font-size: 14px; font-weight: 600; margin-
                                 detail.id = 'ci-detail-' + idx;
                                 detail.style.cssText = 'display: none; margin-top: 12px; margin-left: 16px;';
 
+                                // Determination progress toward the minimum sample count.
+                                var detWrap = document.createElement('div');
+                                detWrap.style.cssText = 'margin-bottom: 12px;';
+                                var detLbl = document.createElement('div');
+                                detLbl.style.cssText = 'font-size: 11px; color: rgb(148, 163, 184); margin-bottom: 4px; font-family: \'JetBrains Mono\', monospace;';
+                                detLbl.textContent = 'Samples toward determination: ' + Math.min(count, minSamples) + ' / ' + minSamples +
+                                    (needed > 0 ? '  (' + needed + ' more needed)' : '  (reached)');
+                                var detTrack = document.createElement('div');
+                                detTrack.style.cssText = 'height: 12px; background: rgba(30, 41, 59, 0.6); border-radius: 2px; overflow: hidden; border: 1px solid rgba(71, 85, 105, 0.5);';
+                                var detFill = document.createElement('div');
+                                var detPct = minSamples > 0 ? Math.max(0, Math.min(100, (count / minSamples) * 100)) : 100;
+                                detFill.style.cssText = 'height: 100%; width: ' + detPct + '%; background: ' + (needed > 0 ? 'rgb(251, 191, 36)' : 'rgb(52, 211, 153)') + '; opacity: 0.75;';
+                                detTrack.appendChild(detFill);
+                                detWrap.appendChild(detLbl);
+                                detWrap.appendChild(detTrack);
+                                detail.appendChild(detWrap);
+
                                 if (hasData) {
                                     var stats = document.createElement('div');
                                     stats.style.cssText = 'font-size: 11px; color: rgb(148, 163, 184); margin-bottom: 10px; font-family: \'JetBrains Mono\', monospace;';

tests/test_confidence_stats.py

@@ -121,6 +121,26 @@ def test_recommendation_too_few_samples(stats):
     assert rain["recommendation"]["severity"] == "info"
 
 
+def test_samples_needed_counts_down_to_zero(stats):
+    # Unobserved class needs the full MIN_SAMPLES.
+    clear = next(c for c in stats.summary()["classes"] if c["name"] == "Clear")
+    assert clear["min_samples"] == MIN_SAMPLES
+    assert clear["samples_needed"] == MIN_SAMPLES
+
+    # After some samples, the remaining count decreases.
+    for _ in range(10):
+        stats.record("Rain", 50.0)
+    rain = next(c for c in stats.summary()["classes"] if c["name"] == "Rain")
+    assert rain["samples_needed"] == MIN_SAMPLES - 10
+    assert str(MIN_SAMPLES - 10) in rain["recommendation"]["text"]
+
+    # Once the threshold is reached, no more samples are needed.
+    for _ in range(MIN_SAMPLES):
+        stats.record("Snow", 95.0)
+    snow = next(c for c in stats.summary()["classes"] if c["name"] == "Snow")
+    assert snow["samples_needed"] == 0
+
+
 def test_recommendation_healthy(stats):
     for _ in range(MIN_SAMPLES + 10):
         stats.record("Clear", 95.0)