Merge pull request #6 from NCATSTranslator/trapi-2.0

Trapi 2.0

Author: tokebe

README.md

@@ -6,6 +6,37 @@ Models based on Pydantic provide deserialize with basic validation, serialize, a
 
 Allows for easy FastAPI standup.
 
+## TRAPI versions
+
+`translator_tom` provides models for multiple TRAPI versions. When importing directly from `translator_tom`, you automatically import models for the latest version.
+
+```python
+from translator_tom import Response                  # TRAPI 2.0 (latest)
+from translator_tom.model_dicts import ResponseDict  # TRAPI 2.0 (latest)
+```
+
+To pin a specific version, import it from its version subpackage:
+
+```python
+from translator_tom.v2_0 import Response             # TRAPI 2.0
+from translator_tom.v1_6 import Response             # TRAPI 1.6
+from translator_tom.v1_6.model_dicts import ResponseDict
+```
+
+Each version has the same general API: models, model_dicts, diff, semantic validation (WIP). Some items are version-agnostic (Biolink, CURIEs, `TOMBase`, etc.) and shared between the two (`translator_tom.utils`).
+
+### Converting TRAPI versions
+
+The TRAPI 2.0 package provides a utility for converting 1.6 models to 2.0 models:
+
+```python
+from translator_tom import up_version
+
+my_v1_response = ... # Some TRAPI 1.6 response
+
+my_v2_response = up_version(my_v1_response)
+```
+
 ## Model Usage
 
 The main ways you interact with a Model are as follows:
@@ -344,6 +375,15 @@ This returns a list of warnings and errors with clear descriptions and tuples de
 > [!WARNING]
 > This feature is WIP and does not do every bit of semantic validation you might expect.
 
+## Scripts
+
+TOM provides some module-level scripts, for your convenience:
+
+- `tom-parse`: Parse a given JSON into a given TOM model to check that it parses.
+- `tom-validate`: Run semantic validation (WIP) against a given JSON/TOM model.
+- `tom-up-version`: Upgrade a TRAPI 1.6 JSON to TRAPI 2.0.
+- `tom-diff`: Diff two JSONs of a given TOM model.
+
 ## Design Decisions
 
 There are a view caveats to using TOM, listed below:

bench/test_sd.py

@@ -1,15 +1,20 @@
 """Quick serdes benchmark: one file per size bucket, comparing TOM vs reasoner-pydantic.
 
-Streams per-file timings in an aligned format as they complete, then prints a
-summary table across files at the end.
+Runs against `data/example_trapi/<version>/`. Defaults to `1.6` because the pinned
+reasoner-pydantic models TRAPI 1.x; pass `--version 2.0` for TOM-only 2.0 timings
+(the reasoner-pydantic rows are not meaningful there). Streams per-file timings in an
+aligned format as they complete, then prints a summary table across files at the end.
 """
 
 import time
 
 import orjson
 from pydantic import TypeAdapter
 
-from utils import CORPUS_ROOT, read_corpus_file
+from utils import corpus_root, import_version, parse_version, read_corpus_file
+
+VERSION = parse_version(__doc__, default="1.6")
+CORPUS_ROOT = corpus_root(VERSION)
 
 LABEL_WIDTH = 23
 VALUE_FMT = "{:>8.4f}s"
@@ -45,8 +50,7 @@ def section(title: str) -> None:
 # --- Imports ---
 
 t0 = time.perf_counter()
-from translator_tom import Response  # noqa: E402
-
+Response = import_version(VERSION).Response
 t_tom = time.perf_counter() - t0
 
 t0 = time.perf_counter()
@@ -55,7 +59,7 @@ def section(title: str) -> None:
 t_rp = time.perf_counter() - t0
 
 section("Imports")
-print(f"  {'translator_tom':<{LABEL_WIDTH}} {VALUE_FMT.format(t_tom)}")
+print(f"  {f'translator_tom {VERSION}':<{LABEL_WIDTH}} {VALUE_FMT.format(t_tom)}")
 print(f"  {'reasoner-pydantic':<{LABEL_WIDTH}} {VALUE_FMT.format(t_rp)}")
 
 
@@ -103,9 +107,7 @@ def section(title: str) -> None:
     pair_row("adapter.python", t_vp, t_dp, file_results)
 
     # Combined dict-based pipeline (alternative to adapter.json single-pass).
-    pair_row(
-        "orjson + adapter.python", t_loads + t_vp, t_dp + t_dumps, file_results
-    )
+    pair_row("orjson + adapter.python", t_loads + t_vp, t_dp + t_dumps, file_results)
 
     # --- adapter (json: bytes <-> model) ---
     t0 = time.perf_counter()
@@ -154,8 +156,7 @@ def section(title: str) -> None:
 section("Summary (seconds): from / to")
 
 short_labels = {
-    lbl: lbl.split("/")[-1].removesuffix(".gz").removesuffix(".json")
-    for lbl in results
+    lbl: lbl.split("/")[-1].removesuffix(".gz").removesuffix(".json") for lbl in results
 }
 ops = list(next(iter(results.values())).keys())
 

bench/test_sd_tom.py

@@ -1,16 +1,25 @@
 """TOM-only serdes benchmark across every example response.
 
-Walks `data/example_trapi/**` and runs the core (de)serialization paths for
-each file. Streams per-file timings in an aligned format as they complete,
-then prints a summary table across files at the end.
+Walks `data/example_trapi/<version>/**` (default `2.0`; pass `--version 1.6`) and
+runs the core (de)serialization paths for each file. Streams per-file timings in an
+aligned format as they complete, then prints a summary table across files at the end.
 
 For a quicker comparison run that also benches reasoner-pydantic on one file
 per size bucket, see `bench/test_sd.py`.
 """
 
 import time
 
-from utils import CORPUS_ROOT, discover_files, read_corpus_file
+from utils import (
+    corpus_root,
+    discover_files,
+    import_version,
+    parse_version,
+    read_corpus_file,
+)
+
+VERSION = parse_version(__doc__)
+CORPUS_ROOT = corpus_root(VERSION)
 
 LABEL_WIDTH = 10
 VALUE_FMT = "{:>8.4f}s"
@@ -40,12 +49,11 @@ def section(title: str) -> None:
 # --- Import ---
 
 t0 = time.perf_counter()
-from translator_tom import Response  # noqa: E402
-
+Response = import_version(VERSION).Response
 t_tom = time.perf_counter() - t0
 
 section("Imports")
-print(f"  translator_tom Response  {VALUE_FMT.format(t_tom)}")
+print(f"  translator_tom {VERSION} Response  {VALUE_FMT.format(t_tom)}")
 
 
 TEST_FILES = discover_files(CORPUS_ROOT)

bench/test_sd_tom_dicts.py

@@ -1,9 +1,10 @@
 """Dict-util-only serdes benchmark across every example response.
 
-The `model_dicts` twin of `bench/test_sd_tom.py`: same corpus walk and output,
-but driving the `*DictUtil` serdes (raw orjson/ormsgpack over the TypedDict form,
-no model construction) instead of the `Response` model. Run both to see the cost
-the model layer adds over operating on plain dicts.
+The `model_dicts` twin of `bench/test_sd_tom.py`: same corpus walk and output
+(default `2.0`; pass `--version 1.6`), but driving the `*DictUtil` serdes (raw
+orjson/ormsgpack over the TypedDict form, no model construction) instead of the
+`Response` model. Run both to see the cost the model layer adds over operating on
+plain dicts.
 
 The `+val` rows re-run the `from` path with `validate=True`, adding a pydantic
 `TypeAdapter` pass over the parsed data; their `from` timing minus the plain
@@ -12,7 +13,16 @@
 
 import time
 
-from utils import CORPUS_ROOT, discover_files, read_corpus_file
+from utils import (
+    corpus_root,
+    discover_files,
+    import_version,
+    parse_version,
+    read_corpus_file,
+)
+
+VERSION = parse_version(__doc__)
+CORPUS_ROOT = corpus_root(VERSION)
 
 LABEL_WIDTH = 12
 VALUE_FMT = "{:>8.4f}s"
@@ -42,12 +52,13 @@ def section(title: str) -> None:
 # --- Import ---
 
 t0 = time.perf_counter()
-from translator_tom.model_dicts import ResponseDictUtil  # noqa: E402
-
+ResponseDictUtil = import_version(VERSION, "model_dicts").ResponseDictUtil
 t_tom = time.perf_counter() - t0
 
 section("Imports")
-print(f"  model_dicts ResponseDictUtil  {VALUE_FMT.format(t_tom)}")
+print(
+    f"  translator_tom {VERSION} model_dicts ResponseDictUtil  {VALUE_FMT.format(t_tom)}"
+)
 
 
 TEST_FILES = discover_files(CORPUS_ROOT)
@@ -101,8 +112,7 @@ def section(title: str) -> None:
 section("Summary (seconds): from / to")
 
 short_labels = {
-    lbl: lbl.split("/")[-1].removesuffix(".gz").removesuffix(".json")
-    for lbl in results
+    lbl: lbl.split("/")[-1].removesuffix(".gz").removesuffix(".json") for lbl in results
 }
 ops = list(next(iter(results.values())).keys())
 

bench/test_semantic_validation.py

@@ -1,17 +1,26 @@
 """Semantic-validation benchmark across every example response.
 
-Walks `data/example_trapi/**`, deserializes each file, and runs
-`semantic_validate` on the resulting `Response`. Streams per-file timings and
-the error/warning counts as they complete, then prints a summary table across
-files at the end.
+Walks `data/example_trapi/<version>/**` (default `2.0`; pass `--version 1.6`),
+deserializes each file, and runs `semantic_validate` on the resulting `Response`.
+Streams per-file timings and the error/warning counts as they complete, then prints
+a summary table across files at the end.
 
 For the serdes benchmarks see `bench/test_sd_tom.py` (TOM-only, every file) and
 `bench/test_sd.py` (one file per size bucket, TOM vs reasoner-pydantic).
 """
 
 import time
 
-from utils import CORPUS_ROOT, discover_files, read_corpus_file
+from utils import (
+    corpus_root,
+    discover_files,
+    import_version,
+    parse_version,
+    read_corpus_file,
+)
+
+VERSION = parse_version(__doc__)
+CORPUS_ROOT = corpus_root(VERSION)
 
 VALUE_FMT = "{:>8.4f}s"
 
@@ -24,13 +33,14 @@ def section(title: str) -> None:
 # --- Import ---
 
 t0 = time.perf_counter()
-from translator_tom import Response  # noqa: E402
-from translator_tom.validation import semantic_validate  # noqa: E402
-
+_ttom = import_version(VERSION)
+_validation = import_version(VERSION, "validation")
 t_tom = time.perf_counter() - t0
+Response = _ttom.Response
+semantic_validate = _validation.semantic_validate
 
 section("Imports")
-print(f"  translator_tom + validation  {VALUE_FMT.format(t_tom)}")
+print(f"  translator_tom {VERSION} + validation  {VALUE_FMT.format(t_tom)}")
 
 
 TEST_FILES = discover_files(CORPUS_ROOT)