refactor(tags): unify suggestion source — one canonical DB-tag dropdown, drop dead raw/alias machinery (#154)
CI / lint (push) Successful in 3s
CI / frontend-build (push) Successful in 20s
CI / backend-lint-and-test (push) Successful in 36s
CI / integration (push) Successful in 3m45s

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
This commit is contained in:
2026-07-10 15:22:51 -04:00
parent 6ab7fd5c7f
commit a444cf82d1
14 changed files with 227 additions and 543 deletions
+26 -16
View File
@@ -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)