Merge branch 'develop' into feat-tflite-cli

Author: omkar-334

CHANGELOG.md

@@ -21,7 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
--
+- Fixed `import rfdetr` failing on NumPy 2.x when a transitive dependency references the removed `np.complex_` alias ([#1064](https://github.com/roboflow/rf-detr/pull/1064))
 
 ### Security
 

src/rfdetr/__init__.py

@@ -31,6 +31,22 @@
 import sys
 from typing import Any
 
+# np.complex_ was removed in NumPy 2.0 (June 2024). Some transitive dependencies (e.g. older
+# tensorflow, chumpy) still reference it, causing AttributeError on import rfdetr. See issue #1061.
+# TODO: Remove once all transitive deps support NumPy 2.x natively.
+try:
+    import numpy
+
+    _IS_NUMPY_INSTALLED = True
+except ImportError:
+    _IS_NUMPY_INSTALLED = False
+
+if _IS_NUMPY_INSTALLED and not hasattr(numpy, "complex_"):
+    _complex128 = getattr(numpy, "complex128", None)
+    if _complex128 is not None:
+        numpy.complex_ = _complex128
+
+
 from rfdetr.detr import RFDETR
 from rfdetr.inference import ModelContext
 from rfdetr.variants import (

src/rfdetr/detr.py

@@ -267,7 +267,14 @@ def from_checkpoint(cls, path: str | os.PathLike[str], **kwargs: Any) -> RFDETR:
         1. ``model_name`` key in the checkpoint (written by the PTL training
            stack since v1.7.0).
         2. ``pretrain_weights`` field in the checkpoint's ``args`` entry
-           (legacy fallback).
+           (legacy fallback for older checkpoints).
+        3. The **filename** of *path* itself, used as a last resort when
+           ``pretrain_weights`` is absent or an unset-like sentinel value
+           (empty string, ``"none"``, or ``"null"``).  Starter weights
+           published by Roboflow store ``pretrain_weights="none"`` in their
+           ``args``; passing the canonical filename (e.g.
+           ``rf-detr-small.pth``) lets ``from_checkpoint`` infer the class
+           automatically.
 
         Both legacy ``argparse.Namespace`` checkpoints (produced by ``engine.py``) and dict-style checkpoints (produced
         by the PTL training stack) are supported.
@@ -288,7 +295,8 @@ def from_checkpoint(cls, path: str | os.PathLike[str], **kwargs: Any) -> RFDETR:
             FileNotFoundError: If *path* does not exist.
             OSError: If *path* exists but cannot be read.
             KeyError: If the checkpoint does not contain an ``"args"`` key.
-            ValueError: If the model class cannot be inferred from ``model_name`` or ``pretrain_weights``.
+            ValueError: If the model class cannot be inferred from ``model_name``,
+                ``pretrain_weights``, or the checkpoint filename.
 
         Examples:
             >>> model = RFDETR.from_checkpoint("checkpoint_best_total.pth")  # doctest: +SKIP
@@ -360,11 +368,24 @@ def from_checkpoint(cls, path: str | os.PathLike[str], **kwargs: Any) -> RFDETR:
         else:
             normalized_name = ""
 
-        # Fall back to pretrain_weights filename parsing for older checkpoints.
+        # Fall back to pretrain_weights (legacy) or, when unset-like, the checkpoint filename.
         if isinstance(args, dict):
-            weights_name = str(args.get("pretrain_weights", "")).lower()
+            weights_name = str(args.get("pretrain_weights", "")).strip().lower()
         else:
-            weights_name = str(getattr(args, "pretrain_weights", "")).lower()
+            weights_name = str(getattr(args, "pretrain_weights", "")).strip().lower()
+        # The sentinel set {"", "none", "null"} covers unset-like checkpoint values:
+        #   ""     — pretrain_weights key absent entirely
+        #   "none" — checkpoint value was None or the literal string "none";
+        #            after str(...).strip().lower() both normalize to the same sentinel.
+        #            This is NOT an intentional "no pretraining" flag (see
+        #            test_pretrain_weights_none_warns, which operates at the config
+        #            level, not the checkpoint level)
+        #   "null" — checkpoint stored the literal string "null" (for example from a
+        #            YAML-originated value), which is also treated as unset-like here
+        _filename_fallback = False
+        if weights_name in {"", "none", "null"}:
+            weights_name = os.path.basename(os.fspath(path)).lower()
+            _filename_fallback = True
 
         if model_cls is None:
             # Guard: plus-only checkpoints should raise an actionable install error
@@ -385,6 +406,14 @@ def from_checkpoint(cls, path: str | os.PathLike[str], **kwargs: Any) -> RFDETR:
                     model_cls = klass
                     break
 
+            if _filename_fallback and model_cls is not None:
+                logger.info(
+                    "pretrain_weights unset in checkpoint %r; inferred model class %s from filename %r",
+                    path,
+                    getattr(model_cls, "__name__", repr(model_cls)),
+                    weights_name,
+                )
+
         if model_cls is None:
             raise ValueError(
                 f"Could not infer model class from checkpoint at {path!r} "

tests/models/test_from_checkpoint.py

@@ -96,6 +96,27 @@ def test_characterization_infers_correct_class_namespace(
         assert call_kwargs.get("pretrain_weights") == str(tmp_path / "ckpt.pth")
         assert result is mock_cls.return_value
 
+    @pytest.mark.parametrize(
+        "missing_value",
+        [
+            pytest.param("none", id="bare-none"),
+            pytest.param("null", id="bare-null"),
+            pytest.param("", id="empty"),
+            pytest.param("  None  ", id="whitespace-None"),
+            pytest.param("  ", id="whitespace-only"),
+            pytest.param(" null ", id="whitespace-null"),
+            pytest.param(None, id="python-None"),
+        ],
+    )
+    def test_namespace_args_falls_back_to_checkpoint_filename_when_pretrain_weights_missing(
+        self, tmp_path: Path, missing_value: str | None
+    ) -> None:
+        """Namespace args: filename fallback fires when pretrain_weights is unset-like."""
+        ckpt = _ns(missing_value)  # type: ignore[arg-type]
+        _, mock_cls = _call_from_checkpoint(ckpt, tmp_path / "rf-detr-small.pth", "rfdetr.variants.RFDETRSmall")
+        mock_cls.assert_called_once()
+        assert mock_cls.call_args.kwargs["num_classes"] == 80
+
 
 # ---------------------------------------------------------------------------
 # Dict args (PTL / converted checkpoints)
@@ -151,6 +172,21 @@ def test_characterization_unknown_pretrain_weights_raises_value_error(self, tmp_
             with pytest.raises(ValueError, match="Could not infer model class"):
                 RFDETR.from_checkpoint(tmp_path / "ckpt.pth")
 
+    def test_filename_fallback_unrecognized_name_raises_value_error(self, tmp_path: Path) -> None:
+        """ValueError fires via filename-fallback path when filename has no known model token."""
+        ckpt = {"args": {"pretrain_weights": "none", "num_classes": 80}}
+        with patch("rfdetr.detr.torch.load", return_value=ckpt):
+            with pytest.raises(ValueError, match="Could not infer model class"):
+                RFDETR.from_checkpoint(tmp_path / "finetuned.pth")
+
+    @pytest.mark.skipif(_IS_RFDETR_PLUS_AVAILABLE, reason="rfdetr_plus is installed — guard not active")
+    def test_filename_fallback_xlarge_without_plus_raises_import_error(self, tmp_path: Path) -> None:
+        """ImportError fires via filename-fallback path when rfdetr_plus is absent."""
+        ckpt = {"args": {"pretrain_weights": "none", "num_classes": 80}}
+        with patch("rfdetr.detr.torch.load", return_value=ckpt):
+            with pytest.raises(ImportError):
+                RFDETR.from_checkpoint(tmp_path / "rf-detr-xlarge-starter.pth")
+
     def test_characterization_missing_args_key_raises_key_error(self, tmp_path: Path) -> None:
         """Checkpoint without 'args' key raises KeyError."""
         ckpt = {"model": {}}
@@ -314,6 +350,27 @@ def test_falls_back_to_pretrain_weights_without_model_name(self, tmp_path: Path)
         _, mock_cls = _call_from_checkpoint(ckpt, tmp_path / "ckpt.pth", "rfdetr.variants.RFDETRSmall")
         mock_cls.assert_called_once()
 
+    @pytest.mark.parametrize(
+        "missing_value",
+        [
+            pytest.param("none", id="bare-none"),
+            pytest.param("null", id="bare-null"),
+            pytest.param("", id="empty"),
+            pytest.param("  None  ", id="whitespace-None"),
+            pytest.param("  ", id="whitespace-only"),
+            pytest.param(" null ", id="whitespace-null"),
+            pytest.param(None, id="python-None"),
+        ],
+    )
+    def test_falls_back_to_checkpoint_filename_when_pretrain_weights_missing(
+        self, tmp_path: Path, missing_value: str | None
+    ) -> None:
+        """When pretrain_weights is missing-like, from_checkpoint infers class from checkpoint filename."""
+        ckpt = {"args": {"pretrain_weights": missing_value, "num_classes": 80}}
+        _, mock_cls = _call_from_checkpoint(ckpt, tmp_path / "rf-detr-small.pth", "rfdetr.variants.RFDETRSmall")
+        mock_cls.assert_called_once()
+        assert mock_cls.call_args.kwargs["num_classes"] == 80
+
     def test_unknown_model_name_falls_back_to_pretrain_weights(self, tmp_path: Path) -> None:
         """Unrecognised model_name falls back to pretrain_weights parsing."""
         ckpt = {

tests/try_instantiate_all_models.py

@@ -92,7 +92,9 @@
 }
 
 
-def _test_from_checkpoint(model_instance: object, actual_cls: type, extra_kwargs: dict) -> None:
+def _test_from_checkpoint(
+    model_instance: object, actual_cls: type, extra_kwargs: dict, *, test_starter: bool = True
+) -> None:
     """Round-trip a model through from_checkpoint using a temp training checkpoint.
 
     Saves the instantiated model's weights into a minimal training-style checkpoint (``{"args": ..., "model":
@@ -104,6 +106,9 @@ def _test_from_checkpoint(model_instance: object, actual_cls: type, extra_kwargs
         actual_cls: The expected model class (e.g. ``RFDETRSmall``).
         extra_kwargs: Extra kwargs to pass to ``from_checkpoint`` (e.g.
             ``{"accept_platform_model_license": True}`` for plus models).
+        test_starter: When ``True`` (default) also run the starter-like
+            checkpoint round-trip.  Pass ``False`` for non-default resolutions
+            to avoid running the same resolution-independent test multiple times.
 
     Raises:
         AssertionError: If the recovered model is not an instance of *actual_cls*.
@@ -121,6 +126,13 @@ def _test_from_checkpoint(model_instance: object, actual_cls: type, extra_kwargs
         ),
         "model": model_instance.model.model.state_dict(),
     }
+    starter_like_ckpt = {
+        "args": argparse.Namespace(
+            pretrain_weights="none",
+            num_classes=num_classes,
+        ),
+        "model": model_instance.model.model.state_dict(),
+    }
 
     tmp_fd, tmp_path = tempfile.mkstemp(suffix=".pth")
     os.close(tmp_fd)
@@ -135,6 +147,21 @@ def _test_from_checkpoint(model_instance: object, actual_cls: type, extra_kwargs
     finally:
         os.unlink(tmp_path)
 
+    if test_starter:
+        starter_tmp_fd, starter_path = tempfile.mkstemp(prefix=f"{actual_cls.size}-starter-", suffix=".pth")
+        os.close(starter_tmp_fd)
+        try:
+            torch.save(starter_like_ckpt, starter_path)
+            starter_recovered = _rfdetr.from_checkpoint(starter_path, **extra_kwargs)
+            assert starter_recovered is not None, "from_checkpoint returned None for starter-like checkpoint"
+            assert hasattr(starter_recovered, "model"), "starter-like from_checkpoint result missing 'model' attribute"
+            got = type(starter_recovered).__name__
+            assert isinstance(starter_recovered, actual_cls), (
+                f"starter-like from_checkpoint returned {got}, expected {actual_cls.__name__}"
+            )
+        finally:
+            os.unlink(starter_path)
+
 
 def _test_coco_class_name_mapping(model_instance: object) -> None:
     """Verify predict() uses sparse COCO category-ID → class-name mapping.
@@ -232,7 +259,7 @@ def main() -> None:
                 # from_checkpoint round-trip: save a training-style checkpoint and reload it.
                 # Pass the real class (not a partial) so `_test_from_checkpoint` can read
                 # `.size` and `.__name__` and run `isinstance(recovered, actual_cls)`.
-                _test_from_checkpoint(model_instance, actual_cls, instantiate_kwargs)
+                _test_from_checkpoint(model_instance, actual_cls, instantiate_kwargs, test_starter=(res is None))
 
                 # Inference class-name regression for issue #988 — run on all
                 # nano-sized pretrained COCO models at default resolution only.

tests/utilities/test_package.py

@@ -168,6 +168,36 @@ def test_model_context_importable_from_top_level(self) -> None:
 
         assert ModelContext is not None
 
+    def test_top_level_import_sets_numpy_complex_alias(self) -> None:
+        """Verify rfdetr shim sets np.complex_ in a fresh interpreter with complex_ absent.
+
+        Runs in a subprocess so the shim code path is actually executed — importing rfdetr inside pytest is a no-op
+        because rfdetr is already cached in sys.modules.
+        """
+        result = subprocess.run(
+            [
+                sys.executable,
+                "-c",
+                (
+                    "import numpy\n"
+                    "if hasattr(numpy, 'complex_'):\n"
+                    "    del numpy.complex_\n"
+                    "import rfdetr\n"
+                    "assert hasattr(numpy, 'complex_'), 'shim did not set numpy.complex_'\n"
+                    "assert numpy.complex_ is numpy.complex128, 'complex_ must alias complex128'\n"
+                ),
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        assert result.returncode == 0, (
+            "Subprocess for NumPy complex_ shim failed:\n"
+            f"return code: {result.returncode}\n"
+            f"stdout:\n{result.stdout}\n"
+            f"stderr:\n{result.stderr}"
+        )
+
     def test_identity_across_import_paths(self) -> None:
         """The same class object must be returned regardless of import path.