feat: implement get-kernel-variants

Author: sayakpaul

docs/source/api/kernels.md

@@ -14,6 +14,10 @@
 
 [[autodoc]] kernels.has_kernel
 
+### get_kernel_variants
+
+[[autodoc]] kernels.get_kernel_variants
+
 ### get_loaded_kernels
 
 [[autodoc]] kernels.get_loaded_kernels

docs/source/basic-usage.md

@@ -43,6 +43,23 @@ is_available = has_kernel("kernels-community/activation", version=1)
 print(f"Kernel available: {is_available}")
 ```
 
+When no compatible kernel is found, [`~kernels.has_kernel`] does not say *why*.
+[`~kernels.get_kernel_variants`] returns the full resolution trace instead: one
+decision per build variant in the repository, with compatible variants listed
+first. Each decision is a `VariantAccepted` or a `VariantRejected`, and rejected
+variants carry a human-readable `reason`:
+
+```python
+from kernels import get_kernel_variants, VariantAccepted
+
+for decision in get_kernel_variants("kernels-community/activation", version=1):
+    name = decision.variant.variant_str
+    if isinstance(decision, VariantAccepted):
+        print(f"{name}: compatible")
+    else:
+        print(f"{name}: rejected ({decision.reason})")
+```
+
 ## Inspecting Loaded Kernels
 
 [`~kernels.get_loaded_kernels`] returns a snapshot of every kernel that has been loaded

kernels/src/kernels/__init__.py

@@ -28,13 +28,18 @@
     LoadedKernel,
     RepoInfo,
     get_kernel,
+    get_kernel_variants,
     get_loaded_kernels,
     get_local_kernel,
     get_locked_kernel,
     has_kernel,
     install_kernel,
     load_kernel,
 )
+from kernels.variants import (
+    VariantAccepted,
+    VariantRejected,
+)
 
 _add_additional_dll_paths()
 
@@ -54,7 +59,10 @@
     "Metadata",
     "Mode",
     "RepoInfo",
+    "VariantAccepted",
+    "VariantRejected",
     "get_kernel",
+    "get_kernel_variants",
     "get_loaded_kernels",
     "get_local_kernel",
     "get_locked_kernel",

kernels/src/kernels/utils.py

@@ -25,10 +25,12 @@
 from kernels.lockfile import KernelLock, VariantLock
 from kernels.status import resolve_status
 from kernels.variants import (
+    Decision,
     Variant,
     get_variants,
     get_variants_local,
     resolve_variant,
+    resolve_variants,
     variants_trace_str,
 )
 
@@ -552,6 +554,42 @@ def has_kernel(
     )
 
 
+def get_kernel_variants(
+    repo_id: str,
+    revision: str | None = None,
+    version: int | None = None,
+    backend: str | None = None,
+) -> list[Decision]:
+    """
+    Resolve all build variants of a kernel against the current environment.
+
+    The decisions are sorted with compatible variants first, the most preferred
+    variant leading.
+
+    Args:
+        repo_id (`str`):
+            The Hub repository containing the kernel.
+        revision (`str`, *optional*):
+            The specific revision (branch, tag, or commit) to inspect. Cannot be used together with `version`.
+        version (`int`, *optional*):
+            The kernel version to inspect. Cannot be used together with `revision`.
+            Either `version` or `revision` must be specified.
+        backend (`str`, *optional*):
+            The backend to resolve variants for. Can only be `cpu` or the backend that Torch is compiled for.
+            The backend will be detected automatically if not provided.
+
+    Returns:
+        `list[Decision]`: One `VariantAccepted` or `VariantRejected` per build variant
+            in the repository, compatible variants first.
+    """
+    revision = select_revision_or_version(repo_id, revision=revision, version=version)
+
+    api = _get_hf_api()
+    variants = get_variants(api, repo_id=repo_id, revision=revision)
+    _, trace = resolve_variants(variants, backend)
+    return trace
+
+
 def load_kernel(
     repo_id: str, *, lockfile: Path | None, backend: str | None = None, revision: str | None = None
 ) -> ModuleType: