RadGraph-IT 1.0.0__tar.gz

radgraph_it-1.0.0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# Model artifacts / weights / data — MUST NOT be committed.
+# The model bundle (config.json, vocab.json, model_manifest.json, best.pt / model.safetensors)
+# lives on the Hugging Face Hub, never in this repository.
+*.pt
+*.pth
+*.bin
+*.safetensors
+*.tar.gz
+/models/
+/artifacts/
+/data/
+
+# Local caches
+.hf_cache/
+.radgraphit_cache/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

radgraph_it-1.0.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
+adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Changed
+- Pin the model bundle and encoder to immutable Hugging Face commit revisions.
+- Require a checksum-backed manifest for every local and remote model bundle.
+- Download only manifest-declared bundle files and construct the encoder without redundant
+  pretrained-weight downloads.
+
+### Fixed
+- Harden manifest paths, checksums, schema/version parsing, and encoder consistency checks.
+- Normalize checkpoint, vocabulary, I/O, and inference failures into the public error hierarchy.
+- Run the real pinned checkpoint against a committed synthetic golden output in CI.
+- Align pre-commit, Python 3.13 coverage, CLI input validation, and documented cache size.
+
+## [1.0.0]
+
+First public release.
+
+### Added
+- Public Python API `radgraphit.RadGraphIT`: `from_pretrained()` (Hugging Face Hub),
+  `from_local()` (local bundle), and direct lazy construction; `predict()` accepts a string or a
+  sequence of strings and preserves input order; `predictor(...)` is an alias of `predict()`.
+- Output in the canonical **RadGraph-XL** dictionary format: stable entity ordering, deterministic
+  relation ordering, no dangling edges.
+- Italian RadGraph-XL compatibility tokenizer (exact equivalent of
+  `radgraph_xl_preprocess_report`).
+- `dygie_v2` inference backend: pure-PyTorch port of the Italian v2 model (shared encoder, span
+  extractor, NER head, relation head), on CPU or CUDA.
+- Automatic anonymous model download from the public Hugging Face Hub repository
+  (`radgraphIT/Radgraph-IT-v1`), cached after the first use.
+- CLI `radgraphit predict`: reports as arguments, from `--input-file` (one per line), or from
+  stdin; JSON output on stdout.

radgraph_it-1.0.0/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Daniel Rabottini (therabo)
+Copyright (c) 2026 Edoardo Avenia (edoardoavenia)
+Copyright (c) 2026 Rocco Angelella (roccoangelella)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

radgraph_it-1.0.0/LICENSES/Third-Party.md

@@ -0,0 +1,41 @@
+# Third-Party
+
+This file collects provenance and attributions. It does **not** declare weights, datasets, or
+clinical texts redistributable, and it does **not** automatically copy any third-party license. The
+package code itself is licensed under MIT (see the root `LICENSE` file); this file concerns the
+third-party components it builds on.
+
+## RadGraph-XL output format and serializer
+
+The output dictionary and the serialization logic (`postprocess_reports` / `get_entity`) derive from
+the official **RadGraph / RadGraph-XL** package from Stanford AIMI / StanfordMIMI.
+
+- Upstream repository: `radgraph` package (Stanford), distributed under the MIT license.
+
+Citation:
+
+> Delbrouck et al. "RadGraph-XL: A Large-Scale Expert-Annotated Dataset for Entity and Relation
+> Extraction from Radiology Reports." Findings of the ACL 2024, pp. 12902–12915.
+> https://aclanthology.org/2024.findings-acl.765
+
+## Inference backend (`dygie_v2`)
+
+An inference-only PyTorch port of the Italian v2 model (internal project "RadGraph-XL-IT",
+`training_v2`), which is itself a pure-PyTorch reimplementation of the DyGIE++ architecture
+(NER + relations) without AllenNLP.
+
+- DyGIE / DyGIE++ architecture: Wadden et al., "Entity, Relation, and Event Extraction with
+  Contextualized Span Representations", EMNLP 2019.
+- Pre-trained encoder: fetched at runtime from the Hugging Face Hub (e.g. `IVN-RIN/medBIT-r3-plus`);
+  subject to the license of its own repository on the Hub. Not redistributed by this package.
+
+## Model, weights, and data
+
+The model weights, the datasets, and any clinical text are **not** included in this repository or in
+the wheel/sdist, and are not declared redistributable. The model bundle is hosted separately on the
+Hugging Face Hub and is subject to the licenses/terms declared in that repository.
+
+## Runtime dependencies
+
+`torch`, `transformers`, `nltk`, `huggingface_hub` are subject to their respective licenses
+(BSD-3-Clause, Apache-2.0, Apache-2.0, Apache-2.0 respectively, unless changed upstream).

radgraph_it-1.0.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: RadGraph-IT
+Version: 1.0.0
+Summary: RadGraph graph inference for Italian radiology reports, with output in the canonical RadGraph-XL format.
+Project-URL: Homepage, https://github.com/therabo/RadGraph-IT
+Project-URL: Repository, https://github.com/therabo/RadGraph-IT
+Project-URL: Issues, https://github.com/therabo/RadGraph-IT/issues
+Project-URL: Changelog, https://github.com/therabo/RadGraph-IT/blob/main/CHANGELOG.md
+Author: Daniel Rabottini, Edoardo Avenia, Rocco Angelella
+License-Expression: MIT
+License-File: LICENSE
+License-File: LICENSES/Third-Party.md
+Keywords: information-extraction,italian,nlp,radgraph,radiology
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: Italian
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: huggingface-hub>=0.23
+Requires-Dist: nltk>=3.8
+Requires-Dist: packaging>=23
+Requires-Dist: torch>=2.1
+Requires-Dist: transformers>=4.39
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pre-commit>=3.5; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff==0.16.0; extra == 'dev'
+Requires-Dist: safetensors>=0.4; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Provides-Extra: safetensors
+Requires-Dist: safetensors>=0.4; extra == 'safetensors'
+Description-Content-Type: text/markdown
+
+# RadGraph-IT 🇮🇹
+
+**RadGraph** graph inference for **Italian** radiology reports, with output in the canonical
+**RadGraph-XL** format.
+
+`radgraphit` takes one or more Italian radiology reports, runs the Italian DyGIE v2 model
+(PyTorch: shared encoder, span extractor, NER head, and relation head), and returns the graph of
+entities and relations as the RadGraph-XL-compatible dictionary.
+
+- **Package / import / CLI name:** `radgraphit` · **Python:** `>= 3.10` · **Device:** CPU or CUDA
+- **Model:** downloaded automatically from pinned Hugging Face revisions on first use
+  (~445 MB / 424 MiB plus small tokenizer/config files, then cached)
+
+## Installation
+
+```bash
+pip install radgraphit
+```
+
+## Usage — Python API
+
+```python
+from radgraphit import RadGraphIT
+
+predictor = RadGraphIT()
+annotations = predictor.predict(
+    "Non si evidenziano segni di pneumotorace dopo la rimozione del drenaggio toracico."
+)
+```
+
+`predict` accepts a **string** or a **sequence of strings** and preserves order.
+`predictor(report)` is an alias for `predictor.predict(report)`:
+
+```python
+annotations = predictor(["referto 1", "referto 2"])  # batch, order preserved
+```
+
+## Usage — CLI
+
+```bash
+# report as an argument
+radgraphit predict "Non si evidenzia pneumotorace."
+
+# from a file (one report per line), or from stdin
+radgraphit predict --input-file reports.txt
+echo "Nessuna evidenza di pneumotorace." | radgraphit predict
+```
+
+The result is written as JSON to stdout.
+
+## Output
+
+For the input `["Non si evidenzia pneumotorace ..."]` the output has this shape (top-level keys
+`"0"`, `"1"`, … in input order):
+
+```python
+{
+    "0": {
+        "text": "<normalized tokens, space-separated>",
+        "entities": {
+            "1": {
+                "tokens": "<span tokens>",
+                "label": "Observation::definitely absent",
+                "start_ix": 3,
+                "end_ix": 3,
+                "relations": [["located_at", "2"]],
+            }
+        },
+        "data_source": None,
+        "data_split": "inference",
+    },
+    "1": {"...": "..."},
+}
+```
+
+- The indices (`start_ix`, `end_ix`) are **token-level, zero-based, and inclusive**.
+- Relations are directed *source → target* lists `[label, target_entity_id]`.
+- The output is deterministic: entities and relations are stably ordered.
+
+## Citation
+
+The output format and the serializer derive from the official **RadGraph / RadGraph-XL** package
+(see [`Third-Party`](LICENSES/Third-Party.md)). If you use this package, please cite
+both this work and the RadGraph-XL paper:
+
+```bibtex
+@software{radgraphit,
+    author = "Daniel Rabottini and Edoardo Avenia and Rocco Angelella",
+    title = "{RadGraph-IT}: {RadGraph} graph inference for {Italian} radiology reports",
+    year = "2026",
+    version = "1.0.0",
+    url = "https://github.com/therabo/RadGraph-IT",
+}
+```
+
+```bibtex
+@inproceedings{delbrouck-etal-2024-radgraph,
+    title = "{R}ad{G}raph-{XL}: A Large-Scale Expert-Annotated Dataset for Entity and Relation
+             Extraction from Radiology Reports",
+    author = "Delbrouck, Jean-Benoit and Chambon, Pierre and Chen, Zhihong and Varma, Maya and
+              Johnston, Andrew and Blankemeier, Louis and Van Veen, Dave and Bui, Tan and
+              Truong, Steven and Langlotz, Curtis",
+    booktitle = "Findings of the Association for Computational Linguistics ACL 2024",
+    year = "2024",
+    url = "https://aclanthology.org/2024.findings-acl.765",
+    pages = "12902--12915",
+}
+```
+
+## License
+
+See the [`MIT License`](LICENSE) and [`Third-Party`](LICENSES/Third-Party.md) notices.
+
+> **Not a medical device.** The output is an automatic extraction of entities and relations from
+> text and does not constitute a diagnosis, a report, or a clinical opinion.

radgraph_it-1.0.0/README.md

@@ -0,0 +1,115 @@
+# RadGraph-IT 🇮🇹
+
+**RadGraph** graph inference for **Italian** radiology reports, with output in the canonical
+**RadGraph-XL** format.
+
+`radgraphit` takes one or more Italian radiology reports, runs the Italian DyGIE v2 model
+(PyTorch: shared encoder, span extractor, NER head, and relation head), and returns the graph of
+entities and relations as the RadGraph-XL-compatible dictionary.
+
+- **Package / import / CLI name:** `radgraphit` · **Python:** `>= 3.10` · **Device:** CPU or CUDA
+- **Model:** downloaded automatically from pinned Hugging Face revisions on first use
+  (~445 MB / 424 MiB plus small tokenizer/config files, then cached)
+
+## Installation
+
+```bash
+pip install radgraphit
+```
+
+## Usage — Python API
+
+```python
+from radgraphit import RadGraphIT
+
+predictor = RadGraphIT()
+annotations = predictor.predict(
+    "Non si evidenziano segni di pneumotorace dopo la rimozione del drenaggio toracico."
+)
+```
+
+`predict` accepts a **string** or a **sequence of strings** and preserves order.
+`predictor(report)` is an alias for `predictor.predict(report)`:
+
+```python
+annotations = predictor(["referto 1", "referto 2"])  # batch, order preserved
+```
+
+## Usage — CLI
+
+```bash
+# report as an argument
+radgraphit predict "Non si evidenzia pneumotorace."
+
+# from a file (one report per line), or from stdin
+radgraphit predict --input-file reports.txt
+echo "Nessuna evidenza di pneumotorace." | radgraphit predict
+```
+
+The result is written as JSON to stdout.
+
+## Output
+
+For the input `["Non si evidenzia pneumotorace ..."]` the output has this shape (top-level keys
+`"0"`, `"1"`, … in input order):
+
+```python
+{
+    "0": {
+        "text": "<normalized tokens, space-separated>",
+        "entities": {
+            "1": {
+                "tokens": "<span tokens>",
+                "label": "Observation::definitely absent",
+                "start_ix": 3,
+                "end_ix": 3,
+                "relations": [["located_at", "2"]],
+            }
+        },
+        "data_source": None,
+        "data_split": "inference",
+    },
+    "1": {"...": "..."},
+}
+```
+
+- The indices (`start_ix`, `end_ix`) are **token-level, zero-based, and inclusive**.
+- Relations are directed *source → target* lists `[label, target_entity_id]`.
+- The output is deterministic: entities and relations are stably ordered.
+
+## Citation
+
+The output format and the serializer derive from the official **RadGraph / RadGraph-XL** package
+(see [`Third-Party`](LICENSES/Third-Party.md)). If you use this package, please cite
+both this work and the RadGraph-XL paper:
+
+```bibtex
+@software{radgraphit,
+    author = "Daniel Rabottini and Edoardo Avenia and Rocco Angelella",
+    title = "{RadGraph-IT}: {RadGraph} graph inference for {Italian} radiology reports",
+    year = "2026",
+    version = "1.0.0",
+    url = "https://github.com/therabo/RadGraph-IT",
+}
+```
+
+```bibtex
+@inproceedings{delbrouck-etal-2024-radgraph,
+    title = "{R}ad{G}raph-{XL}: A Large-Scale Expert-Annotated Dataset for Entity and Relation
+             Extraction from Radiology Reports",
+    author = "Delbrouck, Jean-Benoit and Chambon, Pierre and Chen, Zhihong and Varma, Maya and
+              Johnston, Andrew and Blankemeier, Louis and Van Veen, Dave and Bui, Tan and
+              Truong, Steven and Langlotz, Curtis",
+    booktitle = "Findings of the Association for Computational Linguistics ACL 2024",
+    year = "2024",
+    url = "https://aclanthology.org/2024.findings-acl.765",
+    pages = "12902--12915",
+}
+```
+
+## License
+
+See the [`MIT License`](LICENSE) and [`Third-Party`](LICENSES/Third-Party.md) notices.
+
+> **Not a medical device.** The output is an automatic extraction of entities and relations from
+> text and does not constitute a diagnosis, a report, or a clinical opinion.

radgraph_it-1.0.0/pyproject.toml

@@ -0,0 +1,146 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "RadGraph-IT"
+version = "1.0.0"
+description = "RadGraph graph inference for Italian radiology reports, with output in the canonical RadGraph-XL format."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE", "LICENSES/Third-Party.md"]
+authors = [
+    { name = "Daniel Rabottini" },
+    { name = "Edoardo Avenia" },
+    { name = "Rocco Angelella" },
+]
+keywords = [
+    "radiology",
+    "nlp",
+    "information-extraction",
+    "radgraph",
+    "italian",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Healthcare Industry",
+    "Natural Language :: Italian",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+    # License is declared via the SPDX 'license' field (PEP 639); no legacy "License ::" classifier.
+]
+
+# Minimal runtime footprint: the encoder backend (torch + transformers), the compatibility
+# tokenizer (nltk), and the standard model download path (huggingface_hub). Nothing else.
+dependencies = [
+    "torch>=2.1",
+    "transformers>=4.39",
+    "nltk>=3.8",
+    "huggingface_hub>=0.23",
+    "packaging>=23",
+]
+
+[project.optional-dependencies]
+# Safer future weight format; the current v2 checkpoint is a .pt.
+safetensors = ["safetensors>=0.4"]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "ruff==0.16.0",
+    "mypy>=1.11",
+    "build>=1.2",
+    "twine>=5",
+    "safetensors>=0.4",
+    "pre-commit>=3.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/therabo/RadGraph-IT"
+Repository = "https://github.com/therabo/RadGraph-IT"
+Issues = "https://github.com/therabo/RadGraph-IT/issues"
+Changelog = "https://github.com/therabo/RadGraph-IT/blob/main/CHANGELOG.md"
+
+[project.scripts]
+radgraphit = "radgraphit.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/radgraphit"]
+
+[tool.hatch.build.targets.sdist]
+# Keep the distribution lean: ship the package, notices, changelog, and maintainer manifest tool.
+# Never ship weights, datasets, or clinical text (there are none in the tree anyway).
+include = [
+    "src/radgraphit",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSES",
+    "scripts/publish_model.py",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "C4", "SIM", "PTH", "RUF"]
+ignore = [
+    "B008",  # function call in default argument — intentional for registry defaults
+]
+
+[tool.ruff.lint.per-file-ignores]
+"src/radgraphit/inference/backends/dygie_v2/*" = ["N812"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["radgraphit"]
+
+[tool.mypy]
+# Assume 3.12 so mypy can parse the installed third-party stubs (numpy, pulled in via torch, ships
+# PEP 695 `type` statements that don't parse under a 3.10 target). The real >=3.10 floor is enforced
+# by ruff (target-version = "py310") and by the CI test matrix (3.10/3.11/3.12).
+python_version = "3.12"
+strict = true
+warn_unused_configs = true
+files = ["src/radgraphit"]
+# torch/transformers/nltk/huggingface_hub ship incomplete or no stubs; don't fail typecheck on
+# their missing type information (our own code stays fully typed).
+[[tool.mypy.overrides]]
+module = [
+    "transformers.*",
+    "nltk.*",
+    "huggingface_hub.*",
+    "safetensors.*",
+]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+# The vendored/adapted DyGIE-v2 backend is a faithful port of upstream PyTorch modules; hold it
+# to import-time typing but relax the strictest rules that fight idiomatic nn.Module code.
+module = ["radgraphit.inference.backends.dygie_v2.*"]
+disallow_any_generics = false
+warn_return_any = false
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = "-ra"
+markers = [
+    "integration: opt-in tests that require a real v2 checkpoint (see RADGRAPHIT_TEST_MODEL_DIR).",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["radgraphit"]
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true