FabledCurator/backend/app/api/suggestions.py

"""Suggestions API: per-image ranked suggestions + accept/alias/dismiss."""

from quart import Blueprint, jsonify, request

from ..extensions import get_session
from ..services.ml.allowlist import AllowlistService
from ..services.ml.suggestions import SuggestionService

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 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:
        try:
            override = min(1.0, max(0.0, float(raw_min)))
        except ValueError:
            return jsonify({"error": "min must be a float in [0,1]"}), 400
    async with get_session() as session:
        sl = await SuggestionService(session).for_image(
            image_id, threshold_override=override
        )
    return jsonify(
        {
            "by_category": {
                cat: [
                    {
                        "canonical_tag_id": s.canonical_tag_id,
                        "display_name": s.display_name,
                        "category": s.category,
                        "score": round(s.score, 4),
                        "source": s.source,
                        # 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.
                        "rejected": s.rejected,
                        # the crop region that produced this tag (#1206) —
                        # {bbox,kind,detector} or null (whole-image won). Drives
                        # the hover→overlay highlight.
                        "grounding": s.grounding,
                    }
                    for s in items
                ]
                for cat, items in sl.by_category.items()
            }
        }
    )


@suggestions_bp.route(
    "/images/<int:image_id>/suggestions/accept", methods=["POST"]
)
async def accept_suggestion(image_id: int):
    body = await request.get_json()
    if not body or "tag_id" not in body:
        return jsonify({"error": "tag_id required"}), 400
    tag_id = body["tag_id"]
    async with get_session() as session:
        await AllowlistService(session).accept(image_id, tag_id)
        await session.commit()
    return jsonify({"accepted": True, "tag_id": tag_id})


@suggestions_bp.route(
    "/images/<int:image_id>/suggestions/dismiss", methods=["POST"]
)
async def dismiss_suggestion(image_id: int):
    body = await request.get_json()
    if not body or "tag_id" not in body:
        return jsonify({"error": "tag_id required"}), 400
    async with get_session() as session:
        await AllowlistService(session).dismiss(image_id, body["tag_id"])
        await session.commit()
    return "", 204


@suggestions_bp.route(
    "/images/<int:image_id>/suggestions/undismiss", methods=["POST"]
)
async def undismiss_suggestion(image_id: int):
    """Reverse a per-image dismissal (reject-recovery). Idempotent — undoing a
    tag that isn't rejected is a no-op delete."""
    body = await request.get_json()
    if not body or "tag_id" not in body:
        return jsonify({"error": "tag_id required"}), 400
    async with get_session() as session:
        await AllowlistService(session).undismiss(image_id, body["tag_id"])
        await session.commit()
    return "", 204


@suggestions_bp.route("/suggestions/bulk", methods=["POST"])
async def bulk_suggestions():
    body = await request.get_json()
    if not body or "image_ids" not in body:
        return jsonify({"error": "image_ids required"}), 400
    raw = body["image_ids"]
    if not isinstance(raw, list) or not raw:
        return jsonify({"error": "image_ids must be a non-empty list"}), 400
    try:
        ids = [int(x) for x in raw]
    except (TypeError, ValueError):
        return jsonify({"error": "image_ids must be integers"}), 400
    if len(ids) > 200:
        return jsonify({"error": "selection too large (max 200)"}), 400
    try:
        threshold = float(body.get("threshold", 0.8))
    except (TypeError, ValueError):
        threshold = 0.8
    threshold = min(1.0, max(0.0, threshold))
    async with get_session() as session:
        suggestions = await SuggestionService(session).for_selection(
            ids, threshold=threshold
        )
    return jsonify(
        {
            "suggestions": suggestions,
            "evaluated": len(ids),
            "threshold": threshold,
        }
    )