wikidata-google-knowledge-mcp 0.2.0__py3-none-any.whl

wikidata_google_knowledge_mcp/__init__.py

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

wikidata_google_knowledge_mcp/arbitration.py

@@ -0,0 +1,283 @@
+"""Optional cheap-model arbitration for the unresolved tail.
+
+The model sees one entity at a time: a compact packet with the caller input,
+at most 3 (hard max 5) Wikidata-bearing and 3 (max 5) Google-only candidates,
+their joins, local evidence and conflicts. No raw provider JSON, no articles,
+no tools, no browsing. Candidates are named by packet-local handles (C1, C2...);
+the model can only pick one of those handles, so it cannot mint a QID or a
+Google id. Anything else - a schema violation, an unknown handle, a timeout,
+a refused budget, a missing price - is a failure and the row stays HOLD.
+
+The model name, endpoint, credential and prices are configuration. The call
+budget and the cost cap are checked before every call, using a worst-case
+estimate, and the actual usage is recorded after it.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from datetime import datetime, timezone
+from typing import Any, Callable
+
+import anyio
+import httpx2
+
+from .config import ARBITRATION_KEY_ENV, USER_AGENT, Settings
+from .normalize import EntityInput, parse_url
+from .policy import CONFLICTS, EVIDENCE, RESOLVER_POLICY_VERSION
+from .redact import redact, register_secret, short_error
+from .secrets import Credential, load_credential
+
+ARB_DECISIONS = ("MATCH", "NO_MATCH", "AMBIGUOUS", "CONFLICT")
+ARB_REASONS = (
+    "NAME_AND_LOCATION_CONSISTENT", "NAME_AND_ROLE_CONSISTENT", "NAME_AND_CREATOR_CONSISTENT",
+    "NAME_AND_DATE_CONSISTENT", "OFFICIAL_SITE_CONSISTENT", "DESCRIPTION_CONSISTENT", "PROVIDERS_CONCORDANT",
+    "MULTIPLE_PLAUSIBLE", "INSUFFICIENT_EVIDENCE", "KIND_MISMATCH", "LOCATION_MISMATCH", "DATE_MISMATCH",
+    "GRAIN_MISMATCH", "NO_PLAUSIBLE_CANDIDATE",
+)
+NORMAL_PER_PROVIDER = 3
+MAX_PER_PROVIDER = 5
+SYSTEM_PROMPT = (
+    "You check whether a local entity is the same real-world entity as one of the listed candidates. "
+    "Use only the facts in the packet. Candidates are named C1, C2, ...; never output any other identifier. "
+    "Answer MATCH with one candidate only when the packet's facts make that identity clear. "
+    "A person needs more than a shared name. A dated event occurrence is not its festival or series, and a "
+    "series is not one dated edition. If several candidates remain plausible answer AMBIGUOUS; if the facts "
+    "contradict each other answer CONFLICT; if no candidate fits answer NO_MATCH."
+)
+
+
+def _short(s: Any, n: int) -> str:
+    s = "" if s is None else str(s)
+    return s if len(s) <= n else s[: n - 1] + "…"
+
+
+def _ctx(ev_ctx: dict, qids: list[str], key: str = "label_en", n: int = 3) -> list[str]:
+    out: list[str] = []
+    for q in qids or []:
+        for v in (ev_ctx.get(q) or {}).get(key) or (ev_ctx.get(q) or {}).get("labels") or []:
+            if v not in out:
+                out.append(v)
+                break
+        if len(out) >= n:
+            break
+    return out
+
+
+def _candidate_entry(handle: str, ident: dict, ctx: dict) -> dict:
+    f = ident.get("facts") or {}
+    refs = f.get("refs") or {}
+    g = ident.get("gitem") or {}
+    e: dict[str, Any] = {"id": handle, "source": "both" if (ident.get("qid") and ident.get("gid")) else (
+        "wikidata" if ident.get("qid") else "google"), "label": _short(ident.get("label"), 80),
+        "desc": _short(ident.get("desc") or g.get("desc"), 160), "kinds": ident.get("kinds") or []}
+    if f:
+        cls = _ctx(ctx, refs.get("classes", []))
+        if cls:
+            e["classes"] = cls
+        iso = sorted({v for q in refs.get("country", []) for v in (ctx.get(q) or {}).get("iso") or []})
+        if iso:
+            e["country"] = iso
+        places = _ctx(ctx, refs.get("admin", []) + refs.get("location", []), "labels")
+        if places:
+            e["places"] = places
+        for bucket in ("occupation", "creator", "organizer"):
+            vals = _ctx(ctx, refs.get(bucket, []), "labels")
+            if vals:
+                e[bucket] = vals
+        dates = []
+        for pid in ("P585", "P580", "P582", "P577", "P571"):
+            for d in (f.get("dates") or {}).get(pid, [])[:1]:
+                dates.append(f"{pid}:{d['y']}" + (f"-{d['m']:02d}" if d.get("m") and d.get("p", 0) >= 10 else ""))
+        if dates:
+            e["dates"] = dates[:3]
+        hosts = [u["host"] for u in (parse_url(w) for w in f.get("websites") or []) if u]
+        if hosts:
+            e["website_hosts"] = hosts[:2]
+    if g:
+        if g.get("types"):
+            e["google_types"] = g["types"][:3]
+        gh = parse_url(g.get("website"))
+        if gh:
+            e["google_website_host"] = gh["host"]
+    if (ident.get("info") or {}).get("distance_km") is not None:
+        e["distance_km"] = ident["info"]["distance_km"]
+    e["evidence"] = sorted(c for c in ident["codes"] if c in EVIDENCE)
+    e["conflicts"] = sorted(c for c in ident["conflicts"] if c in CONFLICTS)
+    return e
+
+
+def build_packet(inp: EntityInput, decided: dict, ctx: dict, per_provider: int = NORMAL_PER_PROVIDER
+                 ) -> tuple[dict, dict[str, dict]]:
+    """Packet for one entity plus {handle: {"qid", "gid"}} of the observed ids behind each handle."""
+    n = max(1, min(MAX_PER_PROVIDER, per_provider))
+    live = [i for i in decided["live"]]
+    wd = [i for i in live if i.get("qid")][:n]
+    gonly = [i for i in live if not i.get("qid")][:n]
+    handles: dict[str, dict] = {}
+    cands = []
+    for k, ident in enumerate(wd + gonly, start=1):
+        h = f"C{k}"
+        handles[h] = {"qid": ident.get("qid"), "gid": ident.get("gid")}
+        cands.append(_candidate_entry(h, ident, ctx))
+    entity = inp.compact()
+    entity.pop("source_id", None)
+    for k in ("existing_id_trusted", "official_url_reviewed"):
+        entity.pop(k, None)
+    packet = {"policy": RESOLVER_POLICY_VERSION, "entity": entity, "candidates": cands,
+              "deterministic": {"decision": decided["decision"], "reasons": decided["reasons"]}}
+    return packet, handles
+
+
+def packet_hash(packet: dict) -> str:
+    return "pk1:" + hashlib.sha256(json.dumps(packet, sort_keys=True, ensure_ascii=False,
+                                              separators=(",", ":")).encode()).hexdigest()[:32]
+
+
+def output_schema(handles: list[str]) -> dict:
+    return {
+        "type": "object", "additionalProperties": False,
+        "required": ["decision", "candidate", "reason_codes"],
+        "properties": {
+            "decision": {"type": "string", "enum": list(ARB_DECISIONS)},
+            "candidate": {"anyOf": [{"type": "string", "enum": handles}, {"type": "null"}]},
+            "reason_codes": {"type": "array", "maxItems": 4, "items": {"type": "string", "enum": list(ARB_REASONS)}},
+        },
+    }
+
+
+def validate_output(obj: Any, handles: dict[str, dict]) -> tuple[dict | None, str | None]:
+    if not isinstance(obj, dict) or set(obj) - {"decision", "candidate", "reason_codes"}:
+        return None, "schema_violation"
+    d, c, r = obj.get("decision"), obj.get("candidate"), obj.get("reason_codes")
+    if d not in ARB_DECISIONS or not isinstance(r, list) or len(r) > 4 or any(x not in ARB_REASONS for x in r):
+        return None, "schema_violation"
+    if d == "MATCH":
+        if not isinstance(c, str) or c not in handles:
+            return None, "unknown_candidate"
+    elif c is not None and c not in handles:
+        return None, "unknown_candidate"
+    return {"decision": d, "candidate": c if d == "MATCH" else None, "reason_codes": sorted(set(r))}, None
+
+
+def est_tokens(n_bytes: int) -> int:
+    """Estimate only: UTF-8 bytes / 4 (no tokenizer is bundled)."""
+    return (n_bytes + 3) // 4
+
+
+class Arbiter:
+    """One instance per run: it owns the call counter and the spent-cost total."""
+
+    def __init__(self, settings: Settings, credential: Credential | None = None,
+                 transport: httpx2.AsyncBaseTransport | None = None, clock: Callable[[], float] = time.time,
+                 cache_get: Callable[[str], dict | None] | None = None,
+                 cache_put: Callable[[str, dict], None] | None = None):
+        self.settings = settings
+        self.credential = credential if credential is not None else load_credential(ARBITRATION_KEY_ENV,
+                                                                                    settings.secrets_file)
+        register_secret(self.credential.value)
+        self._transport = transport
+        self._clock = clock
+        self._get = cache_get or (lambda k: None)
+        self._put = cache_put or (lambda k, v: None)
+        self.calls = 0
+        self.cost_usd = 0.0
+        self.tokens_in = 0
+        self.tokens_out = 0
+        self.cache_hits = 0
+
+    def availability(self) -> str | None:
+        """None when a paid call is allowed at all, else the reason it is not."""
+        s = self.settings
+        if not s.arbitration_enabled:
+            return "disabled"
+        if not s.arbitration_model:
+            return "model_not_configured"
+        if not self.credential.present:
+            return "credential_missing"
+        if s.arbitration_price_in_per_mtok is None or s.arbitration_price_out_per_mtok is None:
+            return "price_unknown"
+        return None
+
+    def _worst_cost(self, prompt_bytes: int) -> float:
+        s = self.settings
+        return (est_tokens(prompt_bytes) * s.arbitration_price_in_per_mtok +
+                s.arbitration_max_output_tokens * s.arbitration_price_out_per_mtok) / 1e6
+
+    def _key(self, phash: str) -> str:
+        return hashlib.sha256(f"{phash}|{self.settings.arbitration_model}|{RESOLVER_POLICY_VERSION}".encode()).hexdigest()
+
+    async def arbitrate(self, packet: dict, handles: dict[str, dict]) -> dict:
+        s = self.settings
+        phash = packet_hash(packet)
+        base = {"model": s.arbitration_model, "policy": RESOLVER_POLICY_VERSION, "packet_hash": phash,
+                "at": datetime.fromtimestamp(self._clock(), tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")}
+        if not handles:
+            return {**base, "status": "skipped", "error": "no_candidates"}
+        cached = self._get(self._key(phash))
+        if cached is not None:
+            self.cache_hits += 1
+            return {**cached, "cached": True}
+        why = self.availability()
+        if why:
+            return {**base, "status": "unavailable", "error": why}
+        messages = [{"role": "system", "content": SYSTEM_PROMPT},
+                    {"role": "user", "content": json.dumps(packet, ensure_ascii=False, separators=(",", ":"))}]
+        body = {"model": s.arbitration_model, "messages": messages,
+                "max_completion_tokens": s.arbitration_max_output_tokens,
+                "response_format": {"type": "json_schema", "json_schema": {
+                    "name": "entity_arbitration", "strict": True, "schema": output_schema(sorted(handles))}}}
+        prompt_bytes = len(json.dumps(messages, ensure_ascii=False).encode())
+        if self.calls >= s.arbitration_max_calls:
+            return {**base, "status": "budget", "error": "max_calls"}
+        worst = self._worst_cost(prompt_bytes)
+        if self.cost_usd + worst > s.arbitration_max_cost_usd:
+            return {**base, "status": "budget", "error": "max_cost"}
+        self.calls += 1
+        headers = {"Authorization": f"Bearer {self.credential.value}", "User-Agent": USER_AGENT,
+                   "Content-Type": "application/json"}
+        try:
+            with anyio.fail_after(s.arbitration_timeout_s):
+                async with httpx2.AsyncClient(transport=self._transport,
+                                              timeout=httpx2.Timeout(s.arbitration_timeout_s)) as http:
+                    resp = await http.post(s.arbitration_url, json=body, headers=headers)
+        except (TimeoutError, httpx2.TimeoutException):
+            self.cost_usd += worst  # unknown usage: assume the worst case was billed
+            return {**base, "status": "failed", "error": "timeout", "cost_usd": round(worst, 6), "cost_basis": "worst_case"}
+        except httpx2.TransportError as exc:
+            return {**base, "status": "failed", "error": redact(short_error(exc))}
+        if resp.status_code != 200:
+            return {**base, "status": "failed", "error": f"http_{resp.status_code}"}
+        try:
+            data = resp.json()
+            usage = data.get("usage") or {}
+            msg = data["choices"][0]["message"]
+            content = msg.get("content")
+            obj = json.loads(content) if isinstance(content, str) else None
+        except (ValueError, KeyError, IndexError, TypeError):
+            data, usage, obj = {}, {}, None
+        tin, tout = usage.get("prompt_tokens"), usage.get("completion_tokens")
+        if isinstance(tin, int) and isinstance(tout, int):
+            cost = (tin * s.arbitration_price_in_per_mtok + tout * s.arbitration_price_out_per_mtok) / 1e6
+            basis = "measured_usage"
+            self.tokens_in += tin
+            self.tokens_out += tout
+        else:
+            cost, basis = worst, "worst_case"
+        self.cost_usd += cost
+        result, err = validate_output(obj, handles)
+        rec = {**base, "usage": {"prompt_tokens": tin, "completion_tokens": tout}, "cost_usd": round(cost, 6),
+               "cost_basis": basis}
+        if result is None:
+            return {**rec, "status": "failed", "error": err or "malformed"}
+        picked = handles.get(result["candidate"]) if result["candidate"] else None
+        out = {**rec, "status": "ok", **result, "selected": picked}
+        self._put(self._key(phash), out)
+        return out
+
+    def summary(self) -> dict:
+        return {"calls": self.calls, "cache_hits": self.cache_hits, "cost_usd": round(self.cost_usd, 6),
+                "tokens_in": self.tokens_in, "tokens_out": self.tokens_out,
+                "availability": self.availability() or "available", "model": self.settings.arbitration_model}

wikidata_google_knowledge_mcp/batch.py

@@ -0,0 +1,367 @@
+"""resolve-batch: streamed JSONL in, JSONL out, plus a receipt.
+
+- Input is read line by line and resolved in chunks; memory is bounded by the
+  chunk size, not the corpus.
+- Every row gets exactly one output record, in input order, even when another
+  row is invalid or a provider fails.
+- The output file is the checkpoint. On restart, rows whose
+  (source_id, input_fingerprint) already have a record are skipped; rows that
+  ended in BUDGET_EXHAUSTED (always) or PROVIDER_ERROR (with retry_errors) are
+  removed from the output first and resolved again. A torn last line from a
+  crash is dropped.
+- A provider budget running out stops the run after the current chunk.
+- The receipt is recomputed from the complete output file, so it is the same
+  however many restarts produced that file.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from collections import Counter
+from pathlib import Path
+from typing import Callable, Iterator
+
+from .compact import dumps
+from .evidence_export import unavailable
+from .errors import InvalidRequest
+from .normalize import richness
+from .policy import DECISIONS, RESOLVER_POLICY_VERSION
+from .resolver import Resolver, Row, invalid_record, make_row
+
+RETRY_ALWAYS = {"BUDGET_EXHAUSTED"}
+RETRY_ON_REQUEST = {"PROVIDER_ERROR", "ARBITRATION_FAILED", "ARBITRATION_BUDGET"}
+
+
+def evidence_path(out: Path) -> Path:
+    return out.with_name(out.name + ".evidence.jsonl")
+
+
+def _row_key(rec: dict) -> tuple:
+    return (rec.get("source_id"), rec.get("input_fingerprint"))
+
+
+def _read_input(path: Path) -> Iterator[tuple[int, object]]:
+    with path.open("r", encoding="utf-8") as fh:
+        for i, line in enumerate(fh):
+            if not line.strip():
+                continue
+            try:
+                yield i, json.loads(line)
+            except ValueError:
+                yield i, {"__invalid_json__": True}
+
+
+def _prepare_output(out: Path, retry_errors: bool, policy: str, mode: str) -> tuple[Counter, bool]:
+    """Drop a torn last line and rows that must be recomputed; return (completed keys,
+    whether a dropped row sat before a kept one, i.e. the file must be re-sorted at the end).
+    An output file holds one policy version and one provider mode only."""
+    done: Counter = Counter()
+    gap = reorder = False
+    if not out.exists():
+        return done, False
+    retry = RETRY_ALWAYS | (RETRY_ON_REQUEST if retry_errors else set())
+    keep: list[str] = []
+    changed = False
+    with out.open("r", encoding="utf-8") as fh:
+        for line in fh:
+            if not line.endswith("\n"):
+                changed = True  # torn write from an interrupted run
+                break
+            try:
+                rec = json.loads(line)
+            except ValueError:
+                changed = True
+                continue
+            if rec.get("input_fingerprint") is not None and (
+                    rec.get("resolver_policy_version") != policy or rec.get("providers_mode") not in (None, mode)):
+                raise InvalidRequest(f"{out.name} holds results of policy {rec.get('resolver_policy_version')} / "
+                                     f"mode {rec.get('providers_mode')}; write this run to a new --out file")
+            if set(rec.get("reasons") or []) & retry:
+                changed = gap = True
+                continue
+            reorder = reorder or gap
+            keep.append(line)
+            done[_row_key(rec)] += 1
+    if changed:
+        tmp = out.with_suffix(out.suffix + ".tmp")
+        with tmp.open("w", encoding="utf-8") as fh:
+            fh.writelines(keep)
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.replace(tmp, out)
+    _sync_sidecar(out)
+    return done, reorder
+
+
+def _sync_sidecar(out: Path) -> None:
+    """Keep exactly one evidence line per kept output row (drops torn lines and the
+    evidence of rows that will be recomputed)."""
+    side = evidence_path(out)
+    if not side.exists():
+        return
+    wanted = Counter(json.loads(line).get("evidence_ref") for line in out.open("r", encoding="utf-8"))
+    keep: list[str] = []
+    with side.open("r", encoding="utf-8") as fh:
+        for line in fh:
+            if not line.endswith("\n"):
+                break
+            try:
+                ref = json.loads(line).get("evidence_ref")
+            except ValueError:
+                continue
+            if wanted[ref] > 0:
+                wanted[ref] -= 1
+                keep.append(line)
+    tmp = side.with_suffix(side.suffix + ".tmp")
+    with tmp.open("w", encoding="utf-8") as fh:
+        fh.writelines(keep)
+        fh.flush()
+        os.fsync(fh.fileno())
+    os.replace(tmp, side)
+
+
+def _input_key(i: int, raw: object) -> tuple:
+    if isinstance(raw, dict) and raw.get("__invalid_json__"):
+        return (f"line:{i + 1}", None)
+    row = make_row(i, raw)
+    return (row.source_id, row.fp)
+
+
+def _reorder_output(out: Path, in_path: Path) -> None:
+    _reorder_file(out, in_path, _row_key)
+    side = evidence_path(out)
+    if side.exists():
+        _reorder_file(side, in_path, lambda e: (e.get("source_id"), e.get("input_fingerprint")))
+
+
+def _reorder_file(out: Path, in_path: Path, keyfn) -> None:
+    """Restore input order after retried rows were appended at the end. Keeps only
+    integer positions and byte offsets in memory, not the records."""
+    positions: dict[tuple, list[int]] = {}
+    for pos, (i, raw) in enumerate(_read_input(in_path)):
+        positions.setdefault(_input_key(i, raw), []).append(pos)
+    order: list[tuple[int, int, int]] = []
+    seen: Counter = Counter()
+    with out.open("rb") as fh:
+        while True:
+            off = fh.tell()
+            line = fh.readline()
+            if not line:
+                break
+            key = keyfn(json.loads(line))
+            plist = positions.get(key, [])
+            k = seen[key]
+            seen[key] += 1
+            order.append((plist[k] if k < len(plist) else 1 << 60, off, len(line)))
+    order.sort()
+    tmp = out.with_suffix(out.suffix + ".tmp")
+    with out.open("rb") as src, tmp.open("wb") as dst:
+        for _, off, n in order:
+            src.seek(off)
+            dst.write(src.read(n))
+        dst.flush()
+        os.fsync(dst.fileno())
+    os.replace(tmp, out)
+
+
+def summarize(out: Path) -> dict:
+    """Deterministic summary of a complete output file."""
+    dec: Counter = Counter()
+    kinds: Counter = Counter()
+    rich: Counter = Counter()
+    by_kind: dict[str, Counter] = {}
+    reasons: Counter = Counter()
+    calls: Counter = Counter()
+    views: Counter = Counter()
+    transitions: Counter = Counter()
+    n = llm_needed = llm_used = res_hits = prov_hits = minimal_google = google_called = 0
+    cost = 0.0
+    with out.open("r", encoding="utf-8") as fh:
+        for line in fh:
+            rec = json.loads(line)
+            n += 1
+            d = rec["decision"]
+            dec[d] += 1
+            k = rec.get("kind") or "none"
+            kinds[k] += 1
+            rich[rec.get("richness") or "invalid"] += 1
+            by_kind.setdefault(k, Counter())[d] += 1
+            for r in rec.get("reasons") or []:
+                reasons[r] += 1
+            for p, v in (rec.get("provider_calls") or {}).items():
+                calls[p] += v
+            llm_needed += bool(rec.get("llm_needed"))
+            llm_used += bool(rec.get("arbitration_used"))
+            cost += rec.get("arbitration_cost") or 0.0
+            res_hits += bool((rec.get("cache_hits") or {}).get("resolution"))
+            prov_hits += (rec.get("cache_hits") or {}).get("provider") or 0
+            google_called += bool(rec.get("google_called"))
+            v = rec.get("views")
+            if v:
+                views[("wikidata", v["wikidata"]["decision"])] += 1
+                views[("dual", v["dual"]["decision"])] += 1
+                transitions[f'{v["wikidata"]["decision"]}->{v["dual"]["decision"]}'] += 1
+                minimal_google += bool(v.get("minimal_would_call_google"))
+    out_bytes = out.stat().st_size if out.exists() else 0
+    summary = {
+        "policy": RESOLVER_POLICY_VERSION,
+        "rows": n,
+        "decisions": {d: dec.get(d, 0) for d in DECISIONS},
+        "decision_share": {d: round(dec.get(d, 0) / n, 4) if n else 0.0 for d in DECISIONS},
+        "kinds": dict(sorted(kinds.items())),
+        "richness": dict(sorted(rich.items())),
+        "decisions_by_kind": {k: dict(sorted(c.items())) for k, c in sorted(by_kind.items())},
+        "reasons": dict(sorted(reasons.items())),
+        "llm_needed": llm_needed,
+        "llm_used": llm_used,
+        "arbitration_cost_usd": round(cost, 6),
+        "dedicated_provider_calls": dict(sorted(calls.items())),
+        "rows_with_google_called": google_called,
+        "resolution_cache_hits": res_hits,
+        "provider_cache_hits": prov_hits,
+        "output_bytes": out_bytes,
+    }
+    if views:
+        summary["ablation"] = {
+            "wikidata_only": {d: views.get(("wikidata", d), 0) for d in DECISIONS},
+            "dual": {d: views.get(("dual", d), 0) for d in DECISIONS},
+            "transitions": dict(sorted(transitions.items())),
+            "minimal_would_call_google": minimal_google,
+        }
+    return summary
+
+
+async def run_batch(resolver: Resolver, in_path: Path, out_path: Path, *, chunk: int = 25,
+                    retry_errors: bool = False, limit: int | None = None,
+                    clock: Callable[[], float] = time.monotonic) -> dict:
+    t0 = clock()
+    done, reorder = _prepare_output(out_path, retry_errors, RESOLVER_POLICY_VERSION, resolver.providers)
+    skipped = processed = 0
+    stop_reason = None
+    interrupted = False
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    fh = out_path.open("a", encoding="utf-8")
+    efh = evidence_path(out_path).open("a", encoding="utf-8")
+    pending: list[Row] = []
+
+    async def flush() -> str | None:
+        nonlocal processed
+        if not pending:
+            return None
+        try:
+            await resolver.resolve_rows(pending)
+        except Exception:  # noqa: BLE001 - isolate: retry one by one
+            for r in pending:
+                if r.result is None and r.inp is not None:
+                    try:
+                        await resolver.resolve_rows([r])
+                    except Exception as exc:  # noqa: BLE001
+                        r.error = f"internal_error:{type(exc).__name__}"
+                        r.result = invalid_record(r)
+                        r.result["reasons"] = ["PROVIDER_ERROR"]
+                        r.result["warnings"] = [r.error]
+        reason = None
+        for r in pending:
+            ev = r.evidence or unavailable(r.result, "invalid_input" if r.inp is None else "evidence_not_built")
+            efh.write(json.dumps(ev, ensure_ascii=False, sort_keys=True) + "\n")
+        efh.flush()
+        os.fsync(efh.fileno())
+        for r in pending:
+            fh.write(dumps(r.result) + "\n")
+            processed += 1
+            if "BUDGET_EXHAUSTED" in (r.result.get("reasons") or []):
+                reason = "budget_exhausted"
+        fh.flush()
+        os.fsync(fh.fileno())
+        pending.clear()
+        return reason
+
+    try:
+        for i, raw in _read_input(in_path):
+            if limit is not None and processed + len(pending) + skipped >= limit:
+                break
+            if isinstance(raw, dict) and raw.get("__invalid_json__"):
+                row = Row(idx=i, source_id=f"line:{i + 1}", error="invalid JSON")
+                row.result = invalid_record(row)
+            else:
+                row = make_row(i, raw)
+            key = (row.source_id, row.fp)
+            if done[key] > 0:
+                done[key] -= 1
+                skipped += 1
+                continue
+            pending.append(row)
+            if len(pending) >= chunk:
+                stop_reason = await flush()
+                if stop_reason:
+                    break
+        if not stop_reason:
+            stop_reason = await flush()
+    except KeyboardInterrupt:
+        interrupted = True  # rows already written stay; the open chunk is redone on restart
+        stop_reason = "interrupted"
+    finally:
+        fh.close()
+        efh.close()
+    if reorder and not interrupted:
+        _reorder_output(out_path, in_path)
+    receipt = {
+        "tool": "wdkg", "op": "resolve-batch", "policy": RESOLVER_POLICY_VERSION,
+        "input": str(in_path), "output": str(out_path), "evidence": str(evidence_path(out_path)),
+        "mode": {"providers": resolver.providers, "llm": resolver.llm, "search": resolver.search_strategy,
+                 "candidates": resolver.k, "chunk": chunk},
+        "complete": stop_reason is None and not interrupted,
+        "next": None if stop_reason is None else "re-run the same command to resume (budget-stopped rows are redone)",
+        "stop_reason": stop_reason,
+        "session": {
+            "processed": processed, "skipped_already_done": skipped,
+            "duration_s": round(clock() - t0, 3),
+            "upstream_requests": dict(resolver.budget.used),
+            "request_caps": dict(getattr(resolver.budget, "limits", {})),
+            "raw_bytes": dict(resolver.budget.raw_bytes),
+            "cache_hits": {k: v for k, v in resolver.stats.items()},
+            "arbitration": resolver.arbiter.summary(),
+        },
+        "summary": summarize(out_path),
+    }
+    return receipt
+
+
+def dry_run(resolver: Resolver, in_path: Path, limit: int | None = None) -> dict:
+    """Parse, normalise and check the resolution cache. No network, no output."""
+    n = invalid = cached = 0
+    kinds: Counter = Counter()
+    rich: Counter = Counter()
+    with_url = with_ids = 0
+    for i, raw in _read_input(in_path):
+        if limit is not None and n >= limit:
+            break
+        n += 1
+        row = make_row(i, raw) if not (isinstance(raw, dict) and raw.get("__invalid_json__")) else None
+        if row is None or row.inp is None:
+            invalid += 1
+            continue
+        kinds[row.inp.kind or "none"] += 1
+        rich[richness(row.inp)] += 1
+        with_url += row.inp.url is not None
+        with_ids += bool(row.inp.existing_wikidata_qid or row.inp.existing_google_kg_id)
+        rec = resolver.store.get_resolution(resolver._res_key(row.fp)) if resolver.use_cache else None
+        if rec is not None and (rec.get("evidence") or not resolver.require_evidence) and \
+                resolver._refs_fresh(rec.get("refs") or {}):
+            cached += 1
+    todo = n - invalid - cached
+    k = resolver.k
+    est = {
+        "wikidata_label_batches": -(-todo // 60),
+        "wikidata_wbsearch_upper_bound": todo if resolver.search_strategy != "label" else 0,
+        "wikidata_entity_batches_upper_bound": -(-(todo * k) // 50),
+        "wikidata_context_batches_estimate": -(-(todo * k * 6) // 150),
+        "google_upper_bound": (todo + -(-(todo * k) // 20)) if resolver.providers == "dual" else with_url,
+    }
+    return {"op": "resolve-batch", "dry_run": True, "policy": RESOLVER_POLICY_VERSION, "rows": n,
+            "invalid": invalid, "resolution_cache_hits": cached, "to_resolve": todo,
+            "kinds": dict(sorted(kinds.items())), "richness": dict(sorted(rich.items())),
+            "with_official_url": with_url, "with_existing_ids": with_ids,
+            "estimated_requests": est, "note": "estimates are upper bounds before any cache reuse"}