car-inference 0.47.0

//! Hardware detection — auto-configure models and context based on system capabilities.

use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct HardwareInfo {
    pub os: String,
    pub arch: String,
    pub cpu_cores: usize,
    pub total_ram_mb: u64,
    /// Inference backend the build can actually drive — Metal on
    /// Apple Silicon (via the always-compiled MLX backend; the cfg-target
    /// `mlx-rs` dep, not the candle `metal` feature), CUDA on NVIDIA (with
    /// `cuda` feature), CPU otherwise. Distinct from `gpu_devices`,
    /// which lists every GPU the OS sees regardless of whether CAR
    /// has a backend for it.
    pub gpu_backend: GpuBackend,
    pub gpu_memory_mb: Option<u64>,
    /// Every GPU the OS reports — vendor + name + memory if known.
    /// Populated even when `gpu_backend == Cpu` so downstream
    /// consumers (Tokhn's concierge etc.) can route based on the
    /// hardware that's actually present, not just what CAR's
    /// inference backends currently target.
    #[serde(default)]
    pub gpu_devices: Vec<GpuDevice>,
    /// Recommended model based on available resources.
    pub recommended_model: String,
    /// Recommended max context length in tokens.
    pub recommended_context: usize,
    /// Maximum model size in MB that fits in memory (with headroom for KV cache).
    pub max_model_mb: u64,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum GpuBackend {
    Metal,
    Cuda,
    Cpu,
}

/// Acceleration tier this build can actually drive — derived from
/// `gpu_backend` plus the OS-reported `gpu_devices` list.
///
/// The enum is intentionally narrower than the underlying detection
/// data: routing layers and Tokhn's concierge want a one-look answer
/// to "what tier is this user on" without each re-applying the
/// gpu_backend × gpu_devices × feature-flag matrix themselves.
///
/// `UnsupportedDiscreteGpu` is the case #93 exists to surface — a
/// discrete NVIDIA / AMD / Intel GPU is present but CAR's compiled
/// inference backends can't drive it yet (cuda / metal feature not
/// compiled in, or no DirectML / Vulkan / ROCm backend exists for
/// this build). Routing logic should tier these systems above
/// `Cpu`-only systems even though the actual inference path is the
/// same — they have hardware that *could* be driven once a backend
/// lands, and the routing should bias toward keeping the door open
/// (e.g. recommending GGUF + CPU-bias rather than the smallest
/// possible model).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(tag = "tier", rename_all = "snake_case")]
pub enum SupportedAcceleration {
    /// Apple Silicon with the MLX backend compiled (the default on
    /// aarch64 macOS; dropped only by `car_skip_mlx`). Active path is
    /// MLX — the candle `metal` feature is not required for this tier.
    /// MLX may execute on the Metal GPU or via Accelerate depending on
    /// the `mlx-metal` feature; either way the memory model is unified.
    Apple {
        /// Total system memory in MB; Apple Silicon's unified memory
        /// is shared between CPU and GPU.
        unified_memory_mb: u64,
    },
    /// NVIDIA with the `cuda` feature compiled. Active path is
    /// Candle + CUDA. `device_memory_mb` comes from `nvidia-smi`
    /// when available.
    Cuda { device_memory_mb: Option<u64> },
    /// Discrete GPU detected but no compiled backend can drive it.
    /// CAR falls back to CPU inference. Future DirectML / Vulkan /
    /// ROCm backends will move qualifying systems out of this tier.
    UnsupportedDiscreteGpu {
        vendor: GpuVendor,
        name: String,
        memory_mb: Option<u64>,
    },
    /// CPU-only — either no GPU at all, or only an integrated GPU
    /// without a usable inference path.
    Cpu,
}

/// One discrete or integrated GPU as reported by the OS.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct GpuDevice {
    pub vendor: GpuVendor,
    pub name: String,
    /// VRAM (or unified memory) in megabytes when the OS reports it.
    /// Linux sysfs doesn't expose this universally; Windows WMI does.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub memory_mb: Option<u64>,
}

impl GpuDevice {
    /// True when this is a discrete GPU with dedicated VRAM (RTX, RX,
    /// Arc, Radeon Pro, …) rather than an integrated/shared-memory adapter
    /// whose reported VRAM is meaningless. See [`is_discrete_gpu`].
    pub fn is_discrete(&self) -> bool {
        is_discrete_gpu(&self.vendor, &self.name)
    }
}

/// GPU vendor identity. `Other(String)` carries the raw vendor
/// string for hardware we don't yet enumerate (Moore Threads, etc.).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum GpuVendor {
    Apple,
    Nvidia,
    Amd,
    Intel,
    Other(String),
}

impl GpuVendor {
    /// Map a PCI vendor ID (Linux sysfs reports as `0x...`) to a
    /// vendor identity. The IDs are stable; AMD = 0x1002, NVIDIA =
    /// 0x10de, Intel = 0x8086.
    pub fn from_pci_id(raw: &str) -> Self {
        let id = raw.trim().trim_start_matches("0x").to_ascii_lowercase();
        match id.as_str() {
            "1002" => Self::Amd,
            "10de" => Self::Nvidia,
            "8086" => Self::Intel,
            "106b" => Self::Apple,
            other => Self::Other(other.to_string()),
        }
    }

    /// Map a free-form name (Windows WMI / macOS system_profiler) to
    /// a vendor identity. Falls back to `Other(name)` when unknown.
    pub fn from_name(name: &str) -> Self {
        let lower = name.to_ascii_lowercase();
        if lower.contains("nvidia")
            || lower.contains("geforce")
            || lower.contains("quadro")
            || lower.contains("tesla")
            || lower.contains("rtx")
            || lower.contains("gtx")
        {
            Self::Nvidia
        } else if lower.contains("amd")
            || lower.contains("radeon")
            || lower.contains("rx ")
            || lower.contains("vega")
            || lower.contains("instinct")
        {
            Self::Amd
        } else if lower.contains("intel")
            || lower.contains("arc ")
            || lower.contains("iris")
            || lower.contains("uhd graphics")
            || lower.contains("hd graphics")
        {
            Self::Intel
        } else if lower.contains("apple")
            || lower.starts_with("m1")
            || lower.starts_with("m2")
            || lower.starts_with("m3")
            || lower.starts_with("m4")
        {
            Self::Apple
        } else {
            Self::Other(name.to_string())
        }
    }
}

impl HardwareInfo {
    /// One-look acceleration tier derived from `gpu_backend` and
    /// `gpu_devices`. See [`SupportedAcceleration`] for the variant
    /// semantics.
    ///
    /// "Discrete GPU" here means *not* an integrated graphics chip —
    /// integrated GPUs share system RAM and don't typically warrant
    /// a separate routing tier from CPU. The heuristic recognises
    /// integrated parts by name (`HD Graphics`, `UHD Graphics`,
    /// `Iris`, `Vega 8/11/...` integrated APUs).
    pub fn supported_acceleration(&self) -> SupportedAcceleration {
        match self.gpu_backend {
            GpuBackend::Metal => SupportedAcceleration::Apple {
                unified_memory_mb: self.total_ram_mb,
            },
            GpuBackend::Cuda => SupportedAcceleration::Cuda {
                device_memory_mb: self.gpu_memory_mb,
            },
            GpuBackend::Cpu => {
                // Look for a discrete GPU we can't drive. Picks the
                // first matching device — multi-GPU systems pick the
                // first reported device, which is fine for tiering.
                if let Some(dev) = self
                    .gpu_devices
                    .iter()
                    .find(|d| is_discrete_gpu(&d.vendor, &d.name))
                {
                    SupportedAcceleration::UnsupportedDiscreteGpu {
                        vendor: dev.vendor.clone(),
                        name: dev.name.clone(),
                        memory_mb: dev.memory_mb,
                    }
                } else {
                    SupportedAcceleration::Cpu
                }
            }
        }
    }

    /// Auto-detect system hardware and compute recommendations.
    pub fn detect() -> Self {
        let os = detect_os();
        let arch = std::env::consts::ARCH.to_string();
        let cpu_cores = std::thread::available_parallelism()
            .map(|n| n.get())
            .unwrap_or(1);
        let total_ram_mb = detect_ram_mb();
        let gpu_backend = detect_gpu_backend();
        let gpu_memory_mb = detect_gpu_memory_mb(&gpu_backend, total_ram_mb);
        let gpu_devices = detect_gpu_devices();

        // Split the two questions model selection actually asks: what can this
        // machine run AT ALL, and what should it run for the best experience.
        //
        // `max_model_mb` (the honest ceiling): CPU inference always works off
        // system RAM, so a small discrete GPU must not lower it — it's RAM-based.
        // Sizing off VRAM alone (the prior behaviour) capped a 4 GB-GPU /
        // 16 GB-RAM box to a 0.6B ceiling the moment the CUDA build reported GPU
        // memory, even though it runs an 8B on CPU. ~60% for weights; reserve
        // ~700 MB for the embedding model family; the rest is KV cache / OS.
        //
        // `recommended_model` targets the FAST path: the largest model that runs
        // well GPU-resident. A discrete GPU needs VRAM for the KV cache and
        // activations at inference time, NOT just the weights — sizing to a flat
        // ~80% of VRAM (weights-fit) recommended a model that *loads* but OOMs
        // once a real generation's KV cache grows (observed: a 4B loaded on a
        // 4 GB card, then hit CUDA_ERROR_OUT_OF_MEMORY on a 4096-token build).
        // `gpu_recommend_budget_mb` instead holds back a working reserve, so the
        // recommendation is a model that actually runs, not just fits. On Apple
        // unified memory (Metal) VRAM ≈ RAM and on CPU there's no VRAM, so both
        // use the RAM budget. Nets 4 GB→1.7B, 8 GB→8B, 24 GB→30B, while
        // `max_model_mb` still reports the RAM-based CPU ceiling.
        let embedding_model_mb: u64 = 700;
        let ram_budget_mb = ((total_ram_mb as f64 * 0.6) as u64).saturating_sub(embedding_model_mb);
        let recommend_budget_mb =
            gpu_recommend_budget_mb(&gpu_backend, gpu_memory_mb, ram_budget_mb);
        // The ceiling is never below what we recommend (a huge GPU + tiny RAM
        // machine can still GPU-run a model larger than the RAM budget).
        let max_model_mb = ram_budget_mb.max(recommend_budget_mb);
        let available_mb = total_ram_mb.max(gpu_memory_mb.unwrap_or(0));

        let recommended_model = recommend_model(recommend_budget_mb);
        let recommended_context = recommend_context(available_mb, &recommended_model);

        Self {
            os,
            arch,
            cpu_cores,
            total_ram_mb,
            gpu_backend,
            gpu_memory_mb,
            gpu_devices,
            recommended_model,
            recommended_context,
            max_model_mb,
        }
    }

    /// When the headroom-safe [`recommended_model`](Self::recommended_model)
    /// can't do tool-use but a tool-capable model's WEIGHTS would still fit VRAM
    /// (just not with full working headroom), name that model and its caveat —
    /// so a user who needs the assistant's tool path knows the option exists.
    /// Returns `None` when the recommendation already does tools, when nothing
    /// tool-capable fits, or off a discrete GPU. Displayed under the
    /// recommendation in `car info`; not serialized (derived on demand).
    pub fn tool_capable_hint(&self) -> Option<String> {
        // Only meaningful on a discrete GPU sized by VRAM; unified-memory /
        // CPU recommendations are already RAM-budgeted.
        if !matches!(self.gpu_backend, GpuBackend::Cuda) {
            return None;
        }
        let vram = self.gpu_memory_mb?;
        if model_is_tool_capable(&self.recommended_model) {
            return None;
        }
        // The largest model whose WEIGHTS fit VRAM (a looser budget than the
        // headroom-reserved recommendation) — ~90% of VRAM for weights.
        let weights_fit = recommend_model((vram as f64 * 0.9) as u64);
        if weights_fit != self.recommended_model && model_is_tool_capable(&weights_fit) {
            Some(format!(
                "{weights_fit} adds tool-use but is tight on {vram} MB VRAM - \
                 heavy generations may fall back"
            ))
        } else {
            None
        }
    }
}

/// Whether a recommended Qwen3 model advertises tool-use, matching the catalog:
/// the 4B / 8B / 30B tiers do; the 0.6B / 1.7B tiers don't. Name-based (covers
/// the `-MLX` variants too) since this is a display hint, not a routing gate.
fn model_is_tool_capable(name: &str) -> bool {
    let l = name.to_ascii_lowercase();
    l.contains("4b") || l.contains("8b") || l.contains("30b")
}

fn detect_os() -> String {
    if cfg!(target_os = "macos") {
        "macos".into()
    } else if cfg!(target_os = "linux") {
        "linux".into()
    } else if cfg!(target_os = "windows") {
        "windows".into()
    } else {
        std::env::consts::OS.into()
    }
}

/// Memory that could be handed to a new allocation *right now*, in MB.
///
/// [`detect_ram_mb`] answers "how big is this machine", which is a constant.
/// This answers "how much is free at this instant", which is what decides
/// whether loading a multi-gigabyte model will fit or drive the box into swap.
/// Sizing a load off total RAM is how a 64 GB Mac with 900 MB free happily
/// accepts a 30 GB model.
///
/// Returns `None` when the platform can't be queried, so callers can tell
/// "no headroom" apart from "don't know" and degrade rather than hard-refuse.
pub fn available_ram_mb() -> Option<u64> {
    #[cfg(target_os = "macos")]
    {
        // Free pages alone badly understate availability on macOS: the OS parks
        // most of RAM in the inactive/purgeable lists and reclaims them on
        // demand. Counting free + inactive + purgeable matches what Activity
        // Monitor treats as reclaimable and what a large allocation can
        // actually get. Speculative pages are excluded (they belong to
        // readahead that is still useful), as is the compressor.
        let mut count: libc::mach_msg_type_number_t = (std::mem::size_of::<libc::vm_statistics64>()
            / std::mem::size_of::<libc::integer_t>())
            as libc::mach_msg_type_number_t;
        let mut stats: libc::vm_statistics64 = unsafe { std::mem::zeroed() };
        // SAFETY: `host_statistics64` fills `stats` with `count` integer_t
        // words; both the struct and the count are sized from the same type.
        //
        // `mach_host_self` is deprecated in `libc` in favour of the `mach2`
        // crate. Kept here deliberately: it still works, and pulling a new
        // dependency in for one call is not worth it. Note that Linux CI
        // cannot see this lint at all — the block is macOS-gated, so it is
        // only reachable by running clippy ON a Mac.
        #[allow(deprecated)]
        let rc = unsafe {
            libc::host_statistics64(
                libc::mach_host_self(),
                libc::HOST_VM_INFO64,
                &mut stats as *mut libc::vm_statistics64 as *mut libc::integer_t,
                &mut count,
            )
        };
        if rc == libc::KERN_SUCCESS {
            let page = page_size_bytes();
            let reclaimable = (stats.free_count as u64)
                .saturating_sub(stats.speculative_count as u64)
                + stats.inactive_count as u64
                + stats.purgeable_count as u64;
            return Some(reclaimable.saturating_mul(page) / (1024 * 1024));
        }
        return None;
    }
    #[cfg(target_os = "linux")]
    {
        // `MemAvailable` is the kernel's own estimate of what a new workload
        // can get without swapping — strictly better than free+cached math.
        let content = std::fs::read_to_string("/proc/meminfo").ok()?;
        for line in content.lines() {
            if let Some(rest) = line.strip_prefix("MemAvailable:") {
                let kb: u64 = rest.split_whitespace().next()?.parse().ok()?;
                return Some(kb / 1024);
            }
        }
        return None;
    }
    #[cfg(target_os = "windows")]
    {
        return windows_available_ram_mb();
    }
    #[allow(unreachable_code)]
    None
}

#[cfg(target_os = "macos")]
fn page_size_bytes() -> u64 {
    // SAFETY: `sysconf` with a valid name returns a long; -1 signals failure.
    let rc = unsafe { libc::sysconf(libc::_SC_PAGESIZE) };
    if rc > 0 {
        rc as u64
    } else {
        4096
    }
}

#[cfg(target_os = "windows")]
fn windows_available_ram_mb() -> Option<u64> {
    // `wmic` is deprecated and absent on recent Windows; PowerShell's CIM path
    // is the supported query. Shelling out is acceptable here only because
    // there is no libc equivalent — a failure degrades to `None`, not a wrong
    // number.
    use std::process::Command;
    let out = Command::new("powershell")
        .args([
            "-NoProfile",
            "-NonInteractive",
            "-Command",
            "(Get-CimInstance Win32_OperatingSystem).FreePhysicalMemory",
        ])
        .output()
        .ok()?;
    let kb: u64 = String::from_utf8_lossy(&out.stdout).trim().parse().ok()?;
    Some(kb / 1024)
}

fn detect_ram_mb() -> u64 {
    // macOS: read hw.memsize via the sysctlbyname syscall — NOT by shelling out
    // to `sysctl`. The subprocess form (in /usr/sbin) fails silently for
    // GUI/launchd-spawned daemons (CarHost → car-server) whose PATH lacks
    // /usr/sbin, and for sandboxed/hardened processes that can't spawn one — it
    // fell through to the 8192 fallback, so a 32 GB Mac reported 8 GB and every
    // downstream figure (GPU memory, max model, recommendation) was wrong
    // (PAR-7264). The syscall has no PATH or subprocess dependency.
    #[cfg(target_os = "macos")]
    {
        let mut size: u64 = 0;
        let mut len: libc::size_t = std::mem::size_of::<u64>();
        // SAFETY: `hw.memsize` returns a u64; we pass a pointer to `size` and its
        // exact byte length, and a null new-value (read-only query).
        let rc = unsafe {
            libc::sysctlbyname(
                c"hw.memsize".as_ptr(),
                &mut size as *mut u64 as *mut libc::c_void,
                &mut len,
                std::ptr::null_mut(),
                0,
            )
        };
        if rc == 0 && size > 0 {
            return size / (1024 * 1024);
        }
    }
    // Linux: /proc/meminfo
    #[cfg(target_os = "linux")]
    {
        if let Ok(content) = std::fs::read_to_string("/proc/meminfo") {
            for line in content.lines() {
                if line.starts_with("MemTotal:") {
                    let parts: Vec<&str> = line.split_whitespace().collect();
                    if parts.len() >= 2 {
                        if let Ok(kb) = parts[1].parse::<u64>() {
                            return kb / 1024;
                        }
                    }
                }
            }
        }
    }
    // Windows: Win32_ComputerSystem.TotalPhysicalMemory (bytes —
    // the actually-installed RAM). The original #231 §6.1 hypothesis
    // was a sysinfo field/unit bug, but the real cause was simpler:
    // this function had NO Windows branch at all and fell straight
    // through to the 8192 fallback below — so a 32 GB Hyper-V guest
    // reported 8192 MB regardless of installed RAM, and `Max model
    // size` / `Recommended model` derived from that wrong value.
    #[cfg(target_os = "windows")]
    {
        if let Some(mb) = detect_ram_mb_windows() {
            return mb;
        }
    }
    // Fallback: assume 8GB
    8192
}

/// Read total installed physical memory on Windows, in megabytes.
///
/// Prefers `wmic` (fast, no PowerShell startup cost) but falls back to
/// PowerShell `Get-CimInstance` because `wmic` is deprecated and absent
/// by default on recent Windows 11 (24H2 — the exact host in the #231
/// §6.1 report). Both surfaces expose `Win32_ComputerSystem`'s
/// `TotalPhysicalMemory`, which is the installed-RAM byte count (NOT
/// `Win32_OperatingSystem.TotalVisibleMemorySize`, which is in KB and
/// excludes hardware-reserved memory). Returns `None` if neither path
/// yields a parseable value, letting the caller fall back to 8192.
///
/// Exposed (`pub`) so other daemon components can reuse the CRLF-aware
/// Win32 detector instead of hand-rolling their own Windows RAM branch —
/// e.g. `car-server-core`'s admission controller, which sizes inference
/// concurrency off host RAM.
#[cfg(target_os = "windows")]
pub fn detect_ram_mb_windows() -> Option<u64> {
    // wmic list form: "TotalPhysicalMemory=34305015808"
    if let Ok(output) = std::process::Command::new("wmic")
        .args([
            "ComputerSystem",
            "get",
            "TotalPhysicalMemory",
            "/format:list",
        ])
        .output()
    {
        if let Ok(s) = String::from_utf8(output.stdout) {
            if let Some(mb) = parse_total_physical_memory_bytes(&s) {
                return Some(mb);
            }
        }
    }
    // PowerShell fallback emits a bare integer.
    if let Ok(output) = std::process::Command::new("powershell")
        .args([
            "-NoProfile",
            "-Command",
            "(Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory",
        ])
        .output()
    {
        if let Ok(s) = String::from_utf8(output.stdout) {
            if let Some(mb) = parse_total_physical_memory_bytes(&s) {
                return Some(mb);
            }
        }
    }
    None
}

/// Parse a `TotalPhysicalMemory` byte count from either `wmic`
/// `/format:list` output (`TotalPhysicalMemory=NNN`, surrounded by
/// blank CRLF lines) or the bare integer PowerShell prints. Returns
/// the value in megabytes. Separated from the I/O so it's unit-testable
/// without shelling out to the OS.
#[allow(dead_code)] // referenced from cfg(target_os = "windows") and from tests
fn parse_total_physical_memory_bytes(stdout: &str) -> Option<u64> {
    for line in stdout.lines() {
        let line = line.trim();
        if line.is_empty() {
            continue;
        }
        // wmic `key=value` form: only accept the right key.
        let candidate = if let Some((key, val)) = line.split_once('=') {
            if !key.trim().eq_ignore_ascii_case("TotalPhysicalMemory") {
                continue;
            }
            val.trim()
        } else {
            // PowerShell bare-integer form; non-numeric lines (any
            // header noise) fail the parse below and are skipped.
            line
        };
        if let Ok(bytes) = candidate.parse::<u64>() {
            if bytes > 0 {
                return Some(bytes / (1024 * 1024));
            }
        }
    }
    None
}

/// Heuristic — is this a discrete GPU worth tiering above CPU?
///
/// Integrated graphics (Intel HD/UHD/Iris, AMD APU iGPUs) share
/// system RAM and don't currently warrant a routing tier separate
/// from CPU even when a backend would technically run on them.
/// Discrete GPUs (RTX, RX 7000-series, Arc A-series, Radeon Pro,
/// etc.) have dedicated VRAM and the routing logic wants to know.
fn is_discrete_gpu(vendor: &GpuVendor, name: &str) -> bool {
    // Strip vendor trademark noise (`(TM)`, `(R)`, `™`, `®`) before
    // matching so heuristics work on the wire form WMIC actually
    // emits ("AMD Radeon(TM) Graphics", "Intel(R) UHD Graphics 630").
    let lower = name
        .to_ascii_lowercase()
        .replace("(tm)", "")
        .replace("(r)", "")
        .replace(['™', '®'], "");
    // Apple GPUs are always integrated unified-memory; reported on
    // Apple Silicon hosts. Caller already handles those via the
    // Metal tier — exclude here for symmetry.
    if matches!(vendor, GpuVendor::Apple) {
        return false;
    }
    // Intel: integrated unless explicitly Arc.
    if matches!(vendor, GpuVendor::Intel) {
        return lower.contains("arc ");
    }
    // AMD: integrated APU iGPUs typically have very small Vega
    // numbers (Vega 6/7/8/11) or report as the generic "AMD Radeon
    // Graphics" with no model number. Discrete cards are RX,
    // Radeon Pro, Instinct, or W-series.
    if matches!(vendor, GpuVendor::Amd) {
        let integrated_markers = [
            "vega 6",
            "vega 7",
            "vega 8",
            "vega 9",
            "vega 10",
            "vega 11",
            "radeon graphics", // generic APU label, post trademark-strip
        ];
        if integrated_markers.iter().any(|m| lower.contains(m)) {
            return false;
        }
        return true;
    }
    // NVIDIA cards are essentially always discrete (Tegra mobile
    // SoCs aren't a desktop scenario CAR targets).
    if matches!(vendor, GpuVendor::Nvidia) {
        return true;
    }
    // Other / unknown vendors — treat as discrete to stay
    // optimistic. Routing can fall back to CPU at execute time if
    // it's actually unusable.
    matches!(vendor, GpuVendor::Other(_))
}

fn detect_gpu_backend() -> GpuBackend {
    // Apple Silicon: MLX is the active inference backend and is
    // unconditionally compiled on aarch64 macOS (see Cargo.toml's
    // `[target.'cfg(...)'.dependencies] mlx-rs`), dropped only by
    // `--cfg=car_skip_mlx` for the FFI / XCFramework slices that proxy
    // inference to the daemon. So whenever MLX is in the build, the
    // honest hardware backend is Metal — independent of candle's
    // `metal` feature, which is a *separate*, secondary Apple path that
    // the release never enables. Gating Metal on `feature = "metal"`
    // (the prior behaviour) reported every Apple Silicon machine —
    // released binary included — as CPU, mis-sizing the recommender and
    // every consumer of `supported_acceleration()`. This mirrors the
    // exact cfg `recommend_model()` already uses to pick MLX models.
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    {
        GpuBackend::Metal
    }

    // Non-MLX builds (other platforms, or `car_skip_mlx`): report
    // whichever candle backend is actually compiled in. Returning a GPU
    // backend the build can't drive would lie to callers — model loading
    // would then fail at runtime. Per #93, report what we can drive.
    #[cfg(all(
        feature = "metal",
        not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))
    ))]
    {
        return GpuBackend::Metal;
    }
    // x86_64 Linux + Windows compile candle with CUDA (see
    // car-inference/Cargo.toml), so CUDA is the backend the build can drive
    // there. Runtime presence of an actual NVIDIA GPU is resolved later by
    // `cuda_if_available` at device-load time (and `nvidia-smi` in
    // `detect_gpu_memory_mb` below), so a GPU-less box still loads on CPU.
    #[cfg(all(
        any(target_os = "linux", target_os = "windows"),
        target_arch = "x86_64",
        not(car_skip_cuda),
        not(feature = "metal")
    ))]
    {
        return GpuBackend::Cuda;
    }
    // Remaining cases — CPU is all the build can drive: aarch64 Linux, macOS
    // without MLX and without candle's `metal` feature (`car_skip_mlx` or
    // x86_64 macOS), plus mobile/other targets that get the base CPU candle.
    #[cfg(all(
        not(all(
            any(target_os = "linux", target_os = "windows"),
            target_arch = "x86_64",
            not(car_skip_cuda)
        )),
        not(feature = "metal"),
        not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))
    ))]
    {
        GpuBackend::Cpu
    }
}

/// On a CUDA build (x86_64 Linux/Windows, not `car_skip_cuda`), probe whether
/// the CUDA *runtime* libraries (cuBLAS) are actually loadable. The NVIDIA
/// **driver** (`nvcuda.dll`/`libcuda.so`, in System32 / the system path) is
/// enough for `cuda_if_available` to hand back a CUDA device, but cuBLAS/cudart
/// ship in the CUDA **toolkit**, which a normal end user does not have — and the
/// first matmul then PANICS inside cudarc (`Expected symbol … 127`). This lets
/// `to_candle_device`, `car info`, and `car doctor` detect that state up front
/// and report it honestly instead of crashing mid-inference.
///
/// Returns `None` on non-CUDA builds (the question is not applicable). Probes a
/// real cuBLAS **symbol** (`cublasCreate_v2`), not just the library file: error
/// 127 is `ERROR_PROC_NOT_FOUND` (symbol missing), so a present-but-wrong-version
/// cuBLAS would pass a file-only check yet still panic. Cached — `to_candle_device`
/// can be hit repeatedly.
pub fn cuda_runtime_available() -> Option<bool> {
    #[cfg(all(
        any(target_os = "linux", target_os = "windows"),
        target_arch = "x86_64",
        not(car_skip_cuda)
    ))]
    {
        use std::sync::OnceLock;
        static CACHE: OnceLock<bool> = OnceLock::new();
        Some(*CACHE.get_or_init(probe_cublas_symbol))
    }
    #[cfg(not(all(
        any(target_os = "linux", target_os = "windows"),
        target_arch = "x86_64",
        not(car_skip_cuda)
    )))]
    {
        None
    }
}

/// Whether the NVIDIA **driver** (`nvcuda.dll` / `libcuda.so.1`) is loadable —
/// distinct from the toolkit **runtime** (cuBLAS, see
/// [`cuda_runtime_available`]). The driver lives in System32 / the system
/// loader path (always searchable), so its presence means a real NVIDIA GPU is
/// installed and `cuda_if_available` would select a CUDA device. Combined with
/// `cuda_runtime_available() == Some(false)`, this is precisely the
/// "driver but no toolkit" state that makes candle's eager cuBLAS-handle
/// creation panic — which callers must pre-empt *before* touching
/// `cuda_if_available`, since that panic is uncatchable (cudarc poisons a lazy
/// static). Returns `None` on non-CUDA builds. Cached.
pub fn nvidia_driver_present() -> Option<bool> {
    #[cfg(all(
        any(target_os = "linux", target_os = "windows"),
        target_arch = "x86_64",
        not(car_skip_cuda)
    ))]
    {
        use std::sync::OnceLock;
        static CACHE: OnceLock<bool> = OnceLock::new();
        Some(*CACHE.get_or_init(|| {
            #[cfg(target_os = "windows")]
            let name = "nvcuda.dll";
            #[cfg(target_os = "linux")]
            let name = "libcuda.so.1";
            // SAFETY: only loads a system library to test its presence; no
            // symbol is called. Unloads on drop.
            unsafe { libloading::Library::new(name).is_ok() }
        }))
    }
    #[cfg(not(all(
        any(target_os = "linux", target_os = "windows"),
        target_arch = "x86_64",
        not(car_skip_cuda)
    )))]
    {
        None
    }
}

#[cfg(all(
    any(target_os = "linux", target_os = "windows"),
    target_arch = "x86_64",
    not(car_skip_cuda)
))]
fn probe_cublas_symbol() -> bool {
    #[cfg(target_os = "windows")]
    let lib_name = "cublas64_12.dll";
    #[cfg(target_os = "linux")]
    let lib_name = "libcublas.so.12";
    // SAFETY: we only load a well-known system library and *resolve* a symbol —
    // we never call it, so there are no calling-convention preconditions to
    // uphold. `Library`/`Symbol` unload on drop.
    unsafe {
        match libloading::Library::new(lib_name) {
            Ok(lib) => lib
                .get::<unsafe extern "C" fn() -> i32>(b"cublasCreate_v2\0")
                .is_ok(),
            Err(_) => false,
        }
    }
}

fn detect_gpu_memory_mb(backend: &GpuBackend, total_ram_mb: u64) -> Option<u64> {
    match backend {
        GpuBackend::Metal => {
            // Apple Silicon has unified memory — GPU can use most of system RAM.
            // macOS reserves ~2-4GB for OS, so usable = total - 4GB
            Some(total_ram_mb.saturating_sub(4096))
        }
        GpuBackend::Cuda => {
            // Try nvidia-smi. The CLI ships with the NVIDIA driver on both
            // Linux and Windows, and the `--query-gpu/--format` invocation is
            // identical on both. macOS dropped CUDA support years ago — no
            // nvidia-smi there.
            #[cfg(any(target_os = "linux", target_os = "windows"))]
            {
                if let Ok(output) = std::process::Command::new("nvidia-smi")
                    .args(["--query-gpu=memory.total", "--format=csv,noheader,nounits"])
                    .output()
                {
                    if let Ok(s) = String::from_utf8(output.stdout) {
                        // Multi-GPU systems print one line per device. Take
                        // the first since the backend currently targets one
                        // device at a time.
                        if let Some(first) = s.lines().next() {
                            if let Ok(mb) = first.trim().parse::<u64>() {
                                return Some(mb);
                            }
                        }
                    }
                }
            }
            None
        }
        GpuBackend::Cpu => None,
    }
}

/// The NVIDIA GPUs `nvidia-smi` reports, with authoritative name + VRAM.
/// nvidia-smi is the source of truth for NVIDIA cards on both Linux and
/// Windows: Windows WMI `AdapterRAM` is a signed 32-bit field that misreports
/// VRAM past ~4 GB (and on some Optimus laptops surfaces only the integrated
/// adapter), and Linux sysfs doesn't expose NVIDIA VRAM at all. Empty when
/// nvidia-smi is absent — an AMD/Intel-only box is unaffected.
#[cfg(any(target_os = "linux", target_os = "windows"))]
fn nvidia_smi_gpus() -> Vec<GpuDevice> {
    std::process::Command::new("nvidia-smi")
        .args([
            "--query-gpu=name,memory.total",
            "--format=csv,noheader,nounits",
        ])
        .output()
        .ok()
        .and_then(|o| String::from_utf8(o.stdout).ok())
        .map(|s| parse_nvidia_smi_gpus(&s))
        .unwrap_or_default()
}

// ---------------------------------------------------------------------------
// GPU enumeration — vendor-agnostic, reports devices the OS sees regardless
// of whether CAR has an inference backend that can drive them.
// ---------------------------------------------------------------------------

fn detect_gpu_devices() -> Vec<GpuDevice> {
    #[cfg(target_os = "linux")]
    {
        return detect_gpu_devices_linux();
    }
    #[cfg(target_os = "windows")]
    {
        return detect_gpu_devices_windows();
    }
    #[cfg(target_os = "macos")]
    {
        return detect_gpu_devices_macos();
    }
    #[allow(unreachable_code)]
    Vec::new()
}

#[cfg(target_os = "linux")]
fn detect_gpu_devices_linux() -> Vec<GpuDevice> {
    let mut out = Vec::new();
    let drm = match std::fs::read_dir("/sys/class/drm") {
        Ok(d) => d,
        Err(_) => return out,
    };
    let mut seen = std::collections::HashSet::new();
    for entry in drm.flatten() {
        let name = entry.file_name();
        let s = name.to_string_lossy();
        // sysfs symlinks every output (card0-HDMI-A-1, card0-eDP-1, etc.)
        // back to the parent card. We only want the cards themselves.
        if !s.starts_with("card") || s.contains('-') {
            continue;
        }
        let device_path = entry.path().join("device");
        let vendor_id = std::fs::read_to_string(device_path.join("vendor"))
            .ok()
            .map(|s| s.trim().to_string());
        if let Some(vid) = &vendor_id {
            if !seen.insert(format!("{}:{}", vid, entry.path().display())) {
                continue;
            }
        }
        let device_name = read_drm_device_name(&device_path).unwrap_or_else(|| s.to_string());
        let vendor = vendor_id
            .as_deref()
            .map(GpuVendor::from_pci_id)
            .unwrap_or_else(|| GpuVendor::Other("unknown".into()));
        out.push(GpuDevice {
            vendor,
            name: device_name,
            memory_mb: read_drm_memory_mb(&device_path),
        });
    }
    // sysfs names NVIDIA cards "PCI device 0x…" with no VRAM; nvidia-smi has
    // the real name + VRAM and leads the list. See `reconcile_nvidia`.
    reconcile_nvidia(out, nvidia_smi_gpus())
}

#[cfg(target_os = "linux")]
fn read_drm_device_name(device: &std::path::Path) -> Option<String> {
    // Vendor-specific. AMD exposes `product_name`; NVIDIA/Intel don't
    // generally. Fall back to PCI device ID hex when no name.
    if let Ok(name) = std::fs::read_to_string(device.join("product_name")) {
        let trimmed = name.trim();
        if !trimmed.is_empty() {
            return Some(trimmed.to_string());
        }
    }
    std::fs::read_to_string(device.join("device"))
        .ok()
        .map(|s| format!("PCI device {}", s.trim()))
}

#[cfg(target_os = "linux")]
fn read_drm_memory_mb(device: &std::path::Path) -> Option<u64> {
    // AMD: mem_info_vram_total (bytes). NVIDIA needs nvidia-smi
    // (handled separately by detect_gpu_memory_mb for the CUDA
    // backend). Intel iGPUs share system RAM and don't report a fixed
    // budget here.
    if let Ok(s) = std::fs::read_to_string(device.join("mem_info_vram_total")) {
        if let Ok(bytes) = s.trim().parse::<u64>() {
            return Some(bytes / (1024 * 1024));
        }
    }
    None
}

#[cfg(target_os = "windows")]
fn detect_gpu_devices_windows() -> Vec<GpuDevice> {
    // WMI enumerates every adapter (incl. AMD/Intel integrated) but its
    // `AdapterRAM` misreports NVIDIA VRAM, so nvidia-smi is authoritative for
    // NVIDIA cards and leads the list — that makes the active CUDA device the
    // one `car info` prints as the primary "GPU:" line.
    reconcile_nvidia(wmi_gpu_devices(), nvidia_smi_gpus())
}

#[cfg(target_os = "windows")]
fn wmi_gpu_devices() -> Vec<GpuDevice> {
    // wmic is deprecated in modern Win 11 but still installed by
    // default. PowerShell `Get-CimInstance` is the modern path; use
    // it as a fallback when wmic isn't found.
    if let Ok(output) = std::process::Command::new("wmic")
        .args([
            "path",
            "Win32_VideoController",
            "get",
            "Name,AdapterRAM",
            "/format:list",
        ])
        .output()
    {
        if let Ok(s) = String::from_utf8(output.stdout) {
            return parse_windows_wmic_list(&s);
        }
    }
    if let Ok(output) = std::process::Command::new("powershell")
        .args([
            "-NoProfile",
            "-Command",
            "Get-CimInstance Win32_VideoController | Select-Object Name,AdapterRAM | ConvertTo-Csv -NoTypeInformation",
        ])
        .output()
    {
        if let Ok(s) = String::from_utf8(output.stdout) {
            return parse_windows_wmic_csv(&s);
        }
    }
    Vec::new()
}

#[cfg(target_os = "macos")]
fn detect_gpu_devices_macos() -> Vec<GpuDevice> {
    if let Ok(output) = std::process::Command::new("system_profiler")
        .args(["SPDisplaysDataType", "-json"])
        .output()
    {
        if let Ok(s) = String::from_utf8(output.stdout) {
            return parse_macos_system_profiler_json(&s);
        }
    }
    Vec::new()
}

// Parsers separated from the I/O so they're unit-testable without
// shelling out to the OS.

#[allow(dead_code)] // referenced from cfg(target_os = "windows") and from tests
fn parse_windows_wmic_list(stdout: &str) -> Vec<GpuDevice> {
    let mut out = Vec::new();
    let mut name: Option<String> = None;
    let mut adapter_ram_bytes: Option<u64> = None;
    for line in stdout.lines() {
        let line = line.trim();
        if line.is_empty() {
            if let Some(n) = name.take() {
                out.push(GpuDevice {
                    vendor: GpuVendor::from_name(&n),
                    name: n,
                    memory_mb: adapter_ram_bytes.map(|b| b / (1024 * 1024)),
                });
            }
            adapter_ram_bytes = None;
            continue;
        }
        if let Some(rest) = line.strip_prefix("Name=") {
            name = Some(rest.to_string());
        } else if let Some(rest) = line.strip_prefix("AdapterRAM=") {
            adapter_ram_bytes = rest.parse::<u64>().ok();
        }
    }
    if let Some(n) = name {
        out.push(GpuDevice {
            vendor: GpuVendor::from_name(&n),
            name: n,
            memory_mb: adapter_ram_bytes.map(|b| b / (1024 * 1024)),
        });
    }
    out
}

#[allow(dead_code)]
fn parse_windows_wmic_csv(stdout: &str) -> Vec<GpuDevice> {
    let mut out = Vec::new();
    let mut headers: Option<Vec<String>> = None;
    for line in stdout.lines() {
        let line = line.trim();
        if line.is_empty() {
            continue;
        }
        let cols: Vec<String> = line
            .split(',')
            .map(|c| c.trim().trim_matches('"').to_string())
            .collect();
        if headers.is_none() {
            headers = Some(cols);
            continue;
        }
        let h = headers.as_ref().unwrap();
        let mut name = String::new();
        let mut bytes: Option<u64> = None;
        for (i, col) in cols.iter().enumerate() {
            match h.get(i).map(|s| s.as_str()) {
                Some("Name") => name = col.clone(),
                Some("AdapterRAM") => bytes = col.parse::<u64>().ok(),
                _ => {}
            }
        }
        if !name.is_empty() {
            out.push(GpuDevice {
                vendor: GpuVendor::from_name(&name),
                name,
                memory_mb: bytes.map(|b| b / (1024 * 1024)),
            });
        }
    }
    out
}

/// Parse `nvidia-smi --query-gpu=name,memory.total --format=csv,noheader,nounits`.
/// One GPU per line, e.g. `NVIDIA GeForce RTX 2050, 4096`. The name never
/// contains a comma, so split on the last one.
fn parse_nvidia_smi_gpus(stdout: &str) -> Vec<GpuDevice> {
    let mut out = Vec::new();
    for line in stdout.lines() {
        let line = line.trim();
        if line.is_empty() {
            continue;
        }
        let (name, mem) = match line.rsplit_once(',') {
            Some((n, m)) => (n.trim(), m.trim()),
            None => (line, ""),
        };
        if name.is_empty() {
            continue;
        }
        out.push(GpuDevice {
            vendor: GpuVendor::Nvidia,
            name: name.to_string(),
            memory_mb: mem.parse::<u64>().ok(),
        });
    }
    out
}

/// Merge the authoritative `nvidia-smi` list over the OS enumerator's list:
/// NVIDIA devices lead — so the compute GPU is the primary one `car info`
/// prints and `car-bench` labels — and any NVIDIA entry the OS enumerator
/// produced with wrong/missing VRAM is dropped in favour of nvidia-smi's. A
/// box with no NVIDIA (nvidia-smi absent → empty) is returned unchanged.
fn reconcile_nvidia(base: Vec<GpuDevice>, nvidia: Vec<GpuDevice>) -> Vec<GpuDevice> {
    if nvidia.is_empty() {
        return base;
    }
    let mut out = nvidia;
    out.extend(base.into_iter().filter(|d| d.vendor != GpuVendor::Nvidia));
    out
}

#[allow(dead_code)]
fn parse_macos_system_profiler_json(stdout: &str) -> Vec<GpuDevice> {
    // system_profiler emits something like:
    // { "SPDisplaysDataType": [
    //   { "_name": "Apple M3 Max", "spdisplays_vram_shared": "...", ... }
    // ] }
    let value: serde_json::Value = match serde_json::from_str(stdout) {
        Ok(v) => v,
        Err(_) => return Vec::new(),
    };
    let displays = match value.get("SPDisplaysDataType").and_then(|v| v.as_array()) {
        Some(a) => a,
        None => return Vec::new(),
    };
    let mut out = Vec::new();
    for d in displays {
        let name = d
            .get("_name")
            .and_then(|v| v.as_str())
            .unwrap_or("")
            .to_string();
        if name.is_empty() {
            continue;
        }
        // VRAM keys vary by Mac generation. spdisplays_vram (discrete),
        // spdisplays_vram_shared (Apple Silicon unified). Both are
        // human strings like "8 GB" or "Up to 96 GB" — parse loosely.
        let memory_mb = d
            .get("spdisplays_vram")
            .or_else(|| d.get("spdisplays_vram_shared"))
            .and_then(|v| v.as_str())
            .and_then(parse_human_memory_mb);
        out.push(GpuDevice {
            vendor: GpuVendor::from_name(&name),
            name,
            memory_mb,
        });
    }
    out
}

fn parse_human_memory_mb(s: &str) -> Option<u64> {
    // "8 GB", "Up to 96 GB", "1024 MB". Find the first number then a
    // unit token after it.
    let mut number_buf = String::new();
    let mut after_number = false;
    let mut unit_buf = String::new();
    for ch in s.chars() {
        if ch.is_ascii_digit() && !after_number {
            number_buf.push(ch);
        } else if !number_buf.is_empty() && (ch.is_ascii_alphabetic()) {
            after_number = true;
            unit_buf.push(ch);
        } else if after_number && unit_buf.len() >= 2 {
            break;
        }
    }
    let value: u64 = number_buf.parse().ok()?;
    let unit = unit_buf.to_ascii_uppercase();
    let mb = if unit.starts_with("GB") {
        value * 1024
    } else if unit.starts_with("MB") {
        value
    } else if unit.starts_with("KB") {
        value / 1024
    } else {
        return None;
    };
    Some(mb)
}

/// VRAM (MB) to hold back from the model-weights budget on a discrete GPU for
/// the KV cache, activations, and driver/display overhead. A running model's
/// peak footprint is weights + a growing KV cache, not weights alone; sizing to
/// weights-fit recommended a model that loads but OOMs mid-generation (a 4B on a
/// 4 GB card OOM'd on a 4096-token build). ~2 GB is a realistic working reserve
/// for a few-thousand-token context plus activations and the driver/display.
const VRAM_RUNTIME_RESERVE_MB: u64 = 2048;

/// The model-weights budget for the RECOMMENDED (fast-path) model.
///
/// On a discrete CUDA GPU it's VRAM minus [`VRAM_RUNTIME_RESERVE_MB`] of working
/// headroom, so the recommendation is a model that runs GPU-resident WITH a live
/// KV cache — not merely one whose weights fit. On Apple unified memory (Metal)
/// or CPU there's no separate VRAM pool, so it falls back to the system-RAM
/// budget. Pure so the size bands are unit-tested.
fn gpu_recommend_budget_mb(
    gpu_backend: &GpuBackend,
    gpu_memory_mb: Option<u64>,
    ram_budget_mb: u64,
) -> u64 {
    match gpu_backend {
        GpuBackend::Cuda => gpu_memory_mb
            .map(|vram| vram.saturating_sub(VRAM_RUNTIME_RESERVE_MB))
            .unwrap_or(ram_budget_mb),
        GpuBackend::Metal | GpuBackend::Cpu => ram_budget_mb,
    }
}

/// Recommend the best model that fits in available memory.
fn recommend_model(max_model_mb: u64) -> String {
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    {
        if max_model_mb >= 17000 {
            return "Qwen3-30B-A3B-MLX".into();
        } else if max_model_mb >= 4900 {
            return "Qwen3-8B-MLX".into();
        } else if max_model_mb >= 2500 {
            return "Qwen3-4B-MLX".into();
        } else if max_model_mb >= 800 {
            return "Qwen3-1.7B-MLX".into();
        }

        "Qwen3-0.6B-MLX".into()
    }

    #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
    if max_model_mb >= 17000 {
        "Qwen3-30B-A3B".into()
    } else if max_model_mb >= 4900 {
        "Qwen3-8B".into()
    } else if max_model_mb >= 2500 {
        "Qwen3-4B".into()
    } else if max_model_mb >= 1800 {
        "Qwen3-1.7B".into()
    } else {
        "Qwen3-0.6B".into()
    }
}

/// Recommend context length based on available memory and model size.
fn recommend_context(available_mb: u64, model_name: &str) -> usize {
    let model_mb = match model_name {
        "Qwen3-0.6B" => 650,
        "Qwen3-1.7B" => 1800,
        "Qwen3-4B" => 2500,
        "Qwen3-4B-MLX" => 2400,
        "Qwen3-8B" => 4900,
        "Qwen3-8B-MLX" => 4800,
        "Qwen3-30B-A3B" => 17000,
        "Qwen3-30B-A3B-MLX" => 16500,
        "Qwen3-1.7B-MLX" => 800,
        "Qwen3-0.6B-MLX" => 500,
        _ => 650,
    };
    let kv_cost_per_1k = match model_name {
        "Qwen3-0.6B" => 0.1,
        "Qwen3-1.7B" => 0.3,
        "Qwen3-4B" => 0.5,
        "Qwen3-4B-MLX" => 0.5,
        "Qwen3-8B" => 1.0,
        "Qwen3-8B-MLX" => 1.0,
        "Qwen3-30B-A3B" => 1.5,
        "Qwen3-30B-A3B-MLX" => 1.5,
        "Qwen3-1.7B-MLX" => 0.3,
        "Qwen3-0.6B-MLX" => 0.1,
        _ => 0.1,
    };

    let kv_budget_mb = available_mb.saturating_sub(model_mb).saturating_sub(1024) as f64;
    let max_context = (kv_budget_mb / kv_cost_per_1k * 1000.0) as usize;

    max_context.clamp(2048, 131072)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn cuda_runtime_available_matches_build_and_never_panics() {
        // The whole point of the probe is that it can't panic (unlike touching
        // cudarc directly). On a CUDA build it must answer Some(_) — true or
        // false depending on whether the toolkit runtime is installed on this
        // box; on any other build the question is N/A → None. This also runs on
        // CI's CPU-only (`car_skip_cuda`) build, exercising the None branch.
        let r = cuda_runtime_available();
        #[cfg(all(
            any(target_os = "linux", target_os = "windows"),
            target_arch = "x86_64",
            not(car_skip_cuda)
        ))]
        assert!(r.is_some(), "CUDA build must resolve the probe to Some");
        #[cfg(not(all(
            any(target_os = "linux", target_os = "windows"),
            target_arch = "x86_64",
            not(car_skip_cuda)
        )))]
        assert_eq!(r, None, "non-CUDA build must report the probe as N/A");
    }

    #[test]
    fn available_ram_is_readable_and_bounded_by_total() {
        let total = detect_ram_mb();
        assert!(total > 0, "total RAM must be detectable");
        // Every platform CAR ships on can answer this; a None here means the
        // detection path regressed rather than that the machine is unusual.
        let avail = available_ram_mb().expect("available RAM must be readable");
        assert!(
            avail <= total,
            "available ({avail} MB) cannot exceed total ({total} MB)"
        );
    }

    #[test]
    fn available_ram_differs_from_total() {
        // The whole point of the function: it must not be a restatement of
        // total RAM. A machine running this test suite always has *some*
        // memory in use, so equality means we accidentally reported capacity.
        let total = detect_ram_mb();
        let avail = available_ram_mb().expect("available RAM must be readable");
        assert!(
            avail < total,
            "available ({avail} MB) == total ({total} MB) — reporting capacity, not availability"
        );
    }

    #[test]
    fn tool_capable_hint_names_the_tighter_option() {
        assert!(model_is_tool_capable("Qwen3-4B"));
        assert!(model_is_tool_capable("Qwen3-8B-MLX"));
        assert!(model_is_tool_capable("Qwen3-30B-A3B"));
        assert!(!model_is_tool_capable("Qwen3-1.7B"));
        assert!(!model_is_tool_capable("Qwen3-0.6B"));

        let hw = |backend, vram, rec: &str| HardwareInfo {
            os: "windows".into(),
            arch: "x86_64".into(),
            cpu_cores: 12,
            total_ram_mb: 16000,
            gpu_backend: backend,
            gpu_memory_mb: vram,
            gpu_devices: vec![],
            recommended_model: rec.into(),
            recommended_context: 131072,
            max_model_mb: 8643,
        };
        // 4 GB card, headroom-safe rec 1.7B → names the tool-capable 4B (fits weights).
        let hint = hw(GpuBackend::Cuda, Some(4096), "Qwen3-1.7B").tool_capable_hint();
        assert!(
            hint.as_deref().unwrap_or("").contains("Qwen3-4B"),
            "got {hint:?}"
        );
        // Already tool-capable → no note.
        assert!(hw(GpuBackend::Cuda, Some(24576), "Qwen3-30B-A3B")
            .tool_capable_hint()
            .is_none());
        // Not a discrete GPU → no note.
        assert!(hw(GpuBackend::Cpu, None, "Qwen3-1.7B")
            .tool_capable_hint()
            .is_none());
    }

    #[test]
    fn gpu_recommend_budget_reserves_working_headroom() {
        use GpuBackend::*;
        let ram = 8643; // a 16 GB box's RAM-weights budget
                        // Discrete CUDA GPU: VRAM minus the ~2 GB working reserve. A 4 GB card
                        // lands BELOW the 4B band (which OOMs mid-generation) — the headroom fix.
        assert_eq!(gpu_recommend_budget_mb(&Cuda, Some(4096), ram), 4096 - 2048);
        assert!(
            gpu_recommend_budget_mb(&Cuda, Some(4096), ram) < 2500,
            "4 GB must fall below the 4B band"
        );
        // 8 GB comfortably reaches the 8B band; 24 GB the 30B band.
        assert!(gpu_recommend_budget_mb(&Cuda, Some(8192), ram) >= 4900);
        assert!(gpu_recommend_budget_mb(&Cuda, Some(24576), ram) >= 17000);
        // A tiny GPU saturates to 0 (no underflow), not a huge wrapped value.
        assert_eq!(gpu_recommend_budget_mb(&Cuda, Some(1024), ram), 0);
        // No VRAM figure, or Metal (unified) / CPU: fall back to the RAM budget.
        assert_eq!(gpu_recommend_budget_mb(&Cuda, None, ram), ram);
        assert_eq!(gpu_recommend_budget_mb(&Metal, Some(16384), ram), ram);
        assert_eq!(gpu_recommend_budget_mb(&Cpu, None, ram), ram);
    }

    #[test]
    fn parse_total_physical_memory_wmic_list() {
        // wmic /format:list wraps the key=value in blank CRLF lines.
        let out = "\r\n\r\nTotalPhysicalMemory=34305015808\r\n\r\n";
        // 34305015808 / 1024 / 1024 = 32715 MB (~32 GB).
        assert_eq!(parse_total_physical_memory_bytes(out), Some(32715));
    }

    #[test]
    fn parse_total_physical_memory_powershell_bare_integer() {
        assert_eq!(
            parse_total_physical_memory_bytes("34305015808\r\n"),
            Some(32715)
        );
    }

    // The syscall-based RAM read must agree with `sysctl -n hw.memsize`. In
    // dev/CI the subprocess works (PATH has /usr/sbin) so this guards the
    // syscall implementation itself; the reason we switched TO the syscall is it
    // ALSO works in GUI/launchd/sandboxed contexts where the subprocess silently
    // failed → the 8192 fallback → a 32 GB Mac reported as 8 GB (PAR-7264).
    #[cfg(target_os = "macos")]
    #[test]
    fn macos_ram_detection_matches_sysctl() {
        let got = detect_ram_mb();
        assert!(
            got >= 1024,
            "RAM detection returned implausibly low {got} MB"
        );
        if let Ok(o) = std::process::Command::new("sysctl")
            .args(["-n", "hw.memsize"])
            .output()
        {
            if let Ok(s) = String::from_utf8(o.stdout) {
                if let Ok(bytes) = s.trim().parse::<u64>() {
                    assert_eq!(
                        got,
                        bytes / (1024 * 1024),
                        "sysctlbyname read disagrees with `sysctl` subprocess"
                    );
                }
            }
        }
    }

    #[test]
    fn parse_total_physical_memory_rejects_garbage_and_zero() {
        assert_eq!(parse_total_physical_memory_bytes(""), None);
        assert_eq!(parse_total_physical_memory_bytes("not a number\r\n"), None);
        assert_eq!(
            parse_total_physical_memory_bytes("TotalPhysicalMemory=0"),
            None
        );
        // Wrong key must not be picked up.
        assert_eq!(
            parse_total_physical_memory_bytes("TotalVisibleMemorySize=8388608"),
            None
        );
    }

    #[test]
    fn pci_id_to_vendor_known() {
        assert_eq!(GpuVendor::from_pci_id("0x1002"), GpuVendor::Amd);
        assert_eq!(GpuVendor::from_pci_id("0x10de"), GpuVendor::Nvidia);
        assert_eq!(GpuVendor::from_pci_id("0x8086"), GpuVendor::Intel);
        assert_eq!(GpuVendor::from_pci_id("0x10DE"), GpuVendor::Nvidia);
    }

    #[test]
    fn pci_id_to_vendor_unknown_falls_through() {
        match GpuVendor::from_pci_id("0xabcd") {
            GpuVendor::Other(s) => assert_eq!(s, "abcd"),
            other => panic!("expected Other, got {other:?}"),
        }
    }

    #[test]
    fn name_to_vendor_picks_amd_radeon() {
        assert_eq!(
            GpuVendor::from_name("AMD Radeon RX 7900 XTX"),
            GpuVendor::Amd
        );
        assert_eq!(GpuVendor::from_name("Radeon Pro 580X"), GpuVendor::Amd);
    }

    #[test]
    fn name_to_vendor_picks_nvidia() {
        assert_eq!(
            GpuVendor::from_name("NVIDIA GeForce RTX 4090"),
            GpuVendor::Nvidia
        );
        assert_eq!(GpuVendor::from_name("Quadro P2200"), GpuVendor::Nvidia);
    }

    #[test]
    fn name_to_vendor_picks_intel_arc_and_iris() {
        assert_eq!(GpuVendor::from_name("Intel Arc A770"), GpuVendor::Intel);
        assert_eq!(
            GpuVendor::from_name("Intel Iris Xe Graphics"),
            GpuVendor::Intel
        );
    }

    #[test]
    fn name_to_vendor_picks_apple_silicon() {
        assert_eq!(GpuVendor::from_name("Apple M3 Max"), GpuVendor::Apple);
    }

    #[test]
    fn parse_wmic_list_two_devices() {
        // Real wmic /format:list output has CRLF + blank line separators.
        let stdout = "\r\nName=NVIDIA GeForce RTX 4090\r\nAdapterRAM=25756221440\r\n\r\nName=Intel UHD Graphics 770\r\nAdapterRAM=1073741824\r\n\r\n";
        let devices = parse_windows_wmic_list(stdout);
        assert_eq!(devices.len(), 2);
        assert_eq!(devices[0].vendor, GpuVendor::Nvidia);
        assert_eq!(devices[0].name, "NVIDIA GeForce RTX 4090");
        assert_eq!(devices[0].memory_mb, Some(25756221440 / (1024 * 1024)));
        assert_eq!(devices[1].vendor, GpuVendor::Intel);
        assert_eq!(devices[1].memory_mb, Some(1024));
    }

    #[test]
    fn parse_wmic_list_handles_missing_ram() {
        // Some virtual adapters omit AdapterRAM. memory_mb stays None.
        let stdout = "Name=Microsoft Basic Display Adapter\r\n\r\n";
        let devices = parse_windows_wmic_list(stdout);
        assert_eq!(devices.len(), 1);
        assert_eq!(devices[0].memory_mb, None);
    }

    #[test]
    fn parse_nvidia_smi_reads_name_and_vram() {
        // `--query-gpu=name,memory.total --format=csv,noheader,nounits`; the
        // name contains spaces (never a comma), memory is bare MB.
        let stdout = "NVIDIA GeForce RTX 2050, 4096\r\nNVIDIA A100-SXM4-40GB, 40960\n";
        let devices = parse_nvidia_smi_gpus(stdout);
        assert_eq!(devices.len(), 2);
        assert_eq!(devices[0].vendor, GpuVendor::Nvidia);
        assert_eq!(devices[0].name, "NVIDIA GeForce RTX 2050");
        assert_eq!(devices[0].memory_mb, Some(4096));
        assert_eq!(devices[1].name, "NVIDIA A100-SXM4-40GB");
        assert_eq!(devices[1].memory_mb, Some(40960));
    }

    #[test]
    fn reconcile_leads_with_nvidia_and_drops_wmi_duplicate() {
        // The exact shape of the bug: WMI reports only the AMD integrated
        // adapter (VRAM misreported as 512 MB); nvidia-smi has the real RTX.
        // Reconciled list must LEAD with the NVIDIA card (so it's the primary
        // "GPU:" line) and keep the AMD entry after it.
        let wmi = vec![GpuDevice {
            vendor: GpuVendor::Amd,
            name: "AMD Radeon(TM) Graphics".into(),
            memory_mb: Some(512),
        }];
        let smi = vec![GpuDevice {
            vendor: GpuVendor::Nvidia,
            name: "NVIDIA GeForce RTX 2050".into(),
            memory_mb: Some(4096),
        }];
        let merged = reconcile_nvidia(wmi, smi);
        assert_eq!(merged.len(), 2);
        assert_eq!(merged[0].vendor, GpuVendor::Nvidia);
        assert_eq!(merged[0].memory_mb, Some(4096));
        assert_eq!(merged[1].vendor, GpuVendor::Amd);
    }

    #[test]
    fn reconcile_replaces_a_wmi_nvidia_entry_with_smi() {
        // When WMI *does* list the NVIDIA (with a bad 32-bit AdapterRAM), the
        // duplicate is dropped in favour of nvidia-smi's accurate VRAM.
        let wmi = vec![GpuDevice {
            vendor: GpuVendor::Nvidia,
            name: "NVIDIA GeForce RTX 2050".into(),
            memory_mb: Some(512), // wrong: AdapterRAM cap
        }];
        let smi = vec![GpuDevice {
            vendor: GpuVendor::Nvidia,
            name: "NVIDIA GeForce RTX 2050".into(),
            memory_mb: Some(4096),
        }];
        let merged = reconcile_nvidia(wmi, smi);
        assert_eq!(merged.len(), 1);
        assert_eq!(merged[0].memory_mb, Some(4096));
    }

    #[test]
    fn reconcile_no_nvidia_leaves_list_untouched() {
        let wmi = vec![GpuDevice {
            vendor: GpuVendor::Amd,
            name: "AMD Radeon".into(),
            memory_mb: Some(8192),
        }];
        let merged = reconcile_nvidia(wmi.clone(), vec![]);
        assert_eq!(merged, wmi);
    }

    #[test]
    fn gpu_device_is_discrete_flags_integrated_apu_and_rtx() {
        // The APU iGPU on the dev box — `car info` hides this when a discrete
        // GPU is present.
        let apu = GpuDevice {
            vendor: GpuVendor::Amd,
            name: "AMD Radeon(TM) Graphics".into(),
            memory_mb: Some(512),
        };
        assert!(!apu.is_discrete());
        let rtx = GpuDevice {
            vendor: GpuVendor::Nvidia,
            name: "NVIDIA GeForce RTX 2050".into(),
            memory_mb: Some(4096),
        };
        assert!(rtx.is_discrete());
    }

    #[test]
    fn parse_macos_system_profiler_apple_silicon() {
        let stdout = r#"{
          "SPDisplaysDataType": [
            {
              "_name": "Apple M3 Max",
              "spdisplays_vram_shared": "Up to 96 GB"
            }
          ]
        }"#;
        let devices = parse_macos_system_profiler_json(stdout);
        assert_eq!(devices.len(), 1);
        assert_eq!(devices[0].vendor, GpuVendor::Apple);
        assert_eq!(devices[0].memory_mb, Some(96 * 1024));
    }

    #[test]
    fn parse_macos_system_profiler_discrete_amd() {
        let stdout = r#"{
          "SPDisplaysDataType": [
            {
              "_name": "AMD Radeon Pro 5500M",
              "spdisplays_vram": "8 GB"
            }
          ]
        }"#;
        let devices = parse_macos_system_profiler_json(stdout);
        assert_eq!(devices.len(), 1);
        assert_eq!(devices[0].vendor, GpuVendor::Amd);
        assert_eq!(devices[0].memory_mb, Some(8 * 1024));
    }

    #[test]
    fn parse_macos_system_profiler_handles_garbage() {
        assert!(parse_macos_system_profiler_json("not json").is_empty());
        assert!(parse_macos_system_profiler_json("{}").is_empty());
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn live_macos_detection_returns_at_least_one_device() {
        // system_profiler is part of the base macOS install — not
        // gated by Xcode tools. Should always return at least the
        // built-in GPU on a Mac.
        let devices = detect_gpu_devices_macos();
        assert!(
            !devices.is_empty(),
            "expected at least one GPU device on macOS",
        );
    }

    #[test]
    fn human_memory_parser() {
        assert_eq!(parse_human_memory_mb("8 GB"), Some(8 * 1024));
        assert_eq!(parse_human_memory_mb("Up to 96 GB"), Some(96 * 1024));
        assert_eq!(parse_human_memory_mb("1024 MB"), Some(1024));
        assert_eq!(parse_human_memory_mb("nope"), None);
    }

    fn hw_with_devices(backend: GpuBackend, devices: Vec<GpuDevice>) -> HardwareInfo {
        HardwareInfo {
            os: "linux".into(),
            arch: "x86_64".into(),
            cpu_cores: 8,
            total_ram_mb: 32_000,
            gpu_backend: backend,
            gpu_memory_mb: None,
            gpu_devices: devices,
            recommended_model: String::new(),
            recommended_context: 4096,
            max_model_mb: 0,
        }
    }

    #[test]
    fn discrete_gpu_heuristic() {
        // NVIDIA is always discrete in CAR's target.
        assert!(is_discrete_gpu(&GpuVendor::Nvidia, "GeForce RTX 4090"));

        // AMD: discrete cards yes, APU iGPUs no.
        assert!(is_discrete_gpu(&GpuVendor::Amd, "Radeon RX 7900 XTX"));
        assert!(is_discrete_gpu(&GpuVendor::Amd, "Radeon Pro W7900"));
        assert!(!is_discrete_gpu(&GpuVendor::Amd, "Radeon Vega 8 Graphics"));
        assert!(!is_discrete_gpu(&GpuVendor::Amd, "AMD Radeon(TM) Graphics"));

        // Intel: only Arc counts as discrete.
        assert!(is_discrete_gpu(
            &GpuVendor::Intel,
            "Intel Arc A770 Graphics"
        ));
        assert!(!is_discrete_gpu(
            &GpuVendor::Intel,
            "Intel(R) UHD Graphics 630"
        ));
        assert!(!is_discrete_gpu(
            &GpuVendor::Intel,
            "Intel Iris Xe Graphics"
        ));

        // Apple GPUs are unified-memory, never "discrete" in this sense.
        assert!(!is_discrete_gpu(&GpuVendor::Apple, "Apple M3 Max"));
    }

    #[test]
    fn supported_acceleration_metal_apple_silicon() {
        let hw = hw_with_devices(
            GpuBackend::Metal,
            vec![GpuDevice {
                vendor: GpuVendor::Apple,
                name: "Apple M3".into(),
                memory_mb: None,
            }],
        );
        match hw.supported_acceleration() {
            SupportedAcceleration::Apple { unified_memory_mb } => {
                assert_eq!(unified_memory_mb, 32_000);
            }
            other => panic!("expected Apple, got {:?}", other),
        }
    }

    // Regression guard for the bug where `detect_gpu_backend()` gated
    // Metal on candle's `feature = "metal"` (never enabled in release)
    // and so reported every Apple Silicon machine — released binary
    // included — as CPU, even though MLX is the active, always-compiled
    // backend. Runs only where MLX is in the build (the same cfg the
    // detection and `recommend_model()` use).
    #[test]
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    fn detect_gpu_backend_reports_metal_on_apple_silicon() {
        assert_eq!(detect_gpu_backend(), GpuBackend::Metal);
        let hw = HardwareInfo::detect();
        assert!(
            matches!(
                hw.supported_acceleration(),
                SupportedAcceleration::Apple { .. }
            ),
            "expected Apple tier on Apple Silicon, got {:?}",
            hw.supported_acceleration()
        );
    }

    #[test]
    fn supported_acceleration_cuda_with_memory() {
        let mut hw = hw_with_devices(
            GpuBackend::Cuda,
            vec![GpuDevice {
                vendor: GpuVendor::Nvidia,
                name: "GeForce RTX 4090".into(),
                memory_mb: Some(24_000),
            }],
        );
        hw.gpu_memory_mb = Some(24_000);
        match hw.supported_acceleration() {
            SupportedAcceleration::Cuda { device_memory_mb } => {
                assert_eq!(device_memory_mb, Some(24_000));
            }
            other => panic!("expected Cuda, got {:?}", other),
        }
    }

    #[test]
    fn supported_acceleration_unsupported_amd_discrete() {
        let hw = hw_with_devices(
            GpuBackend::Cpu,
            vec![GpuDevice {
                vendor: GpuVendor::Amd,
                name: "Radeon RX 7900 XTX".into(),
                memory_mb: Some(24_000),
            }],
        );
        match hw.supported_acceleration() {
            SupportedAcceleration::UnsupportedDiscreteGpu {
                vendor,
                name,
                memory_mb,
            } => {
                assert_eq!(vendor, GpuVendor::Amd);
                assert!(name.contains("7900"));
                assert_eq!(memory_mb, Some(24_000));
            }
            other => panic!("expected UnsupportedDiscreteGpu, got {:?}", other),
        }
    }

    #[test]
    fn supported_acceleration_integrated_falls_to_cpu() {
        // Intel UHD Graphics is integrated — same tier as CPU-only.
        let hw = hw_with_devices(
            GpuBackend::Cpu,
            vec![GpuDevice {
                vendor: GpuVendor::Intel,
                name: "Intel(R) UHD Graphics 630".into(),
                memory_mb: None,
            }],
        );
        assert_eq!(hw.supported_acceleration(), SupportedAcceleration::Cpu);
    }

    #[test]
    fn supported_acceleration_no_gpu_at_all() {
        let hw = hw_with_devices(GpuBackend::Cpu, vec![]);
        assert_eq!(hw.supported_acceleration(), SupportedAcceleration::Cpu);
    }
}