synth-curator 0.1.0__py3-none-any.whl

synth_curator/__init__.py

@@ -0,0 +1,7 @@
+"""synth-curator: utility-weighted curation of synthetic image pools."""
+__version__ = "0.1.0"   # set before the imports below - weights_bundle.py reads it during import
+
+from .model_interface import Model, ProductionModel, model_from_function
+from .pipeline import SynthCurator
+
+__all__ = ["Model", "ProductionModel", "SynthCurator", "model_from_function"]

synth_curator/__main__.py

@@ -0,0 +1,5 @@
+"""`python -m synth_curator <config.yaml>` - see cli.py."""
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

synth_curator/cli.py

@@ -0,0 +1,49 @@
+"""Command-line entry point: `synth-curator <config.yaml>`.
+
+Builds a SynthCurator from the config and runs it - the literal top-level starting point for
+someone who has real images, a synthetic pool, and a config file, and wants to run the whole
+pipeline without wiring the Python API themselves.
+
+    $ synth-curator config.yaml                     # -> curated manifest CSV path
+    $ synth-curator config.yaml --train-production   # -> also trains the production model
+    $ python -m synth_curator config.yaml
+
+With a config `resample:` section, both of the above sweep N seeds (SynthCurator.resample())
+instead of running once - see config.example.yaml.
+
+The model comes from the config's `model:` block (a dotted `trainer` path); this entry point has
+no way to pass a Python Model object directly - use SynthCurator.from_config in your own script
+for that.
+"""
+from __future__ import annotations
+
+import argparse
+import logging
+
+from .pipeline import SynthCurator
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="synth-curator")
+    parser.add_argument("config", help="path to a config.example.yaml-style YAML file")
+    parser.add_argument("-q", "--quiet", action="store_true", help="only show warnings and errors")
+    parser.add_argument("--train-production", action="store_true",
+                        help="also train the production model on the curated set (needs your "
+                             "model's trainer to implement train_production); prints whatever it returns")
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(level=logging.WARNING if args.quiet else logging.INFO, format="%(message)s")
+
+    sc = SynthCurator.from_config(args.config)
+    seeds = SynthCurator.resample_seeds_from_config(args.config)
+    if seeds is None:
+        print(sc.train_production() if args.train_production else sc.run())
+    else:
+        for seed, resampled in sc.resample(seeds).items():
+            result = resampled.train_production() if args.train_production else resampled.run()
+            print(f"seed={seed}: {result}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

synth_curator/core/__init__.py

@@ -0,0 +1 @@
+"""Shared math: scoring, FID/KID/SWD, sampling, safety, groups, registry, fingerprint."""

synth_curator/core/block_search.py

@@ -0,0 +1,134 @@
+"""Optional per-class block search (block_search=True): distributionally score each class of each
+drawn block against the same class of the real set, then pick the best block.
+
+Port of v14 evaluate_distributional_utility_per_class / select_optimal_block_per_class /
+write_class_log. Off by default in v15 (the winning block's U_dist did not track downstream F2).
+"""
+from __future__ import annotations
+
+import logging
+from collections import defaultdict
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import torch
+
+from .distributional import calculate_fid, calculate_kid, calculate_swd, get_stats
+from .features import load_features, real_class_lookup, stack_synthetic
+from .registry import DEFAULT_DIST_MIN_SAMPLES, is_distributional, props
+from .sampling import class_index
+from .scoring import calculate_robust_bounds, calculate_robust_score
+
+log = logging.getLogger(__name__)
+
+
+def _usable_dist_metrics(dist_metrics, n_real, n_synth, min_samples):
+    """Which distributional metrics a class has enough samples to estimate."""
+    n = min(n_real, n_synth)
+    return [m for m in dist_metrics if n >= min_samples[props(m)["family"]]]
+
+
+def evaluate_distributional_utility_per_class(blocks, per_class_weights, features_dir: Path,
+                                              classes: list[str], min_samples: dict | None = None):
+    """Sets per block: U_dist_by_class, U_dist (mean over scored classes), dist_detail, distributional_scores."""
+    min_samples = {**DEFAULT_DIST_MIN_SAMPLES, **(min_samples or {})}
+    idx = class_index({c: 0 for c in classes})
+    all_dist = sorted({m for w in per_class_weights.values() for m in w if is_distributional(m)})
+    for b in blocks:
+        b["U_dist"], b["U_dist_by_class"], b["dist_detail"], b["distributional_scores"] = 0.0, {}, [], {}
+    if not all_dist:
+        log.info("no distributional metrics in the weights: U_dist = 0 for all blocks")
+        return blocks
+
+    lookup = real_class_lookup(features_dir)
+    spaces = sorted({props(m)["space"] for m in all_dist})
+    synth = {s: load_features(features_dir, "synthetic", s) for s in spaces}
+    real_by_class = {}
+    for s in spaces:
+        buckets = defaultdict(list)
+        for key, vec in load_features(features_dir, "real", s).items():
+            class_name = lookup.get(Path(key).stem)
+            if class_name in idx:
+                buckets[class_name].append(vec)
+        real_by_class[s] = {c: torch.stack(v).float() for c, v in buckets.items()}
+
+    real_stats_cache = {}
+    for class_name in classes:
+        weights = per_class_weights.get(class_name, {})
+        cls_dist = [m for m in all_dist if m in weights]
+        if not cls_dist:
+            continue
+        n_real = max(len(real_by_class[props(m)["space"]].get(class_name, [])) for m in cls_dist)
+        n_synth = min(int((b["df"]["target_class_label"] == class_name).sum()) for b in blocks)
+        usable = _usable_dist_metrics(cls_dist, n_real, n_synth, min_samples)
+        if not usable:
+            log.info("[%s] n_real=%d n_synth=%d: no estimable metric, class skipped", class_name, n_real, n_synth)
+            continue
+        share = sum(weights[m] for m in usable)
+        if share <= 0:
+            continue
+        renorm = {m: weights[m] / share for m in usable}
+
+        for m in usable:
+            p = props(m)
+            real_tensor = real_by_class[p["space"]][class_name]
+            raw_scores = []
+            for b in blocks:
+                names = b["df"].loc[b["df"]["target_class_label"] == class_name, "filename"].tolist()
+                st = stack_synthetic(synth[p["space"]], names)
+                if p["family"] == "fid":
+                    key = (class_name, p["space"])
+                    if key not in real_stats_cache:
+                        real_stats_cache[key] = get_stats(real_tensor)
+                    mu_r, sg_r = real_stats_cache[key]
+                    mu_s, sg_s = get_stats(st)
+                    score = calculate_fid(mu_s, sg_s, mu_r, sg_r)
+                elif p["family"] == "kid":
+                    score = calculate_kid(st, real_tensor)
+                else:  # swd needs equal row counts: trim the longer side
+                    a, r = st, real_tensor
+                    if a.shape[0] != r.shape[0]:
+                        keep = min(a.shape[0], r.shape[0])
+                        g = torch.Generator().manual_seed(b["idx"] * 1000 + idx[class_name])
+                        if a.shape[0] > keep:
+                            a = a[torch.randperm(a.shape[0], generator=g)[:keep]]
+                        if r.shape[0] > keep:
+                            r = r[torch.randperm(r.shape[0], generator=g)[:keep]]
+                    score = calculate_swd(a, r, generator=torch.Generator().manual_seed(idx[class_name] * 97 + len(m)))
+                raw_scores.append(score)
+
+            series = pd.Series(raw_scores)
+            vmin, vmax = calculate_robust_bounds(series)
+            norm = calculate_robust_score(series, vmin, vmax, p["optimize"])
+            for i, b in enumerate(blocks):
+                b["U_dist_by_class"][class_name] = b["U_dist_by_class"].get(class_name, 0.0) + renorm[m] * float(norm.iloc[i])
+                b["dist_detail"].append((class_name, m, raw_scores[i], float(norm.iloc[i])))
+                b["distributional_scores"][f"Raw_{class_name}_{m}"] = raw_scores[i]
+                b["distributional_scores"][f"Normalized_{class_name}_{m}"] = float(norm.iloc[i])
+
+    for b in blocks:
+        scored = b["U_dist_by_class"]
+        b["U_dist"] = float(np.mean(list(scored.values()))) if scored else 0.0
+    return blocks
+
+
+def select_optimal_block_per_class(blocks):
+    """Argmax of U_dist. Selection is purely distributional (instance quality already shaped the draw);
+    U_inst is recorded for logging only."""
+    best, best_score = None, -float("inf")
+    for b in blocks:
+        b["U_inst"] = b["df"]["S_Composite"].mean()
+        b["S_Final"] = b["U_dist"]
+        if b["U_dist"] > best_score:
+            best, best_score = b, b["U_dist"]
+    log.info("winner: block %d (U_dist=%.4f)", best["idx"], best_score)
+    return best["df"], blocks
+
+
+def write_class_log(blocks, path: Path) -> None:
+    rows = [{"Block_ID": b["idx"], "target_class_label": class_name, "metric": m, "raw": raw, "normalized": norm,
+             "U_dist_class": b["U_dist_by_class"].get(class_name), "U_dist_block": b["U_dist"]}
+            for b in blocks for class_name, m, raw, norm in b["dist_detail"]]
+    if rows:
+        pd.DataFrame(rows).to_csv(path, index=False)

synth_curator/core/distributional.py

@@ -0,0 +1,109 @@
+"""FID / KID / SWD (+ precision/recall helpers) on feature tensors.
+
+Port of metric_pipeline/torch_metrics.py; math unchanged.
+"""
+from __future__ import annotations
+
+import logging
+
+import numpy as np
+import torch
+from scipy import linalg
+
+log = logging.getLogger(__name__)
+
+
+def get_stats(features: torch.Tensor, eps: float = 1e-6):
+    """Mean and regularized covariance of a feature set (float64)."""
+    mu = torch.mean(features, dim=0, dtype=torch.float64)
+    sigma = torch.cov(features.to(torch.double).T)
+    sigma = sigma + torch.eye(sigma.shape[0], device=features.device, dtype=torch.float64) * eps
+    return mu, sigma
+
+
+def calculate_fid(mu1: torch.Tensor, sigma1: torch.Tensor,
+                  mu2: torch.Tensor, sigma2: torch.Tensor) -> float:
+    """Frechet distance between two Gaussians (synthetic first, real second). Lower is better."""
+    mu1_np = mu1.cpu().numpy().astype(np.float64)
+    sigma1_np = sigma1.cpu().numpy().astype(np.float64)
+    mu2_np = mu2.cpu().numpy().astype(np.float64)
+    sigma2_np = sigma2.cpu().numpy().astype(np.float64)
+
+    diff = mu1_np - mu2_np
+    mean_term = diff.dot(diff)
+
+    try:
+        covmean = linalg.sqrtm(sigma1_np @ sigma2_np)
+    except linalg.LinAlgError:
+        log.warning("linalg.sqrtm failed to converge; returning inf")
+        return float("inf")
+
+    if np.iscomplexobj(covmean):
+        covmean = covmean.real
+
+    if not np.isfinite(covmean).all():
+        log.warning("sqrtm returned non-finite values; retrying with a small diagonal offset")
+        offset = np.eye(sigma1_np.shape[0]) * 1e-6
+        covmean = linalg.sqrtm((sigma1_np + offset) @ (sigma2_np + offset))
+        if np.iscomplexobj(covmean):
+            covmean = covmean.real
+
+    fid = mean_term + np.trace(sigma1_np + sigma2_np - 2 * covmean)
+    return 0.0 if fid < 0 else float(fid)
+
+
+def calculate_swd(features1, features2, n_projections=128, generator=None) -> float:
+    """Sliced Wasserstein distance; equal row counts required. Pass a seeded generator for reproducibility."""
+    features1 = features1.cpu().to(torch.float32)
+    features2 = features2.cpu().to(torch.float32)
+    projections = torch.randn(features1.shape[1], n_projections, generator=generator)
+    projections = projections / torch.linalg.norm(projections, dim=0, keepdim=True)
+    sorted1, _ = torch.sort(features1 @ projections, dim=0)
+    sorted2, _ = torch.sort(features2 @ projections, dim=0)
+    return torch.mean(torch.abs(sorted1 - sorted2)).item()
+
+
+def _polynomial_kernel(X, Y, degree=3, gamma=None, coef0=1):
+    if gamma is None:
+        gamma = 1.0 / X.shape[1]
+    return (X @ Y.T * gamma + coef0) ** degree
+
+
+def calculate_kid(features1, features2) -> float:
+    """Kernel Inception Distance (polynomial kernel)."""
+    features1 = features1.cpu().to(torch.float32)
+    features2 = features2.cpu().to(torch.float32)
+    k_xx = _polynomial_kernel(features1, features1)
+    k_yy = _polynomial_kernel(features2, features2)
+    k_xy = _polynomial_kernel(features1, features2)
+    return (k_xx.mean() + k_yy.mean() - 2 * k_xy.mean()).item()
+
+
+def calculate_per_image_kl_divergence(probabilities: torch.Tensor, eps: float = 1e-16) -> torch.Tensor:
+    """Per-image KL(p(y|x) || p(y)): the per-image term of the Inception Score."""
+    eps_t = torch.tensor(eps, device=probabilities.device, dtype=torch.float32)
+    p_y = probabilities.mean(dim=0, keepdim=True)
+    return torch.sum(probabilities * (torch.log(probabilities + eps_t) - torch.log(p_y + eps_t)), dim=1)
+
+
+def calculate_precision_recall_scores(real_features, synth_features, k=3) -> dict:
+    """Global precision/recall plus per-image realism/coverage (k-NN distances). Uses the GPU if present."""
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    real_features = real_features.to(device)
+    synth_features = synth_features.to(device)
+
+    def kth(dists, k_):
+        return torch.kthvalue(dists, k=k_, dim=1)[0]
+
+    per_image_realism = kth(torch.cdist(synth_features, real_features, p=2), k)
+    per_image_coverage = kth(torch.cdist(real_features, synth_features, p=2), k)
+    real_manifold = kth(torch.cdist(real_features, real_features, p=2), k + 1)
+
+    precision = (per_image_realism.unsqueeze(1) <= real_manifold.unsqueeze(0)).any(dim=1).float().mean().item()
+    recall = (per_image_coverage.unsqueeze(1) <= real_manifold.unsqueeze(0)).any(dim=1).float().mean().item()
+    return {
+        "precision": precision,
+        "recall": recall,
+        "per_image_realism_scores": per_image_realism.cpu(),
+        "per_image_coverage_scores": per_image_coverage.cpu(),
+    }

synth_curator/core/features.py

@@ -0,0 +1,43 @@
+"""Feature-tensor access. A feature space is two dicts {filename: 1-D tensor}, one for the real
+reference set and one for the synthetic pool, stored as `{real,synthetic}_{space}.pt` in
+`features_dir` (space = dino | inception). Real class labels (only needed for block_search) live
+in `real_labels.csv` (columns: filename, class)."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+import torch
+
+from ..exceptions import MissingFeaturesError
+
+
+def feature_path(features_dir: Path, role: str, space: str) -> Path:
+    return Path(features_dir) / f"{role}_{space}.pt"
+
+
+def load_features(features_dir: Path, role: str, space: str) -> dict[str, torch.Tensor]:
+    path = feature_path(features_dir, role, space)
+    if not path.exists():
+        raise MissingFeaturesError(f"missing feature file {path}")
+    return torch.load(path, map_location="cpu")
+
+
+def stack_real(real: dict[str, torch.Tensor]) -> torch.Tensor:
+    return torch.stack(list(real.values())).float()
+
+
+def stack_synthetic(synth: dict[str, torch.Tensor], filenames) -> torch.Tensor:
+    try:
+        return torch.stack([synth[f] for f in filenames]).float()
+    except KeyError as e:
+        raise MissingFeaturesError(f"image {e} is in the metadata but not in the feature dict") from None
+
+
+def real_class_lookup(features_dir: Path) -> dict[str, str]:
+    """{filename stem: class} for the real reference set (FS-CS and block_search need it)."""
+    path = Path(features_dir) / "real_labels.csv"
+    if not path.exists():
+        raise MissingFeaturesError(f"missing {path} (columns: filename, class); FS-CS and block_search need real class labels")
+    df = pd.read_csv(path)
+    return {Path(f).stem: c for f, c in zip(df["filename"], df["class"])}

synth_curator/core/fingerprint.py

@@ -0,0 +1,31 @@
+"""Marks a cached output with the inputs that built it, so a later call can tell it's stale. No
+fingerprint file present is treated as a match (never invalidates a cache it didn't itself write)."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def _path(out_dir: Path) -> Path:
+    return Path(str(out_dir) + ".fingerprint.json")
+
+
+def exists(out_dir: Path) -> bool:
+    return _path(out_dir).exists()
+
+
+def matches(out_dir: Path, current: dict[str, Any]) -> bool:
+    """True only if a fingerprint is present AND equals `current` exactly."""
+    path = _path(out_dir)
+    if not path.exists():
+        return False
+    try:
+        stored = json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return False
+    return stored == current
+
+
+def write(out_dir: Path, current: dict[str, Any]) -> None:
+    _path(out_dir).write_text(json.dumps(current, indent=2, sort_keys=True))

synth_curator/core/geometry.py

@@ -0,0 +1,25 @@
+"""Cosine k-NN in feature space (a plain-torch replacement for a FAISS dependency).
+
+Distances match FAISS IndexFlatL2 on L2-normalized vectors: squared L2 = 2 - 2*cos.
+Used by the KNN map, realism (synthetic vs real) and diversity (synthetic vs synthetic).
+"""
+from __future__ import annotations
+
+import torch
+
+
+def knn_cosine(query: torch.Tensor, db: torch.Tensor, k: int, chunk: int = 2048):
+    """Returns (D, I): squared-L2 distances and indices of the k nearest `db` rows per `query` row, ascending."""
+    q = query.float()
+    d = db.float()
+    q = q / (q.norm(dim=1, keepdim=True) + 1e-8)
+    d = d / (d.norm(dim=1, keepdim=True) + 1e-8)
+    if torch.cuda.is_available():
+        d = d.cuda()
+    dists, idxs = [], []
+    for i in range(0, len(q), chunk):
+        sim = q[i:i + chunk].to(d.device) @ d.T
+        top = sim.topk(k, dim=1)
+        dists.append((2 - 2 * top.values).clamp_min(0).cpu())
+        idxs.append(top.indices.cpu())
+    return torch.cat(dists).numpy(), torch.cat(idxs).numpy()

synth_curator/core/groups.py

@@ -0,0 +1,87 @@
+"""Group distributional scores: one score per (generation group, distributional metric),
+normalized to [0,1] across groups (1.0 = best), inherited by every image in the group.
+
+Port of v15 compute_group_scores. Computed live from feature tensors so any `dist_group_by`
+partition works. Groups are large enough that FID is well estimated (per-class it is not).
+Group scores are global (all classes pooled); how much a class trusts them is per class (weights).
+"""
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+
+import pandas as pd
+import torch
+
+from .distributional import calculate_fid, calculate_kid, calculate_swd, get_stats
+from .features import load_features, stack_real, stack_synthetic
+from .registry import props
+from .scoring import calculate_robust_bounds, calculate_robust_score, group_key
+
+log = logging.getLogger(__name__)
+
+SWD_MAX_N = 8192   # cap the group-vs-real SWD sample so many groups stay affordable
+
+
+def compute_group_raw(df: pd.DataFrame, features_dir: Path, group_cols: list[str],
+                      dist_metrics: list[str]) -> pd.DataFrame:
+    """Raw distributional value per (group, metric); lower is better for all of them."""
+    df = df.assign(_group=group_key(df, group_cols))
+    groups = sorted(df["_group"].unique())
+    log.info("computing group scores over %s: %d groups", group_cols, len(groups))
+
+    spaces = sorted({props(m)["space"] for m in dist_metrics})
+    real = {s: stack_real(load_features(features_dir, "real", s)) for s in spaces}
+    synth = {s: load_features(features_dir, "synthetic", s) for s in spaces}
+
+    real_stats: dict[str, tuple] = {}
+    raw: dict[str, list[float]] = {m: [] for m in dist_metrics}
+    for gi, g in enumerate(groups):
+        names = df.loc[df["_group"] == g, "filename"].tolist()
+        for m in dist_metrics:
+            p = props(m)
+            rt = real[p["space"]]
+            st = stack_synthetic(synth[p["space"]], names)
+            if p["family"] == "fid":
+                if p["space"] not in real_stats:
+                    real_stats[p["space"]] = get_stats(rt)
+                mu_r, sg_r = real_stats[p["space"]]
+                mu_s, sg_s = get_stats(st)
+                raw[m].append(calculate_fid(mu_s, sg_s, mu_r, sg_r))
+            elif p["family"] == "kid":
+                raw[m].append(calculate_kid(st, rt))
+            else:
+                gen = torch.Generator().manual_seed(gi)
+                n = min(st.shape[0], rt.shape[0], SWD_MAX_N)
+                a = st[torch.randperm(st.shape[0], generator=gen)[:n]]
+                b = rt[torch.randperm(rt.shape[0], generator=gen)[:n]]
+                raw[m].append(calculate_swd(a, b, generator=torch.Generator().manual_seed(gi)))
+
+    return pd.DataFrame({m: pd.Series(raw[m], index=groups) for m in dist_metrics})
+
+
+def compute_group_scores(df: pd.DataFrame, features_dir: Path, group_cols: list[str],
+                         dist_metrics: list[str], cache_path: Path | None = None) -> pd.DataFrame:
+    """Raw group values normalized across groups to [0,1], 1.0 = best."""
+    if cache_path is not None and Path(cache_path).exists():
+        g = pd.read_csv(cache_path, index_col=0)
+        if set(dist_metrics).issubset(g.columns):
+            log.info("group scores loaded from cache %s", cache_path)
+            return g
+
+    raw = compute_group_raw(df, features_dir, group_cols, dist_metrics)
+    scores = {}
+    for m in dist_metrics:
+        vmin, vmax = calculate_robust_bounds(raw[m])
+        scores[m] = calculate_robust_score(raw[m], vmin, vmax, props(m)["optimize"])
+        log.info("%s best group: %s (raw %.4f)", m, scores[m].idxmax(), raw[m][scores[m].idxmax()])
+    out = pd.DataFrame(scores)
+
+    if cache_path is not None:
+        cache_path = Path(cache_path)
+        cache_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = cache_path.with_suffix(cache_path.suffix + f".tmp{os.getpid()}")
+        out.to_csv(tmp)
+        os.replace(tmp, cache_path)
+    return out

synth_curator/core/output.py

@@ -0,0 +1,45 @@
+"""Curation outputs: manifest CSV, block log, weights-used JSON.
+
+Port of create_csv_manifest (metric_pipeline/dataset_curation/main.py) and generate_evaluation_log.
+Write the manifest BEFORE the log: the manifest is the deliverable, and a log-first write once
+destroyed a completed curation.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pandas as pd
+
+
+def write_manifest(selected: pd.DataFrame, out_csv: Path, image_dir: Path | None = None) -> Path:
+    """CSV with source_path, target_class, safe_filename."""
+    out_csv.parent.mkdir(parents=True, exist_ok=True)
+    src = selected["filename"].map(lambda f: str(image_dir / f) if image_dir else str(f))
+    pd.DataFrame({
+        "source_path": src.values,
+        "target_class": selected["target_class_label"].values,
+        "safe_filename": selected["filename"].astype(str).str.replace("/", "_").str.replace("\\", "_").values,
+    }).to_csv(out_csv, index=False)
+    return out_csv
+
+
+def write_block_log(blocks: list[dict], path: Path) -> None:
+    """Per-image scores + block-level utilities for every drawn block."""
+    frames = []
+    for b in blocks:
+        d = b["df"].copy()
+        d["Block_U_inst"], d["Block_U_dist"], d["Block_S_Final"] = b["U_inst"], b["U_dist"], b["S_Final"]
+        for k, v in b["distributional_scores"].items():
+            d[k] = v
+        frames.append(d)
+    log_df = pd.concat(frames, ignore_index=True)
+    core = [c for c in ["filename", "Block_ID", "target_class_label", "S_Composite", "Block_S_Final",
+                        "Block_U_inst", "Block_U_dist"] if c in log_df.columns]
+    log_df[core + [c for c in log_df.columns if c not in core]].to_csv(path, index=False)
+
+
+def write_weights_used(path: Path, weights: dict, params: dict) -> None:
+    from .. import __version__
+    path.write_text(json.dumps({"algorithm": "v15", "library_version": __version__,
+                                "params": params, "weights": weights}, indent=2))

synth_curator/core/registry.py

@@ -0,0 +1,61 @@
+"""Metric registry: name -> type, optimize direction, and for distributional metrics the
+family (fid|kid|swd) and feature space (dino|inception) they are computed on.
+
+Port of METRIC_PROPERTIES in framework_utils/utils.py. Mutable on purpose: add your own entry
+(and a calculator in steps/metrics) to extend the portfolio.
+"""
+from ..exceptions import SynthCuratorError
+
+
+def _inst(optimize: str) -> dict:
+    return {"type": "instance", "optimize": optimize}
+
+
+def _dist(family: str, space: str) -> dict:
+    return {"type": "distributional", "optimize": "min", "family": family, "space": space}
+
+
+METRIC_PROPERTIES: dict[str, dict] = {
+    "psnr_score": _inst("max"),
+    "ssim_score": _inst("max"),
+    "fsim_score": _inst("max"),
+    "lpips_score": _inst("min"),
+    "brisqe_score": _inst("min"),
+    "fscs_score": _inst("max"),
+    "clip_similarity_cancer": _inst("max"),
+    "clip_similarity_artifact": _inst("min"),
+    "clip_log_odds_score": _inst("max"),
+    "diversity_score": _inst("max"),
+    "realism_score": _inst("min"),
+    "is_contribution_score": _inst("max"),
+    "fid_inception": _dist("fid", "inception"),
+    "fid_dino": _dist("fid", "dino"),
+    "kid_dino": _dist("kid", "dino"),
+    "swd_dino": _dist("swd", "dino"),
+}
+
+DEFAULT_DIST_MIN_SAMPLES = {"fid": 2048, "kid": 256, "swd": 64}
+
+
+def props(metric: str) -> dict:
+    try:
+        return METRIC_PROPERTIES[metric]
+    except KeyError:
+        raise SynthCuratorError(f"unknown metric {metric!r}; known: {sorted(METRIC_PROPERTIES)}") from None
+
+
+def is_distributional(metric: str) -> bool:
+    return props(metric)["type"] == "distributional"
+
+
+def is_instance(metric: str) -> bool:
+    return props(metric)["type"] == "instance"
+
+
+# The default metric portfolio (fid_dino is registered but not part of the locked configuration).
+DEFAULT_METRICS = [
+    "clip_log_odds_score", "fscs_score", "clip_similarity_cancer", "clip_similarity_artifact",
+    "lpips_score", "fsim_score", "brisqe_score", "psnr_score", "ssim_score",
+    "diversity_score", "realism_score", "is_contribution_score",
+    "fid_inception", "kid_dino", "swd_dino",
+]