os_helper.hardware_utils module

Hardware Utilities

Cross-platform hardware inspection: CPU (core counts + model name), RAM, GPU (vendor, model name, VRAM), and Apple Silicon chip identification.

This module stays a plain hardware-facts probe. It answers “what does this machine have” (cores, chip/GPU model strings, memory sizes) and deliberately does NOT answer AI-inference questions like “how many tokens/s will this push” or “should this repo use Ollama or vLLM” — those derivations belong to the consumer (e.g. best-engine-ai-helper), which combines these raw facts with its own domain tables (memory-bandwidth-per-chip, decode-efficiency-per- backend, …). Keeping the split this way lets every helper in the suite (9+ repos) call the same hardware probe without pulling in AI-specific logic.

Probe order for the accelerator vendor mirrors real-world prevalence: Apple Silicon first (macOS can otherwise surface stray nvidia-smi output from a VM or eGPU passthrough), then NVIDIA, then AMD, then an Intel-iGPU check on Linux, falling back to plain CPU.

Usage example

>>> import os_helper as osh
>>> info = osh.hardware_info()
>>> info["cpu"]["logical_cores"] > 0
True
>>> info["ram_gb"] > 0
True

Author

Warith HARCHAOUI, https://linkedin.com/in/warith-harchaoui

os_helper.hardware_utils.amd_gpus()

List every AMD GPU visible to rocm-smi with its name and VRAM.

ROCm’s text output format has drifted across releases, so this is a best-effort parse: it pairs up --showproductname names with --showmeminfo vram totals by GPU index. When the two calls disagree on GPU count (or either returns nothing usable), it degrades to VRAM-only entries rather than guessing a mismatched name.

Returns:

One entry per GPU: {"vendor": "amd", "name": str | None, "vram_gb": float}. Empty list when rocm-smi is unavailable.

Return type:

list of dict

os_helper.hardware_utils.apple_chip_name()

Return the Apple Silicon chip name (e.g. 'Apple M2 Max').

Returns:

The chip name, or None on non-macOS platforms or when the system_profiler “Chip:” line is absent (older Intel Macs).

Return type:

str or None

os_helper.hardware_utils.apple_unified_memory_gb()

Return the Apple Silicon unified-memory pool size in GB.

Returns:

Memory in GB, or None off macOS or when the value could not be parsed from system_profiler.

Return type:

float or None

os_helper.hardware_utils.available_ram_gb()

Return system RAM currently free (not committed to any process), in GB.

Unlike ram_gb() (a static hardware fact: total installed memory), this is a live figure that shrinks as other processes — including an already-running local inference server — consume memory, and grows again once they release it. Consumers that only care about total capacity should keep using ram_gb(); this is for callers that need to know what is realistically usable right now.

Returns:

Free RAM in GB, per psutil.virtual_memory().available (accounts for reclaimable OS caches/buffers, so it is more representative of “usable now” than the raw “free” figure some tools report).

Return type:

float

Examples

>>> 0 <= available_ram_gb() <= ram_gb()
True

os_helper.hardware_utils.cpu_count_logical()

Return the number of logical CPUs (including hyperthreads/SMT).

Returns:

os.cpu_count(), or 1 if the platform refuses to report it.

Return type:

int

Examples

>>> cpu_count_logical() >= 1
True

os_helper.hardware_utils.cpu_count_physical()

Return the number of physical CPU cores (excluding hyperthreads/SMT).

Delegates to psutil, which already normalizes this across platforms (it reads /proc/cpuinfo core ids on Linux, sysctl on macOS, and the WMI processor table on Windows).

Returns:

Physical core count, or None when psutil cannot determine it (rare, e.g. some container sandboxes).

Return type:

int or None

os_helper.hardware_utils.cpu_model()

Return a human-readable CPU model string for the current machine.

Parameters:

None

Returns:

e.g. 'Apple M2 Max', 'AMD Ryzen 9 7950X', 'Intel(R) Xeon(R) Platinum 8358 CPU @ 2.60GHz'. None if no probe on this platform yielded a usable string.

Return type:

str or None

Examples

>>> cpu_model() is None or isinstance(cpu_model(), str)
True

os_helper.hardware_utils.cpu_percent()

Return instantaneous CPU utilization as a percentage (0-100).

Delegates to psutil.cpu_percent, sampled over a short blocking window so the figure reflects genuinely current load rather than the misleading 0.0 psutil returns on a first call with no interval. A live figure, not a hardware fact — call this only where a short (0.1s) blocking sample is acceptable (diagnostics, one-shot CLI reports); do not call it in a hot loop.

Returns:

CPU utilization percent, 0-100.

Return type:

float

Examples

>>> 0.0 <= cpu_percent() <= 100.0
True

os_helper.hardware_utils.disk_usage_gb(path=None)

Return free space and percent used for the filesystem holding path.

Parameters:

path (str or None) – Any path on the filesystem to report on. Defaults to the user’s home directory, since that is where most local caches (model weights, package caches, build artifacts) actually live and eventually fill up.

Returns:

{"free_gb": float, "used_gb": float, "total_gb": float, "percent_used": float}.

Return type:

dict

Examples

>>> usage = disk_usage_gb()
>>> 0.0 <= usage["percent_used"] <= 100.0
True

os_helper.hardware_utils.gpu_utilization_percent(vendor=None)

Return the current (live) GPU compute utilization, 0-100.

Apple Silicon (via IOKit, see _apple_gpu_utilization_percent() — no powermetrics/sudo needed), NVIDIA (nvidia-smi), and AMD (rocm-smi). A multi-GPU box reports the first card’s utilization only, matching gpus()’s single-card assumption elsewhere in this module.

Parameters:

vendor (str or None) – One of gpu_vendor()’s return values. Defaults to calling gpu_vendor() when omitted.

Returns:

Utilization percent, or None when unavailable (wrong vendor, tool not on PATH, or unparseable output) — never a fabricated number.

Return type:

float or None

Examples

>>> util = gpu_utilization_percent("cpu")
>>> util is None
True

os_helper.hardware_utils.gpu_vendor()

Identify the primary compute accelerator vendor on this machine.

Checks, in order: Apple Silicon, NVIDIA (nvidia-smi), AMD (rocm-smi), Intel integrated graphics (Linux lspci only), then falls back to 'cpu'.

Returns:

One of: 'apple', 'nvidia', 'amd', 'intel', 'cpu'.

Return type:

str

Examples

>>> gpu_vendor() in ('apple', 'nvidia', 'amd', 'intel', 'cpu')
True

os_helper.hardware_utils.gpus()

List every discrete GPU on this machine, dispatched by detected vendor.

Apple Silicon is intentionally excluded: it has no discrete VRAM pool to enumerate (see apple_unified_memory_gb() instead).

Returns:

See nvidia_gpus() / amd_gpus() for the entry shape. Empty list on Apple Silicon, Intel iGPU, or CPU-only machines.

Return type:

list of dict

os_helper.hardware_utils.hardware_info()

Return a single snapshot of every hardware fact this module can detect.

Convenience aggregate over every other function in this module, useful for a one-call “what is this machine” report (CLI detect commands, diagnostics, bug reports). Mixes static facts (core counts, RAM capacity) with live figures (cpu_percent, available_ram_gb, disk, gpu_utilization_percent) sampled at call time — fine for a one-shot report, not for polling in a hot loop (see the live functions’ own docstrings).

Returns:

{"platform": str, "cpu": {"physical_cores": int | None, "logical_cores": int, "model": str | None, "percent": float}, "ram_gb": float, "available_ram_gb": float, "disk": {"free_gb": float, "used_gb": float, "total_gb": float, "percent_used": float}, "gpu_vendor": str, "gpus": list[dict], "gpu_utilization_percent": float | None, "apple_chip": str | None, "apple_unified_gb": float | None}.

Return type:

dict

Examples

>>> info = hardware_info()
>>> set(info) == {
...     "platform", "cpu", "ram_gb", "available_ram_gb", "disk",
...     "gpu_vendor", "gpus", "gpu_utilization_percent",
...     "apple_chip", "apple_unified_gb",
... }
True

os_helper.hardware_utils.nvidia_gpus()

List every NVIDIA GPU visible to nvidia-smi with its name and VRAM.

Returns:

One entry per GPU: {"vendor": "nvidia", "name": str, "vram_gb": float}. Empty list when nvidia-smi is unavailable or reports nothing.

Return type:

list of dict

Examples

>>> all('vram_gb' in g for g in nvidia_gpus())
True

os_helper.hardware_utils.platform_name()

Return the current OS as a short lowercase string.

Returns:

One of: 'darwin', 'linux', 'windows'.

Return type:

str

Examples

>>> platform_name() in ('darwin', 'linux', 'windows')
True

os_helper.hardware_utils.ram_gb()

Return total system RAM in GB.

Returns:

Total RAM in GB. Always a positive float — psutil is a mandatory runtime dependency, so this never raises ImportError.

Return type:

float

Examples

>>> ram_gb() > 0
True