feat: runtime feature flags, upload/download, RAW decoding

Adds Redis-backed feature flags for vision stages with admin UI toggles
and manual backfill trigger, photo upload and download routers with
frontend upload modal, and rawpy-based RAW decoding with JPEG fallback
for misnamed DNGs. Fixes pgvector serialization, is_trashed filter, and
naive-datetime bind in incremental duplicate regrouping; bumps Celery
time limits on regroup tasks beyond the 5-minute default.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

backend/app/routers/admin.py

@@ -18,6 +18,14 @@ from app.models.user import User
 from app.models.photos import Photo
 from app.models.folders import SourceRoot
 from app.config import settings
+from app.services.feature_flags import (
+    ALL_FLAGS,
+    snapshot as flags_snapshot,
+    set_flag,
+    reset_flag,
+    is_enabled,
+    FLAG_VISION_ENABLED,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -258,3 +266,141 @@ async def delete_user(
 
     logger.info(f"Admin '{admin.username}' deactivated user '{user.username}'")
     return {"status": "ok", "detail": f"User '{user.username}' deactivated"}
+
+
+# ---------------------------------------------------------------------------
+# AI / vision feature flags + manual triggers
+# ---------------------------------------------------------------------------
+
+class FeatureFlagUpdate(BaseModel):
+    """PATCH body for toggling a feature flag.
+
+    ``value`` sets an explicit override (true/false); omitting it clears
+    the override and reverts the flag to its YAML default.
+    """
+    value: Optional[bool] = None
+
+
+@router.get("/feature-flags")
+async def get_feature_flags(admin: User = Depends(require_admin)):
+    """Return every tunable feature flag with its current effective
+    value, YAML default, and whether an admin override is in effect."""
+    return {"flags": flags_snapshot()}
+
+
+@router.patch("/feature-flags/{flag_name}")
+async def update_feature_flag(
+    flag_name: str,
+    body: FeatureFlagUpdate,
+    admin: User = Depends(require_admin),
+):
+    """Set or clear an override for one flag. With ``value`` set, the
+    flag is pinned to that boolean; without it, the override is deleted
+    and the YAML default takes over again.
+
+    New value is observed by vision tasks on their next invocation —
+    there's no worker restart required.
+    """
+    if flag_name not in ALL_FLAGS:
+        raise HTTPException(status_code=404, detail=f"Unknown flag: {flag_name}")
+    try:
+        if body.value is None:
+            reset_flag(flag_name)
+            action = "cleared override"
+        else:
+            set_flag(flag_name, bool(body.value))
+            action = f"set to {body.value}"
+    except RuntimeError as e:
+        # Redis unreachable — surface as 503 so the UI doesn't think it
+        # succeeded silently.
+        raise HTTPException(status_code=503, detail=str(e))
+
+    logger.info(f"Admin '{admin.username}' {action} for flag '{flag_name}'")
+    return {"flags": flags_snapshot()}
+
+
+class BackfillVisionBody(BaseModel):
+    """POST body for triggering a vision backfill. ``task`` picks a
+    specific stage (``embed`` / ``ocr`` / ``detect`` / ``faces`` /
+    ``classify``); leaving it null runs every enabled stage. ``limit``
+    caps how many photos per stage are queued — useful for smoke-
+    testing a newly-enabled feature before committing a full run.
+    """
+    task: Optional[str] = None
+    limit: Optional[int] = None
+
+
+@router.post("/ai/backfill")
+async def trigger_ai_backfill(
+    body: BackfillVisionBody,
+    admin: User = Depends(require_admin),
+):
+    """Queue a vision backfill pass. Identical code path as the automatic
+    post-scan backfill — just triggered manually from the UI."""
+    if not is_enabled(FLAG_VISION_ENABLED):
+        raise HTTPException(
+            status_code=400,
+            detail="Vision is currently disabled; enable it before running a backfill.",
+        )
+    valid_tasks = {'embed', 'ocr', 'detect', 'faces', 'classify'}
+    if body.task is not None and body.task not in valid_tasks:
+        raise HTTPException(
+            status_code=400,
+            detail=f"task must be one of {sorted(valid_tasks)} or null",
+        )
+    if body.limit is not None and body.limit <= 0:
+        raise HTTPException(status_code=400, detail="limit must be positive")
+
+    # Import lazily so importing admin.py doesn't pull in the whole
+    # vision stack on startup (Celery task module loads numpy etc.).
+    from app.tasks.vision import backfill_vision
+
+    result = backfill_vision.apply_async(
+        kwargs={'task': body.task, 'limit': body.limit}
+    )
+    logger.info(
+        f"Admin '{admin.username}' queued vision backfill "
+        f"(task={body.task}, limit={body.limit}, celery_id={result.id})"
+    )
+    return {
+        "status": "queued",
+        "task_id": result.id,
+        "task": body.task,
+        "limit": body.limit,
+    }
+
+
+@router.post("/ai/recluster-faces")
+async def trigger_face_recluster(admin: User = Depends(require_admin)):
+    """Kick off face recluster. Normally auto-fires after a scan via a
+    debounced scheduler; this endpoint is for admins who want to force
+    a fresh clustering pass (e.g. after tweaking ``cluster_eps`` in
+    the YAML config)."""
+    if not is_enabled(FLAG_VISION_ENABLED):
+        raise HTTPException(
+            status_code=400,
+            detail="Vision is currently disabled; enable it before reclustering.",
+        )
+    from app.tasks.vision import recluster_faces
+
+    result = recluster_faces.apply_async()
+    logger.info(
+        f"Admin '{admin.username}' queued face recluster (celery_id={result.id})"
+    )
+    return {"status": "queued", "task_id": result.id}
+
+
+@router.post("/ai/rescan")
+async def trigger_full_rescan(admin: User = Depends(require_admin)):
+    """Dispatch the same scan_all_source_roots job the backend runs at
+    startup. Picks up any new files on disk and, through the
+    post-scan hook, queues a vision backfill for whatever still lacks
+    embeddings / OCR / etc.
+    """
+    from app.tasks.scan import scan_all_source_roots
+
+    result = scan_all_source_roots.apply_async()
+    logger.info(
+        f"Admin '{admin.username}' queued full rescan (celery_id={result.id})"
+    )
+    return {"status": "queued", "task_id": result.id}