feat(ml): DB-backed tagger_store_floor (default 0.70), the ingest confidence floor

Promotes the prediction store-floor from the TAGGER_STORE_FLOOR env (default
0.05) to a DB-backed, Settings-UI-tunable ml_settings column (default 0.70).
Storing every tag down to 0.05 from a ~10k-tag tagger is what grew
image_record's TOAST to ~100 GB; the suggestion path already filters at 0.70
and the centroid/learned path covers lower-confidence preferred tags, so the
sub-0.70 tail is redundant. Foundation for plan-task #764 (backfill + reclaim
land next; this only changes the write gate for NEW imports).

- ml_settings.tagger_store_floor (migration 0044, default 0.70)
- tagger.Tagger.infer(store_floor=...); ml task passes settings.tagger_store_floor
- ML admin GET/PATCH expose it; PATCH rejects a category suggestion threshold
  below the floor (nothing below the floor is stored, so the gap surfaces
  nothing) — server backstop for the UI slider clamp
- Settings → ML: store-floor slider + caption; category sliders min-bound to it

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

backend/app/api/ml_admin.py

@@ -13,6 +13,7 @@ _EDITABLE = (
     "suggestion_threshold_general",
     "centroid_similarity_threshold",
     "min_reference_images",
+    "tagger_store_floor",
 )
 
 
@@ -30,6 +31,7 @@ async def get_settings():
             "suggestion_threshold_general": s.suggestion_threshold_general,
             "centroid_similarity_threshold": s.centroid_similarity_threshold,
             "min_reference_images": s.min_reference_images,
+            "tagger_store_floor": s.tagger_store_floor,
             "tagger_model_version": s.tagger_model_version,
             "embedder_model_version": s.embedder_model_version,
         }
@@ -47,13 +49,45 @@ async def patch_settings():
         s = (
             await session.execute(select(MLSettings).where(MLSettings.id == 1))
         ).scalar_one()
+
+        # Merge the patch over current values, then validate the result as a
+        # whole — the store-floor invariant couples three fields, so they
+        # can't be checked one at a time.
+        proposed = {f: getattr(s, f) for f in _EDITABLE}
         for field in _EDITABLE:
             if field in body:
-                setattr(s, field, body[field])
+                proposed[field] = body[field]
+
+        err = _validate(proposed)
+        if err is not None:
+            return jsonify({"error": err}), 400
+
+        for field in _EDITABLE:
+            setattr(s, field, proposed[field])
         await session.commit()
     return await get_settings()
 
 
+def _validate(p: dict) -> str | None:
+    """Returns an error string if the proposed settings are invalid, else None.
+
+    Invariant (plan-task #764): the per-category suggestion thresholds can't
+    drop below tagger_store_floor — nothing below the floor is stored, so a
+    lower threshold would silently surface nothing in that gap. The UI clamps
+    the sliders to the floor; this is the server-side backstop.
+    """
+    floor = p["tagger_store_floor"]
+    if not (0.0 <= floor <= 1.0):
+        return "tagger_store_floor must be between 0 and 1"
+    for cat in ("character", "general"):
+        if p[f"suggestion_threshold_{cat}"] < floor:
+            return (
+                f"suggestion_threshold_{cat} cannot be below tagger_store_floor "
+                f"({floor}) — predictions below the floor are not stored"
+            )
+    return None
+
+
 @ml_admin_bp.route("/backfill", methods=["POST"])
 async def trigger_backfill():
     from ..tasks.ml import backfill

backend/app/models/ml_settings.py

@@ -28,6 +28,15 @@ class MLSettings(Base):
     centroid_similarity_threshold: Mapped[float] = mapped_column(
         Float, nullable=False, default=0.55
     )
+    # Ingest floor: tagger predictions below this confidence are not stored
+    # (tagger.Tagger.infer). Default 0.70 — the suggestion path already
+    # filters at 0.70 and the centroid/learned path covers low-confidence
+    # preferred tags, so the sub-0.70 tail is redundant weight (it had
+    # bloated image_record's TOAST to ~100 GB; plan-task #764). Operator-
+    # tunable via Settings → ML; must stay ≤ the suggestion thresholds.
+    tagger_store_floor: Mapped[float] = mapped_column(
+        Float, nullable=False, default=0.70
+    )
     min_reference_images: Mapped[int] = mapped_column(
         Integer, nullable=False, default=5
     )

backend/app/services/ml/tagger.py

@@ -33,8 +33,13 @@ _MODEL_DIR = Path(os.environ.get("ML_MODEL_DIR", "/models")) / "camie"
 _MODEL_FILE = f"{MODEL_NAME}.onnx"
 _METADATA_FILE = f"{MODEL_NAME}-metadata.json"
 
-# Below this confidence, predictions aren't stored (keeps the JSON compact).
-STORE_FLOOR = float(os.environ.get("TAGGER_STORE_FLOOR", "0.05"))
+# Ingest floor below which predictions aren't stored (keeps the JSON compact).
+# DEFAULT/fallback only — the live value is DB-backed
+# (ml_settings.tagger_store_floor) and passed into infer() per call by the ml
+# task. 0.70: the suggestion path already filters there and the centroid path
+# covers lower-confidence preferred tags, so the sub-0.70 tail is redundant
+# (it had bloated image_record's TOAST to ~100 GB; plan-task #764).
+DEFAULT_STORE_FLOOR = 0.70
 
 # The categories FC-2b surfaces in the UI. Others (meta/rating/year) are
 # still stored but the suggestion service filters them out.
@@ -145,10 +150,13 @@ class Tagger:
         arr = arr.transpose(2, 0, 1)                        # HWC -> CHW
         return arr[np.newaxis, :, :, :]                     # NCHW
 
-    def infer(self, image_path: Path) -> dict[str, TagPrediction]:
+    def infer(
+        self, image_path: Path, *, store_floor: float = DEFAULT_STORE_FLOOR,
+    ) -> dict[str, TagPrediction]:
         """Run Camie v2 on one image. Returns {name: TagPrediction} with
-        confidence >= STORE_FLOOR (across all categories — the suggestion
-        service does category filtering later).
+        confidence >= store_floor (across all categories — the suggestion
+        service does category filtering later). store_floor is the DB-backed
+        ml_settings.tagger_store_floor, passed in by the ml task.
 
         v2 emits multiple outputs; we use the refined predictions
         (output[1] per onnx_inference.py). Sigmoid is applied to raw
@@ -167,7 +175,7 @@ class Tagger:
         cats = self._tag_categories
         for idx, score in enumerate(probs):
             conf = float(score)
-            if conf < STORE_FLOOR:
+            if conf < store_floor:
                 continue
             if idx >= len(names):
                 # Output longer than metadata declared — shouldn't happen but

backend/app/tasks/ml.py

@@ -127,7 +127,10 @@ def tag_and_embed(self, image_id: int) -> dict:
                 phase = "video_infer"
                 import numpy as np
 
-                preds = _maxpool_predictions([tagger.infer(f) for f in frames])
+                preds = _maxpool_predictions(
+                    [tagger.infer(f, store_floor=settings.tagger_store_floor)
+                     for f in frames]
+                )
                 embedding = np.mean(
                     [embedder.infer(f) for f in frames], axis=0
                 ).astype("float32")
@@ -136,7 +139,7 @@ def tag_and_embed(self, image_id: int) -> dict:
             else:
                 phase = "tag"
                 t0 = time.monotonic()
-                raw = tagger.infer(src)
+                raw = tagger.infer(src, store_floor=settings.tagger_store_floor)
                 log.info(
                     "tag_and_embed tagged in %.1fs (%d tags): %s",
                     time.monotonic() - t0, len(raw), ctx,