Skip to main content

rigspark_runtime/
diagnostics.rs

1use crate::hardware::command_output;
2use rigspark_core::{
3    advice::{hardware_score, unified},
4    catalog::{BACKENDS, Catalog},
5    reports::{gib, strip_control, table},
6    sizing::{Hardware, memory_capacity},
7};
8use serde::{Deserialize, Serialize};
9use serde_json::{Value, json};
10
11#[derive(Debug, Deserialize, Serialize)]
12#[serde(rename_all = "camelCase", deny_unknown_fields)]
13pub struct BackendInfo {
14    pub name: String,
15    pub installed: bool,
16    pub version: Option<String>,
17    pub is_default: bool,
18    pub install_hint: String,
19}
20
21pub async fn probe_backends(hardware: &Hardware) -> Vec<BackendInfo> {
22    probe_available_backends(Some(hardware)).await
23}
24
25pub async fn probe_available_backends(hardware: Option<&Hardware>) -> Vec<BackendInfo> {
26    let apple = hardware.is_some_and(unified);
27    probe_with(apple, &SystemBackendProbe).await
28}
29
30#[async_trait::async_trait]
31trait BackendProbe: Sync {
32    async fn installed(&self, name: &str, program: &str) -> Result<bool, String>;
33    async fn version(&self, name: &str, program: &str, args: &[&str]) -> Result<String, String>;
34}
35
36struct SystemBackendProbe;
37
38#[async_trait::async_trait]
39impl BackendProbe for SystemBackendProbe {
40    async fn installed(&self, name: &str, program: &str) -> Result<bool, String> {
41        if name == "bitnet" {
42            return crate::process_control::resolve_bitnet_server().map(|_| true);
43        }
44        if name == "mlx" {
45            return command_output(program, &["-c", "import mlx_lm"])
46                .await
47                .map(|_| true)
48                .map_err(|error| error.to_string());
49        }
50        Ok(crate::process_control::resolve_binary(program).is_ok())
51    }
52
53    async fn version(&self, name: &str, program: &str, args: &[&str]) -> Result<String, String> {
54        if name == "bitnet" {
55            let path = crate::process_control::resolve_bitnet_server()?;
56            return command_output(path.to_str().ok_or("invalid BitNet executable path")?, args)
57                .await
58                .map_err(|error| error.to_string());
59        }
60        command_output(program, args)
61            .await
62            .map_err(|error| error.to_string())
63    }
64}
65
66async fn probe_with(apple: bool, probe: &impl BackendProbe) -> Vec<BackendInfo> {
67    let mut result = Vec::new();
68    for name in BACKENDS {
69        let (program, args): (&str, &[&str]) = match name {
70            "ollama" => ("ollama", &["--version"]),
71            "llamacpp" => ("llama-server", &["--version"]),
72            "bitnet" => ("bitnet", &["--version"]),
73            "mlx" => (
74                "python3",
75                &[
76                    "-c",
77                    "import importlib.metadata; print(importlib.metadata.version('mlx-lm'))",
78                ],
79            ),
80            _ => ("lms", &["--version"]),
81        };
82        let installed = if name == "mlx" && !apple {
83            false
84        } else {
85            probe.installed(name, program).await.unwrap_or(false)
86        };
87        let version = if installed {
88            probe
89                .version(name, program, args)
90                .await
91                .ok()
92                .map(|text| strip_control(text.trim()))
93                .filter(|text| !text.is_empty())
94        } else {
95            None
96        };
97        result.push(BackendInfo {
98            name: name.into(),
99            installed,
100            version,
101            is_default: false,
102            install_hint: match name {
103                "ollama" => "https://ollama.com/download",
104                "llamacpp" => "https://github.com/ggml-org/llama.cpp",
105                "mlx" => "python3 -m pip install mlx-lm",
106                "bitnet" => "Build https://github.com/microsoft/BitNet and set RIGSPARK_BITNET_SERVER to its absolute llama-server path",
107                _ => "https://lmstudio.ai/download",
108            }
109            .into(),
110        });
111    }
112    let priority: &[&str] = if apple {
113        &["mlx", "ollama", "llamacpp"]
114    } else {
115        &["ollama", "llamacpp"]
116    };
117    let selected = priority
118        .iter()
119        .find(|name| {
120            result
121                .iter()
122                .any(|entry| entry.name == **name && entry.installed)
123        })
124        .copied();
125    for entry in &mut result {
126        entry.is_default = selected == Some(entry.name.as_str());
127    }
128    result
129}
130
131pub fn report(
132    catalog: &Catalog,
133    hardware: &Hardware,
134    backends: &[BackendInfo],
135    state_exists: bool,
136) -> Value {
137    report_inputs(Ok(catalog), Ok(hardware), backends, state_exists)
138}
139
140fn hardware_check(hardware: &Hardware) -> Value {
141    let (_, usable) = memory_capacity(hardware);
142    let summary = format!(
143        "{}/{}, {} usable memory, {} free disk",
144        if hardware.arch == rigspark_core::sizing::CpuArch::Arm64 {
145            "arm64"
146        } else {
147            "x64"
148        },
149        match hardware.platform {
150            rigspark_core::sizing::Platform::Darwin => "darwin",
151            rigspark_core::sizing::Platform::Win32 => "win32",
152            _ => "linux",
153        },
154        gib(usable),
155        gib(hardware.free_disk_bytes)
156    );
157    if usable < 1073741824.0 {
158        json!({"name":"hardware","status":"fail","detail":format!("insufficient usable memory to run a model ({summary})")})
159    } else {
160        json!({"name":"hardware","status":"ok","detail":summary})
161    }
162}
163
164fn catalog_check(catalog: &Catalog) -> Value {
165    let unverified: Vec<_> = catalog
166        .models
167        .iter()
168        .flat_map(|model| {
169            model
170                .quantizations
171                .iter()
172                .filter(|quant| quant.digest_verified == Some(false))
173                .map(|quant| {
174                    format!(
175                        "{} ({})",
176                        strip_control(&model.id),
177                        strip_control(&quant.name)
178                    )
179                })
180        })
181        .collect();
182    if catalog.models.is_empty() {
183        json!({"name":"catalog", "status":"warn", "detail":"catalog contains no models"})
184    } else {
185        json!({"name":"catalog","status":if unverified.is_empty() { "ok" } else { "warn" },"detail":if unverified.is_empty() { format!("{} model(s), all digests verified",catalog.models.len()) } else { format!("{} quantization(s) have digestVerified:false — size-only verify: {}",unverified.len(),unverified.join(", ")) }})
186    }
187}
188
189pub fn report_inputs(
190    catalog: Result<&Catalog, &str>,
191    hardware: Result<&Hardware, &str>,
192    backends: &[BackendInfo],
193    state_exists: bool,
194) -> Value {
195    let failed = |name: &str, prefix: &str, error: &str| json!({"name":name,"status":"fail","detail":format!("{prefix}: {}",strip_control(error))});
196    let hardware_check = hardware
197        .map(hardware_check)
198        .unwrap_or_else(|error| failed("hardware", "hardware detection failed", error));
199    let catalog_check = catalog
200        .map(catalog_check)
201        .unwrap_or_else(|error| failed("catalog", "catalog is unusable", error));
202    let backend = backends.first().map_or(json!({"name":"backend","status":"fail","detail":"no backend registered"}), |backend| json!({"name":"backend","status":if backend.installed { "ok" } else { "fail" },"detail":if backend.installed { format!("{} is installed",backend.name) } else { format!("{} is not installed — run: {}",backend.name,backend.install_hint) }}));
203    let state = if state_exists {
204        json!({"name":"state","status":"warn","detail":"runtime state exists; active-server readiness not checked by the offline Rust doctor (Checkpoint 3)"})
205    } else {
206        json!({"name":"state","status":"ok","detail":"no active server recorded"})
207    };
208    let checks = vec![hardware_check, backend, catalog_check, state];
209    json!({"ok":checks.iter().all(|check| check["status"] != "fail"),"checks":checks,"hardwareScore":hardware.ok().map(hardware_score),"backends":backends})
210}
211
212pub fn format_report(report: &Value) -> String {
213    let checks = report["checks"]
214        .as_array()
215        .into_iter()
216        .flatten()
217        .map(|check| {
218            vec![
219                check["name"].as_str().unwrap_or("").into(),
220                check["status"].as_str().unwrap_or("").to_uppercase(),
221                check["detail"].as_str().unwrap_or("").into(),
222            ]
223        })
224        .collect();
225    let backends = report["backends"]
226        .as_array()
227        .into_iter()
228        .flatten()
229        .map(|backend| {
230            vec![
231                backend["name"].as_str().unwrap_or("").into(),
232                if backend["installed"] == true {
233                    "yes".into()
234                } else {
235                    "no".into()
236                },
237                backend["version"].as_str().unwrap_or("unknown").into(),
238                if backend["isDefault"] == true {
239                    "yes".into()
240                } else {
241                    "".into()
242                },
243                if backend["installed"] == true {
244                    "".into()
245                } else {
246                    format!(
247                        "not installed — run: {}",
248                        backend["installHint"].as_str().unwrap_or("")
249                    )
250                },
251            ]
252        })
253        .collect();
254    let bottleneck = match report["hardwareScore"]["bottleneck"].as_str().unwrap_or("") {
255        "vram" => "VRAM",
256        "ram" => "RAM",
257        "compute" => "Compute",
258        "storage" => "Storage",
259        _ => "unknown",
260    };
261    let score = report["hardwareScore"]["total"]
262        .as_f64()
263        .map_or_else(|| "unknown".into(), |score| format!("{score}/100"));
264    format!(
265        "{}\n\nBackends\n{}\n\nAI Hardware Score: {}\nPrimary bottleneck: {bottleneck}\n\n{}\n",
266        table(
267            &[("Check", false), ("Status", false), ("Detail", false)],
268            checks
269        ),
270        table(
271            &[
272                ("Backend", false),
273                ("Installed", false),
274                ("Version", false),
275                ("Default", false),
276                ("Detail", false)
277            ],
278            backends
279        ),
280        score,
281        if report["ok"] == true {
282            "All checks passed."
283        } else {
284            "Problems found — see FAIL rows above."
285        }
286    )
287}
288
289#[cfg(test)]
290mod probe_tests {
291    use super::*;
292
293    struct Probe {
294        absent: bool,
295    }
296
297    #[async_trait::async_trait]
298    impl BackendProbe for Probe {
299        async fn installed(&self, name: &str, _program: &str) -> Result<bool, String> {
300            if name == "llamacpp" {
301                return Err("broken discovery".into());
302            }
303            Ok(!self.absent)
304        }
305        async fn version(
306            &self,
307            name: &str,
308            _program: &str,
309            _args: &[&str],
310        ) -> Result<String, String> {
311            if name == "ollama" {
312                return Err("broken version".into());
313            }
314            Ok("  version\u{1b}[31m\nspoof  ".into())
315        }
316    }
317
318    #[tokio::test]
319    async fn backend_probes_isolate_failures_preserve_installation_and_choose_platform_default() {
320        for apple in [false, true] {
321            let rows = probe_with(apple, &Probe { absent: false }).await;
322            assert_eq!(rows.len(), 5);
323            let bitnet = rows.iter().find(|row| row.name == "bitnet").unwrap();
324            assert!(bitnet.installed);
325            assert!(!bitnet.is_default);
326            assert!(bitnet.install_hint.contains("RIGSPARK_BITNET_SERVER"));
327            let ollama = rows.iter().find(|row| row.name == "ollama").unwrap();
328            assert!(ollama.installed);
329            assert!(ollama.version.is_none());
330            assert!(
331                !rows
332                    .iter()
333                    .find(|row| row.name == "llamacpp")
334                    .unwrap()
335                    .installed
336            );
337            assert_eq!(
338                rows.iter().find(|row| row.name == "mlx").unwrap().installed,
339                apple
340            );
341            let defaults: Vec<_> = rows
342                .iter()
343                .filter(|row| row.is_default)
344                .map(|row| row.name.as_str())
345                .collect();
346            assert_eq!(defaults, vec![if apple { "mlx" } else { "ollama" }]);
347            for row in rows {
348                assert!(!row.install_hint.is_empty());
349                if let Some(version) = row.version {
350                    assert!(!version.contains(['\u{1b}', '\n']));
351                }
352            }
353        }
354        let rows = probe_with(true, &Probe { absent: true }).await;
355        assert!(
356            rows.iter()
357                .all(|row| !row.installed && !row.is_default && row.version.is_none())
358        );
359    }
360
361    struct StudioOnly;
362    #[async_trait::async_trait]
363    impl BackendProbe for StudioOnly {
364        async fn installed(&self, name: &str, _program: &str) -> Result<bool, String> {
365            Ok(name == "lmstudio")
366        }
367        async fn version(&self, _: &str, _: &str, _: &[&str]) -> Result<String, String> {
368            Ok("0.3.0".into())
369        }
370    }
371
372    #[tokio::test]
373    async fn attach_only_lm_studio_is_never_the_auto_selected_default() {
374        for apple in [false, true] {
375            let rows = probe_with(apple, &StudioOnly).await;
376            assert!(
377                rows.iter()
378                    .any(|row| row.name == "lmstudio" && row.installed)
379            );
380            assert!(rows.iter().all(|row| !row.is_default));
381        }
382    }
383}