feat: add label context for enriched admin UI (#392)

* feat: add label context for enriched admin UI

adds track metadata (title, artist, matches) alongside copyright labels
so the admin UI can show meaningful info for reviewing flags.

changes:
- add label_context table to moderation service DB
- update /emit-label to accept optional context payload
- add /admin/context endpoint for backfilling context
- update admin UI with card-based layout showing track info and matches
- update backend to send context when emitting labels
- add backfill scripts for labels and context

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

* fix: use --with-editable instead of sys.path hack

properly install backend package via uv's --with-editable flag
instead of manipulating sys.path

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

* fix: update test to expect full label context parameters

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

---------

Co-authored-by: Claude <[e-mail]>

backend/src/backend/_internal/moderation.py

···
         track_id: database ID of the track
         result: scan result from moderation service
     """
+    from sqlalchemy.orm import joinedload
+
     async with db_session() as db:
         is_flagged = result.get("is_flagged", False)
 
···
 
         # emit ATProto label if flagged
         if is_flagged:
-            track = await db.scalar(select(Track).where(Track.id == track_id))
+            track = await db.scalar(
+                select(Track)
+                .options(joinedload(Track.artist))
+                .where(Track.id == track_id)
+            )
             if track and track.atproto_record_uri:
                 await _emit_copyright_label(
                     uri=track.atproto_record_uri,
                     cid=track.atproto_record_cid,
+                    track_title=track.title,
+                    artist_handle=track.artist.handle if track.artist else None,
+                    artist_did=track.artist_did,
+                    highest_score=scan.highest_score,
+                    matches=scan.matches,
                 )
 
 
-async def _emit_copyright_label(uri: str, cid: str | None) -> None:
+async def _emit_copyright_label(
+    uri: str,
+    cid: str | None,
+    track_title: str | None = None,
+    artist_handle: str | None = None,
+    artist_did: str | None = None,
+    highest_score: float | None = None,
+    matches: list[dict[str, Any]] | None = None,
+) -> None:
     """emit a copyright-violation label to the ATProto labeler service.
 
     this is fire-and-forget - failures are logged but don't affect the scan result.
···
     args:
         uri: AT URI of the track record
         cid: optional CID of the record
+        track_title: title of the track (for admin UI context)
+        artist_handle: handle of the artist (for admin UI context)
+        artist_did: DID of the artist (for admin UI context)
+        highest_score: highest match score (for admin UI context)
+        matches: list of copyright matches (for admin UI context)
     """
     try:
+        # build context for admin UI display
+        context: dict[str, Any] | None = None
+        if track_title or artist_handle or matches:
+            context = {
+                "track_title": track_title,
+                "artist_handle": artist_handle,
+                "artist_did": artist_did,
+                "highest_score": highest_score,
+                "matches": matches,
+            }
+
+        payload: dict[str, Any] = {
+            "uri": uri,
+            "val": "copyright-violation",
+            "cid": cid,
+        }
+        if context:
+            payload["context"] = context
+
         async with httpx.AsyncClient(timeout=httpx.Timeout(10.0)) as client:
             response = await client.post(
                 f"{settings.moderation.labeler_url}/emit-label",
-                json={
-                    "uri": uri,
-                    "val": "copyright-violation",
-                    "cid": cid,
-                },
+                json=payload,
                 headers={"X-Moderation-Key": settings.moderation.auth_token},
             )
             response.raise_for_status()

backend/tests/test_moderation.py

···
     ) as mock_emit:
         await _store_scan_result(track.id, mock_moderation_response)
 
-        # verify label emission was called
+        # verify label emission was called with full context
         mock_emit.assert_called_once_with(
             uri="at://did:plc:labelertest/fm.plyr.track/abc123",
             cid="bafyreiabc123",
+            track_title="Labeler Test Track",
+            artist_handle="labeler.bsky.social",
+            artist_did="did:plc:labelertest",
+            highest_score=85,
+            matches=[
+                {
+                    "artist": "Test Artist",
+                    "title": "Test Song",
+                    "score": 85,
+                    "isrc": "USRC12345678",
+                }
+            ],
         )
 
 

moderation/src/admin.rs

···
 use axum::{extract::State, response::Html, Json};
 use serde::{Deserialize, Serialize};
 
+use crate::db::LabelContext;
 use crate::state::{AppError, AppState};
 
 /// A flagged track pending review.
···
     pub created_at: String,
     /// If there's a negation label for this URI+val, it's been resolved.
     pub resolved: bool,
+    /// Optional context about the track (title, artist, matches).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub context: Option<LabelContext>,
 }
 
 /// Response for listing flagged tracks.
···
     pub message: String,
 }
 
+/// Request to store label context (for backfill).
+#[derive(Debug, Deserialize)]
+pub struct StoreContextRequest {
+    pub uri: String,
+    pub context: ContextPayload,
+}
+
+/// Context payload for storage.
+#[derive(Debug, Deserialize)]
+pub struct ContextPayload {
+    pub track_title: Option<String>,
+    pub artist_handle: Option<String>,
+    pub artist_did: Option<String>,
+    pub highest_score: Option<f64>,
+    pub matches: Option<Vec<crate::db::CopyrightMatch>>,
+}
+
+/// Response after storing context.
+#[derive(Debug, Serialize)]
+pub struct StoreContextResponse {
+    pub message: String,
+}
+
 /// List all flagged tracks (copyright-violation labels without negations).
 pub async fn list_flagged(
     State(state): State<AppState>,
···
     }))
 }
 
+/// Store context for a label (for backfill without re-emitting labels).
+pub async fn store_context(
+    State(state): State<AppState>,
+    Json(request): Json<StoreContextRequest>,
+) -> Result<Json<StoreContextResponse>, AppError> {
+    let db = state.db.as_ref().ok_or(AppError::LabelerNotConfigured)?;
+
+    tracing::info!(uri = %request.uri, "storing label context");
+
+    let label_ctx = LabelContext {
+        track_title: request.context.track_title,
+        artist_handle: request.context.artist_handle,
+        artist_did: request.context.artist_did,
+        highest_score: request.context.highest_score,
+        matches: request.context.matches,
+    };
+
+    db.store_context(&request.uri, &label_ctx).await?;
+
+    Ok(Json(StoreContextResponse {
+        message: format!("context stored for {}", request.uri),
+    }))
+}
+
 /// Serve the admin UI HTML.
 pub async fn admin_ui() -> Html<&'static str> {
     Html(ADMIN_HTML)
···
             font-family: system-ui, -apple-system, sans-serif;
             background: #0a0a0a;
             color: #e5e5e5;
-            max-width: 900px;
+            max-width: 1100px;
             margin: 0 auto;
             padding: 20px;
             line-height: 1.6;
···
         }
         .status.error { display: block; background: rgba(239, 68, 68, 0.2); color: #ef4444; }
         .status.success { display: block; background: rgba(34, 197, 94, 0.2); color: #22c55e; }
-        table {
-            width: 100%;
-            border-collapse: collapse;
+        .flags-list {
+            display: flex;
+            flex-direction: column;
+            gap: 12px;
         }
-        th, td {
-            text-align: left;
-            padding: 12px;
-            border-bottom: 1px solid #222;
+        .flag-card {
+            background: #111;
+            border: 1px solid #222;
+            border-radius: 8px;
+            padding: 16px;
         }
-        th { color: #888; font-weight: 500; }
-        .uri {
+        .flag-card.resolved { opacity: 0.6; }
+        .flag-header {
+            display: flex;
+            justify-content: space-between;
+            align-items: flex-start;
+            margin-bottom: 12px;
+        }
+        .track-info h3 {
+            margin: 0 0 4px 0;
+            color: #fff;
+            font-size: 1.1em;
+        }
+        .track-info .artist {
+            color: #888;
+            font-size: 0.9em;
+        }
+        .track-info .uri {
             font-family: monospace;
-            font-size: 0.85em;
+            font-size: 0.75em;
+            color: #666;
             word-break: break-all;
+            margin-top: 4px;
+        }
+        .flag-badges {
+            display: flex;
+            gap: 8px;
+            align-items: center;
         }
         .badge {
             display: inline-block;
···
         }
         .badge.pending { background: rgba(234, 179, 8, 0.2); color: #eab308; }
         .badge.resolved { background: rgba(34, 197, 94, 0.2); color: #22c55e; }
+        .badge.score { background: rgba(239, 68, 68, 0.2); color: #ef4444; }
+        .matches {
+            background: #0a0a0a;
+            border-radius: 4px;
+            padding: 12px;
+            margin-top: 12px;
+        }
+        .matches h4 {
+            margin: 0 0 8px 0;
+            color: #888;
+            font-size: 0.85em;
+            font-weight: 500;
+        }
+        .match-item {
+            display: flex;
+            justify-content: space-between;
+            padding: 6px 0;
+            border-bottom: 1px solid #1a1a1a;
+            font-size: 0.9em;
+        }
+        .match-item:last-child { border-bottom: none; }
+        .match-item .title { color: #e5e5e5; }
+        .match-item .artist { color: #888; }
+        .match-item .score {
+            color: #ef4444;
+            font-family: monospace;
+        }
+        .flag-actions {
+            display: flex;
+            justify-content: flex-end;
+            margin-top: 12px;
+            padding-top: 12px;
+            border-top: 1px solid #222;
+        }
         .resolve-btn {
             background: #f59e0b;
             color: #000;
             border: none;
-            padding: 6px 12px;
+            padding: 8px 16px;
             border-radius: 4px;
             cursor: pointer;
             font-size: 0.85em;
+            font-weight: 500;
         }
         .resolve-btn:hover { background: #d97706; }
-        .resolve-btn:disabled { background: #444; color: #888; cursor: not-allowed; }
+        .resolve-btn:disabled { background: #333; color: #666; cursor: not-allowed; }
         .empty { color: #666; text-align: center; padding: 40px; }
-        .loading { color: #888; }
+        .loading { color: #888; text-align: center; padding: 40px; }
         .refresh-btn {
             background: #333;
             color: #fff;
···
             margin-bottom: 16px;
         }
         .header-row h2 { margin: 0; }
+        .no-context { color: #666; font-style: italic; font-size: 0.9em; }
     </style>
 </head>
 <body>
···
             <h2>flagged tracks</h2>
             <button class="refresh-btn" onclick="loadFlags()">refresh</button>
         </div>
-        <table>
-            <thead>
-                <tr>
-                    <th>seq</th>
-                    <th>uri</th>
-                    <th>label</th>
-                    <th>status</th>
-                    <th>action</th>
-                </tr>
-            </thead>
-            <tbody id="flags-table">
-                <tr><td colspan="5" class="loading">loading...</td></tr>
-            </tbody>
-        </table>
+        <div id="flags-list" class="flags-list">
+            <div class="loading">loading...</div>
+        </div>
     </div>
 
     <script>
···
         }
 
         async function loadFlags() {
-            const tbody = document.getElementById('flags-table');
-            tbody.innerHTML = '<tr><td colspan="5" class="loading">loading...</td></tr>';
+            const container = document.getElementById('flags-list');
+            container.innerHTML = '<div class="loading">loading...</div>';
 
             try {
                 const res = await fetch('/admin/flags', {
···
                 const data = await res.json();
 
                 if (data.tracks.length === 0) {
-                    tbody.innerHTML = '<tr><td colspan="5" class="empty">no flagged tracks</td></tr>';
+                    container.innerHTML = '<div class="empty">no flagged tracks</div>';
                     return;
                 }
 
-                tbody.innerHTML = data.tracks.map(track => `
-                    <tr>
-                        <td>${track.seq}</td>
-                        <td class="uri">${escapeHtml(track.uri)}</td>
-                        <td><span class="badge pending">${escapeHtml(track.val)}</span></td>
-                        <td><span class="badge ${track.resolved ? 'resolved' : 'pending'}">${track.resolved ? 'resolved' : 'pending'}</span></td>
-                        <td>
-                            <button class="resolve-btn"
-                                    onclick="resolveFlag('${escapeHtml(track.uri)}', '${escapeHtml(track.val)}')"
-                                    ${track.resolved ? 'disabled' : ''}>
-                                ${track.resolved ? 'resolved' : 'mark false positive'}
-                            </button>
-                        </td>
-                    </tr>
-                `).join('');
+                container.innerHTML = data.tracks.map(track => {
+                    const ctx = track.context || {};
+                    const hasContext = ctx.track_title || ctx.artist_handle;
+                    const matches = ctx.matches || [];
+
+                    return `
+                        <div class="flag-card ${track.resolved ? 'resolved' : ''}">
+                            <div class="flag-header">
+                                <div class="track-info">
+                                    ${hasContext ? `
+                                        <h3>${escapeHtml(ctx.track_title || 'unknown track')}</h3>
+                                        <div class="artist">by @${escapeHtml(ctx.artist_handle || 'unknown')}</div>
+                                    ` : `
+                                        <div class="no-context">no track info available</div>
+                                    `}
+                                    <div class="uri">${escapeHtml(track.uri)}</div>
+                                </div>
+                                <div class="flag-badges">
+                                    ${ctx.highest_score ? `<span class="badge score">${(ctx.highest_score * 100).toFixed(0)}% match</span>` : ''}
+                                    <span class="badge ${track.resolved ? 'resolved' : 'pending'}">${track.resolved ? 'resolved' : 'pending'}</span>
+                                </div>
+                            </div>
+                            ${matches.length > 0 ? `
+                                <div class="matches">
+                                    <h4>potential matches</h4>
+                                    ${matches.slice(0, 3).map(m => `
+                                        <div class="match-item">
+                                            <span><span class="title">${escapeHtml(m.title)}</span> <span class="artist">by ${escapeHtml(m.artist)}</span></span>
+                                            <span class="score">${(m.score * 100).toFixed(0)}%</span>
+                                        </div>
+                                    `).join('')}
+                                </div>
+                            ` : ''}
+                            <div class="flag-actions">
+                                <button class="resolve-btn"
+                                        onclick="resolveFlag('${escapeHtml(track.uri)}', '${escapeHtml(track.val)}')"
+                                        ${track.resolved ? 'disabled' : ''}>
+                                    ${track.resolved ? 'resolved' : 'mark false positive'}
+                                </button>
+                            </div>
+                        </div>
+                    `;
+                }).join('');
 
             } catch (err) {
-                tbody.innerHTML = `<tr><td colspan="5" class="empty">error: ${err.message}</td></tr>`;
+                container.innerHTML = `<div class="empty">error: ${err.message}</div>`;
             }
         }
 
···
         }
 
         function escapeHtml(str) {
+            if (!str) return '';
             return str.replace(/&/g, '&amp;')
                       .replace(/</g, '&lt;')
                       .replace(/>/g, '&gt;')

moderation/src/db.rs

···
 //! Database operations for the labeler.
 
 use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
 use sqlx::{postgres::PgPoolOptions, PgPool};
 
 use crate::admin::FlaggedTrack;
 use crate::labels::Label;
+
+/// Type alias for context row from database query.
+type ContextRow = (
+    Option<String>,
+    Option<String>,
+    Option<String>,
+    Option<f64>,
+    Option<serde_json::Value>,
+);
+
+/// Type alias for flagged track row from database query.
+type FlaggedRow = (
+    i64,
+    String,
+    String,
+    DateTime<Utc>,
+    Option<String>,
+    Option<String>,
+    Option<String>,
+    Option<f64>,
+    Option<serde_json::Value>,
+);
+
+/// Copyright match info stored alongside labels.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CopyrightMatch {
+    pub title: String,
+    pub artist: String,
+    pub score: f64,
+}
+
+/// Context stored alongside a label for display in admin UI.
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct LabelContext {
+    pub track_title: Option<String>,
+    pub artist_handle: Option<String>,
+    pub artist_did: Option<String>,
+    pub highest_score: Option<f64>,
+    pub matches: Option<Vec<CopyrightMatch>>,
+}
 
 /// Database connection pool and operations.
 #[derive(Clone)]
···
             .execute(&self.pool)
             .await?;
 
+        // Label context table for admin UI display
+        sqlx::query(
+            r#"
+            CREATE TABLE IF NOT EXISTS label_context (
+                id BIGSERIAL PRIMARY KEY,
+                uri TEXT NOT NULL UNIQUE,
+                track_title TEXT,
+                artist_handle TEXT,
+                artist_did TEXT,
+                highest_score DOUBLE PRECISION,
+                matches JSONB,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            "#,
+        )
+        .execute(&self.pool)
+        .await?;
+
+        sqlx::query("CREATE INDEX IF NOT EXISTS idx_label_context_uri ON label_context(uri)")
+            .execute(&self.pool)
+            .await?;
+
         Ok(())
     }
 
+    /// Store or update label context for a URI.
+    pub async fn store_context(&self, uri: &str, context: &LabelContext) -> Result<(), sqlx::Error> {
+        let matches_json = context
+            .matches
+            .as_ref()
+            .map(|m| serde_json::to_value(m).unwrap_or_default());
+
+        sqlx::query(
+            r#"
+            INSERT INTO label_context (uri, track_title, artist_handle, artist_did, highest_score, matches)
+            VALUES ($1, $2, $3, $4, $5, $6)
+            ON CONFLICT (uri) DO UPDATE SET
+                track_title = EXCLUDED.track_title,
+                artist_handle = EXCLUDED.artist_handle,
+                artist_did = EXCLUDED.artist_did,
+                highest_score = EXCLUDED.highest_score,
+                matches = EXCLUDED.matches
+            "#,
+        )
+        .bind(uri)
+        .bind(&context.track_title)
+        .bind(&context.artist_handle)
+        .bind(&context.artist_did)
+        .bind(context.highest_score)
+        .bind(matches_json)
+        .execute(&self.pool)
+        .await?;
+
+        Ok(())
+    }
+
+    /// Get label context for a URI.
+    pub async fn get_context(&self, uri: &str) -> Result<Option<LabelContext>, sqlx::Error> {
+        let row: Option<ContextRow> = sqlx::query_as(
+                r#"
+                SELECT track_title, artist_handle, artist_did, highest_score, matches
+                FROM label_context
+                WHERE uri = $1
+                "#,
+            )
+            .bind(uri)
+            .fetch_optional(&self.pool)
+            .await?;
+
+        Ok(row.map(|(track_title, artist_handle, artist_did, highest_score, matches)| {
+            LabelContext {
+                track_title,
+                artist_handle,
+                artist_did,
+                highest_score,
+                matches: matches.and_then(|v| serde_json::from_value(v).ok()),
+            }
+        }))
+    }
+
     /// Store a signed label and return its sequence number.
     pub async fn store_label(&self, label: &Label) -> Result<i64, sqlx::Error> {
         let sig = label.sig.as_ref().map(|b| b.to_vec()).unwrap_or_default();
···
             .map(|s| s.unwrap_or(0))
     }
 
-    /// Get all copyright-violation labels with their resolution status.
+    /// Get all copyright-violation labels with their resolution status and context.
     ///
     /// A label is resolved if there's a negation label for the same uri+val.
     pub async fn get_pending_flags(&self) -> Result<Vec<FlaggedTrack>, sqlx::Error> {
-        // Get all copyright-violation labels (non-negations)
-        let rows = sqlx::query_as::<_, LabelRow>(
+        // Get all copyright-violation labels with context via LEFT JOIN
+        let rows: Vec<FlaggedRow> = sqlx::query_as(
+                r#"
+                SELECT l.seq, l.uri, l.val, l.cts,
+                       c.track_title, c.artist_handle, c.artist_did, c.highest_score, c.matches
+                FROM labels l
+                LEFT JOIN label_context c ON l.uri = c.uri
+                WHERE l.val = 'copyright-violation' AND l.neg = false
+                ORDER BY l.seq DESC
+                "#,
+            )
+            .fetch_all(&self.pool)
+            .await?;
+
+        // Get all negation labels
+        let negated_uris: std::collections::HashSet<String> = sqlx::query_scalar::<_, String>(
             r#"
-            SELECT seq, src, uri, cid, val, neg, cts, exp, sig
+            SELECT DISTINCT uri
             FROM labels
-            WHERE val = 'copyright-violation' AND neg = false
-            ORDER BY seq DESC
+            WHERE val = 'copyright-violation' AND neg = true
             "#,
         )
         .fetch_all(&self.pool)
-        .await?;
-
-        // Get all negation labels for these URIs
-        let uris: Vec<String> = rows.iter().map(|r| r.uri.clone()).collect();
-        let negated_uris: std::collections::HashSet<String> = if !uris.is_empty() {
-            sqlx::query_scalar::<_, String>(
-                r#"
-                SELECT DISTINCT uri
-                FROM labels
-                WHERE val = 'copyright-violation' AND neg = true
-                "#,
-            )
-            .fetch_all(&self.pool)
-            .await?
-            .into_iter()
-            .collect()
-        } else {
-            std::collections::HashSet::new()
-        };
+        .await?
+        .into_iter()
+        .collect();
 
         let tracks = rows
             .into_iter()
-            .map(|r| FlaggedTrack {
-                seq: r.seq,
-                uri: r.uri.clone(),
-                val: r.val,
-                created_at: r.cts.format("%Y-%m-%d %H:%M:%S").to_string(),
-                resolved: negated_uris.contains(&r.uri),
+            .map(|(seq, uri, val, cts, track_title, artist_handle, artist_did, highest_score, matches)| {
+                let context = if track_title.is_some() || artist_handle.is_some() {
+                    Some(LabelContext {
+                        track_title,
+                        artist_handle,
+                        artist_did,
+                        highest_score,
+                        matches: matches.and_then(|v| serde_json::from_value(v).ok()),
+                    })
+                } else {
+                    None
+                };
+
+                FlaggedTrack {
+                    seq,
+                    uri: uri.clone(),
+                    val,
+                    created_at: cts.format("%Y-%m-%d %H:%M:%S").to_string(),
+                    resolved: negated_uris.contains(&uri),
+                    context,
+                }
             })
             .collect();
 

moderation/src/handlers.rs

···
 use serde::{Deserialize, Serialize};
 use tracing::info;
 
+use crate::db::{CopyrightMatch, LabelContext};
 use crate::labels::Label;
 use crate::state::{AppError, AppState};
 
···
     pub labeler_enabled: bool,
 }
 
+/// Context info for display in admin UI.
+#[derive(Debug, Deserialize)]
+pub struct EmitLabelContext {
+    pub track_title: Option<String>,
+    pub artist_handle: Option<String>,
+    pub artist_did: Option<String>,
+    pub highest_score: Option<f64>,
+    pub matches: Option<Vec<CopyrightMatch>>,
+}
+
 #[derive(Debug, Deserialize)]
 pub struct EmitLabelRequest {
     /// AT URI of the resource to label (e.g., at://did:plc:xxx/fm.plyr.track/abc123)
···
     /// If true, negate an existing label
     #[serde(default)]
     pub neg: bool,
+    /// Optional context for admin UI display
+    pub context: Option<EmitLabelContext>,
 }
 
 fn default_label_val() -> String {
···
     // Store in database
     let seq = db.store_label(&label).await?;
     info!(seq, uri = %request.uri, "label stored");
+
+    // Store context if provided (for admin UI)
+    if let Some(ctx) = request.context {
+        let label_ctx = LabelContext {
+            track_title: ctx.track_title,
+            artist_handle: ctx.artist_handle,
+            artist_did: ctx.artist_did,
+            highest_score: ctx.highest_score,
+            matches: ctx.matches,
+        };
+        if let Err(e) = db.store_context(&request.uri, &label_ctx).await {
+            // Log but don't fail - context is supplementary
+            tracing::warn!(uri = %request.uri, error = %e, "failed to store label context");
+        }
+    }
 
     // Broadcast to subscribers
     if let Some(tx) = &state.label_tx {

moderation/src/main.rs

···
         .route("/admin", get(admin::admin_ui))
         .route("/admin/flags", get(admin::list_flagged))
         .route("/admin/resolve", post(admin::resolve_flag))
+        .route("/admin/context", post(admin::store_context))
         // ATProto XRPC endpoints (public)
         .route("/xrpc/com.atproto.label.queryLabels", get(xrpc::query_labels))
         .route(

scripts/backfill_copyright_labels.py

···
+#!/usr/bin/env -S uv run --script --quiet --with-editable=backend
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+#     "httpx",
+#     "pydantic-settings",
+# ]
+# ///
+"""backfill copyright labels for flagged tracks.
+
+usage:
+    uv run scripts/backfill_copyright_labels.py --env prod --dry-run
+    uv run scripts/backfill_copyright_labels.py --env prod
+
+this will:
+- fetch all tracks flagged in copyright_scans that have atproto_record_uri
+- emit labels to the moderation service for each flagged track
+
+environment variables (set in .env or export):
+    PROD_DATABASE_URL - production database connection string
+    STAGING_DATABASE_URL - staging database connection string
+    MODERATION_SERVICE_URL - URL of moderation service (default: https://moderation.plyr.fm)
+    MODERATION_AUTH_TOKEN - auth token for moderation service
+"""
+
+import asyncio
+import os
+import sys
+from typing import Literal
+
+import httpx
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+Environment = Literal["dev", "staging", "prod"]
+
+
+class BackfillSettings(BaseSettings):
+    """settings for backfill script."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    dev_database_url: str = Field(default="", validation_alias="DEV_DATABASE_URL")
+    staging_database_url: str = Field(
+        default="", validation_alias="STAGING_DATABASE_URL"
+    )
+    prod_database_url: str = Field(default="", validation_alias="PROD_DATABASE_URL")
+
+    moderation_service_url: str = Field(
+        default="https://moderation.plyr.fm",
+        validation_alias="MODERATION_SERVICE_URL",
+    )
+    moderation_auth_token: str = Field(
+        default="", validation_alias="MODERATION_AUTH_TOKEN"
+    )
+
+    def get_database_url(self, env: Environment) -> str:
+        """get database URL for environment."""
+        urls = {
+            "dev": self.dev_database_url,
+            "staging": self.staging_database_url,
+            "prod": self.prod_database_url,
+        }
+        url = urls.get(env, "")
+        if not url:
+            raise ValueError(f"no database URL configured for {env}")
+        return url
+
+
+def setup_env(settings: BackfillSettings, env: Environment) -> None:
+    """setup environment variables for backend imports."""
+    db_url = settings.get_database_url(env)
+    # ensure asyncpg driver is used
+    if db_url.startswith("postgresql://"):
+        db_url = db_url.replace("postgresql://", "postgresql+asyncpg://", 1)
+    # asyncpg uses 'ssl' not 'sslmode' - convert the parameter
+    db_url = db_url.replace("sslmode=require", "ssl=require")
+    os.environ["DATABASE_URL"] = db_url
+
+
+async def emit_label(
+    client: httpx.AsyncClient,
+    settings: BackfillSettings,
+    uri: str,
+    cid: str | None,
+) -> bool:
+    """emit a copyright-violation label for a track."""
+    try:
+        response = await client.post(
+            f"{settings.moderation_service_url}/emit-label",
+            json={
+                "uri": uri,
+                "val": "copyright-violation",
+                "cid": cid,
+            },
+            headers={"X-Moderation-Key": settings.moderation_auth_token},
+            timeout=30.0,
+        )
+        response.raise_for_status()
+        return True
+    except httpx.HTTPStatusError as e:
+        print(f"  ❌ HTTP error: {e.response.status_code}")
+        try:
+            print(f"     {e.response.json()}")
+        except Exception:
+            print(f"     {e.response.text[:200]}")
+        return False
+    except Exception as e:
+        print(f"  ❌ error: {e}")
+        return False
+
+
+async def run_backfill(env: Environment, dry_run: bool = False) -> None:
+    """backfill copyright labels for flagged tracks."""
+    settings = BackfillSettings()
+
+    # validate settings
+    try:
+        db_url = settings.get_database_url(env)
+        print(
+            f"✓ database: {db_url.split('@')[1].split('/')[0] if '@' in db_url else 'configured'}"
+        )
+    except ValueError as e:
+        print(f"❌ {e}")
+        print(f"\nset {env.upper()}_DATABASE_URL in .env")
+        sys.exit(1)
+
+    if not settings.moderation_auth_token:
+        print("❌ MODERATION_AUTH_TOKEN not set")
+        sys.exit(1)
+
+    print(f"✓ moderation service: {settings.moderation_service_url}")
+
+    # setup env before backend imports
+    setup_env(settings, env)
+
+    # import backend after env setup
+    from sqlalchemy import select
+    from sqlalchemy.orm import joinedload
+
+    from backend.models import CopyrightScan, Track
+    from backend.utilities.database import db_session
+
+    async with db_session() as db:
+        # find flagged tracks with atproto URIs
+        stmt = (
+            select(Track)
+            .options(joinedload(Track.artist))
+            .join(CopyrightScan, CopyrightScan.track_id == Track.id)
+            .where(CopyrightScan.is_flagged.is_(True))
+            .where(Track.atproto_record_uri.isnot(None))
+            .order_by(Track.created_at.desc())
+        )
+
+        result = await db.execute(stmt)
+        tracks = result.scalars().unique().all()
+
+        if not tracks:
+            print("\n✅ no flagged tracks need label backfill")
+            return
+
+        print(f"\n📋 found {len(tracks)} flagged tracks with ATProto URIs")
+
+        if dry_run:
+            print("\n[DRY RUN] would emit labels for:")
+            for track in tracks:
+                print(f"  - {track.id}: {track.title} by @{track.artist.handle}")
+                print(f"    uri: {track.atproto_record_uri}")
+            return
+
+        # emit labels
+        async with httpx.AsyncClient() as client:
+            emitted = 0
+            failed = 0
+
+            for i, track in enumerate(tracks, 1):
+                print(f"\n[{i}/{len(tracks)}] emitting label for: {track.title}")
+                print(f"  artist: @{track.artist.handle}")
+                print(f"  uri: {track.atproto_record_uri}")
+
+                success = await emit_label(
+                    client,
+                    settings,
+                    track.atproto_record_uri,
+                    track.atproto_record_cid,
+                )
+
+                if success:
+                    emitted += 1
+                    print("  ✓ label emitted")
+                else:
+                    failed += 1
+
+        print(f"\n{'=' * 50}")
+        print("✅ backfill complete")
+        print(f"   emitted: {emitted}")
+        print(f"   failed: {failed}")
+
+
+def main() -> None:
+    """main entry point."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="backfill copyright labels for flagged tracks"
+    )
+    parser.add_argument(
+        "--env",
+        type=str,
+        required=True,
+        choices=["dev", "staging", "prod"],
+        help="environment to backfill",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="show what would be emitted without making changes",
+    )
+
+    args = parser.parse_args()
+
+    print(f"🏷️  copyright label backfill - {args.env}")
+    print("=" * 50)
+
+    asyncio.run(run_backfill(args.env, args.dry_run))
+
+
+if __name__ == "__main__":
+    main()

scripts/backfill_label_context.py

···
+#!/usr/bin/env -S uv run --script --quiet --with-editable=backend
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+#     "httpx",
+#     "pydantic-settings",
+# ]
+# ///
+"""backfill label context from copyright_scans to moderation service.
+
+this script reads flagged tracks from the backend database and populates
+the label_context table in the moderation service database. it does NOT
+emit new labels - it only adds context to existing labels.
+
+usage:
+    uv run scripts/backfill_label_context.py --env prod --dry-run
+    uv run scripts/backfill_label_context.py --env prod
+
+environment variables (set in .env or export):
+    PROD_DATABASE_URL - production database connection string
+    STAGING_DATABASE_URL - staging database connection string
+    MODERATION_SERVICE_URL - URL of moderation service (default: https://moderation.plyr.fm)
+    MODERATION_AUTH_TOKEN - auth token for moderation service
+"""
+
+import asyncio
+import os
+import sys
+from typing import Any, Literal
+
+import httpx
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+Environment = Literal["dev", "staging", "prod"]
+
+
+class BackfillSettings(BaseSettings):
+    """settings for backfill script."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    dev_database_url: str = Field(default="", validation_alias="DEV_DATABASE_URL")
+    staging_database_url: str = Field(
+        default="", validation_alias="STAGING_DATABASE_URL"
+    )
+    prod_database_url: str = Field(default="", validation_alias="PROD_DATABASE_URL")
+
+    moderation_service_url: str = Field(
+        default="https://moderation.plyr.fm",
+        validation_alias="MODERATION_SERVICE_URL",
+    )
+    moderation_auth_token: str = Field(
+        default="", validation_alias="MODERATION_AUTH_TOKEN"
+    )
+
+    def get_database_url(self, env: Environment) -> str:
+        """get database URL for environment."""
+        urls = {
+            "dev": self.dev_database_url,
+            "staging": self.staging_database_url,
+            "prod": self.prod_database_url,
+        }
+        url = urls.get(env, "")
+        if not url:
+            raise ValueError(f"no database URL configured for {env}")
+        return url
+
+
+def setup_env(settings: BackfillSettings, env: Environment) -> None:
+    """setup environment variables for backend imports."""
+    db_url = settings.get_database_url(env)
+    # ensure asyncpg driver is used
+    if db_url.startswith("postgresql://"):
+        db_url = db_url.replace("postgresql://", "postgresql+asyncpg://", 1)
+    # asyncpg uses 'ssl' not 'sslmode' - convert the parameter
+    db_url = db_url.replace("sslmode=require", "ssl=require")
+    os.environ["DATABASE_URL"] = db_url
+
+
+async def store_context(
+    client: httpx.AsyncClient,
+    settings: BackfillSettings,
+    uri: str,
+    context: dict[str, Any],
+) -> bool:
+    """store context directly via emit-label endpoint.
+
+    we send a "dummy" emit that just stores context for an existing label.
+    the moderation service will upsert the context without creating a new label
+    if we use neg=false and the label already exists (it just updates context).
+
+    actually, we need a dedicated endpoint for this. let's use a workaround:
+    call emit-label with the context - it will store the context even though
+    the label already exists (store_context uses ON CONFLICT DO UPDATE).
+    """
+    try:
+        # we need to call emit-label to trigger context storage
+        # but we don't want to create duplicate labels
+        # the backend will reject duplicate labels, so we just send context
+        # via a new endpoint we need to add... or we can use a hack:
+        # just POST to emit-label with context - it will store label + context
+        # but since label already exists, we'll get an error... hmm
+
+        # actually, looking at the code, store_label will create a new label row
+        # each time (no unique constraint on uri+val). that's intentional for
+        # labeler protocol. so we can't use emit-label for backfill.
+
+        # we need a dedicated endpoint. let's add /admin/context for this.
+        response = await client.post(
+            f"{settings.moderation_service_url}/admin/context",
+            json={
+                "uri": uri,
+                "context": context,
+            },
+            headers={"X-Moderation-Key": settings.moderation_auth_token},
+            timeout=30.0,
+        )
+        response.raise_for_status()
+        return True
+    except httpx.HTTPStatusError as e:
+        print(f"  ❌ HTTP error: {e.response.status_code}")
+        try:
+            print(f"     {e.response.json()}")
+        except Exception:
+            print(f"     {e.response.text[:200]}")
+        return False
+    except Exception as e:
+        print(f"  ❌ error: {e}")
+        return False
+
+
+async def run_backfill(env: Environment, dry_run: bool = False) -> None:
+    """backfill label context from copyright_scans."""
+    settings = BackfillSettings()
+
+    # validate settings
+    try:
+        db_url = settings.get_database_url(env)
+        print(
+            f"✓ database: {db_url.split('@')[1].split('/')[0] if '@' in db_url else 'configured'}"
+        )
+    except ValueError as e:
+        print(f"❌ {e}")
+        print(f"\nset {env.upper()}_DATABASE_URL in .env")
+        sys.exit(1)
+
+    if not settings.moderation_auth_token:
+        print("❌ MODERATION_AUTH_TOKEN not set")
+        sys.exit(1)
+
+    print(f"✓ moderation service: {settings.moderation_service_url}")
+
+    # setup env before backend imports
+    setup_env(settings, env)
+
+    # import backend after env setup
+    from sqlalchemy import select
+    from sqlalchemy.orm import joinedload
+
+    from backend.models import CopyrightScan, Track
+    from backend.utilities.database import db_session
+
+    async with db_session() as db:
+        # find flagged tracks with atproto URIs and their scan results
+        stmt = (
+            select(Track, CopyrightScan)
+            .options(joinedload(Track.artist))
+            .join(CopyrightScan, CopyrightScan.track_id == Track.id)
+            .where(CopyrightScan.is_flagged.is_(True))
+            .where(Track.atproto_record_uri.isnot(None))
+            .order_by(Track.created_at.desc())
+        )
+
+        result = await db.execute(stmt)
+        rows = result.unique().all()
+
+        if not rows:
+            print("\n✅ no flagged tracks to backfill context for")
+            return
+
+        print(f"\n📋 found {len(rows)} flagged tracks with context to backfill")
+
+        if dry_run:
+            print("\n[DRY RUN] would store context for:")
+            for track, scan in rows:
+                print(f"  - {track.id}: {track.title} by @{track.artist.handle}")
+                print(f"    uri: {track.atproto_record_uri}")
+                print(
+                    f"    score: {scan.highest_score}, matches: {len(scan.matches or [])}"
+                )
+            return
+
+        # store context for each track
+        async with httpx.AsyncClient() as client:
+            stored = 0
+            failed = 0
+
+            for i, (track, scan) in enumerate(rows, 1):
+                print(f"\n[{i}/{len(rows)}] storing context for: {track.title}")
+                print(f"  artist: @{track.artist.handle}")
+                print(f"  uri: {track.atproto_record_uri}")
+
+                context = {
+                    "track_title": track.title,
+                    "artist_handle": track.artist.handle if track.artist else None,
+                    "artist_did": track.artist_did,
+                    "highest_score": scan.highest_score,
+                    "matches": scan.matches,
+                }
+
+                success = await store_context(
+                    client,
+                    settings,
+                    track.atproto_record_uri,
+                    context,
+                )
+
+                if success:
+                    stored += 1
+                    print("  ✓ context stored")
+                else:
+                    failed += 1
+
+        print(f"\n{'=' * 50}")
+        print("✅ backfill complete")
+        print(f"   stored: {stored}")
+        print(f"   failed: {failed}")
+
+
+def main() -> None:
+    """main entry point."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="backfill label context from copyright_scans"
+    )
+    parser.add_argument(
+        "--env",
+        type=str,
+        required=True,
+        choices=["dev", "staging", "prod"],
+        help="environment to backfill",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="show what would be stored without making changes",
+    )
+
+    args = parser.parse_args()
+
+    print(f"🏷️  label context backfill - {args.env}")
+    print("=" * 50)
+
+    asyncio.run(run_backfill(args.env, args.dry_run))
+
+
+if __name__ == "__main__":
+    main()