src/features/discovery/docs/cloud_extraction_implementation_guide.md

Cloud Extraction & Product Detection Guide

This document details the configuration, implementation, and safeguards that ensure successful video frame extraction and product identification in the cloud environment.

1. Cloud Video Extraction (server.js)

Problem: Cloud IPs (Hugging Face/AWS/GCP) are aggressively blocked by YouTube, causing 403 Forbidden or Sign in to confirm you're not a bot errors.

Solution:

• Authentication: We use browser cookies exported via YT_DLP_COOKIES_BASE64 environment variable. This authenticates the request as a legitimate user session.
• Failover Logic:
  1. Primary: Attempt direct extraction with yt-dlp using cookies.
  2. Fallback: If direct extraction fails (e.g., age-gated or heavy throttling), the system falls back to downloading the highest quality thumbnail available (maxresdefault -> sddefault -> hqdefault).
  3. IPv4 Forcing: While previously discussed, specific IP forcing is less critical than valid cookies.

Configuration Requirements:

• YT_DLP_COOKIES_BASE64: Required env var containing base64-encoded Netscape format cookies.
• yt-dlp binary must act as a mobile client (User-Agent spoofing handles this internally in some versions, but cookies are key).

2. Product Detection & Thumbnails

Problem: Detected objects sometimes lacked cropped images (e.g., bounding box failures or sharp errors), leading to empty cards in the UI.

Solution:

• Vision Model: We utilize Qwen/Qwen2.5-VL-7B-Instruct for its strong multi-modal understanding and JSON output reliability.
• Thumbnail Guarantee:
  • The system attempts to crop the detected object from the frame.
  • Regression Fix: If the crop fails or detection comes from a full-frame analysis (fallback mode), the system automatically uploads the full frame as the product thumbnail.
  • This guarantees 100% image coverage for every detected product.

3. Data Privacy & Diagnostics

Problem: Diagnostic logs (e.g., "Extracted 4 frames") were appearing as "products" in the public or moderation UI, confusing users.

Solution:

• Status Segregation:
  • Valid Products: status = 'pending_review' (default) or approved.
  • Diagnostics/Errors: status = 'rejected'.
• Database Hygiene:
  • All internal logging (e.g., logDiag) explicitly sets status='rejected'.
  • Error catches in major workflows (e.g., extractFrames) log errors to DB with rejected status for debugging without polluting the UI.
• Frontend Filtering:
  • ShowcaseService explicitly filters out status='rejected' items from both the Public Showcase and Moderation Queue.
  • This ensures that even if a diagnostic log is generated, it remains invisible to the end-user.

4. Infrastructure & Deployment

Problem: Server timeouts or cold starts on serverless platforms (Vercel) caused extraction to fail mid-process.

Solution:

• Persistent Worker: We deploy the heavy extraction worker on Hugging Face Spaces (Docker/Node.js) which allows for long-running processes (up to 48 hours).
• Inngest Coordination: The Vercel app triggers the job via Inngest, but the heavy lifting happens on the dedicated worker, communicating back status updates.

5. Maintenance & Monitoring

• Health Check: The /health endpoint returns the current git version timestamp (e.g., 2026-02-07T19:30:00Z) to verify successful deployments.
• Database Cleanup: Occasional SQL cleanup of old diagnostic logs can keep table size manageable:

  DELETE FROM detected_objects WHERE status = 'rejected' AND created_at < NOW() - INTERVAL '7 days';