RadGraph-IT 1.0.0__py3-none-any.whl

radgraphit/artifacts/manifest.py

@@ -0,0 +1,290 @@
+"""``model_manifest.json``: schema, parsing, and SHA-256 verification.
+
+The manifest is versioned *inside the Hugging Face model repository*, alongside ``config.json``,
+``vocab.json`` and the weights. It records what package/schema/backend the bundle targets, which
+encoder it needs, the pinned revision, and a SHA-256 for every required file. The resolver verifies
+it against the downloaded bytes **before** the model is built, so a corrupted or tampered download
+fails loudly and early rather than as an obscure state-dict error.
+
+Example ``model_manifest.json`` (see also ``scripts/publish_model.py``, which generates it):
+
+.. code-block:: json
+
+    {
+      "manifest_version": 1,
+      "package": "radgraphit",
+      "min_package_version": "1.0.0",
+      "schema": "radgraph-xl",
+      "backend": "dygie_v2",
+      "encoder": {
+        "model_name": "IVN-RIN/medBIT-r3-plus",
+        "revision": "<immutable encoder commit sha>",
+        "max_length": 512
+      },
+      "revision": "<git-sha-or-tag of this bundle>",
+      "weights_file": "best.pt",
+      "files": {
+        "config.json": {"sha256": "…"},
+        "vocab.json": {"sha256": "…"},
+        "best.pt": {"sha256": "…"}
+      }
+    }
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath, PureWindowsPath
+
+from packaging.version import InvalidVersion, Version
+
+from ..core.errors import ManifestError
+from . import registry
+
+MANIFEST_VERSION = 1
+_CHUNK = 1 << 20  # 1 MiB streaming reads, so large weight files don't load into memory to hash
+_SHA256 = re.compile(r"^[0-9a-fA-F]{64}$")
+
+
+def sha256_file(path: Path) -> str:
+    """Return the hex SHA-256 of a file, read in streaming chunks."""
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(_CHUNK), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _safe_filename(value: object, *, field: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise ManifestError(f"Manifest field {field} must be a non-empty filename.")
+    posix = PurePosixPath(value)
+    windows = PureWindowsPath(value)
+    if (
+        posix.is_absolute()
+        or windows.is_absolute()
+        or len(posix.parts) != 1
+        or len(windows.parts) != 1
+        or value in {".", ".."}
+    ):
+        raise ManifestError(
+            f"Manifest field {field} must be a plain filename inside the bundle, got {value!r}."
+        )
+    return value
+
+
+def _positive_int(value: object, *, field: str) -> int:
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise ManifestError(f"Manifest field {field} must be a positive integer.")
+    if value <= 0:
+        raise ManifestError(f"Manifest field {field} must be a positive integer.")
+    return value
+
+
+def _non_empty_string(value: object, *, field: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ManifestError(f"Manifest field {field} must be a non-empty string.")
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class ModelManifest:
+    """Parsed, validated model manifest."""
+
+    manifest_version: int
+    package: str
+    min_package_version: str
+    schema: str
+    backend: str
+    encoder_model_name: str
+    encoder_revision: str
+    encoder_max_length: int
+    revision: str
+    weights_file: str
+    files: dict[str, str]  # filename -> expected sha256
+
+    @classmethod
+    def from_path(cls, path: Path) -> ModelManifest:
+        """Parse and structurally validate a ``model_manifest.json`` file."""
+        if not path.is_file():
+            raise ManifestError(
+                f"Model manifest not found at {path}. A valid RadGraphIT bundle must contain "
+                f"{registry.MANIFEST_FILENAME} alongside its config, vocabulary, and weights."
+            )
+        try:
+            raw = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+            raise ManifestError(f"Could not read a valid JSON manifest at {path}: {exc}") from exc
+        if not isinstance(raw, dict):
+            raise ManifestError(f"Model manifest at {path} must be a JSON object.")
+
+        try:
+            encoder = raw["encoder"]
+            files_raw = raw["files"]
+            if not isinstance(encoder, dict):
+                raise TypeError("'encoder' must be an object")
+            if not isinstance(files_raw, dict) or not files_raw:
+                raise TypeError("'files' must be a non-empty object")
+            files: dict[str, str] = {}
+            for name, metadata in files_raw.items():
+                filename = _safe_filename(name, field="files key")
+                if not isinstance(metadata, dict):
+                    raise TypeError(f"metadata for {filename!r} must be an object")
+                expected = metadata["sha256"]
+                if not isinstance(expected, str) or not _SHA256.fullmatch(expected):
+                    raise ValueError(f"sha256 for {filename!r} must contain exactly 64 hex digits")
+                files[filename] = expected.lower()
+
+            weights_file = _safe_filename(raw["weights_file"], field="weights_file")
+            if weights_file not in registry.WEIGHT_FILENAMES:
+                raise ValueError(
+                    f"weights_file must be one of {', '.join(registry.WEIGHT_FILENAMES)}"
+                )
+            encoder_model_name = encoder["model_name"]
+            if not isinstance(encoder_model_name, str) or not encoder_model_name.strip():
+                raise ValueError("encoder.model_name must be a non-empty string")
+            if "revision" in encoder:
+                encoder_revision = encoder["revision"]
+            else:
+                encoder_revision = registry.ENCODER_REVISIONS.get(encoder_model_name)
+            if not isinstance(encoder_revision, str) or not encoder_revision.strip():
+                raise ValueError(
+                    "encoder.revision must contain an immutable commit SHA or release tag"
+                )
+            manifest_version = raw["manifest_version"]
+            if not isinstance(manifest_version, int) or isinstance(manifest_version, bool):
+                raise ValueError("manifest_version must be an integer")
+
+            manifest = cls(
+                manifest_version=manifest_version,
+                package=_non_empty_string(raw["package"], field="package"),
+                min_package_version=_non_empty_string(
+                    raw["min_package_version"], field="min_package_version"
+                ),
+                schema=_non_empty_string(raw["schema"], field="schema"),
+                backend=_non_empty_string(raw["backend"], field="backend"),
+                encoder_model_name=encoder_model_name,
+                encoder_revision=encoder_revision,
+                encoder_max_length=_positive_int(encoder["max_length"], field="encoder.max_length"),
+                revision=_non_empty_string(raw["revision"], field="revision"),
+                weights_file=weights_file,
+                files=files,
+            )
+        except ManifestError:
+            raise
+        except (KeyError, TypeError, ValueError) as exc:
+            raise ManifestError(
+                f"Model manifest at {path} is missing or has a malformed field: {exc}"
+            ) from exc
+        required = {
+            registry.CONFIG_FILENAME,
+            registry.VOCAB_FILENAME,
+            manifest.weights_file,
+        }
+        missing_checksums = required.difference(manifest.files)
+        if missing_checksums:
+            raise ManifestError(
+                "Model manifest must provide SHA-256 checksums for every required bundle file; "
+                f"missing: {', '.join(sorted(missing_checksums))}."
+            )
+        return manifest
+
+    def check_compatibility(self, package_version: str) -> None:
+        """Validate manifest/backend/schema/version compatibility with this package.
+
+        Raises :class:`ManifestError` on any incompatibility, with a message naming the mismatch.
+        """
+        if self.manifest_version != MANIFEST_VERSION:
+            if self.manifest_version > MANIFEST_VERSION:
+                raise ManifestError(
+                    f"Manifest version {self.manifest_version} is newer than this package supports "
+                    f"({MANIFEST_VERSION}). Upgrade radgraphit."
+                )
+            raise ManifestError(
+                f"Manifest version {self.manifest_version} is unsupported; expected "
+                f"{MANIFEST_VERSION}."
+            )
+        if self.package != "radgraphit":
+            raise ManifestError(f"Manifest targets package {self.package!r}, not 'radgraphit'.")
+        if self.backend not in registry.SUPPORTED_BACKENDS:
+            raise ManifestError(
+                f"Manifest backend {self.backend!r} is not supported by this package "
+                f"(supported: {sorted(registry.SUPPORTED_BACKENDS)})."
+            )
+        if self.schema not in registry.SUPPORTED_SCHEMAS:
+            raise ManifestError(
+                f"Manifest schema {self.schema!r} is not supported by this package "
+                f"(supported: {sorted(registry.SUPPORTED_SCHEMAS)})."
+            )
+        try:
+            installed = Version(package_version)
+            required = Version(self.min_package_version)
+        except InvalidVersion as exc:
+            raise ManifestError(f"Manifest or package contains an invalid version: {exc}") from exc
+        if installed < required:
+            raise ManifestError(
+                f"This model requires radgraphit >= {self.min_package_version}, but "
+                f"{package_version} is installed. Upgrade radgraphit."
+            )
+
+    def verify_files(self, directory: Path) -> None:
+        """Verify every file listed in the manifest exists in ``directory`` with the right SHA-256.
+
+        Also checks that the manifest's encoder metadata agrees with ``config.json``.
+        Raises :class:`ManifestError` naming the first inconsistency.
+        """
+        for filename, expected in self.files.items():
+            file_path = directory / filename
+            if not file_path.is_file():
+                raise ManifestError(
+                    f"Manifest lists required file {filename!r} but it is missing from {directory}."
+                )
+            try:
+                actual = sha256_file(file_path)
+            except OSError as exc:
+                raise ManifestError(f"Could not hash manifest file {file_path}: {exc}") from exc
+            if actual != expected:
+                raise ManifestError(
+                    f"Checksum mismatch for {filename!r} in {directory}: manifest expects "
+                    f"{expected}, downloaded file is {actual}. The bundle is corrupted or has been "
+                    "tampered with; delete the cache directory and re-download."
+                )
+        config_path = directory / registry.CONFIG_FILENAME
+        try:
+            config = json.loads(config_path.read_text(encoding="utf-8"))
+        except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+            raise ManifestError(
+                f"Could not read a valid JSON config at {config_path}: {exc}"
+            ) from exc
+        if not isinstance(config, dict) or not isinstance(config.get("encoder"), dict):
+            raise ManifestError(f"{config_path} must contain an 'encoder' object.")
+        encoder = config["encoder"]
+        if encoder.get("model_name") != self.encoder_model_name:
+            raise ManifestError(
+                "Manifest encoder.model_name does not match config.json: "
+                f"{self.encoder_model_name!r} != {encoder.get('model_name')!r}."
+            )
+        try:
+            config_max_length = _positive_int(
+                encoder.get("max_length"), field="config encoder.max_length"
+            )
+        except ManifestError as exc:
+            raise ManifestError(f"Invalid encoder configuration in {config_path}: {exc}") from exc
+        if config_max_length != self.encoder_max_length:
+            raise ManifestError(
+                "Manifest encoder.max_length does not match config.json: "
+                f"{self.encoder_max_length} != {config_max_length}."
+            )
+
+    def required_filenames(self) -> tuple[str, ...]:
+        """All filenames the manifest declares (used to drive selective downloads)."""
+        names = set(self.files) | {
+            registry.MANIFEST_FILENAME,
+            registry.CONFIG_FILENAME,
+            registry.VOCAB_FILENAME,
+            self.weights_file,
+        }
+        return tuple(sorted(names))

radgraphit/artifacts/registry.py

@@ -0,0 +1,24 @@
+"""The single source of truth for the default model location and supported bundle schema."""
+
+from __future__ import annotations
+
+DEFAULT_MODEL_ID = "radgraphIT/Radgraph-IT-v1"
+DEFAULT_REVISION = "368c01baddbe1bdfb1b439243ae0c224f0e6624d"
+ENCODER_REVISIONS = {
+    "IVN-RIN/medBIT-r3-plus": "0f1c91e551551869a72935962b54c1f5247333a4",
+}
+
+#: Files the model bundle must contain on the Hub / in a local directory.
+MANIFEST_FILENAME = "model_manifest.json"
+CONFIG_FILENAME = "config.json"
+VOCAB_FILENAME = "vocab.json"
+
+#: Weight file candidates, in preference order (safetensors preferred once published; the current
+#: v2 artifact ships ``best.pt``).
+WEIGHT_FILENAMES = ("model.safetensors", "best.pt")
+
+#: Backend identifiers this package version knows how to build.
+SUPPORTED_BACKENDS = frozenset({"dygie_v2"})
+
+#: Manifest ``schema`` values this package version can serialize to.
+SUPPORTED_SCHEMAS = frozenset({"radgraph-xl"})

radgraphit/artifacts/resolver.py

@@ -0,0 +1,200 @@
+"""Resolve a model bundle to a verified local directory.
+
+Two entry points:
+
+* :func:`resolve_pretrained` — the standard path. Downloads only the files declared by the bundle's
+  manifest from an explicitly pinned Hugging Face Hub revision, caches them, and verifies
+  compatibility + SHA-256 before returning.
+* :func:`resolve_local` — for development, offline testing, and diagnostics. Points at an existing
+  local directory and requires the exact same manifest verification.
+
+Both return a :class:`ResolvedModel` (a verified directory + parsed manifest). Neither ever falls
+back to unverified loading: a missing manifest, an unreachable repository, or a bad checksum raises
+a specific, actionable error.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path, PurePosixPath
+
+from huggingface_hub import hf_hub_download, snapshot_download
+
+from ..core.errors import ModelNotConfiguredError, ModelNotFoundError
+from . import registry
+from .manifest import ModelManifest
+
+logger = logging.getLogger("radgraphit")
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedModel:
+    """A verified, on-disk model bundle."""
+
+    directory: Path
+    manifest: ModelManifest
+
+    @property
+    def config_path(self) -> Path:
+        return self.directory / registry.CONFIG_FILENAME
+
+    @property
+    def vocab_path(self) -> Path:
+        return self.directory / registry.VOCAB_FILENAME
+
+    @property
+    def weights_path(self) -> Path:
+        return self.directory / self.manifest.weights_file
+
+
+def _package_version() -> str:
+    try:
+        return version("radgraphit")
+    except PackageNotFoundError:  # not installed (e.g. running from a source checkout)
+        from .. import __version__
+
+        return __version__
+
+
+_BUNDLE_SUBDIRS = ("", "model")  # search the snapshot root first, then a conventional model/ subdir
+
+
+def _looks_like_bundle(directory: Path) -> bool:
+    """Whether ``directory`` holds a dygie training bundle (config + vocab + weights).
+
+    The ``config.json`` must carry an ``"encoder"`` block, which distinguishes the training config
+    from an unrelated Hugging Face ``config.json`` that may sit at the repo root next to custom
+    modeling code (as in the published RadGraphIT repo, whose bundle lives under ``model/``).
+    """
+    if not directory.is_dir():
+        return False
+    config_path = directory / registry.CONFIG_FILENAME
+    if not config_path.is_file() or not (directory / registry.VOCAB_FILENAME).is_file():
+        return False
+    if not any((directory / weights).is_file() for weights in registry.WEIGHT_FILENAMES):
+        return False
+    try:
+        config = json.loads(config_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError, UnicodeError):
+        return False
+    return isinstance(config, dict) and "encoder" in config
+
+
+def _locate_bundle(root: Path) -> Path:
+    """Return the directory holding the dygie bundle (``root`` or its ``model/`` subdir)."""
+    for sub in _BUNDLE_SUBDIRS:
+        candidate = root / sub if sub else root
+        if _looks_like_bundle(candidate):
+            return candidate
+    raise ModelNotFoundError(
+        f"No RadGraphIT model bundle found under {root} (looked in {root} and {root / 'model'}). "
+        f"A bundle must contain {registry.CONFIG_FILENAME} (with an 'encoder' block), "
+        f"{registry.VOCAB_FILENAME}, and a weights file ({' or '.join(registry.WEIGHT_FILENAMES)})."
+    )
+
+
+def _verify(directory: Path) -> ResolvedModel:
+    """Locate a manifest-backed bundle within ``directory`` and validate it completely."""
+    bundle = _locate_bundle(directory)
+    manifest_path = bundle / registry.MANIFEST_FILENAME
+    manifest = ModelManifest.from_path(manifest_path)
+    manifest.check_compatibility(_package_version())
+    manifest.verify_files(bundle)
+    logger.debug("Verified model bundle at %s (revision %s)", bundle, manifest.revision)
+    return ResolvedModel(directory=bundle, manifest=manifest)
+
+
+def resolve_local(path: str | Path) -> ResolvedModel:
+    """Resolve and verify a model bundle in an existing local directory.
+
+    Raises :class:`ModelNotFoundError` if the directory does not exist, and :class:`ManifestError`
+    (via :func:`_verify`) if its required manifest is missing, incompatible, or fails verification.
+    """
+    directory = Path(path).expanduser()
+    if not directory.is_dir():
+        raise ModelNotFoundError(
+            f"Local model directory {directory} does not exist or is not a directory. Point "
+            "RadGraphIT.from_local(...) at a directory containing model_manifest.json, "
+            "config.json, vocab.json and the declared weights file, or at a parent holding them "
+            "under model/."
+        )
+    return _verify(directory)
+
+
+def resolve_pretrained(
+    model_id: str,
+    *,
+    revision: str,
+    cache_dir: str | Path | None = None,
+    local_files_only: bool = False,
+) -> ResolvedModel:
+    """Download (or reuse cached) the model bundle from the Hub and verify it.
+
+    ``model_id`` and ``revision`` must be non-empty. Revisions should be immutable commit SHAs or
+    tags; the package default is pinned to an exact commit.
+
+    The default RadGraphIT model is a **public, ungated** Hub repository, so no authentication is
+    required — anyone can download it with a plain ``pip install``.
+
+    Raises :class:`ModelNotFoundError` if the download fails for any reason (unknown repo, network,
+    offline-with-no-cache, or a repository that is private/gated instead of public).
+    """
+    if not isinstance(model_id, str) or not model_id.strip():
+        raise ModelNotConfiguredError("model_id must be a non-empty Hugging Face repository id.")
+    if not isinstance(revision, str) or not revision.strip():
+        raise ModelNotConfiguredError(
+            "revision must be a non-empty immutable commit SHA or release tag."
+        )
+
+    manifest_locations = (
+        registry.MANIFEST_FILENAME,
+        f"model/{registry.MANIFEST_FILENAME}",
+    )
+    manifest_path: Path | None = None
+    manifest_location: str | None = None
+    manifest_errors: list[str] = []
+    for candidate in manifest_locations:
+        try:
+            downloaded = hf_hub_download(
+                repo_id=model_id,
+                filename=candidate,
+                revision=revision,
+                cache_dir=str(cache_dir) if cache_dir is not None else None,
+                local_files_only=local_files_only,
+            )
+        except Exception as exc:
+            manifest_errors.append(f"{candidate}: {exc}")
+            continue
+        manifest_path = Path(downloaded)
+        manifest_location = candidate
+        break
+    if manifest_path is None or manifest_location is None:
+        details = "; ".join(manifest_errors)
+        raise ModelNotFoundError(
+            f"Could not find {registry.MANIFEST_FILENAME} for model {model_id!r} at revision "
+            f"{revision!r}. A verified manifest is mandatory. Details: {details}"
+        )
+
+    manifest = ModelManifest.from_path(manifest_path)
+    manifest.check_compatibility(_package_version())
+    bundle_prefix = PurePosixPath(manifest_location).parent
+    prefix = "" if str(bundle_prefix) == "." else f"{bundle_prefix.as_posix()}/"
+    allow_patterns = [f"{prefix}{name}" for name in manifest.required_filenames()]
+    try:
+        local_dir = snapshot_download(
+            repo_id=model_id,
+            revision=revision,
+            cache_dir=str(cache_dir) if cache_dir is not None else None,
+            local_files_only=local_files_only,
+            allow_patterns=allow_patterns,
+        )
+    except Exception as exc:
+        raise ModelNotFoundError(
+            f"Could not download model {model_id!r} at revision {revision!r} from the Hugging "
+            f"Face Hub: {exc}. Check the repository id, the revision, your network connection, and "
+            "that the repository is public and ungated."
+        ) from exc
+    return _verify(Path(local_dir))

radgraphit/cli.py

@@ -0,0 +1,131 @@
+"""Command-line interface: ``radgraphit predict``.
+
+The CLI is the one place the package writes to stdout (the library itself never prints). It reads
+one or more reports — from positional arguments, a ``--input-file`` (one report per line), or
+stdin — runs inference, and writes the RadGraph-XL dictionary as JSON to stdout.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from . import __version__
+from .api import RadGraphIT
+from .core.errors import RadGraphITError
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="radgraphit",
+        description="Extract the RadGraph-XL graph from Italian radiology reports.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    predict = subparsers.add_parser("predict", help="Annotate one or more reports.")
+    source = predict.add_mutually_exclusive_group()
+    source.add_argument(
+        "--model-dir",
+        help="Path to a local model bundle (config.json, vocab.json, "
+        "model_manifest.json, weights). Use this for development/offline.",
+    )
+    source.add_argument(
+        "--model-id",
+        help="Hugging Face model repository (standard path). Default: the registry.",
+    )
+    predict.add_argument(
+        "--revision",
+        help="Revision (commit sha or tag) of the Hugging Face repository. Used with --model-id.",
+    )
+    predict.add_argument(
+        "--cache-dir", help="Cache directory for the model download (default: HF cache)."
+    )
+    predict.add_argument(
+        "--device",
+        default="auto",
+        help="Device: auto (default), cpu, cuda, cuda:<index>.",
+    )
+    predict.add_argument(
+        "--input-file",
+        help="Text file with one report per line (alternative to positional arguments).",
+    )
+    predict.add_argument(
+        "--indent", type=int, default=2, help="Indentation of the output JSON (default: 2)."
+    )
+    predict.add_argument(
+        "reports",
+        nargs="*",
+        help="One or more reports as arguments. If absent, reads from --input-file or stdin.",
+    )
+    return parser
+
+
+def _collect_reports(args: argparse.Namespace) -> list[str]:
+    """Gather reports from the single input source validated by :func:`main`."""
+    if args.reports:
+        return list(args.reports)
+    if args.input_file:
+        with Path(args.input_file).open(encoding="utf-8") as handle:
+            return [line.strip() for line in handle if line.strip()]
+    data = sys.stdin.read()
+    return [line.strip() for line in data.splitlines() if line.strip()]
+
+
+def _build_predictor(args: argparse.Namespace) -> RadGraphIT:
+    if args.model_dir:
+        return RadGraphIT.from_local(args.model_dir, device=args.device)
+    kwargs: dict[str, object] = {"device": args.device, "cache_dir": args.cache_dir}
+    if args.model_id:
+        kwargs["model_id"] = args.model_id
+    if args.revision:
+        kwargs["revision"] = args.revision
+    return RadGraphIT.from_pretrained(**kwargs)  # type: ignore[arg-type]
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """CLI entry point. Returns a process exit code."""
+    logging.basicConfig(level=logging.WARNING, format="%(name)s: %(message)s")
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "predict":
+        if args.reports and args.input_file:
+            print(
+                "radgraphit: positional reports and --input-file are mutually exclusive.",
+                file=sys.stderr,
+            )
+            return 2
+        if args.model_dir and (args.revision or args.cache_dir):
+            print(
+                "radgraphit: --revision/--cache-dir cannot be used with --model-dir.",
+                file=sys.stderr,
+            )
+            return 2
+        try:
+            reports = _collect_reports(args)
+            if not reports:
+                print("radgraphit: no report provided.", file=sys.stderr)
+                return 2
+            predictor = _build_predictor(args)
+            annotations = predictor.predict(reports)
+        except RadGraphITError as exc:
+            print(f"radgraphit: {exc}", file=sys.stderr)
+            return 1
+        except (OSError, UnicodeError) as exc:
+            print(f"radgraphit: {exc}", file=sys.stderr)
+            return 1
+        json.dump(annotations, sys.stdout, indent=args.indent, ensure_ascii=False)
+        sys.stdout.write("\n")
+        return 0
+
+    parser.error(f"unknown command {args.command!r}")  # argparse exits; unreachable return below
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

radgraphit/core/__init__.py

@@ -0,0 +1 @@
+"""Core domain: immutable value objects, typed protocols, and the error hierarchy."""