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