1use 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 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#[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#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
50pub struct RecommendedPath {
51 pub wgpu_backend: String,
53 pub inference_mode: String,
55 pub rationale: String,
57 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 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 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 pub fn default_path(out_dir: &Path) -> PathBuf {
86 out_dir.join(MACHINE_GPU_PROFILE_NAME)
87 }
88
89 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 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 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 pub fn apply_env_script_ps1(&self) -> String {
137 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 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}