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_ml_suggestions.py

@@ -1,8 +1,11 @@
+"""Suggestion read-path (tagging-v2): suggestions come from trained HEADS, not
+Camie predictions or centroids. Heads are inserted directly (training needs
+scikit-learn, ml image only); scoring is numpy-only (available via pgvector)."""
 import pytest
+from sqlalchemy import select
 
-from backend.app.models import ImageRecord, TagKind
+from backend.app.models import ImageRecord, MLSettings, TagHead, TagKind
 from backend.app.models.tag import image_tag
-from backend.app.services.ml.aliases import AliasService
 from backend.app.services.ml.allowlist import AllowlistService
 from backend.app.services.ml.suggestions import SuggestionService
 from backend.app.services.tag_service import TagService
@@ -10,179 +13,121 @@ from backend.app.services.tag_service import TagService
 pytestmark = pytest.mark.integration
 
 
-def _img(sha: str) -> ImageRecord:
-    return ImageRecord(
-        path=f"/images/{sha}.jpg",
-        sha256=sha,
-        size_bytes=1,
-        mime="image/jpeg",
-        width=1,
-        height=1,
-        origin="imported_filesystem",
-        integrity_status="unknown",
+def _emb(slot: int, val: float = 3.0) -> list[float]:
+    """An embedding pointing along axis `slot` (so its L2-normalized form is the
+    unit vector e_slot — a head with weights e_slot scores it sigmoid(1)≈0.73)."""
+    v = [0.0] * 1152
+    v[slot] = val
+    return v
+
+
+async def _img(db, sha: str, emb=None) -> ImageRecord:
+    img = ImageRecord(
+        path=f"/images/{sha}.jpg", sha256=sha, size_bytes=1, mime="image/jpeg",
+        width=1, height=1, origin="imported_filesystem",
+        integrity_status="unknown", siglip_embedding=emb,
     )
-
-
-async def _seed_img(db, sha: str, predictions: dict) -> ImageRecord:
-    """#768: create an image + seed its predictions into image_prediction
-    (the read path's source), returning the flushed record."""
-    from tests._prediction_helpers import seed_predictions
-
-    img = _img(sha)
     db.add(img)
     await db.flush()
-    await seed_predictions(db, img.id, predictions)
     return img
 
 
+async def _embver(db) -> str:
+    s = (await db.execute(select(MLSettings).where(MLSettings.id == 1))).scalar_one()
+    return s.embedder_model_version
+
+
+async def _head(db, tag_id: int, slot: int, suggest_threshold: float = 0.5):
+    weights = [0.0] * 1152
+    weights[slot] = 1.0
+    db.add(TagHead(
+        tag_id=tag_id, embedding_version=await _embver(db),
+        weights=weights, bias=0.0, suggest_threshold=suggest_threshold,
+        auto_apply_threshold=None, n_pos=10, n_neg=30,
+        ap=0.8, precision_cv=0.9, recall=0.6,
+    ))
+
+
 @pytest.mark.asyncio
-async def test_threshold_filters_low_confidence_general(db):
-    # Default general threshold is 0.50 (alembic 0029 lowered it from
-    # 0.95). Use 0.30/0.60 to keep the test asserting threshold behavior
-    # rather than the exact cutoff number.
-    img = await _seed_img(
-        db,
-        "a" * 64,
-        {
-            "lowconf": {"category": "general", "confidence": 0.30},
-            "sword": {"category": "general", "confidence": 0.97},
-        },
-    )
+async def test_head_suggestion_surfaces_for_matching_image(db):
+    tag = await TagService(db).find_or_create("glasses", TagKind.general)
+    img = await _img(db, "a" * 64, _emb(0))
+    await _head(db, tag.id, slot=0)
+    await db.commit()
+
     sl = await SuggestionService(db).for_image(img.id)
-    names = [s.display_name for s in sl.by_category.get("general", [])]
-    # display_name is normalized (tag_name.normalize) before surfacing.
-    assert "Sword" in names
-    assert "Lowconf" not in names
+    general = sl.by_category["general"]
+    assert len(general) == 1
+    s = general[0]
+    assert s.canonical_tag_id == tag.id
+    assert s.source == "head"
+    assert s.creates_new_tag is False
+    assert s.via_alias is False and s.raw_name is None
+    assert s.score > 0.5
 
 
 @pytest.mark.asyncio
-async def test_threshold_override_surfaces_low_confidence(db):
-    # The typed-dropdown "show everything the model saw" mode: threshold_override
-    # surfaces stored predictions below the configured threshold (in canonical
-    # formatting) so they can be picked instead of hand-typed (2026-06-09).
-    img = await _seed_img(
-        db,
-        "d" * 64,
-        {
-            "lowconf": {"category": "general", "confidence": 0.30},
-            "sword": {"category": "general", "confidence": 0.97},
-        },
-    )
-    sl = await SuggestionService(db).for_image(img.id, threshold_override=0.0)
-    names = [s.display_name for s in sl.by_category.get("general", [])]
-    assert "Sword" in names
-    assert "Lowconf" in names  # below the configured threshold, surfaced anyway
-
-    # Unsurfaced categories are still excluded even with the override.
-    img2 = await _seed_img(
-        db, "e" * 64, {"safe": {"category": "rating", "confidence": 0.99}}
-    )
-    sl2 = await SuggestionService(db).for_image(img2.id, threshold_override=0.0)
-    assert "rating" not in sl2.by_category
+async def test_no_embedding_means_no_suggestions(db):
+    img = await _img(db, "b" * 64, None)
+    tag = await TagService(db).find_or_create("cat", TagKind.general)
+    await _head(db, tag.id, slot=0)
+    await db.commit()
+    assert (await SuggestionService(db).for_image(img.id)).by_category == {}
 
 
 @pytest.mark.asyncio
-async def test_unsurfaced_category_dropped(db):
-    img = await _seed_img(
-        db,
-        "b" * 64,
-        {"safe": {"category": "rating", "confidence": 0.99}},
-    )
-    sl = await SuggestionService(db).for_image(img.id)
-    assert "rating" not in sl.by_category
-
-
-@pytest.mark.asyncio
-async def test_alias_resolution(db):
-    tags = TagService(db)
-    canonical = await tags.find_or_create("Sasuke Uchiha", TagKind.character)
-    await AliasService(db).create("uchiha_sasuke", "character", canonical.id)
-    img = await _seed_img(
-        db,
-        "c" * 64,
-        {"uchiha_sasuke": {"category": "character", "confidence": 0.96}},
-    )
-    sl = await SuggestionService(db).for_image(img.id)
-    chars = sl.by_category["character"]
-    assert len(chars) == 1
-    assert chars[0].display_name == "Sasuke Uchiha"
-    assert chars[0].canonical_tag_id == canonical.id
-    assert chars[0].creates_new_tag is False
-    # Surfaced via an alias on the raw model key — the UI marks it + offers undo.
-    assert chars[0].via_alias is True
-    assert chars[0].raw_name == "uchiha_sasuke"
-
-
-@pytest.mark.asyncio
-async def test_raw_tag_creates_new(db):
-    img = await _seed_img(
-        db,
-        "d" * 64,
-        {"brand_new_tag": {"category": "character", "confidence": 0.96}},
-    )
-    sl = await SuggestionService(db).for_image(img.id)
-    chars = sl.by_category["character"]
-    # display_name is the normalized Camie name (underscores -> spaces,
-    # title-cased), not the raw vocab key.
-    assert chars[0].display_name == "Brand New Tag"
-    assert chars[0].creates_new_tag is True
-    # Not aliased, but the raw key is carried so the modal can author one.
-    assert chars[0].via_alias is False
-    assert chars[0].raw_name == "brand_new_tag"
-    assert chars[0].canonical_tag_id is None
+async def test_no_heads_means_no_suggestions(db):
+    img = await _img(db, "c" * 64, _emb(0))
+    await db.commit()  # no heads trained yet
+    assert (await SuggestionService(db).for_image(img.id)).by_category == {}
 
 
 @pytest.mark.asyncio
 async def test_applied_tag_not_suggested(db):
-    tags = TagService(db)
-    tag = await tags.find_or_create("alreadyhere", TagKind.character)
-    img = await _seed_img(
-        db,
-        "e" * 64,
-        {"alreadyhere": {"category": "character", "confidence": 0.96}},
-    )
+    tag = await TagService(db).find_or_create("dog", TagKind.general)
+    img = await _img(db, "d" * 64, _emb(0))
+    await _head(db, tag.id, slot=0)
     await db.execute(
         image_tag.insert().values(
             image_record_id=img.id, tag_id=tag.id, source="manual"
         )
     )
+    await db.commit()
     sl = await SuggestionService(db).for_image(img.id)
-    assert "character" not in sl.by_category or not sl.by_category["character"]
+    assert "general" not in sl.by_category or not sl.by_category["general"]
+
+
+@pytest.mark.asyncio
+async def test_threshold_override_surfaces_below_cut(db):
+    # A head with a high suggest_threshold won't surface on a so-so score, but
+    # the dropdown's override=0 floor surfaces every head regardless.
+    tag = await TagService(db).find_or_create("horse", TagKind.general)
+    img = await _img(db, "e" * 64, _emb(1))   # orthogonal to the head → score 0.5
+    await _head(db, tag.id, slot=0, suggest_threshold=0.6)
+    await db.commit()
+    svc = SuggestionService(db)
+    assert svc and not (await svc.for_image(img.id)).by_category.get("general")
+    flooded = await svc.for_image(img.id, threshold_override=0.0)
+    assert any(s.canonical_tag_id == tag.id for s in flooded.by_category["general"])
 
 
 @pytest.mark.asyncio
 async def test_rejected_tag_surfaced_flagged_then_reversible(db):
-    # A dismissed suggestion is NOT dropped: it stays in the list flagged
-    # rejected=True so the rail can show it + offer one-click un-reject
-    # (visible, reversible rejection — operator-asked 2026-06-27). A live
-    # suggestion sorts ahead of the rejected one.
-    tags = TagService(db)
-    rejected_tag = await tags.find_or_create("rejectme", TagKind.general)
-    img = await _seed_img(
-        db,
-        "f" * 64,
-        {
-            "rejectme": {"category": "general", "confidence": 0.96},
-            "keepme": {"category": "general", "confidence": 0.90},
-        },
-    )
-    await AllowlistService(db).dismiss(img.id, rejected_tag.id)
+    # A dismissed suggestion is NOT dropped: it stays flagged rejected so the
+    # rail can show it + offer one-click un-reject (operator-asked 2026-06-27).
+    tag = await TagService(db).find_or_create("goblin", TagKind.general)
+    img = await _img(db, "f" * 64, _emb(0))
+    await _head(db, tag.id, slot=0)
+    await db.commit()
+    await AllowlistService(db).dismiss(img.id, tag.id)
+    await db.commit()
 
     sl = await SuggestionService(db).for_image(img.id)
-    general = sl.by_category["general"]
-    # Match by id, not display casing (an existing tag keeps its stored name).
-    rej = next(s for s in general if s.canonical_tag_id == rejected_tag.id)
-    assert rej.rejected is True
-    live = [s for s in general if not s.rejected]
-    assert live, "the un-rejected 'keepme' suggestion should still surface"
-    # Live suggestions sort ahead of rejected ones regardless of score.
-    assert general[-1].canonical_tag_id == rejected_tag.id
+    s = next(x for x in sl.by_category["general"] if x.canonical_tag_id == tag.id)
+    assert s.rejected is True
 
-    # Un-reject reverts it to a live suggestion.
-    await AllowlistService(db).undismiss(img.id, rejected_tag.id)
+    await AllowlistService(db).undismiss(img.id, tag.id)
+    await db.commit()
     sl2 = await SuggestionService(db).for_image(img.id)
-    rej2 = next(
-        s for s in sl2.by_category["general"]
-        if s.canonical_tag_id == rejected_tag.id
-    )
-    assert rej2.rejected is False
+    s2 = next(x for x in sl2.by_category["general"] if x.canonical_tag_id == tag.id)
+    assert s2.rejected is False