ccrt 0.1.0__py3-none-any.whl

ccrt/__init__.py

@@ -0,0 +1,37 @@
+"""Public CCRT API. Source accounts stay separate from proposed event links."""
+
+from ccrt._version import __version__
+from ccrt.client import UCDPClient, UCDPError
+from ccrt.loaders import ValidationError, load_acled_csv, load_csv, load_ucdp_csv
+from ccrt.merge import Candidate, MatchConfig, Reconciliation, reconcile
+from ccrt.report import ReviewReport, summarize_review
+from ccrt.review import Decision, Review
+from ccrt.schema import Dataset, SourceRecord, ValidationIssue
+from ccrt.storage import load_dataset, load_review, load_run, save_dataset, save_review, save_run
+
+__all__ = [
+    "__version__",
+    "SourceRecord",
+    "Dataset",
+    "ValidationIssue",
+    "ValidationError",
+    "UCDPClient",
+    "UCDPError",
+    "load_ucdp_csv",
+    "load_acled_csv",
+    "load_csv",
+    "MatchConfig",
+    "Candidate",
+    "Reconciliation",
+    "reconcile",
+    "Decision",
+    "Review",
+    "ReviewReport",
+    "summarize_review",
+    "load_dataset",
+    "save_dataset",
+    "load_run",
+    "save_run",
+    "load_review",
+    "save_review",
+]

ccrt/__main__.py

@@ -0,0 +1,3 @@
+from ccrt.cli import main
+
+raise SystemExit(main())

ccrt/_version.py

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

ccrt/cli.py

@@ -0,0 +1,205 @@
+"""Small CLI using the same library APIs as notebooks."""
+
+import argparse
+import sys
+from pathlib import Path
+
+from ccrt._version import __version__
+from ccrt.client import UCDPClient, UCDPError
+from ccrt.config import ucdp_api_key
+from ccrt.export import read_review_csv, write_csv, write_parquet, write_records_csv
+from ccrt.interactive import review_interactive
+from ccrt.loaders import load_acled_csv, load_csv, load_ucdp_csv
+from ccrt.merge import MatchConfig, reconcile
+from ccrt.report import format_review_report, summarize_review
+from ccrt.review import Review
+from ccrt.schema import canonical_json
+from ccrt.storage import (
+    atomic_write,
+    load_dataset,
+    load_review,
+    load_run,
+    save_dataset,
+    save_review,
+    save_run,
+)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="ccrt", description="Reviewable conflict record reconciliation")
+    parser.add_argument("--version", action="version", version=__version__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    imp = commands.add_parser("import", help="Normalize a source CSV into a CCRT JSON bundle")
+    imp.add_argument("source", choices=["ucdp", "acled", "generic"])
+    imp.add_argument("input")
+    imp.add_argument("output")
+    imp.add_argument("--version", required=True, help="GED release or export snapshot label")
+    imp.add_argument("--source-name", help="Source label for generic CSV")
+    imp.add_argument(
+        "--collect-errors", action="store_true", help="Retain invalid rows in the validation report"
+    )
+    fetch = commands.add_parser("fetch-ucdp", help="Fetch GED using UCDP_API_KEY or a local .env")
+    fetch.add_argument("output")
+    fetch.add_argument("--version", required=True)
+    fetch.add_argument("--country", type=int, action="append", help="Gleditsch-Ward country ID; repeatable")
+    fetch.add_argument("--start-date")
+    fetch.add_argument("--end-date")
+    fetch.add_argument("--max-pages", type=int, default=5000)
+    fetch.add_argument(
+        "--env-file", help="Read UCDP_API_KEY from this file when it is not set in the environment"
+    )
+    match = commands.add_parser("match", help="Create all candidate links and a review table")
+    match.add_argument("left")
+    match.add_argument("right")
+    match.add_argument("output_dir")
+    match.add_argument("--max-days", type=int, default=3)
+    match.add_argument("--max-km", type=float, default=25)
+    match.add_argument("--include-coarse-locations", action="store_true")
+    match.add_argument("--country-alias", action="append", default=[], metavar="FROM=TO")
+    review = commands.add_parser("review", help="Import edited review CSV or record one decision")
+    review.add_argument("run")
+    review.add_argument("output")
+    review.add_argument("--existing", help="Continue a saved review JSON")
+    method = review.add_mutually_exclusive_group(required=True)
+    method.add_argument("--csv", help="Edited review CSV")
+    method.add_argument("--candidate")
+    review.add_argument("--status", choices=["accepted", "rejected", "unresolved"])
+    review.add_argument("--reviewer", default="")
+    review.add_argument("--note", default="")
+    interactive = commands.add_parser(
+        "review-interactive", help="Review source accounts in the terminal and save each decision"
+    )
+    interactive.add_argument("run", help="Match run.json")
+    interactive.add_argument("output", help="Review JSON; created or resumed in place")
+    interactive.add_argument("--from-existing", help="Seed a new review JSON from an earlier review")
+    interactive.add_argument("--reviewer", required=True, help="Name recorded with decisions")
+    interactive.add_argument("--left-id", help="Inspect one left-side source record and its candidates")
+    interactive.add_argument("--all", action="store_true", help="Include already decided groups")
+    tui = commands.add_parser("review-tui", help="Experimental full-screen terminal review dashboard")
+    tui.add_argument("run", help="Match run.json")
+    tui.add_argument("output", help="Review JSON; created or resumed in place")
+    tui.add_argument("--from-existing", help="Seed a new review JSON from an earlier review")
+    tui.add_argument("--reviewer", required=True, help="Name recorded with decisions")
+    tui.add_argument("--left-id", help="Start at a left-side source record")
+    report = commands.add_parser("report", help="Summarize review coverage and accepted-link diagnostics")
+    report.add_argument("run", help="Match run.json")
+    report.add_argument("--review", help="Saved review JSON; omitted means all unresolved")
+    report.add_argument("--output", help="Also save a new JSON report")
+    export = commands.add_parser("export", help="Export normalized data or a reviewed run")
+    export.add_argument("input")
+    export.add_argument("output")
+    export.add_argument("--format", choices=["csv", "parquet", "review-csv"], required=True)
+    export.add_argument("--review", help="Saved review JSON for review-csv")
+    args = parser.parse_args(argv)
+    try:
+        if args.command in {"import", "fetch-ucdp", "review", "export"} and Path(args.output).exists():
+            raise FileExistsError(f"output exists: {args.output}")
+        if args.command == "import":
+            options = {"version": args.version, "errors": "collect" if args.collect_errors else "raise"}
+            if args.source == "generic":
+                if not args.source_name:
+                    raise ValueError("generic import requires --source-name")
+                dataset = load_csv(args.input, args.source_name, **options)
+            else:
+                dataset = {"ucdp": load_ucdp_csv, "acled": load_acled_csv}[args.source](args.input, **options)
+            save_dataset(dataset, args.output)
+            print(f"Imported {len(dataset)} records; {len(dataset.issues)} validation issues")
+        elif args.command == "fetch-ucdp":
+            with UCDPClient(api_key=ucdp_api_key(args.env_file)) as client:
+                dataset = client.fetch(
+                    version=args.version,
+                    countries=args.country,
+                    start_date=args.start_date,
+                    end_date=args.end_date,
+                    max_pages=args.max_pages,
+                )
+            save_dataset(dataset, args.output)
+            print(f"Fetched {len(dataset)} records; {len(dataset.issues)} validation issues")
+        elif args.command == "match":
+            aliases = {}
+            for value in args.country_alias:
+                if "=" not in value:
+                    raise ValueError("country aliases use FROM=TO")
+                key, target = value.split("=", 1)
+                aliases[key] = target
+            result = reconcile(
+                load_dataset(args.left),
+                load_dataset(args.right),
+                config=MatchConfig(args.max_days, args.max_km, args.include_coarse_locations, aliases),
+            )
+            directory = Path(args.output_dir)
+            directory.mkdir(parents=True, exist_ok=False)
+            save_run(result, directory / "run.json")
+            save_review(Review.create(result), result, directory / "review.json")
+            write_csv(result, directory / "candidates.csv")
+            print(f"{len(result.candidates)} candidate links; {len(result.unlinked)} unlinked records")
+        elif args.command == "review":
+            result = load_run(args.run)
+            if args.csv:
+                if args.existing or args.status or args.reviewer or args.note:
+                    raise ValueError("--csv cannot be combined with single-decision options")
+                review = read_review_csv(args.csv, result)
+            else:
+                if not args.status:
+                    raise ValueError("--candidate requires --status")
+                review = load_review(args.existing, result) if args.existing else Review.create(result)
+                review = review.decide(args.candidate, args.status, reviewer=args.reviewer, note=args.note)
+            save_review(review, result, args.output)
+            print(f"Saved {len(review.decisions)} review decisions")
+        elif args.command in {"review-interactive", "review-tui"}:
+            if args.command == "review-tui" and (not sys.stdin.isatty() or not sys.stdout.isatty()):
+                raise ValueError("review-tui needs an interactive terminal")
+            result = load_run(args.run)
+            output = Path(args.output)
+            if output.exists():
+                if args.from_existing:
+                    raise ValueError("output already exists; omit --from-existing to resume it")
+                current = load_review(output, result)
+            else:
+                current = (
+                    load_review(args.from_existing, result) if args.from_existing else Review.create(result)
+                )
+                save_review(current, result, output)
+
+            def save(updated):
+                save_review(updated, result, output, overwrite=True)
+
+            if args.command == "review-tui":
+                from ccrt.tui import run_tui
+
+                run_tui(result, current, reviewer=args.reviewer, left_id=args.left_id, save=save)
+            else:
+                review_interactive(
+                    result,
+                    current,
+                    reviewer=args.reviewer,
+                    left_id=args.left_id,
+                    show_all=args.all,
+                    save=save,
+                )
+        elif args.command == "report":
+            result = load_run(args.run)
+            review = load_review(args.review, result) if args.review else None
+            summary = summarize_review(result, review)
+            if args.output:
+                atomic_write(args.output, canonical_json(summary.to_dict()) + "\n")
+            print(format_review_report(summary))
+        else:
+            if args.format == "review-csv":
+                result = load_run(args.input)
+                review = load_review(args.review, result) if args.review else None
+                write_csv(result, args.output, review=review)
+            else:
+                if args.review:
+                    raise ValueError("--review only applies to --format review-csv")
+                dataset = load_dataset(args.input)
+                writer = write_parquet if args.format == "parquet" else write_records_csv
+                writer(dataset, args.output)
+            print(f"Wrote {args.output}")
+    except (OSError, ValueError, UCDPError, ImportError) as exc:
+        parser.exit(2, f"ccrt: {exc}\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ccrt/client.py

@@ -0,0 +1,166 @@
+"""Bounded, token-authenticated UCDP GED client. No network access on import."""
+
+from __future__ import annotations
+
+import math
+import os
+import time
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+
+import httpx
+
+from ccrt.loaders.base import parse_date
+from ccrt.loaders.ucdp import check_version, from_api_records
+
+
+class UCDPError(RuntimeError):
+    """A sanitized error: response bodies, headers and tokens are never included."""
+
+
+class UCDPClient:
+    def __init__(self, api_key=None, *, timeout=30.0, retries=3, transport=None):
+        self._api_key = api_key if api_key is not None else os.environ.get("UCDP_API_KEY", "")
+        if not self._api_key or not self._api_key.strip():
+            raise UCDPError("Set UCDP_API_KEY or pass api_key to UCDPClient")
+        if not math.isfinite(timeout) or timeout <= 0 or type(retries) is not int or not 0 <= retries <= 5:
+            raise ValueError("timeout must be finite and positive; retries must be an integer from 0 to 5")
+        self._retries = retries
+        self._client = httpx.Client(timeout=timeout, transport=transport, follow_redirects=False)
+
+    def close(self):
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def _page(self, version, params):
+        for attempt in range(self._retries + 1):
+            delay = min(2**attempt, 30)
+            try:
+                response = self._client.get(
+                    f"https://ucdpapi.pcr.uu.se/api/gedevents/{version}",
+                    params=params,
+                    headers={"x-ucdp-access-token": self._api_key},
+                )
+            except httpx.TransportError:
+                if attempt == self._retries:
+                    raise UCDPError("UCDP connection failed after bounded retries") from None
+            else:
+                status = response.status_code
+                if status in {401, 403}:
+                    raise UCDPError("UCDP rejected the access token (authentication/authorization)")
+                if status == 200:
+                    try:
+                        payload = response.json()
+                    except ValueError:
+                        raise UCDPError("UCDP returned invalid JSON") from None
+                    if not isinstance(payload, dict):
+                        raise UCDPError("UCDP returned an invalid response object")
+                    return payload
+                if status not in {429, 500, 502, 503, 504}:
+                    raise UCDPError(f"UCDP request failed (HTTP {status})")
+                if attempt == self._retries:
+                    raise UCDPError(f"UCDP request exhausted retries (HTTP {status})")
+                retry_after = response.headers.get("Retry-After")
+                if retry_after:
+                    try:
+                        delay = max(0, float(retry_after))
+                    except ValueError:
+                        try:
+                            when = parsedate_to_datetime(retry_after)
+                            delay = max(0, (when - datetime.now(timezone.utc)).total_seconds())
+                        except (TypeError, ValueError, OverflowError):
+                            delay = min(2**attempt, 30)
+                    if not math.isfinite(delay) or delay > 30:
+                        raise UCDPError("UCDP requested a longer retry delay; try again later")
+            time.sleep(delay)
+        raise AssertionError("unreachable")
+
+    def fetch(
+        self,
+        *,
+        version,
+        countries=None,
+        start_date=None,
+        end_date=None,
+        types_of_violence=None,
+        page_size=1000,
+        max_pages=5000,
+    ):
+        """Fetch a complete bounded query. Date filters apply to UCDP date_end.
+
+        Country values are UCDP/Gleditsch-Ward numeric IDs, not ISO codes.
+        A partial response is never returned as a complete Dataset.
+        """
+        check_version(version)
+        if type(page_size) is not int or not 1 <= page_size <= 1000:
+            raise ValueError("page_size must be an integer from 1 to 1000")
+        if type(max_pages) is not int or not 1 <= max_pages <= 5000:
+            raise ValueError("max_pages must be an integer from 1 to 5000")
+        params = {"pagesize": page_size}
+        for name, values in (("Country", countries), ("TypeOfViolence", types_of_violence)):
+            if values is not None:
+                values = list(values)
+                if not values or any(type(v) is not int or v < 1 for v in values):
+                    raise ValueError(f"{name} must contain positive integer IDs")
+                if name == "TypeOfViolence" and any(v not in {1, 2, 3} for v in values):
+                    raise ValueError("TypeOfViolence must contain 1, 2, or 3")
+                params[name] = ",".join(str(v) for v in sorted(set(values)))
+        dates = []
+        for name, value in (("StartDate", start_date), ("EndDate", end_date)):
+            parsed = parse_date(value) if value is not None else None
+            dates.append(parsed)
+            if parsed:
+                params[name] = parsed.isoformat()
+        if all(dates) and dates[0] > dates[1]:
+            raise ValueError("start_date exceeds end_date")
+        rows, expected, seen_ids = [], None, set()
+        # The live GED endpoint indexes pages from zero. Starting at one silently
+        # skips the first page, even though its documentation examples use page=1.
+        page = 0
+        while True:
+            payload = self._page(version, {**params, "page": page})
+            total, pages, results = (
+                payload.get("TotalCount"),
+                payload.get("TotalPages"),
+                payload.get("Result"),
+            )
+            if (
+                type(total) is not int
+                or total < 0
+                or type(pages) is not int
+                or pages < 0
+                or not isinstance(results, list)
+                or any(not isinstance(r, dict) for r in results)
+            ):
+                raise UCDPError("UCDP response has invalid pagination or records")
+            if (total > 0 and pages == 0) or (total == 0 and pages > 1):
+                raise UCDPError("UCDP response has inconsistent pagination")
+            if expected is None:
+                expected = (total, pages)
+                if pages > max_pages:
+                    raise UCDPError("Query exceeds max_pages; narrow the query or increase the bound")
+            elif expected != (total, pages):
+                raise UCDPError("UCDP result count changed during pagination; retry the query")
+            if page < pages and not results:
+                raise UCDPError("UCDP returned an empty intermediate page")
+            for row in results:
+                identifier = str(row.get("id", ""))
+                if identifier in seen_ids:
+                    raise UCDPError("UCDP repeated a record during pagination; retry the query")
+                seen_ids.add(identifier)
+            rows.extend(results)
+            if page + 1 >= pages:
+                break
+            page += 1
+        if len(rows) != expected[0]:
+            raise UCDPError("UCDP result count does not match retrieved records")
+        return from_api_records(
+            rows,
+            version=version,
+            metadata={"query": params, "retrieved_at": datetime.now(timezone.utc).isoformat()},
+        )

ccrt/config.py

@@ -0,0 +1,23 @@
+"""Credential lookup for the CLI's UCDP fetch command."""
+
+import os
+from pathlib import Path
+
+from dotenv import dotenv_values
+
+
+def ucdp_api_key(env_file: str | Path | None = None) -> str | None:
+    """Use the process environment first, then a local .env file.
+
+    Reads only UCDP_API_KEY; it does not import the rest of the file into the
+    process environment or expand variables inside the token.
+    """
+    key = os.environ.get("UCDP_API_KEY", "").strip()
+    if key:
+        return key
+    path = Path(env_file) if env_file is not None else Path.cwd() / ".env"
+    if not path.is_file():
+        if env_file is not None:
+            raise FileNotFoundError(f"environment file not found: {path}")
+        return None
+    return (dotenv_values(path, interpolate=False).get("UCDP_API_KEY") or "").strip() or None

ccrt/evaluation.py

@@ -0,0 +1,30 @@
+"""Candidate retrieval metrics for an EXHAUSTIVELY labeled, bounded pair universe."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Evaluation:
+    true_positives: int
+    false_positives: int
+    false_negatives: int
+    precision: float | None
+    recall: float | None
+
+
+def evaluate_candidates(result, true_pairs):
+    """true_pairs contains all true (left source ID, right source ID) links in these inputs.
+
+    Missing positive labels are treated as negatives, so partially reviewed samples
+    must not be passed to this function. This evaluates retrieval, not casualty truth.
+    """
+    truth = set(true_pairs)
+    left_ids = {r.source_id for r in result.left}
+    right_ids = {r.source_id for r in result.right}
+    if any(a not in left_ids or b not in right_ids for a, b in truth):
+        raise ValueError("truth contains source IDs outside the evaluation datasets")
+    proposed = {(c.left.source_id, c.right.source_id) for c in result.candidates}
+    tp = len(proposed & truth)
+    fp = len(proposed - truth)
+    fn = len(truth - proposed)
+    return Evaluation(tp, fp, fn, tp / (tp + fp) if tp + fp else None, tp / (tp + fn) if tp + fn else None)

ccrt/export.py

@@ -0,0 +1,152 @@
+"""Research tables with original claims and explicit review state."""
+
+import csv
+import io
+import json
+from dataclasses import asdict
+from pathlib import Path
+
+from ccrt.review import Review
+from ccrt.schema import SourceRecord, canonical_json
+from ccrt.storage import atomic_write, dataset_dict, dataset_from_dict
+
+
+def write_records_csv(dataset, path, *, overwrite=False):
+    """Flat normalized table; JSON bundle is the lossless interchange format."""
+    stream = io.StringIO(newline="")
+    writer = csv.DictWriter(stream, fieldnames=list(SourceRecord.__dataclass_fields__))
+    writer.writeheader()
+    writer.writerows(r.to_dict() for r in dataset)
+    atomic_write(path, stream.getvalue(), overwrite=overwrite)
+
+
+def write_parquet(dataset, path, *, overwrite=False):
+    try:
+        import pyarrow as pa
+        import pyarrow.parquet as pq
+    except ImportError:
+        raise ImportError('Install Parquet support with: pip install "ccrt[tables]"') from None
+    path = Path(path)
+    if path.exists() and not overwrite:
+        raise FileExistsError(f"output exists: {path}")
+    integers = {
+        "date_precision",
+        "geo_precision",
+        "total_deaths_low",
+        "total_deaths_best",
+        "total_deaths_high",
+        "civilian_deaths",
+    }
+    fields = [
+        (
+            name,
+            pa.int64()
+            if name in integers
+            else pa.float64()
+            if name in {"latitude", "longitude"}
+            else pa.string(),
+        )
+        for name in SourceRecord.__dataclass_fields__
+    ]
+    metadata = dataset_dict(dataset)
+    metadata.pop("records")
+    schema = pa.schema(fields, metadata={b"ccrt": canonical_json(metadata).encode("utf-8")})
+    table = pa.Table.from_pylist([r.to_dict() for r in dataset], schema=schema)
+    # Serialize before touching the target; null-only and empty columns keep fixed types.
+    sink = pa.BufferOutputStream()
+    pq.write_table(table, sink)
+    from ccrt.storage import atomic_write_bytes
+
+    atomic_write_bytes(path, sink.getvalue().to_pybytes(), overwrite=overwrite)
+
+
+def read_parquet(path):
+    try:
+        import pyarrow.parquet as pq
+    except ImportError:
+        raise ImportError('Install Parquet support with: pip install "ccrt[tables]"') from None
+    table = pq.read_table(path)
+    if b"ccrt" not in (table.schema.metadata or {}):
+        raise ValueError("Parquet file has no CCRT provenance; import it through a source adapter")
+    payload = json.loads(table.schema.metadata[b"ccrt"])
+    payload["records"] = table.to_pylist()
+    return dataset_from_dict(payload)
+
+
+def write_csv(result, path, *, review=None, overwrite=False):
+    """Write candidates and unlinked accounts. Several rows may refer to one record."""
+    review = review or Review.create(result)
+    review.validate(result)
+    decisions = {d.candidate_id: d for d in review.decisions}
+    evidence = [
+        "candidate_id",
+        "status",
+        "reviewer",
+        "note",
+        "reviewed_at",
+        "run_id",
+        "days_apart",
+        "distance_km",
+        "match_score",
+        "warnings",
+        "unlinked_reason",
+    ]
+    columns = list(SourceRecord.__dataclass_fields__)
+    fields = evidence + [f"{side}_{field}" for side in ("left", "right") for field in columns]
+    stream = io.StringIO(newline="")
+    writer = csv.DictWriter(stream, fieldnames=fields)
+    writer.writeheader()
+    run_id = result.run_id
+    for candidate in result.candidates:
+        writer.writerow(
+            {
+                **asdict(decisions[candidate.candidate_id]),
+                "run_id": run_id,
+                "days_apart": candidate.days_apart,
+                "distance_km": round(candidate.distance_km, 3),
+                "match_score": round(candidate.score, 6),
+                "warnings": ";".join(candidate.warnings),
+                **{f"left_{k}": v for k, v in candidate.left.to_dict().items()},
+                **{f"right_{k}": v for k, v in candidate.right.to_dict().items()},
+            }
+        )
+    for item in result.unlinked:
+        side = "left" if item.record.source == result.left.source else "right"
+        writer.writerow(
+            {
+                "status": "unlinked",
+                "run_id": run_id,
+                "unlinked_reason": item.reason,
+                **{f"{side}_{k}": v for k, v in item.record.to_dict().items()},
+            }
+        )
+    atomic_write(path, stream.getvalue(), overwrite=overwrite)
+
+
+def read_review_csv(path, result):
+    """Read only review fields from a previously exported candidate CSV."""
+    from datetime import datetime, timezone
+
+    from ccrt.review import Decision
+
+    decisions = []
+    with open(path, newline="", encoding="utf-8-sig") as stream:
+        reader = csv.DictReader(stream)
+        required = {"candidate_id", "status", "reviewer", "note", "reviewed_at", "run_id"}
+        if not required <= set(reader.fieldnames or ()):
+            raise ValueError("review CSV is missing review columns")
+        for row in reader:
+            if row["run_id"] != result.run_id:
+                raise ValueError(f"review CSV line {reader.line_num}: belongs to a different run")
+            if row["status"] == "unlinked" and not row["candidate_id"]:
+                continue
+            if row["status"] != "unresolved" and not row["reviewed_at"]:
+                row["reviewed_at"] = datetime.now(timezone.utc).isoformat()
+            try:
+                decisions.append(Decision(**{k: row[k] for k in required if k != "run_id"}))
+            except ValueError as exc:
+                pair = f"{row.get('left_source_id', '?')}/{row.get('right_source_id', '?')}"
+                raise ValueError(f"review CSV line {reader.line_num} ({pair}): {exc}") from exc
+    review = Review(result.run_id, tuple(decisions))
+    review.validate(result)
+    return review