selects 0.1.0__py3-none-any.whl

selects/db/__init__.py

@@ -0,0 +1,127 @@
+"""selects database session management."""
+from __future__ import annotations
+
+import threading
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Dict, Generator, Tuple
+
+from sqlalchemy import create_engine, event, inspect
+from sqlalchemy.engine import Engine
+from sqlalchemy.orm import Session, sessionmaker
+
+from selects.db.models import Base
+
+# Directory holding the packaged Alembic environment (env.py, versions/). Ships
+# inside the selects.db package so migrations are available wherever the
+# package is installed, without relying on an alembic.ini in the CWD.
+_MIGRATIONS_DIR = Path(__file__).parent / "migrations"
+
+# Cache of (engine, sessionmaker) keyed by resolved db path, so repeated
+# init_db() calls with the same path reuse a single Engine/pool instead of
+# creating a new one each time (important since init_db is invoked once per
+# ML pipeline stage, ~20 call sites, while the app also serves concurrent
+# requests + background indexing writes against the same SQLite file).
+_ENGINES: Dict[str, Tuple[Engine, "sessionmaker[Session]"]] = {}
+_ENGINES_LOCK = threading.Lock()
+
+
+def _make_url(db_path: Path) -> str:
+    return f"sqlite:///{db_path}"
+
+
+def _set_sqlite_pragmas(dbapi_connection, connection_record) -> None:  # noqa: ANN001
+    cursor = dbapi_connection.cursor()
+    try:
+        cursor.execute("PRAGMA journal_mode=WAL")
+        cursor.execute("PRAGMA synchronous=NORMAL")
+        cursor.execute("PRAGMA foreign_keys=ON")
+        cursor.execute("PRAGMA busy_timeout=5000")
+    finally:
+        cursor.close()
+
+
+def _alembic_config(connection):  # noqa: ANN001, ANN202
+    """Build an in-code Alembic Config pointing at the packaged migrations dir
+    and bound to an already-open *connection* (so migrations run on the same
+    engine + WAL pragmas as the rest of the app, no alembic.ini required)."""
+    from alembic.config import Config
+
+    cfg = Config()
+    cfg.set_main_option("script_location", str(_MIGRATIONS_DIR))
+    cfg.attributes["connection"] = connection
+    return cfg
+
+
+def _ensure_schema(engine: Engine) -> None:
+    """Bring *engine*'s database to the current schema via Alembic.
+
+    Three cases:
+      * Fresh DB (no tables): ``create_all`` then stamp head — fast path that
+        avoids replaying every migration on brand-new databases.
+      * Existing DB without an ``alembic_version`` table (every pre-Alembic
+        selects DB in the wild): stamp the baseline revision, then upgrade to
+        head. The follow-up revision that adds ``source`` to the photo_tags PK is
+        a guarded no-op when the column is already present, so this is safe for
+        DBs at any historical photo_tags shape.
+      * DB already under Alembic control: upgrade to head.
+    """
+    from alembic import command
+    from alembic.script import ScriptDirectory
+
+    table_names = set(inspect(engine).get_table_names())
+
+    if not table_names:
+        with engine.begin() as conn:
+            Base.metadata.create_all(conn)
+        with engine.connect() as conn:
+            command.stamp(_alembic_config(conn), "head")
+        return
+
+    if "alembic_version" not in table_names:
+        with engine.connect() as conn:
+            cfg = _alembic_config(conn)
+            baseline = ScriptDirectory.from_config(cfg).get_base()
+            command.stamp(cfg, baseline)
+        with engine.connect() as conn:
+            command.upgrade(_alembic_config(conn), "head")
+        return
+
+    with engine.connect() as conn:
+        command.upgrade(_alembic_config(conn), "head")
+
+
+def init_db(db_path: Path) -> sessionmaker[Session]:
+    """Create all tables and return a sessionmaker bound to *db_path*.
+
+    Idempotent: repeated calls with the same (resolved) path reuse the same
+    cached Engine/sessionmaker rather than creating a new Engine each time,
+    and ``create_all`` only runs once per path per process.
+    """
+    key = str(Path(db_path).resolve())
+    with _ENGINES_LOCK:
+        cached = _ENGINES.get(key)
+        if cached is not None:
+            return cached[1]
+
+        db_path.parent.mkdir(parents=True, exist_ok=True)
+        engine = create_engine(_make_url(db_path), echo=False)
+        event.listens_for(engine, "connect")(_set_sqlite_pragmas)
+        _ensure_schema(engine)
+        factory = sessionmaker(bind=engine, expire_on_commit=False)
+        _ENGINES[key] = (engine, factory)
+        return factory
+
+
+@contextmanager
+def session_scope(Session: sessionmaker[Session]) -> Generator[Session, None, None]:  # noqa: N803
+    """Provide a transactional session scope, committing on success."""
+    session = Session()
+    try:
+        yield session
+        session.commit()
+    except Exception:
+        session.rollback()
+        raise
+    finally:
+        session.close()

selects/db/migrations/env.py

@@ -0,0 +1,67 @@
+"""Alembic environment for selects.
+
+Designed to be driven programmatically via the Alembic Python API (see
+``selects.db._ensure_schema``) rather than an ``alembic.ini`` on disk. The
+target database URL is supplied through ``config`` — either as an already-open
+Connection in ``config.attributes['connection']`` or via the ``sqlalchemy.url``
+main option. ``render_as_batch=True`` is enabled so future column ALTERs work on
+SQLite (which has no native ALTER for most operations).
+"""
+from __future__ import annotations
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+from selects.db.models import Base
+
+config = context.config
+
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        render_as_batch=True,
+        compare_type=True,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def _run_with_connection(connection) -> None:
+    context.configure(
+        connection=connection,
+        target_metadata=target_metadata,
+        render_as_batch=True,
+        compare_type=True,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    # Reuse a caller-provided connection when available so migrations run on the
+    # same engine (and WAL pragmas) as the rest of the app.
+    connection = config.attributes.get("connection", None)
+    if connection is not None:
+        _run_with_connection(connection)
+        return
+
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    with connectable.connect() as conn:
+        _run_with_connection(conn)
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

selects/db/migrations/script.py.mako

@@ -0,0 +1,26 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

selects/db/migrations/versions/8ff743c44fc7_baseline_schema.py

@@ -0,0 +1,297 @@
+"""baseline schema
+
+Revision ID: 8ff743c44fc7
+Revises: 
+Create Date: 2026-07-05 22:10:30.688752
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '8ff743c44fc7'
+down_revision: Union[str, None] = None
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('geocode_cache',
+    sa.Column('lat_round', sa.Float(), nullable=False),
+    sa.Column('lon_round', sa.Float(), nullable=False),
+    sa.Column('payload', sa.Text(), nullable=True),
+    sa.Column('display_name', sa.Text(), nullable=True),
+    sa.Column('wikipedia_summary', sa.Text(), nullable=True),
+    sa.PrimaryKeyConstraint('lat_round', 'lon_round')
+    )
+    op.create_table('photos',
+    sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+    sa.Column('path', sa.String(length=4096), nullable=False),
+    sa.Column('sha256', sa.String(length=64), nullable=True),
+    sa.Column('mtime', sa.Float(), nullable=True),
+    sa.Column('size_bytes', sa.Integer(), nullable=True),
+    sa.Column('format', sa.String(length=16), nullable=True),
+    sa.Column('width', sa.Integer(), nullable=True),
+    sa.Column('height', sa.Integer(), nullable=True),
+    sa.Column('taken_at', sa.DateTime(), nullable=True),
+    sa.Column('gps_lat', sa.Float(), nullable=True),
+    sa.Column('gps_lon', sa.Float(), nullable=True),
+    sa.Column('camera', sa.String(length=256), nullable=True),
+    sa.Column('thumb_path', sa.String(length=4096), nullable=True),
+    sa.Column('preview_path', sa.String(length=4096), nullable=True),
+    sa.Column('indexed_at', sa.DateTime(), nullable=True),
+    sa.PrimaryKeyConstraint('id')
+    )
+    with op.batch_alter_table('photos', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_photos_path'), ['path'], unique=True)
+
+    op.create_table('stories',
+    sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+    sa.Column('day', sa.String(length=10), nullable=False),
+    sa.Column('title', sa.Text(), nullable=False),
+    sa.Column('photo_count', sa.Integer(), nullable=False),
+    sa.Column('created_at', sa.DateTime(), nullable=False),
+    sa.PrimaryKeyConstraint('id')
+    )
+    with op.batch_alter_table('stories', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_stories_day'), ['day'], unique=True)
+
+    op.create_table('videos',
+    sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+    sa.Column('path', sa.String(length=4096), nullable=False),
+    sa.Column('sha256', sa.String(length=64), nullable=True),
+    sa.Column('mtime', sa.Float(), nullable=True),
+    sa.Column('size_bytes', sa.Integer(), nullable=True),
+    sa.Column('format', sa.String(length=16), nullable=True),
+    sa.Column('width', sa.Integer(), nullable=True),
+    sa.Column('height', sa.Integer(), nullable=True),
+    sa.Column('duration_sec', sa.Float(), nullable=True),
+    sa.Column('taken_at', sa.DateTime(), nullable=True),
+    sa.Column('thumb_path', sa.String(length=4096), nullable=True),
+    sa.Column('preview_path', sa.String(length=4096), nullable=True),
+    sa.Column('indexed_at', sa.DateTime(), nullable=True),
+    sa.PrimaryKeyConstraint('id')
+    )
+    with op.batch_alter_table('videos', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_videos_path'), ['path'], unique=True)
+
+    op.create_table('aesthetic_scores',
+    sa.Column('photo_id', sa.Integer(), nullable=False),
+    sa.Column('nima_score', sa.Float(), nullable=True),
+    sa.Column('ap25_score', sa.Float(), nullable=True),
+    sa.Column('personal_score', sa.Float(), nullable=True),
+    sa.ForeignKeyConstraint(['photo_id'], ['photos.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('photo_id')
+    )
+    op.create_table('classical_scores',
+    sa.Column('photo_id', sa.Integer(), nullable=False),
+    sa.Column('blur', sa.Float(), nullable=True),
+    sa.Column('exposure', sa.Float(), nullable=True),
+    sa.Column('faces_count', sa.Integer(), nullable=True),
+    sa.Column('eyes_open_ratio', sa.Float(), nullable=True),
+    sa.Column('auto_reject', sa.Boolean(), nullable=False),
+    sa.Column('reject_reason', sa.Text(), nullable=True),
+    sa.ForeignKeyConstraint(['photo_id'], ['photos.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('photo_id')
+    )
+    op.create_table('embeddings',
+    sa.Column('photo_id', sa.Integer(), nullable=False),
+    sa.Column('siglip', sa.LargeBinary(), nullable=False),
+    sa.Column('aesthetic_iqa', sa.Float(), nullable=True),
+    sa.ForeignKeyConstraint(['photo_id'], ['photos.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('photo_id')
+    )
+    op.create_table('face_embeddings',
+    sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+    sa.Column('photo_id', sa.Integer(), nullable=False),
+    sa.Column('face_index', sa.Integer(), nullable=False),
+    sa.Column('embedding', sa.LargeBinary(), nullable=False),
+    sa.Column('bbox_x', sa.Integer(), nullable=False),
+    sa.Column('bbox_y', sa.Integer(), nullable=False),
+    sa.Column('bbox_w', sa.Integer(), nullable=False),
+    sa.Column('bbox_h', sa.Integer(), nullable=False),
+    sa.Column('confidence', sa.Float(), nullable=False),
+    sa.ForeignKeyConstraint(['photo_id'], ['photos.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id')
+    )
+    with op.batch_alter_table('face_embeddings', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_face_embeddings_photo_id'), ['photo_id'], unique=False)
+
+    op.create_table('moments',
+    sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+    sa.Column('primary_photo_id', sa.Integer(), nullable=False),
+    sa.Column('started_at', sa.DateTime(), nullable=False),
+    sa.Column('ended_at', sa.DateTime(), nullable=False),
+    sa.Column('size', sa.Integer(), nullable=False),
+    sa.ForeignKeyConstraint(['primary_photo_id'], ['photos.id'], ),
+    sa.PrimaryKeyConstraint('id')
+    )
+    with op.batch_alter_table('moments', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_moments_primary_photo_id'), ['primary_photo_id'], unique=False)
+
+    op.create_table('photo_categories',
+    sa.Column('photo_id', sa.Integer(), nullable=False),
+    sa.Column('landscape_sim', sa.Float(), nullable=True),
+    sa.Column('portrait_sim', sa.Float(), nullable=True),
+    sa.Column('object_sim', sa.Float(), nullable=True),
+    sa.Column('primary_category', sa.String(length=16), nullable=True),
+    sa.ForeignKeyConstraint(['photo_id'], ['photos.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('photo_id')
+    )
+    op.create_table('photo_ratings',
+    sa.Column('photo_id', sa.Integer(), nullable=False),
+    sa.Column('rating', sa.Integer(), nullable=False),
+    sa.Column('rated_at', sa.DateTime(), nullable=False),
+    sa.ForeignKeyConstraint(['photo_id'], ['photos.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('photo_id')
+    )
+    # NOTE: photo_tags is intentionally created here in its PRE-source shape:
+    # PK (photo_id, tag), no ``source`` column. The follow-up revision
+    # ('add source to photo_tags PK') ports the historical hand-rolled migration
+    # (_migrate_add_source_column) that adds the column and rebuilds the PK. This
+    # lets pre-source databases in the wild stamp this baseline honestly and then
+    # upgrade to head, while the follow-up revision is a guarded no-op for DBs
+    # that already have the source column.
+    op.create_table('photo_tags',
+    sa.Column('photo_id', sa.Integer(), nullable=False),
+    sa.Column('tag', sa.String(length=128), nullable=False),
+    sa.Column('score', sa.Float(), nullable=False),
+    sa.ForeignKeyConstraint(['photo_id'], ['photos.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('photo_id', 'tag')
+    )
+    with op.batch_alter_table('photo_tags', schema=None) as batch_op:
+        batch_op.create_index('ix_photo_tags_tag', ['tag'], unique=False)
+
+    op.create_table('pipeline_states',
+    sa.Column('photo_id', sa.Integer(), nullable=False),
+    sa.Column('classical_done', sa.Boolean(), nullable=False),
+    sa.Column('embedding_done', sa.Boolean(), nullable=False),
+    sa.Column('vl_done', sa.Boolean(), nullable=False),
+    sa.Column('ordering_done', sa.Boolean(), nullable=False),
+    sa.Column('error', sa.Text(), nullable=True),
+    sa.ForeignKeyConstraint(['photo_id'], ['photos.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('photo_id')
+    )
+    with op.batch_alter_table('pipeline_states', schema=None) as batch_op:
+        batch_op.create_index('ix_pipeline_states_work', ['classical_done', 'embedding_done'], unique=False)
+
+    op.create_table('story_items',
+    sa.Column('story_id', sa.Integer(), nullable=False),
+    sa.Column('rank', sa.Integer(), nullable=False),
+    sa.Column('photo_id', sa.Integer(), nullable=False),
+    sa.Column('scene_label', sa.String(length=64), nullable=True),
+    sa.Column('scene_rank', sa.Integer(), nullable=True),
+    sa.ForeignKeyConstraint(['photo_id'], ['photos.id'], ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['story_id'], ['stories.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('story_id', 'rank')
+    )
+    op.create_table('swipes',
+    sa.Column('photo_id', sa.Integer(), nullable=False),
+    sa.Column('decision', sa.Text(), nullable=False),
+    sa.Column('swiped_at', sa.DateTime(), nullable=False),
+    sa.ForeignKeyConstraint(['photo_id'], ['photos.id'], ),
+    sa.PrimaryKeyConstraint('photo_id')
+    )
+    op.create_table('visits',
+    sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+    sa.Column('story_id', sa.Integer(), nullable=False),
+    sa.Column('rank', sa.Integer(), nullable=False),
+    sa.Column('name', sa.Text(), nullable=False),
+    sa.Column('summary', sa.Text(), nullable=True),
+    sa.Column('lat', sa.Float(), nullable=False),
+    sa.Column('lon', sa.Float(), nullable=False),
+    sa.Column('elevation_m', sa.Integer(), nullable=True),
+    sa.Column('arrived_at', sa.DateTime(), nullable=False),
+    sa.Column('departed_at', sa.DateTime(), nullable=False),
+    sa.Column('photo_count', sa.Integer(), nullable=False),
+    sa.Column('cover_photo_id', sa.Integer(), nullable=True),
+    sa.ForeignKeyConstraint(['cover_photo_id'], ['photos.id'], ),
+    sa.ForeignKeyConstraint(['story_id'], ['stories.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id')
+    )
+    with op.batch_alter_table('visits', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_visits_story_id'), ['story_id'], unique=False)
+        batch_op.create_index('ix_visits_story_rank', ['story_id', 'rank'], unique=False)
+
+    op.create_table('moment_members',
+    sa.Column('moment_id', sa.Integer(), nullable=False),
+    sa.Column('photo_id', sa.Integer(), nullable=False),
+    sa.Column('rank', sa.Integer(), nullable=False),
+    sa.ForeignKeyConstraint(['moment_id'], ['moments.id'], ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['photo_id'], ['photos.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('moment_id', 'photo_id')
+    )
+    op.create_table('persons',
+    sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+    sa.Column('label', sa.Text(), nullable=True),
+    sa.Column('cover_face_embedding_id', sa.Integer(), nullable=True),
+    sa.Column('photo_count', sa.Integer(), nullable=False),
+    sa.Column('centroid', sa.LargeBinary(), nullable=True),
+    sa.Column('created_at', sa.DateTime(), nullable=False),
+    sa.ForeignKeyConstraint(['cover_face_embedding_id'], ['face_embeddings.id'], ),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_table('photo_persons',
+    sa.Column('photo_id', sa.Integer(), nullable=False),
+    sa.Column('person_id', sa.Integer(), nullable=False),
+    sa.Column('face_embedding_id', sa.Integer(), nullable=False),
+    sa.Column('confidence', sa.Float(), nullable=False),
+    sa.ForeignKeyConstraint(['face_embedding_id'], ['face_embeddings.id'], ),
+    sa.ForeignKeyConstraint(['person_id'], ['persons.id'], ),
+    sa.ForeignKeyConstraint(['photo_id'], ['photos.id'], ),
+    sa.PrimaryKeyConstraint('photo_id', 'person_id')
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_table('photo_persons')
+    op.drop_table('persons')
+    op.drop_table('moment_members')
+    with op.batch_alter_table('visits', schema=None) as batch_op:
+        batch_op.drop_index('ix_visits_story_rank')
+        batch_op.drop_index(batch_op.f('ix_visits_story_id'))
+
+    op.drop_table('visits')
+    op.drop_table('swipes')
+    op.drop_table('story_items')
+    with op.batch_alter_table('pipeline_states', schema=None) as batch_op:
+        batch_op.drop_index('ix_pipeline_states_work')
+
+    op.drop_table('pipeline_states')
+    with op.batch_alter_table('photo_tags', schema=None) as batch_op:
+        batch_op.drop_index('ix_photo_tags_tag')
+
+    op.drop_table('photo_tags')
+    op.drop_table('photo_ratings')
+    op.drop_table('photo_categories')
+    with op.batch_alter_table('moments', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_moments_primary_photo_id'))
+
+    op.drop_table('moments')
+    with op.batch_alter_table('face_embeddings', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_face_embeddings_photo_id'))
+
+    op.drop_table('face_embeddings')
+    op.drop_table('embeddings')
+    op.drop_table('classical_scores')
+    op.drop_table('aesthetic_scores')
+    with op.batch_alter_table('videos', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_videos_path'))
+
+    op.drop_table('videos')
+    with op.batch_alter_table('stories', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_stories_day'))
+
+    op.drop_table('stories')
+    with op.batch_alter_table('photos', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_photos_path'))
+
+    op.drop_table('photos')
+    op.drop_table('geocode_cache')
+    # ### end Alembic commands ###

selects/db/migrations/versions/a1b2c3d4e5f6_add_source_to_photo_tags_pk.py

@@ -0,0 +1,105 @@
+"""add source column to photo_tags and rebuild PK
+
+Ports the historical hand-rolled ``_migrate_add_source_column`` (formerly in
+selects/ml/ram_tags.py). Adds the ``source`` column to ``photo_tags`` and
+rebuilds the table so the primary key is ``(photo_id, tag, source)`` — allowing
+the same tag name from different sources (RAM++, posting/lookback clusters,
+legacy NULL-source SigLIP tags).
+
+This revision is a **guarded no-op** when ``source`` is already part of the
+primary key, so it is safe to run against databases that were either created by
+``create_all`` at a schema point that already had the source-in-PK shape, or
+already upgraded by the old hand-rolled migration.
+
+Revision ID: a1b2c3d4e5f6
+Revises: 8ff743c44fc7
+Create Date: 2026-07-05 22:15:00.000000
+
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "a1b2c3d4e5f6"
+down_revision: Union[str, None] = "8ff743c44fc7"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    bind = op.get_bind()
+    insp = sa.inspect(bind)
+
+    if "photo_tags" not in insp.get_table_names():
+        return
+
+    pk_cols = insp.get_pk_constraint("photo_tags").get("constrained_columns") or []
+    if "source" in pk_cols:
+        # Already migrated (source is part of the PK) — nothing to do.
+        return
+
+    existing_cols = {c["name"] for c in insp.get_columns("photo_tags")}
+
+    # Raw-SQL rebuild (mirrors the historical hand-rolled migration). We do not
+    # toggle PRAGMA foreign_keys here because Alembic runs inside a transaction
+    # (where the pragma is a no-op) and photo_tags is not referenced by any other
+    # table's foreign key, so recreating it is safe.
+    op.execute(
+        """
+        CREATE TABLE photo_tags_new (
+            photo_id INTEGER NOT NULL,
+            tag VARCHAR(128) NOT NULL,
+            score FLOAT NOT NULL,
+            source VARCHAR(16),
+            PRIMARY KEY (photo_id, tag, source),
+            FOREIGN KEY(photo_id) REFERENCES photos (id) ON DELETE CASCADE
+        )
+        """
+    )
+    if "source" in existing_cols:
+        op.execute(
+            "INSERT OR IGNORE INTO photo_tags_new (photo_id, tag, score, source) "
+            "SELECT photo_id, tag, score, source FROM photo_tags"
+        )
+    else:
+        op.execute(
+            "INSERT OR IGNORE INTO photo_tags_new (photo_id, tag, score, source) "
+            "SELECT photo_id, tag, score, NULL FROM photo_tags"
+        )
+    op.execute("DROP TABLE photo_tags")
+    op.execute("ALTER TABLE photo_tags_new RENAME TO photo_tags")
+    op.execute("CREATE INDEX IF NOT EXISTS ix_photo_tags_tag ON photo_tags (tag)")
+    op.execute("CREATE INDEX IF NOT EXISTS ix_photo_tags_source ON photo_tags (source)")
+
+
+def downgrade() -> None:
+    bind = op.get_bind()
+    insp = sa.inspect(bind)
+
+    if "photo_tags" not in insp.get_table_names():
+        return
+
+    pk_cols = insp.get_pk_constraint("photo_tags").get("constrained_columns") or []
+    if "source" not in pk_cols:
+        return
+
+    op.execute(
+        """
+        CREATE TABLE photo_tags_new (
+            photo_id INTEGER NOT NULL,
+            tag VARCHAR(128) NOT NULL,
+            score FLOAT NOT NULL,
+            PRIMARY KEY (photo_id, tag),
+            FOREIGN KEY(photo_id) REFERENCES photos (id) ON DELETE CASCADE
+        )
+        """
+    )
+    op.execute(
+        "INSERT OR IGNORE INTO photo_tags_new (photo_id, tag, score) "
+        "SELECT photo_id, tag, score FROM photo_tags"
+    )
+    op.execute("DROP TABLE photo_tags")
+    op.execute("ALTER TABLE photo_tags_new RENAME TO photo_tags")
+    op.execute("CREATE INDEX IF NOT EXISTS ix_photo_tags_tag ON photo_tags (tag)")