FabledCurator/backend/app/models/ml_settings.py

"""MLSettings — single-row table holding ML pipeline tunables."""

from datetime import datetime

from sqlalchemy import (
    Boolean,
    CheckConstraint,
    DateTime,
    Float,
    Integer,
    String,
    func,
    select,
    text,
)
from sqlalchemy.orm import Mapped, mapped_column

from .base import Base


class MLSettings(Base):
    __tablename__ = "ml_settings"
    # Bare name — Base.metadata's naming convention prepends ck_<table>_,
    # producing ck_ml_settings_singleton. The chain shipped the DOUBLED
    # ck_ml_settings_ck_ml_settings_singleton, because the migration
    # pre-prefixed the name and the convention prefixed it again; alembic
    # 0088 renames it to what this line has always produced (#3275).
    __table_args__ = (CheckConstraint("id = 1", name="singleton"),)

    id: Mapped[int] = mapped_column(Integer, primary_key=True)
    # CPU whole-image embedding (B3, operator 2026-07-02). The ml-worker's ONLY
    # processing role is the embed fallback for stacks WITHOUT a GPU agent — ON
    # by default so a fresh install works with no agent. Stacks that run the
    # agent and drop the ml-worker container turn this OFF so import hooks stop
    # queueing embed work nothing will consume (the daily GPU 'embed' backfill
    # covers those images instead).
    cpu_embed_enabled: Mapped[bool] = mapped_column(
        Boolean, nullable=False, default=True,
        server_default="true",
    )
    # Video embedding (#747). Sample one frame every N seconds (fixed CADENCE, not
    # a fixed count) so coverage reflects real screen time regardless of length;
    # cap the total so a long video can't explode into hundreds of embeds. The
    # per-frame SigLIP embeddings are mean-pooled. Operator-tunable.
    video_frame_interval_seconds: Mapped[float] = mapped_column(
        Float, nullable=False, default=4.0,
        server_default="4",
    )
    video_max_frames: Mapped[int] = mapped_column(
        Integer, nullable=False, default=64,
        server_default="64",
    )
    # Tagging-v2 head training (#114). The head is the suggestion source that
    # LEARNS from the operator's tags (replacing Camie + centroid). A concept
    # needs >= head_min_positives labelled images before a head is trained;
    # head_auto_apply_precision is the precision bar a head must clear (at some
    # operating point) to "graduate" into earned auto-apply. Operator-tunable.
    head_min_positives: Mapped[int] = mapped_column(
        Integer, nullable=False, default=8,
        server_default="8",
    )
    head_auto_apply_precision: Mapped[float] = mapped_column(
        Float, nullable=False, default=0.97,
        server_default="0.97",
    )
    # Earned auto-apply (#114). A graduated head fires (tags images without a
    # human) when this master switch is on AND the head has at least
    # head_auto_apply_min_positives clean labels — so a precise-looking but
    # under-supported low-N head can't spray tags across the library. ON by
    # default (operator-asked 2026-06-29: opt-OUT, not opt-in); the support +
    # measured-precision gates keep it safe, and every auto-tag is reversible.
    head_auto_apply_enabled: Mapped[bool] = mapped_column(
        Boolean, nullable=False, default=True,
        server_default="true",
    )
    head_auto_apply_min_positives: Mapped[int] = mapped_column(
        # Support floor raised 30→50 (operator-asked 2026-07-06): a head needs
        # more human labels before it may fire without a human.
        Integer, nullable=False, default=50,
        server_default="30",
    )
    # CCIP character-match cosine cut (#114). 0.85 default — the v1 flat 0.75
    # over-fired (high-reference characters matched a scatter of images); 0.85
    # keeps the confident single-character matches. Tunable from the agent card.
    ccip_match_threshold: Mapped[float] = mapped_column(
        Float, nullable=False, default=0.85,
        server_default="0.85",
    )
    # CCIP auto-apply (#114). Confident matches (>= ccip_auto_apply_threshold,
    # above the suggest cut) auto-tag on a daily sweep. ON by default (opt-out);
    # single-character references + the high bar keep it safe, every tag reversible.
    ccip_auto_apply_enabled: Mapped[bool] = mapped_column(
        Boolean, nullable=False, default=True,
        server_default="true",
    )
    ccip_auto_apply_threshold: Mapped[float] = mapped_column(
        # Raised 0.92→0.95 (operator-asked 2026-07-06) so only very confident
        # character matches auto-tag.
        Float, nullable=False, default=0.95,
        server_default="0.92",
    )
    # -- Presentation chrome auto-hide (#141) -------------------------------
    # `banner` (chrome — clusters on UI, not content) auto-applies on the sweep
    # with its OWN flat threshold (decoupled from content-head graduation) and is
    # HIDDEN from the gallery. Hiding is consequential so it runs HIGH. When an
    # image would be auto-hidden but ALSO scores >= presentation_conflict_threshold
    # on a content head, it's still hidden but flagged for review
    # (PresentationReview, mode='chrome') instead of buried silently. ON by default
    # (opt-out); every auto-tag is reversible. NOTE (#1464): `wip` + `editor
    # screenshot` are no longer chrome — they went to the PROCESS path below.
    presentation_auto_apply_enabled: Mapped[bool] = mapped_column(
        Boolean, nullable=False, default=True,
        server_default="true",
    )
    presentation_auto_apply_threshold: Mapped[float] = mapped_column(
        Float, nullable=False, default=0.90,
        # text(), not a string, because alembic 0082 used sa.text(): a bare
        # string renders DEFAULT '0.90'::double precision while text() renders
        # DEFAULT 0.90, and the chain is MIXED — some migrations used one,
        # some the other. Same value, different stored expression, so each
        # column here mirrors whichever form its own migration used (#3275).
        server_default=text("0.90"),
    )
    presentation_conflict_threshold: Mapped[float] = mapped_column(
        Float, nullable=False, default=0.50,
        server_default=text("0.50"),
    )
    # -- Process auto-apply (#1464) ----------------------------------------
    # `wip` / `editor screenshot` are PROCESS art — unfinished pieces + program
    # screenshots that must stay OUT of head/CCIP training but, unlike chrome,
    # remain VISIBLE in the gallery (operator 2026-07-12). They auto-apply on the
    # sweep with their OWN flat threshold and a PROVISIONAL source (`process_auto`,
    # in training_data._AUTO_SOURCES) so the head NEVER trains on its own output —
    # it learns only from title (`wip_title`) + manual labels, which breaks the
    # runaway loop. When a process tag would be applied but the image ALSO scores
    # >= process_conflict_threshold on a content head, it's flagged for review
    # (PresentationReview, mode='process') rather than silently marked. OFF by
    # default — a new whole-library auto-tagger is opt-in; every auto-tag reversible.
    process_auto_apply_enabled: Mapped[bool] = mapped_column(
        Boolean, nullable=False, default=False,
        server_default="false",
    )
    process_auto_apply_threshold: Mapped[float] = mapped_column(
        Float, nullable=False, default=0.90,
        server_default="0.90",
    )
    process_conflict_threshold: Mapped[float] = mapped_column(
        Float, nullable=False, default=0.50,
        server_default="0.50",
    )
    # Default = SigLIP 2 (so400m, 512px) for new installs (migration 0069);
    # existing libraries keep their stored value until the operator re-embeds.
    embedder_model_version: Mapped[str] = mapped_column(
        String(128), nullable=False, default="siglip2-so400m-patch16-512",
        server_default="siglip2-so400m-patch16-512",
    )
    # The HF model NAME the embedder loads (server CPU embed + announced to the
    # GPU agent in the lease). Operator-settable so the embedder is a choice, not
    # a hardcode (#1190): set name + version together, then re-embed + retrain.
    embedder_model_name: Mapped[str] = mapped_column(
        String(128), nullable=False, default="google/siglip2-so400m-patch16-512",
        server_default="google/siglip2-so400m-patch16-512",
    )
    # -- Crop proposers / detectors (#1202, #134) --------------------------
    # WHERE-to-crop YOLO detectors feeding the crop→SigLIP bag + CCIP. Config
    # lives HERE (DB) and is announced to the GPU agent in the lease — same as
    # the embedder model — so it is UI-tunable with NO restart, and the agent's
    # env is bootstrap-only. Each weights spec is an ultralytics builtin name,
    # an http(s) URL, or "hf_repo::file" (agent's _resolve). enabled off (or an
    # empty weights) skips that proposer. All ON by default (operator 2026-07-05)
    # so a fresh install crops out-of-the-box.
    # person: general COCO figure detector for Western/realistic art the anime
    # person-detector misses → NMS-merged with imgutils → CCIP + concept.
    detector_person_enabled: Mapped[bool] = mapped_column(
        Boolean, nullable=False, default=True,
        server_default="true",
    )
    detector_person_weights: Mapped[str] = mapped_column(
        String(512), nullable=False, default="yolo11n.pt",
        server_default="yolo11n.pt",
    )
    detector_person_conf: Mapped[float] = mapped_column(
        Float, nullable=False, default=0.35,
        server_default=text("0.35"),
    )
    # anatomy: booru_yolo anime/furry/NSFW torso components → concept crops.
    # Default = yolov11m_aa22 (26 classes, best mAP50-95 0.96), committed in the
    # upstream repo so the URL resolves. License UNSTATED — fine for a private
    # homelab (operator accepted #1202).
    detector_anatomy_enabled: Mapped[bool] = mapped_column(
        Boolean, nullable=False, default=True,
        server_default="true",
    )
    detector_anatomy_weights: Mapped[str] = mapped_column(
        String(512), nullable=False,
        default=(
            "https://github.com/aperveyev/booru_yolo/raw/main/models/"
            "yolov11m_aa22.pt"
        ),
        server_default="https://github.com/aperveyev/booru_yolo/raw/main/models/yolov11m_aa22.pt",
    )
    detector_anatomy_conf: Mapped[float] = mapped_column(
        Float, nullable=False, default=0.30,
        server_default=text("0.30"),
    )
    # panel: comic page → panel regions → concept crops (Apache-2.0, YOLOv12x).
    detector_panel_enabled: Mapped[bool] = mapped_column(
        Boolean, nullable=False, default=True,
        server_default="true",
    )
    detector_panel_weights: Mapped[str] = mapped_column(
        String(512), nullable=False,
        default="mosesb/best-comic-panel-detection::best.pt",
        server_default="mosesb/best-comic-panel-detection::best.pt",
    )
    detector_panel_conf: Mapped[float] = mapped_column(
        Float, nullable=False, default=0.30,
        server_default=text("0.30"),
    )
    # Per-frame caps bound the crop→embed explosion; max_regions is the hard
    # per-job backstop; dedupe_iou drops near-duplicate crops before the embed.
    detector_max_figures: Mapped[int] = mapped_column(
        Integer, nullable=False, default=8,
        server_default="8",
    )
    detector_max_components: Mapped[int] = mapped_column(
        Integer, nullable=False, default=8,
        server_default="8",
    )
    detector_max_panels: Mapped[int] = mapped_column(
        Integer, nullable=False, default=8,
        server_default="8",
    )
    detector_max_regions: Mapped[int] = mapped_column(
        Integer, nullable=False, default=128,
        server_default="128",
    )
    detector_dedupe_iou: Mapped[float] = mapped_column(
        Float, nullable=False, default=0.85,
        server_default=text("0.85"),
    )
    # -- CCIP character prototypes (#1317) ---------------------------------
    # The per-character reference set is precomputed + refreshed INCREMENTALLY
    # (services.ml.character_prototypes) instead of rebuilt on the request path.
    # ccip_ref_signature is the cheap GLOBAL gate — when it's unchanged the
    # refresh no-ops; ccip_prototype_cap bounds the reference vectors kept per
    # character so MATCH cost doesn't grow with a character's popularity.
    ccip_ref_signature: Mapped[str | None] = mapped_column(
        String(128), nullable=True
    )
    ccip_prototype_cap: Mapped[int] = mapped_column(
        Integer, nullable=False, default=64,
        server_default="64",
    )
    # -- Discord drop grouping (milestone 388) -----------------------------
    # FC authors a post out of a creator's variant drop. The predicate is three
    # axes ANDed together, and the time one does the real work: SIMILARITY
    # ALONE OVER-GROUPS. Any two pieces of the same character by the same
    # artist sit close in SigLIP space, so a cosine-only rule collapses a month
    # of one character into a single "post". What makes a variant set a set is
    # that it was dropped TOGETHER.
    discord_grouping_enabled: Mapped[bool] = mapped_column(
        # ON by default, matching the operator's standing opt-OUT preference for
        # automatic behaviour (2026-06-29, recorded on the head/ccip auto-apply
        # switches). Safe to default on because the act is reversible by one
        # DELETE: removing a synthetic post un-absorbs its members.
        Boolean, nullable=False, default=True,
        server_default="true",
    )
    # Cosine DISTANCE, not similarity — this is the units gallery_service's
    # `cosine_distance` already speaks, and converting at the query site is a
    # step to get backwards. Lower = stricter. 0.10 is deliberately TIGHT: the
    # two failure modes are not symmetric. Grouping too shy leaves a drop
    # scattered, which is visible and fixable by raising this; grouping too
    # greedy merges distinct pieces into a post that claims they belong
    # together, which is the failure that would discredit the feature.
    discord_group_max_distance: Mapped[float] = mapped_column(
        Float, nullable=False, default=0.10,
        server_default=text("0.10"),
    )
    # The gap that ENDS a drop, measured between CONSECUTIVE messages rather
    # than from the first — an artist trickling variants out over an evening is
    # one drop, and a window anchored on the first message would cut it in half
    # at an arbitrary point.
    discord_group_window_minutes: Mapped[float] = mapped_column(
        Float, nullable=False, default=60.0,
        server_default=text("60"),
    )
    # How long a synthetic post keeps accepting new members (#388 E3). This is
    # NOT the drop window above: the window cuts one sweep's messages into
    # drops, this decides how long a finished drop can still be REJOINED when a
    # creator adds variants days later. A week by default — long enough for the
    # "and here is the alt outfit" follow-up that motivated the feature, short
    # enough that a group does not still be open when the same character comes
    # round again months later and gets absorbed by mistake.
    #
    # Openness is DERIVED from this, not stored: a group is open if it grew (or
    # started) within this period. So lowering it closes old groups and raising
    # it reopens them, which is comprehensible and reversible — the alternative,
    # a stored closed_at, would need its own repair path to ever change.
    discord_group_close_after_hours: Mapped[float] = mapped_column(
        Float, nullable=False, default=168.0,
        server_default=text("168"),
    )
    # Anti-thrash (#388 E3). An updated post SHOULD be visible — that is the
    # point of keeping it open — but a group gaining one image a day must not
    # monopolise the feed. Growth smaller than this never moves the post, and
    # no group moves more than once per cooldown, so a drip-feed updates in
    # place while a real second wave resurfaces exactly once.
    discord_group_resurface_min_images: Mapped[int] = mapped_column(
        Integer, nullable=False, default=2,
        server_default="2",
    )
    discord_group_resurface_cooldown_hours: Mapped[float] = mapped_column(
        Float, nullable=False, default=24.0,
        server_default=text("24"),
    )
    updated_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )

    @classmethod
    async def load(cls, session) -> MLSettings:
        """The singleton settings row (id=1), via an async session. Mirrors
        ImportSettings.load — the shared singleton-loader pattern."""
        return (await session.execute(select(cls).where(cls.id == 1))).scalar_one()

    @classmethod
    def load_sync(cls, session) -> MLSettings:
        """The singleton settings row (id=1), via a sync session."""
        return session.execute(select(cls).where(cls.id == 1)).scalar_one()