feat(ccip): tunable match threshold, default 0.85 (#114)

Live data showed the v1 flat 0.75 cosine over-fired — ~64% of matched images got
3-10 character guesses dominated by the most-referenced characters (a 27-ref
character clears a low bar on many images). A sweep showed 0.85 collapses the
noise (noisy multi-matches 47→3) while keeping the confident single-character
matches.

- ml_settings.ccip_match_threshold (migration 0063, default 0.85); match_image
  reads it (override still accepted). DEFAULT_SIM_THRESHOLD fallback 0.75→0.85.
- Exposed in GET/PATCH /api/ml/settings (validated 0.5–0.999).
- Slider in the GPU agent card ("Character-match strictness") — tune live, no
  redeploy, same observe-and-tune loop as auto-apply.

Test: a ~0.9-cosine figure matches at 0.85, dropped at 0.95.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ttrj5P7upUTueSfoJcxEqa

backend/app/api/ml_admin.py

@@ -21,6 +21,7 @@ _EDITABLE = (
     "head_auto_apply_precision",
     "head_auto_apply_enabled",
     "head_auto_apply_min_positives",
+    "ccip_match_threshold",
 )
 
 
@@ -48,6 +49,7 @@ async def get_settings():
             "head_auto_apply_precision": s.head_auto_apply_precision,
             "head_auto_apply_enabled": s.head_auto_apply_enabled,
             "head_auto_apply_min_positives": s.head_auto_apply_min_positives,
+            "ccip_match_threshold": s.ccip_match_threshold,
         }
     )
 
@@ -115,6 +117,8 @@ def _validate(p: dict) -> str | None:
         return "head_auto_apply_precision must be between 0.5 and 0.999"
     if int(p["head_auto_apply_min_positives"]) < 1:
         return "head_auto_apply_min_positives must be >= 1"
+    if not (0.5 <= float(p["ccip_match_threshold"]) <= 0.999):
+        return "ccip_match_threshold must be between 0.5 and 0.999"
     return None
 
 

backend/app/models/ml_settings.py

@@ -86,6 +86,12 @@ class MLSettings(Base):
     head_auto_apply_min_positives: Mapped[int] = mapped_column(
         Integer, nullable=False, default=30
     )
+    # CCIP character-match cosine cut (#114). 0.85 default — the v1 flat 0.75
+    # over-fired (high-reference characters matched a scatter of images); 0.85
+    # keeps the confident single-character matches. Tunable from the agent card.
+    ccip_match_threshold: Mapped[float] = mapped_column(
+        Float, nullable=False, default=0.85
+    )
     tagger_model_version: Mapped[str] = mapped_column(
         String(128), nullable=False, default="camie-tagger-v2"
     )

backend/app/services/ml/ccip.py

@@ -16,15 +16,25 @@ the hands-on eval. numpy is imported lazily (API worker has it via pgvector).
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from ...models import ImageRegion, Tag, TagKind
+from ...models import ImageRegion, MLSettings, Tag, TagKind
 from ...models.tag import image_tag
 
-# Cosine-similarity floor to call a figure the same character. Conservative
-# default; tune from real matches (CCIP same-char clusters tightly).
-DEFAULT_SIM_THRESHOLD = 0.75
+# Cosine-similarity floor to call a figure the same character. The live setting
+# (ml_settings.ccip_match_threshold) drives it; this is only the fallback when no
+# threshold is supplied AND no settings row exists.
+DEFAULT_SIM_THRESHOLD = 0.85
 _FIGURE_KINDS = ("face", "figure")
 
 
+async def _settings_threshold(session: AsyncSession) -> float:
+    val = (
+        await session.execute(
+            select(MLSettings.ccip_match_threshold).where(MLSettings.id == 1)
+        )
+    ).scalar_one_or_none()
+    return float(val) if val is not None else DEFAULT_SIM_THRESHOLD
+
+
 def _l2norm(mat, np):
     n = np.linalg.norm(mat, axis=1, keepdims=True)
     n[n == 0] = 1.0
@@ -68,14 +78,18 @@ async def _tag_names(session: AsyncSession, tag_ids: list[int]) -> dict[int, str
 
 
 async def match_image(
-    session: AsyncSession, image_id: int, threshold: float = DEFAULT_SIM_THRESHOLD
+    session: AsyncSession, image_id: int, threshold: float | None = None
 ) -> list[dict]:
     """Character suggestions for one image from its figure-region CCIP vectors:
     [{tag_id, name, category:'character', score, source:'ccip'}], ranked.
     Already-applied character tags are excluded. Empty if the image has no figure
-    CCIP vectors or no character references exist yet."""
+    CCIP vectors or no character references exist yet. threshold defaults to the
+    live ml_settings.ccip_match_threshold."""
     import numpy as np
 
+    if threshold is None:
+        threshold = await _settings_threshold(session)
+
     qvecs = (
         await session.execute(
             select(ImageRegion.ccip_embedding).where(