Skip to main content

qualia_core_db/q42/
machine_gpu_profile.rs

1//! Machine GPU capability profile — which **native** tiers beat portable WGSL here.
2//!
3//! WGSL is the universal floor (WebGPU / wgpu). HLSL+DXC, CUDA-C/NVRTC/WMMA, MSL, SPIR-V,
4//! subgroups, and coopmat are higher tiers when present. This profile records what the host
5//! actually has and which decode path was measured best, so install/runtime can prefer
6//! native performance instead of defaulting forever to the WGSL baseline.
7//!
8//! On disk: `machine-gpu-profile.json` (campaign / passport adjacent).
9
10use serde::{Deserialize, Serialize};
11use std::path::{Path, PathBuf};
12
13pub const MACHINE_GPU_PROFILE_VERSION: u32 = 1;
14pub const MACHINE_GPU_PROFILE_NAME: &str = "machine-gpu-profile.json";
15
16#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
17pub struct ToolchainAvailability {
18    pub wgpu: bool,
19    pub cuda_toolkit: bool,
20    /// DXC CLI for HLSL→SPIR-V/DXIL (`dxc` / QUALIA_DXC_CLI_PATH). Distinct from QUALIA_DXC_PATH (dxcompiler.dll for wgpu).
21    pub dxc_cli: bool,
22    pub metal_xcrun: bool,
23}
24
25#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
26pub struct AdapterFeatures {
27    pub name: String,
28    pub backend: String,
29    pub discrete: bool,
30    pub subgroups: bool,
31    pub coopmat: bool,
32    pub shader_f16: bool,
33    pub timestamp_query: bool,
34    pub topology_hash: String,
35}
36
37/// One measured decode path (backend + mode + package).
38#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
39pub struct MeasuredDecodePath {
40    pub wgpu_backend: String,
41    pub inference_mode: String,
42    pub p64_path: String,
43    pub tok_s: f64,
44    pub coherence_ok: bool,
45    pub tokens: u32,
46}
47
48/// Recommended runtime configuration for **this machine**.
49#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
50pub struct RecommendedPath {
51    /// e.g. `vulkan` | `dx12` | `metal`
52    pub wgpu_backend: String,
53    /// e.g. `fast-verify` | `portable` | `cuda`
54    pub inference_mode: String,
55    /// Why this beats baseline.
56    pub rationale: String,
57    /// Optional QUALIA_* env to apply.
58    pub env: Vec<(String, String)>,
59}
60
61#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
62pub struct MachineGpuProfile {
63    pub version: u32,
64    pub written_unix_ms: u64,
65    pub host: String,
66    pub toolchain: ToolchainAvailability,
67    pub adapter: AdapterFeatures,
68    /// Native tiers that exist on this host (ordered preference for work that can use them).
69    pub native_tiers: Vec<String>,
70    pub measured_paths: Vec<MeasuredDecodePath>,
71    pub recommended: RecommendedPath,
72    pub notes: Vec<String>,
73}
74
75impl MachineGpuProfile {
76    /// Current time in ms.
77    pub fn now_ms() -> u64 {
78        std::time::SystemTime::now()
79            .duration_since(std::time::UNIX_EPOCH)
80            .map(|d| d.as_millis() as u64)
81            .unwrap_or(0)
82    }
83
84    /// Default profile path under `out_dir`.
85    pub fn default_path(out_dir: &Path) -> PathBuf {
86        out_dir.join(MACHINE_GPU_PROFILE_NAME)
87    }
88
89    /// Serializes the profile to `path`.
90    pub fn write_json(&self, path: &Path) -> Result<(), String> {
91        let json = serde_json::to_string_pretty(self).map_err(|e| format!("serialize: {e}"))?;
92        if let Some(parent) = path.parent() {
93            std::fs::create_dir_all(parent).map_err(|e| format!("mkdir: {e}"))?;
94        }
95        std::fs::write(path, json).map_err(|e| format!("write {}: {e}", path.display()))
96    }
97
98    /// Loads a profile from `path`; `None` when absent.
99    pub fn load_json(path: &Path) -> Result<Option<Self>, String> {
100        if !path.is_file() {
101            return Ok(None);
102        }
103        let bytes = std::fs::read(path).map_err(|e| format!("read: {e}"))?;
104        let p: Self = serde_json::from_slice(&bytes).map_err(|e| format!("parse: {e}"))?;
105        Ok(Some(p))
106    }
107
108    /// Pick best coherent measured path by tok/s.
109    pub fn recompute_recommended(&mut self) {
110        let best = self
111            .measured_paths
112            .iter()
113            .filter(|p| p.coherence_ok)
114            .max_by(|a, b| {
115                a.tok_s
116                    .partial_cmp(&b.tok_s)
117                    .unwrap_or(std::cmp::Ordering::Equal)
118            });
119        if let Some(b) = best {
120            self.recommended = RecommendedPath {
121                wgpu_backend: b.wgpu_backend.clone(),
122                inference_mode: b.inference_mode.clone(),
123                rationale: format!(
124                    "highest coherent decode-proxy {:.2} tok/s on {} + {} (package {})",
125                    b.tok_s, b.wgpu_backend, b.inference_mode, b.p64_path
126                ),
127                env: vec![
128                    ("QUALIA_WGPU_BACKEND".into(), b.wgpu_backend.clone()),
129                    ("QUALIA_INFERENCE_MODE".into(), b.inference_mode.clone()),
130                ],
131            };
132        }
133    }
134
135    /// Renders a PowerShell env script for this profile.
136    pub fn apply_env_script_ps1(&self) -> String {
137        // ASCII only: Windows PowerShell 5.1 reads BOM-less files as ANSI.
138        let mut s = String::from(
139            "# Machine GPU capability profile: prefer native over WGSL-only defaults\n",
140        );
141        for (k, v) in &self.recommended.env {
142            s.push_str(&format!("$env:{k}='{v}'\n"));
143        }
144        s.push_str(
145            "# Forge: CUDA densify decode GEMV stays lab-only unless you know the package\n",
146        );
147        s.push_str(
148            "# $env:QUALIA_LLM_CUDA_TC_DECODE='1'  # only after oracle green for that layout\n",
149        );
150        s
151    }
152}
153
154#[cfg(test)]
155mod tests {
156    use super::*;
157
158    #[test]
159    fn recompute_picks_fastest_coherent() {
160        let mut p = MachineGpuProfile {
161            version: 1,
162            written_unix_ms: 0,
163            host: "test".into(),
164            toolchain: Default::default(),
165            adapter: Default::default(),
166            native_tiers: vec!["cuda".into(), "vulkan".into()],
167            measured_paths: vec![
168                MeasuredDecodePath {
169                    wgpu_backend: "dx12".into(),
170                    inference_mode: "portable".into(),
171                    p64_path: "a.p64".into(),
172                    tok_s: 40.0,
173                    coherence_ok: true,
174                    tokens: 16,
175                },
176                MeasuredDecodePath {
177                    wgpu_backend: "vulkan".into(),
178                    inference_mode: "fast-verify".into(),
179                    p64_path: "a.p64".into(),
180                    tok_s: 100.0,
181                    coherence_ok: true,
182                    tokens: 16,
183                },
184                MeasuredDecodePath {
185                    wgpu_backend: "dx12".into(),
186                    inference_mode: "cuda".into(),
187                    p64_path: "a.p64".into(),
188                    tok_s: 200.0,
189                    coherence_ok: false,
190                    tokens: 16,
191                },
192            ],
193            recommended: Default::default(),
194            notes: vec![],
195        };
196        p.recompute_recommended();
197        assert_eq!(p.recommended.wgpu_backend, "vulkan");
198        assert_eq!(p.recommended.inference_mode, "fast-verify");
199
200        // Windows PowerShell 5.1 reads BOM-less files as ANSI: non-ASCII would render as mojibake.
201        let ps1 = p.apply_env_script_ps1();
202        assert!(ps1.is_ascii(), "apply script must be ASCII: {ps1}");
203        assert!(ps1.contains("$env:QUALIA_WGPU_BACKEND='vulkan'"));
204        assert!(ps1.contains("$env:QUALIA_INFERENCE_MODE='fast-verify'"));
205    }
206}