Skip to main content

qualia_client_core/
model_preferences.rs

1//! User-defined LLM load priority and conditional selection.
2
3use std::path::{Path, PathBuf};
4
5use qualia_core_db::resource_catalog::ResourceCatalog;
6use serde::{Deserialize, Serialize};
7use sysinfo::System;
8
9use crate::model_lifecycle::{self, load_install_manifest, models_dir, ActiveModelRecord};
10
11const PREFS_FILE: &str = "model_preferences.json";
12
13#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
14#[serde(rename_all = "snake_case")]
15pub enum ModelTask {
16    #[default]
17    Always,
18    Chat,
19    Coding,
20    Vision,
21    LowRam,
22}
23
24impl ModelTask {
25    /// Label.
26    pub fn label(self) -> &'static str {
27        match self {
28            ModelTask::Always => "Whenever installed",
29            ModelTask::Chat => "General chat",
30            ModelTask::Coding => "Coding / reasoning",
31            ModelTask::Vision => "Vision / multimodal",
32            ModelTask::LowRam => "Low RAM only",
33        }
34    }
35
36    /// Constructs from str-lossy.
37    pub fn from_str_lossy(s: &str) -> Self {
38        match s.trim().to_lowercase().as_str() {
39            "chat" => ModelTask::Chat,
40            "coding" => ModelTask::Coding,
41            "vision" => ModelTask::Vision,
42            "low_ram" | "lowram" => ModelTask::LowRam,
43            _ => ModelTask::Always,
44        }
45    }
46
47    /// `str` form.
48    pub fn as_str(self) -> &'static str {
49        match self {
50            ModelTask::Always => "always",
51            ModelTask::Chat => "chat",
52            ModelTask::Coding => "coding",
53            ModelTask::Vision => "vision",
54            ModelTask::LowRam => "low_ram",
55        }
56    }
57}
58
59#[derive(Debug, Clone, Serialize, Deserialize)]
60pub struct ModelLoadCondition {
61    #[serde(default = "default_true")]
62    pub require_installed: bool,
63    #[serde(default)]
64    pub task: ModelTask,
65    #[serde(default)]
66    pub min_ram_gb: Option<f64>,
67    #[serde(default = "default_true")]
68    pub respect_ram_estimate: bool,
69    #[serde(default)]
70    pub require_multimodal: bool,
71}
72
73impl Default for ModelLoadCondition {
74    fn default() -> Self {
75        Self {
76            require_installed: true,
77            task: ModelTask::Always,
78            min_ram_gb: None,
79            respect_ram_estimate: true,
80            require_multimodal: false,
81        }
82    }
83}
84
85fn default_true() -> bool {
86    true
87}
88
89#[derive(Debug, Clone, Serialize, Deserialize)]
90pub struct ModelPreferenceEntry {
91    pub model_id: String,
92    pub label: String,
93    pub priority: u32,
94    #[serde(default)]
95    pub when: ModelLoadCondition,
96}
97
98#[derive(Debug, Clone, Serialize, Deserialize)]
99pub struct ModelPreferences {
100    #[serde(default)]
101    pub auto_select: bool,
102    #[serde(default)]
103    pub entries: Vec<ModelPreferenceEntry>,
104}
105
106impl Default for ModelPreferences {
107    fn default() -> Self {
108        Self {
109            auto_select: true,
110            entries: vec![],
111        }
112    }
113}
114
115#[derive(Debug, Clone, Serialize)]
116pub struct ResolvedModelPreference {
117    pub model_id: String,
118    pub label: String,
119    pub reason: String,
120    pub gguf_path: String,
121    pub priority: u32,
122    pub task: String,
123}
124
125/// Preferences path.
126pub fn preferences_path(storage_root: &Path) -> PathBuf {
127    storage_root.join("Meta").join(PREFS_FILE)
128}
129
130/// Loads preferences.
131pub fn load_preferences(storage_root: &Path) -> ModelPreferences {
132    let path = preferences_path(storage_root);
133    let Ok(text) = std::fs::read_to_string(&path) else {
134        return ModelPreferences::default();
135    };
136    serde_json::from_str(&text).unwrap_or_default()
137}
138
139/// Saves preferences.
140pub fn save_preferences(storage_root: &Path, prefs: &ModelPreferences) -> Result<(), String> {
141    let path = preferences_path(storage_root);
142    if let Some(parent) = path.parent() {
143        std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
144    }
145    let json = serde_json::to_string_pretty(prefs).map_err(|e| e.to_string())?;
146    std::fs::write(path, json).map_err(|e| e.to_string())
147}
148
149/// Lists installed model IDs.
150pub fn list_installed_model_ids(storage_root: &Path) -> Vec<String> {
151    let models = models_dir(storage_root);
152    let Ok(entries) = std::fs::read_dir(&models) else {
153        return vec![];
154    };
155    let mut ids = Vec::new();
156    for entry in entries.filter_map(Result::ok) {
157        let path = entry.path();
158        let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
159            continue;
160        };
161        if !name.ends_with(".install.json") {
162            continue;
163        }
164        let model_id = name.trim_end_matches(".install.json");
165        if load_install_manifest(storage_root, model_id).is_some() {
166            ids.push(model_id.to_string());
167        }
168    }
169    ids.sort();
170    ids
171}
172
173fn system_ram_gb() -> f64 {
174    let mut sys = System::new_all();
175    sys.refresh_memory();
176    sys.total_memory() as f64 / 1024.0 / 1024.0 / 1024.0
177}
178
179fn catalog_ram_mb(catalog: &ResourceCatalog, model_id: &str) -> Option<u32> {
180    catalog
181        .find_llm(model_id)
182        .and_then(|m| m.ram_estimate_mb.or(m.size_mb))
183}
184
185fn catalog_is_multimodal(catalog: &ResourceCatalog, model_id: &str) -> bool {
186    catalog
187        .find_llm(model_id)
188        .map(|m| m.is_multimodal())
189        .unwrap_or(false)
190}
191
192fn task_matches(
193    condition_task: ModelTask,
194    request_task: ModelTask,
195    catalog: &ResourceCatalog,
196    model_id: &str,
197) -> bool {
198    if condition_task == ModelTask::Always {
199        return true;
200    }
201    if condition_task != request_task && request_task != ModelTask::Always {
202        return false;
203    }
204    let Some(llm) = catalog.find_llm(model_id) else {
205        return condition_task == request_task;
206    };
207    match condition_task {
208        ModelTask::Coding => {
209            llm.tags
210                .as_ref()
211                .map(|t| t.iter().any(|tag| tag == "coding" || tag == "reasoning"))
212                .unwrap_or(false)
213                || llm
214                    .recommended_for
215                    .as_ref()
216                    .map(|r| r.iter().any(|x| x == "coding"))
217                    .unwrap_or(false)
218        }
219        ModelTask::Vision => catalog_is_multimodal(catalog, model_id),
220        ModelTask::LowRam => {
221            let ram = catalog_ram_mb(catalog, model_id).unwrap_or(u32::MAX);
222            ram <= 2000
223                || llm
224                    .recommended_for
225                    .as_ref()
226                    .map(|r| {
227                        r.iter()
228                            .any(|x| x == "low_ram" || x == "very_low_ram" || x == "edge")
229                    })
230                    .unwrap_or(false)
231        }
232        ModelTask::Chat => true,
233        ModelTask::Always => true,
234    }
235}
236
237fn condition_passes(
238    entry: &ModelPreferenceEntry,
239    request_task: ModelTask,
240    ram_gb: f64,
241    catalog: &ResourceCatalog,
242    storage_root: &Path,
243) -> Option<String> {
244    let manifest = load_install_manifest(storage_root, &entry.model_id)?;
245    if entry.when.require_installed && !Path::new(&manifest.gguf_path).is_file() {
246        return None;
247    }
248    if entry.when.require_multimodal && manifest.modality != "multimodal" {
249        return None;
250    }
251    if let Some(min) = entry.when.min_ram_gb {
252        if ram_gb < min {
253            return None;
254        }
255    }
256    if entry.when.respect_ram_estimate {
257        if let Some(need_mb) = catalog_ram_mb(catalog, &entry.model_id) {
258            let need_gb = need_mb as f64 / 1024.0;
259            if ram_gb < need_gb * 0.85 {
260                return None;
261            }
262        }
263    }
264    if !task_matches(entry.when.task, request_task, catalog, &entry.model_id) {
265        return None;
266    }
267    let reason = format!(
268        "Priority #{} — {} ({})",
269        entry.priority,
270        entry.label,
271        entry.when.task.label()
272    );
273    Some(reason)
274}
275
276/// Resolves a preference.
277pub fn resolve_preference(
278    storage_root: &Path,
279    catalog: &ResourceCatalog,
280    prefs: &ModelPreferences,
281    request_task: ModelTask,
282) -> Option<ResolvedModelPreference> {
283    if prefs.entries.is_empty() {
284        return None;
285    }
286    let ram_gb = system_ram_gb();
287    let mut entries: Vec<_> = prefs.entries.iter().collect();
288    entries.sort_by_key(|e| e.priority);
289
290    for entry in entries {
291        let Some(reason) = condition_passes(entry, request_task, ram_gb, catalog, storage_root)
292        else {
293            continue;
294        };
295        let manifest = load_install_manifest(storage_root, &entry.model_id)?;
296        return Some(ResolvedModelPreference {
297            model_id: entry.model_id.clone(),
298            label: entry.label.clone(),
299            reason,
300            gguf_path: manifest.gguf_path,
301            priority: entry.priority,
302            task: entry.when.task.as_str().to_string(),
303        });
304    }
305    None
306}
307
308/// Applies preference.
309pub fn apply_preference(
310    storage_root: &Path,
311    catalog: &ResourceCatalog,
312    prefs: &ModelPreferences,
313    request_task: ModelTask,
314) -> Result<ActiveModelRecord, String> {
315    let resolved = resolve_preference(storage_root, catalog, prefs, request_task)
316        .ok_or_else(|| "No installed model matches your priority rules".to_string())?;
317    model_lifecycle::activate_model_for_id(&resolved.model_id, storage_root)
318        .map_err(|e| e.to_string())
319}
320
321/// `default-preferences-from` catalog.
322pub fn default_preferences_from_catalog(catalog: &ResourceCatalog) -> ModelPreferences {
323    let mut llms: Vec<_> = catalog.llms.iter().collect();
324    llms.sort_by_key(|m| m.ram_estimate_mb.or(m.size_mb).unwrap_or(u32::MAX));
325
326    let entries: Vec<ModelPreferenceEntry> = llms
327        .iter()
328        .take(6)
329        .enumerate()
330        .map(|(i, m)| {
331            let task = if m.is_multimodal() {
332                ModelTask::Vision
333            } else if m
334                .tags
335                .as_ref()
336                .map(|t| t.iter().any(|tag| tag == "coding"))
337                .unwrap_or(false)
338            {
339                ModelTask::Coding
340            } else if m
341                .recommended_for
342                .as_ref()
343                .map(|r| r.iter().any(|x| x == "edge" || x == "low_ram"))
344                .unwrap_or(false)
345            {
346                ModelTask::LowRam
347            } else {
348                ModelTask::Chat
349            };
350            ModelPreferenceEntry {
351                model_id: m.id.clone(),
352                label: m.name.clone(),
353                priority: (i as u32) + 1,
354                when: ModelLoadCondition {
355                    task,
356                    ..ModelLoadCondition::default()
357                },
358            }
359        })
360        .collect();
361
362    ModelPreferences {
363        auto_select: true,
364        entries,
365    }
366}
367
368/// Ensures preferences.
369pub fn ensure_preferences(storage_root: &Path, catalog: &ResourceCatalog) -> ModelPreferences {
370    let mut prefs = load_preferences(storage_root);
371    if prefs.entries.is_empty() && !catalog.llms.is_empty() {
372        prefs = default_preferences_from_catalog(catalog);
373        let _ = save_preferences(storage_root, &prefs);
374    }
375    prefs
376}
377
378#[cfg(test)]
379mod tests {
380    use super::*;
381    use qualia_core_db::resource_catalog::ResourceCatalog;
382
383    #[test]
384    fn default_preferences_sorted_by_ram() {
385        let catalog = qualia_core_db::resource_catalog::load_default()
386            .unwrap_or_else(|_| ResourceCatalog::empty());
387        let prefs = default_preferences_from_catalog(&catalog);
388        assert!(!prefs.entries.is_empty());
389        assert!(prefs.auto_select);
390        for (i, entry) in prefs.entries.iter().enumerate() {
391            assert_eq!(entry.priority, (i as u32) + 1);
392        }
393    }
394
395    #[test]
396    fn task_from_str_maps_coding() {
397        assert_eq!(ModelTask::from_str_lossy("coding"), ModelTask::Coding);
398        assert_eq!(ModelTask::from_str_lossy("always"), ModelTask::Always);
399    }
400}