refactor(tags): unify suggestion source — one canonical DB-tag dropdown, drop dead raw/alias machinery (#154)

Every tag suggestion is a canonical DB tag now (tagging-v2 #114: heads + CCIP
score EXISTING concept tags). The pre-heads apparatus for model-predicted tags
that didn't exist in the DB — creates_new_tag / raw_name / via_alias, the
/suggestions/alias endpoint + add_alias_and_accept, AliasPickerDialog, and the
store's aliasAccept/removeAlias — was dead and is removed.

The type-to-add dropdown was TWO row sources (server autocomplete + the image's
ML suggestions) merged with a dedup that dropped the %-bearing suggestion row
when the debounced server hit landed — the operator's "confidence % flickers
then vanishes". Now it's ONE list of DB-tag matches, each annotated with the
model's confidence (join by canonical_tag_id) when the tag was scored for this
image. No dedup, no flicker; picking a suggested tag still records acceptance
via TagPanel.findPending.

Single per-image fetch: score_image now reports above_threshold per row
(computed vs the head's own suggest cut, separate from the inclusion floor), so
the rail makes ONE min=0 request and derives the panel (above_threshold) and the
dropdown (all, text-filtered) client-side — the two /suggestions calls collapse
to one. Manual "Create 'X' as <kind>" (novel typed names) is unchanged; the
alias table + tag-side alias admin + auto-apply alias matching are untouched.

Tests: gate/serializer assertions updated (above_threshold; dropped dead-field
+ alias-endpoint checks); frontend spec seeds via the single load and covers the
byCategory/aboveByCategory split.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CgZP9v2otxVJymiYsnVuMy

backend/app/api/suggestions.py

@@ -11,10 +11,11 @@ suggestions_bp = Blueprint("suggestions", __name__, url_prefix="/api")
 
 @suggestions_bp.route("/images/<int:image_id>/suggestions", methods=["GET"])
 async def get_suggestions(image_id: int):
-    # ?min=<float> overrides the configured per-category thresholds so the typed
-    # tag-input dropdown can surface EVERY stored prediction (min=0), including
-    # low-confidence actions/features, in canonical formatting. Omitted → the
-    # curated above-threshold list the Suggestions panel uses.
+    # ?min=<float> overrides the per-head suggest thresholds for INCLUSION. The
+    # rail sends min=0 in its single per-image fetch to get EVERY head (each row
+    # still carries above_threshold vs its natural cut), then derives the panel
+    # (above_threshold) and the typed dropdown (all, filtered by text) client-side
+    # — no second request. Omitted → only above-threshold rows.
     override = None
     raw_min = request.args.get("min")
     if raw_min is not None:
@@ -36,12 +37,11 @@ async def get_suggestions(image_id: int):
                         "category": s.category,
                         "score": round(s.score, 4),
                         "source": s.source,
-                        "creates_new_tag": s.creates_new_tag,
-                        # raw model key (alias is stored under this) + whether an
-                        # operator alias produced this suggestion — drive the
-                        # modal's "Treat as alias"/"Remove alias" affordances.
-                        "raw_name": s.raw_name,
-                        "via_alias": s.via_alias,
+                        # whether the score cleared the head's own suggest cut.
+                        # The single min=0 fetch returns every head; the panel
+                        # shows above_threshold, the typed dropdown shows all and
+                        # annotates each match with its score.
+                        "above_threshold": s.above_threshold,
                         # operator dismissed this tag for this image — surfaced
                         # (not dropped) so the rail can show it rejected + offer
                         # one-click un-reject.
@@ -73,26 +73,6 @@ async def accept_suggestion(image_id: int):
     return jsonify({"accepted": True, "tag_id": tag_id})
 
 
-@suggestions_bp.route(
-    "/images/<int:image_id>/suggestions/alias", methods=["POST"]
-)
-async def alias_suggestion(image_id: int):
-    body = await request.get_json()
-    required = {"alias_string", "alias_category", "canonical_tag_id"}
-    if not body or not required.issubset(body):
-        return jsonify({"error": f"required: {sorted(required)}"}), 400
-    canonical_tag_id = body["canonical_tag_id"]
-    async with get_session() as session:
-        await AllowlistService(session).add_alias_and_accept(
-            image_id,
-            body["alias_string"],
-            body["alias_category"],
-            canonical_tag_id,
-        )
-        await session.commit()
-    return jsonify({"accepted": True, "tag_id": canonical_tag_id})
-
-
 @suggestions_bp.route(
     "/images/<int:image_id>/suggestions/dismiss", methods=["POST"]
 )

backend/app/services/ml/allowlist.py

@@ -12,13 +12,11 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 from ...models import TagSuggestionRejection
 from ...models.tag import image_tag
-from .aliases import AliasService
 
 
 class AllowlistService:
     def __init__(self, session: AsyncSession):
         self.session = session
-        self.aliases = AliasService(session)
 
     async def _apply_image_tag(self, image_id: int, tag_id: int, source: str):
         stmt = insert(image_tag).values(
@@ -41,18 +39,6 @@ class AllowlistService:
         await self._apply_image_tag(image_id, tag_id, source="ml_accepted")
         await self._clear_rejection(image_id, tag_id)
 
-    async def add_alias_and_accept(
-        self,
-        image_id: int,
-        alias_string: str,
-        alias_category: str,
-        canonical_tag_id: int,
-    ) -> None:
-        await self.aliases.create(
-            alias_string, alias_category, canonical_tag_id
-        )
-        await self.accept(image_id, canonical_tag_id)
-
     async def dismiss(self, image_id: int, tag_id: int) -> None:
         stmt = insert(TagSuggestionRejection).values(
             image_record_id=image_id, tag_id=tag_id

backend/app/services/ml/heads.py

@@ -500,13 +500,19 @@ async def score_image(
     session: AsyncSession, image_id: int, threshold_override: float | None = None,
 ) -> list[dict]:
     """Suggestions for one image from the trained heads: [{tag_id, name,
-    category, score}], ranked. A concept surfaces when its score clears the
-    head's own suggest_threshold — or, when threshold_override is given (the
-    typed-dropdown "show everything" mode), that flat floor instead (0 → every
-    head). System-tag heads (wip/banner/editor) instead use a flat
-    _SYSTEM_TAG_SUGGEST_FLOOR so their false positives surface for rejection
-    (still overridden by threshold_override). Empty if the image has no
-    embedding or no heads exist yet.
+    category, score, above_threshold, grounding}], ranked. A concept is INCLUDED
+    when its score clears the head's own suggest_threshold — or, when
+    threshold_override is given (the typed-dropdown "show everything" mode), that
+    flat floor instead (0 → every head). System-tag heads (wip/banner/editor)
+    instead use a flat _SYSTEM_TAG_SUGGEST_FLOOR so their false positives surface
+    for rejection (still overridden by threshold_override). Empty if the image has
+    no embedding or no heads exist yet.
+
+    ``above_threshold`` is reported SEPARATELY from inclusion: it's always whether
+    the score cleared the head's NATURAL cut (suggest_threshold, or the system
+    floor), regardless of any override. So the single min=0 fetch returns every
+    head, and the caller can split panel (above_threshold) from dropdown (all)
+    without a second request.
 
     MAX-OVER-BAG: the image is scored as a BAG of embeddings — the whole-image
     vector PLUS every concept-region crop the agent embedded (same model
@@ -537,21 +543,25 @@ async def score_image(
     winners = probs_bag.argmax(axis=0)                  # (H,)
     out = []
     for i, p in enumerate(probs):
-        if threshold_override is not None:
-            cut = threshold_override
-        elif heads["meta"][i]["is_system"]:
-            # System tags surface at the flat floor (see _SYSTEM_TAG_SUGGEST_FLOOR)
-            # so their false positives show up for the operator to reject.
-            cut = _SYSTEM_TAG_SUGGEST_FLOOR
-        else:
-            cut = heads["thr"][i]
+        m = heads["meta"][i]
+        # The head's NATURAL suggest cut — system tags use the flat floor (see
+        # _SYSTEM_TAG_SUGGEST_FLOOR) so their false positives show up for the
+        # operator to reject; content heads use their own precision-tuned
+        # threshold. This is what "above threshold" means (drives the panel).
+        natural = (
+            _SYSTEM_TAG_SUGGEST_FLOOR if m["is_system"] else float(heads["thr"][i])
+        )
+        # INCLUSION is looser under threshold_override (dropdown show-all,
+        # override=0): every head comes back so a low-confidence concept can still
+        # be typed + picked, each carrying its own above_threshold flag.
+        cut = threshold_override if threshold_override is not None else natural
         if p >= cut:
-            m = heads["meta"][i]
             out.append({
                 "tag_id": m["tag_id"],
                 "name": m["name"],
                 "category": m["category"],
                 "score": float(p),
+                "above_threshold": bool(p >= natural),
                 "grounding": bag_meta[int(winners[i])],
             })
     out.sort(key=lambda d: d["score"], reverse=True)

backend/app/services/ml/suggestions.py

@@ -22,22 +22,20 @@ from .heads import score_image
 
 @dataclass(frozen=True)
 class Suggestion:
-    # canonical_tag_id is None when this is a raw Camie tag with no alias and
-    # no existing Tag row — accepting it will create the tag.
-    canonical_tag_id: int | None
+    # Every suggestion is a canonical Tag: heads/CCIP only score EXISTING concept
+    # tags (tagging-v2, #114). The old raw-model-key / creates-new / alias-remap
+    # cases are gone — a suggestion always maps to a real tag id.
+    canonical_tag_id: int
     display_name: str
     category: str
     score: float
     source: str  # 'head' | 'ccip' | 'both' (Camie tagger/centroid removed in v2)
-    creates_new_tag: bool
-    # raw_name = the booru model vocab key behind this suggestion. It's the key
-    # an alias MUST be stored under (resolution looks up the raw key), so the
-    # modal needs it to author an alias correctly. None for centroid-only hits
-    # (no underlying prediction → nothing to alias).
-    raw_name: str | None = None
-    # via_alias = this suggestion was surfaced because an operator alias remapped
-    # the raw prediction to this canonical tag. Lets the UI mark it + offer undo.
-    via_alias: bool = False
+    # above_threshold = the score cleared the head's own suggest cut (or the
+    # system floor). The Suggestions PANEL shows only these; the typed-tag
+    # dropdown fetches ALL suggestions (every head, min=0) and just annotates each
+    # matching row with its score, so a low-confidence concept can still be typed
+    # and picked. CCIP character matches are always above their match threshold.
+    above_threshold: bool
     # rejected = the operator dismissed this tag for this image (a stored
     # TagSuggestionRejection). It stays in the list — flagged, not dropped — so
     # the rejection is VISIBLE and REVERSIBLE in the rail (misclick recovery,
@@ -108,6 +106,7 @@ class SuggestionService:
         for h in hits:
             merged[(h["category"], h["tag_id"])] = {
                 "name": h["name"], "score": h["score"], "source": "head",
+                "above_threshold": h["above_threshold"],
                 "grounding": h.get("grounding"),
             }
         for c in ccip_hits:
@@ -116,12 +115,16 @@ class SuggestionService:
             if ex is not None:
                 ex["source"] = "both"
                 ex["score"] = max(ex["score"], c["score"])
+                # CCIP only returns matches above its own threshold, so a CCIP
+                # corroboration always makes the merged suggestion above-threshold.
+                ex["above_threshold"] = True
                 # Keep the head's localized crop if it had one; else fall back to
                 # the CCIP figure so a corroborated character still grounds (#1206).
                 ex["grounding"] = ex.get("grounding") or c.get("grounding")
             else:
                 merged[key] = {
                     "name": c["name"], "score": c["score"], "source": "ccip",
+                    "above_threshold": True,
                     "grounding": c.get("grounding"),
                 }
 
@@ -136,7 +139,7 @@ class SuggestionService:
                     category=cat,
                     score=m["score"],
                     source=m["source"],
-                    creates_new_tag=False,
+                    above_threshold=m["above_threshold"],
                     rejected=tag_id in rejected,
                     grounding=m.get("grounding"),
                 )
@@ -157,8 +160,7 @@ class SuggestionService:
         was suggested for (or already applied to) >= threshold fraction of
         the selection AND was acceptable on >= 1 image. Confidence is the
         mean over images where it was suggested. Aggregated by
-        canonical_tag_id; creates-new (no canonical id) suggestions are
-        skipped (bulk Accept applies by tag id)."""
+        canonical_tag_id (every suggestion is a canonical tag now)."""
         if not image_ids:
             return {}
         threshold = min(1.0, max(0.0, threshold))
@@ -169,8 +171,6 @@ class SuggestionService:
             sl = await self.for_image(image_id)
             for category, items in sl.by_category.items():
                 for s in items:
-                    if s.canonical_tag_id is None or s.creates_new_tag:
-                        continue
                     # for_image keeps rejected tags (flagged) for the rail;
                     # bulk consensus must still ignore them — a tag dismissed on
                     # an image isn't a suggestion for that image.