Upload agents/modality_detector.py with huggingface_hub

agents/modality_detector.py

@@ -0,0 +1,270 @@
+"""
+FORENSIQ — Capture Modality Detector
+
+Classifies images into capture modalities BEFORE forensic analysis.
+Each modality has known false-positive patterns that agents must account for.
+
+Modalities:
+  DSLR          — Traditional camera, raw/JPEG from camera firmware
+  SMARTPHONE    — Standard smartphone photo (no portrait mode)
+  PORTRAIT_MODE — Smartphone portrait mode (computational bokeh)
+  SCREENSHOT    — Screen capture
+  MESSAGING     — Compressed via WhatsApp/Telegram/etc (stripped metadata, double JPEG)
+  SOCIAL_MEDIA  — Downloaded from Instagram/Facebook/Twitter (re-encoded, stripped)
+  UNKNOWN       — Cannot determine
+"""
+
+import numpy as np
+from PIL import Image
+from scipy.ndimage import gaussian_filter, sobel
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class ModalityResult:
+    modality: str                # Primary modality classification
+    confidence: float            # 0-1
+    indicators: dict             # Evidence for the classification
+    score_adjustments: dict      # Per-test score multipliers (1.0 = no change, 0.0 = suppress)
+
+
+def detect_modality(img: Image.Image) -> ModalityResult:
+    """Detect capture modality from image properties."""
+    indicators = {}
+    scores = {}  # modality -> evidence strength
+    
+    w, h = img.size
+    
+    # ── 1. Metadata analysis ──────────────────────────────────────────
+    try:
+        exif = img._getexif() or {}
+    except:
+        exif = {}
+    
+    from PIL.ExifTags import TAGS
+    decoded = {}
+    for tid, v in exif.items():
+        t = TAGS.get(tid, str(tid))
+        try:
+            decoded[t] = str(v)[:200]
+        except:
+            pass
+    
+    has_make = "Make" in decoded
+    has_model = "Model" in decoded
+    has_lens = "LensModel" in decoded or "LensInfo" in decoded
+    has_focal = "FocalLength" in decoded
+    has_software = "Software" in decoded
+    has_gps = "GPSInfo" in decoded
+    info = img.info or {}
+    source_format = getattr(img, 'format', None)
+    
+    cam_fields = sum([has_make, has_model, has_lens, has_focal])
+    indicators["exif_camera_fields"] = cam_fields
+    indicators["has_exif"] = bool(decoded)
+    indicators["format"] = source_format
+    
+    # Rich EXIF with lens info → DSLR
+    if cam_fields >= 3 and has_lens:
+        scores["DSLR"] = scores.get("DSLR", 0) + 0.4
+    
+    # Camera make is a phone brand
+    phone_brands = ["apple", "samsung", "google", "pixel", "huawei", "xiaomi", "oneplus",
+                    "oppo", "vivo", "realme", "motorola", "lg", "sony xperia", "nothing"]
+    make = decoded.get("Make", "").lower()
+    model = decoded.get("Model", "").lower()
+    if any(b in make or b in model for b in phone_brands):
+        scores["SMARTPHONE"] = scores.get("SMARTPHONE", 0) + 0.5
+        indicators["phone_brand"] = True
+    
+    # No EXIF at all → messaging/social or AI
+    if not decoded:
+        scores["MESSAGING"] = scores.get("MESSAGING", 0) + 0.3
+        scores["SOCIAL_MEDIA"] = scores.get("SOCIAL_MEDIA", 0) + 0.2
+        indicators["no_exif"] = True
+    
+    # ── 2. Resolution analysis ────────────────────────────────────────
+    mp = w * h / 1e6
+    indicators["megapixels"] = round(mp, 2)
+    
+    # Common messaging app resolutions (WhatsApp compresses to ~1600px max side)
+    max_side = max(w, h)
+    if max_side <= 1600 and mp < 3:
+        scores["MESSAGING"] = scores.get("MESSAGING", 0) + 0.25
+        indicators["low_res"] = True
+    
+    # Screenshot-like aspect ratios (phone screens)
+    ratio = max(w, h) / min(w, h)
+    if ratio > 1.9 and max_side > 1000:  # Tall phone screenshots
+        scores["SCREENSHOT"] = scores.get("SCREENSHOT", 0) + 0.3
+        indicators["tall_ratio"] = round(ratio, 2)
+    
+    # Standard phone ratios: 4:3 or 16:9
+    if abs(ratio - 4/3) < 0.05 or abs(ratio - 16/9) < 0.05:
+        scores["SMARTPHONE"] = scores.get("SMARTPHONE", 0) + 0.1
+    
+    # ── 3. Portrait mode detection (computational bokeh) ──────────────
+    gray = np.array(img.convert("L")).astype(np.float64)
+    
+    # Compute local sharpness map
+    lap = np.array([[0, 1, 0], [1, -4, 1], [0, 1, 0]], dtype=np.float64)
+    from scipy.signal import convolve2d
+    laplacian = convolve2d(gray, lap, mode="same", boundary="symm")
+    sharpness = gaussian_filter(np.abs(laplacian), sigma=10)
+    
+    # Portrait mode signature: sharp foreground + uniformly blurred background
+    # with an ABRUPT transition between them (not gradual like real DoF)
+    sharp_thresh = np.percentile(sharpness, 75)
+    blur_thresh = np.percentile(sharpness, 25)
+    
+    sharp_region = sharpness > sharp_thresh
+    blur_region = sharpness < blur_thresh
+    
+    # Compute transition sharpness
+    # In portrait mode: boundary between sharp/blur is very steep
+    # In real DoF: boundary is gradual
+    sharp_fraction = float(np.mean(sharp_region))
+    blur_fraction = float(np.mean(blur_region))
+    
+    # Check if blur is very uniform (computational vs optical)
+    blur_values = sharpness[blur_region] if np.any(blur_region) else np.array([0])
+    blur_uniformity = 1.0 - min(float(np.std(blur_values)) / (float(np.mean(blur_values)) + 1e-9), 1.0)
+    
+    indicators["sharp_fraction"] = round(sharp_fraction, 3)
+    indicators["blur_fraction"] = round(blur_fraction, 3)
+    indicators["blur_uniformity"] = round(blur_uniformity, 3)
+    
+    # Strong portrait mode signal: distinct sharp/blur regions with uniform blur
+    if blur_fraction > 0.3 and blur_uniformity > 0.6 and sharp_fraction > 0.15:
+        scores["PORTRAIT_MODE"] = scores.get("PORTRAIT_MODE", 0) + 0.5
+        indicators["portrait_mode_signature"] = True
+    
+    # ── 4. Screenshot detection ───────────────────────────────────────
+    # Screenshots have: perfect pixel edges, UI elements, uniform background areas
+    edge_mag = np.hypot(sobel(gray, 0), sobel(gray, 1))
+    
+    # Perfect horizontal/vertical edges (UI elements)
+    strong_edges = edge_mag > np.percentile(edge_mag, 95)
+    gx = sobel(gray, axis=1)
+    gy = sobel(gray, axis=0)
+    
+    # Ratio of H/V edges to diagonal edges
+    h_edges = np.abs(gx) > np.abs(gy) * 3  # Strongly horizontal
+    v_edges = np.abs(gy) > np.abs(gx) * 3  # Strongly vertical
+    hv_ratio = float(np.sum(h_edges | v_edges)) / (float(np.sum(strong_edges)) + 1e-9)
+    
+    if hv_ratio > 0.6:
+        scores["SCREENSHOT"] = scores.get("SCREENSHOT", 0) + 0.3
+        indicators["hv_edge_ratio"] = round(hv_ratio, 3)
+    
+    # ── 5. Double JPEG / messaging detection ──────────────────────────
+    # Check for 8x8 block boundary artifacts (double JPEG)
+    hc, wc = (gray.shape[0] // 8) * 8, (gray.shape[1] // 8) * 8
+    if hc > 16 and wc > 16:
+        g = gray[:hc, :wc]
+        bd = [float(np.mean(np.abs(g[i, :] - g[i-1, :]))) for i in range(8, hc, 8)]
+        it = [float(np.mean(np.abs(g[i, :] - g[i-1, :]))) for i in range(1, hc) if i % 8 != 0]
+        if bd and it:
+            blockiness = float(np.mean(bd)) / (float(np.mean(it)) + 1e-9)
+            if blockiness > 1.3:
+                scores["MESSAGING"] = scores.get("MESSAGING", 0) + 0.2
+                indicators["double_jpeg"] = round(blockiness, 3)
+    
+    # ── 6. Determine primary modality ─────────────────────────────────
+    if not scores:
+        modality = "UNKNOWN"
+        confidence = 0.2
+    else:
+        modality = max(scores, key=scores.get)
+        confidence = min(1.0, scores[modality])
+    
+    # Override: if portrait mode + smartphone, portrait mode wins
+    if scores.get("PORTRAIT_MODE", 0) > 0.3 and scores.get("SMARTPHONE", 0) > 0:
+        modality = "PORTRAIT_MODE"
+        confidence = min(1.0, scores["PORTRAIT_MODE"] + scores["SMARTPHONE"] * 0.3)
+    
+    # ── 7. Build score adjustments per modality ───────────────────────
+    adjustments = _get_modality_adjustments(modality)
+    
+    return ModalityResult(
+        modality=modality,
+        confidence=round(confidence, 3),
+        indicators=indicators,
+        score_adjustments=adjustments,
+    )
+
+
+def _get_modality_adjustments(modality: str) -> dict:
+    """
+    Return per-test score multipliers for known false-positive patterns.
+    1.0 = no change, 0.0 = suppress entirely, 0.5 = halve the score.
+    """
+    
+    if modality == "PORTRAIT_MODE":
+        return {
+            # These tests false-positive on computational bokeh
+            "Autocorrelation Peak": 0.1,      # Bokeh creates periodic patterns
+            "Texture Repetition": 0.1,         # Bokeh is repetitive by design
+            "VAE Patch Boundaries": 0.2,       # Segmentation mask operates in blocks
+            "PRNU Uniformity": 0.15,           # Dual-region noise (sharp vs blur)
+            "Poisson-Gaussian Model": 0.3,     # Noise model breaks with synthetic blur
+            "DoF Consistency": 0.2,            # Abrupt transitions are EXPECTED
+            "Vignetting cos⁴θ": 0.3,          # Smartphones don't follow cos⁴θ
+            "HF Noise Structure": 0.3,         # Blur region has different noise
+            "Noise Spatial Frequency": 0.3,    # Same reason
+            "CFA Nyquist": 0.5,               # Computational processing removes CFA
+        }
+    
+    elif modality == "MESSAGING":
+        return {
+            # These tests false-positive on messaging compression
+            "EXIF Completeness": 0.15,         # WhatsApp strips ALL EXIF — this is normal
+            "Compression Ghosts": 0.2,         # Double JPEG is expected
+            "ICC Color Profile": 0.2,          # Stripped by messaging apps
+            "Maker Note": 0.2,                 # Stripped
+            "Thumbnail Check": 0.2,            # Stripped
+            "Software Detection": 0.2,         # Stripped
+            "JPEG Quantization": 0.3,          # Re-encoded with generic tables
+            "CFA Nyquist": 0.5,               # Re-encoding destroys CFA traces
+        }
+    
+    elif modality == "SOCIAL_MEDIA":
+        return {
+            "EXIF Completeness": 0.2,
+            "Compression Ghosts": 0.3,
+            "ICC Color Profile": 0.3,
+            "Maker Note": 0.2,
+            "Thumbnail Check": 0.3,
+        }
+    
+    elif modality == "SCREENSHOT":
+        return {
+            # Screenshots are NOT photos — most optical/sensor tests are meaningless
+            "Vignetting cos⁴θ": 0.1,
+            "Vignetting Symmetry": 0.1,
+            "Lens Distortion": 0.1,
+            "Field Curvature": 0.1,
+            "CA Magnitude": 0.1,
+            "CA Radial Gradient": 0.1,
+            "Lateral CA": 0.1,
+            "Purple Fringing": 0.1,
+            "Bokeh Shape": 0.1,
+            "PRNU Uniformity": 0.1,
+            "Bayer CFA Pattern": 0.1,
+            "CFA Nyquist": 0.1,
+            "Hot/Dead Pixels": 0.1,
+            "Noise Autocorrelation": 0.1,
+            "Demosaic Interpolation": 0.1,
+        }
+    
+    elif modality == "SMARTPHONE":
+        return {
+            # Smartphones use computational photography — mild suppression
+            "Vignetting cos⁴θ": 0.5,          # Computational correction
+            "CFA Nyquist": 0.7,               # Heavy ISP processing
+            "Poisson-Gaussian Model": 0.7,     # Noise reduction
+        }
+    
+    else:  # DSLR or UNKNOWN
+        return {}  # No adjustments — full scoring