feat(suggestions): heads are the suggestion source — Camie + centroid removed (#114 C)

The rail's Suggestions now come from the trained per-concept heads. SuggestionService.for_image scores the image's frozen SigLIP embedding against
every head (heads.score_image) and surfaces concepts above each head's own
suggest threshold; the typed-dropdown's min=0 "show everything" mode maps to a
flat floor so any head-scored concept can still be picked. Already-applied tags
drop; rejected tags stay flagged + reversible (unchanged).

REMOVED from the suggestion path (rule 22, no fallback): the Camie
ImagePrediction candidate/alias/merge pipeline and the per-tag centroid
augmentation, plus the now-dead SuggestionService internals (_load_predictions,
_threshold_for, _settings, self.aliases, self.centroids). Head suggestions are
always canonical tags, so raw_name/via_alias are null/false and the rail's
alias kebab is inert by data (its removal + the Camie ingest-tagger rip are the
flagged follow-up). for_selection (bulk consensus) now aggregates head
suggestions unchanged.

Tests rewritten to the head path: test_ml_suggestions (surfaces/applied/
rejected-reversible/override/no-embedding/no-heads), test_suggestions_bulk
(consensus), test_api_suggestions (get + dropped the Camie-alias roundtrip),
and test_ml_artist_retired (artist not head-eligible via _HEAD_KINDS).

DEPLOY NOTE: after this lands, the rail is empty until you run Train heads
(Settings → Tagging → Concept heads) — deploy, train, then the rail populates.

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

tests/test_api_suggestions.py

@@ -1,7 +1,8 @@
 import pytest
+from sqlalchemy import select
 
 from backend.app.celery_app import celery
-from backend.app.models import ImageRecord, TagKind
+from backend.app.models import ImageRecord, MLSettings, TagHead, TagKind
 from backend.app.services.tag_service import TagService
 
 pytestmark = pytest.mark.integration
@@ -31,13 +32,30 @@ async def _img(db, preds, sha="s" * 64):
 
 @pytest.mark.asyncio
 async def test_get_suggestions(client, db):
-    img = await _img(
-        db, {"sword": {"category": "general", "confidence": 0.97}}
+    # Suggestions come from a trained head now (Camie/centroid removed): an image
+    # whose embedding aligns with the head surfaces that concept.
+    s = (await db.execute(select(MLSettings).where(MLSettings.id == 1))).scalar_one()
+    img = ImageRecord(
+        path="/images/headsug.jpg", sha256="h" * 64, size_bytes=1,
+        mime="image/jpeg", width=1, height=1, origin="imported_filesystem",
+        integrity_status="unknown", siglip_embedding=[3.0] + [0.0] * 1151,
     )
+    db.add(img)
+    await db.flush()
+    tag = await TagService(db).find_or_create("sword", TagKind.general)
+    db.add(TagHead(
+        tag_id=tag.id, embedding_version=s.embedder_model_version,
+        weights=[1.0] + [0.0] * 1151, bias=0.0, suggest_threshold=0.5,
+        auto_apply_threshold=None, n_pos=10, n_neg=30,
+        ap=0.8, precision_cv=0.9, recall=0.6,
+    ))
+    await db.commit()
     resp = await client.get(f"/api/images/{img.id}/suggestions")
     assert resp.status_code == 200
     body = await resp.get_json()
-    assert "general" in body["by_category"]
+    general = body["by_category"].get("general", [])
+    s2 = next(x for x in general if x["canonical_tag_id"] == tag.id)
+    assert s2["source"] == "head"
 
 
 @pytest.mark.asyncio
@@ -121,67 +139,3 @@ async def test_alias_requires_fields(client, db):
         f"/api/images/{img.id}/suggestions/alias", json={"alias_string": "x"}
     )
     assert resp.status_code == 400
-
-
-async def _img_at(db, path, sha, preds):
-    from tests._prediction_helpers import seed_predictions
-
-    img = ImageRecord(
-        path=path, sha256=sha, size_bytes=1, mime="image/jpeg",
-        width=1, height=1, origin="imported_filesystem",
-        integrity_status="unknown",
-    )
-    db.add(img)
-    await db.commit()
-    await seed_predictions(db, img.id, preds)
-    await db.commit()
-    return img
-
-
-@pytest.mark.asyncio
-async def test_alias_roundtrip_resolves_by_raw_key(client, db):
-    """Locks the modal-alias contract: the suggestion exposes the RAW model key,
-    an alias authored with that key resolves on a later image, and the resolved
-    suggestion is flagged via_alias. (Pre-fix the modal stored the normalized
-    display name, which never resolved.)"""
-    canonical = await TagService(db).find_or_create(
-        "Sasuke Uchiha", TagKind.character
-    )
-    await db.commit()
-    preds = {"uchiha_sasuke": {"category": "character", "confidence": 0.99}}
-    img_a = await _img_at(db, "/images/alias_a.jpg", "a" * 64, preds)
-
-    # (a) raw_name is exposed so the modal can author the alias with it; the
-    # raw prediction doesn't textually match the tag, so it'd otherwise be +new.
-    body = await (
-        await client.get(f"/api/images/{img_a.id}/suggestions")
-    ).get_json()
-    sug = body["by_category"]["character"][0]
-    assert sug["raw_name"] == "uchiha_sasuke"
-    assert sug["via_alias"] is False
-    assert sug["creates_new_tag"] is True
-
-    # Author the alias keyed by the RAW key (what the frontend now sends).
-    resp = await client.post(
-        f"/api/images/{img_a.id}/suggestions/alias",
-        json={
-            "alias_string": sug["raw_name"],
-            "alias_category": "character",
-            "canonical_tag_id": canonical.id,
-        },
-    )
-    assert resp.status_code == 200
-    assert (await resp.get_json())["allowlisted"] is True
-
-    # (b) A DIFFERENT image with the same prediction now resolves via the alias
-    # (image A's tag is applied, so it's filtered there). Had the alias been
-    # stored under the display name, this would NOT resolve.
-    img_b = await _img_at(db, "/images/alias_b.jpg", "b" * 64, preds)
-    body_b = await (
-        await client.get(f"/api/images/{img_b.id}/suggestions")
-    ).get_json()
-    sug_b = body_b["by_category"]["character"][0]
-    assert sug_b["canonical_tag_id"] == canonical.id
-    assert sug_b["via_alias"] is True
-    assert sug_b["creates_new_tag"] is False
-    assert sug_b["raw_name"] == "uchiha_sasuke"