Upload 29 files

raven/__init__.py

@@ -0,0 +1 @@
+__version__ = "5.0.0"

raven/anchors.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+import numpy as np
+from sklearn.preprocessing import StandardScaler
+from sklearn.decomposition import PCA
+from sklearn.covariance import LedoitWolf
+
+
+class RobustAnchor:
+    def __init__(self, scaler_mean, scaler_scale, pca_mean, pca_components, location, precision, dist_mean, dist_std):
+        self.scaler_mean=np.asarray(scaler_mean,np.float64); self.scaler_scale=np.asarray(scaler_scale,np.float64)
+        self.pca_mean=np.asarray(pca_mean,np.float64); self.pca_components=np.asarray(pca_components,np.float64)
+        self.location=np.asarray(location,np.float64); self.precision=np.asarray(precision,np.float64); self.dist_mean=float(dist_mean); self.dist_std=float(dist_std)
+    @classmethod
+    def fit(cls,x:np.ndarray,max_components:int=48):
+        x=np.asarray(x,np.float64); sc=StandardScaler().fit(x); xs=sc.transform(x)
+        ncomp=max(1,min(int(max_components),xs.shape[1],max(1,xs.shape[0]-2)))
+        pca=PCA(n_components=ncomp,whiten=False,svd_solver="auto",random_state=1337).fit(xs); xp=pca.transform(xs)
+        lw=LedoitWolf(assume_centered=False).fit(xp); d=cls._distance_raw(xp,lw.location_,lw.precision_); dm=float(d.mean()); ds=float(d.std()+1e-6)
+        return cls(sc.mean_,sc.scale_+1e-8,pca.mean_,pca.components_,lw.location_,lw.precision_,dm,ds)
+    @staticmethod
+    def _distance_raw(x,loc,precision):
+        q=x-loc[None,:]; d2=np.einsum("bi,ij,bj->b",q,precision,q); return np.sqrt(np.maximum(d2,0.0))
+    def project(self,x):
+        xs=(np.asarray(x,np.float64)-self.scaler_mean[None,:])/self.scaler_scale[None,:]; return (xs-self.pca_mean[None,:])@self.pca_components.T
+    def score(self,x):
+        d=self._distance_raw(self.project(x),self.location,self.precision); return ((d-self.dist_mean)/self.dist_std).astype(np.float32)
+    def to_dict(self):
+        return {"scaler_mean":self.scaler_mean.astype(np.float32),"scaler_scale":self.scaler_scale.astype(np.float32),"pca_mean":self.pca_mean.astype(np.float32),"pca_components":self.pca_components.astype(np.float32),"location":self.location.astype(np.float32),"precision":self.precision.astype(np.float32),"dist_mean":self.dist_mean,"dist_std":self.dist_std}
+    @classmethod
+    def from_dict(cls,d): return cls(d["scaler_mean"],d["scaler_scale"],d["pca_mean"],d["pca_components"],d["location"],d["precision"],d["dist_mean"],d["dist_std"])
+
+
+class AnchorSet:
+    BRANCHES=("semantic","camera","spectral","patch","specialist")
+    def __init__(self,anchors:dict[str,RobustAnchor]): self.anchors=anchors
+    @classmethod
+    def fit(cls,cache:dict,cfg:dict):
+        mask=(cache["label"]==0)&(cache["split"]=="train")
+        if int(mask.sum())<40: raise ValueError("Need >=40 REAL train feature views to fit anchors")
+        nmax=int(cfg["anchors"].get("pca_max_components",48)); return cls({b:RobustAnchor.fit(cache[b][mask],nmax) for b in cls.BRANCHES})
+    def score(self,features:dict) -> np.ndarray:
+        return np.stack([self.anchors[b].score(features[b]) for b in self.BRANCHES],axis=1).astype(np.float32)
+    def to_dict(self): return {b:a.to_dict() for b,a in self.anchors.items()}
+    @classmethod
+    def from_dict(cls,d): return cls({b:RobustAnchor.from_dict(v) for b,v in d.items()})

raven/audit.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+from collections import Counter, defaultdict
+import numpy as np
+
+
+def _rate(counter: Counter, n: int) -> dict:
+    return {str(k): float(v / max(1, n)) for k, v in counter.items()}
+
+
+def audit_manifest(rows: list[dict], cfg: dict | None = None) -> dict:
+    report: dict = {"n": len(rows), "warnings": [], "notes": []}
+    debias = bool((cfg or {}).get("features", {}).get("resolution_debias", True))
+    by_label = defaultdict(list)
+    for r in rows:
+        by_label[int(r.get("label", -1))].append(r)
+    for label, name in ((0, "REAL"), (1, "AI")):
+        subset = by_label[label]
+        n = len(subset)
+        report[name] = {
+            "n": n,
+            "formats": _rate(Counter(r.get("format", "unknown") for r in subset), n),
+            "light": _rate(Counter(r.get("light_bucket", "unknown") for r in subset), n),
+            "sources": dict(Counter(str(r.get("source", "unknown")) for r in subset)),
+            "raw_sources": dict(Counter(str(r.get("raw_source", r.get("source", "unknown"))) for r in subset)),
+            "mean_luma": float(np.nanmean([r.get("mean_luma", np.nan) for r in subset])) if n else None,
+            "mean_megapixels": float(np.nanmean([r.get("megapixels", np.nan) for r in subset])) if n else None,
+            "exif_rate": float(np.mean([bool(r.get("has_exif", False)) for r in subset])) if n else None,
+        }
+    if len(by_label[0]) and len(by_label[1]):
+        real_fmt = report["REAL"]["formats"]; ai_fmt = report["AI"]["formats"]
+        keys = set(real_fmt) | set(ai_fmt)
+        fmt_gap = max((abs(real_fmt.get(k, 0.0) - ai_fmt.get(k, 0.0)) for k in keys), default=0.0)
+        if fmt_gap > 0.35:
+            report["warnings"].append("Large REAL/AI file-format imbalance. Model may learn JPG-vs-PNG shortcuts.")
+        rl = report["REAL"]["mean_luma"]; al = report["AI"]["mean_luma"]
+        if rl is not None and al is not None and abs(rl - al) > 0.12:
+            report["warnings"].append("Large brightness imbalance between REAL and AI. Add matched low-light/bright samples.")
+        rr = report["REAL"]["mean_megapixels"]; ar = report["AI"]["mean_megapixels"]
+        if rr and ar and max(rr, ar) / max(0.05, min(rr, ar)) > 2.5:
+            if debias:
+                report["notes"].append("Raw REAL/AI resolutions differ strongly, but v5.1 resolution deconfounding is enabled: all forensic branches use fixed square analysis grids and native megapixels/aspect are excluded from classifier/calibration inputs.")
+            else:
+                report["warnings"].append("Large resolution imbalance between REAL and AI. Enable features.resolution_debias.")
+    nr=len(by_label[0]); na=len(by_label[1])
+    report["raw_class_ratio_ai_to_real"] = float(na/max(1,nr)) if nr else None
+    report["training_prior_policy"] = "exact 50:50 REAL/AI class-first sampling + equal-class loss + 50:50 bootstrap calibration"
+    report["resolution_policy"] = "fixed-grid forensic analysis; native megapixels/aspect excluded" if debias else "raw"
+    report["storage_origins"] = dict(Counter(str(r.get("origin_kind","image")) for r in rows))
+    if nr and na and max(nr,na)/max(1,min(nr,na)) >= 3:
+        report["warnings"].append("Large raw class-count imbalance detected. RAVEN v3 neutralizes it with 50:50 sampling/loss/calibration; report balanced metrics, not raw accuracy.")
+    ai_sources = len(report.get("AI", {}).get("sources", {}))
+    if ai_sources < 5:
+        report["warnings"].append("Fewer than 5 AI generator sources. Unseen-generator generalization will be fragile.")
+    if len(by_label[0]) < 700 or len(by_label[1]) < 700:
+        report["warnings"].append("Under ~700 images in a class. RAVEN-F2K still runs, but calibration becomes noisy.")
+    return report

raven/benchmark.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+import copy
+import time
+import torch
+from .foundation import FoundationEncoder
+from .foundation_runtime import FoundationRuntime
+from .utils import configure_cpu
+
+
+def benchmark_foundation(cfg: dict, accelerator: str = "auto", loops: int = 5) -> dict:
+    cfg = copy.deepcopy(cfg)
+    hc = cfg["hardware"]
+    fc = cfg["foundation"]
+    fc["accelerator"] = accelerator
+    configure_cpu(hc.get("torch_threads", 6), hc.get("interop_threads", 1))
+    enc = FoundationEncoder(
+        fc.get("backend", "dinov2_vits14"),
+        bool(fc.get("allow_fallback", True)),
+        fc.get("fallback_backend", "torchvision_convnext_tiny"),
+    ).eval().to("cpu")
+    rt = FoundationRuntime(fc, enc)
+    b = rt.batch_size
+    x = torch.randn(b, 3, 224, 224)
+    rt.infer(x)
+    loops = max(2, int(loops))
+    t0 = time.perf_counter()
+    for _ in range(loops):
+        rt.infer(x)
+    sec = time.perf_counter() - t0
+    ips = (b * loops) / max(sec, 1e-9)
+    result = {
+        "requested_accelerator": accelerator,
+        "selected_runtime": rt.backend,
+        "foundation_backend": enc.backend,
+        "batch_size": b,
+        "loops": loops,
+        "seconds": sec,
+        "foundation_images_per_second": ips,
+        "foundation_only_estimate_minutes_30000_images": 30000.0 / max(ips, 1e-9) / 60.0,
+        "note": "This measures frozen foundation inference only; JPEG/Parquet decode and forensic branches add extra time.",
+    }
+    rt.release_accelerator_memory()
+    return result

raven/budget.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import copy
+import json
+import math
+from pathlib import Path
+
+import yaml
+
+from .benchmark import benchmark_foundation
+from .config import load_config
+from .utils import read_jsonl
+
+
+def _counts(rows: list[dict]) -> dict:
+    out = {"train_real": 0, "train_ai": 0, "val": 0, "test": 0}
+    for r in rows:
+        split = str(r.get("split", "train"))
+        if split == "train":
+            out["train_ai" if int(r.get("label", 0)) == 1 else "train_real"] += 1
+        elif split == "val":
+            out["val"] += 1
+        elif split == "test":
+            out["test"] += 1
+    return out
+
+
+def _estimate(cfg: dict, counts: dict, ips: float) -> dict:
+    fc = cfg["foundation"]
+    rc = cfg["real_specialists"]
+    tc = cfg["training"]
+    cap = int(fc.get("train_cap_per_class", 0))
+    tr0 = counts["train_real"] if cap <= 0 else min(counts["train_real"], cap)
+    tr1 = counts["train_ai"] if cap <= 0 else min(counts["train_ai"], cap)
+    eval_n = counts["val"] + counts["test"]
+    base_n = tr0 + tr1 + eval_n
+    aug_per_class = int(fc.get("augment_max_per_class", 0))
+    aug_n = 0
+    if not bool(fc.get("reuse_semantic_for_augmented_views", True)):
+        aug_n = min(tr0, aug_per_class) + min(tr1, aug_per_class)
+    foundation_n = base_n + aug_n
+    foundation_h = foundation_n / max(ips, 1e-6) / 3600.0
+
+
+    runtime = str(fc.get("_planned_runtime", "unknown"))
+    overhead = {"directml": 1.65, "openvino": 1.80, "torch": 2.15}.get(runtime, 1.90)
+    cache_h = foundation_h * overhead
+
+    specialist_limit = int(rc.get("max_real_images", 0))
+    specialist_n = counts["train_real"] if specialist_limit <= 0 else min(counts["train_real"], specialist_limit)
+    specialist_epochs = int(rc.get("epochs", 12))
+    specialist_h = 0.05 + specialist_n * (0.030 + 0.0015 * specialist_epochs) / 3600.0
+
+
+    members = int(tc.get("ensemble_members", 5))
+    epochs = int(tc.get("epochs", 60))
+    refine = int(tc.get("hard_refine_epochs", 6))
+    selected_train = tr0 + tr1
+    fusion_h = 0.04 + (selected_train / 10000.0) * members * (epochs + refine) * 0.0018
+    calibration_h = 0.08
+    total = cache_h + specialist_h + fusion_h + calibration_h
+    return {
+        "selected_train_real": tr0,
+        "selected_train_ai": tr1,
+        "eval_images": eval_n,
+        "foundation_passes": foundation_n,
+        "foundation_hours_raw": foundation_h,
+        "cache_hours_est": cache_h,
+        "specialist_hours_est": specialist_h,
+        "fusion_hours_est": fusion_h,
+        "calibration_hours_est": calibration_h,
+        "total_hours_est": total,
+    }
+
+
+def plan_budget(
+    manifest: str,
+    base_config: str,
+    out_config: str,
+    target_hours: float = 4.5,
+    min_hours: float = 3.0,
+    max_hours: float = 6.0,
+    accelerator: str = "auto",
+    loops: int = 4,
+) -> dict:
+    rows = read_jsonl(manifest)
+    counts = _counts(rows)
+    cfg = copy.deepcopy(load_config(base_config))
+    bench = benchmark_foundation(cfg, accelerator, loops)
+    ips = float(bench["foundation_images_per_second"])
+    runtime = str(bench["selected_runtime"])
+    fc, rc, tc = cfg["foundation"], cfg["real_specialists"], cfg["training"]
+    fc["_planned_runtime"] = runtime
+
+
+    tc["ensemble_members"] = 5
+    tc["epochs"] = 60
+    tc["early_stop_patience"] = 7
+    tc["hard_refine_epochs"] = 6
+    tc["hard_refine_lr_multiplier"] = 0.22
+    tc["hard_replay_boost"] = 4.0
+    tc["contrastive_weight"] = 0.028
+    tc["branch_dropout"] = 0.12
+    tc["source_dropout_per_member"] = 1
+    rc["epochs"] = 12
+    rc["early_stop_patience"] = 3
+
+    rc["max_real_images"] = int(counts["train_real"])
+    fc["reuse_semantic_for_augmented_views"] = True
+    fc["augment_max_per_class"] = 6000
+    fc["train_coreset"] = True
+    fc["train_cap_per_class"] = 0
+
+
+    target = min(max(float(target_hours), float(min_hours)), float(max_hours))
+    runtime_factor = {"directml": 1.65, "openvino": 1.80, "torch": 2.15}.get(runtime, 1.90)
+    foundation_budget_h = target * 0.62
+    affordable_total = int(foundation_budget_h * 3600.0 * ips / runtime_factor)
+    eval_n = counts["val"] + counts["test"]
+    train_budget = max(2000, affordable_total - eval_n)
+
+
+    fc["train_cap_per_class"] = 0
+
+    est = _estimate(cfg, counts, ips)
+
+
+    if fc["train_cap_per_class"] == 0 and est["total_hours_est"] < min(target * 0.78, max_hours - 0.5):
+        remaining_h = max(0.0, target - est["total_hours_est"])
+        extra_passes = int(remaining_h * 3600.0 * ips / runtime_factor * 0.72)
+        per_cls_extra = min(counts["train_real"], counts["train_ai"], max(0, extra_passes // 2))
+        if per_cls_extra >= 500:
+            fc["reuse_semantic_for_augmented_views"] = False
+            fc["augment_max_per_class"] = int(min(6000, per_cls_extra))
+            est = _estimate(cfg, counts, ips)
+
+
+    if est["total_hours_est"] > max_hours:
+        fc["reuse_semantic_for_augmented_views"] = True
+        fc["augment_max_per_class"] = 0
+        tc["epochs"] = min(int(tc.get("epochs",60)), 50)
+        tc["hard_refine_epochs"] = min(int(tc.get("hard_refine_epochs",6)), 4)
+        fc["train_cap_per_class"] = 0
+        rc["max_real_images"] = int(counts["train_real"])
+        est = _estimate(cfg, counts, ips)
+
+    cfg["project"]["version"] = "5.1-full-data-debiased"
+    cfg["budget"] = {
+        "target_hours": target,
+        "minimum_hours": float(min_hours),
+        "maximum_hours": float(max_hours),
+        "benchmark_runtime": runtime,
+        "foundation_images_per_second": ips,
+        "planner_note": "Estimate is hardware-measured but still approximate; disk/image decode speed can shift wall time.",
+    }
+    fc.pop("_planned_runtime", None)
+    out = Path(out_config)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(yaml.safe_dump(cfg, allow_unicode=True, sort_keys=False), encoding="utf-8")
+    result = {
+        "counts": counts,
+        "benchmark": bench,
+        "selected": {
+            "train_cap_per_class": int(fc.get("train_cap_per_class", 0)),
+            "reuse_semantic_for_augmented_views": bool(fc.get("reuse_semantic_for_augmented_views", True)),
+            "augment_max_per_class": int(fc.get("augment_max_per_class", 0)),
+            "real_specialist_max": int(rc.get("max_real_images", 0)),
+            "ensemble_members": int(tc.get("ensemble_members", 5)),
+            "hard_refine_epochs": int(tc.get("hard_refine_epochs", 0)),
+            "all_original_train_images": True,
+        },
+        "estimate": est,
+        "output_config": str(out),
+    }
+    Path(str(out) + ".plan.json").write_text(json.dumps(result, indent=2, ensure_ascii=False), encoding="utf-8")
+    return result

raven/cache.py

@@ -0,0 +1,323 @@
+from __future__ import annotations
+
+import json
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+
+import numpy as np
+import torch
+import torch.nn.functional as F
+from tqdm import tqdm
+
+from .foundation import FoundationEncoder
+from .foundation_runtime import FoundationRuntime
+from .forensic_features import load_rgb, extract_handcrafted, spectral_map, camera_residual_map
+from .specialists import load_specialists
+from .transforms import SymmetricAugment
+from .utils import configure_cpu, seed_everything, stable_unit
+
+
+def _specialist_batch_scores(spec, cam, smaps: torch.Tensor, cmaps: torch.Tensor) -> np.ndarray:
+    with torch.inference_mode():
+        ps = spec(smaps)
+        pc = cam(cmaps)
+
+        def met(pred, target):
+            err = torch.abs(pred - target)
+            flat = err.flatten(1)
+            mae = flat.mean(1)
+            mse = ((pred - target) ** 2).flatten(1).mean(1)
+            cos = 1.0 - F.cosine_similarity(pred.flatten(1), target.flatten(1), dim=1)
+            q90 = torch.quantile(flat, .90, dim=1)
+            return torch.stack([mae, mse, cos, q90], 1)
+
+        return torch.cat([met(ps, smaps), met(pc, cmaps)], 1).cpu().numpy().astype(np.float32)
+
+
+def _prepare_unique_row(item):
+
+    r, augment_copies, transform, feat_cfg, map_size, reuse_semantic = item
+    im = load_rgb(r["path"])
+    sem_tensor = transform(im)
+    aug = SymmetricAugment()
+    views = []
+    for v in range(0, max(0, int(augment_copies)) + 1):
+        if v > 0 and r.get("split") != "train":
+            break
+        view = im if v == 0 else aug(im)
+        h = extract_handcrafted(view, feat_cfg)
+        views.append({
+            "view_id": v,
+            "handcrafted": h,
+            "spectral_map": spectral_map(view, map_size),
+            "camera_map": camera_residual_map(view, map_size),
+
+            "semantic_tensor": None if (v == 0 or reuse_semantic) else transform(view),
+        })
+    return r, sem_tensor, views
+
+
+def _prepare_unique_row_safe(item):
+    try:
+        return _prepare_unique_row(item), None
+    except Exception as exc:
+        return None, f"{item[0].get('path')}: {exc}"
+
+
+def _select_augment_paths(rows: list[dict], cap_per_class: int) -> set[str]:
+
+    from collections import defaultdict
+    if cap_per_class <= 0:
+        return set()
+    chosen = set()
+    for cls in (0, 1):
+        groups = defaultdict(list)
+        for r in rows:
+            if int(r.get("label", -1)) == cls and r.get("split") == "train":
+                groups[str(r.get("source", "unknown"))].append(r)
+        if not groups:
+            continue
+        for g in groups.values():
+            g.sort(key=lambda r: stable_unit(str(r.get("path", ""))))
+        keys = sorted(groups)
+        pos = {k: 0 for k in keys}
+        count = 0
+        while count < cap_per_class:
+            added = False
+            for k in keys:
+                i = pos[k]
+                if i < len(groups[k]):
+                    chosen.add(str(groups[k][i]["path"]))
+                    pos[k] = i + 1
+                    count += 1
+                    added = True
+                    if count >= cap_per_class:
+                        break
+            if not added:
+                break
+    return chosen
+
+
+def _training_coreset(rows: list[dict], cap_per_class: int) -> list[dict]:
+
+    from collections import defaultdict
+    if cap_per_class <= 0:
+        return list(rows)
+    keep = [r for r in rows if str(r.get("split", "train")) != "train"]
+    for cls in (0, 1):
+        pool = [r for r in rows if str(r.get("split", "train")) == "train" and int(r.get("label", -1)) == cls]
+        if len(pool) <= cap_per_class:
+            keep.extend(pool)
+            continue
+        groups = defaultdict(list)
+        for r in pool:
+            parent = Path(str(r.get("path", ""))).parent.name
+            key = (str(r.get("source", "unknown")), str(r.get("light_bucket", "unknown")), parent)
+            groups[key].append(r)
+        for vals in groups.values():
+            vals.sort(key=lambda r: stable_unit(str(r.get("path", ""))))
+        keys = sorted(groups, key=lambda k: stable_unit("|".join(k)))
+        pos = {k: 0 for k in keys}
+        selected = []
+        while len(selected) < cap_per_class:
+            added = False
+            for k in keys:
+                i = pos[k]
+                if i < len(groups[k]):
+                    selected.append(groups[k][i]); pos[k] = i + 1; added = True
+                    if len(selected) >= cap_per_class:
+                        break
+            if not added:
+                break
+        keep.extend(selected)
+
+    keep.sort(key=lambda r: (str(r.get("split", "train")), int(r.get("label", 0)), str(r.get("path", ""))))
+    return keep
+
+def cache_features(rows: list[dict], cfg: dict, specialists_path: str, out_path: str, augment_copies: int = 1) -> dict:
+    hc = cfg["hardware"]
+    fc = cfg["foundation"]
+    feat_cfg = cfg["features"]
+    configure_cpu(hc.get("torch_threads", 6), hc.get("interop_threads", 1))
+    seed_everything(cfg["training"].get("seed", 1337))
+
+    input_unique = len(rows)
+    train_cap = int(fc.get("train_cap_per_class", 0))
+    if bool(fc.get("train_coreset", False)) and train_cap > 0:
+        rows = _training_coreset(rows, train_cap)
+        print(f"[cache] diversity core-set: {input_unique} -> {len(rows)} unique rows (train cap={train_cap}/class; all val/test kept)")
+
+    foundation = FoundationEncoder(
+        fc.get("backend", "dinov2_vits14"),
+        bool(fc.get("allow_fallback", True)),
+        fc.get("fallback_backend", "torchvision_convnext_tiny"),
+    )
+    foundation.eval().to("cpu")
+
+
+    p = Path(out_path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    foundation_state_path = p.with_suffix(p.suffix + ".foundation.pt")
+    torch.save(
+        {"backend": foundation.backend, "dim": int(foundation.dim), "state_dict": foundation.model.state_dict()},
+        foundation_state_path,
+    )
+
+    runtime = FoundationRuntime(fc, foundation)
+    spec, cam, sck = load_specialists(specialists_path, "cpu")
+    map_size = int(sck["map_size"])
+
+
+    bsz = max(1, int(runtime.batch_size))
+    preprocess_workers = max(0, int(hc.get("preprocess_workers", 2)))
+    reuse_sem = bool(fc.get("reuse_semantic_for_augmented_views", True))
+    augment_cap = int(fc.get("augment_max_per_class", 4000))
+    augment_paths = _select_augment_paths(rows, augment_cap) if augment_copies > 0 else set()
+    print(f"[cache] image-level augmentation selected for {len(augment_paths)} train images "
+          f"(cap={augment_cap}/class, copies={augment_copies})")
+
+    store = {k: [] for k in [
+        "semantic", "camera", "spectral", "patch", "quality", "specialist",
+        "label", "source", "path", "split", "view_id", "light_bucket", "mean_luma",
+    ]}
+
+    total_unique = len(rows)
+    executor = ThreadPoolExecutor(max_workers=preprocess_workers) if preprocess_workers > 1 else None
+
+    try:
+        for start in tqdm(range(0, total_unique, bsz), desc=f"cache-features[{runtime.backend}]"):
+            chunk_rows = rows[start:start + bsz]
+            jobs = [
+                (
+                    r,
+                    augment_copies if str(r.get("path")) in augment_paths else 0,
+                    foundation.transform, feat_cfg, map_size, reuse_sem
+                )
+                for r in chunk_rows
+            ]
+            if executor is not None:
+                results = list(executor.map(_prepare_unique_row_safe, jobs))
+                prepared = []
+                for item, err in results:
+                    if err:
+                        print(f"[warning] skip {err}")
+                    elif item is not None:
+                        prepared.append(item)
+            else:
+                prepared = []
+                for j in jobs:
+                    try:
+                        prepared.append(_prepare_unique_row(j))
+                    except Exception as exc:
+                        print(f"[warning] skip {j[0].get('path')}: {exc}")
+
+            if not prepared:
+                continue
+            if not prepared:
+                continue
+
+            base_tensors = torch.stack([x[1] for x in prepared]).float()
+            semantic_base = runtime.infer(base_tensors)
+
+
+            semantic_aug = {}
+            if not reuse_sem:
+                aug_tensors = []
+                aug_keys = []
+                for pi, (_, _, views) in enumerate(prepared):
+                    for vv in views:
+                        if vv["view_id"] > 0 and vv["semantic_tensor"] is not None:
+                            aug_tensors.append(vv["semantic_tensor"])
+                            aug_keys.append((pi, vv["view_id"]))
+                for astart in range(0, len(aug_tensors), bsz):
+                    aa = torch.stack(aug_tensors[astart:astart + bsz]).float()
+                    yy = runtime.infer(aa)
+                    for off in range(len(yy)):
+                        semantic_aug[aug_keys[astart + off]] = yy[off]
+
+
+            flat_views = []
+            smaps = []
+            cmaps = []
+            for pi, (r, _, views) in enumerate(prepared):
+                for vv in views:
+                    flat_views.append((pi, r, vv))
+                    smaps.append(torch.from_numpy(vv["spectral_map"])[None])
+                    cmaps.append(torch.from_numpy(vv["camera_map"])[None])
+            ss = _specialist_batch_scores(
+                spec,
+                cam,
+                torch.stack(smaps).float(),
+                torch.stack(cmaps).float(),
+            )
+
+            for i, (pi, r, vv) in enumerate(flat_views):
+                v = int(vv["view_id"])
+                sem = semantic_base[pi] if (v == 0 or reuse_sem) else semantic_aug[(pi, v)]
+                h = vv["handcrafted"]
+                store["semantic"].append(sem)
+                store["camera"].append(h["camera"])
+                store["spectral"].append(h["spectral"])
+                store["patch"].append(h["patch"])
+                store["quality"].append(h["quality"])
+                store["specialist"].append(ss[i])
+                store["label"].append(int(r["label"]))
+                store["source"].append(str(r.get("source", "unknown")))
+                store["path"].append(str(r["path"]))
+                store["split"].append(str(r.get("split", "train")))
+                store["view_id"].append(v)
+                store["light_bucket"].append(str(r.get("light_bucket", "unknown")))
+                store["mean_luma"].append(float(h["quality"][0]))
+    finally:
+        if executor is not None:
+            executor.shutdown(wait=True)
+        runtime.release_accelerator_memory()
+
+    arrays = {}
+    for k, v in store.items():
+        if k in {"semantic", "camera", "spectral", "patch", "quality", "specialist"}:
+            dtype = np.float16 if (k == "semantic" and bool(fc.get("cache_semantic_float16", True))) else np.float32
+            arrays[k] = np.stack(v).astype(dtype)
+        elif k in {"label", "view_id"}:
+            arrays[k] = np.asarray(v, dtype=np.int64)
+        elif k == "mean_luma":
+            arrays[k] = np.asarray(v, dtype=np.float32)
+        else:
+            arrays[k] = np.asarray(v, dtype=str)
+
+
+    if bool(fc.get("compress_feature_cache", False)):
+        np.savez_compressed(p, **arrays)
+    else:
+        np.savez(p, **arrays)
+
+    meta = {
+        "version": 5,
+        "foundation_requested": fc.get("backend"),
+        "foundation_actual": foundation.backend,
+        "foundation_runtime": runtime.backend,
+        "foundation_dim": int(foundation.dim),
+        "foundation_state": str(foundation_state_path.resolve()),
+        "specialists": str(Path(specialists_path).resolve()),
+        "augment_copies": int(augment_copies),
+        "augment_selected_images": int(len(augment_paths)),
+        "augment_max_per_class": int(augment_cap),
+        "reuse_semantic_for_augmented_views": reuse_sem,
+        "unique_images": int(total_unique),
+        "input_unique_images": int(input_unique),
+        "train_cap_per_class": int(train_cap),
+        "train_coreset": bool(fc.get("train_coreset", False)),
+        "count": int(len(arrays["label"])),
+        "dims": {k: int(arrays[k].shape[1]) for k in ["semantic", "camera", "spectral", "patch", "quality", "specialist"]},
+    }
+    p.with_suffix(p.suffix + ".meta.json").write_text(json.dumps(meta, indent=2, ensure_ascii=False), encoding="utf-8")
+    print(
+        f"[saved] {p} ({meta['count']} views from {meta['unique_images']} unique images, "
+        f"foundation={foundation.backend}, runtime={runtime.backend}, reuse_aug_semantic={reuse_sem})"
+    )
+    return meta
+
+
+def load_cache(path: str) -> dict[str, np.ndarray]:
+    z = np.load(path, allow_pickle=False)
+    return {k: z[k] for k in z.files}

raven/calibration.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+import numpy as np
+from sklearn.linear_model import LogisticRegression
+
+
+class MetaCalibrator:
+
+    def __init__(self,coef,intercept,mean=None,std=None):
+        coef=np.asarray(coef,np.float64)
+        if coef.ndim==1: coef=coef[None,:]
+        intercept=np.asarray(intercept,np.float64).reshape(-1)
+        if len(intercept)==1 and coef.shape[0]>1: intercept=np.repeat(intercept,coef.shape[0])
+        self.coef=coef; self.intercept=intercept
+        d=coef.shape[1]
+        self.mean=np.zeros(d,np.float64) if mean is None else np.asarray(mean,np.float64).reshape(-1)
+        self.std=np.ones(d,np.float64) if std is None else np.maximum(np.asarray(std,np.float64).reshape(-1),1e-8)
+
+    @staticmethod
+    def _balanced_standardization(x,y):
+        x=np.asarray(x,np.float64); y=np.asarray(y,int)
+        m0=x[y==0]; m1=x[y==1]
+        mean=.5*m0.mean(0)+.5*m1.mean(0)
+
+        second=.5*(m0*m0).mean(0)+.5*(m1*m1).mean(0)
+        std=np.sqrt(np.maximum(second-mean*mean,1e-8))
+        return mean,std
+
+    @classmethod
+    def fit(cls,x:np.ndarray,y:np.ndarray,bootstraps:int=15,seed:int=1337):
+        x=np.asarray(x,np.float64); y=np.asarray(y,int)
+        i0=np.where(y==0)[0]; i1=np.where(y==1)[0]
+        if len(i0)<4 or len(i1)<4: raise ValueError("Calibration requires both REAL and AI validation examples.")
+        mean,std=cls._balanced_standardization(x,y); z=(x-mean)/std
+        n=min(len(i0),len(i1)); rng=np.random.default_rng(seed); coefs=[]; intercepts=[]
+        for b in range(max(3,int(bootstraps))):
+
+            a=rng.choice(i0,size=n,replace=True); c=rng.choice(i1,size=n,replace=True); idx=np.r_[a,c]; rng.shuffle(idx)
+            m=LogisticRegression(C=.35,max_iter=3000,solver="lbfgs")
+            m.fit(z[idx],y[idx]); coefs.append(m.coef_[0]); intercepts.append(m.intercept_[0])
+        return cls(np.stack(coefs),np.asarray(intercepts),mean,std)
+
+    def _member_probs(self,x):
+        z=(np.asarray(x,np.float64)-self.mean)/self.std
+        logits=z@self.coef.T+self.intercept[None,:]; logits=np.clip(logits,-40,40)
+        return 1/(1+np.exp(-logits))
+
+    def predict_proba(self,x): return self._member_probs(x).mean(1)
+
+    def predict_stats(self,x,lower_q=.10,upper_q=.90):
+        p=self._member_probs(x)
+        return {
+            "mean":p.mean(1),"std":p.std(1),
+            "lower":np.quantile(p,float(lower_q),axis=1),
+            "upper":np.quantile(p,float(upper_q),axis=1),
+        }
+
+    def to_dict(self):
+        return {"version":2,"prior":"balanced_0.5_0.5","coef":self.coef.astype(np.float32),"intercept":self.intercept.astype(np.float32),"mean":self.mean.astype(np.float32),"std":self.std.astype(np.float32)}
+
+    @classmethod
+    def from_dict(cls,d): return cls(d["coef"],d["intercept"],d.get("mean"),d.get("std"))
+
+
+def meta_features(logit_mean,logit_std,branch_mean,gates_mean,anchors,specialist,quality=None):
+
+
+    return np.concatenate([
+        np.asarray(logit_mean).reshape(-1,1),np.asarray(logit_std).reshape(-1,1),
+        np.asarray(branch_mean),np.asarray(gates_mean),np.asarray(anchors),np.asarray(specialist),
+    ],axis=1).astype(np.float32)
+
+
+def select_thresholds(y,probs,cfg):
+    y=np.asarray(y,int); p=np.asarray(probs,np.float64); real=p[y==0]; ai=p[y==1]
+    if len(real)<5 or len(ai)<5: return .25,.75
+    far=float(cfg.get("target_false_ai_rate",.015)); frr=float(cfg.get("target_false_real_rate",.04))
+
+    ai_thr=float(np.quantile(real,np.clip(1-far,0,1))); real_thr=float(np.quantile(ai,np.clip(frr,0,1)))
+    ai_thr=max(ai_thr,float(cfg.get("minimum_ai_threshold",.72))); real_thr=min(real_thr,float(cfg.get("maximum_real_threshold",.28)))
+    if real_thr>=ai_thr: real_thr,ai_thr=.25,.75
+    return real_thr,ai_thr

raven/cli.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+import argparse,json
+from pathlib import Path
+import torch
+from .config import load_config
+from .utils import read_jsonl
+from .manifest import build_manifest,manifest_summary
+from .audit import audit_manifest
+from .specialists import train_real_specialists
+from .cache import cache_features
+from .training import train_fusion
+from .evaluate import evaluate_cache
+from .inference import infer_image
+from .hard_mining import mine_hard
+from .onnx_export import export_fusion,export_foundation
+from .directml_inference import infer_directml
+from .parquet_io import import_parquet,inspect_parquet
+from .model import RavenFusion
+from .diagnose import diagnose
+from .benchmark import benchmark_foundation
+from .budget import plan_budget
+
+
+def pjson(x): print(json.dumps(x,indent=2,ensure_ascii=False))
+
+def cmd_build(a):
+    cfg=load_config(a.config); mc=cfg.get("manifest",{})
+    rows=build_manifest(
+        a.real_dir,a.ai_dir,a.out,a.holdout_source,
+        a.val if a.val is not None else mc.get("val_fraction",.15),
+        a.real_test if a.real_test is not None else mc.get("real_test_fraction",.15),
+        a.dedupe_distance if a.dedupe_distance is not None else mc.get("dedupe_hamming_distance",3),
+        a.parquet_cache_dir,
+        a.real_parquet_image_column,a.real_parquet_source_column,
+        a.ai_parquet_image_column,a.ai_parquet_source_column,
+        a.real_source_name if getattr(a,"real_source_name",None) else mc.get("real_source_name"),
+        a.ai_source_name if getattr(a,"ai_source_name",None) else mc.get("ai_source_name"),
+    ); print(manifest_summary(rows))
+def cmd_report(a): print(manifest_summary(read_jsonl(a.manifest)))
+def cmd_audit(a): pjson(audit_manifest(read_jsonl(a.manifest), load_config(a.config) if getattr(a,"config",None) else None))
+def cmd_pretrain(a): pjson(train_real_specialists(read_jsonl(a.manifest),load_config(a.config),a.out))
+def cmd_cache(a): pjson(cache_features(read_jsonl(a.manifest),load_config(a.config),a.specialists,a.out,a.augment_copies))
+def cmd_train(a): pjson(train_fusion(a.cache,load_config(a.config),a.out))
+def cmd_eval(a):
+    r=evaluate_cache(a.model,a.cache,a.split); pjson({"total":r["total"],"by_source":r["by_source"],"by_light":r["by_light"]})
+    if a.report_json: Path(a.report_json).write_text(json.dumps(r,indent=2,ensure_ascii=False),encoding="utf-8")
+def cmd_infer(a): pjson(infer_image(a.model,a.image))
+def cmd_mine(a): pjson(mine_hard(a.model,a.cache,a.out,a.split,a.confidence))
+def cmd_expf(a): print(export_fusion(a.model,a.out))
+def cmd_expb(a): print(export_foundation(a.model,a.out))
+def cmd_dml(a): pjson(infer_directml(a.model,a.foundation_onnx,a.fusion_onnx,a.image,a.cpu_only))
+def cmd_parquet(a): pjson(import_parquet(a.parquet,a.out_dir,a.label,a.source,a.manifest_out,a.image_column))
+def cmd_parquet_info(a): pjson(inspect_parquet(a.parquet))
+def cmd_diag(a): pjson(diagnose())
+def cmd_bench(a): pjson(benchmark_foundation(load_config(a.config),a.accelerator,a.loops))
+def cmd_budget(a): pjson(plan_budget(a.manifest,a.config,a.out,a.target_hours,a.min_hours,a.max_hours,a.accelerator,a.loops))
+
+def cmd_inspect(a):
+    ck=torch.load(a.model,map_location="cpu",weights_only=False); m=RavenFusion(ck["dims"],len(ck.get("ai_source_map",{})),len(ck.get("real_source_map",{}))); total=sum(p.numel() for p in m.parameters()); trainable=sum(p.numel() for p in m.parameters() if p.requires_grad); pjson({"fusion_parameters_per_member":total,"fusion_trainable_per_member":trainable,"ensemble_members":len(ck["ensemble_states"]),"foundation_backend":ck["foundation_backend"],"foundation_parameters_not_stored_in_fusion_count":True,"calibration_prior":"50:50 REAL/AI","validation_metrics":ck.get("validation_metrics")})
+
+
+def parser():
+    p=argparse.ArgumentParser(prog="RAVEN-F2K",description="Budget-adaptive AI-generated image detector optimized for i3-12100F / 16GB / RX 570")
+    s=p.add_subparsers(dest="cmd",required=True)
+    q=s.add_parser("build-manifest"); q.add_argument("--real-dir",required=True,help="REAL image directory OR a .parquet file; directories may also contain parquet files"); q.add_argument("--ai-dir",required=True,help="AI image directory OR a .parquet file; directories may also contain parquet files"); q.add_argument("--out",default="manifest.jsonl"); q.add_argument("--config",default="configs/raven_f2k_rx570.yaml"); q.add_argument("--holdout-source",nargs="*",default=[]); q.add_argument("--ai-source-name",help="Force every AI file to one generator/source label, e.g. gpt-image-2. Original folder label is preserved as raw_source."); q.add_argument("--real-source-name",help="Optional forced REAL source label."); q.add_argument("--val",type=float); q.add_argument("--real-test",type=float); q.add_argument("--dedupe-distance",type=int); q.add_argument("--parquet-cache-dir",default="cache/parquet_materialized"); q.add_argument("--real-parquet-image-column"); q.add_argument("--real-parquet-source-column"); q.add_argument("--ai-parquet-image-column"); q.add_argument("--ai-parquet-source-column"); q.set_defaults(func=cmd_build)
+    q=s.add_parser("report"); q.add_argument("--manifest",required=True); q.set_defaults(func=cmd_report)
+    q=s.add_parser("audit"); q.add_argument("--manifest",required=True); q.add_argument("--config",default="configs/raven_f2k_rx570_3to6h.yaml"); q.set_defaults(func=cmd_audit)
+    q=s.add_parser("pretrain-real"); q.add_argument("--manifest",required=True); q.add_argument("--config",default="configs/raven_f2k_rx570.yaml"); q.add_argument("--out",default="models/real_specialists.pt"); q.set_defaults(func=cmd_pretrain)
+    q=s.add_parser("cache-features"); q.add_argument("--manifest",required=True); q.add_argument("--specialists",default="models/real_specialists.pt"); q.add_argument("--config",default="configs/raven_f2k_rx570.yaml"); q.add_argument("--out",default="cache/features.npz"); q.add_argument("--augment-copies",type=int,default=1); q.set_defaults(func=cmd_cache)
+    q=s.add_parser("train"); q.add_argument("--cache",default="cache/features.npz"); q.add_argument("--config",default="configs/raven_f2k_rx570.yaml"); q.add_argument("--out",default="models/raven_f2k.pt"); q.set_defaults(func=cmd_train)
+    q=s.add_parser("eval"); q.add_argument("--model",default="models/raven_f2k.pt"); q.add_argument("--cache",default="cache/features.npz"); q.add_argument("--split",default="test"); q.add_argument("--report-json",default="outputs/eval.json"); q.set_defaults(func=cmd_eval)
+    q=s.add_parser("infer"); q.add_argument("--model",default="models/raven_f2k.pt"); q.add_argument("--image",required=True); q.set_defaults(func=cmd_infer)
+    q=s.add_parser("mine-hard"); q.add_argument("--model",default="models/raven_f2k.pt"); q.add_argument("--cache",default="cache/features.npz"); q.add_argument("--split",default="test"); q.add_argument("--confidence",type=float,default=.80); q.add_argument("--out",default="outputs/hard.jsonl"); q.set_defaults(func=cmd_mine)
+    q=s.add_parser("export-fusion-onnx"); q.add_argument("--model",default="models/raven_f2k.pt"); q.add_argument("--out",default="models/raven_fusion.onnx"); q.set_defaults(func=cmd_expf)
+    q=s.add_parser("export-foundation-onnx"); q.add_argument("--model",default="models/raven_f2k.pt"); q.add_argument("--out",default="models/raven_foundation.onnx"); q.set_defaults(func=cmd_expb)
+    q=s.add_parser("infer-directml"); q.add_argument("--model",default="models/raven_f2k.pt"); q.add_argument("--foundation-onnx",default="models/raven_foundation.onnx"); q.add_argument("--fusion-onnx",default="models/raven_fusion.onnx"); q.add_argument("--image",required=True); q.add_argument("--cpu-only",action="store_true"); q.set_defaults(func=cmd_dml)
+    q=s.add_parser("import-parquet"); q.add_argument("--parquet",required=True); q.add_argument("--out-dir",required=True); q.add_argument("--label",type=int,choices=[0,1],required=True); q.add_argument("--source",required=True); q.add_argument("--manifest-out",default="outputs/parquet_import.jsonl"); q.add_argument("--image-column",default="image"); q.set_defaults(func=cmd_parquet)
+    q=s.add_parser("parquet-info"); q.add_argument("--parquet",required=True); q.set_defaults(func=cmd_parquet_info)
+    q=s.add_parser("inspect-model"); q.add_argument("--model",default="models/raven_f2k.pt"); q.set_defaults(func=cmd_inspect)
+    q=s.add_parser("diagnose"); q.set_defaults(func=cmd_diag)
+    q=s.add_parser("benchmark-foundation"); q.add_argument("--config",default="configs/raven_f2k_rx570.yaml"); q.add_argument("--accelerator",choices=["auto","directml","openvino","torch"],default="auto"); q.add_argument("--loops",type=int,default=5); q.set_defaults(func=cmd_bench)
+    q=s.add_parser("plan-budget"); q.add_argument("--manifest",required=True); q.add_argument("--config",default="configs/raven_f2k_rx570_3to6h.yaml"); q.add_argument("--out",default="configs/auto_3to6h.yaml"); q.add_argument("--target-hours",type=float,default=4.5); q.add_argument("--min-hours",type=float,default=3.0); q.add_argument("--max-hours",type=float,default=6.0); q.add_argument("--accelerator",choices=["auto","directml","openvino","torch"],default="auto"); q.add_argument("--loops",type=int,default=4); q.set_defaults(func=cmd_budget)
+    return p
+
+
+def main():
+    a=parser().parse_args(); a.func(a)

raven/config.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+from pathlib import Path
+import yaml
+
+
+def load_config(path: str | Path) -> dict:
+    p = Path(path)
+    with p.open("r", encoding="utf-8") as f:
+        cfg = yaml.safe_load(f)
+    if not isinstance(cfg, dict):
+        raise ValueError(f"Invalid YAML config: {p}")
+    return cfg

raven/dataset.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+from collections import Counter, defaultdict
+import math
+import numpy as np
+import torch
+from torch.utils.data import Dataset, Sampler
+
+BRANCH_KEYS=("semantic","camera","spectral","patch","specialist")
+
+
+class FeatureNormalizer:
+    def __init__(self,stats:dict): self.stats=stats
+    @classmethod
+    def fit(cls,cache:dict,mask:np.ndarray):
+
+        stats={}; labels=np.asarray(cache["label"])[mask]
+        for k in BRANCH_KEYS:
+            x=np.asarray(cache[k][mask],np.float64); x0=x[labels==0]; x1=x[labels==1]
+            if len(x0) and len(x1):
+                mean=.5*x0.mean(0)+.5*x1.mean(0); second=.5*(x0*x0).mean(0)+.5*(x1*x1).mean(0); std=np.sqrt(np.maximum(second-mean*mean,1e-10))
+            else:
+                mean=x.mean(0); std=x.std(0)
+            stats[k]={"mean":mean.astype(np.float32),"std":np.maximum(std,1e-5).astype(np.float32)}
+        return cls(stats)
+    def transform(self,k:str,x:np.ndarray)->np.ndarray:
+        s=self.stats[k]; return ((np.asarray(x,np.float32)-s["mean"])/s["std"]).astype(np.float32)
+    def to_dict(self): return self.stats
+    @classmethod
+    def from_dict(cls,d): return cls({k:{"mean":np.asarray(v["mean"],np.float32),"std":np.asarray(v["std"],np.float32)} for k,v in d.items()})
+
+
+class CachedFeatureDataset(Dataset):
+    def __init__(self,cache:dict,indices:np.ndarray,normalizer:FeatureNormalizer,anchor_scores:np.ndarray,ai_source_map:dict[str,int],real_source_map:dict[str,int]):
+        self.cache=cache; self.indices=np.asarray(indices,dtype=np.int64); self.norm=normalizer; self.anchor_scores=anchor_scores; self.ai_source_map=ai_source_map; self.real_source_map=real_source_map
+    def __len__(self): return len(self.indices)
+    def __getitem__(self,i):
+        j=int(self.indices[i]); label=int(self.cache["label"][j]); source=str(self.cache["source"][j])
+        out={k:torch.from_numpy(self.norm.transform(k,self.cache[k][j])) for k in BRANCH_KEYS}
+        out.update({
+            "quality":torch.from_numpy(np.asarray(self.cache["quality"][j],np.float32)),
+            "anchors":torch.from_numpy(np.asarray(self.anchor_scores[j],np.float32)),
+            "luma":torch.tensor(float(self.cache["mean_luma"][j]),dtype=torch.float32),
+            "label":torch.tensor(float(label),dtype=torch.float32),
+            "ai_domain":torch.tensor(self.ai_source_map.get(source,-1) if label==1 else -1,dtype=torch.long),
+            "real_domain":torch.tensor(self.real_source_map.get(source,-1) if label==0 else -1,dtype=torch.long),
+            "source":source,"path":str(self.cache["path"][j]),"view_id":int(self.cache["view_id"][j]),"index":j,
+        })
+        return out
+
+
+def make_source_maps(cache:dict,train_mask:np.ndarray):
+    labels=cache["label"]; sources=cache["source"]
+    ai=sorted({str(sources[i]) for i in np.where(train_mask & (labels==1))[0]}); real=sorted({str(sources[i]) for i in np.where(train_mask & (labels==0))[0]})
+    return {s:i for i,s in enumerate(ai)},{s:i for i,s in enumerate(real)}
+
+
+class ClassBalancedSourceSampler(Sampler[int]):
+
+    def __init__(self, ds:CachedFeatureDataset, max_minority_oversample_factor:float=2.0, seed:int=1337):
+        self.ds=ds; self.factor=max(1.0,float(max_minority_oversample_factor)); self.seed=int(seed); self.epoch=0
+        class_source=defaultdict(lambda:defaultdict(list))
+        for local_i,j in enumerate(ds.indices):
+            label=int(ds.cache["label"][j]); source=str(ds.cache["source"][j]); class_source[label][source].append(local_i)
+        if 0 not in class_source or 1 not in class_source:
+            raise ValueError("Balanced sampler requires both REAL(label=0) and AI(label=1) in the training split.")
+        self.groups={c:{s:np.asarray(v,dtype=np.int64) for s,v in d.items()} for c,d in class_source.items()}
+        counts={c:sum(len(v) for v in d.values()) for c,d in self.groups.items()}
+        minority=min(counts[0],counts[1]); majority=max(counts[0],counts[1])
+        self.per_class=int(min(majority,max(minority,math.ceil(minority*self.factor))))
+        self.length=self.per_class*2
+
+    def __len__(self): return self.length
+
+    def _draw_class(self, cls:int, n:int, rng:np.random.Generator) -> np.ndarray:
+
+        source_names=list(self.groups[cls].keys())
+        queues={s:rng.permutation(self.groups[cls][s]) for s in source_names}
+        pos={s:0 for s in source_names}
+        result=np.empty(n,dtype=np.int64)
+
+        written=0
+        while written<n:
+            order=list(source_names); rng.shuffle(order)
+            for s in order:
+                if written>=n: break
+                q=queues[s]; i=pos[s]
+                if i>=len(q):
+                    q=rng.permutation(self.groups[cls][s]); queues[s]=q; i=0
+                result[written]=int(q[i]); pos[s]=i+1; written+=1
+        return result
+
+    def __iter__(self):
+        rng=np.random.default_rng(self.seed+self.epoch*1009); self.epoch+=1
+        real=self._draw_class(0,self.per_class,rng); ai=self._draw_class(1,self.per_class,rng)
+        pair_order=rng.permutation(self.per_class)
+        seq=[]
+        for k in pair_order:
+            if rng.random()<0.5: seq.extend((int(real[k]),int(ai[k])))
+            else: seq.extend((int(ai[k]),int(real[k])))
+        return iter(seq)
+
+
+def balanced_sampler(ds:CachedFeatureDataset,max_minority_oversample_factor:float=2.0,seed:int=1337):
+    return ClassBalancedSourceSampler(ds,max_minority_oversample_factor,seed)

raven/diagnose.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+import os
+import platform
+import sys
+import torch
+
+
+def diagnose() -> dict:
+    out={
+        "python":sys.version.split()[0],
+        "platform":platform.platform(),
+        "machine":platform.machine(),
+        "logical_cpus":os.cpu_count(),
+        "torch":torch.__version__,
+        "torch_cuda_available":bool(torch.cuda.is_available()),
+        "torch_cuda_version":torch.version.cuda,
+        "mkldnn_available":bool(torch.backends.mkldnn.is_available()),
+        "recommended_cache_runtime":"DirectML on RX 570 if available; otherwise OpenVINO CPU; PyTorch fallback",
+    }
+    try:
+        import onnxruntime as ort
+        out["onnxruntime"]=ort.__version__
+        out["onnx_providers"]=ort.get_available_providers()
+        out["directml_ready"]="DmlExecutionProvider" in out["onnx_providers"]
+    except Exception:
+        out["onnxruntime"]=None; out["onnx_providers"]=[]; out["directml_ready"]=False
+    try:
+        import openvino as ov
+        out["openvino"]=getattr(ov,"__version__","installed")
+        out["openvino_devices"]=ov.Core().available_devices
+        out["openvino_ready"]="CPU" in out["openvino_devices"]
+    except Exception:
+        out["openvino"]=None; out["openvino_devices"]=[]; out["openvino_ready"]=False
+    try:
+        import pyarrow
+        out["pyarrow"]=pyarrow.__version__; out["parquet_ready"]=True
+    except Exception:
+        out["pyarrow"]=None; out["parquet_ready"]=False
+    return out

raven/directml_inference.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+import numpy as np
+import torch
+import torch.nn.functional as F
+from .onnx_runtime import open_session,run_foundation,run_fusion
+from .transforms import foundation_transform
+from .forensic_features import load_rgb,extract_handcrafted,spectral_map,camera_residual_map
+from .specialists import load_specialists_checkpoint
+from .dataset import FeatureNormalizer,BRANCH_KEYS
+from .anchors import AnchorSet
+from .calibration import MetaCalibrator,meta_features
+from .provenance import inspect_provenance
+from .model import RavenFusion
+
+
+def _specialist(im,ck):
+    spec,cam,sck=load_specialists_checkpoint(ck,"cpu"); size=int(sck["map_size"]); sm=torch.from_numpy(spectral_map(im,size)[None,None]).float(); cm=torch.from_numpy(camera_residual_map(im,size)[None,None]).float()
+    with torch.inference_mode():
+        ps=spec(sm); pc=cam(cm)
+        def m(pred,target):
+            err=torch.abs(pred-target); flat=err.flatten(1); return [float(flat.mean()),float(((pred-target)**2).flatten(1).mean()),float(1-F.cosine_similarity(pred.flatten(1),target.flatten(1),dim=1).mean()),float(torch.quantile(flat,.90))]
+        return np.asarray(m(ps,sm)+m(pc,cm),np.float32)
+
+
+def infer_directml(model_path:str,foundation_onnx:str,fusion_onnx:str,image_path:str,cpu_only:bool=False):
+    ck=torch.load(model_path,map_location="cpu",weights_only=False); im=load_rgb(image_path); tf=foundation_transform(224); x=tf(im)[None].numpy().astype(np.float32)
+    fs=open_session(foundation_onnx,prefer_directml=not cpu_only); fus=open_session(fusion_onnx,prefer_directml=not cpu_only); sem=run_foundation(fs,x)[0].astype(np.float32)
+    h=extract_handcrafted(im,ck["config"]["features"]); sp=_specialist(im,ck["specialists_checkpoint"]); raw={"semantic":sem,"camera":h["camera"],"spectral":h["spectral"],"patch":h["patch"],"specialist":sp}
+    norm=FeatureNormalizer.from_dict(ck["normalizer"]); anchors=AnchorSet.from_dict(ck["anchors"]); nf={k:norm.transform(k,raw[k])[None] for k in BRANCH_KEYS}; anch=anchors.score({k:raw[k][None] for k in BRANCH_KEYS}); q=h["quality"][None].astype(np.float32); luma=np.asarray([float(h["quality"][0])],np.float32)
+    oo=run_fusion(fus,{**nf,"quality":q,"anchors":anch,"luma":luma}); mx=meta_features(oo["logit_mean"],oo["logit_std"],oo["branch_mean"],oo["gates_mean"],anch,sp[None],q); cs=MetaCalibrator.from_dict(ck["calibrator"]).predict_stats(mx); prob=float(cs["mean"][0]); pstd=float(cs["std"][0]); plo=float(cs["lower"][0]); phi=float(cs["upper"][0]); rt=float(ck["real_threshold"]); at=float(ck["ai_threshold"]); prov=inspect_provenance(image_path)
+    if prov.get("ai_provenance"): verdict="AI"; reason="verified provenance"
+    elif plo>=at: verdict="AI"; reason="balanced calibration interval is above AI threshold"
+    elif phi<=rt: verdict="REAL"; reason="balanced calibration interval is below REAL threshold"
+    else: verdict="UNCERTAIN"; reason="calibration interval overlaps the decision region"
+    gates=np.asarray(oo["gates_mean"])[0]; branches=1/(1+np.exp(-np.asarray(oo["branch_mean"])[0])); names=list(RavenFusion.BRANCHES)
+    return {"verdict":verdict,"balanced_ai_probability":prob,"balanced_real_probability":1-prob,"ai_probability":prob,"probability_definition":"50:50 REAL/AI prior; not inflated by dataset counts","calibration_std":pstd,"balanced_ai_probability_interval_80":[plo,phi],"reason":reason,"providers":{"foundation":fs.get_providers(),"fusion":fus.get_providers()},"thresholds":{"REAL_max":rt,"AI_min":at},"routing_weights":{n:float(gates[i]) for i,n in enumerate(names)},"branch_evidence":{n:float(branches[i]) for i,n in enumerate(names)},"provenance":prov}

raven/evaluate.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+import json
+import numpy as np
+import torch
+from torch.utils.data import DataLoader
+from .cache import load_cache
+from .anchors import AnchorSet
+from .dataset import FeatureNormalizer,CachedFeatureDataset
+from .model import RavenFusion
+from .training import collect_ensemble
+from .calibration import MetaCalibrator,meta_features
+from .metrics import selective_metrics,group_report
+
+
+def evaluate_cache(model_path:str,cache_path:str,split:str="test"):
+    ck=torch.load(model_path,map_location="cpu",weights_only=False); cache=load_cache(cache_path); mask=(cache["split"]==split)&(cache["view_id"]==0); idx=np.where(mask)[0]
+    if not len(idx): raise ValueError(f"No original-view samples in split={split}")
+    norm=FeatureNormalizer.from_dict(ck["normalizer"]); anchors=AnchorSet.from_dict(ck["anchors"]); anch=anchors.score(cache)
+    ds=CachedFeatureDataset(cache,idx,norm,anch,ck.get("ai_source_map",{}),ck.get("real_source_map",{})); loader=DataLoader(ds,batch_size=256,shuffle=False,num_workers=0)
+    models=[]
+    for st in ck["ensemble_states"]:
+        m=RavenFusion(ck["dims"],len(ck.get("ai_source_map",{})),len(ck.get("real_source_map",{}))); m.load_state_dict(st); m.eval(); models.append(m)
+    ens=collect_ensemble(models,loader,torch.device("cpu")); ii=ens["indices"]; mx=meta_features(ens["logit_mean"],ens["logit_std"],ens["branch_mean"],ens["gates_mean"],anch[ii],cache["specialist"][ii],cache["quality"][ii]); cstats=MetaCalibrator.from_dict(ck["calibrator"]).predict_stats(mx); probs=cstats["mean"]; lower=cstats["lower"]; upper=cstats["upper"]
+    rt=float(ck["real_threshold"]); at=float(ck["ai_threshold"]); total=selective_metrics(ens["labels"],probs,rt,at,lower,upper)
+    by_source=group_report(ens["labels"],probs,ens["sources"],rt,at,lower,upper); by_light=group_report(ens["labels"],probs,cache["light_bucket"][ii],rt,at,lower,upper)
+    pred=[]
+    for j,p,lo,hi,sd in zip(ii,probs,lower,upper,cstats["std"]):
+        verdict="AI" if lo>=at else ("REAL" if hi<=rt else "UNCERTAIN")
+        pred.append({"index":int(j),"path":str(cache["path"][j]),"label":int(cache["label"][j]),"source":str(cache["source"][j]),"light_bucket":str(cache["light_bucket"][j]),"balanced_ai_probability":float(p),"calibration_std":float(sd),"probability_interval_80":[float(lo),float(hi)],"verdict":verdict})
+    return {"total":total,"by_source":by_source,"by_light":by_light,"predictions":pred}

raven/forensic_features.py

@@ -0,0 +1,210 @@
+from __future__ import annotations
+import math
+from pathlib import Path
+import numpy as np
+from PIL import Image, ImageOps, ImageFilter
+import torch
+import torch.nn.functional as F
+
+
+def load_rgb(path: str | Path) -> Image.Image:
+    with Image.open(path) as im:
+        return ImageOps.exif_transpose(im).convert("RGB")
+
+
+def canonical_analysis_image(im: Image.Image, side: int) -> Image.Image:
+
+    x = ImageOps.exif_transpose(im).convert("RGB")
+    w, h = x.size
+    crop = max(1, min(w, h))
+    left = max(0, (w - crop) // 2); top = max(0, (h - crop) // 2)
+    x = x.crop((left, top, left + crop, top + crop))
+    if x.size != (side, side):
+        x = x.resize((side, side), Image.Resampling.LANCZOS)
+    return x
+
+
+def _rgb_array(im: Image.Image, max_side: int = 384) -> np.ndarray:
+
+    x = canonical_analysis_image(im, int(max_side))
+    return np.asarray(x, dtype=np.float32) / 255.0
+
+
+def _gray(a: np.ndarray) -> np.ndarray:
+    return a[..., 0] * 0.299 + a[..., 1] * 0.587 + a[..., 2] * 0.114
+
+
+def _entropy01(x: np.ndarray, bins: int = 64) -> float:
+    hist, _ = np.histogram(np.clip(x, 0, 1), bins=bins, range=(0, 1), density=False)
+    p = hist.astype(np.float64); p /= max(1.0, p.sum()); p = p[p > 0]
+    return float(-(p * np.log2(p)).sum() / math.log2(bins)) if len(p) else 0.0
+
+
+def quality_features(im: Image.Image) -> np.ndarray:
+    a = _rgb_array(im, 256); y = _gray(a)
+    gx = np.diff(y, axis=1); gy = np.diff(y, axis=0)
+    edge = (float(np.mean(np.abs(gx))) + float(np.mean(np.abs(gy)))) * 0.5
+    sat = a.max(-1) - a.min(-1)
+    w, h = im.size
+    feats = [
+        float(y.mean()), float(y.std()), float(np.quantile(y, .05)), float(np.quantile(y, .95)),
+        float((y < .08).mean()), float((y < .18).mean()), float((y > .92).mean()),
+        float(sat.mean()), edge, _entropy01(y),
+        0.0, 0.0,
+    ]
+    return np.asarray(feats, dtype=np.float32)
+
+
+def spectral_map(im: Image.Image, size: int = 64) -> np.ndarray:
+    a = _rgb_array(im, 320); y = _gray(a)
+    f = np.fft.fftshift(np.fft.fft2(y))
+    mag = np.log1p(np.abs(f)).astype(np.float32)
+    mag = (mag - mag.mean()) / (mag.std() + 1e-6)
+    mag = np.clip(mag, -5, 5)
+    p = Image.fromarray(mag, mode="F").resize((size, size), Image.Resampling.BILINEAR)
+    out = np.asarray(p, dtype=np.float32)
+    return out / 5.0
+
+
+def camera_residual_map(im: Image.Image, size: int = 64) -> np.ndarray:
+    small = canonical_analysis_image(im, 320)
+    gray = small.convert("L")
+    blur = gray.filter(ImageFilter.GaussianBlur(radius=1.15))
+    a = np.asarray(gray, dtype=np.float32) / 255.0
+    b = np.asarray(blur, dtype=np.float32) / 255.0
+    r = a - b
+    scale = np.quantile(np.abs(r), .98) + 1e-6
+    r = np.clip(r / scale, -1, 1).astype(np.float32)
+    p = Image.fromarray(r, mode="F").resize((size, size), Image.Resampling.BILINEAR)
+    return np.asarray(p, dtype=np.float32).copy()
+
+
+def _radial_profile(mag: np.ndarray, bins: int) -> np.ndarray:
+    h, w = mag.shape
+    yy, xx = np.indices((h, w))
+    cy, cx = (h-1)/2.0, (w-1)/2.0
+    rr = np.sqrt(((yy-cy)/(max(1,h)/2.0))**2 + ((xx-cx)/(max(1,w)/2.0))**2)
+    edges = np.linspace(0, math.sqrt(2), bins+1)
+    out = np.zeros(bins, np.float32)
+    for i in range(bins):
+        mask = (rr >= edges[i]) & (rr < edges[i+1])
+        if mask.any(): out[i] = float(mag[mask].mean())
+    out -= out.mean(); out /= out.std() + 1e-6
+    return out
+
+
+def _angular_profile(mag: np.ndarray, bins: int) -> np.ndarray:
+    h, w = mag.shape; yy, xx = np.indices((h, w)); cy, cx = (h-1)/2.0, (w-1)/2.0
+    theta = np.arctan2(yy-cy, xx-cx) + np.pi
+    edges = np.linspace(0, 2*np.pi, bins+1)
+    out = np.zeros(bins, np.float32)
+    for i in range(bins):
+        mask = (theta >= edges[i]) & (theta < edges[i+1])
+        if mask.any(): out[i] = float(mag[mask].mean())
+    out -= out.mean(); out /= out.std() + 1e-6
+    return out
+
+
+def spectral_features(im: Image.Image, radial_bins: int = 32, angular_bins: int = 8) -> np.ndarray:
+    a = _rgb_array(im, 320); y = _gray(a)
+    f = np.fft.fftshift(np.fft.fft2(y)); power = np.log1p(np.abs(f)).astype(np.float32)
+    radial = _radial_profile(power, radial_bins); angular = _angular_profile(power, angular_bins)
+    h, w = power.shape; yy, xx = np.indices((h, w)); cy, cx = (h-1)/2.0, (w-1)/2.0
+    rr = np.sqrt(((yy-cy)/(h/2.0))**2 + ((xx-cx)/(w/2.0))**2)
+    low = float(power[rr < .20].mean()) if (rr < .20).any() else 0.0
+    mid = float(power[(rr >= .20) & (rr < .55)].mean()) if ((rr >= .20) & (rr < .55)).any() else 0.0
+    high = float(power[rr >= .55].mean()) if (rr >= .55).any() else 0.0
+    extras = np.asarray([
+        high/(abs(low)+1e-6), mid/(abs(low)+1e-6), high/(abs(mid)+1e-6),
+        float(power.std()), float(np.quantile(power, .95)-np.quantile(power, .05)),
+        float(np.mean(np.abs(np.diff(power, axis=0)))), float(np.mean(np.abs(np.diff(power, axis=1)))),
+    ], dtype=np.float32)
+    return np.concatenate([radial, angular, extras]).astype(np.float32)
+
+
+_LAP_KERNEL = torch.tensor([[[[0,-1,0],[-1,4,-1],[0,-1,0]]]], dtype=torch.float32)
+
+_HP_KERNELS = torch.tensor([
+    [[0,-1,0],[-1,4,-1],[0,-1,0]],
+    [[-1,-1,-1],[0,0,0],[1,1,1]],
+    [[-1,0,1],[-1,0,1],[-1,0,1]],
+    [[-1,0,0],[0,2,0],[0,0,-1]],
+    [[0,0,-1],[0,2,0],[-1,0,0]],
+    [[-1,2,-1],[2,-4,2],[-1,2,-1]],
+    [[1,-2,1],[-2,4,-2],[1,-2,1]],
+    [[0,1,0],[1,-4,1],[0,1,0]],
+], dtype=torch.float32)[:, None]
+
+
+def _moments(v: np.ndarray) -> list[float]:
+    v = np.asarray(v, dtype=np.float64).ravel()
+    sd = float(v.std()) + 1e-8; m = float(v.mean()); z = (v-m)/sd
+    return [float(np.mean(np.abs(v))), sd, float(np.mean(z**4)), float(np.quantile(np.abs(v), .90)), float(np.quantile(np.abs(v), .99))]
+
+
+def camera_features(im: Image.Image) -> np.ndarray:
+    a = _rgb_array(im, 256); y = _gray(a).astype(np.float32)
+    t = torch.from_numpy(y)[None, None]
+    with torch.inference_mode():
+        r = F.conv2d(t, _HP_KERNELS, padding=1)[0].numpy()
+    feats: list[float] = []
+    for i in range(r.shape[0]): feats.extend(_moments(r[i]))
+
+    chans = []
+    for c in range(3):
+        tc = torch.from_numpy(a[..., c].astype(np.float32))[None, None]
+        blur = F.avg_pool2d(tc, 3, 1, 1)
+        chans.append((tc-blur)[0,0].numpy().ravel())
+    for i, j in ((0,1),(0,2),(1,2)):
+        if np.std(chans[i]) > 1e-7 and np.std(chans[j]) > 1e-7:
+            feats.append(float(np.corrcoef(chans[i], chans[j])[0,1]))
+        else: feats.append(0.0)
+
+    residual = y - F.avg_pool2d(t, 3, 1, 1)[0,0].numpy()
+    phase_means = []; phase_stds = []
+    for py in (0,1):
+        for px in (0,1):
+            q = residual[py::2, px::2]
+            phase_means.append(float(np.mean(np.abs(q)))); phase_stds.append(float(np.std(q)))
+    feats.extend(phase_means); feats.extend(phase_stds)
+
+    lum = y.ravel(); noise = np.abs(residual).ravel()
+    if np.std(lum) > 1e-7 and np.std(noise) > 1e-7: feats.append(float(np.corrcoef(lum, noise)[0,1]))
+    else: feats.append(0.0)
+    return np.asarray(feats, dtype=np.float32)
+
+
+def _patch_micro(patch: np.ndarray) -> np.ndarray:
+    y = _gray(patch); gx = np.diff(y, axis=1); gy = np.diff(y, axis=0)
+    t = torch.from_numpy(y.astype(np.float32))[None, None]
+    blur = F.avg_pool2d(t, 3, 1, 1)[0,0].numpy(); res = y - blur
+    lap = F.conv2d(t, _LAP_KERNEL, padding=1)[0,0].numpy()
+    f = np.fft.fftshift(np.fft.fft2(y)); mag = np.abs(f); h,w=mag.shape; yy,xx=np.indices((h,w)); cy,cx=(h-1)/2,(w-1)/2
+    rr=np.sqrt(((yy-cy)/(h/2))**2+((xx-cx)/(w/2))**2); lo=float(mag[rr<.25].mean())+1e-7; hi=float(mag[rr>.60].mean())
+    return np.asarray([
+        float(y.mean()), float(y.std()), _entropy01(y),
+        float(np.mean(np.abs(gx))), float(np.std(gx)), float(np.mean(np.abs(gy))), float(np.std(gy)),
+        float(np.mean(np.abs(res))), float(np.std(res)), float(np.mean(np.abs(lap))), float(np.std(lap)), hi/lo,
+    ], dtype=np.float32)
+
+
+def patch_features(im: Image.Image, patch_count: int = 8, patch_fraction: float = .32) -> np.ndarray:
+    a = _rgb_array(im, 384); h, w, _ = a.shape; short = min(h,w); cs = max(48, min(short, int(short*patch_fraction)))
+    grid = max(1, math.ceil(math.sqrt(patch_count))); xs=np.linspace(0,max(0,w-cs),grid); ys=np.linspace(0,max(0,h-cs),grid)
+    vv=[]
+    for yy in ys:
+        for xx in xs:
+            vv.append(_patch_micro(a[int(yy):int(yy)+cs, int(xx):int(xx)+cs]))
+            if len(vv)>=patch_count: break
+        if len(vv)>=patch_count: break
+    if not vv: vv=[_patch_micro(a)]
+    v=np.stack(vv); return np.concatenate([v.mean(0), v.std(0), v.max(0)]).astype(np.float32)
+
+
+def extract_handcrafted(im: Image.Image, cfg: dict) -> dict[str, np.ndarray]:
+    return {
+        "quality": quality_features(im),
+        "camera": camera_features(im),
+        "spectral": spectral_features(im, int(cfg.get("spectral_radial_bins",32)), int(cfg.get("spectral_angular_bins",8))),
+        "patch": patch_features(im, int(cfg.get("patch_count",8)), float(cfg.get("patch_fraction",.32))),
+    }

raven/foundation.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+import warnings
+import torch
+import torch.nn as nn
+from torchvision.models import convnext_tiny, ConvNeXt_Tiny_Weights
+from .transforms import foundation_transform
+
+
+class FoundationEncoder(nn.Module):
+    def __init__(self, backend: str = "dinov2_vits14", allow_fallback: bool = True, fallback_backend: str = "torchvision_convnext_tiny", pretrained: bool = True):
+        super().__init__()
+        self.requested_backend = backend
+        self.backend = backend
+        self.transform = foundation_transform(224)
+        self.dim = 0
+        try:
+            if backend == "dinov2_vits14":
+                self.model = torch.hub.load("facebookresearch/dinov2", "dinov2_vits14", trust_repo=True, pretrained=pretrained)
+                self.dim = 384
+            elif backend == "torchvision_convnext_tiny":
+                m = convnext_tiny(weights=ConvNeXt_Tiny_Weights.DEFAULT if pretrained else None)
+                m.classifier = nn.Identity()
+                self.model = m
+                self.dim = 768
+            else:
+                raise ValueError(f"Unknown foundation backend: {backend}")
+        except Exception as exc:
+            if not allow_fallback or backend == fallback_backend:
+                raise
+            warnings.warn(f"Foundation '{backend}' unavailable: {exc}. Falling back to {fallback_backend}.")
+            self.backend = fallback_backend
+            if fallback_backend != "torchvision_convnext_tiny":
+                raise ValueError("Only torchvision_convnext_tiny is implemented as fallback")
+            try:
+                m = convnext_tiny(weights=ConvNeXt_Tiny_Weights.DEFAULT if pretrained else None)
+            except Exception as exc2:
+                raise RuntimeError(
+                    "No pretrained foundation weights are available. Connect to the internet once, "
+                    "or pre-populate the torch cache. Random foundation weights are intentionally refused "
+                    "because they invalidate few-shot detection."
+                ) from exc2
+            m.classifier = nn.Identity()
+            self.model = m
+            self.dim = 768
+        for p in self.model.parameters():
+            p.requires_grad = False
+        self.model.eval()
+
+    @torch.inference_mode()
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        y = self.model(x)
+        if isinstance(y, dict):
+            y = y.get("x_norm_clstoken", next(iter(y.values())))
+        if y.ndim > 2:
+            y = y.flatten(1)
+        return y.float()

raven/foundation_runtime.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import gc
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import torch
+import torch.nn as nn
+
+from .foundation import FoundationEncoder
+
+
+class _FoundationWrapper(nn.Module):
+    def __init__(self, enc: FoundationEncoder):
+        super().__init__()
+        self.enc = enc
+
+    def forward(self, x):
+        return self.enc(x)
+
+
+class FoundationRuntime:
+
+
+    def __init__(self, cfg: dict, encoder: FoundationEncoder):
+        self.cfg = cfg
+        self.encoder = encoder
+        self.backend = "torch"
+        self.batch_size = max(1, int(cfg.get("torch_batch_size", 8)))
+        self.runtime_cache = Path(cfg.get("runtime_cache_dir", "cache/foundation_runtime"))
+        self.runtime_cache.mkdir(parents=True, exist_ok=True)
+        self._session: Any = None
+        self._compiled: Any = None
+
+        requested = str(cfg.get("accelerator", "auto")).strip().lower()
+        order = [requested] if requested not in {"auto", ""} else ["directml", "openvino", "torch"]
+
+        errors = []
+        for candidate in order:
+            try:
+                if candidate == "directml":
+                    self._init_directml()
+                elif candidate == "openvino":
+                    self._init_openvino()
+                elif candidate == "torch":
+                    self._init_torch()
+                else:
+                    raise ValueError(f"Unknown foundation accelerator: {candidate}")
+                print(f"[foundation-runtime] {self.backend}, batch={self.batch_size}")
+                break
+            except Exception as exc:
+                errors.append(f"{candidate}: {exc}")
+                self._session = None
+                self._compiled = None
+        else:
+            raise RuntimeError("No foundation runtime could be initialized: " + " | ".join(errors))
+
+    @property
+    def model_backend(self) -> str:
+        return self.encoder.backend
+
+    @property
+    def dim(self) -> int:
+        return int(self.encoder.dim)
+
+    def _fixed_batch_onnx_path(self, batch: int) -> Path:
+        safe = self.encoder.backend.replace("/", "_")
+        return self.runtime_cache / f"{safe}_b{batch}_fixed.onnx"
+
+    def _init_directml(self):
+        import onnxruntime as ort
+
+        available = ort.get_available_providers()
+        if "DmlExecutionProvider" not in available:
+            raise RuntimeError(f"DmlExecutionProvider unavailable; providers={available}")
+
+        batch = max(1, int(self.cfg.get("directml_batch_size", 4)))
+        onnx_path = self._fixed_batch_onnx_path(batch)
+        if not onnx_path.exists():
+            print(f"[foundation-runtime] exporting fixed-batch ONNX once -> {onnx_path}")
+            wrapper = _FoundationWrapper(self.encoder).eval()
+            dummy = torch.randn(batch, 3, 224, 224, dtype=torch.float32)
+            torch.onnx.export(
+                wrapper,
+                dummy,
+                str(onnx_path),
+                input_names=["image"],
+                output_names=["embedding"],
+                opset_version=18,
+                do_constant_folding=True,
+            )
+
+        opts = ort.SessionOptions()
+
+        opts.execution_mode = ort.ExecutionMode.ORT_SEQUENTIAL
+        opts.enable_mem_pattern = False
+        opts.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL
+        self._session = ort.InferenceSession(
+            str(onnx_path),
+            sess_options=opts,
+            providers=["DmlExecutionProvider", "CPUExecutionProvider"],
+        )
+        self.backend = "directml"
+        self.batch_size = batch
+
+    def _init_openvino(self):
+        import openvino as ov
+
+        batch = max(1, int(self.cfg.get("openvino_batch_size", 16)))
+        safe = self.encoder.backend.replace("/", "_")
+        xml = self.runtime_cache / f"{safe}_b{batch}.xml"
+
+        if not xml.exists():
+            print(f"[foundation-runtime] converting to OpenVINO IR once -> {xml}")
+            wrapper = _FoundationWrapper(self.encoder).eval()
+            dummy = torch.randn(batch, 3, 224, 224, dtype=torch.float32)
+            ov_model = ov.convert_model(wrapper, example_input=dummy)
+            ov.save_model(
+                ov_model,
+                str(xml),
+                compress_to_fp16=bool(self.cfg.get("openvino_compress_fp16", True)),
+            )
+
+        core = ov.Core()
+        config = {}
+
+        config["PERFORMANCE_HINT"] = "THROUGHPUT"
+        try:
+            config["INFERENCE_NUM_THREADS"] = int(self.cfg.get("openvino_threads", 6))
+        except Exception:
+            pass
+        try:
+            self._compiled = core.compile_model(str(xml), "CPU", config)
+        except Exception:
+
+            self._compiled = core.compile_model(str(xml), "CPU", {"PERFORMANCE_HINT": "THROUGHPUT"})
+        self.backend = "openvino"
+        self.batch_size = batch
+
+    def _init_torch(self):
+        self.encoder.eval().to("cpu")
+        self.backend = "torch"
+        self.batch_size = max(1, int(self.cfg.get("torch_batch_size", 8)))
+
+    def _pad(self, x: np.ndarray | torch.Tensor) -> tuple[np.ndarray, int]:
+        if isinstance(x, torch.Tensor):
+            a = x.detach().cpu().numpy().astype(np.float32, copy=False)
+        else:
+            a = np.asarray(x, dtype=np.float32)
+        n = int(a.shape[0])
+        if n == self.batch_size:
+            return a, n
+        if n > self.batch_size:
+            raise ValueError(f"Runtime batch {n} exceeds configured fixed batch {self.batch_size}")
+        pad = np.zeros((self.batch_size,) + tuple(a.shape[1:]), dtype=np.float32)
+        pad[:n] = a
+        return pad, n
+
+    @torch.inference_mode()
+    def infer(self, x: torch.Tensor) -> np.ndarray:
+        if self.backend == "torch":
+            return self.encoder(x.float()).cpu().numpy().astype(np.float32)
+
+        a, n = self._pad(x)
+        if self.backend == "directml":
+            y = self._session.run(["embedding"], {"image": a})[0]
+        elif self.backend == "openvino":
+            result = self._compiled([a])
+            y = result[self._compiled.output(0)]
+        else:
+            raise RuntimeError(self.backend)
+        return np.asarray(y[:n], dtype=np.float32)
+
+    def release_accelerator_memory(self):
+
+        self._session = None
+        self._compiled = None
+        gc.collect()

raven/hard_mining.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+from .evaluate import evaluate_cache
+from .utils import write_jsonl
+
+
+def mine_hard(model_path:str,cache_path:str,out_path:str,split:str="test",confidence:float=.80):
+    report=evaluate_cache(model_path,cache_path,split); hard=[]
+    for r in report["predictions"]:
+        p=float(r.get("balanced_ai_probability",r.get("ai_probability",.5))); y=int(r["label"]); v=r["verdict"]
+        wrong_confident=(y==0 and p>=confidence) or (y==1 and p<=1-confidence)
+        uncertain=v=="UNCERTAIN"
+        if wrong_confident or uncertain:
+            x=dict(r); x["hard_type"]="confident_wrong" if wrong_confident else "uncertain"; x["hard_weight"]=2.0 if wrong_confident else 1.35; hard.append(x)
+    write_jsonl(out_path,hard); return {"count":len(hard),"split":split,"output":out_path,"metrics":report["total"]}

raven/inference.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+import json
+from pathlib import Path
+import numpy as np
+import torch
+from .foundation import FoundationEncoder
+from .forensic_features import load_rgb,extract_handcrafted,spectral_map,camera_residual_map
+from .specialists import load_specialists_checkpoint
+from .anchors import AnchorSet
+from .dataset import FeatureNormalizer,BRANCH_KEYS
+from .model import RavenFusion
+from .calibration import MetaCalibrator,meta_features
+from .provenance import inspect_provenance
+from .utils import configure_cpu
+import torch.nn.functional as F
+
+
+def load_detector(path:str):
+    ck=torch.load(path,map_location="cpu",weights_only=False); cfg=ck["config"]; configure_cpu(cfg["hardware"].get("torch_threads",6),cfg["hardware"].get("interop_threads",1))
+    foundation=FoundationEncoder(ck["foundation_backend"],allow_fallback=False,fallback_backend=ck["foundation_backend"],pretrained=ck.get("foundation_state") is None).eval().to("cpu")
+    if ck.get("foundation_state") is not None:
+        foundation.model.load_state_dict(ck["foundation_state"]["state_dict"])
+    if ck.get("specialists_checkpoint") is None: raise ValueError("Detector checkpoint has no embedded real-specialist model. Re-run cache/train with v2 pipeline.")
+    spec,cam,sck=load_specialists_checkpoint(ck["specialists_checkpoint"],"cpu")
+    models=[]
+    for st in ck["ensemble_states"]:
+        m=RavenFusion(ck["dims"],len(ck.get("ai_source_map",{})),len(ck.get("real_source_map",{}))); m.load_state_dict(st); m.eval(); models.append(m)
+    return ck,foundation,(spec,cam,sck),models,FeatureNormalizer.from_dict(ck["normalizer"]),AnchorSet.from_dict(ck["anchors"]),MetaCalibrator.from_dict(ck["calibrator"])
+
+
+def _specialist_score_batch(im,spec,cam,sck):
+    size=int(sck["map_size"]); sm=torch.from_numpy(spectral_map(im,size)[None,None]).float(); cm=torch.from_numpy(camera_residual_map(im,size)[None,None]).float()
+    with torch.inference_mode():
+        ps=spec(sm); pc=cam(cm)
+        def met(pred,target):
+            err=torch.abs(pred-target); flat=err.flatten(1); return [float(flat.mean()),float(((pred-target)**2).flatten(1).mean()),float(1-F.cosine_similarity(pred.flatten(1),target.flatten(1),dim=1).mean()),float(torch.quantile(flat,.90))]
+        return np.asarray(met(ps,sm)+met(pc,cm),np.float32)
+
+
+def extract_single(path:str,ck,foundation,specialists,normalizer,anchors):
+    im=load_rgb(path); h=extract_handcrafted(im,ck["config"]["features"]); sem=None
+    with torch.inference_mode(): sem=foundation(foundation.transform(im)[None].float()).cpu().numpy()[0].astype(np.float32)
+    spec,cam,sck=specialists; sp=_specialist_score_batch(im,spec,cam,sck)
+    raw={"semantic":sem,"camera":h["camera"],"spectral":h["spectral"],"patch":h["patch"],"specialist":sp}
+    norm={k:normalizer.transform(k,raw[k])[None] for k in BRANCH_KEYS}; anch=anchors.score({k:raw[k][None] for k in BRANCH_KEYS})
+    q=h["quality"][None].astype(np.float32); luma=np.asarray([float(h["quality"][0])],np.float32)
+    return raw,norm,anch,q,luma
+
+@torch.inference_mode()
+def infer_image(model_path:str,image_path:str) -> dict:
+    ck,foundation,specialists,models,norm,anchors,cal=load_detector(model_path); raw,features,anch,q,luma=extract_single(image_path,ck,foundation,specialists,norm,anchors)
+    tf={k:torch.from_numpy(v).float() for k,v in features.items()}; tq=torch.from_numpy(q); ta=torch.from_numpy(anch); tl=torch.from_numpy(luma)
+    outs=[m(tf,tq,ta,tl,0.0,False) for m in models]; logits=np.asarray([float(o["logit"][0]) for o in outs],np.float32); branches=np.stack([o["branch_logits"][0].numpy() for o in outs]); gates=np.stack([o["gates"][0].numpy() for o in outs])
+    mx=meta_features(np.asarray([logits.mean()]),np.asarray([logits.std()]),branches.mean(0)[None],gates.mean(0)[None],anch,raw["specialist"][None],q); cstats=cal.predict_stats(mx); prob=float(cstats["mean"][0]); pstd=float(cstats["std"][0]); plo=float(cstats["lower"][0]); phi=float(cstats["upper"][0])
+    prov=inspect_provenance(image_path); rt=float(ck["real_threshold"]); at=float(ck["ai_threshold"])
+    if prov.get("ai_provenance"): verdict="AI"; reason="verified provenance indicates algorithmic generation"
+    elif plo>=at: verdict="AI"; reason="the balanced-prior calibration interval is entirely above the AI threshold"
+    elif phi<=rt: verdict="REAL"; reason="the balanced-prior calibration interval is entirely below the REAL threshold"
+    else: verdict="UNCERTAIN"; reason="calibration uncertainty overlaps the decision region"
+    bnames=list(RavenFusion.BRANCHES); gate_mean=gates.mean(0); branch_prob=1/(1+np.exp(-branches.mean(0)))
+    return {"verdict":verdict,"balanced_ai_probability":prob,"balanced_real_probability":1-prob,"ai_probability":prob,"real_probability":1-prob,"probability_definition":"50:50 REAL/AI prior; not inflated by training file counts","calibration_std":pstd,"balanced_ai_probability_interval_80":[plo,phi],"reason":reason,"ensemble_logit_std":float(logits.std()),"thresholds":{"REAL_max":rt,"AI_min":at},"foundation":ck["foundation_backend"],"mean_luma":float(luma[0]),"darkness":float(np.clip((.25-luma[0])/.25,0,1)),"branch_evidence":{b:float(branch_prob[i]) for i,b in enumerate(bnames)},"routing_weights":{b:float(gate_mean[i]) for i,b in enumerate(bnames)},"real_anchor_z":{b:float(anch[0,i]) for i,b in enumerate(bnames)},"specialist_errors":{"spectral_MAE":float(raw["specialist"][0]),"spectral_MSE":float(raw["specialist"][1]),"spectral_cosine_error":float(raw["specialist"][2]),"spectral_Q90":float(raw["specialist"][3]),"camera_MAE":float(raw["specialist"][4]),"camera_MSE":float(raw["specialist"][5]),"camera_cosine_error":float(raw["specialist"][6]),"camera_Q90":float(raw["specialist"][7])},"provenance":prov}

raven/manifest.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+from collections import Counter
+from pathlib import Path
+import numpy as np
+from PIL import Image, ImageOps
+try:
+    import imagehash
+except Exception:
+    imagehash = None
+from tqdm import tqdm
+from .utils import iter_images, stable_unit, write_jsonl
+from .parquet_io import discover_parquet_files, materialize_parquet
+
+
+def _phash(path: Path, hash_size: int = 12) -> str | None:
+    try:
+        with Image.open(path) as im:
+            im = ImageOps.exif_transpose(im).convert("RGB")
+            if imagehash is not None:
+                return str(imagehash.phash(im, hash_size=hash_size))
+            g = im.convert("L").resize((32, 32), Image.Resampling.LANCZOS)
+            a = np.asarray(g, dtype=np.float32) / 255.0
+            low = np.abs(np.fft.fft2(a))[:hash_size, :hash_size]
+            flat = low.ravel(); med = float(np.median(flat[1:])) if flat.size > 1 else float(flat[0])
+            bits = (flat > med).astype(np.uint8)
+            value = 0
+            for bit in bits: value = (value << 1) | int(bit)
+            width = (len(bits) + 3) // 4
+            return f"{value:0{width}x}"
+    except Exception:
+        return None
+
+
+def _hamming_hex(a: str, b: str) -> int:
+    try: return (int(a, 16) ^ int(b, 16)).bit_count()
+    except Exception: return 9999
+
+
+class _HammingIndex:
+
+    def __init__(self, max_distance:int):
+        self.d=max(0,int(max_distance)); self.values=[]; self.buckets={}
+
+    def _segments(self, value:int, bits:int):
+        parts=max(1,self.d+1); base=bits//parts; rem=bits%parts; shift=0
+        for i in range(parts):
+            width=base+(1 if i<rem else 0); mask=(1<<width)-1
+            yield i,(value>>shift)&mask
+            shift+=width
+
+    def duplicate_or_add(self, ph:str|None)->bool:
+        if not ph or self.d<0: return False
+        try: value=int(ph,16)
+        except Exception: return False
+        bits=max(4,len(ph)*4); cand=set(); segs=list(self._segments(value,bits))
+        for key in segs:
+            cand.update(self.buckets.get(key,()))
+        for idx in cand:
+            if (value^self.values[idx]).bit_count()<=self.d:
+                return True
+        idx=len(self.values); self.values.append(value)
+        for key in segs:
+            self.buckets.setdefault(key,[]).append(idx)
+        return False
+
+def _stats(path: Path) -> dict:
+    try:
+        with Image.open(path) as im:
+            fmt = (im.format or path.suffix.lstrip(".")).upper(); exif = im.getexif(); has_exif = bool(exif)
+            im = ImageOps.exif_transpose(im).convert("RGB"); w, h = im.size
+            tiny = im.copy(); tiny.thumbnail((192, 192)); a = np.asarray(tiny, dtype=np.float32) / 255.0
+            y = a[..., 0] * 0.2126 + a[..., 1] * 0.7152 + a[..., 2] * 0.0722
+            mean = float(y.mean()); std = float(y.std()); dark_fraction = float((y < 0.12).mean())
+            if mean < 0.08: bucket = "extreme-dark"
+            elif mean < 0.20: bucket = "dark"
+            elif mean < 0.38: bucket = "dim"
+            else: bucket = "normal"
+            return {"width":int(w),"height":int(h),"megapixels":float(w*h/1e6),"aspect_ratio":float(w/max(1,h)),"format":fmt,"has_exif":has_exif,"mean_luma":mean,"std_luma":std,"dark_fraction":dark_fraction,"light_bucket":bucket}
+    except Exception:
+        return {"width":None,"height":None,"megapixels":None,"aspect_ratio":None,"format":path.suffix.lstrip(".").upper(),"has_exif":False,"mean_luma":None,"std_luma":None,"dark_fraction":None,"light_bucket":"unknown"}
+
+
+def _normal_descriptors(root_spec:str|Path,label:int) -> list[dict]:
+    root=Path(root_spec).resolve(); out=[]
+    if not root.exists(): return out
+
+    if root.is_file(): return out
+    for p in iter_images(root):
+        try: rel=p.relative_to(root)
+        except Exception: continue
+        source_leaf=rel.parts[0] if len(rel.parts)>1 else ("unknown-camera" if label==0 else "unknown-generator")
+        out.append({"path":str(p.resolve()),"label":int(label),"source_leaf":source_leaf,"group":str(rel.with_suffix("")),"origin_kind":"image","origin_parquet":None,"origin_row":None})
+    return out
+
+
+def _parquet_descriptors(root_spec:str|Path,label:int,cache_root:Path,image_column:str|None,source_column:str|None) -> list[dict]:
+    out=[]
+    for pq in discover_parquet_files(root_spec):
+        default_source=pq.stem
+        rows=materialize_parquet(pq,cache_root,label,default_source,image_column,source_column)
+        out.extend(rows)
+    return out
+
+
+def build_manifest(
+    real_dir: str,
+    ai_dir: str,
+    out: str,
+    holdout_sources: list[str] | None = None,
+    val_fraction: float = 0.15,
+    real_test_fraction: float = 0.15,
+    dedupe_hamming_distance: int = 3,
+    parquet_cache_dir: str | None = None,
+    real_parquet_image_column: str | None = None,
+    real_parquet_source_column: str | None = None,
+    ai_parquet_image_column: str | None = None,
+    ai_parquet_source_column: str | None = None,
+    force_real_source: str | None = None,
+    force_ai_source: str | None = None,
+) -> list[dict]:
+    holdout = {s.strip().lower() for s in (holdout_sources or []) if s.strip()}
+    rows=[]; dedupe_index=_HammingIndex(dedupe_hamming_distance)
+    manifest_parent=Path(out).resolve().parent
+    pq_cache=Path(parquet_cache_dir).resolve() if parquet_cache_dir else (manifest_parent/"cache"/"parquet_materialized")
+    pq_cache.mkdir(parents=True,exist_ok=True)
+
+    def duplicate(ph):
+        if dedupe_hamming_distance < 0:
+            return False
+        return dedupe_index.duplicate_or_add(ph)
+
+    specs=[
+        (0,real_dir,"real",real_parquet_image_column,real_parquet_source_column),
+        (1,ai_dir,"ai",ai_parquet_image_column,ai_parquet_source_column),
+    ]
+    for label,root_spec,kind,img_col,src_col in specs:
+        descriptors=_normal_descriptors(root_spec,label)
+        pq_desc=_parquet_descriptors(root_spec,label,pq_cache/kind,img_col,src_col)
+        descriptors.extend(pq_desc)
+        print(f"[{kind}] normal_images={len(descriptors)-len(pq_desc)} parquet_images={len(pq_desc)}")
+        for d in tqdm(descriptors,desc=f"manifest-{kind}"):
+            p=Path(d["path"]); raw_source_leaf=str(d.get("source_leaf") or ("unknown-camera" if label==0 else "unknown-generator"))
+            forced = force_real_source if label==0 else force_ai_source
+            source_leaf = str(forced).strip() if forced and str(forced).strip() else raw_source_leaf
+            ph=_phash(p)
+            if duplicate(ph): continue
+            group=str(d.get("group") or p.stem)
+            if label==1 and source_leaf.lower() in holdout: split="test"
+            else:
+                r=stable_unit(f"{kind}:{group}")
+                if label==0:
+                    if r<real_test_fraction: split="test"
+                    elif r<real_test_fraction+val_fraction: split="val"
+                    else: split="train"
+                else: split="val" if r<val_fraction else "train"
+            rows.append({
+                "path":str(p.resolve()),"label":int(label),
+                "source":(f"real:{source_leaf}" if label==0 else source_leaf),
+                "raw_source":raw_source_leaf,
+                "generator":source_leaf if label==1 else None,"camera_bucket":source_leaf if label==0 else None,
+                "group":group,"phash":ph,"split":split,
+                "origin_kind":d.get("origin_kind","image"),"origin_parquet":d.get("origin_parquet"),"origin_row":d.get("origin_row"),
+                **_stats(p),
+            })
+    write_jsonl(out,rows); return rows
+
+
+def manifest_summary(rows:list[dict])->str:
+    c=Counter((r.get("split"),int(r.get("label",-1))) for r in rows); src=Counter((r.get("split"),str(r.get("source","unknown"))) for r in rows); origin=Counter((r.get("split"),str(r.get("origin_kind","image"))) for r in rows)
+    lines=["Counts by split / label (0=REAL, 1=AI):"]
+    for k,v in sorted(c.items(),key=lambda kv:str(kv[0])): lines.append(f"  {k}: {v}")
+    lines.append("\nCounts by split / source:")
+    for k,v in sorted(src.items(),key=lambda kv:str(kv[0])): lines.append(f"  {k}: {v}")
+    lines.append("\nCounts by split / storage origin:")
+    for k,v in sorted(origin.items(),key=lambda kv:str(kv[0])): lines.append(f"  {k}: {v}")
+    return "\n".join(lines)

raven/metrics.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+from collections import defaultdict
+import numpy as np
+from sklearn.metrics import roc_auc_score,average_precision_score,accuracy_score,balanced_accuracy_score
+
+
+def _balanced_weights(y):
+    y=np.asarray(y,int); w=np.zeros(len(y),float)
+    for c in (0,1):
+        m=y==c
+        if m.any(): w[m]=.5/m.sum()
+    return w
+
+
+def ece(y,p,bins=12,balanced=True):
+    y=np.asarray(y,int); p=np.asarray(p,float); w=_balanced_weights(y) if balanced and len(np.unique(y))==2 else np.ones(len(y))/max(1,len(y)); out=0.0
+    edges=np.linspace(0,1,bins+1)
+    for lo,hi in zip(edges[:-1],edges[1:]):
+        m=(p>=lo)&(p<(hi if hi<1 else 1.00001))
+        if not m.any(): continue
+        ww=w[m]; sw=ww.sum()
+        if sw<=0: continue
+        conf=float(np.sum(ww*p[m])/sw); acc=float(np.sum(ww*y[m])/sw); out+=float(sw)*abs(acc-conf)
+    return float(out/max(w.sum(),1e-12))
+
+
+def selective_metrics(y,p,real_thr,ai_thr,lower=None,upper=None):
+    y=np.asarray(y,int); p=np.asarray(p,float); lo=p if lower is None else np.asarray(lower,float); hi=p if upper is None else np.asarray(upper,float)
+    pred=np.full(len(y),-1,int); pred[hi<=real_thr]=0; pred[lo>=ai_thr]=1; known=pred>=0; real=y==0; ai=y==1
+    both=len(np.unique(y))==2; bw=_balanced_weights(y) if both else None
+    out={
+        "n":int(len(y)),"accuracy@0.5_raw":float(accuracy_score(y,p>=.5)),
+        "balanced_accuracy@0.5":float(balanced_accuracy_score(y,p>=.5)) if both else None,
+        "AUROC":float(roc_auc_score(y,p)) if both else None,
+        "AP_raw_prevalence_sensitive":float(average_precision_score(y,p)) if both else None,
+        "AP_balanced":float(average_precision_score(y,p,sample_weight=bw)) if both else None,
+        "balanced_Brier":float(np.sum(bw*(p-y)**2)) if both else None,
+        "coverage":float(known.mean()),"selective_accuracy_raw":float((pred[known]==y[known]).mean()) if known.any() else None,
+        "false_AI_rate_REAL_to_AI":float((lo[real]>=ai_thr).mean()) if real.any() else None,
+        "false_REAL_rate_AI_to_REAL":float((hi[ai]<=real_thr).mean()) if ai.any() else None,
+        "AI_confirmed_recall":float((lo[ai]>=ai_thr).mean()) if ai.any() else None,
+        "REAL_confirmed_recall":float((hi[real]<=real_thr).mean()) if real.any() else None,
+        "uncertain_rate":float((~known).mean()),"ECE_balanced":float(ece(y,p,balanced=True)) if both else None,
+        "real_threshold":float(real_thr),"ai_threshold":float(ai_thr),
+    }
+    if known.any() and both:
+        wk=_balanced_weights(y[known]); out["selective_accuracy_balanced"]=float(np.sum(wk*(pred[known]==y[known]))/max(wk.sum(),1e-12))
+    else: out["selective_accuracy_balanced"]=out["selective_accuracy_raw"]
+    return out
+
+
+def group_report(y,p,groups,real_thr,ai_thr,lower=None,upper=None):
+    by=defaultdict(list); y=np.asarray(y); p=np.asarray(p); lower=p if lower is None else np.asarray(lower); upper=p if upper is None else np.asarray(upper)
+    for i,g in enumerate(groups): by[str(g)].append(i)
+    out=[]
+    for g,idx in sorted(by.items()):
+        ii=np.asarray(idx,int); m=selective_metrics(y[ii],p[ii],real_thr,ai_thr,lower[ii],upper[ii]); m["group"]=g; out.append(m)
+    return out

raven/model.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+
+class GradReverseFn(torch.autograd.Function):
+    @staticmethod
+    def forward(ctx,x,lambd): ctx.lambd=float(lambd); return x.view_as(x)
+    @staticmethod
+    def backward(ctx,g): return -ctx.lambd*g,None
+
+def grad_reverse(x,lambd): return GradReverseFn.apply(x,lambd)
+
+
+class Tower(nn.Module):
+    def __init__(self,din:int,dout:int,dropout:float=.12):
+        super().__init__(); self.net=nn.Sequential(nn.LayerNorm(din),nn.Linear(din,dout),nn.GELU(),nn.Dropout(dropout),nn.Linear(dout,dout),nn.GELU())
+    def forward(self,x): return self.net(x)
+
+
+class RavenFusion(nn.Module):
+
+    BRANCHES=("semantic","camera","spectral","patch","specialist")
+    def __init__(self,dims:dict,num_ai_domains:int=0,num_real_domains:int=0,latent_dim:int=64):
+        super().__init__()
+        outdims={"semantic":96,"camera":48,"spectral":48,"patch":48,"specialist":24}
+        self.towers=nn.ModuleDict({k:Tower(int(dims[k]),outdims[k]) for k in self.BRANCHES})
+        self.branch_heads=nn.ModuleDict({k:nn.Linear(outdims[k],1) for k in self.BRANCHES})
+        total=sum(outdims.values()); self.pre_vib=nn.Sequential(nn.LayerNorm(total),nn.Linear(total,128),nn.GELU(),nn.Dropout(.15))
+        self.mu=nn.Linear(128,latent_dim); self.logvar=nn.Linear(128,latent_dim)
+        qdim=int(dims["quality"]); self.router=nn.Sequential(nn.LayerNorm(qdim),nn.Linear(qdim,48),nn.GELU(),nn.Linear(48,len(self.BRANCHES)))
+        self.anomaly_head=nn.Sequential(nn.LayerNorm(5),nn.Linear(5,24),nn.GELU(),nn.Linear(24,1))
+        self.global_head=nn.Sequential(nn.LayerNorm(latent_dim),nn.Linear(latent_dim,48),nn.GELU(),nn.Dropout(.12),nn.Linear(48,1))
+        self.mixer=nn.Linear(3,1)
+        with torch.no_grad():
+            self.mixer.weight.copy_(torch.tensor([[1.0,1.0,.8]])); self.mixer.bias.zero_()
+        self.ai_domain_head=nn.Sequential(nn.Linear(latent_dim,48),nn.GELU(),nn.Linear(48,num_ai_domains)) if num_ai_domains>1 else None
+        self.real_domain_head=nn.Sequential(nn.Linear(latent_dim,48),nn.GELU(),nn.Linear(48,num_real_domains)) if num_real_domains>1 else None
+
+    def _latent(self,h,sample:bool):
+        p=self.pre_vib(h); mu=self.mu(p); lv=torch.clamp(self.logvar(p),-6,4)
+        if sample and self.training: z=mu+torch.randn_like(mu)*torch.exp(.5*lv)
+        else: z=mu
+        kl=-.5*torch.mean(1+lv-mu.pow(2)-lv.exp())
+        return z,mu,lv,kl
+
+    def forward(self,features:dict,quality:torch.Tensor,anchors:torch.Tensor,luma:torch.Tensor,domain_lambda:float=0.0,sample_vib:bool=True):
+        parts={k:self.towers[k](features[k]) for k in self.BRANCHES}; h=torch.cat([parts[k] for k in self.BRANCHES],1); z,mu,lv,kl=self._latent(h,sample_vib)
+        branch_logits=torch.cat([self.branch_heads[k](parts[k]) for k in self.BRANCHES],1)
+
+
+        route_quality=quality.clone()
+        if route_quality.shape[1]>=12: route_quality[:,10:12]=0.0
+        route_logits=self.router(route_quality)
+
+        darkness=torch.clamp((.25-luma)/.25,0,1).unsqueeze(1)
+        prior=torch.tensor([-.60,.50,.38,.30,.12],dtype=route_logits.dtype,device=route_logits.device).unsqueeze(0)
+        gates=F.softmax(route_logits+darkness*prior,dim=1); gated=(gates*branch_logits).sum(1,keepdim=True)
+        global_logit=self.global_head(z); anomaly_logit=self.anomaly_head(anchors)
+
+        components=torch.cat([global_logit,gated,anomaly_logit],1); logit=self.mixer(components).squeeze(1)
+        ai_domain=self.ai_domain_head(grad_reverse(z,domain_lambda)) if self.ai_domain_head is not None and domain_lambda>0 else None
+        real_domain=self.real_domain_head(grad_reverse(z,domain_lambda)) if self.real_domain_head is not None and domain_lambda>0 else None
+        return {"logit":logit,"branch_logits":branch_logits,"gates":gates,"components":components,"latent":mu,"kl":kl,"ai_domain_logits":ai_domain,"real_domain_logits":real_domain}

raven/onnx_export.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+from pathlib import Path
+import torch
+import torch.nn as nn
+from .model import RavenFusion
+from .foundation import FoundationEncoder
+
+
+class FusionEnsembleWrapper(nn.Module):
+    KEYS=("semantic","camera","spectral","patch","specialist")
+    def __init__(self,models): super().__init__(); self.models=nn.ModuleList(models)
+    def forward(self,semantic,camera,spectral,patch,specialist,quality,anchors,luma):
+        f={"semantic":semantic,"camera":camera,"spectral":spectral,"patch":patch,"specialist":specialist}; outs=[m(f,quality,anchors,luma,0.0,False) for m in self.models]
+        logits=torch.stack([o["logit"] for o in outs],1); branches=torch.stack([o["branch_logits"] for o in outs],1); gates=torch.stack([o["gates"] for o in outs],1)
+        return logits.mean(1),logits.std(1,unbiased=False),branches.mean(1),gates.mean(1)
+
+
+class FoundationWrapper(nn.Module):
+    def __init__(self,enc): super().__init__(); self.enc=enc
+    def forward(self,x): return self.enc(x)
+
+
+def export_fusion(model_path:str,out_path:str):
+    ck=torch.load(model_path,map_location="cpu",weights_only=False); models=[]
+    for st in ck["ensemble_states"]:
+        m=RavenFusion(ck["dims"],len(ck.get("ai_source_map",{})),len(ck.get("real_source_map",{}))); m.load_state_dict(st); m.eval(); models.append(m)
+    w=FusionEnsembleWrapper(models).eval(); d=ck["dims"]; inputs=[torch.randn(1,d[k]) for k in ("semantic","camera","spectral","patch","specialist")]+[torch.randn(1,d["quality"]),torch.randn(1,5),torch.tensor([.3])]
+    Path(out_path).parent.mkdir(parents=True,exist_ok=True)
+    torch.onnx.export(w,tuple(inputs),out_path,input_names=["semantic","camera","spectral","patch","specialist","quality","anchors","luma"],output_names=["logit_mean","logit_std","branch_mean","gates_mean"],dynamic_axes={n:{0:"batch"} for n in ["semantic","camera","spectral","patch","specialist","quality","anchors","luma","logit_mean","logit_std","branch_mean","gates_mean"]},opset_version=18)
+    return out_path
+
+
+def export_foundation(model_path:str,out_path:str):
+    ck=torch.load(model_path,map_location="cpu",weights_only=False); enc=FoundationEncoder(ck["foundation_backend"],allow_fallback=False,fallback_backend=ck["foundation_backend"],pretrained=ck.get("foundation_state") is None).eval();
+    if ck.get("foundation_state") is not None: enc.model.load_state_dict(ck["foundation_state"]["state_dict"])
+    w=FoundationWrapper(enc).eval(); x=torch.randn(1,3,224,224)
+    Path(out_path).parent.mkdir(parents=True,exist_ok=True)
+    torch.onnx.export(w,x,out_path,input_names=["image"],output_names=["embedding"],dynamic_axes={"image":{0:"batch"},"embedding":{0:"batch"}},opset_version=18)
+    return out_path

raven/onnx_runtime.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+import numpy as np
+
+
+def open_session(path: str, prefer_directml: bool = True):
+    try:
+        import onnxruntime as ort
+    except Exception as exc:
+        raise RuntimeError("Install requirements-directml.txt (or onnxruntime) first") from exc
+
+    available = ort.get_available_providers()
+    providers = []
+    opts = ort.SessionOptions()
+    opts.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL
+
+    if prefer_directml and "DmlExecutionProvider" in available:
+
+        opts.execution_mode = ort.ExecutionMode.ORT_SEQUENTIAL
+        opts.enable_mem_pattern = False
+        providers.append("DmlExecutionProvider")
+    else:
+
+        opts.intra_op_num_threads = 6
+        opts.inter_op_num_threads = 1
+        providers.append("CPUExecutionProvider")
+
+    if "CPUExecutionProvider" not in providers:
+        providers.append("CPUExecutionProvider")
+    return ort.InferenceSession(path, sess_options=opts, providers=providers)
+
+
+def run_foundation(session, image: np.ndarray) -> np.ndarray:
+    return session.run(["embedding"], {"image": np.asarray(image, np.float32)})[0]
+
+
+def run_fusion(session, inputs: dict):
+    feed = {k: np.asarray(v, np.float32) for k, v in inputs.items()}
+    o = session.run(None, feed)
+    return {"logit_mean": o[0], "logit_std": o[1], "branch_mean": o[2], "gates_mean": o[3]}

raven/parquet_io.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+import shutil
+from pathlib import Path
+from typing import Iterable
+
+from PIL import Image
+
+
+COMMON_IMAGE_COLUMNS = (
+    "image", "images", "jpg", "jpeg", "png", "webp", "bytes", "image_bytes"
+)
+COMMON_SOURCE_COLUMNS = (
+    "source", "generator", "model", "camera", "camera_model", "origin", "dataset"
+)
+
+
+def _require_pyarrow():
+    try:
+        import pyarrow.parquet as pq
+        return pq
+    except Exception as exc:
+        raise RuntimeError(
+            "Parquet support requires pyarrow. Run windows\\01_install_cpu.bat "
+            "or: python -m pip install pyarrow"
+        ) from exc
+
+
+def discover_parquet_files(path: str | Path) -> list[Path]:
+    p = Path(path)
+    if not p.exists():
+        return []
+    if p.is_file() and p.suffix.lower() == ".parquet":
+        return [p.resolve()]
+    if p.is_dir():
+        return sorted(x.resolve() for x in p.rglob("*.parquet") if x.is_file())
+    return []
+
+
+def _choose_column(names: list[str], requested: str | None, candidates: Iterable[str]) -> str | None:
+    if requested:
+        if requested not in names:
+            raise KeyError(f"Parquet column '{requested}' not found. Columns={names}")
+        return requested
+    lower = {n.lower(): n for n in names}
+    for c in candidates:
+        if c.lower() in lower:
+            return lower[c.lower()]
+    return None
+
+
+def inspect_parquet(parquet_path: str | Path) -> dict:
+    pq = _require_pyarrow()
+    pf = pq.ParquetFile(str(parquet_path))
+    names = list(pf.schema_arrow.names)
+    image_col = _choose_column(names, None, COMMON_IMAGE_COLUMNS)
+    source_col = _choose_column(names, None, COMMON_SOURCE_COLUMNS)
+    return {
+        "path": str(Path(parquet_path).resolve()),
+        "rows": int(pf.metadata.num_rows),
+        "row_groups": int(pf.metadata.num_row_groups),
+        "columns": names,
+        "auto_image_column": image_col,
+        "auto_source_column": source_col,
+    }
+
+
+def _cell_to_bytes(cell, parquet_parent: Path) -> bytes | None:
+    if cell is None:
+        return None
+    if isinstance(cell, memoryview):
+        return cell.tobytes()
+    if isinstance(cell, (bytes, bytearray)):
+        return bytes(cell)
+    if isinstance(cell, str):
+        p = Path(cell)
+        if not p.is_absolute():
+            p = parquet_parent / p
+        return p.read_bytes() if p.exists() and p.is_file() else None
+    if isinstance(cell, dict):
+        raw = cell.get("bytes")
+        if raw is not None:
+            if isinstance(raw, memoryview):
+                return raw.tobytes()
+            if isinstance(raw, (bytes, bytearray)):
+                return bytes(raw)
+        path_value = cell.get("path")
+        if path_value:
+            p = Path(str(path_value))
+            if not p.is_absolute():
+                p = parquet_parent / p
+            return p.read_bytes() if p.exists() and p.is_file() else None
+    return None
+
+
+def _ext_from_bytes(raw: bytes) -> str:
+    try:
+        with Image.open(io.BytesIO(raw)) as im:
+            fmt = (im.format or "").upper()
+        return {
+            "JPEG": ".jpg",
+            "JPG": ".jpg",
+            "PNG": ".png",
+            "WEBP": ".webp",
+            "BMP": ".bmp",
+            "TIFF": ".tiff",
+            "GIF": ".gif",
+        }.get(fmt, ".img")
+    except Exception:
+        return ".img"
+
+
+def _safe_text(value, fallback: str) -> str:
+    if value is None:
+        return fallback
+    s = str(value).strip()
+    if not s:
+        return fallback
+    return "".join(c if c.isalnum() or c in "-_.:" else "_" for c in s)[:120]
+
+
+def materialize_parquet(
+    parquet_path: str | Path,
+    cache_root: str | Path,
+    label: int,
+    default_source: str | None = None,
+    image_column: str | None = None,
+    source_column: str | None = None,
+    batch_size: int = 128,
+) -> list[dict]:
+
+    pq = _require_pyarrow()
+    parquet_path = Path(parquet_path).resolve()
+    pf = pq.ParquetFile(str(parquet_path))
+    names = list(pf.schema_arrow.names)
+    image_col = _choose_column(names, image_column, COMMON_IMAGE_COLUMNS)
+    if image_col is None:
+        raise KeyError(
+            f"Could not auto-detect an image column in {parquet_path.name}. "
+            f"Columns={names}. Use --real-parquet-image-column/--ai-parquet-image-column."
+        )
+    src_col = _choose_column(names, source_column, COMMON_SOURCE_COLUMNS)
+
+    stat=parquet_path.stat()
+    cache_key=json.dumps({"path":str(parquet_path),"size":stat.st_size,"mtime_ns":stat.st_mtime_ns,"label":int(label),"default_source":default_source,"image_column":image_col,"source_column":src_col},sort_keys=True)
+    digest = hashlib.sha256(cache_key.encode("utf-8")).hexdigest()[:16]
+    out_dir = Path(cache_root).resolve() / digest
+    out_dir.mkdir(parents=True, exist_ok=True)
+    index_file = out_dir / "_index.jsonl"
+
+
+    if index_file.exists():
+        try:
+            cached = [json.loads(x) for x in index_file.read_text(encoding="utf-8").splitlines() if x.strip()]
+            if cached and all(Path(r["path"]).exists() for r in cached):
+                return cached
+        except Exception:
+            pass
+
+    columns = [image_col] + ([src_col] if src_col and src_col != image_col else [])
+    default_source = _safe_text(default_source, parquet_path.stem)
+    descriptors: list[dict] = []
+    global_row = 0
+
+
+    for batch in pf.iter_batches(batch_size=max(1, int(batch_size)), columns=columns):
+        rows = batch.to_pylist()
+        for row in rows:
+            raw = _cell_to_bytes(row.get(image_col), parquet_path.parent)
+            src = _safe_text(row.get(src_col) if src_col else None, default_source)
+            if raw is None:
+                global_row += 1
+                continue
+            ext = _ext_from_bytes(raw)
+            if ext == ".img":
+
+                try:
+                    with Image.open(io.BytesIO(raw)) as im:
+                        im = im.convert("RGB")
+                        out_path = out_dir / f"{global_row:09d}.png"
+                        if not out_path.exists():
+                            im.save(out_path, "PNG")
+                except Exception:
+                    global_row += 1
+                    continue
+            else:
+                out_path = out_dir / f"{global_row:09d}{ext}"
+                if not out_path.exists() or out_path.stat().st_size != len(raw):
+                    out_path.write_bytes(raw)
+            descriptors.append({
+                "path": str(out_path.resolve()),
+                "label": int(label),
+                "source_leaf": src,
+                "group": f"parquet:{parquet_path.name}:{global_row}",
+                "origin_kind": "parquet",
+                "origin_parquet": str(parquet_path),
+                "origin_row": int(global_row),
+                "parquet_image_column": image_col,
+                "parquet_source_column": src_col,
+            })
+            global_row += 1
+
+    index_file.write_text(
+        "\n".join(json.dumps(r, ensure_ascii=False) for r in descriptors) + ("\n" if descriptors else ""),
+        encoding="utf-8",
+    )
+    return descriptors
+
+
+def import_parquet(
+    parquet_path: str,
+    out_dir: str,
+    label: int,
+    source: str,
+    manifest_out: str,
+    image_column: str = "image",
+):
+
+    from .utils import write_jsonl
+
+    rows = materialize_parquet(
+        parquet_path=parquet_path,
+        cache_root=out_dir,
+        label=label,
+        default_source=source,
+        image_column=image_column,
+        source_column=None,
+    )
+    manifest_rows = [
+        {"path": r["path"], "label": int(label), "source": source, "origin_parquet": r["origin_parquet"], "origin_row": r["origin_row"]}
+        for r in rows
+    ]
+    write_jsonl(manifest_out, manifest_rows)
+    return {"count": len(rows), "out_dir": str(Path(out_dir).resolve()), "manifest": manifest_out}

raven/provenance.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+import json
+import shutil
+import subprocess
+
+
+def inspect_provenance(path: str) -> dict:
+
+    tool=shutil.which("c2patool")
+    if not tool: return {"available":False,"ai_provenance":False,"note":"c2patool not installed"}
+    try:
+        p=subprocess.run([tool,"--json",path],capture_output=True,text=True,timeout=12)
+        text=(p.stdout or "")+(p.stderr or ""); low=text.lower()
+        markers=["trainedalgorithmicmedia","trained algorithmic media","ai-generated","ai generated","openai","chatgpt"]
+        hit=next((m for m in markers if m in low),None)
+        return {"available":True,"ai_provenance":bool(hit),"marker":hit,"raw_present":bool(text.strip())}
+    except Exception as exc:
+        return {"available":True,"ai_provenance":False,"error":str(exc)}

raven/specialists.py

@@ -0,0 +1,264 @@
+from __future__ import annotations
+
+import copy
+from collections import defaultdict
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+import random
+
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from torch.utils.data import Dataset, DataLoader
+from tqdm import tqdm
+
+from .forensic_features import load_rgb, spectral_map, camera_residual_map
+from .utils import configure_cpu, seed_everything
+
+
+def _make_maps(item):
+    r, map_size = item
+    im = load_rgb(r["path"])
+    return spectral_map(im, map_size), camera_residual_map(im, map_size)
+
+
+class MapDataset(Dataset):
+    def __init__(self, rows: list[dict], map_size: int, precompute_workers: int = 0):
+        self.rows = rows
+        self.map_size = map_size
+        jobs = [(r, map_size) for r in rows]
+        spectral, camera = [], []
+        if precompute_workers > 1:
+            with ThreadPoolExecutor(max_workers=precompute_workers) as ex:
+                it = ex.map(_make_maps, jobs)
+                for s, c in tqdm(it, total=len(jobs), desc="precompute-real-maps", leave=False):
+                    spectral.append(s)
+                    camera.append(c)
+        else:
+            for j in tqdm(jobs, desc="precompute-real-maps", leave=False):
+                s, c = _make_maps(j)
+                spectral.append(s)
+                camera.append(c)
+
+        self.spectral = np.stack(spectral).astype(np.float16) if spectral else np.zeros((0, map_size, map_size), np.float16)
+        self.camera = np.stack(camera).astype(np.float16) if camera else np.zeros((0, map_size, map_size), np.float16)
+
+    def __len__(self):
+        return len(self.rows)
+
+    def __getitem__(self, i):
+        return torch.from_numpy(self.spectral[i][None]), torch.from_numpy(self.camera[i][None])
+
+
+class ConvAutoencoder(nn.Module):
+    def __init__(self, latent_dim: int = 48):
+        super().__init__()
+        self.enc = nn.Sequential(
+            nn.Conv2d(1, 16, 3, 2, 1), nn.GELU(),
+            nn.Conv2d(16, 32, 3, 2, 1), nn.GELU(),
+            nn.Conv2d(32, 48, 3, 2, 1), nn.GELU(),
+            nn.Conv2d(48, latent_dim, 3, 2, 1), nn.GELU(),
+        )
+        self.dec = nn.Sequential(
+            nn.ConvTranspose2d(latent_dim, 48, 4, 2, 1), nn.GELU(),
+            nn.ConvTranspose2d(48, 32, 4, 2, 1), nn.GELU(),
+            nn.ConvTranspose2d(32, 16, 4, 2, 1), nn.GELU(),
+            nn.ConvTranspose2d(16, 1, 4, 2, 1),
+        )
+
+    def forward(self, x):
+        return self.dec(self.enc(x))
+
+
+def _mask_blocks(x: torch.Tensor, fraction: float) -> torch.Tensor:
+    if fraction <= 0:
+        return x
+    b, _, h, w = x.shape
+    mask = torch.ones_like(x)
+    block = max(4, h // 8)
+    n = max(1, int((h * w * fraction) / (block * block)))
+    for bi in range(b):
+        for _ in range(n):
+            y = random.randint(0, max(0, h - block))
+            xx = random.randint(0, max(0, w - block))
+            mask[bi, :, y:y + block, xx:xx + block] = 0
+    return x * mask
+
+
+def _stratified_cap_real(rows: list[dict], limit: int, seed: int) -> list[dict]:
+
+    if limit <= 0 or len(rows) <= limit:
+        return list(rows)
+    groups = defaultdict(list)
+    for r in rows:
+        key = (str(r.get("light_bucket", "unknown")), str(r.get("source", "real")))
+        groups[key].append(r)
+    rng = random.Random(seed)
+    for v in groups.values():
+        rng.shuffle(v)
+    keys = list(groups)
+    rng.shuffle(keys)
+    out = []
+    cursor = {k: 0 for k in keys}
+    while len(out) < limit:
+        added = False
+        for k in keys:
+            i = cursor[k]
+            if i < len(groups[k]):
+                out.append(groups[k][i])
+                cursor[k] = i + 1
+                added = True
+                if len(out) >= limit:
+                    break
+        if not added:
+            break
+    return out
+
+
+def train_real_specialists(rows: list[dict], cfg: dict, out_path: str) -> dict:
+    hc = cfg["hardware"]
+    rcfg = cfg["real_specialists"]
+    seed = int(cfg["training"].get("seed", 1337))
+    configure_cpu(hc.get("torch_threads", 6), hc.get("interop_threads", 1))
+    seed_everything(seed)
+
+    real = [r for r in rows if int(r.get("label", -1)) == 0 and r.get("split") == "train"]
+    real = _stratified_cap_real(real, int(rcfg.get("max_real_images", 5000)), seed)
+    random.Random(seed).shuffle(real)
+    if len(real) < 50:
+        raise ValueError("Need at least 50 REAL training images for real-only specialists")
+
+    nval = max(20, min(512, int(len(real) * .12)))
+    val = real[:nval]
+    train = real[nval:]
+    msize = int(rcfg.get("map_size", 64))
+    pre_workers = max(0, int(rcfg.get("precompute_workers", hc.get("preprocess_workers", 2))))
+    ds = MapDataset(train, msize, pre_workers)
+    vds = MapDataset(val, msize, pre_workers)
+
+
+    loader = DataLoader(ds, batch_size=int(rcfg.get("batch_size", 64)), shuffle=True, num_workers=0)
+    vloader = DataLoader(vds, batch_size=int(rcfg.get("batch_size", 64)), shuffle=False, num_workers=0)
+
+    device = torch.device("cpu")
+    spec = ConvAutoencoder(int(rcfg.get("latent_dim", 40))).to(device)
+    cam = ConvAutoencoder(int(rcfg.get("latent_dim", 40))).to(device)
+    params = list(spec.parameters()) + list(cam.parameters())
+    opt = torch.optim.AdamW(
+        params,
+        lr=float(rcfg.get("lr", .0018)),
+        weight_decay=float(rcfg.get("weight_decay", 1e-4)),
+    )
+
+    best = float("inf")
+    best_state = None
+    stale = 0
+    patience = int(rcfg.get("early_stop_patience", 3))
+    epochs = int(rcfg.get("epochs", 10))
+    frac = float(rcfg.get("mask_fraction", .25))
+
+    for ep in range(epochs):
+        spec.train()
+        cam.train()
+        total = 0.0
+        count = 0
+        bar = tqdm(loader, desc=f"real-specialists {ep + 1}/{epochs}")
+        for s, c in bar:
+            s = s.to(device).float()
+            c = c.to(device).float()
+            opt.zero_grad(set_to_none=True)
+            sin = _mask_blocks(s, frac)
+            cin = c + torch.randn_like(c) * float(rcfg.get("camera_noise_std", .015))
+            ps = spec(sin)
+            pc = cam(cin)
+            loss = F.smooth_l1_loss(ps, s) + F.smooth_l1_loss(pc, c)
+            loss.backward()
+            torch.nn.utils.clip_grad_norm_(params, 3.0)
+            opt.step()
+            total += float(loss.item())
+            count += 1
+            bar.set_postfix(loss=f"{total / count:.4f}")
+
+        spec.eval()
+        cam.eval()
+        vals = []
+        with torch.inference_mode():
+            for s, c in vloader:
+                s = s.float()
+                c = c.float()
+                ps = spec(s)
+                pc = cam(c)
+                vals.append(float((F.l1_loss(ps, s) + F.l1_loss(pc, c)).item()))
+        score = float(np.mean(vals)) if vals else total / max(1, count)
+        print(f"[specialists] validation={score:.6f}")
+        if score < best - 1e-5:
+            best = score
+            best_state = {"spectral": copy.deepcopy(spec.state_dict()), "camera": copy.deepcopy(cam.state_dict())}
+            stale = 0
+        else:
+            stale += 1
+            if stale >= patience:
+                break
+
+    if best_state:
+        spec.load_state_dict(best_state["spectral"])
+        cam.load_state_dict(best_state["camera"])
+    Path(out_path).parent.mkdir(parents=True, exist_ok=True)
+    torch.save({
+        "version": 4,
+        "map_size": msize,
+        "latent_dim": int(rcfg.get("latent_dim", 40)),
+        "spectral_state": spec.state_dict(),
+        "camera_state": cam.state_dict(),
+        "validation_loss": best,
+        "capped_real_images": len(real),
+    }, out_path)
+    print(f"[saved] {out_path}")
+    return {"validation_loss": best, "real_train": len(train), "real_val": len(val), "capped_real_images": len(real)}
+
+
+def load_specialists(path: str, device="cpu"):
+    ck = torch.load(path, map_location=device, weights_only=False)
+    latent = int(ck.get("latent_dim", 48))
+    s = ConvAutoencoder(latent).to(device)
+    c = ConvAutoencoder(latent).to(device)
+    s.load_state_dict(ck["spectral_state"])
+    c.load_state_dict(ck["camera_state"])
+    s.eval()
+    c.eval()
+    return s, c, ck
+
+
+@torch.inference_mode()
+def specialist_scores(im, specialists_path: str, cache_obj=None) -> np.ndarray:
+    if cache_obj is None:
+        spec, cam, ck = load_specialists(specialists_path, "cpu")
+    else:
+        spec, cam, ck = cache_obj
+    size = int(ck["map_size"])
+    sm = torch.from_numpy(spectral_map(im, size)[None, None]).float()
+    cm = torch.from_numpy(camera_residual_map(im, size)[None, None]).float()
+    ps = spec(sm)
+    pc = cam(cm)
+
+    def metrics(pred, target):
+        err = torch.abs(pred - target)
+        mse = torch.mean((pred - target) ** 2)
+        mae = torch.mean(err)
+        cos = F.cosine_similarity(pred.flatten(1), target.flatten(1), dim=1).mean()
+        q90 = torch.quantile(err.flatten(), .90)
+        return [float(mae), float(mse), float(1 - cos), float(q90)]
+
+    return np.asarray(metrics(ps, sm) + metrics(pc, cm), dtype=np.float32)
+
+
+def load_specialists_checkpoint(ck: dict, device="cpu"):
+    latent = int(ck.get("latent_dim", 48))
+    s = ConvAutoencoder(latent).to(device)
+    c = ConvAutoencoder(latent).to(device)
+    s.load_state_dict(ck["spectral_state"])
+    c.load_state_dict(ck["camera_state"])
+    s.eval()
+    c.eval()
+    return s, c, ck

raven/training.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+import copy,json,math
+from pathlib import Path
+import numpy as np
+import torch
+import torch.nn.functional as F
+from torch.utils.data import DataLoader, WeightedRandomSampler
+from tqdm import tqdm
+from sklearn.metrics import roc_auc_score
+from .cache import load_cache
+from .anchors import AnchorSet
+from .dataset import FeatureNormalizer,CachedFeatureDataset,make_source_maps,balanced_sampler,BRANCH_KEYS
+from .model import RavenFusion
+from .calibration import MetaCalibrator,meta_features,select_thresholds
+from .metrics import selective_metrics
+from .utils import configure_cpu,seed_everything
+
+
+def _dims(cache): return {**{k:int(cache[k].shape[1]) for k in BRANCH_KEYS},"quality":int(cache["quality"].shape[1])}
+
+def _features_from_batch(batch,device,noise_sem=0.0,noise_for=0.0,branch_dropout:float=0.0):
+    out={}
+    for k in BRANCH_KEYS:
+        x=batch[k].to(device).float(); ns=noise_sem if k=="semantic" else noise_for
+        if ns>0: x=x+torch.randn_like(x)*ns
+        out[k]=x
+
+
+    if branch_dropout>0 and len(out.get("semantic",[])):
+        b=out["semantic"].shape[0]; candidates=[k for k in BRANCH_KEYS if k!="semantic"]
+        active=torch.rand(b,device=device)<float(branch_dropout)
+        which=torch.randint(0,len(candidates),(b,),device=device)
+        for ci,k in enumerate(candidates):
+            mask=active & (which==ci)
+            if mask.any(): out[k]=out[k].clone(); out[k][mask]=0
+    return out
+
+
+def _binary_metric_loss(z:torch.Tensor,y:torch.Tensor)->torch.Tensor:
+
+    y=(y>=.5)
+    if not y.any() or (~y).sum()==0:
+        return z.new_tensor(0.0)
+    zn=F.normalize(z,dim=1)
+    c0=F.normalize(zn[~y].mean(0,keepdim=True),dim=1)
+    c1=F.normalize(zn[y].mean(0,keepdim=True),dim=1)
+    within=(1-(zn[~y]*c0).sum(1)).mean()+(1-(zn[y]*c1).sum(1)).mean()
+    between=F.relu(F.cosine_similarity(c0,c1,dim=1).mean()-0.15)
+    return .5*within+.5*between
+
+
+def _hard_replay_sampler(ds, path_scores:dict[str,float], boost:float, seed:int):
+    labels=[]; sources=[]; paths=[]
+    for j in ds.indices:
+        labels.append(int(ds.cache["label"][j])); sources.append(str(ds.cache["source"][j])); paths.append(str(ds.cache["path"][j]))
+    weights=np.zeros(len(labels),dtype=np.float64)
+    for cls in (0,1):
+        ids=[i for i,v in enumerate(labels) if v==cls]
+        by={}
+        for i in ids: by.setdefault(sources[i],[]).append(i)
+        for inds in by.values():
+            base=1.0/(2.0*max(1,len(by))*max(1,len(inds)))
+            for i in inds: weights[i]=base*(1.0+float(boost)*float(path_scores.get(paths[i],0.0)))
+        sm=weights[ids].sum()
+        if sm>0: weights[ids]*=.5/sm
+    g=torch.Generator(); g.manual_seed(int(seed))
+    return WeightedRandomSampler(torch.as_tensor(weights,dtype=torch.double),num_samples=len(ds),replacement=True,generator=g)
+
+
+def _balanced_bce(logits, targets, raw_labels):
+
+    losses=F.binary_cross_entropy_with_logits(logits,targets,reduction="none")
+    raw_labels=raw_labels.reshape(-1)
+    pieces=[]
+    for cls in (0,1):
+        m=(raw_labels==cls)
+        if m.any(): pieces.append(losses[m].mean())
+    return torch.stack(pieces).mean() if pieces else losses.mean()
+
+@torch.inference_mode()
+def _collect_one(model,loader,device):
+    model.eval(); lo=[]; br=[]; ga=[]; labels=[]; idx=[]; sources=[]; paths=[]
+    for b in loader:
+        out=model(_features_from_batch(b,device),b["quality"].to(device).float(),b["anchors"].to(device).float(),b["luma"].to(device).float(),0.0,False)
+        lo.append(out["logit"].cpu().numpy()); br.append(out["branch_logits"].cpu().numpy()); ga.append(out["gates"].cpu().numpy()); labels.append(b["label"].numpy()); idx.append(b["index"].numpy()); sources.extend(b["source"]); paths.extend(b["path"])
+    return {"logit":np.concatenate(lo),"branch":np.concatenate(br),"gates":np.concatenate(ga),"labels":np.concatenate(labels).astype(int),"indices":np.concatenate(idx).astype(int),"sources":sources,"paths":paths}
+
+@torch.inference_mode()
+def collect_ensemble(models,loader,device):
+    per=[_collect_one(m,loader,device) for m in models]; logits=np.stack([x["logit"] for x in per],1); branches=np.stack([x["branch"] for x in per],1); gates=np.stack([x["gates"] for x in per],1)
+    return {"logit_mean":logits.mean(1),"logit_std":logits.std(1),"branch_mean":branches.mean(1),"gates_mean":gates.mean(1),"labels":per[0]["labels"],"indices":per[0]["indices"],"sources":per[0]["sources"],"paths":per[0]["paths"]}
+
+
+def _refine_hard(model,ds,vloader,device,tc,member_id:int):
+    epochs=int(tc.get("hard_refine_epochs",0))
+    if epochs<=0: return model
+
+    orig_idx=np.asarray([j for j in ds.indices if int(ds.cache["view_id"][j])==0],dtype=np.int64)
+    if len(orig_idx)<32: return model
+    ods=CachedFeatureDataset(ds.cache,orig_idx,ds.norm,ds.anchor_scores,ds.ai_source_map,ds.real_source_map)
+    ol=DataLoader(ods,batch_size=256,shuffle=False,num_workers=0)
+    pred=_collect_one(model,ol,device); probs=1/(1+np.exp(-np.clip(pred["logit"],-30,30)))
+
+    err=np.abs(probs-pred["labels"]); uncertainty=1.0-np.abs(probs-.5)*2.0; hardness=np.clip(.70*err+.30*uncertainty,0,1)
+    path_scores={p:float(h) for p,h in zip(pred["paths"],hardness)}
+    sampler=_hard_replay_sampler(ds,path_scores,float(tc.get("hard_replay_boost",4.0)),int(tc.get("seed",1337))+7000+member_id)
+    loader=DataLoader(ds,batch_size=int(tc.get("batch_size",256)),sampler=sampler,num_workers=0,drop_last=False)
+    opt=torch.optim.AdamW(model.parameters(),lr=float(tc.get("lr",.0014))*float(tc.get("hard_refine_lr_multiplier",.22)),weight_decay=float(tc.get("weight_decay",.01)))
+    best_pred=_collect_one(model,vloader,device); best=float(roc_auc_score(best_pred["labels"],best_pred["logit"])) if len(np.unique(best_pred["labels"]))==2 else 0.0
+    best_state=copy.deepcopy(model.state_dict()); stale=0
+    for ep in range(epochs):
+        model.train()
+        for b in loader:
+            y=b["label"].to(device).float(); smooth=float(tc.get("label_smoothing",.02)); ys=y*(1-smooth)+.5*smooth
+            f=_features_from_batch(b,device,float(tc.get("feature_noise_semantic",.012))*.6,float(tc.get("feature_noise_forensic",.020))*.6,float(tc.get("branch_dropout",.12))*.5)
+            q=b["quality"].to(device).float(); a=b["anchors"].to(device).float(); l=b["luma"].to(device).float(); opt.zero_grad(set_to_none=True)
+            o=model(f,q,a,l,0.0,True); loss=_balanced_bce(o["logit"],ys,y)+float(tc.get("branch_loss_weight",.12))*.5*_balanced_bce(o["branch_logits"].reshape(-1),ys[:,None].expand_as(o["branch_logits"]).reshape(-1),y[:,None].expand_as(o["branch_logits"]).reshape(-1))+float(tc.get("contrastive_weight",.028))*_binary_metric_loss(o["latent"],y)+float(tc.get("vib_beta",.0015))*o["kl"]
+            loss.backward(); torch.nn.utils.clip_grad_norm_(model.parameters(),3.0); opt.step()
+        vp=_collect_one(model,vloader,device); auc=float(roc_auc_score(vp["labels"],vp["logit"])) if len(np.unique(vp["labels"]))==2 else 0.0
+        if auc>best+5e-5: best=auc; best_state=copy.deepcopy(model.state_dict()); stale=0
+        else:
+            stale+=1
+            if stale>=2: break
+    model.load_state_dict(best_state)
+    print(f"[member {member_id+1}] hard-replay refined AUROC={best:.5f}")
+    return model
+
+def _train_member(member_id,cache,base_train_mask,val_mask,normalizer,anchor_scores,ai_map,real_map,dims,cfg,excluded_sources):
+    tc=cfg["training"]; hc=cfg["hardware"]; device=torch.device("cpu")
+    mask=base_train_mask.copy()
+    if excluded_sources:
+        mask &= ~np.isin(cache["source"],list(excluded_sources))
+    train_idx=np.where(mask)[0]
+
+    pseudo=(base_train_mask & np.isin(cache["source"],list(excluded_sources)) & (cache["view_id"]==0)) if excluded_sources else np.zeros_like(base_train_mask)
+    member_val_idx=np.where(val_mask|pseudo)[0]
+    ds=CachedFeatureDataset(cache,train_idx,normalizer,anchor_scores,ai_map,real_map); vds=CachedFeatureDataset(cache,member_val_idx,normalizer,anchor_scores,ai_map,real_map)
+    workers=0
+    loader=DataLoader(ds,batch_size=int(tc.get("batch_size",64)),sampler=balanced_sampler(ds,float(tc.get("max_minority_oversample_factor",2.0)),int(tc.get("seed",1337))+member_id*101),num_workers=workers,drop_last=False)
+    vloader=DataLoader(vds,batch_size=256,shuffle=False,num_workers=0)
+    seed=int(tc.get("seed",1337))+member_id*101; seed_everything(seed)
+    model=RavenFusion(dims,len(ai_map),len(real_map)).to(device); opt=torch.optim.AdamW(model.parameters(),lr=float(tc.get("lr",.0012)),weight_decay=float(tc.get("weight_decay",.01)))
+    sched=torch.optim.lr_scheduler.CosineAnnealingLR(opt,T_max=max(1,int(tc.get("epochs",80))))
+    best=-1.0; state=None; stale=0; patience=int(tc.get("early_stop_patience",10)); epochs=int(tc.get("epochs",80)); total_steps=max(1,epochs*len(loader)); step=0
+    for ep in range(epochs):
+        model.train(); run=0.0; n=0
+        bar=tqdm(loader,desc=f"fusion m{member_id+1} {ep+1}/{epochs}",leave=False)
+        for b in bar:
+            y=b["label"].to(device).float(); smooth=float(tc.get("label_smoothing",.02)); ys=y*(1-smooth)+.5*smooth
+            dl=2/(1+math.exp(-10*min(1.0,step/total_steps)))-1
+            f1=_features_from_batch(b,device,float(tc.get("feature_noise_semantic",.012)),float(tc.get("feature_noise_forensic",.020)),float(tc.get("branch_dropout",.12)))
+            f2=_features_from_batch(b,device,float(tc.get("feature_noise_semantic",.012)),float(tc.get("feature_noise_forensic",.020)),float(tc.get("branch_dropout",.12)))
+            q=b["quality"].to(device).float(); a=b["anchors"].to(device).float(); l=b["luma"].to(device).float(); opt.zero_grad(set_to_none=True)
+            o1=model(f1,q,a,l,dl,True); o2=model(f2,q,a,l,0.0,True)
+            main=_balanced_bce(o1["logit"],ys,y)+.5*_balanced_bce(o2["logit"],ys,y)
+            bt=ys[:,None].expand_as(o1["branch_logits"]); raw_bt=y[:,None].expand_as(o1["branch_logits"]); branch=_balanced_bce(o1["branch_logits"].reshape(-1),bt.reshape(-1),raw_bt.reshape(-1))
+            consistency=F.mse_loss(torch.sigmoid(o1["logit"]),torch.sigmoid(o2["logit"]))
+            adv=torch.tensor(0.0,device=device); ai_d=b["ai_domain"].to(device); vr=ai_d>=0
+            if o1["ai_domain_logits"] is not None and vr.any(): adv=adv+float(tc.get("adversarial_weight_ai",.035))*F.cross_entropy(o1["ai_domain_logits"][vr],ai_d[vr])
+            re_d=b["real_domain"].to(device); vr2=re_d>=0
+            if o1["real_domain_logits"] is not None and vr2.any(): adv=adv+float(tc.get("adversarial_weight_real",.02))*F.cross_entropy(o1["real_domain_logits"][vr2],re_d[vr2])
+            metric=_binary_metric_loss(o1["latent"],y)
+            loss=main+float(tc.get("branch_loss_weight",.12))*branch+float(tc.get("consistency_weight",.08))*consistency+float(tc.get("contrastive_weight",.028))*metric+float(tc.get("vib_beta",.0015))*o1["kl"]+adv
+            loss.backward(); torch.nn.utils.clip_grad_norm_(model.parameters(),4.0); opt.step(); run+=float(loss.item()); n+=1; step+=1; bar.set_postfix(loss=f"{run/n:.4f}")
+        sched.step(); pred=_collect_one(model,vloader,device); auc=float(roc_auc_score(pred["labels"],pred["logit"])) if len(np.unique(pred["labels"]))==2 else 0.0
+        if auc>best+1e-4: best=auc; state=copy.deepcopy(model.state_dict()); stale=0
+        else:
+            stale+=1
+            if stale>=patience: break
+    if state is not None: model.load_state_dict(state)
+    model=_refine_hard(model,ds,vloader,device,tc,member_id)
+    final_pred=_collect_one(model,vloader,device); final_auc=float(roc_auc_score(final_pred["labels"],final_pred["logit"])) if len(np.unique(final_pred["labels"]))==2 else best
+    print(f"[member {member_id+1}] best pseudo-unseen/val AUROC={final_auc:.5f}; excluded={sorted(excluded_sources)}")
+    return model,final_auc
+
+
+def train_fusion(cache_path:str,cfg:dict,out_path:str):
+    hc=cfg["hardware"]; configure_cpu(hc.get("torch_threads",6),hc.get("interop_threads",1)); cache=load_cache(cache_path); dims=_dims(cache)
+    train_mask=cache["split"]=="train"; val_mask=(cache["split"]=="val")&(cache["view_id"]==0)
+    if train_mask.sum()<200 or val_mask.sum()<40: raise ValueError("Feature cache needs sufficient train/val samples. Build manifest with ~15% validation.")
+    normalizer=FeatureNormalizer.fit(cache,train_mask); anchors=AnchorSet.fit(cache,cfg); anchor_scores=anchors.score(cache); ai_map,real_map=make_source_maps(cache,train_mask)
+    ai_sources=sorted(ai_map); members=[]; member_info=[]; nmem=int(cfg["training"].get("ensemble_members",5)); drop=int(cfg["training"].get("source_dropout_per_member",1))
+    for m in range(nmem):
+        excluded=set()
+        if drop>0 and len(ai_sources)>=4:
+            for j in range(drop): excluded.add(ai_sources[(m*drop+j)%len(ai_sources)])
+        model,auc=_train_member(m,cache,train_mask,val_mask,normalizer,anchor_scores,ai_map,real_map,dims,cfg,excluded); members.append(model); member_info.append({"best_auc":auc,"excluded_ai_sources":sorted(excluded)})
+    val_idx=np.where(val_mask)[0]; vds=CachedFeatureDataset(cache,val_idx,normalizer,anchor_scores,ai_map,real_map); vloader=DataLoader(vds,batch_size=256,shuffle=False,num_workers=0)
+    ens=collect_ensemble(members,vloader,torch.device("cpu")); ii=ens["indices"]
+    mx=meta_features(ens["logit_mean"],ens["logit_std"],ens["branch_mean"],ens["gates_mean"],anchor_scores[ii],cache["specialist"][ii],cache["quality"][ii]); calibrator=MetaCalibrator.fit(mx,ens["labels"],bootstraps=int(cfg["calibration"].get("bootstrap_members",15)),seed=int(cfg["training"].get("seed",1337))); cstats=calibrator.predict_stats(mx); probs=cstats["mean"]
+    rthr,athr=select_thresholds(ens["labels"],probs,cfg["calibration"]); metrics=selective_metrics(ens["labels"],probs,rthr,athr,cstats["lower"],cstats["upper"])
+    meta_path=Path(cache_path).with_suffix(Path(cache_path).suffix+".meta.json"); cache_meta=json.loads(meta_path.read_text(encoding="utf-8")) if meta_path.exists() else {}
+    specialist_ck=None
+    if cache_meta.get("specialists") and Path(cache_meta["specialists"]).exists(): specialist_ck=torch.load(cache_meta["specialists"],map_location="cpu",weights_only=False)
+    foundation_state=None
+    if cache_meta.get("foundation_state") and Path(cache_meta["foundation_state"]).exists(): foundation_state=torch.load(cache_meta["foundation_state"],map_location="cpu",weights_only=False)
+    checkpoint={"version":5,"name":"RAVEN-F2K-BUDGET-MAX","config":cfg,"dims":dims,"foundation_backend":cache_meta.get("foundation_actual",cfg["foundation"].get("backend","dinov2_vits14")),"foundation_dim":cache_meta.get("foundation_dim",dims["semantic"]),"foundation_state":foundation_state,"normalizer":normalizer.to_dict(),"anchors":anchors.to_dict(),"ai_source_map":ai_map,"real_source_map":real_map,"ensemble_states":[m.state_dict() for m in members],"members":member_info,"calibrator":calibrator.to_dict(),"real_threshold":rthr,"ai_threshold":athr,"validation_metrics":metrics,"specialists_checkpoint":specialist_ck}
+    p=Path(out_path); p.parent.mkdir(parents=True,exist_ok=True); torch.save(checkpoint,p)
+    print("[validation]"); [print(f"  {k}: {v}") for k,v in metrics.items()]; print(f"[saved] {p}")
+    return metrics

raven/transforms.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+import io
+import random
+import numpy as np
+from PIL import Image, ImageEnhance, ImageFilter, ImageOps
+import torch
+from torchvision import transforms as T
+
+IMAGENET_MEAN = (0.485, 0.456, 0.406)
+IMAGENET_STD = (0.229, 0.224, 0.225)
+
+
+def jpeg_recompress(img: Image.Image, quality: int) -> Image.Image:
+    b = io.BytesIO()
+    img.convert("RGB").save(b, format="JPEG", quality=int(quality), optimize=False)
+    b.seek(0)
+    return Image.open(b).convert("RGB")
+
+
+def sensor_noise(img: Image.Image, sigma: float) -> Image.Image:
+    a = np.asarray(img.convert("RGB"), dtype=np.float32) / 255.0
+    read = np.random.normal(0, sigma, a.shape).astype(np.float32)
+    shot = np.random.normal(0, np.sqrt(np.clip(a, 0, 1) + 1e-4) * sigma * 0.35).astype(np.float32)
+    a = np.clip(a + read + shot, 0, 1)
+    return Image.fromarray((a * 255 + .5).astype(np.uint8), mode="RGB")
+
+
+class SymmetricAugment:
+
+    def __call__(self, image: Image.Image) -> Image.Image:
+        im = ImageOps.exif_transpose(image).convert("RGB")
+        if random.random() < .70:
+            im = jpeg_recompress(im, random.randint(35, 100))
+        if random.random() < .15:
+            im = jpeg_recompress(im, random.randint(45, 92))
+        if random.random() < .52:
+            w, h = im.size; s = random.uniform(.45, 1.25)
+            im = im.resize((max(64, int(w*s)), max(64, int(h*s))), random.choice([
+                Image.Resampling.BICUBIC, Image.Resampling.BILINEAR, Image.Resampling.LANCZOS]))
+        if random.random() < .20:
+            im = im.filter(ImageFilter.GaussianBlur(random.uniform(.1, 1.25)))
+        if random.random() < .12:
+            im = im.filter(ImageFilter.UnsharpMask(radius=1, percent=random.randint(60, 130), threshold=2))
+        if random.random() < .25:
+            im = ImageEnhance.Brightness(im).enhance(random.uniform(.68, 1.30))
+        if random.random() < .25:
+            im = ImageEnhance.Contrast(im).enhance(random.uniform(.72, 1.28))
+        if random.random() < .15:
+            im = ImageEnhance.Color(im).enhance(random.uniform(.72, 1.28))
+        if random.random() < .18:
+            im = sensor_noise(im, random.uniform(.002, .016))
+        if random.random() < .18:
+            w, h = im.size; s = random.uniform(.60, .92)
+            tmp = im.resize((max(64, int(w*s)), max(64, int(h*s))), Image.Resampling.BICUBIC)
+            im = tmp.resize((w, h), Image.Resampling.BILINEAR)
+            if random.random() < .7:
+                im = jpeg_recompress(im, random.randint(55, 92))
+        return im
+
+
+def foundation_transform(size: int = 224):
+    return T.Compose([
+        T.Resize(size + 32, interpolation=T.InterpolationMode.BICUBIC),
+        T.CenterCrop(size),
+        T.ToTensor(),
+        T.Normalize(IMAGENET_MEAN, IMAGENET_STD),
+    ])

raven/utils.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+import hashlib
+import json
+import os
+import random
+from pathlib import Path
+from typing import Iterable
+import numpy as np
+import torch
+
+IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".webp", ".bmp", ".tif", ".tiff"}
+
+
+def seed_everything(seed: int) -> None:
+    random.seed(seed)
+    np.random.seed(seed)
+    torch.manual_seed(seed)
+    if torch.cuda.is_available():
+        torch.cuda.manual_seed_all(seed)
+
+
+def configure_cpu(threads: int = 6, interop_threads: int = 1) -> None:
+    threads = max(1, int(threads))
+    os.environ.setdefault("OMP_NUM_THREADS", str(threads))
+    os.environ.setdefault("MKL_NUM_THREADS", str(threads))
+    torch.set_num_threads(threads)
+    try:
+        torch.set_num_interop_threads(max(1, int(interop_threads)))
+    except RuntimeError:
+        pass
+    torch.backends.mkldnn.enabled = True
+
+
+def stable_unit(text: str) -> float:
+    h = hashlib.sha256(text.encode("utf-8")).digest()
+    return int.from_bytes(h[:8], "big") / float(2**64 - 1)
+
+
+def iter_images(root: str | Path) -> Iterable[Path]:
+    root = Path(root)
+    if not root.exists():
+        return
+    for p in root.rglob("*"):
+        if p.is_file() and p.suffix.lower() in IMAGE_EXTS:
+            yield p
+
+
+def read_jsonl(path: str | Path) -> list[dict]:
+    rows: list[dict] = []
+    with Path(path).open("r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                rows.append(json.loads(line))
+    return rows
+
+
+def write_jsonl(path: str | Path, rows: Iterable[dict]) -> None:
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    with p.open("w", encoding="utf-8") as f:
+        for row in rows:
+            f.write(json.dumps(row, ensure_ascii=False) + "\n")
+
+
+def safe_source_name(source: str) -> str:
+    return "".join(c if c.isalnum() or c in "-_." else "_" for c in str(source))[:96]