cuml-cpu: fix import issues, enable conda import tests (#6400)

Fixes #6403 

This project publishes a conda package, `cuml-cpu`, which does what it sounds like... allows the use of cuML on systems without a GPU.

This proposes some updates to packaging for `cuml-cpu`:

* fixes importing in CPU-only environment (broken in 25.04, see #6403)
* enables import tests during conda builds, to reduce the risk of such issues going undetected in the future

## Notes for Reviewers

### Why all these changes in Python code?

See some of the challenges I faced documented in #6400 (comment). 

In short, `import cuml` when it was installed via `cuml-cpu` will break at import time whenever modules imported with `cuml.internals.safe_imports.gpu_only_import()` are used in any of the following ways:

* type hints
* decorators
* any other module-level direct use

Like this:

```text
cuml.internals.safe_imports.UnavailableError: cudf is not installed in non GPU-enabled installations
```

### How long has this been broken? What's the root cause?

It seems like something changed within 25.04... earlier versions of cuML are not affected by these issues: #6403 (comment)

I don't know what the root cause is. Maybe some changes to `cuml`'s top-level imports in 25.04 is now pulling in the modules with these problems at runtime, when previously it wasn't? I'm really not sure.

### Benefits of these Changes

This adds a bit of test coverage in CI, minimally verifying that `cuml-cpu` is installable and that `import cuml` works in an environment without a GPU.

Inspired by:

* similar changes in `cuvs`: rapidsai/cuvs#750
* this conversation I recently had with @betatim : rapidsai/cuvs#743 (comment)

### How I tested this

Saw stuff like this in `conda-python-build` jobs, confirming that the import tests were running and passing:

```text
BUILD START: ['cuml-cpu-25.04.00a137-py310_250312_g153b21870_137.conda']
...
import: 'cuml'
...
Resource usage statistics from testing cuml-cpu:
...
   Time elapsed: 0:00:10.0
...
TEST END: /tmp/conda-bld-output/linux-64/cuml-cpu-25.04.00a137-py310_250312_g153b21870_137.conda
```

Authors:
  - James Lamb (https://github.com/jameslamb)

Approvers:
  - Gil Forsyth (https://github.com/gforsyth)
  - Simon Adorf (https://github.com/csadorf)
  - Tim Head (https://github.com/betatim)

URL: #6400

Author: jameslamb

ci/build_python.sh

@@ -37,7 +37,6 @@ if [[ ${RAPIDS_CUDA_MAJOR} == "12" ]]; then
   sccache --zero-stats
 
   RAPIDS_PACKAGE_VERSION=$(head -1 ./VERSION) rapids-conda-retry build \
-  --no-test \
   conda/recipes/cuml-cpu
 
   sccache --show-adv-stats

conda/recipes/cuml-cpu/meta.yaml

@@ -39,9 +39,10 @@ requirements:
     - umap-learn=0.5.6
     - nvtx
 
-tests:                                 # [linux64]
-  imports:                             # [linux64]
-    - cuml                             # [linux64]
+test:
+  # test that the package is installable and these modules are importable
+  imports:
+    - cuml
 
 about:
   home: https://rapids.ai/

python/cuml/cuml/_thirdparty/sklearn/preprocessing/_imputation.py

@@ -29,7 +29,7 @@
 
 from cuml.internals.safe_imports import cpu_only_import
 numpy = cpu_only_import('numpy')
-np = gpu_only_import('cupy')
+np = gpu_only_import('cupy', alt=numpy)
 sparse = gpu_only_import_from('cupyx.scipy', 'sparse')
 
 

python/cuml/cuml/_thirdparty/sklearn/utils/sparsefuncs.py

@@ -11,6 +11,7 @@
 # This code is under BSD 3 clause license.
 # Authors mentioned above do not endorse or promote this production.
 
+import numpy
 
 from ....thirdparty_adapters.sparsefuncs_fast import (
     csr_mean_variance_axis0 as _csr_mean_var_axis0,
@@ -21,7 +22,7 @@
 from cuml.internals.safe_imports import cpu_only_import_from
 cpu_sp = cpu_only_import_from('scipy', 'sparse')
 gpu_sp = gpu_only_import_from('cupyx.scipy', 'sparse')
-np = gpu_only_import('cupy')
+np = gpu_only_import('cupy', alt=numpy)
 cpu_np = cpu_only_import('numpy')
 
 

python/cuml/cuml/dask/common/input_utils.py

@@ -27,7 +27,6 @@
 from dask_cudf import Series as dcSeries
 from dask.dataframe import Series as daskSeries
 from dask.dataframe import DataFrame as daskDataFrame
-from cudf import Series
 from cuml.internals.safe_imports import gpu_only_import_from
 from collections import OrderedDict
 from cuml.internals.memory_utils import with_cupy_rmm
@@ -197,7 +196,7 @@ def _get_datatype_from_inputs(data):
 
 @with_cupy_rmm
 def concatenate(objs, axis=0):
-    if isinstance(objs[0], DataFrame) or isinstance(objs[0], Series):
+    if isinstance(objs[0], DataFrame) or isinstance(objs[0], cudf.Series):
         if len(objs) == 1:
             return objs[0]
         else:

python/cuml/cuml/feature_extraction/_vectorizers.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2020-2023, NVIDIA CORPORATION.
+# Copyright (c) 2020-2025, NVIDIA CORPORATION.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,7 +14,6 @@
 #
 from cuml.internals.safe_imports import cpu_only_import
 import cuml.internals.logger as logger
-from cudf.utils.dtypes import min_signed_type
 from cuml.internals.type_utils import CUPY_SPARSE_DTYPES
 import numbers
 from cuml.internals.safe_imports import gpu_only_import
@@ -256,7 +255,7 @@ def _compute_empty_doc_ids(self, count_df, n_doc):
         of documents.
         """
         remaining_docs = count_df["doc_id"].unique()
-        dtype = min_signed_type(n_doc)
+        dtype = cudf.utils.dtypes.min_signed_type(n_doc)
         doc_ids = cudf.DataFrame(
             data={"all_ids": cp.arange(0, n_doc, dtype=dtype)}, dtype=dtype
         )

python/cuml/cuml/internals/base_return_types.py

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2022-2023, NVIDIA CORPORATION.
+# Copyright (c) 2022-2025, NVIDIA CORPORATION.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -97,7 +97,8 @@ def _get_base_return_type(class_name, attr):
         if attr.__annotations__["return"].replace("'", "") == class_name:
             return "base"
     except Exception:
-        assert False, "Shouldn't get here"
-        return None
+        raise AssertionError(
+            f"Failed to determine return type for {attr} (class = '${class_name}'). This is a bug in cuML, please report it."
+        )
 
     return None

python/cuml/cuml/model_selection/_split.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+from __future__ import annotations
 
 from typing import Optional, Union, List, Tuple
 

python/cuml/cuml/preprocessing/LabelEncoder.py

@@ -207,7 +207,7 @@ def fit(self, y, _classes=None):
         self.dtype = y.dtype if y.dtype != cp.dtype("O") else str
         return self
 
-    def transform(self, y) -> cudf.Series:
+    def transform(self, y):
         """
         Transform an input into its categorical keys.
 
@@ -242,7 +242,7 @@ def transform(self, y) -> cudf.Series:
 
         return encoded
 
-    def fit_transform(self, y, z=None) -> cudf.Series:
+    def fit_transform(self, y, z=None):
         """
         Simultaneously fit and transform an input
 
@@ -258,7 +258,7 @@ def fit_transform(self, y, z=None) -> cudf.Series:
 
         return y.cat.codes
 
-    def inverse_transform(self, y: cudf.Series) -> cudf.Series:
+    def inverse_transform(self, y: "cudf.Series"):
         """
         Revert ordinal label to original label
 

python/cuml/cuml/preprocessing/encoders.py

@@ -16,7 +16,6 @@
 from typing import Optional
 
 import cuml.internals.logger as logger
-from cudf import DataFrame, Series
 from cuml import Base
 from cuml.common.doc_utils import generate_docstring
 from cuml.common.exceptions import NotFittedError
@@ -95,7 +94,7 @@ def _check_input(self, X, is_categories=False):
             self._set_input_type("array")
             if is_categories:
                 X = X.transpose()
-            return DataFrame(X)
+            return cudf.DataFrame(X)
         else:
             self._set_input_type("df")
             return X
@@ -346,7 +345,7 @@ def _compute_drop_idx(self):
                 )
             drop_idx = dict()
             for feature in self.drop.keys():
-                self.drop[feature] = Series(self.drop[feature])
+                self.drop[feature] = cudf.Series(self.drop[feature])
                 if len(self.drop[feature]) != 1:
                     msg = (
                         "Trying to drop multiple values for feature {}, "
@@ -361,7 +360,7 @@ def _compute_drop_idx(self):
                         "categories.".format(feature)
                     )
                     raise ValueError(msg)
-                cats = Series(cats)
+                cats = cudf.Series(cats)
                 idx = cats.isin(self.drop[feature])
                 drop_idx[feature] = cp.asarray(cats[idx].index)
             return drop_idx
@@ -517,26 +516,28 @@ def inverse_transform(self, X):
             # if close: `and not cupyx.scipy.sparse.issparsecsc(X)`
             # and change the following line by `X = X.tocsc()`
             X = X.toarray()
-        result = DataFrame(columns=self._encoders.keys())
+        result = cudf.DataFrame(columns=self._encoders.keys())
         j = 0
         for feature in self._encoders.keys():
             feature_enc = self._encoders[feature]
             cats = feature_enc.classes_
 
             if self.drop is not None:
                 # Remove dropped categories
-                dropped_class_idx = Series(self.drop_idx_[feature])
-                dropped_class_mask = Series(cats).isin(cats[dropped_class_idx])
+                dropped_class_idx = cudf.Series(self.drop_idx_[feature])
+                dropped_class_mask = cudf.Series(cats).isin(
+                    cats[dropped_class_idx]
+                )
                 if len(cats) == 1:
-                    inv = Series(Index([cats[0]]).repeat(X.shape[0]))
+                    inv = cudf.Series(Index([cats[0]]).repeat(X.shape[0]))
                     result[feature] = inv
                     continue
                 cats = cats[~dropped_class_mask]
 
             enc_size = len(cats)
             x_feature = X[:, j : j + enc_size]
             idx = cp.argmax(x_feature, axis=1)
-            inv = Series(cats.iloc[idx]).reset_index(drop=True)
+            inv = cudf.Series(cats.iloc[idx]).reset_index(drop=True)
 
             if self.handle_unknown == "ignore":
                 not_null_idx = x_feature.any(axis=1)
@@ -548,7 +549,7 @@ def inverse_transform(self, X):
                 dropped_mask = cp.asarray(x_feature.sum(axis=1) == 0).flatten()
                 if dropped_mask.any():
                     inv[dropped_mask] = feature_enc.inverse_transform(
-                        Series(self.drop_idx_[feature])
+                        cudf.Series(self.drop_idx_[feature])
                     )[0]
 
             result[feature] = inv
@@ -624,7 +625,7 @@ def _slice_feat(X, i):
 def _get_output(
     output_type: Optional[str],
     input_type: Optional[str],
-    out: DataFrame,
+    out: "cudf.DataFrame",
     dtype,
 ):
     if output_type == "input":
@@ -729,7 +730,7 @@ def transform(self, X):
             col_idx = self._encoders[feature].transform(Xi)
             result[feature] = col_idx
 
-        r = DataFrame(result)
+        r = cudf.DataFrame(result)
         return _get_output(self.output_type, self.input_type, r, self.dtype)
 
     @generate_docstring(
@@ -766,7 +767,7 @@ def inverse_transform(self, X):
             inv = self._encoders[feature].inverse_transform(Xi)
             result[feature] = inv
 
-        r = DataFrame(result)
+        r = cudf.DataFrame(result)
         return _get_output(self.output_type, self.input_type, r, self.dtype)
 
     @classmethod

python/cuml/cuml/preprocessing/text/stem/porter_stemmer_utils/suffix_utils.py

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2020-2024, NVIDIA CORPORATION.
+# Copyright (c) 2020-2025, NVIDIA CORPORATION.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -84,23 +84,25 @@ def subtract_valid(input_array, valid_bool_array, sub_val):
             input_array[pos] = input_array[pos] - sub_val
 
 
-@cudf.core.buffer.acquire_spill_lock()
 def get_stem_series(word_str_ser, suffix_len, can_replace_mask):
     """
     word_str_ser: input string column
     suffix_len: length of suffix to replace
     can_repalce_mask: bool array marking strings where to replace
     """
-    NTHRD = 1024
-    NBLCK = int(np.ceil(float(len(word_str_ser)) / float(NTHRD)))
-
-    start_series = cudf.Series(cp.zeros(len(word_str_ser), dtype=cp.int32))
-    end_ser = word_str_ser.str.len()
-
-    end_ar = end_ser._column.data_array_view(mode="read")
-    can_replace_mask_ar = can_replace_mask._column.data_array_view(mode="read")
-
-    subtract_valid[NBLCK, NTHRD](end_ar, can_replace_mask_ar, suffix_len)
-    return word_str_ser.str.slice_from(
-        starts=start_series, stops=end_ser.fillna(0)
-    )
+    with cudf.core.buffer.acquire_spill_lock():
+        NTHRD = 1024
+        NBLCK = int(np.ceil(float(len(word_str_ser)) / float(NTHRD)))
+
+        start_series = cudf.Series(cp.zeros(len(word_str_ser), dtype=cp.int32))
+        end_ser = word_str_ser.str.len()
+
+        end_ar = end_ser._column.data_array_view(mode="read")
+        can_replace_mask_ar = can_replace_mask._column.data_array_view(
+            mode="read"
+        )
+
+        subtract_valid[NBLCK, NTHRD](end_ar, can_replace_mask_ar, suffix_len)
+        return word_str_ser.str.slice_from(
+            starts=start_series, stops=end_ser.fillna(0)
+        )

python/cuml/cuml/thirdparty_adapters/adapters.py

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2020-2023, NVIDIA CORPORATION.
+# Copyright (c) 2020-2025, NVIDIA CORPORATION.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,12 +14,10 @@
 # limitations under the License.
 #
 
-from cupyx.scipy import sparse as gpu_sparse
 from scipy import sparse as cpu_sparse
 from scipy.sparse import csc_matrix as cpu_coo_matrix
 from scipy.sparse import csc_matrix as cpu_csc_matrix
 from cuml.internals.safe_imports import cpu_only_import_from
-from cupyx.scipy.sparse import csc_matrix as gpu_coo_matrix
 from cuml.internals.safe_imports import gpu_only_import_from
 from cuml.internals.global_settings import GlobalSettings
 from cuml.internals.input_utils import input_to_cupy_array, input_to_host_array
@@ -28,6 +26,8 @@
 
 np = cpu_only_import("numpy")
 cp = gpu_only_import("cupy")
+gpu_sparse = gpu_only_import("cupyx.scipy.sparse")
+gpu_coo_matrix = gpu_only_import_from("cupyx.scipy.sparse", "coo_matrix")
 gpu_csr_matrix = gpu_only_import_from("cupyx.scipy.sparse", "csr_matrix")
 gpu_csc_matrix = gpu_only_import_from("cupyx.scipy.sparse", "csc_matrix")
 cpu_csr_matrix = cpu_only_import_from("scipy.sparse", "csr_matrix")