Skip to main content

fetchium_core/ai/
setup.rs

1//! Device-aware Ollama setup guidance and model recommendations.
2//!
3//! Detects RAM, CPU, and architecture, then recommends the best Ollama models
4//! that fit safely in available memory. Provides `ollama pull` commands and
5//! per-model descriptions so users can set up with one command.
6
7use sysinfo::System;
8
9/// Hardware profile of the current machine.
10#[derive(Debug, Clone)]
11pub struct DeviceSpec {
12    /// Total RAM in gigabytes (rounded).
13    pub total_ram_gb: f64,
14    /// Number of logical CPU cores.
15    pub cpu_cores: usize,
16    /// True on Apple M-series (fast unified memory, CPU+GPU shared).
17    pub is_apple_silicon: bool,
18    /// Approximate free RAM available for a model (total minus OS overhead).
19    pub usable_ram_gb: f64,
20}
21
22impl DeviceSpec {
23    /// Detect the current machine's hardware spec.
24    pub fn detect() -> Self {
25        let mut sys = System::new_all();
26        sys.refresh_all();
27
28        let total_bytes = sys.total_memory();
29        let total_ram_gb = total_bytes as f64 / (1024.0 * 1024.0 * 1024.0);
30
31        // Reserve ~4 GB for OS + other processes (conservative on Intel/AMD).
32        // Apple Silicon shares memory, so deduct less.
33        let is_apple_silicon = detect_apple_silicon();
34        let os_overhead_gb = if is_apple_silicon { 3.0 } else { 4.5 };
35        let usable_ram_gb = (total_ram_gb - os_overhead_gb).max(0.5);
36
37        Self {
38            total_ram_gb,
39            cpu_cores: sys.cpus().len(),
40            is_apple_silicon,
41            usable_ram_gb,
42        }
43    }
44}
45
46/// A single Ollama model recommendation with setup guidance.
47#[derive(Debug, Clone)]
48pub struct ModelRecommendation {
49    /// Ollama model tag (e.g. `"qwen3:14b"`).
50    pub name: &'static str,
51    /// Approximate VRAM/RAM needed for Q4_K_M quantization.
52    pub size_gb: f64,
53    /// One-line description of the model's strengths.
54    pub description: &'static str,
55    /// Recommendation category.
56    pub category: RecommendCategory,
57}
58
59/// Why a model is being recommended.
60#[derive(Debug, Clone, Copy, PartialEq, Eq)]
61pub enum RecommendCategory {
62    /// Best balance of quality and speed for this device.
63    BestForDevice,
64    /// Fastest option that still produces good results.
65    FastAndLight,
66    /// Maximum quality the device can run without swapping.
67    MaxQuality,
68    /// Specialised reasoning model (slower but more accurate for logic tasks).
69    Reasoning,
70    /// Requires more RAM than available; will use swap — not recommended.
71    TooLarge,
72}
73
74impl RecommendCategory {
75    pub fn label(&self) -> &'static str {
76        match self {
77            Self::BestForDevice => "BEST FOR YOU",
78            Self::FastAndLight => "FAST & LIGHT",
79            Self::MaxQuality => "MAX QUALITY",
80            Self::Reasoning => "REASONING",
81            Self::TooLarge => "TOO LARGE (swap risk)",
82        }
83    }
84}
85
86/// All models we know about, in descending quality order.
87/// size_gb is Q4_K_M quantization footprint.
88static KNOWN_MODELS: &[(&str, f64, &str)] = &[
89    (
90        "qwen3:30b-a3b",
91        17.0,
92        "Qwen3 30B MoE (3B active) — best reasoning with low compute cost",
93    ),
94    (
95        "deepseek-r1:32b",
96        20.0,
97        "DeepSeek-R1 32B — state-of-the-art reasoning, large context",
98    ),
99    (
100        "qwen3:14b",
101        9.0,
102        "Qwen3 14B — best quality/size ratio, multilingual, tool use",
103    ),
104    (
105        "deepseek-r1:14b",
106        9.0,
107        "DeepSeek-R1 14B — chain-of-thought reasoning, 128k context",
108    ),
109    (
110        "gemma3:12b",
111        7.5,
112        "Gemma3 12B — Google's best 12B, strong at code and analysis",
113    ),
114    (
115        "qwen3:8b",
116        5.0,
117        "Qwen3 8B — fast, accurate, excellent at following instructions",
118    ),
119    (
120        "deepseek-r1:7b",
121        4.7,
122        "DeepSeek-R1 7B — reasoning specialist, great for Q&A",
123    ),
124    (
125        "gemma3:9b",
126        5.5,
127        "Gemma3 9B — well-rounded, fast, strong at code",
128    ),
129    ("qwen3:4b", 2.6, "Qwen3 4B — compact, surprisingly capable"),
130    (
131        "phi3:mini",
132        2.3,
133        "Phi-3 Mini — Microsoft's 3.8B, punches above its weight",
134    ),
135    (
136        "gemma3:2b",
137        1.8,
138        "Gemma3 2B — smallest useful model, good for simple Q&A",
139    ),
140    (
141        "qwen3:1.7b",
142        1.2,
143        "Qwen3 1.7B — ultra-light, CPU-only viable",
144    ),
145    (
146        "gemma3:1b",
147        0.8,
148        "Gemma3 1B — absolute minimum, fast even on old hardware",
149    ),
150];
151
152/// Build a ranked, categorised recommendation list for this device.
153pub fn recommend_models(spec: &DeviceSpec) -> Vec<ModelRecommendation> {
154    let usable = spec.usable_ram_gb;
155    let mut recs: Vec<ModelRecommendation> = Vec::new();
156
157    // Determine tiers based on usable RAM
158    let best_name = best_model_name(usable);
159    let fast_name = fast_model_name(usable);
160    let max_name = max_quality_model_name(usable);
161    let reason_name = reasoning_model_name(usable);
162
163    for &(name, size_gb, description) in KNOWN_MODELS {
164        if size_gb > usable + 2.0 {
165            // Way too big — skip entirely unless it is "just over" (show as TooLarge warning)
166            if size_gb > usable + 6.0 {
167                continue;
168            }
169        }
170
171        let category = if name == best_name {
172            RecommendCategory::BestForDevice
173        } else if Some(name) == fast_name {
174            RecommendCategory::FastAndLight
175        } else if Some(name) == max_name && name != best_name {
176            RecommendCategory::MaxQuality
177        } else if Some(name) == reason_name && name != best_name {
178            RecommendCategory::Reasoning
179        } else if size_gb > usable {
180            RecommendCategory::TooLarge
181        } else {
182            continue; // Don't include models that don't fit any category
183        };
184
185        recs.push(ModelRecommendation {
186            name,
187            size_gb,
188            description,
189            category,
190        });
191    }
192
193    // Sort: BestForDevice first, TooLarge last
194    recs.sort_by_key(|r| match r.category {
195        RecommendCategory::BestForDevice => 0,
196        RecommendCategory::FastAndLight => 1,
197        RecommendCategory::MaxQuality => 2,
198        RecommendCategory::Reasoning => 3,
199        RecommendCategory::TooLarge => 4,
200    });
201
202    recs
203}
204
205/// The single best model name for the given usable RAM.
206pub fn best_model_name(usable_gb: f64) -> &'static str {
207    match usable_gb as u64 {
208        u if u >= 28 => "qwen3:30b-a3b", // 17 GB — fits in 32GB machines
209        u if u >= 20 => "qwen3:14b",     // 9 GB — best in class for 24GB
210        u if u >= 11 => "qwen3:14b",     // 9 GB — fits safely in 16GB
211        u if u >= 6 => "qwen3:8b",       // 5 GB — best for 8-12GB
212        u if u >= 4 => "deepseek-r1:7b", // 4.7 GB — small but reasoning-focused
213        u if u >= 2 => "qwen3:4b",       // 2.6 GB
214        _ => "gemma3:1b",                // Absolute minimum
215    }
216}
217
218fn fast_model_name(usable_gb: f64) -> Option<&'static str> {
219    match usable_gb as u64 {
220        u if u >= 11 => Some("qwen3:8b"),
221        u if u >= 6 => Some("deepseek-r1:7b"),
222        u if u >= 3 => Some("phi3:mini"),
223        _ => None,
224    }
225}
226
227fn max_quality_model_name(usable_gb: f64) -> Option<&'static str> {
228    match usable_gb as u64 {
229        u if u >= 28 => Some("deepseek-r1:32b"),
230        u if u >= 11 => Some("deepseek-r1:14b"),
231        u if u >= 6 => Some("gemma3:9b"),
232        _ => None,
233    }
234}
235
236fn reasoning_model_name(usable_gb: f64) -> Option<&'static str> {
237    match usable_gb as u64 {
238        u if u >= 11 => Some("deepseek-r1:14b"),
239        u if u >= 5 => Some("deepseek-r1:7b"),
240        _ => None,
241    }
242}
243
244/// Format a full Ollama setup guide as a string, ready to print to the terminal.
245///
246/// Includes:
247/// - Install command for Ollama
248/// - Device-specific model table with pull commands
249/// - One-command quick-start for the best model
250pub fn format_setup_guide(spec: &DeviceSpec) -> String {
251    let recs = recommend_models(spec);
252    let best = best_model_name(spec.usable_ram_gb);
253
254    let mut out = String::new();
255
256    out.push_str("┌─ Ollama Setup Guide ────────────────────────────────────────────┐\n");
257    out.push_str("│  Ollama is not running. Follow these steps:                      │\n");
258    out.push_str("└─────────────────────────────────────────────────────────────────┘\n\n");
259
260    // Step 1 — install
261    out.push_str("  Step 1 — Install Ollama\n");
262    out.push_str("  ────────────────────────────────────────\n");
263    out.push_str("    macOS / Linux:  curl -fsSL https://ollama.ai/install.sh | sh\n");
264    out.push_str("    Windows:        https://ollama.ai/download\n\n");
265
266    // Step 2 — pull a model
267    out.push_str("  Step 2 — Pull a model for your machine\n");
268    out.push_str("  ────────────────────────────────────────\n");
269    out.push_str(&format!(
270        "  Your device: {:.0} GB RAM, {} cores{}\n",
271        spec.total_ram_gb,
272        spec.cpu_cores,
273        if spec.is_apple_silicon {
274            ", Apple Silicon (fast)"
275        } else {
276            ", Intel/AMD (CPU inference)"
277        }
278    ));
279    out.push_str(&format!(
280        "  Usable for LLM: ~{:.0} GB\n\n",
281        spec.usable_ram_gb
282    ));
283
284    for rec in &recs {
285        let marker = if rec.name == best { "→" } else { " " };
286        out.push_str(&format!(
287            "  {marker} [{:16}]  {:<22}  ~{:.0} GB  {}\n",
288            rec.category.label(),
289            rec.name,
290            rec.size_gb,
291            rec.description
292        ));
293        out.push_str(&format!("      ollama pull {}\n\n", rec.name));
294    }
295
296    // Quick-start
297    out.push_str("  ─────────────────────────────────────────────────────────────────\n");
298    out.push_str("  Quick-start (best model for your device):\n\n");
299    out.push_str("    ollama serve &\n");
300    out.push_str(&format!("    ollama pull {best}\n"));
301    out.push_str("    fetchium ai \"your question\"\n\n");
302
303    out.push_str(
304        "  After pulling a model, re-run your command — fetchium will detect it automatically.\n",
305    );
306    out.push_str(
307        "  Tip: Add `default_model = \"{best}\"` to ~/.fetchium/config.toml to always use it.\n",
308    );
309
310    out
311}
312
313/// Format a short one-line hint when no models are installed.
314pub fn format_no_models_hint(spec: &DeviceSpec) -> String {
315    let best = best_model_name(spec.usable_ram_gb);
316    format!(
317        "No models installed. Run: ollama pull {best}\n  \
318         Then re-run your command. Use `fetchium doctor` for a full setup guide."
319    )
320}
321
322fn detect_apple_silicon() -> bool {
323    #[cfg(target_os = "macos")]
324    {
325        std::process::Command::new("uname")
326            .arg("-m")
327            .output()
328            .map(|o| String::from_utf8_lossy(&o.stdout).contains("arm64"))
329            .unwrap_or(false)
330    }
331    #[cfg(not(target_os = "macos"))]
332    {
333        false
334    }
335}
336
337#[cfg(test)]
338mod tests {
339    use super::*;
340
341    fn spec(ram_gb: f64) -> DeviceSpec {
342        DeviceSpec {
343            total_ram_gb: ram_gb,
344            cpu_cores: 8,
345            is_apple_silicon: false,
346            usable_ram_gb: (ram_gb - 4.5).max(0.5),
347        }
348    }
349
350    #[test]
351    fn best_model_for_64gb() {
352        assert_eq!(best_model_name(60.0), "qwen3:30b-a3b");
353    }
354
355    #[test]
356    fn best_model_for_16gb() {
357        // 16GB - 4.5 OS = 11.5 usable → qwen3:14b
358        assert_eq!(best_model_name(spec(16.0).usable_ram_gb), "qwen3:14b");
359    }
360
361    #[test]
362    fn best_model_for_8gb() {
363        // 8GB - 4.5 OS = 3.5 usable → deepseek-r1:7b
364        let s = spec(8.0);
365        let b = best_model_name(s.usable_ram_gb);
366        // 3.5 GB usable → qwen3:4b
367        assert!(b == "qwen3:4b" || b == "deepseek-r1:7b");
368    }
369
370    #[test]
371    fn best_model_for_4gb() {
372        let s = spec(4.0);
373        // negative usable → gemma3:1b
374        assert_eq!(best_model_name(s.usable_ram_gb), "gemma3:1b");
375    }
376
377    #[test]
378    fn recommend_models_nonempty_for_16gb() {
379        let recs = recommend_models(&spec(16.0));
380        assert!(!recs.is_empty());
381        assert_eq!(recs[0].category, RecommendCategory::BestForDevice);
382    }
383
384    #[test]
385    fn setup_guide_contains_ollama_install() {
386        let guide = format_setup_guide(&spec(16.0));
387        assert!(guide.contains("ollama.ai/install.sh"));
388        assert!(guide.contains("ollama pull"));
389    }
390
391    #[test]
392    fn no_models_hint_has_pull_cmd() {
393        let hint = format_no_models_hint(&spec(16.0));
394        assert!(hint.contains("ollama pull"));
395    }
396}