inferencekit-cli 0.1.0__py3-none-any.whl

inferencekit/checkpoint.py

@@ -0,0 +1,396 @@
+"""Read safetensors headers (never the weights) from a local directory or the Hugging Face Hub.
+
+A ``.safetensors`` file starts with an 8-byte little-endian unsigned integer N, then N bytes
+of JSON::
+
+    {"<tensor name>": {"dtype": "BF16", "shape": [rows, cols], "data_offsets": [begin, end]},
+     ..., "__metadata__": {...}}
+
+and then the tensor data. The first 8 + N bytes give every tensor's dtype and shape, which is
+all a bytes-per-token count needs. For a Hub id the local Hugging Face cache is tried first (an
+engine box usually has the snapshot it serves on disk, often with no network); otherwise each
+shard costs one or two HTTP range requests (a few MB at most, whatever the checkpoint size). The
+weights are never downloaded. ``HF_HUB_OFFLINE`` is honoured: offline, only the cache is read.
+
+Every header is recorded as (file name, header length, sha256 of the N header bytes), so a
+count can be reproduced against exactly the same tensors.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import os
+import struct
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from inferencekit.registry import OpError
+
+# Bits per element of each safetensors dtype. Packed formats (NVFP4/MXFP4 stored as U8 pairs,
+# FP8 scales) are counted as stored: the bytes on disk are the bytes the kernel reads.
+DTYPE_BITS = {
+    "F64": 64, "F32": 32, "F16": 16, "BF16": 16,
+    "I64": 64, "I32": 32, "I16": 16, "I8": 8,
+    "U64": 64, "U32": 32, "U16": 16, "U8": 8, "BOOL": 8,
+    "F8_E4M3": 8, "F8_E5M2": 8, "F8_E8M0": 8, "F8_E4M3FNUZ": 8, "F8_E5M2FNUZ": 8,
+    "F6_E2M3": 6, "F6_E3M2": 6, "F4": 4, "C64": 64,
+}
+MAX_HEADER = 100_000_000  # the safetensors format caps the header at 100 MB
+FIRST_READ = 1 << 16  # first range request: the length prefix plus the start of the header
+INDEX = "model.safetensors.index.json"
+SINGLE = "model.safetensors"
+
+
+class NotFound(OpError):
+    """The Hub has no such file at that revision."""
+
+
+class HubUnavailable(OpError):
+    """The Hub could not be reached (offline mode, network error, server error); not a missing file."""
+
+
+@dataclass(frozen=True)
+class Tensor:
+    name: str
+    dtype: str
+    shape: tuple[int, ...]
+    nbytes: int
+    file: str
+
+
+@dataclass
+class Checkpoint:
+    """Every tensor of a checkpoint, from its headers, plus how to reproduce the read."""
+
+    tensors: dict[str, Tensor]
+    files: list[dict]  # [{file, header_len, header_sha256, tensors, data_bytes}]
+    source: str  # "directory" | "hub" | "hub-cache"
+    commit: str | None = None  # the Hub commit the headers came from, when the Hub (or the cache) says
+    metadata: dict = field(default_factory=dict)
+    local_dir: Path | None = None  # the snapshot directory, for headers read from the local HF cache
+
+    @property
+    def headers_digest(self) -> str:
+        """One sha256 over the sorted (file, header sha256) list."""
+        lines = "".join(f"{f['file']}:{f['header_sha256']}\n" for f in sorted(self.files, key=lambda f: f["file"]))
+        return hashlib.sha256(lines.encode()).hexdigest()
+
+    @property
+    def stored_bytes(self) -> int:
+        return sum(t.nbytes for t in self.tensors.values())
+
+
+def tensor_bytes(dtype: str, shape) -> int:
+    """Stored bytes of one tensor: elements x bits per element, rounded up to whole bytes."""
+    if dtype not in DTYPE_BITS:
+        raise OpError(f"unknown safetensors dtype {dtype}; cannot size it")
+    return math.ceil(math.prod(int(d) for d in shape) * DTYPE_BITS[dtype] / 8)
+
+
+def parse_header(raw: bytes, file: str) -> tuple[dict[str, Tensor], dict]:
+    """Tensors and the digest entry from the N header bytes of one file."""
+    try:
+        header = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as e:
+        raise OpError(f"{file}: safetensors header is not valid JSON ({e})") from None
+    if not isinstance(header, dict):
+        raise OpError(f"{file}: safetensors header is not a JSON object")
+    tensors: dict[str, Tensor] = {}
+    data_bytes = 0
+    for name, info in header.items():
+        if name == "__metadata__":
+            continue
+        shape = tuple(int(d) for d in info["shape"])
+        size = tensor_bytes(info["dtype"], shape)
+        begin, end = info["data_offsets"]
+        if end - begin != size:
+            raise OpError(f"{file}: tensor {name} is {info['dtype']} {list(shape)} = {size} bytes, but its "
+                          f"data_offsets span {end - begin} bytes")
+        tensors[name] = Tensor(name, info["dtype"], shape, size, file)
+        data_bytes = max(data_bytes, end)
+    entry = {"file": file, "header_len": len(raw), "header_sha256": hashlib.sha256(raw).hexdigest(),
+             "tensors": len(tensors), "data_bytes": data_bytes}
+    return tensors, entry
+
+
+def _length(prefix: bytes, file: str) -> int:
+    if len(prefix) < 8:
+        raise OpError(f"{file}: shorter than the 8-byte safetensors length prefix")
+    (n,) = struct.unpack("<Q", prefix[:8])
+    if n > MAX_HEADER:
+        raise OpError(f"{file}: header length {n} exceeds the safetensors limit; not a safetensors file?")
+    return n
+
+
+def _merge(parts: list[tuple[dict[str, Tensor], dict]], source: str, commit: str | None = None) -> Checkpoint:
+    tensors: dict[str, Tensor] = {}
+    for t, _ in parts:
+        dup = set(t) & set(tensors)
+        if dup:
+            raise OpError(f"tensor {sorted(dup)[0]} appears in two shards; pass the directory with its index file")
+        tensors.update(t)
+    return Checkpoint(tensors, [e for _, e in parts], source, commit)
+
+
+# --------------------------------------------------------------------------- local files
+
+def local_header(path: Path) -> bytes:
+    with open(path, "rb") as f:
+        n = _length(f.read(8), path.name)
+        raw = f.read(n)
+    if len(raw) != n:
+        raise OpError(f"{path.name}: truncated header ({len(raw)} of {n} bytes)")
+    return raw
+
+
+def local_files(directory: Path) -> list[Path]:
+    """Shards named by the index file when there is one (so stray copies are not counted twice)."""
+    index = directory / INDEX
+    if index.is_file():
+        names = sorted(set(json.loads(index.read_text())["weight_map"].values()))
+        return [directory / n for n in names]
+    return sorted(directory.glob("*.safetensors"))
+
+
+def load_local(directory: Path) -> Checkpoint | None:
+    files = local_files(directory)
+    if not files:
+        return None
+    try:
+        return _merge([parse_header(local_header(p), p.name) for p in files], "directory")
+    except OSError as e:
+        raise OpError(f"could not read a safetensors header in {directory}: {e}") from None
+
+
+# --------------------------------------------------------------------------- Hugging Face Hub
+
+_TRUE = {"1", "ON", "YES", "TRUE"}
+
+
+def _hf_constants():
+    """huggingface_hub.constants when that package is installed, else None."""
+    try:
+        from huggingface_hub import constants
+    except Exception:  # noqa: BLE001 - not installed, or broken
+        return None
+    return constants
+
+
+def hub_offline() -> bool:
+    """HF_HUB_OFFLINE (or TRANSFORMERS_OFFLINE), as huggingface_hub reads it."""
+    constants = _hf_constants()
+    if constants is not None and getattr(constants, "HF_HUB_OFFLINE", False):
+        return True
+    return any(os.environ.get(k, "").upper() in _TRUE for k in ("HF_HUB_OFFLINE", "TRANSFORMERS_OFFLINE"))
+
+
+def hub_cache_dir() -> Path:
+    """The Hugging Face hub cache: huggingface_hub's own setting when installed, else the same env vars."""
+    constants = _hf_constants()
+    if constants is not None and getattr(constants, "HF_HUB_CACHE", None):
+        return Path(constants.HF_HUB_CACHE)
+    env = os.environ
+    if env.get("HF_HUB_CACHE") or env.get("HUGGINGFACE_HUB_CACHE"):
+        return Path(env.get("HF_HUB_CACHE") or env["HUGGINGFACE_HUB_CACHE"]).expanduser()
+    home = env.get("HF_HOME") or os.path.join(env.get("XDG_CACHE_HOME") or os.path.expanduser("~/.cache"),
+                                               "huggingface")
+    return Path(home).expanduser() / "hub"
+
+
+def cached_file(repo: str, filename: str, revision: str | None) -> Path | None:
+    """A file of ``repo`` at ``revision`` in the local HF cache, or None. Never touches the network.
+    Uses huggingface_hub.try_to_load_from_cache when installed, else the same cache layout
+    (models--org--name/refs/<rev> -> snapshots/<commit>/<file>)."""
+    try:
+        from huggingface_hub import try_to_load_from_cache
+    except Exception:  # noqa: BLE001 - not installed, or too old
+        try_to_load_from_cache = None
+    if try_to_load_from_cache is not None:
+        try:
+            p = try_to_load_from_cache(repo, filename, revision=revision)
+        except Exception:  # noqa: BLE001 - an unusable cache is the same as no cache
+            return None
+        return Path(p) if isinstance(p, str) and os.path.isfile(p) else None
+    folder = hub_cache_dir() / ("models--" + repo.replace("/", "--"))
+    rev = revision or "main"
+    ref = folder / "refs" / rev
+    try:
+        commit = ref.read_text().strip() if ref.is_file() else rev
+    except OSError:
+        return None
+    p = folder / "snapshots" / commit / filename
+    return p if p.is_file() else None
+
+
+def snapshot_commit(path: Path) -> str | None:
+    """The commit of a cached file: the directory name after 'snapshots' in its (unresolved) path."""
+    parts = Path(path).parts
+    if "snapshots" in parts:
+        i = len(parts) - 1 - parts[::-1].index("snapshots")
+        if i + 1 < len(parts):
+            return parts[i + 1]
+    return None
+
+
+def load_hub_cache(repo: str, revision: str | None) -> Checkpoint | None:
+    """Headers of a Hub checkpoint whose shards are all in the local HF cache, else None."""
+    index = cached_file(repo, INDEX, revision)
+    if index is not None:
+        try:
+            names = sorted(set(json.loads(index.read_text())["weight_map"].values()))
+        except (OSError, ValueError, KeyError):
+            return None
+    else:
+        names = [SINGLE]
+    paths = [cached_file(repo, n, revision) for n in names]
+    if not names or any(p is None for p in paths):
+        return None
+    commits = {snapshot_commit(p) for p in paths} | ({snapshot_commit(index)} if index else set())
+    if len(commits) != 1:  # files from different snapshots: not one checkpoint
+        return None
+    try:
+        parts = [parse_header(local_header(p), n) for p, n in zip(paths, names)]
+    except OSError:
+        return None
+    ck = _merge(parts, "hub-cache", commits.pop())
+    ck.local_dir = paths[0].parent
+    return ck
+
+
+def hub_endpoint() -> str:
+    return (os.environ.get("HF_ENDPOINT") or "https://huggingface.co").rstrip("/")
+
+
+def hub_token() -> str | None:
+    """HF_TOKEN, else the huggingface_hub login when that package is installed. Never recorded."""
+    token = os.environ.get("HF_TOKEN")
+    if token:
+        return token
+    try:
+        from huggingface_hub import get_token
+
+        return get_token()
+    except Exception:  # noqa: BLE001 - not installed, or an old version without get_token
+        return None
+
+
+def hub_url(repo: str, filename: str, revision: str | None) -> str:
+    rev = urllib.parse.quote(revision or "main", safe="")
+    return f"{hub_endpoint()}/{repo}/resolve/{rev}/{urllib.parse.quote(filename)}"
+
+
+class _CommitRedirects(urllib.request.HTTPRedirectHandler):
+    """Follows redirects and keeps the X-Repo-Commit header the Hub puts on the redirect itself."""
+
+    commit: str | None = None
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        self.commit = self.commit or headers.get("X-Repo-Commit")
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+def _get(url: str, byte_range: tuple[int, int] | None, limit: int) -> tuple[bytes, str | None]:
+    """GET at most ``limit`` bytes. The token is an unredirected header, so it is not forwarded
+    to the storage host a Hub download redirects to (that URL is pre-signed)."""
+    req = urllib.request.Request(url)
+    if byte_range:
+        req.add_header("Range", f"bytes={byte_range[0]}-{byte_range[1]}")
+    token = hub_token()
+    if token:
+        req.add_unredirected_header("Authorization", f"Bearer {token}")
+    redirects = _CommitRedirects()
+    with urllib.request.build_opener(redirects).open(req, timeout=60) as r:
+        commit = redirects.commit or r.headers.get("X-Repo-Commit")
+        if byte_range and r.status == 200 and byte_range[0] > 0:  # range ignored: skip to the offset
+            r.read(byte_range[0])
+        # Read only what is needed even if the server ignored the range: never the weights.
+        return r.read(limit), commit
+
+
+def hub_small_file(repo: str, filename: str, revision: str | None) -> tuple[bytes | None, str | None]:
+    """A small file (index, config) from the Hub, or (None, None) when the repo has no such file."""
+    if hub_offline():
+        raise HubUnavailable(f"could not fetch {filename} for '{repo}': HF_HUB_OFFLINE is set")
+    try:
+        return _get(hub_url(repo, filename, revision), None, 64 << 20)
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            return None, None
+        cls = HubUnavailable if e.code >= 500 else OpError
+        raise cls(f"could not fetch {filename} for '{repo}': HTTP {e.code}") from None
+    except OSError as e:  # connection refused, DNS, timeout: the Hub is unreachable
+        raise HubUnavailable(f"could not fetch {filename} for '{repo}': {e}") from None
+
+
+def hub_header(repo: str, filename: str, revision: str | None) -> tuple[bytes, str | None]:
+    if hub_offline():
+        raise HubUnavailable(f"could not read the header of {filename} in '{repo}': HF_HUB_OFFLINE is set")
+    url = hub_url(repo, filename, revision)
+    try:
+        first, commit = _get(url, (0, FIRST_READ - 1), FIRST_READ)
+        n = _length(first, filename)
+        raw = first[8:8 + n]
+        if len(raw) < n:
+            rest, _ = _get(url, (8 + len(raw), 8 + n - 1), n - len(raw))
+            raw += rest
+    except urllib.error.HTTPError as e:
+        cls = NotFound if e.code == 404 else HubUnavailable if e.code >= 500 else OpError
+        raise cls(f"could not read the header of {filename} in '{repo}': HTTP {e.code}") from None
+    except OSError as e:  # connection refused, DNS, timeout: the Hub is unreachable
+        raise HubUnavailable(f"could not read the header of {filename} in '{repo}': {e}") from None
+    if len(raw) != n:
+        raise OpError(f"{filename}: got {len(raw)} of {n} header bytes from the Hub")
+    return raw, commit
+
+
+def load_hub(repo: str, revision: str | None) -> Checkpoint | None:
+    """Headers of every shard named by the index (or the single model.safetensors): from the local
+    HF cache when every shard is there, else by range requests. Offline with no cached copy, or with
+    the Hub unreachable, raises HubUnavailable (the caller can fall back to the config method)."""
+    cached = load_hub_cache(repo, revision)
+    if cached is not None:
+        return cached
+    if hub_offline():
+        raise HubUnavailable(f"HF_HUB_OFFLINE is set and the safetensors shards of '{repo}' at "
+                             f"{revision or 'main'} are not all in the local Hugging Face cache ({hub_cache_dir()})")
+    index, commit = hub_small_file(repo, INDEX, revision)
+    if index is not None:
+        try:
+            names = sorted(set(json.loads(index)["weight_map"].values()))
+        except (ValueError, KeyError) as e:
+            raise OpError(f"{repo}: unreadable {INDEX} ({e})") from None
+    else:
+        names = [SINGLE]
+    parts = []
+    for name in names:
+        try:
+            raw, c = hub_header(repo, name, revision)
+        except NotFound:
+            if index is None:  # no index and no model.safetensors: not a safetensors repo
+                return None
+            raise
+        commit = commit or c
+        parts.append(parse_header(raw, name))
+    return _merge(parts, "hub", commit)
+
+
+def is_hub_id(model: str) -> bool:
+    return not Path(model).exists() and model.count("/") == 1 and not model.startswith((".", "/"))
+
+
+def load(model: str, revision: str | None = None) -> Checkpoint | None:
+    """Headers for a model directory, a file inside one (e.g. its config.json), or a Hub id.
+    None when there are no safetensors files to read."""
+    p = Path(model)
+    if p.is_dir():
+        return load_local(p)
+    if p.is_file():
+        return load_local(p.parent)
+    if is_hub_id(model):
+        return load_hub(model, revision)
+    return None

inferencekit/cli.py

@@ -0,0 +1,274 @@
+"""The ``inferencekit`` command: argparse built from the operation registry.
+
+Each operation's ``cli`` path becomes a (sub)command: ("nsys", "analyze") ->
+``inferencekit nsys analyze``. Arguments map one to one: ``prompt_len`` -> ``--prompt-len``,
+positional arguments stay positional, arrays repeat (``--keep-env A --keep-env B``).
+Commands that run another program take it after ``--``:
+
+    inferencekit nsys capture -- python serve_bench.py --steps 64
+
+Output on stdout. An evidence record is printed tersely by default: its summary line (for
+``bench rounds``, then each engine's ratio to the best one with its 95% CI), one line per gate or
+claim that did not PASS (verdict, name, reason cut to 160 characters), a count of limitations and
+missing items, and ``evidence: <path>`` (the full record, already on disk). The
+full record as JSON comes with ``--json`` (before or after the command) or
+``INFERENCEKIT_OUTPUT=json``; programs that parse stdout set one of them (``bench rounds`` does
+for its ``bench serve`` children). Results that are not records (listings, validation results)
+print as JSON either way, and Markdown results (``report --format md``, ``intake template``,
+``ledger trailers``) as their text. Errors go to stderr with exit code 1.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from inferencekit import __version__, registry
+from inferencekit.evidence import default_root, set_default_root
+from inferencekit.registry import OpError
+
+_PY_TYPES = {"string": str, "integer": int, "number": float}
+OUTPUT_ENV = "INFERENCEKIT_OUTPUT"
+OUTPUT_MODES = ("terse", "json")
+JSON_HELP = "Print the full JSON result instead of the terse summary (same as INFERENCEKIT_OUTPUT=json)."
+CLAIM_VERDICTS = ("FAIL", "UNPROVEN", "NOT RUN")  # the claim verdicts that are not PASS
+REASON_CHARS = 160
+
+
+def _flag(name: str) -> str:
+    return "--" + name.replace("_", "-")
+
+
+def _help(text: str) -> str:
+    # argparse %-formats help strings ("%(default)s"), so a literal "%" must be doubled.
+    return text.replace("%", "%%")
+
+
+def _add_arguments(parser: argparse.ArgumentParser, op: registry.Operation) -> None:
+    for a in op.args:
+        if a.name == "argv" and op.passthrough:
+            continue  # filled from the words after "--"
+        help_text = _help(a.help + (f" (default: {a.default})" if a.default not in (None, [], "") else ""))
+        if a.positional:
+            nargs = "+" if a.type == "array" else None
+            parser.add_argument(a.name, nargs=nargs, type=_PY_TYPES.get(a.items if a.type == "array" else a.type),
+                                choices=a.choices, help=help_text)
+        elif a.type == "boolean":
+            parser.add_argument(_flag(a.name), dest=a.name, action=argparse.BooleanOptionalAction, default=None,
+                                help=help_text)
+        elif a.type == "array":
+            parser.add_argument(_flag(a.name), dest=a.name, action="append", type=_PY_TYPES.get(a.items, str),
+                                choices=a.choices, default=None, help=help_text + " (repeatable)")
+        else:
+            parser.add_argument(_flag(a.name), dest=a.name, type=_PY_TYPES[a.type], choices=a.choices, default=None,
+                                help=help_text)
+    if not any(a.name == "json" for a in op.args):
+        # Also accepted after the command (`inferencekit gates run ... --json`). SUPPRESS: a subcommand that
+        # was not given --json must not reset a --json given before it.
+        parser.add_argument("--json", dest="json_output", action="store_true", default=argparse.SUPPRESS,
+                            help=JSON_HELP)
+    parser.set_defaults(_op=op.name)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ops = registry.load_all()
+    parser = argparse.ArgumentParser(prog="inferencekit", description="Measure-first LLM inference optimisation. "
+                                     "Every command writes a content-addressed evidence record under runs/.")
+    parser.add_argument("--version", action="version", version=f"inferencekit {__version__}")
+    parser.add_argument("--runs-dir", help="Evidence store directory (default: $INFERENCEKIT_RUNS_DIR, else the "
+                        "deprecated $INFERKIT_RUNS_DIR, else ./runs). Records made with --run-dir are also copied to "
+                        "<run-dir>/evidence/.")
+    parser.add_argument("--json", dest="json_output", action="store_true", default=False, help=JSON_HELP)
+    top = parser.add_subparsers(dest="command", metavar="<command>")
+    groups: dict[str, argparse._SubParsersAction] = {}
+    for op in ops.values():
+        if len(op.cli) == 1:
+            sub = top.add_parser(op.cli[0], help=_help(op.summary), description=op.summary)
+        else:
+            head, leaf = op.cli
+            if head not in groups:
+                grp = top.add_parser(head, help=f"{head} commands")
+                groups[head] = grp.add_subparsers(dest="subcommand", metavar="<subcommand>")
+            sub = groups[head].add_parser(leaf, help=_help(op.summary), description=op.summary)
+        _add_arguments(sub, op)
+    mcp = top.add_parser("mcp", help="Model Context Protocol server")
+    mcp_sub = mcp.add_subparsers(dest="subcommand", metavar="<subcommand>")
+    mcp_sub.add_parser("serve", help="Serve every operation as an MCP tool over stdio").set_defaults(_op="mcp:serve")
+    return parser
+
+
+# --------------------------------------------------------------------------- output
+
+def output_mode(flag: bool) -> str:
+    """``json`` with --json or INFERENCEKIT_OUTPUT=json, else ``terse`` (an unknown value is reported)."""
+    if flag:
+        return "json"
+    value = (os.environ.get(OUTPUT_ENV) or "terse").strip().lower()
+    if value not in OUTPUT_MODES:
+        print(f"inferencekit: {OUTPUT_ENV}={value!r} is not one of {list(OUTPUT_MODES)}; using terse",
+              file=sys.stderr)
+        return "terse"
+    return value
+
+
+def is_record(result) -> bool:
+    """An evidence record (it has an id, a kind and a summary), as opposed to a listing or a check result."""
+    return isinstance(result, dict) and all(isinstance(result.get(k), str) and result.get(k)
+                                            for k in ("evidence_id", "kind", "summary"))
+
+
+def _one_line(text, limit: int | None = None) -> str:
+    out = " ".join(str(text).split())
+    return out if limit is None or len(out) <= limit else out[: limit - 3] + "..."
+
+
+def problem_lines(record: dict) -> list[str]:
+    """One line per gate or claim of a record that did not PASS: ``<VERDICT> <name>: <reason>``.
+
+    Read from ``data.gates`` (gates run, gates spec-exact), else ``data.verdicts`` (one verdict per
+    engine: quality score), else the record's own ``data.verdict`` / ``data.reason`` (correctness), plus
+    every ``HARD GATE`` limitation (bench decode, bench rounds). A gate that did not run and was not
+    expected (``applicable`` false) is left out: it is not a finding.
+    """
+    data = record.get("data") if isinstance(record.get("data"), dict) else {}
+    lines = []
+    gates = data.get("gates")
+    items = gates.items() if isinstance(gates, dict) else enumerate(gates) if isinstance(gates, list) else ()
+    for key, g in items:
+        if not isinstance(g, dict) or g.get("verdict") not in CLAIM_VERDICTS:
+            continue
+        if g["verdict"] == "NOT RUN" and not g.get("applicable"):
+            continue
+        reason = f": {_one_line(g['reason'], REASON_CHARS)}" if g.get("reason") else ""
+        lines.append(f"{g['verdict']} {g.get('gate') or key}{reason}")
+    verdicts = data.get("verdicts")
+    if not lines and isinstance(verdicts, dict):
+        lines += [f"{v} {name}" for name, v in verdicts.items() if v in CLAIM_VERDICTS]
+    if not lines and data.get("verdict") in CLAIM_VERDICTS[:2]:
+        name = (data.get("request") or {}).get("op") or record["kind"]
+        reason = f": {_one_line(data['reason'], REASON_CHARS)}" if isinstance(data.get("reason"), str) else ""
+        lines.append(f"{data['verdict']} {name}{reason}")
+    for lim in record.get("limitations") or []:
+        if isinstance(lim, str) and lim.startswith("HARD GATE"):
+            lines.append("FAIL hard gate: " + _one_line(lim.split(":", 1)[1], REASON_CHARS))
+    return lines
+
+
+def _num(x) -> bool:
+    return isinstance(x, (int, float)) and not isinstance(x, bool)
+
+
+def ratio_line(record: dict) -> str | None:
+    """bench rounds: every other engine's ratio to the best engine, with its 95% CI, for the metric and bucket
+    the summary names (the first row whose engine is the best), e.g.
+    ``ratio to best decode_tok_s [all] (a): b 0.52 (95% CI 0.5-0.54)``. None for other records."""
+    data = record.get("data") if isinstance(record.get("data"), dict) else {}
+    if not isinstance(data.get("rows"), list) or not isinstance(data.get("plan"), dict):
+        return None
+    rows = [r for r in data["rows"] if isinstance(r, dict)]
+    head = next((r for r in rows if r.get("engine") == r.get("best")), None)
+    if head is None:
+        return None
+    parts = []
+    for r in rows:
+        if (r.get("bucket"), r.get("metric")) != (head.get("bucket"), head.get("metric")) or \
+                r.get("engine") == head.get("engine") or not _num(r.get("ratio_to_best")):
+            continue
+        ci = r.get("ratio_ci95") if isinstance(r.get("ratio_ci95"), list) else []
+        lo, hi = (ci + [None, None])[:2]
+        parts.append(f"{r['engine']} {r['ratio_to_best']:.3g}" + (f" (95% CI {lo:.3g}-{hi:.3g})"
+                                                                  if _num(lo) and _num(hi) else ""))
+    if not parts:
+        return None
+    more = f", +{len(parts) - 6} more" if len(parts) > 6 else ""
+    return (f"ratio to best {head.get('metric')} [{head.get('bucket')}] ({head.get('engine')}): "
+            + ", ".join(parts[:6]) + more)
+
+
+def evidence_paths(record: dict) -> tuple[Path | None, Path | None]:
+    """Where the full record is: the evidence store copy, and the run-directory copy when there is one."""
+    eid = record["evidence_id"]
+    stored = (default_root() / eid / "evidence.json").resolve()
+    data = record.get("data") if isinstance(record.get("data"), dict) else {}
+    args = (data.get("request") or {}).get("args") or {}
+    run_dir = args.get("run_dir") or data.get("run_dir")  # bench rounds defaults it to the manifest's directory
+    copy = None
+    if isinstance(run_dir, str) and run_dir:
+        copy = (Path(run_dir).expanduser() / "evidence" / f"{eid}.json").resolve()
+    return (stored if stored.is_file() else None), (copy if copy is not None and copy.is_file() else None)
+
+
+def terse(record: dict) -> str:
+    """The terse view of an evidence record (see the module docstring)."""
+    lines = [_one_line(record["summary"])]
+    ratios = ratio_line(record)
+    if ratios:
+        lines.append(ratios)
+    lines += problem_lines(record)
+    n_lim = len(record.get("limitations") or [])
+    n_missing = len((record.get("coverage") or {}).get("missing") or [])
+    if n_lim or n_missing:
+        lines.append(f"{n_lim} limitation(s), {n_missing} missing item(s): listed in the evidence file")
+    stored, copy = evidence_paths(record)
+    if stored is None and copy is None:
+        lines.append(f"evidence: {record['evidence_id']} (no evidence file found under {default_root()})")
+    else:
+        lines.append(f"evidence: {stored or copy}")
+        if stored is not None and copy is not None:
+            lines.append(f"run-dir copy: {copy}")
+    return "\n".join(lines)
+
+
+def print_result(result, mode: str) -> None:
+    if isinstance(result, dict) and result.get("format") == "md" and "markdown" in result:
+        print(result["markdown"])
+        print(f"(written to {result['path']})", file=sys.stderr)
+    elif mode == "terse" and is_record(result):
+        print(terse(result))
+    else:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    # Split at the first "--": everything after it is the command to profile, untouched by argparse.
+    passthrough = None
+    if "--" in argv:
+        i = argv.index("--")
+        argv, passthrough = argv[:i], argv[i + 1:]
+    parser = build_parser()
+    ns = parser.parse_args(argv)
+    if ns.runs_dir:
+        set_default_root(ns.runs_dir)
+    op_name = getattr(ns, "_op", None)
+    if op_name is None:
+        parser.print_help()
+        return 2
+    if op_name == "mcp:serve":
+        from inferencekit.mcp_server import serve
+
+        serve()
+        return 0
+    op = registry.get(op_name)
+    args = {a.name: getattr(ns, a.name) for a in op.args if hasattr(ns, a.name)}
+    if op.passthrough:
+        if not passthrough:
+            parser.error(f"inferencekit {' '.join(op.cli)} needs the command to run after '--'")
+        args["argv"] = passthrough
+    elif passthrough:
+        parser.error("'--' is only valid for commands that run another program")
+    mode = output_mode(getattr(ns, "json_output", False))
+    try:
+        result = registry.call(op_name, args)
+    except OpError as e:
+        print(f"inferencekit: error: {e}", file=sys.stderr)
+        return 1
+    print_result(result, mode)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())