decimer 2.8.0__tar.gz → 2.8.1__tar.gz

{decimer-2.8.0 → decimer-2.8.1}/DECIMER/__init__.py

@@ -17,15 +17,22 @@ Typical usage example::
     SMILES = predict_SMILES(image_path)
     print(SMILES)
 
+Importing DECIMER does not download or load any model. The models are downloaded
+(if they are missing) and loaded when predict_SMILES() is first called, or earlier
+by calling ``load_models()``. They are stored in ``$PYSTOW_HOME/DECIMER-V2/``
+(``~/.data/DECIMER-V2/`` by default); a directory that already holds them is used
+without any network access.
+
 For comments, bug reports, or feature ideas,
 please raise an issue on the GitHub repository.
 """
 
-__version__ = "2.7.2"
+__version__ = "2.8.1"
 
 __all__ = [
     "DECIMER",
 ]
 
 
+from .decimer import load_models
 from .decimer import predict_SMILES

{decimer-2.8.0 → decimer-2.8.1}/DECIMER/decimer.py

@@ -2,6 +2,7 @@ import logging
 import os
 import pickle
 import sys
+import threading
 from typing import List
 from typing import Tuple
 
@@ -68,20 +69,34 @@ gpus = tf.config.experimental.list_physical_devices("GPU")
 for gpu in gpus:
     tf.config.experimental.set_memory_growth(gpu, True)
 
-# Set path
-default_path = pystow.join("DECIMER-V2")
-
+# The models are NOT downloaded or loaded when this module is imported. They are
+# downloaded (if missing) and loaded the first time they are needed, either by the
+# first predict_SMILES() call or by an explicit load_models(), and cached afterwards.
+# They live in $PYSTOW_HOME/DECIMER-V2/ (PYSTOW_HOME defaults to ~/.data), read when
+# the models are first needed. A directory that already holds them is used as it is,
+# without any network access.
 model_urls = {
     "DECIMER": "https://zenodo.org/record/8300489/files/models.zip",
     "DECIMER_HandDrawn": "https://zenodo.org/records/10781330/files/DECIMER_HandDrawn_model.zip",
 }
 
 
+def _get_default_path():
+    """Directory that holds (or will hold) the downloaded models.
+
+    Looked up when the models are first needed, so that PYSTOW_HOME can still be set
+    after DECIMER was imported. Nothing is created here.
+    """
+    return pystow.join("DECIMER-V2", ensure_exists=False)
+
+
 def get_models(model_urls: dict):
     """Download and load models from the provided URLs.
 
     This function downloads models from the provided URLs to a default location,
-    then loads tokenizers and TensorFlow saved models.
+    then loads tokenizers and TensorFlow saved models. It loads everything at once
+    and does not touch the cached models of predict_SMILES(); most callers want
+    load_models() instead.
 
     Args:
         model_urls (dict): A dictionary containing model names as keys and their corresponding URLs as values.
@@ -93,7 +108,9 @@ def get_models(model_urls: dict):
             - DECIMER_Hand_drawn (tf.saved_model): TensorFlow saved model for DECIMER HandDrawn.
     """
     # Download models to a default location
-    model_paths = utils.ensure_models(default_path=default_path, model_urls=model_urls)
+    model_paths = utils.ensure_models(
+        default_path=_get_default_path(), model_urls=model_urls
+    )
 
     # Load tokenizers
     tokenizer_path = os.path.join(
@@ -108,7 +125,86 @@ def get_models(model_urls: dict):
     return tokenizer, DECIMER_V2, DECIMER_Hand_drawn
 
 
-tokenizer, DECIMER_V2, DECIMER_Hand_drawn = get_models(model_urls)
+def _load_tokenizer():
+    """Ensure the printed-structure model files are present and load its tokenizer.
+
+    The tokenizer of the printed-structure model decodes the output of both models.
+    """
+    model_paths = utils.ensure_models(
+        default_path=_get_default_path(),
+        model_urls={"DECIMER": model_urls["DECIMER"]},
+    )
+    return load_tokenizer(
+        os.path.join(model_paths["DECIMER"], "assets", "tokenizer_SMILES.pkl")
+    )
+
+
+def _load_saved_model(model_name: str):
+    """Ensure the files of one model are present, then load its SavedModel."""
+    model_paths = utils.ensure_models(
+        default_path=_get_default_path(),
+        model_urls={model_name: model_urls[model_name]},
+    )
+    return tf.saved_model.load(model_paths[model_name])
+
+
+# Module-level names that are filled on first use. Once loaded, an object is stored
+# in this module's globals under the same name that decimer 2.8.0 and older bound at
+# import, so `from DECIMER.decimer import tokenizer, DECIMER_V2` keeps working.
+_lazy_loaders = {
+    "tokenizer": _load_tokenizer,
+    "DECIMER_V2": lambda: _load_saved_model("DECIMER"),
+    "DECIMER_Hand_drawn": lambda: _load_saved_model("DECIMER_HandDrawn"),
+}
+_load_lock = threading.RLock()
+
+
+def _lazy(name: str):
+    """Return tokenizer, DECIMER_V2 or DECIMER_Hand_drawn, loading it on first use.
+
+    Downloads the files first if they are missing. The lock makes concurrent first
+    calls download and load once. A failed download or load is not cached, so the
+    next call tries again.
+    """
+    try:
+        return globals()[name]
+    except KeyError:
+        pass
+    with _load_lock:
+        if name not in globals():
+            globals()[name] = _lazy_loaders[name]()
+        return globals()[name]
+
+
+def __getattr__(name: str):
+    """Load tokenizer, DECIMER_V2 and DECIMER_Hand_drawn on first attribute access."""
+    if name == "default_path":
+        return _get_default_path()
+    if name in _lazy_loaders:
+        return _lazy(name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def load_models(printed: bool = True, hand_drawn: bool = False) -> None:
+    """Download (if missing) and load the models now, instead of at the first prediction.
+
+    Call this once at start-up if the first predict_SMILES() call should not pay for
+    the download and the loading, for example in a server or when building an image.
+    Models that are already loaded are not loaded again. The tokenizer, which both
+    models need, is always loaded.
+
+    Args:
+        printed (bool): Load the model for printed chemical structures (the default
+            model of predict_SMILES).
+        hand_drawn (bool): Also load the hand-drawn model. load_models(hand_drawn=True)
+            loads everything that decimer 2.8.0 and older loaded on import.
+    """
+    with _load_lock:
+        _lazy("tokenizer")
+        if printed:
+            _lazy("DECIMER_V2")
+        if hand_drawn:
+            _lazy("DECIMER_Hand_drawn")
 
 
 def detokenize_output(predicted_array: int) -> str:
@@ -121,7 +217,8 @@ def detokenize_output(predicted_array: int) -> str:
     Returns:
         (str): SMILES representation of the molecule
     """
-    outputs = [tokenizer.index_word[i] for i in predicted_array[0].numpy()]
+    index_word = _lazy("tokenizer").index_word
+    outputs = [index_word[i] for i in predicted_array[0].numpy()]
     prediction = (
         "".join([str(elem) for elem in outputs])
         .replace("<start>", "")
@@ -145,9 +242,10 @@ def detokenize_output_add_confidence(
     Returns:
         str: SMILES string
     """
+    index_word = _lazy("tokenizer").index_word
     prediction_with_confidence = [
         (
-            tokenizer.index_word[predicted_array[0].numpy()[i]],
+            index_word[predicted_array[0].numpy()[i]],
             confidence_array[i].numpy(),
         )
         for i in range(len(confidence_array))
@@ -177,7 +275,10 @@ def predict_SMILES(
     """
     chemical_structure = pre_process.decode_image(image_input)
 
-    model = DECIMER_Hand_drawn if hand_drawn else DECIMER_V2
+    # The first call downloads the models that are missing and loads the ones it needs
+    # (the tokenizer, and the printed or the hand-drawn model); later calls reuse them.
+    _lazy("tokenizer")
+    model = _lazy("DECIMER_Hand_drawn" if hand_drawn else "DECIMER_V2")
     predicted_tokens, confidence_values = model(tf.constant(chemical_structure))
 
     predicted_SMILES = utils.decoder(detokenize_output(predicted_tokens))

{decimer-2.8.0 → decimer-2.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: decimer
-Version: 2.8.0
+Version: 2.8.1
 Summary: DECIMER 2.7.2: Deep Learning for Chemical Image Recognition using Efficient-Net V2 + Transformer
 Home-page: https://github.com/Kohulan/DECIMER-Image_Transformer
 Author: Kohulan Rajan
@@ -139,6 +139,34 @@ SMILES = predict_SMILES(image_path)
 print(f"🎉 Decoded SMILES: {SMILES}")
 ```
 
+### 📥 Models: downloaded on first use
+
+`import DECIMER` does not download or load anything. The model weights are not part of the pip package; they are
+downloaded from Zenodo the first time they are needed and cached afterwards:
+
+- The first `predict_SMILES(...)` call downloads the printed-structure model (about 300 MB) if it is missing, loads
+  it, and keeps it in memory. Later calls reuse it.
+- The hand-drawn model is only downloaded and loaded by the first `predict_SMILES(..., hand_drawn=True)` call.
+  (Up to version 2.8.0 both models were downloaded and loaded when DECIMER was imported.)
+- To pay for the download and the loading at a time of your choosing (at the start of a server, or when building an
+  image), call `load_models()` once. `load_models(hand_drawn=True)` loads both models, as `import DECIMER` did before.
+
+```python
+import DECIMER
+
+DECIMER.load_models()  # optional: download if missing and load now
+SMILES = DECIMER.predict_SMILES("path/to/your/chemical/masterpiece.jpg")
+```
+
+The models are stored in `$PYSTOW_HOME/DECIMER-V2/` (`~/.data/DECIMER-V2/` by default), where `PYSTOW_HOME` is
+read when the models are first needed. A directory that already holds `DECIMER_model/` (and, for hand-drawn
+structures, `DECIMER_HandDrawn_model/`) is used as it is, without any network access, so an image with
+pre-installed models works offline:
+
+```bash
+export PYSTOW_HOME=/opt/decimer-models   # contains DECIMER-V2/DECIMER_model/saved_model.pb, ...
+```
+
 ---
 
 ## ✍️ DECIMER - Hand-drawn Model

{decimer-2.8.0 → decimer-2.8.1}/README.md

@@ -98,6 +98,34 @@ SMILES = predict_SMILES(image_path)
 print(f"🎉 Decoded SMILES: {SMILES}")
 ```
 
+### 📥 Models: downloaded on first use
+
+`import DECIMER` does not download or load anything. The model weights are not part of the pip package; they are
+downloaded from Zenodo the first time they are needed and cached afterwards:
+
+- The first `predict_SMILES(...)` call downloads the printed-structure model (about 300 MB) if it is missing, loads
+  it, and keeps it in memory. Later calls reuse it.
+- The hand-drawn model is only downloaded and loaded by the first `predict_SMILES(..., hand_drawn=True)` call.
+  (Up to version 2.8.0 both models were downloaded and loaded when DECIMER was imported.)
+- To pay for the download and the loading at a time of your choosing (at the start of a server, or when building an
+  image), call `load_models()` once. `load_models(hand_drawn=True)` loads both models, as `import DECIMER` did before.
+
+```python
+import DECIMER
+
+DECIMER.load_models()  # optional: download if missing and load now
+SMILES = DECIMER.predict_SMILES("path/to/your/chemical/masterpiece.jpg")
+```
+
+The models are stored in `$PYSTOW_HOME/DECIMER-V2/` (`~/.data/DECIMER-V2/` by default), where `PYSTOW_HOME` is
+read when the models are first needed. A directory that already holds `DECIMER_model/` (and, for hand-drawn
+structures, `DECIMER_HandDrawn_model/`) is used as it is, without any network access, so an image with
+pre-installed models works offline:
+
+```bash
+export PYSTOW_HOME=/opt/decimer-models   # contains DECIMER-V2/DECIMER_model/saved_model.pb, ...
+```
+
 ---
 
 ## ✍️ DECIMER - Hand-drawn Model

{decimer-2.8.0 → decimer-2.8.1}/decimer.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: decimer
-Version: 2.8.0
+Version: 2.8.1
 Summary: DECIMER 2.7.2: Deep Learning for Chemical Image Recognition using Efficient-Net V2 + Transformer
 Home-page: https://github.com/Kohulan/DECIMER-Image_Transformer
 Author: Kohulan Rajan
@@ -139,6 +139,34 @@ SMILES = predict_SMILES(image_path)
 print(f"🎉 Decoded SMILES: {SMILES}")
 ```
 
+### 📥 Models: downloaded on first use
+
+`import DECIMER` does not download or load anything. The model weights are not part of the pip package; they are
+downloaded from Zenodo the first time they are needed and cached afterwards:
+
+- The first `predict_SMILES(...)` call downloads the printed-structure model (about 300 MB) if it is missing, loads
+  it, and keeps it in memory. Later calls reuse it.
+- The hand-drawn model is only downloaded and loaded by the first `predict_SMILES(..., hand_drawn=True)` call.
+  (Up to version 2.8.0 both models were downloaded and loaded when DECIMER was imported.)
+- To pay for the download and the loading at a time of your choosing (at the start of a server, or when building an
+  image), call `load_models()` once. `load_models(hand_drawn=True)` loads both models, as `import DECIMER` did before.
+
+```python
+import DECIMER
+
+DECIMER.load_models()  # optional: download if missing and load now
+SMILES = DECIMER.predict_SMILES("path/to/your/chemical/masterpiece.jpg")
+```
+
+The models are stored in `$PYSTOW_HOME/DECIMER-V2/` (`~/.data/DECIMER-V2/` by default), where `PYSTOW_HOME` is
+read when the models are first needed. A directory that already holds `DECIMER_model/` (and, for hand-drawn
+structures, `DECIMER_HandDrawn_model/`) is used as it is, without any network access, so an image with
+pre-installed models works offline:
+
+```bash
+export PYSTOW_HOME=/opt/decimer-models   # contains DECIMER-V2/DECIMER_model/saved_model.pb, ...
+```
+
 ---
 
 ## ✍️ DECIMER - Hand-drawn Model

{decimer-2.8.0 → decimer-2.8.1}/decimer.egg-info/SOURCES.txt

@@ -24,4 +24,5 @@ decimer.egg-info/dependency_links.txt
 decimer.egg-info/entry_points.txt
 decimer.egg-info/requires.txt
 decimer.egg-info/top_level.txt
-tests/test_functions.py
+tests/test_functions.py
+tests/test_lazy_models.py

{decimer-2.8.0 → decimer-2.8.1}/setup.py

@@ -15,7 +15,7 @@ with open("README.md", "r") as fh:
 
 setuptools.setup(
     name="decimer",
-    version="2.8.0",
+    version="2.8.1",
     author="Kohulan Rajan",
     author_email="kohulan.rajan@uni-jena.de",
     maintainer="Kohulan Rajan, Otto Brinkhaus ",

decimer-2.8.1/tests/test_lazy_models.py

@@ -0,0 +1,317 @@
+"""Tests for downloading and loading the models on first use instead of at import.
+
+None of these tests needs the network or the real model files: the download function
+and ``tf.saved_model.load`` are replaced by recorders, and the weights are tiny
+placeholder files.
+"""
+import os
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+import tensorflow as tf
+
+import DECIMER.decimer as decimer_module
+import DECIMER.utils as utils
+from DECIMER import load_models
+from DECIMER import predict_SMILES
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+IMAGE = str(Path(__file__).resolve().parent / "caffeine.png")
+LAZY_NAMES = ("tokenizer", "DECIMER_V2", "DECIMER_Hand_drawn")
+
+# The model directory names in the Zenodo zip files, by download URL.
+PRINTED_URL = decimer_module.model_urls["DECIMER"]
+HAND_DRAWN_URL = decimer_module.model_urls["DECIMER_HandDrawn"]
+DIRECTORY_OF_URL = {
+    PRINTED_URL: "DECIMER_model",
+    HAND_DRAWN_URL: "DECIMER_HandDrawn_model",
+}
+
+
+def write_model_files(models_dir, model_directory):
+    """Write the placeholder files that count as an installed model."""
+    directory = Path(models_dir) / model_directory
+    (directory / "assets").mkdir(parents=True, exist_ok=True)
+    (directory / "saved_model.pb").write_bytes(b"placeholder")
+    (directory / "assets" / "tokenizer_SMILES.pkl").write_bytes(b"placeholder")
+
+
+class FakeModel:
+    """Stands in for a loaded SavedModel: <start> C O <end>, confidence 0.9 each."""
+
+    def __init__(self, path):
+        self.path = path
+
+    def __call__(self, image):
+        return tf.constant([[1, 2, 3, 4]]), tf.constant([0.9, 0.9, 0.9, 0.9])
+
+
+@pytest.fixture
+def recorded(tmp_path, monkeypatch):
+    """An empty model directory, and recorders for everything that would download or load."""
+    home = tmp_path / "pystow-home"
+    monkeypatch.setenv("PYSTOW_HOME", str(home))
+    record = SimpleNamespace(
+        home=home,
+        models_dir=home / "DECIMER-V2",
+        downloads=[],
+        loads=[],
+        tokenizer_paths=[],
+        download_delay=0.0,
+        download_error=None,
+    )
+
+    def fake_download(model_url, model_path, verbose=1):
+        record.downloads.append(model_url)
+        time.sleep(record.download_delay)
+        if record.download_error is not None:
+            raise record.download_error
+        write_model_files(model_path, DIRECTORY_OF_URL[model_url])
+
+    def fake_saved_model_load(path, *args, **kwargs):
+        record.loads.append(os.path.basename(path))
+        return FakeModel(path)
+
+    def fake_load_tokenizer(path):
+        record.tokenizer_paths.append(path)
+        return SimpleNamespace(index_word={1: "<start>", 2: "C", 3: "O", 4: "<end>"})
+
+    monkeypatch.setattr(utils, "download_trained_weights", fake_download)
+    monkeypatch.setattr(tf.saved_model, "load", fake_saved_model_load)
+    monkeypatch.setattr(decimer_module, "load_tokenizer", fake_load_tokenizer)
+
+    def forget_loaded_models():
+        for name in LAZY_NAMES:
+            vars(decimer_module).pop(name, None)
+
+    forget_loaded_models()
+    yield record
+    forget_loaded_models()
+
+
+def test_import_does_no_network_and_loads_no_model(tmp_path):
+    """`import DECIMER` in a fresh interpreter: no network, no model, no files."""
+    home = tmp_path / "pystow-home"
+    script = """
+import os
+import pathlib
+import socket
+
+
+def refuse(*args, **kwargs):
+    raise AssertionError("network access while importing DECIMER")
+
+
+socket.socket.connect = refuse
+socket.create_connection = refuse
+socket.getaddrinfo = refuse
+
+import tensorflow as tf
+
+
+def refuse_load(*args, **kwargs):
+    raise AssertionError("tf.saved_model.load called while importing DECIMER")
+
+
+tf.saved_model.load = refuse_load
+
+import DECIMER
+import DECIMER.decimer as decimer_module
+
+for name in ("tokenizer", "DECIMER_V2", "DECIMER_Hand_drawn"):
+    assert name not in vars(decimer_module), name
+home = pathlib.Path(os.environ["PYSTOW_HOME"])
+assert not (home / "DECIMER-V2").exists()
+assert not list(home.rglob("saved_model.pb"))
+print("import-is-passive")
+"""
+    env = dict(os.environ)
+    env["PYSTOW_HOME"] = str(home)
+    env["PYTHONPATH"] = str(REPO_ROOT)
+    env["TF_CPP_MIN_LOG_LEVEL"] = "3"
+    result = subprocess.run(
+        [sys.executable, "-c", script],
+        env=env,
+        cwd=tmp_path,
+        capture_output=True,
+        text=True,
+        timeout=600,
+    )
+    assert result.returncode == 0, result.stderr[-3000:]
+    assert "import-is-passive" in result.stdout
+
+
+def test_first_call_downloads_and_loads_once_second_call_reuses(recorded):
+    assert predict_SMILES(IMAGE) == "CO"
+    assert recorded.downloads == [PRINTED_URL]
+    assert recorded.loads == ["DECIMER_model"]
+    assert len(recorded.tokenizer_paths) == 1
+
+    assert predict_SMILES(IMAGE) == "CO"
+    assert recorded.downloads == [PRINTED_URL]
+    assert recorded.loads == ["DECIMER_model"]
+    assert len(recorded.tokenizer_paths) == 1
+
+
+def test_hand_drawn_model_is_fetched_and_loaded_only_when_asked_for(recorded):
+    predict_SMILES(IMAGE)
+    assert HAND_DRAWN_URL not in recorded.downloads
+    assert "DECIMER_HandDrawn_model" not in recorded.loads
+
+    assert predict_SMILES(IMAGE, hand_drawn=True) == "CO"
+    assert recorded.downloads == [PRINTED_URL, HAND_DRAWN_URL]
+    assert recorded.loads == ["DECIMER_model", "DECIMER_HandDrawn_model"]
+
+    predict_SMILES(IMAGE, hand_drawn=True)
+    assert recorded.downloads == [PRINTED_URL, HAND_DRAWN_URL]
+    assert recorded.loads == ["DECIMER_model", "DECIMER_HandDrawn_model"]
+
+
+def test_hand_drawn_first_does_not_load_the_printed_model(recorded):
+    """The tokenizer needs the printed model's files, but not the printed model itself."""
+    predict_SMILES(IMAGE, hand_drawn=True)
+    assert recorded.loads == ["DECIMER_HandDrawn_model"]
+    assert PRINTED_URL in recorded.downloads
+
+
+def test_confidence_output_is_unchanged(recorded):
+    smiles, tokens = predict_SMILES(IMAGE, confidence=True)
+    assert smiles == "CO"
+    assert [token for token, _ in tokens] == ["C", "O"]
+    assert [float(value) for _, value in tokens] == pytest.approx([0.9, 0.9])
+
+
+def test_prepopulated_model_directory_is_used_without_network(recorded):
+    write_model_files(recorded.models_dir, "DECIMER_model")
+    write_model_files(recorded.models_dir, "DECIMER_HandDrawn_model")
+    recorded.download_error = AssertionError("downloaded although the files exist")
+
+    assert predict_SMILES(IMAGE) == "CO"
+    assert predict_SMILES(IMAGE, hand_drawn=True) == "CO"
+
+    assert recorded.downloads == []
+    assert recorded.loads == ["DECIMER_model", "DECIMER_HandDrawn_model"]
+    expected = os.path.join(
+        recorded.models_dir, "DECIMER_model", "assets", "tokenizer_SMILES.pkl"
+    )
+    assert recorded.tokenizer_paths == [expected]
+
+
+def test_pystow_home_set_after_import_is_respected(recorded, tmp_path, monkeypatch):
+    """The directory is looked up at first use, so a late PYSTOW_HOME still applies."""
+    elsewhere = tmp_path / "baked-in-image"
+    write_model_files(elsewhere / "DECIMER-V2", "DECIMER_model")
+    monkeypatch.setenv("PYSTOW_HOME", str(elsewhere))
+    recorded.download_error = AssertionError("downloaded although the files exist")
+
+    assert predict_SMILES(IMAGE) == "CO"
+    assert recorded.downloads == []
+    assert not recorded.models_dir.exists()
+
+
+def test_a_bad_image_fails_before_any_download(recorded, tmp_path):
+    # decimer raises a bare Exception for an image it cannot read
+    with pytest.raises(Exception):
+        predict_SMILES(str(tmp_path / "missing.png"))
+    assert recorded.downloads == []
+    assert recorded.loads == []
+
+
+def test_load_models_loads_the_printed_model_once(recorded):
+    load_models()
+    assert recorded.downloads == [PRINTED_URL]
+    assert recorded.loads == ["DECIMER_model"]
+
+    load_models()
+    assert predict_SMILES(IMAGE) == "CO"
+    assert recorded.downloads == [PRINTED_URL]
+    assert recorded.loads == ["DECIMER_model"]
+
+
+def test_load_models_with_hand_drawn_loads_everything_decimer_2_8_0_loaded_at_import(
+    recorded,
+):
+    load_models(hand_drawn=True)
+    assert recorded.downloads == [PRINTED_URL, HAND_DRAWN_URL]
+    assert sorted(recorded.loads) == ["DECIMER_HandDrawn_model", "DECIMER_model"]
+
+    load_models(hand_drawn=True)
+    assert len(recorded.loads) == 2
+
+
+def test_load_models_without_the_printed_model(recorded):
+    load_models(printed=False, hand_drawn=True)
+    assert recorded.loads == ["DECIMER_HandDrawn_model"]
+
+
+def test_failed_download_is_not_cached_and_is_retried(recorded):
+    recorded.download_error = OSError("zenodo is down")
+    with pytest.raises(OSError, match="zenodo is down"):
+        predict_SMILES(IMAGE)
+    assert recorded.loads == []
+
+    recorded.download_error = None
+    assert predict_SMILES(IMAGE) == "CO"
+    assert recorded.downloads == [PRINTED_URL, PRINTED_URL]
+    assert recorded.loads == ["DECIMER_model"]
+
+
+def test_concurrent_first_calls_download_and_load_once(recorded):
+    recorded.download_delay = 0.3
+    threads_count = 4
+    barrier = threading.Barrier(threads_count)
+    results = []
+    errors = []
+
+    def first_call():
+        try:
+            barrier.wait(timeout=30)
+            results.append(predict_SMILES(IMAGE))
+        except Exception as error:  # reported below, in the main thread
+            errors.append(error)
+
+    threads = [threading.Thread(target=first_call) for _ in range(threads_count)]
+    for thread in threads:
+        thread.start()
+    for thread in threads:
+        thread.join(timeout=120)
+
+    assert errors == []
+    assert results == ["CO"] * threads_count
+    assert recorded.downloads == [PRINTED_URL]
+    assert recorded.loads == ["DECIMER_model"]
+
+
+def test_module_level_names_of_older_releases_still_resolve(recorded):
+    """`from DECIMER.decimer import tokenizer, DECIMER_V2, ...` worked with decimer <= 2.8.0."""
+    assert not hasattr(decimer_module, "no_such_name")
+    assert recorded.loads == []
+
+    from DECIMER.decimer import DECIMER_Hand_drawn
+    from DECIMER.decimer import DECIMER_V2
+    from DECIMER.decimer import tokenizer
+
+    assert isinstance(DECIMER_V2, FakeModel)
+    assert DECIMER_V2.path.endswith("DECIMER_model")
+    assert isinstance(DECIMER_Hand_drawn, FakeModel)
+    assert DECIMER_Hand_drawn.path.endswith("DECIMER_HandDrawn_model")
+    assert tokenizer.index_word[2] == "C"
+    assert decimer_module.default_path == recorded.models_dir
+    assert sorted(recorded.loads) == ["DECIMER_HandDrawn_model", "DECIMER_model"]
+
+
+def test_a_model_assigned_to_the_module_is_used(recorded):
+    """Code that replaced decimer.DECIMER_V2 with its own model keeps working."""
+
+    class OtherModel(FakeModel):
+        def __call__(self, image):
+            return tf.constant([[1, 3, 3, 4]]), tf.constant([0.5, 0.5, 0.5, 0.5])
+
+    decimer_module.DECIMER_V2 = OtherModel("my-own-model")
+    assert predict_SMILES(IMAGE) == "OO"
+    assert recorded.loads == []