gem-mapping-studio 0.2.2__py3-none-any.whl

forome/gem/umls/sweep.py

@@ -0,0 +1,576 @@
+#!/usr/bin/env python3
+"""Pre-registered UMLS mapping sweeps: protocol loader, runner, S2-style table.
+
+An "unmapped" verdict in the crosswalk must be *earned*: a stated, reproducible
+search protocol was executed, every candidate it surfaced was recorded, and each
+candidate was rejected under a named criterion. This module makes that a
+mechanical pipeline:
+
+1. The curator writes a protocol YAML **before** searching (pre-registration):
+   dimension, tokens, search passes (terms x match x scope), semantic types to
+   enumerate, and a note on what would confirm or refute the verdict. See
+   ``data/umls/sweeps/credibility.yaml`` for the shape.
+2. ``run(protocol, client)`` executes it through any client with the shared
+   ``search(term, search_type, sabs, page_size, semantic_types, partial)``
+   interface (``UTSClient`` live with disk cache, ``NullClient`` for dry runs,
+   or a local index later) and returns a results dict: the queries, the
+   deduplicated candidates (``found_by`` merged across queries), and counts.
+   Each candidate carries ``fails: null`` / ``why: null`` for the curator to
+   fill in using criteria A-D.
+3. ``render_tex(results)`` renders a ``longtable`` for the supplement.
+
+Results are written to ``data/umls/sweeps/<name>.results.yaml`` -- a separate
+file. The sweep **never** writes ``adjudications.yaml``; an acceptance is still
+recorded through the Mapping Studio.
+
+**Curation survives re-runs.** When the results file already exists, any
+``fails``/``why`` a curator filled in is carried over to the same CUI in the new
+run. A curated CUI that the new run no longer surfaces is kept under
+``stale_curation`` (never silently dropped), so a protocol change or a UMLS
+release change is visible.
+
+Usage:
+    gem-umls-sweep data/umls/sweeps/credibility.yaml
+    gem-umls-sweep data/umls/sweeps/credibility.yaml --tex build/credibility_sweep.tex
+    gem-umls-sweep PROTOCOL.yaml --provider null        # dry run, no key
+    gem-umls-sweep PROTOCOL.yaml --enrich --limit-per-query 50
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import yaml
+
+from forome.gem.umls._paths import DATA_DIR
+from forome.gem.umls.render_crosswalk_tex import tex
+
+SWEEPS_DIR = DATA_DIR / "sweeps"
+
+MATCH_TYPES = ("words", "exact", "normalizedWords", "normalizedString", "partial")
+SCOPES = ("all", "axis")
+CRITERIA = ("A", "B", "C", "D")
+REQUIRED_KEYS = ("name", "dimension", "tokens", "criteria", "date_registered",
+                 "passes")
+
+RESULTS_HEADER = """\
+# GENERATED by gem-umls-sweep from the pre-registered protocol named below.
+# Curator: for every candidate that is NOT accepted as a mapping, set
+#   fails: one of A|B|C|D (see protocol.criteria)   why: one line
+# Leave both null only for a candidate you accept (record the acceptance in
+# adjudications.yaml via the Mapping Studio; this file is never read by the
+# harness). Your fails/why entries are preserved when the sweep is re-run.
+"""
+
+
+class ProtocolError(ValueError):
+    """The protocol file is missing a required key or holds an invalid value."""
+
+
+# --------------------------------------------------------------------------
+# Protocol
+# --------------------------------------------------------------------------
+
+def load_protocol(path: Path | str) -> dict:
+    """Load and validate a sweep protocol. Raises ``ProtocolError``."""
+    path = Path(path)
+    doc = yaml.safe_load(path.read_text())
+    if not isinstance(doc, dict):
+        raise ProtocolError(f"{path}: protocol must be a mapping")
+    validate_protocol(doc)
+    doc["_path"] = str(path)
+    return doc
+
+
+def validate_protocol(p: dict) -> None:
+    missing = [k for k in REQUIRED_KEYS if k not in p]
+    if missing:
+        raise ProtocolError(f"protocol missing required keys: {', '.join(missing)}")
+    if not isinstance(p["tokens"], list) or not p["tokens"]:
+        raise ProtocolError("protocol 'tokens' must be a non-empty list")
+    crit = p["criteria"]
+    if not isinstance(crit, dict) or any(c not in crit for c in CRITERIA):
+        raise ProtocolError("protocol 'criteria' must define codes A, B, C and D")
+    passes = p["passes"]
+    if not isinstance(passes, dict) or not passes:
+        raise ProtocolError("protocol 'passes' must be a non-empty mapping "
+                            "(name -> pass)")
+    for name, body in passes.items():
+        if not isinstance(body, dict):
+            raise ProtocolError(f"pass '{name}' must be a mapping")
+        kind = pass_kind(body)
+        for key in ("match", "scopes"):
+            if key in body and not isinstance(body[key], list):
+                raise ProtocolError(f"pass '{name}': '{key}' must be a list")
+        if kind == "sty":
+            if not isinstance(body["tuis"], list) or not body["tuis"]:
+                raise ProtocolError(f"pass '{name}': 'tuis' must be a non-empty list")
+            mode = body.get("mode") or ("terms" if ("terms" in body or "terms_from" in body)
+                                        else "enumerate")
+            if mode not in ("terms", "enumerate"):
+                raise ProtocolError(f"pass '{name}': mode must be 'terms' or 'enumerate'")
+            if mode == "terms":
+                src = body.get("terms_from")
+                if src is not None and src not in passes:
+                    raise ProtocolError(f"pass '{name}': terms_from '{src}' is not a pass")
+                if src is None and not body.get("terms"):
+                    raise ProtocolError(f"pass '{name}': mode 'terms' needs 'terms' or 'terms_from'")
+                bad = [m for m in (body.get("match") or ["words"]) if m not in MATCH_TYPES]
+                if bad:
+                    raise ProtocolError(f"pass '{name}': unknown match type(s) {bad}")
+            continue
+        if kind is None:
+            raise ProtocolError(f"pass '{name}' needs 'terms', 'phrases' or 'tuis'")
+        queries = pass_queries(body)
+        if not queries:
+            raise ProtocolError(f"pass '{name}': no query strings")
+        match = body.get("match") or ["words"]
+        bad = [m for m in match if m not in MATCH_TYPES]
+        if bad:
+            raise ProtocolError(f"pass '{name}': unknown match type(s) {bad}; "
+                                f"allowed: {list(MATCH_TYPES)}")
+        scopes = body.get("scopes") or ["all"]
+        bad = [s for s in scopes if s not in SCOPES]
+        if bad:
+            raise ProtocolError(f"pass '{name}': unknown scope(s) {bad}; "
+                                f"allowed: {list(SCOPES)}")
+    axis = p.get("axis_tuis")
+    if axis is not None and (not isinstance(axis, list)
+                             or not all(isinstance(t, str) for t in axis)):
+        raise ProtocolError("protocol 'axis_tuis' must be a list of TUIs")
+
+
+def pass_kind(body: dict) -> str | None:
+    if "tuis" in body:
+        return "sty"
+    if "terms" in body or "phrases" in body:
+        return "search"
+    return None
+
+
+def pass_queries(body: dict) -> list[str]:
+    qs = list(body.get("terms") or []) + list(body.get("phrases") or [])
+    return [str(q) for q in qs if str(q).strip()]
+
+
+def axis_filter(protocol: dict) -> str | None:
+    """Comma-joined TUI list for scope=axis queries: each axis TUI plus its
+    Semantic Network subtree (when the reference is available)."""
+    tuis = protocol.get("axis_tuis") or []
+    if not tuis:
+        return None
+    try:
+        from forome.gem.umls import semantic_types as stylib
+        out: set[str] = set()
+        for t in tuis:
+            out |= stylib.subtree_tuis(t)
+    except Exception:  # noqa: BLE001 -- reference data unavailable
+        out = set(tuis)
+    return ",".join(sorted(out)) if out else None
+
+
+# --------------------------------------------------------------------------
+# Runner
+# --------------------------------------------------------------------------
+
+def provider_info(client, umls: str | None = None) -> dict:
+    kind = getattr(client, "kind", None) or type(client).__name__
+    kind = kind.lower().removesuffix("client") or kind.lower()
+    if umls is None:
+        rel = getattr(client, "release", None)
+        if callable(rel):
+            try:
+                row = rel()
+                umls = (row or {}).get("version")
+            except Exception:  # noqa: BLE001 -- no DB / no release row yet
+                umls = None
+        umls = (umls or getattr(client, "umls_release", None)
+                or getattr(client, "version", None) or "unknown")
+    return {"kind": kind, "umls": str(umls)}
+
+
+def _search(client, q: str, match: str, stys: str | None, limit: int | None):
+    if match == "partial":
+        hits = client.search(q, search_type="words", semantic_types=stys,
+                             partial=True)
+    else:
+        hits = client.search(q, search_type=match, semantic_types=stys)
+    hits = list(hits or [])
+    if limit is not None:
+        hits = hits[:limit]
+    return hits
+
+
+def run(protocol: dict, client, enrich: bool = False,
+        limit_per_query: int | None = None, umls: str | None = None) -> dict:
+    """Execute ``protocol`` through ``client``; return the results dict.
+
+    Candidates are deduplicated by CUI in discovery order, ``found_by`` merged.
+    The ``sty`` pass runs only when the client offers ``concepts_by_tui(tui)``
+    (a local index); on a REST provider it is recorded as skipped.
+    """
+    stys_axis = axis_filter(protocol)
+    passes_out: list[dict] = []
+    cands: dict[str, dict] = {}
+    n_queries = 0
+    by_pass: dict[str, int] = {}
+
+    def add(hit: dict, pname: str, q: str, match: str) -> None:
+        cui = hit.get("cui")
+        if not cui:
+            return
+        c = cands.get(cui)
+        if c is None:
+            c = {"cui": cui, "name": hit.get("name"),
+                 "root_source": hit.get("root_source"),
+                 "semantic_types": list(hit.get("semantic_types") or []),
+                 "found_by": [], "sabs": [], "fails": None, "why": None}
+            cands[cui] = c
+        seen_passes = {f["pass"] for f in c["found_by"]}
+        fb = {"pass": pname, "q": q, "match": match}
+        if fb not in c["found_by"]:
+            c["found_by"].append(fb)
+        if pname not in seen_passes:  # distinct candidates per pass
+            by_pass[pname] = by_pass.get(pname, 0) + 1
+
+    for pname, body in protocol["passes"].items():
+        kind = pass_kind(body)
+        rec = {"name": pname, "status": "executed", "queries": []}
+        if kind == "sty":
+            mode = body.get("mode") or ("terms" if ("terms" in body or "terms_from" in body)
+                                        else "enumerate")
+            rec["mode"] = mode
+            if mode == "terms":
+                # search the terms WITHIN each semantic type -- works on any
+                # provider (UTS: semanticTypes filter), never enumerates a type
+                src = body.get("terms_from")
+                terms = (pass_queries(protocol["passes"][src]) if src
+                         else list(body.get("terms") or []))
+                for tui in body["tuis"]:
+                    for q in terms:
+                        for match in (body.get("match") or ["words"]):
+                            hits = _search(client, q, match, tui, limit_per_query)
+                            n_queries += 1
+                            rec["queries"].append({"q": q, "match": match, "scope": tui,
+                                                   "hits": len(hits)})
+                            for h in hits:
+                                add(h, pname, q, match)
+                passes_out.append(rec)
+                continue
+            fn = getattr(client, "concepts_by_tui", None)
+            if not callable(fn):
+                rec["status"] = "skipped"
+                rec["reason"] = (body.get("note")
+                                 or "client has no concepts_by_tui (local index)")
+                passes_out.append(rec)
+                continue
+            cap = int(body.get("limit") or 5000)   # a whole type is never dumped uncapped
+            if limit_per_query is not None:
+                cap = min(cap, limit_per_query)
+            for tui in body["tuis"]:
+                try:
+                    hits = list(fn(tui, limit=cap) or [])
+                except TypeError:                       # client without a limit kwarg
+                    hits = list(fn(tui) or [])[:cap]
+                n_queries += 1
+                qrec = {"q": tui, "match": "sty", "scope": "all", "hits": len(hits)}
+                if len(hits) >= cap:
+                    qrec["truncated"] = cap
+                rec["queries"].append(qrec)
+                for h in hits:
+                    add(h, pname, tui, "sty")
+            passes_out.append(rec)
+            continue
+
+        match_types = body.get("match") or ["words"]
+        scopes = body.get("scopes") or ["all"]
+        for q in pass_queries(body):
+            for match in match_types:
+                for scope in scopes:
+                    qrec = {"q": q, "match": match, "scope": scope, "hits": 0}
+                    if scope == "axis" and not stys_axis:
+                        qrec["skipped"] = "protocol has no axis_tuis"
+                        rec["queries"].append(qrec)
+                        continue
+                    stys = stys_axis if scope == "axis" else None
+                    hits = _search(client, q, match, stys, limit_per_query)
+                    n_queries += 1
+                    qrec["hits"] = len(hits)
+                    rec["queries"].append(qrec)
+                    for h in hits:
+                        add(h, pname, q, match)
+        passes_out.append(rec)
+
+    candidates = list(cands.values())
+    if enrich:
+        _enrich(client, candidates, protocol.get("sabs_of_interest"))
+
+    return {
+        "protocol": {
+            "name": protocol["name"],
+            "date_registered": str(protocol["date_registered"]),
+            "dimension": protocol["dimension"],
+            "tokens": list(protocol["tokens"]),
+            "path": protocol.get("_path"),
+            "criteria": dict(protocol["criteria"]),
+            "sabs_of_interest": list(protocol.get("sabs_of_interest") or []),
+        },
+        "provider": provider_info(client, umls),
+        "passes": passes_out,
+        "candidates": candidates,
+        "summary": {"n_queries": n_queries, "n_candidates": len(candidates),
+                    "by_pass": by_pass},
+    }
+
+
+def _enrich(client, candidates: list[dict], sabs_of_interest=None) -> None:
+    """Fill ``sabs`` with the English source vocabularies holding an atom. When
+    the protocol names ``sabs_of_interest``, ``sabs`` keeps only those (in
+    protocol order) and ``sabs_other`` counts the rest, so the table shows what
+    the reader was promised rather than every mirror vocabulary."""
+    atoms = getattr(client, "atoms", None)
+    if not callable(atoms):
+        return
+    interest = list(sabs_of_interest or [])
+    for c in candidates:
+        try:
+            rows = atoms(c["cui"]) or []
+        except Exception:  # noqa: BLE001 -- enrichment is best-effort
+            rows = []
+        sabs = {a.get("sab") for a in rows
+                if a.get("sab") and (a.get("language") or "ENG") == "ENG"}
+        if interest:
+            c["sabs"] = [s for s in interest if s in sabs]
+            c["sabs_other"] = len(sabs - set(interest))
+        else:
+            c["sabs"] = sorted(sabs)
+
+
+# --------------------------------------------------------------------------
+# Curation merge
+# --------------------------------------------------------------------------
+
+def _curated(c: dict) -> bool:
+    return c.get("fails") is not None or c.get("why") is not None
+
+
+def merge_curation(new: dict, previous: dict | None) -> dict:
+    """Carry curator-filled ``fails``/``why`` from ``previous`` results into
+    ``new`` by CUI. Curated CUIs no longer surfaced go to ``stale_curation``.
+    """
+    if not previous:
+        return new
+    prior = {c["cui"]: c for c in (previous.get("candidates") or [])
+             if c.get("cui") and _curated(c)}
+    prior.update({c["cui"]: c for c in (previous.get("stale_curation") or [])
+                  if c.get("cui")})
+    carried = 0
+    for c in new["candidates"]:
+        p = prior.pop(c["cui"], None)
+        if p is not None:
+            c["fails"] = p.get("fails")
+            c["why"] = p.get("why")
+            carried += 1
+    stale = [{"cui": p["cui"], "name": p.get("name"), "fails": p.get("fails"),
+              "why": p.get("why")} for p in prior.values()]
+    if stale:
+        new["stale_curation"] = stale
+    new["summary"]["n_curated"] = sum(1 for c in new["candidates"] if _curated(c))
+    new["summary"]["n_carried_over"] = carried
+    new["summary"]["n_stale_curation"] = len(stale)
+    return new
+
+
+def load_results(path: Path | str) -> dict | None:
+    path = Path(path)
+    if not path.is_file():
+        return None
+    doc = yaml.safe_load(path.read_text())
+    return doc if isinstance(doc, dict) else None
+
+
+def dump_results(results: dict) -> str:
+    body = yaml.safe_dump(results, sort_keys=False, allow_unicode=True,
+                          width=100, default_flow_style=False)
+    return RESULTS_HEADER + body
+
+
+# --------------------------------------------------------------------------
+# LaTeX
+# --------------------------------------------------------------------------
+
+def _first_pass(c: dict) -> str:
+    fb = c.get("found_by") or []
+    return fb[0]["pass"] if fb else ""
+
+
+def render_tex(results: dict) -> str:
+    """Render the sweep as an S2-style ``longtable``. Candidates with
+    ``fails: null`` render as not yet adjudicated."""
+    p = results["protocol"]
+    prov = results.get("provider") or {}
+    s = results.get("summary") or {}
+    order = {r["name"]: i for i, r in enumerate(results.get("passes") or [])}
+    rows = sorted(results.get("candidates") or [],
+                  key=lambda c: (order.get(_first_pass(c), len(order)),
+                                 (c.get("name") or "").lower(), c.get("cui") or ""))
+    n_adj = sum(1 for c in rows if c.get("fails") is not None)
+
+    out = [
+        r"% =====================================================================",
+        rf"%  GENERATED by gem-umls-sweep from protocol '{p['name']}' "
+        rf"(registered {p.get('date_registered')}) -- do not edit by hand.",
+        rf"%  Dimension: {p.get('dimension')}; tokens: "
+        rf"{', '.join(p.get('tokens') or [])}",
+        rf"%  Provider: {prov.get('kind')} / UMLS {prov.get('umls')}; "
+        rf"{s.get('n_queries', 0)} queries, {len(rows)} candidates, "
+        rf"{n_adj} adjudicated.",
+        r"%  Rejection criteria:",
+    ]
+    for code in CRITERIA:
+        meaning = (p.get("criteria") or {}).get(code, "")
+        out.append(f"%    {code}: {meaning}")
+    out += [
+        r"%  Requires: \usepackage{longtable} and \usepackage{booktabs}.",
+        r"% =====================================================================",
+        "",
+    ]
+    exec_passes = [r["name"] for r in results.get("passes") or []
+                   if r.get("status") == "executed"]
+    skip_passes = [r["name"] for r in results.get("passes") or []
+                   if r.get("status") != "executed"]
+    caption = (rf"Mapping sweep for dimension \texttt{{{tex(p.get('dimension'))}}} "
+               rf"(protocol \texttt{{{tex(p['name'])}}}, registered "
+               rf"{tex(p.get('date_registered'))}; provider {tex(prov.get('kind'))}, "
+               rf"UMLS {tex(prov.get('umls'))}). {s.get('n_queries', 0)} queries "
+               rf"over passes {tex(', '.join(exec_passes)) or '---'}"
+               + (rf" (skipped: {tex(', '.join(skip_passes))})" if skip_passes else "")
+               + rf" surfaced {len(rows)} distinct concepts; {n_adj} adjudicated. "
+               r"Fails: rejection criterion (A denotation, B granularity, "
+               r"C set membership, D domain sense); ``---'' = not yet adjudicated.")
+    head = (r"Candidate & STY & Source & Found by & Fails & Why \\")
+    out += [
+        r"{\footnotesize",
+        r"\begin{longtable}{@{}p{4.0cm} p{2.3cm} p{2.6cm} l c p{4.4cm}@{}}",
+        rf"\caption{{{caption}}}\\",
+        r"\toprule", head, r"\midrule", r"\endfirsthead",
+        r"\toprule", head, r"\midrule", r"\endhead",
+    ]
+    cur = None
+    for c in rows:
+        pn = _first_pass(c)
+        if pn != cur:
+            cur = pn
+            out.append(rf"\midrule \multicolumn{{6}}{{@{{}}l}}"
+                       rf"{{\textbf{{pass: {tex(pn) or '---'}}}}} \\")
+        name = rf"{tex(c.get('name'))} \emph{{({tex(c.get('cui'))})}}"
+        sty = "; ".join(tex(x) for x in (c.get("semantic_types") or []))
+        src = tex(c.get("root_source"))
+        if c.get("sabs"):
+            src += rf" \emph{{({tex(', '.join(c['sabs']))})}}"
+        if c.get("sabs_other"):
+            src += rf" +{int(c['sabs_other'])}"
+        found = ", ".join(sorted({f["pass"] for f in c.get("found_by") or []}))
+        if c.get("fails") is None:
+            fails, why = "---", r"\emph{not adjudicated}"
+        else:
+            fails = tex(c.get("fails"))
+            why = tex(c.get("why")) if c.get("why") else "---"
+        out.append(rf"{name} & {sty} & {src} & {tex(found)} & {fails} & {why} \\")
+    stale = results.get("stale_curation") or []
+    if stale:
+        out.append(r"\midrule \multicolumn{6}{@{}l}{\textbf{curated in a previous "
+                   r"run, no longer surfaced}} \\")
+        for c in stale:
+            out.append(rf"{tex(c.get('name'))} \emph{{({tex(c.get('cui'))})}} & & & "
+                       rf"& {tex(c.get('fails')) or '---'} & {tex(c.get('why')) or '---'} \\")
+    out += [r"\bottomrule", r"\end{longtable}", r"}", ""]
+    return "\n".join(out) + "\n"
+
+
+# --------------------------------------------------------------------------
+# CLI
+# --------------------------------------------------------------------------
+
+def _build_client(provider: str, dsn: str | None = None):
+    if provider == "pg":
+        # the local PostgreSQL index (forome.gem.umls.local_umls); the exact
+        # UMLS release comes from its umls_release row
+        from forome.gem.umls.local_umls import PgUMLSClient
+        return PgUMLSClient(dsn)
+    if provider == "null":
+        from forome.gem.umls.uts_client import NullClient
+        return NullClient()
+    if provider == "uts":
+        # Lazy: adjudicate_ui.api_key() reads UMLS_API_KEY or the repo .envrc.
+        # The key is passed to the client only; it is never printed or logged.
+        from forome.gem.umls import adjudicate_ui as UI
+        from forome.gem.umls import build_umls_crosswalk as H
+        from forome.gem.umls.uts_client import UTSClient
+        key = UI.api_key()
+        if not key:
+            raise SystemExit("gem-umls-sweep: no UMLS API key found (set "
+                             "UMLS_API_KEY or add it to .envrc); use "
+                             "--provider null for a dry run.")
+        return UTSClient(key, cache_dir=H.CACHE_DIR)
+    raise SystemExit(f"gem-umls-sweep: unknown provider '{provider}'")
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="gem-umls-sweep", description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("protocol", help="pre-registered protocol YAML")
+    ap.add_argument("--out", help="results YAML (default: "
+                    "data/umls/sweeps/<name>.results.yaml)")
+    ap.add_argument("--tex", help="also write an S2-style LaTeX longtable here")
+    ap.add_argument("--dsn", default=None,
+                    help="PostgreSQL DSN for --provider pg (default: $GEM_UMLS_DSN, "
+                         "else postgresql:///umls)")
+    ap.add_argument("--provider", choices=["uts", "pg", "null"], default="uts",
+                    help="uts = live UTS REST with disk cache (default); "
+                         "null = no results, for a dry run")
+    ap.add_argument("--enrich", action="store_true",
+                    help="fetch each candidate's atoms to list its English SABs")
+    ap.add_argument("--limit-per-query", type=int, default=None, metavar="N",
+                    help="keep at most N hits per query")
+    ap.add_argument("--umls-release", default=None, metavar="LABEL",
+                    help="label for the UMLS release queried (e.g. 2025AA); "
+                         "default: the client's version string")
+    args = ap.parse_args(argv)
+
+    try:
+        protocol = load_protocol(args.protocol)
+    except ProtocolError as e:
+        print(f"gem-umls-sweep: invalid protocol: {e}", file=sys.stderr)
+        return 2
+
+    out_path = Path(args.out) if args.out else (
+        SWEEPS_DIR / f"{protocol['name']}.results.yaml")
+    client = _build_client(args.provider, args.dsn)
+    results = run(protocol, client, enrich=args.enrich,
+                  limit_per_query=args.limit_per_query, umls=args.umls_release)
+    previous = load_results(out_path)
+    results = merge_curation(results, previous)
+
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(dump_results(results))
+    s = results["summary"]
+    print(f"Wrote {out_path}: {s['n_queries']} queries, {s['n_candidates']} "
+          f"candidates" + (f", {s['n_carried_over']} curated entries carried over"
+                           if previous else "")
+          + (f", {s['n_stale_curation']} stale" if s.get("n_stale_curation") else ""))
+    for p in results["passes"]:
+        if p["status"] != "executed":
+            print(f"  pass '{p['name']}' skipped: {p.get('reason')}")
+    if args.tex:
+        tex_path = Path(args.tex)
+        tex_path.parent.mkdir(parents=True, exist_ok=True)
+        tex_path.write_text(render_tex(results))
+        print(f"Wrote {tex_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())