vecscope 0.1.0__py3-none-any.whl

vecscope/__init__.py

@@ -0,0 +1,6 @@
+"""vecscope: embedding space evidence for agents."""
+
+from vecscope.evidence import Evidence, Finding, audit
+
+__version__ = "0.1.0"
+__all__ = ["Evidence", "Finding", "__version__", "audit"]

vecscope/_knn.py

@@ -0,0 +1,46 @@
+"""Exact k-nearest-neighbor helpers (NumPy only, blocked for memory)."""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def normalize(x: np.ndarray) -> np.ndarray:
+    x = np.asarray(x, dtype=np.float32)
+    norms = np.linalg.norm(x, axis=1, keepdims=True)
+    norms[norms == 0] = 1.0
+    return x / norms
+
+
+def exact_knn(
+    x: np.ndarray, k: int, metric: str = "cosine", block: int = 2048
+) -> tuple[np.ndarray, np.ndarray]:
+    """Return (indices, distances) of the k nearest neighbors, excluding self.
+
+    distances are cosine distance (1 - cos) or squared euclidean.
+    """
+    n = x.shape[0]
+    k = min(k, n - 1)
+    if metric == "cosine":
+        q = normalize(x)
+    else:  # "dot" (negative inner product) or "euclidean"
+        q = np.asarray(x, dtype=np.float32)
+    sq = (q * q).sum(axis=1)
+    idx = np.empty((n, k), dtype=np.int64)
+    dist = np.empty((n, k), dtype=np.float32)
+    for s in range(0, n, block):
+        e = min(s + block, n)
+        if metric == "cosine":
+            d = 1.0 - q[s:e] @ q.T
+        elif metric == "dot":
+            d = -(q[s:e] @ q.T)
+        else:
+            d = sq[s:e, None] - 2.0 * (q[s:e] @ q.T) + sq[None, :]
+        rows = np.arange(e - s)
+        d[rows, np.arange(s, e)] = np.inf  # drop self
+        part = np.argpartition(d, k, axis=1)[:, :k]
+        pd = np.take_along_axis(d, part, axis=1)
+        order = np.argsort(pd, axis=1)
+        idx[s:e] = np.take_along_axis(part, order, axis=1)
+        dist[s:e] = np.take_along_axis(pd, order, axis=1)
+    return idx, dist

vecscope/cli.py

@@ -0,0 +1,87 @@
+"""vecscope CLI: `vecscope audit embeddings.npy`."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from vecscope import __version__
+from vecscope.evidence import audit
+from vecscope.io import load_vectors
+from vecscope.sweep import render_sweep, sweep
+
+
+def _render_text(ev) -> str:
+    mark = {"ok": "ok  ", "warn": "WARN", "fail": "FAIL"}
+    head = f"vecscope {ev.version}  n={ev.n} dim={ev.dim} k={ev.k}  verdict={ev.verdict.upper()}"
+    if ev.sampled:
+        head += f"  (sampled from {ev.n_total} rows)"
+    if ev.n_queries:
+        head += f"  queries={ev.n_queries}"
+    lines = [head]
+    for f in ev.findings:
+        lines.append(
+            f"  [{mark[f.verdict]}] {f.name:<16} {f.metric}={f.value:.4f}  ({f.healthy_range})"
+        )
+        lines.append(f"{'':25}{f.explanation}")
+    if ev.clusters:
+        lines.append(f"  clusters ({len(ev.clusters)}):")
+        lines.append(f"{'':4}{'id':>3}{'size':>7}{'share':>7}{'cos2ctr':>9}{'neardup':>9}"
+                     f"{'hubshare':>10}  sample_ids")
+        for c in ev.clusters:
+            lines.append(f"{'':4}{c['cluster']:>3}{c['size']:>7}{c['share']:>7.1%}"
+                         f"{c['mean_cosine_to_center']:>9.3f}{c['near_duplicate_ratio']:>9.1%}"
+                         f"{c['hub_share']:>10.1%}  {c['sample_ids']}")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="vecscope", description="Embedding space evidence for agents.")
+    p.add_argument("--version", action="version", version=f"vecscope {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    a = sub.add_parser("audit", help="audit an embedding matrix")
+    a.add_argument("path", help=".npy/.npz/.parquet/.jsonl/.csv with one vector per row")
+    a.add_argument("-k", type=int, default=10, help="neighbors per item (default 10)")
+    a.add_argument("--ann", help="optional .npy of ANN neighbor indices (n x k) to score recall")
+    a.add_argument("--queries", help="optional query embeddings (m x dim) for query-side findings")
+    a.add_argument("--clusters", type=int, default=0,
+                   help="attach a per-cluster report with this many clusters (0 = off)")
+    a.add_argument("--near-dup", type=float, default=0.99, help="cosine threshold for near-dups")
+    a.add_argument("--sample", type=int, default=100_000,
+                   help="audit a seeded random subset when n exceeds this (0 = all rows)")
+    a.add_argument("--json", action="store_true", help="emit JSON evidence instead of text")
+    a.add_argument("--fail-on", choices=["warn", "fail"], default="fail",
+                   help="exit 1 when verdict is at least this level")
+    s = sub.add_parser("sweep", help="sweep HNSW/IVF parameters (needs faiss-cpu)")
+    s.add_argument("path", help="embedding file, one vector per row")
+    s.add_argument("-k", type=int, default=10, help="neighbors per query (default 10)")
+    s.add_argument("--queries", help="optional query embeddings; default samples the corpus")
+    s.add_argument("--n-queries", type=int, default=1000, help="queries to time (default 1000)")
+    s.add_argument("--target-recall", type=float, default=0.95,
+                   help="recall@k a configuration must reach to be recommended")
+    s.add_argument("--device", choices=["auto", "cpu", "gpu"], default="auto",
+                   help="run IVF and the exact baseline on the GPU when faiss has GPU support "
+                        "(default auto); HNSW is CPU-only in faiss")
+    s.add_argument("--json", action="store_true", help="emit JSON instead of text")
+    args = p.parse_args(argv)
+
+    x = load_vectors(args.path)
+    if args.cmd == "sweep":
+        q = load_vectors(args.queries) if args.queries else None
+        res = sweep(x, k=args.k, queries=q, n_queries=args.n_queries,
+                    target_recall=args.target_recall, device=args.device)
+        print(json.dumps(res.to_dict(), indent=2) if args.json else render_sweep(res))
+        return 0
+
+    ann = load_vectors(args.ann).astype(int) if args.ann else None
+    q = load_vectors(args.queries) if args.queries else None
+    ev = audit(x, k=args.k, ann_neighbors=ann, near_dup_cos=args.near_dup,
+               sample=args.sample or None, queries=q, clusters=args.clusters)
+    print(ev.to_json() if args.json else _render_text(ev))
+    level = {"ok": 0, "warn": 1, "fail": 2}
+    return 1 if level[ev.verdict] >= level[args.fail_on] else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

vecscope/diagnostics/__init__.py

@@ -0,0 +1,20 @@
+from vecscope.diagnostics.anisotropy import anisotropy
+from vecscope.diagnostics.ann_recall import ann_recall
+from vecscope.diagnostics.clusters import cluster_report
+from vecscope.diagnostics.collapse import collapse
+from vecscope.diagnostics.geometry import (
+    connectivity,
+    distance_concentration,
+    metric_mismatch,
+    norms,
+    outliers,
+    rogue_dimensions,
+)
+from vecscope.diagnostics.hubness import hubness
+from vecscope.diagnostics.queries import query_audit
+
+__all__ = [
+    "anisotropy", "ann_recall", "cluster_report", "collapse", "connectivity",
+    "distance_concentration", "hubness", "metric_mismatch", "norms", "outliers",
+    "query_audit", "rogue_dimensions",
+]

vecscope/diagnostics/anisotropy.py

@@ -0,0 +1,48 @@
+"""Anisotropy: embeddings crowd into a narrow cone, so every pair looks similar.
+
+Evidence: mean cosine of random pairs (0 is isotropic), the norm of the mean unit vector
+(the shared direction every vector carries), the same cosine after subtracting that mean
+(what centering would buy), top principal-component share, effective rank (participation
+ratio of the covariance spectrum).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from vecscope._knn import normalize
+
+
+def anisotropy(x: np.ndarray, sample: int = 20000, seed: int = 0) -> dict:
+    rng = np.random.default_rng(seed)
+    q = normalize(x)
+    n, d = q.shape
+    m = min(sample, n)
+    a = rng.integers(0, n, m)
+    b = rng.integers(0, n, m)
+    keep = a != b
+    mean_cos = float((q[a[keep]] * q[b[keep]]).sum(axis=1).mean())
+    mean_vec = q.mean(axis=0)
+    qc = normalize(q - mean_vec)
+    mean_cos_centered = float((qc[a[keep]] * qc[b[keep]]).sum(axis=1).mean())
+
+    sub = q[rng.choice(n, min(n, 50000), replace=False)]
+    sub = sub - sub.mean(axis=0, keepdims=True)
+    s = np.linalg.svd(sub, compute_uv=False)
+    var = s**2
+    total = var.sum()
+    if total <= 0:  # constant input
+        var = np.zeros_like(var)
+        effective_rank = 0.0
+    else:
+        var = var / total
+        effective_rank = float(1.0 / (var**2).sum())
+    return {
+        "dim": int(d),
+        "mean_random_cosine": mean_cos,
+        "mean_vector_norm": float(np.linalg.norm(mean_vec)),
+        "mean_random_cosine_after_centering": mean_cos_centered,
+        "top1_pc_variance_share": float(var[0]) if var.size else 0.0,
+        "effective_rank": effective_rank,
+        "effective_rank_ratio": effective_rank / float(min(d, sub.shape[0])),
+    }

vecscope/diagnostics/ann_recall.py

@@ -0,0 +1,25 @@
+"""ANN recall: does the approximate index actually return the true neighbors?
+
+Compare neighbors returned by an ANN index (HNSW, IVF, ...) with exact k-NN.
+Evidence: recall@k, per-query worst recall, share of queries below a floor.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def ann_recall(exact_knn_idx: np.ndarray, ann_idx: np.ndarray, floor: float = 0.8) -> dict:
+    k = min(exact_knn_idx.shape[1], ann_idx.shape[1])
+    exact = exact_knn_idx[:, :k]
+    approx = ann_idx[:, :k]
+    hits = np.array([len(set(e.tolist()) & set(a.tolist())) for e, a in zip(exact, approx)])
+    per_query = hits / k
+    return {
+        "k": int(k),
+        "recall_at_k": float(per_query.mean()),
+        "recall_p05": float(np.quantile(per_query, 0.05)),
+        "min_recall": float(per_query.min()),
+        "queries_below_floor_ratio": float((per_query < floor).mean()),
+        "floor": floor,
+    }

vecscope/diagnostics/clusters.py

@@ -0,0 +1,64 @@
+"""Per-cluster report: where in the space do the problems live?
+
+A fixed-seed spherical k-means splits the corpus into a few regions; for each one the report
+gives size, tightness, near-duplicate share, how often its items act as hubs, and sample ids
+the agent can look up. No verdicts: this is a map, not a test.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from vecscope._knn import normalize
+
+
+def spherical_kmeans(q: np.ndarray, n_clusters: int, seed: int = 0, iters: int = 15) -> np.ndarray:
+    rng = np.random.default_rng(seed)
+    centers = q[rng.choice(q.shape[0], n_clusters, replace=False)].copy()
+    labels = np.zeros(q.shape[0], dtype=np.int64)
+    for _ in range(iters):
+        sims = q @ centers.T
+        new = sims.argmax(axis=1)
+        if np.array_equal(new, labels) and _ > 0:
+            break
+        labels = new
+        for c in range(n_clusters):
+            members = q[labels == c]
+            if members.size:
+                centers[c] = members.mean(axis=0)
+        centers = normalize(centers)
+    return labels
+
+
+def cluster_report(
+    x: np.ndarray,
+    n_clusters: int,
+    knn_idx: np.ndarray,
+    knn_dist: np.ndarray,
+    near_dup_cos: float,
+    seed: int = 0,
+    sample_ids: int = 5,
+) -> list[dict]:
+    q = normalize(x)
+    n = q.shape[0]
+    n_clusters = max(1, min(n_clusters, n // 10))
+    labels = spherical_kmeans(q, n_clusters, seed)
+    nk = np.bincount(knn_idx.ravel(), minlength=n).astype(np.float64)
+    nn_cos = 1.0 - knn_dist[:, 0]
+    report = []
+    for c in range(n_clusters):
+        m = np.nonzero(labels == c)[0]
+        if m.size == 0:
+            continue
+        center = normalize(q[m].mean(axis=0, keepdims=True))[0]
+        report.append({
+            "cluster": int(c),
+            "size": int(m.size),
+            "share": float(m.size / n),
+            "mean_cosine_to_center": float((q[m] @ center).mean()),
+            "near_duplicate_ratio": float((nn_cos[m] >= near_dup_cos).mean()),
+            "hub_share": float(nk[m].sum() / nk.sum()) if nk.sum() > 0 else 0.0,
+            "sample_ids": [int(i) for i in m[np.argsort(-(q[m] @ center))[:sample_ids]]],
+        })
+    report.sort(key=lambda r: -r["size"])
+    return report

vecscope/diagnostics/collapse.py

@@ -0,0 +1,32 @@
+"""Collapse: many vectors are (near) identical, so retrieval cannot tell them apart.
+
+Evidence: exact duplicate ratio, near-duplicate ratio (cos > threshold), and the
+share of items whose nearest neighbor is essentially itself.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from vecscope._knn import exact_knn
+
+
+def collapse(
+    x: np.ndarray, near_dup_cos: float = 0.99, knn_dist: np.ndarray | None = None
+) -> dict:
+    n = x.shape[0]
+    if knn_dist is None:
+        _, knn_dist = exact_knn(x, 1)
+    nn_cos = 1.0 - knn_dist[:, 0]
+    exact = float((nn_cos >= 1.0 - 1e-6).mean())
+    near = float((nn_cos >= near_dup_cos).mean())
+    unique_rows = np.unique(np.asarray(x, dtype=np.float32).round(6), axis=0).shape[0]
+    return {
+        "n": int(n),
+        "exact_duplicate_ratio": 1.0 - unique_rows / n,
+        "near_duplicate_ratio": near,
+        "nn_cosine_median": float(np.median(nn_cos)),
+        "nn_cosine_p95": float(np.quantile(nn_cos, 0.95)),
+        "near_dup_threshold": near_dup_cos,
+        "exact_nn_match_ratio": exact,
+    }

vecscope/diagnostics/geometry.py

@@ -0,0 +1,120 @@
+"""Geometry diagnostics derived from the shared exact k-NN pass.
+
+- rogue_dimensions: a handful of dimensions hold most of the variance, so cosine is decided
+  by them alone (Timkey & van Schijndel, 2021).
+- norms: vector lengths vary or vanish, which breaks inner-product retrieval.
+- metric_mismatch: cosine top-k and inner-product top-k disagree, so the index metric matters.
+- distance_concentration: all distances look alike, the nearest neighbor is barely nearer than
+  a random item (relative contrast, Aggarwal et al., 2001).
+- outliers: items whose nearest neighbor is unusually far, typically junk or foreign content.
+- connectivity: small islands in the k-NN graph that graph-based ANN attaches badly or never reaches.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def rogue_dimensions(x: np.ndarray, top: int = 3) -> dict:
+    var = np.asarray(x, dtype=np.float64).var(axis=0)
+    total = var.sum()
+    if total <= 0:  # constant matrix: every dimension is equally (un)informative
+        return {"top1_dim_variance_share": 0.0, "top3_dim_variance_share": 0.0,
+                "expected_share": 1.0 / x.shape[1], "rogue_dims": [0, 1, 2][: x.shape[1]]}
+    share = var / total
+    order = np.argsort(share)[::-1]
+    return {
+        "top1_dim_variance_share": float(share[order[0]]),
+        "top3_dim_variance_share": float(share[order[:top]].sum()),
+        "expected_share": 1.0 / x.shape[1],
+        "rogue_dims": [int(i) for i in order[:top]],
+    }
+
+
+def norms(x: np.ndarray) -> dict:
+    n = np.linalg.norm(np.asarray(x, dtype=np.float64), axis=1)
+    mean = n.mean()
+    return {
+        "norm_cv": float(n.std() / mean) if mean > 0 else 0.0,
+        "zero_norm_ratio": float((n == 0).mean()),
+        "norm_min": float(n.min()),
+        "norm_median": float(np.median(n)),
+        "norm_max": float(n.max()),
+    }
+
+
+def metric_mismatch(cos_knn: np.ndarray, dot_knn: np.ndarray) -> dict:
+    k = min(cos_knn.shape[1], dot_knn.shape[1])
+    a = np.sort(cos_knn[:, :k], axis=1)
+    b = np.sort(dot_knn[:, :k], axis=1)
+    overlap = np.array([np.intersect1d(r, s, assume_unique=True).size for r, s in zip(a, b)]) / k
+    return {
+        "k": int(k),
+        "topk_overlap": float(overlap.mean()),
+        "queries_fully_agreeing_ratio": float((overlap == 1.0).mean()),
+        "min_overlap": float(overlap.min()),
+    }
+
+
+def distance_concentration(nn_dist: np.ndarray, random_pair_cos: float) -> dict:
+    """Relative contrast on cosine distance: mean random distance over median NN distance."""
+    nn = np.asarray(nn_dist, dtype=np.float64)
+    distinct = nn[nn > 1e-4]  # exact duplicates (float32 noise ~1e-7) would pin the median at 0
+    median_nn = float(np.median(distinct)) if distinct.size else 0.0
+    mean_random = float(max(1.0 - random_pair_cos, 1e-9))
+    return {
+        "relative_contrast": mean_random / max(median_nn, 1e-6),
+        "median_nn_distance": median_nn,
+        "mean_random_distance": mean_random,
+    }
+
+
+def outliers(nn_dist: np.ndarray, factor: float = 3.0, sample_ids: int = 10) -> dict:
+    nn = np.asarray(nn_dist, dtype=np.float64)
+    distinct = nn[nn > 1e-4] if (nn > 1e-4).any() else nn
+    median = float(np.median(distinct))
+    mad = float(np.median(np.abs(distinct - median)))
+    cutoff = median + factor * 1.4826 * mad if mad > 0 else median * (1 + factor)
+    mask = nn > cutoff
+    worst = np.argsort(nn)[::-1][:sample_ids]
+    return {
+        "outlier_ratio": float(mask.mean()),
+        "cutoff_nn_distance": float(cutoff),
+        "median_nn_distance": median,
+        "sample_ids": [int(i) for i in worst if mask[i]],
+    }
+
+
+def connectivity(knn: np.ndarray, min_island_frac: float = 0.005, max_iter: int = 1000) -> dict:
+    """Connected components of the symmetrized k-NN graph via min-label propagation.
+
+    Large components are ordinary cluster structure. The retrieval risk is small islands:
+    components smaller than max(k + 1, min_island_frac * n), which graph-based ANN tends to
+    attach to the wrong region or never reach.
+    """
+    n, k = knn.shape
+    src = np.repeat(np.arange(n), k)
+    dst = knn.ravel()
+    a = np.concatenate([src, dst])
+    b = np.concatenate([dst, src])
+    label = np.arange(n)
+    for _ in range(max_iter):
+        new = label.copy()
+        np.minimum.at(new, a, label[b])
+        if np.array_equal(new, label):
+            break
+        label = new
+    labels, counts = np.unique(label, return_counts=True)
+    min_size = max(k + 1, int(np.ceil(min_island_frac * n)))
+    small = counts < min_size
+    island_items = int(counts[small].sum())
+    island_labels = labels[small]
+    sample = np.nonzero(np.isin(label, island_labels))[0][:10]
+    return {
+        "island_ratio": island_items / n,
+        "n_components": int(counts.size),
+        "n_islands": int(small.sum()),
+        "min_island_size": int(min_size),
+        "largest_component_ratio": float(counts.max() / n),
+        "sample_ids": [int(i) for i in sample],
+    }

vecscope/diagnostics/hubness.py

@@ -0,0 +1,33 @@
+"""Hubness: a few points appear in everyone's k-NN list (hubs), others in nobody's (anti-hubs).
+
+High hubness means the same chunks top every query regardless of relevance.
+Evidence: skewness of the k-occurrence distribution N_k, hub share, anti-hub ratio.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from vecscope._knn import exact_knn
+
+
+def hubness(x: np.ndarray, k: int = 10, knn: np.ndarray | None = None) -> dict:
+    n = x.shape[0]
+    if knn is None:
+        knn, _ = exact_knn(x, k)
+    k = knn.shape[1]
+    nk = np.bincount(knn.ravel(), minlength=n).astype(np.float64)
+    mean, std = nk.mean(), nk.std()
+    skew = float(((nk - mean) ** 3).mean() / (std**3)) if std > 0 else 0.0
+    top = np.sort(nk)[::-1]
+    top1pct = max(1, int(np.ceil(n * 0.01)))
+    hub_share = float(top[:top1pct].sum() / nk.sum())
+    antihub_ratio = float((nk == 0).mean())
+    return {
+        "k": int(k),
+        "skewness": skew,
+        "max_k_occurrence": int(nk.max()),
+        "expected_k_occurrence": float(k),
+        "hub_share_top1pct": hub_share,
+        "antihub_ratio": antihub_ratio,
+    }

vecscope/diagnostics/queries.py

@@ -0,0 +1,65 @@
+"""Query-side evidence: do the queries live in the same space as the corpus?
+
+- ood_queries: queries whose nearest corpus item is farther than almost every corpus item is
+  from its own nearest neighbor. Typical causes: asymmetric models used without the query
+  prefix, a different model for queries, or queries about things the corpus does not cover.
+- query_hubness: skewness of how often each corpus item appears in query top-k lists. High
+  values mean the same few items answer everything.
+- coverage (details): share of corpus items that any query reaches in its top-k.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from vecscope._knn import normalize
+
+
+def query_knn(corpus: np.ndarray, queries: np.ndarray, k: int, block: int = 2048):
+    c = normalize(corpus)
+    q = normalize(queries)
+    k = min(k, c.shape[0])
+    idx = np.empty((q.shape[0], k), dtype=np.int64)
+    dist = np.empty((q.shape[0], k), dtype=np.float32)
+    for s in range(0, q.shape[0], block):
+        e = min(s + block, q.shape[0])
+        d = 1.0 - q[s:e] @ c.T
+        part = np.argpartition(d, k - 1, axis=1)[:, :k]
+        pd = np.take_along_axis(d, part, axis=1)
+        order = np.argsort(pd, axis=1)
+        idx[s:e] = np.take_along_axis(part, order, axis=1)
+        dist[s:e] = np.take_along_axis(pd, order, axis=1)
+    return idx, dist
+
+
+def query_audit(
+    corpus: np.ndarray,
+    queries: np.ndarray,
+    k: int,
+    corpus_nn_dist: np.ndarray,
+    sample_ids: int = 10,
+) -> dict:
+    idx, dist = query_knn(corpus, queries, k)
+    n_corpus = corpus.shape[0]
+    corpus_nn = np.asarray(corpus_nn_dist, dtype=np.float64)
+    corpus_nn = corpus_nn[corpus_nn > 1e-4] if (corpus_nn > 1e-4).any() else corpus_nn
+    cutoff = float(np.quantile(corpus_nn, 0.99))
+    nearest = dist[:, 0].astype(np.float64)
+    ood = nearest > cutoff
+    worst = np.argsort(nearest)[::-1][:sample_ids]
+
+    nk = np.bincount(idx.ravel(), minlength=n_corpus).astype(np.float64)
+    std = nk.std()
+    skew = float(((nk - nk.mean()) ** 3).mean() / std**3) if std > 0 else 0.0
+    return {
+        "n_queries": int(queries.shape[0]),
+        "k": int(idx.shape[1]),
+        "ood_query_ratio": float(ood.mean()),
+        "ood_cutoff_distance": cutoff,
+        "median_query_nn_distance": float(np.median(nearest)),
+        "median_corpus_nn_distance": float(np.median(corpus_nn)),
+        "ood_sample_ids": [int(i) for i in worst if ood[i]],
+        "query_hubness_skewness": skew,
+        "max_query_k_occurrence": int(nk.max()),
+        "coverage": float((nk > 0).mean()),
+    }