import asyncio import logging from fastapi import APIRouter, UploadFile, File, HTTPException from io import BytesIO from lib.phash import ( generate_hashes, generate_hash_from_serp_with_stats, check_distance_between_serp, low_content_warning_for, scan_database, effective_score_for_plagiarism, legacy_fallback_applies, ) from lib.cloudinary_service import ( cloudinary_uploader, delete_image, wait_for_url_ready, ) from lib.serp_service import serp_image_search from lib.db_service import get_all_artwork_hashes router = APIRouter() logger = logging.getLogger(__name__) # Score fields carried by every match object (see lib.phash._match_fields). # "similarity" is the pre-existing field (kept unchanged); the rest are # additive - see RESPONSE_STRUCTURE_AUDIT.md. MATCH_SCORE_FIELDS = ( "similarity", "raw_similarity", "raw_similarity_legacy", "calibrated_confidence", "transform_consistency", "transform_agreements", "block_agreements", "content_blocks_used", "low_content_warning", "fallback_used", "effective_similarity", ) def score_fields(match): """Project the score fields of a raw match dict (tolerant to old data).""" return {key: match.get(key) for key in MATCH_SCORE_FIELDS} @router.post("/check/web") async def plagiarism_pipeline(file: UploadFile = File(...)): """ Full plagiarism detection pipeline Steps: 1. Generate perceptual hashes 2. Scan database artworks 3. Upload image to Cloudinary 4. Reverse image search (SerpAPI) 5. Hash internet images 6. Compute similarity 7. Return best match """ upload = None try: file_bytes = await file.read() file_stream = BytesIO(file_bytes) # STEP 1 Generate hashes upload_hashes = generate_hashes(file_stream) if upload_hashes is None: raise HTTPException(400, "Hash generation failed") # STEP 2 Database scan (always returned, even if the web branch degrades) artworks = get_all_artwork_hashes() db_match = scan_database(upload_hashes, artworks) or [] # STEPS 3-6 Web branch: isolated so Serper/Cloudinary/network issues # degrade to web=None + diagnostics instead of failing the whole request. web_match = [] web_diagnostics = { "status": "not_attempted", "serp_returned": 0, "attempted": 0, "hashed_ok": 0, "hashed_failed": 0, } web_warning = None try: # STEP 3 Upload to cloudinary (explicitly public temp upload) file_stream.seek(0) upload_file = UploadFile(filename=file.filename, file=file_stream) upload = cloudinary_uploader(upload_file) secure_url = upload.get("secure_url") # STEP 3b Readiness gate: wait until the CDN URL is publicly # fetchable before asking Serper to crawl it. A premature Serper # call returns 200 + empty organic, indistinguishable from a # genuine "no match online" without this signal. ready, readiness = await asyncio.to_thread( wait_for_url_ready, secure_url ) web_diagnostics.update( { "cloudinary_ready": ready, "readiness_attempts": readiness["attempts"], "readiness_status": readiness["last_status"], "readiness_ms": readiness["elapsed_ms"], } ) if not ready: web_warning = ( "Online check skipped: uploaded image was not yet " "publicly fetchable " f"(status={readiness['last_status']}, " f"attempts={readiness['attempts']}). " "Database result below is still valid." ) web_diagnostics["status"] = "degraded" web_diagnostics["error"] = "cloudinary_url_not_ready" logger.warning("Web branch skipped: %s", web_warning) else: # STEP 4 Reverse image search serp_results = serp_image_search(secure_url) # STEP 5 Generate hashes for SERP results (schema-tolerant + stats) serp_hashes, hash_stats = await asyncio.to_thread( generate_hash_from_serp_with_stats, serp_results ) # STEP 6 Internet similarity web_match = ( check_distance_between_serp(upload_hashes, serp_hashes) or [] ) list_key = hash_stats.get("list_key") if not serp_hashes and hash_stats.get("serp_returned") == 0: status = "no_candidates" web_warning = ( "Serper found no online candidates for this image " f"(list_key={list_key}). " "Database result below is still valid." ) else: status = "ok" if web_match else "no_matches" if not serp_hashes: web_warning = ( "Online check returned no hashable images " f"(serp_returned={hash_stats.get('serp_returned')}, " f"list_key={list_key}, " f"failed={hash_stats.get('hashed_failed')}). " "Database result below is still valid." ) web_diagnostics.update({"status": status, **hash_stats}) except HTTPException as e: web_warning = f"Online check degraded: {e.detail}" web_diagnostics = {**web_diagnostics, "status": "degraded", "error": str(e.detail)} logger.warning("Web branch degraded: %s", e.detail) except Exception as e: web_warning = f"Online check degraded: {e}" web_diagnostics = {**web_diagnostics, "status": "degraded", "error": str(e)} logger.warning("Web branch degraded: %s", e) # ----------------------------- # Normalize database match # ----------------------------- db_best = None if db_match: db_best = { "type": "database", "source": "Registered Artwork", "url": f"{db_match[0]['artwork_id']}", **score_fields(db_match[0]), } # ----------------------------- # Normalize internet match # ----------------------------- web_best = None if web_match: web_best = { "type": "internet", "source": web_match[0].get("source"), "link": web_match[0].get("link"), "url": web_match[0].get("url"), **score_fields(web_match[0]), } # ----------------------------- # Determine best match # ----------------------------- best_match = None # calibrated_confidence is the primary score; it is a monotonic # mapping of raw_similarity, so ranking is unaffected. # Fallback-aware: when the consensus pipeline scores zero but the # legacy score is strong (>= LEGACY_FALLBACK_MIN_SCORE), the legacy # value decides instead so zero-consensus hits still surface. db_score = effective_score_for_plagiarism(db_best or {}) web_score = effective_score_for_plagiarism(web_best or {}) if db_score >= web_score: best_match = db_best else: best_match = web_best for candidate in (db_best, web_best, best_match): if candidate is not None and "fallback_used" not in candidate: candidate["fallback_used"] = legacy_fallback_applies(candidate) candidate["effective_similarity"] = effective_score_for_plagiarism( candidate ) other_matches = normalize_other_matches(web_match, db_match) return { "filename": file.filename, "success": True, "original_hash": upload_hashes["transforms"]["0"]["phash"], "db": db_best, "web": web_best, "best_match": best_match, "hashes": upload_hashes, "other_matches": other_matches, # True when the uploaded image itself has no content-bearing # blocks (flat/low-detail); scores involving it need caution. "low_content_warning": low_content_warning_for(upload_hashes), # Diagnostics so clients can tell "no plagiarism online" apart # from "online check degraded". Additive only. "web_diagnostics": web_diagnostics, "web_warning": web_warning, } except HTTPException: raise except Exception as e: logger.exception("plagiarism_pipeline failed") raise HTTPException(500, str(e)) finally: # STEP 7 Clean up cloudinary temp upload (best-effort, never masks result) if upload and upload.get("public_id"): try: delete_image(upload["public_id"]) except Exception as e: logger.warning("Cloudinary cleanup failed: %s", e) @router.post("/compare") async def compare_two_artworks( file1: UploadFile = File(...), file2: UploadFile = File(...) ): """ Compare two digital artwork images using perceptual hashing. Returns similarity metrics between the two images. """ try: from io import BytesIO from lib.phash import generate_hashes, compare_hash_sets # Read both files file1_bytes = await file1.read() file2_bytes = await file2.read() file1_stream = BytesIO(file1_bytes) file2_stream = BytesIO(file2_bytes) # Generate hashes hash1 = generate_hashes(file1_stream) hash2 = generate_hashes(file2_stream) if hash1 is None or hash2 is None: raise HTTPException(400, "Hash generation failed") # Compare hashes similarity = compare_hash_sets(hash1, hash2) return { "image1": file1.filename, "image2": file2.filename, "comparison": similarity, # True when either image has no content-bearing blocks and flat # blocks had to be used for the comparison. "low_content_warning": similarity["low_content_warning"], # Fallback-aware decision score: legacy drives flagging when the # consensus pipeline scores zero but legacy is strong. "fallback_used": legacy_fallback_applies(similarity), "effective_similarity": effective_score_for_plagiarism(similarity), } except Exception as e: raise HTTPException(500, str(e)) def normalize_other_matches(web_match, db_match): normalized = [] for match in web_match or []: normalized.append(match) for match in db_match or []: match["source"] = "Database" match["link"] = match["url"] normalized.append(match) return normalized