hematite/agent/
diagnose_why.rs

1/// Symptom-driven cross-topic root-cause diagnosis — no model required.
2///
3/// Maps a user's plain-English symptom to a curated topic group, runs all
4/// topics, collects findings via the fix-recipe engine, and returns a ranked
5/// diagnosis with evidence excerpts from the live output.
6
7pub struct SymptomGroup {
8    pub category: &'static str,
9    pub keywords: &'static [&'static str],
10    pub topics: &'static [&'static str],
11}
12
13static SYMPTOM_GROUPS: &[SymptomGroup] = &[
14    SymptomGroup {
15        category: "Performance / Sluggishness",
16        keywords: &[
17            "slow",
18            "sluggish",
19            "lag",
20            "laggy",
21            "freeze",
22            "freezing",
23            "hang",
24            "hanging",
25            "unresponsive",
26            "high cpu",
27            "cpu usage",
28            "cpu spike",
29            "pc slow",
30            "computer slow",
31            "running slow",
32        ],
33        topics: &["resource_load", "processes", "thermal", "pagefile", "disk"],
34    },
35    SymptomGroup {
36        category: "Crash / Blue Screen",
37        keywords: &[
38            "bsod",
39            "blue screen",
40            "unexpected restart",
41            "restart unexpectedly",
42            "kernel panic",
43            "stop error",
44            "bugcheck",
45            "system crash",
46            "pc crashed",
47            "computer crashed",
48            "pc restart unexpectedly",
49        ],
50        topics: &[
51            "recent_crashes",
52            "disk_health",
53            "drivers",
54            "device_health",
55            "memory",
56        ],
57    },
58    SymptomGroup {
59        category: "No Internet / Offline",
60        keywords: &[
61            "no internet",
62            "no network",
63            "can't connect",
64            "cannot connect",
65            "offline",
66            "no connection",
67            "internet not working",
68            "internet down",
69            "can't browse",
70            "cannot browse",
71            "websites not loading",
72        ],
73        topics: &["connectivity", "wifi", "dns_cache", "vpn", "proxy"],
74    },
75    SymptomGroup {
76        category: "Slow Internet / Network",
77        keywords: &[
78            "slow internet",
79            "slow network",
80            "slow wifi",
81            "slow connection",
82            "high latency",
83            "packet loss",
84            "bad ping",
85            "buffering",
86            "low bandwidth",
87            "speed",
88            "network slow",
89        ],
90        topics: &["latency", "wifi", "connections", "network_stats"],
91    },
92    SymptomGroup {
93        category: "Slow Boot / Startup",
94        keywords: &[
95            "slow startup",
96            "slow boot",
97            "boot slow",
98            "startup slow",
99            "takes forever to start",
100            "takes long to start",
101            "long boot",
102            "long startup",
103            "slow to start",
104            "startup takes",
105        ],
106        topics: &["startup_items", "services", "disk", "pending_reboot"],
107    },
108    SymptomGroup {
109        category: "Overheating / Thermal",
110        keywords: &[
111            "hot",
112            "overheating",
113            "overheat",
114            "thermal",
115            "fan noise",
116            "fan loud",
117            "temperature",
118            "cpu temp",
119            "gpu temp",
120            "throttling",
121            "running hot",
122        ],
123        topics: &["thermal", "overclocker", "resource_load"],
124    },
125    SymptomGroup {
126        category: "No Sound / Audio",
127        keywords: &[
128            "no sound",
129            "no audio",
130            "audio not working",
131            "sound not working",
132            "microphone not working",
133            "mic not working",
134            "speakers not working",
135            "headphones not working",
136            "audio broken",
137            "can't hear",
138        ],
139        topics: &["audio", "services", "device_health"],
140    },
141    SymptomGroup {
142        category: "Printer / Printing",
143        keywords: &[
144            "can't print",
145            "cannot print",
146            "printer not working",
147            "print queue",
148            "printer offline",
149            "stuck print",
150            "printing problem",
151            "print error",
152        ],
153        topics: &["printers", "print_spooler", "services"],
154    },
155    SymptomGroup {
156        category: "High Disk Usage",
157        keywords: &[
158            "disk at 100",
159            "disk 100%",
160            "disk usage high",
161            "high disk usage",
162            "disk thrashing",
163            "disk maxed",
164            "storage full",
165            "drive full",
166            "low disk space",
167            "out of disk space",
168        ],
169        topics: &[
170            "processes",
171            "storage",
172            "storage_deep",
173            "pagefile",
174            "disk_health",
175        ],
176    },
177    SymptomGroup {
178        category: "Windows Updates Failing",
179        keywords: &[
180            "updates failing",
181            "update error",
182            "update not working",
183            "windows update broken",
184            "update stuck",
185            "update failed",
186            "can't update",
187            "cannot update",
188            "updates won't install",
189        ],
190        topics: &["updates", "installer_health", "services", "pending_reboot"],
191    },
192    SymptomGroup {
193        category: "Sign-In / Authentication",
194        keywords: &[
195            "can't sign in",
196            "cannot sign in",
197            "login not working",
198            "password wrong",
199            "pin not working",
200            "fingerprint not working",
201            "hello not working",
202            "can't log in",
203            "account locked",
204            "authentication failed",
205            "sign-in failed",
206        ],
207        topics: &["sign_in", "identity_auth", "credentials"],
208    },
209    SymptomGroup {
210        category: "Malware / Suspicious Activity",
211        keywords: &[
212            "virus",
213            "malware",
214            "infected",
215            "suspicious",
216            "ransomware",
217            "trojan",
218            "spyware",
219            "adware",
220            "defender found",
221            "threat",
222            "unusual activity",
223            "something suspicious",
224        ],
225        topics: &[
226            "defender_quarantine",
227            "startup_items",
228            "connections",
229            "services",
230        ],
231    },
232    SymptomGroup {
233        category: "Low Memory / RAM",
234        keywords: &[
235            "out of memory",
236            "low memory",
237            "memory leak",
238            "ram usage high",
239            "not enough memory",
240            "memory full",
241            "ram maxed",
242            "memory pressure",
243            "high ram",
244            "high memory",
245        ],
246        topics: &["resource_load", "processes", "pagefile"],
247    },
248    SymptomGroup {
249        category: "Battery / Power",
250        keywords: &[
251            "battery",
252            "battery dying",
253            "battery not charging",
254            "short battery",
255            "power plan",
256            "cpu slow",
257            "plugged in not charging",
258        ],
259        topics: &["battery", "cpu_power", "thermal"],
260    },
261    SymptomGroup {
262        category: "Display / Screen",
263        keywords: &[
264            "screen flickering",
265            "display problem",
266            "resolution wrong",
267            "wrong resolution",
268            "black screen",
269            "monitor not detected",
270            "display not working",
271            "screen issues",
272            "flickering",
273        ],
274        topics: &["display_config", "drivers", "device_health"],
275    },
276    SymptomGroup {
277        category: "Hardware / Device Error",
278        keywords: &[
279            "device not working",
280            "hardware error",
281            "hardware not recognized",
282            "yellow bang",
283            "device manager error",
284            "unknown device",
285            "peripheral not working",
286            "usb not working",
287        ],
288        topics: &["device_health", "drivers", "peripherals"],
289    },
290    SymptomGroup {
291        category: "Network Share / Drive Access",
292        keywords: &[
293            "can't access share",
294            "network drive not working",
295            "mapped drive",
296            "shared folder not accessible",
297            "smb",
298            "unc path",
299            "network path",
300            "can't see network",
301            "network share",
302        ],
303        topics: &["shares", "services", "connectivity", "firewall_rules"],
304    },
305    SymptomGroup {
306        category: "Microsoft Teams Problems",
307        keywords: &[
308            "teams not working",
309            "teams crashing",
310            "teams won't open",
311            "teams won't start",
312            "teams black screen",
313            "teams slow",
314            "teams freezing",
315            "teams keeps crashing",
316            "teams microphone",
317            "teams camera",
318            "teams audio",
319            "teams video",
320            "teams sign-in",
321            "teams login",
322            "teams can't join",
323            "teams meeting issue",
324            "teams echo",
325            "teams no sound",
326            "teams not loading",
327            "microsoft teams",
328            "teams",
329            "meeting",
330        ],
331        topics: &[
332            "teams",
333            "identity_auth",
334            "audio",
335            "camera",
336            "browser_health",
337        ],
338    },
339    SymptomGroup {
340        category: "Outlook / Email Problems",
341        keywords: &[
342            "outlook not working",
343            "outlook crashing",
344            "outlook won't open",
345            "outlook slow",
346            "outlook not syncing",
347            "email not working",
348            "email not syncing",
349            "outlook freezing",
350            "outlook keeps crashing",
351            "outlook error",
352            "can't send email",
353            "can't receive email",
354            "outlook profile",
355            "outlook add-in",
356            "new outlook",
357            "outlook calendar",
358            "ost file",
359            "outlook",
360            "email not",
361        ],
362        topics: &["outlook", "identity_auth", "installer_health"],
363    },
364    SymptomGroup {
365        category: "Bluetooth Problems",
366        keywords: &[
367            "bluetooth not working",
368            "bluetooth won't pair",
369            "can't pair",
370            "bluetooth device not found",
371            "bluetooth keeps disconnecting",
372            "bluetooth headphones not working",
373            "bluetooth speaker not working",
374            "bluetooth mouse not working",
375            "bluetooth keyboard not working",
376            "bluetooth adapter",
377            "bluetooth radio",
378            "pairing failed",
379            "bluetooth audio",
380            "airpods not connecting",
381        ],
382        topics: &["bluetooth", "audio", "device_health", "services"],
383    },
384    SymptomGroup {
385        category: "Camera / Webcam Problems",
386        keywords: &[
387            "camera not working",
388            "webcam not working",
389            "camera not detected",
390            "camera blocked",
391            "camera privacy",
392            "webcam black screen",
393            "camera in use",
394            "camera busy",
395            "no camera",
396            "webcam not showing",
397            "camera not found",
398            "video not working",
399            "can't use camera",
400        ],
401        topics: &["camera", "device_health", "drivers", "services"],
402    },
403    SymptomGroup {
404        category: "USB / Device Not Recognized",
405        keywords: &[
406            "usb not recognized",
407            "usb not working",
408            "device not recognized",
409            "usb device not found",
410            "usb keeps disconnecting",
411            "usb drops",
412            "flash drive not showing",
413            "external drive not showing",
414            "usb port not working",
415            "keyboard not working",
416            "mouse not working",
417            "external hard drive not detected",
418            "usb connection",
419        ],
420        topics: &["peripherals", "device_health", "drivers", "usb_history"],
421    },
422    SymptomGroup {
423        category: "Sleep / Wake Problems",
424        keywords: &[
425            "won't sleep",
426            "won't wake",
427            "can't wake",
428            "sleep not working",
429            "sleep mode broken",
430            "pc won't go to sleep",
431            "wakes up randomly",
432            "wakes itself",
433            "wake on lan",
434            "hibernate not working",
435            "screen won't turn off",
436            "sleep then restart",
437            "stuck after sleep",
438            "black screen after sleep",
439            "won't resume",
440        ],
441        topics: &[
442            "services",
443            "device_health",
444            "drivers",
445            "scheduled_tasks",
446            "pending_reboot",
447        ],
448    },
449    SymptomGroup {
450        category: "App / Program Crashing",
451        keywords: &[
452            "app keeps crashing",
453            "program crashing",
454            "application crash",
455            "keeps closing",
456            "randomly closes",
457            "crashes after opening",
458            "word crashing",
459            "excel crashing",
460            "chrome crashing",
461            "edge crashing",
462            "firefox crashing",
463            "discord crashing",
464            "photoshop crashing",
465            "app crash",
466            "software crash",
467            "program won't open",
468            "keeps crashing",
469        ],
470        topics: &[
471            "app_crashes",
472            "installer_health",
473            "device_health",
474            "log_check",
475        ],
476    },
477];
478
479/// Find the best matching symptom group for the given user query.
480/// Returns `None` if no keywords match.
481pub fn match_symptom(query: &str) -> Option<&'static SymptomGroup> {
482    let lower = query.to_ascii_lowercase();
483    // Pick the group with the most keyword hits for best specificity.
484    SYMPTOM_GROUPS
485        .iter()
486        .map(|g| {
487            let hits = g.keywords.iter().filter(|k| lower.contains(*k)).count();
488            (hits, g)
489        })
490        .filter(|(hits, _)| *hits > 0)
491        .max_by_key(|(hits, _)| *hits)
492        .map(|(_, g)| g)
493}
494
495pub struct DiagnosisResult {
496    pub category: &'static str,
497    pub topics_run: Vec<&'static str>,
498    pub findings: Vec<Finding>,
499    pub raw_output: String,
500}
501
502pub struct Finding {
503    pub severity: &'static str,
504    pub title: &'static str,
505    pub steps: Vec<&'static str>,
506    pub evidence: Vec<String>,
507    pub dig_deeper: Option<&'static str>,
508}
509
510/// Extract up to `max` lines from `haystack` that contain any of `keywords`.
511/// Returns them as evidence excerpts.
512fn extract_evidence(haystack: &str, keywords: &[&str], max: usize) -> Vec<String> {
513    let lower_hay = haystack.to_ascii_lowercase();
514    let mut out: Vec<String> = Vec::new();
515    for (line, lower_line) in haystack.lines().zip(lower_hay.lines()) {
516        if out.len() >= max {
517            break;
518        }
519        let trimmed = line.trim();
520        if trimmed.is_empty() || trimmed.starts_with('#') || trimmed.starts_with("──") {
521            continue;
522        }
523        if keywords.iter().any(|k| lower_line.contains(k)) {
524            out.push(trimmed.to_string());
525        }
526    }
527    out
528}
529
530/// Build a diagnosis from raw multi-topic output using the fix-recipe engine.
531pub fn build_diagnosis(group: &'static SymptomGroup, raw_output: &str) -> DiagnosisResult {
532    use crate::agent::fix_recipes::match_recipes;
533
534    let recipes = match_recipes(raw_output);
535
536    // Sort: ACTION first, INVESTIGATE second, MONITOR last.
537    let severity_rank = |s: &str| match s {
538        "ACTION" => 0u8,
539        "INVESTIGATE" => 1,
540        _ => 2,
541    };
542
543    let mut sorted_recipes: Vec<_> = recipes.into_iter().collect();
544    sorted_recipes.sort_by_key(|r| severity_rank(r.severity));
545
546    let findings = sorted_recipes
547        .into_iter()
548        .map(|r| {
549            // Build evidence: look for lines related to this finding's trigger words
550            // by searching with the recipe title keywords in the raw output.
551            let title_words: Vec<&str> =
552                r.title.split_whitespace().filter(|w| w.len() > 3).collect();
553            let evidence = extract_evidence(raw_output, &title_words, 2);
554            Finding {
555                severity: r.severity,
556                title: r.title,
557                steps: r.steps.to_vec(),
558                evidence,
559                dig_deeper: r.dig_deeper,
560            }
561        })
562        .collect();
563
564    DiagnosisResult {
565        category: group.category,
566        topics_run: group.topics.to_vec(),
567        findings,
568        raw_output: raw_output.to_string(),
569    }
570}
hematite/agent/diagnose_why.rs

hematite/agent/
diagnose_why.rs
