xr_ai_gpu#

GPU hardware inspection without application orchestration dependencies.

Exceptions#

GPUInventoryError

Raised when a driver query fails or strict inventory cannot be parsed.

Classes#

`GPUDevice`	Driver-visible GPU facts, independent of CUDA ordinal remapping.
`GPUProcess`	One compute process reported by `nvidia-smi`.

Functions#

`query_gpu_inventory`(→ tuple[GPUDevice, Ellipsis])	Return a strict inventory of all driver-visible physical GPUs.
`query_gpu_pci_bus_ids`(→ dict[int, str])	Return physical driver indices mapped to driver PCI bus addresses.
`query_gpu_processes`(→ dict[str, list[GPUProcess]])	Return compute processes grouped by physical GPU UUID.

Package Contents#

class xr_ai_gpu.GPUDevice#

Driver-visible GPU facts, independent of CUDA ordinal remapping.

Memory values are observations at query time, not reservations. Unknown memory is None; it is never interpreted as zero or host memory.

index: int#: Physical driver index reported by nvidia-smi, not a CUDA-remapped ordinal.

uuid: str#: Stable GPU UUID.

pci_bus_id: str#: PCI bus address reported by the driver.

name: str#: Driver-reported product name.

compute_capability: float#: CUDA compute capability.

total_memory_gib: float | None#: Total memory in GiB, or None when unavailable.

free_memory_gib: float | None#: Free memory in GiB, or None when unavailable.

used_memory_gib: float | None#: Used memory in GiB, or None when unavailable.

exception xr_ai_gpu.GPUInventoryError#: Raised when a driver query fails or strict inventory cannot be parsed.

class xr_ai_gpu.GPUProcess#

One compute process reported by nvidia-smi.

gpu_uuid: str#: Driver UUID of the GPU hosting the process.

pid: int#: Host process ID.

name: str#: Driver-reported process name.

used_memory_gib: float | None#: Query-time GPU memory use in GiB, or None when unavailable.

xr_ai_gpu.query_gpu_inventory( *, timeout: float | None = None, ) → tuple[GPUDevice, Ellipsis]#

Return a strict inventory of all driver-visible physical GPUs.

Ignores CUDA_VISIBLE_DEVICES; indices are physical driver indices rather than remapped CUDA ordinals. Memory is observed at query time, in GiB, with unavailable values represented as None. No device filter is applied.

Args:

timeout: Positive, finite driver-command deadline in seconds; None: permits cold-driver initialization without a deadline.

Raises:

GPUInventoryError: The query fails, times out, returns no devices,: or contains malformed fields.

xr_ai_gpu.query_gpu_pci_bus_ids( *, timeout: float | None = None, ) → dict[int, str]#

Return physical driver indices mapped to driver PCI bus addresses.

Ignores CUDA_VISIBLE_DEVICES. Skips rows with fewer than two columns or an index that cannot be parsed as an integer. Returns the address column with surrounding whitespace stripped, including empty or malformed addresses; callers interpret and validate the address. Empty output returns an empty mapping. This narrow query does not require compute capability or memory support.

Args:: timeout: Positive, finite deadline in seconds; None means no deadline.
Raises:: GPUInventoryError: The command cannot run, fails, or times out.

xr_ai_gpu.query_gpu_processes( *, timeout: float | None = None, ) → dict[str, list[GPUProcess]]#

Return compute processes grouped by physical GPU UUID.

CUDA_VISIBLE_DEVICES does not filter this query. Unknown memory is None.

Args:

timeout: Positive, finite driver-command deadline in seconds; None: permits cold-driver initialization without a deadline.

Raises:

GPUInventoryError: The command fails, times out, or contains malformed fields.