"""tag_head + head_training_run: production heads that learn from tags (#114)

The eval (#1130) proved the frozen-embedding + trained-head spine; this lands its
production form. tag_head stores one logistic-regression head per concept (the
new suggestion source, replacing Camie + centroid); head_training_run tracks the
batch that (re)trains them. Adds two head-training tunables to ml_settings.

Revision ID: 0058
Revises: 0057
Create Date: 2026-06-28
"""
from typing import Sequence, Union

import sqlalchemy as sa
from alembic import op
from pgvector.sqlalchemy import Vector
from sqlalchemy.dialects.postgresql import JSONB

revision: str = "0058"
down_revision: Union[str, None] = "0057"
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None

_HEAD_DIM = 1152


def upgrade() -> None:
    op.create_table(
        "tag_head",
        sa.Column(
            "tag_id", sa.Integer(),
            sa.ForeignKey("tag.id", ondelete="CASCADE"), primary_key=True,
        ),
        sa.Column("embedding_version", sa.String(length=128), nullable=False),
        sa.Column("weights", Vector(_HEAD_DIM), nullable=False),
        sa.Column("bias", sa.Float(), nullable=False),
        sa.Column("suggest_threshold", sa.Float(), nullable=False),
        sa.Column("auto_apply_threshold", sa.Float(), nullable=True),
        sa.Column("n_pos", sa.Integer(), nullable=False),
        sa.Column("n_neg", sa.Integer(), nullable=False),
        sa.Column("ap", sa.Float(), nullable=False),
        sa.Column("precision_cv", sa.Float(), nullable=False),
        sa.Column("recall", sa.Float(), nullable=False),
        sa.Column(
            "trained_at", sa.DateTime(timezone=True), nullable=False,
            server_default=sa.func.now(),
        ),
        sa.Column("metrics", JSONB(), nullable=True),
    )

    op.create_table(
        "head_training_run",
        sa.Column("id", sa.Integer(), primary_key=True),
        sa.Column("params", JSONB(), nullable=False),
        sa.Column(
            "status", sa.String(length=16), nullable=False,
            server_default="running",
        ),
        sa.Column(
            "started_at", sa.DateTime(timezone=True), nullable=False,
            server_default=sa.func.now(),
        ),
        sa.Column("finished_at", sa.DateTime(timezone=True), nullable=True),
        sa.Column("n_trained", sa.Integer(), nullable=True),
        sa.Column("n_skipped", sa.Integer(), nullable=True),
        sa.Column("error", sa.Text(), nullable=True),
        sa.Column("last_progress_at", sa.DateTime(timezone=True), nullable=True),
    )
    op.create_index(
        "ix_head_training_run_status", "head_training_run", ["status"],
    )

    # Head-training tunables on the ml_settings singleton.
    op.add_column(
        "ml_settings",
        sa.Column(
            "head_min_positives", sa.Integer(), nullable=False,
            server_default="8",
        ),
    )
    op.add_column(
        "ml_settings",
        sa.Column(
            "head_auto_apply_precision", sa.Float(), nullable=False,
            server_default="0.97",
        ),
    )


def downgrade() -> None:
    op.drop_column("ml_settings", "head_auto_apply_precision")
    op.drop_column("ml_settings", "head_min_positives")
    op.drop_index("ix_head_training_run_status", table_name="head_training_run")
    op.drop_table("head_training_run")
    op.drop_table("tag_head")
