Skip to main content

qualia_client_core/
inference_backend.rs

1//! Persisted inference backend preference (Local / Remote / Hybrid / Ollama).
2//!
3//! **Local** (GGUF in-process) is the primary Qualia engine.
4//! **Ollama** is an explicit opt-in harness for when native inference is not
5//! ready or the principal wants a local Ollama endpoint for chat / ETL prep.
6
7use serde::{Deserialize, Serialize};
8
9use crate::chat_agents::AgentBackendKind;
10use crate::state::app_meta_dir;
11
12const SETTINGS_FILE: &str = "inference_backend.json";
13
14#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
15pub struct InferenceBackendSettings {
16    #[serde(default)]
17    pub backend: AgentBackendKind,
18    /// Remote (Nym / MCP) endpoint label or URL when backend is Remote/Hybrid.
19    #[serde(default)]
20    pub remote_endpoint: String,
21
22    // ── Optional Ollama harness (ignored unless backend == Ollama) ──────────
23    /// e.g. `http://127.0.0.1:11434`
24    #[serde(default = "default_ollama_base_url")]
25    pub ollama_base_url: String,
26    /// Generation model tag (e.g. `llama3.2`, `qwen2.5:7b`).
27    #[serde(default = "default_ollama_model")]
28    pub ollama_model: String,
29    /// Embedding model for ETL / retrieval prep.
30    #[serde(default = "default_ollama_embed_model")]
31    pub ollama_embed_model: String,
32    /// Optional bearer token for hosted/proxied Ollama-compatible APIs.
33    #[serde(default, skip_serializing_if = "Option::is_none")]
34    pub ollama_api_key: Option<String>,
35    #[serde(default = "default_ollama_timeout")]
36    pub ollama_timeout_secs: u64,
37    #[serde(default = "default_ollama_num_ctx")]
38    pub ollama_num_ctx: u32,
39    #[serde(default = "default_ollama_temperature")]
40    pub ollama_temperature: f32,
41    /// When true and backend is Hybrid, try Ollama after local fails (not Remote).
42    #[serde(default)]
43    pub ollama_as_hybrid_fallback: bool,
44}
45
46fn default_ollama_base_url() -> String {
47    crate::ollama_harness::DEFAULT_OLLAMA_BASE_URL.to_string()
48}
49fn default_ollama_model() -> String {
50    "llama3.2".to_string()
51}
52fn default_ollama_embed_model() -> String {
53    "nomic-embed-text".to_string()
54}
55fn default_ollama_timeout() -> u64 {
56    120
57}
58fn default_ollama_num_ctx() -> u32 {
59    8192
60}
61fn default_ollama_temperature() -> f32 {
62    0.2
63}
64
65impl Default for InferenceBackendSettings {
66    fn default() -> Self {
67        Self {
68            backend: AgentBackendKind::Local,
69            remote_endpoint: String::new(),
70            ollama_base_url: default_ollama_base_url(),
71            ollama_model: default_ollama_model(),
72            ollama_embed_model: default_ollama_embed_model(),
73            ollama_api_key: None,
74            ollama_timeout_secs: default_ollama_timeout(),
75            ollama_num_ctx: default_ollama_num_ctx(),
76            ollama_temperature: default_ollama_temperature(),
77            ollama_as_hybrid_fallback: false,
78        }
79    }
80}
81
82impl InferenceBackendSettings {
83    /// Mirror `AgentConfig.inference_backend` string into structured settings.
84    pub fn apply_agent_config_backend_string(&mut self, s: &str) {
85        self.backend = AgentBackendKind::from_str(s);
86    }
87
88    /// `agent-config-string` form.
89    pub fn as_agent_config_string(&self) -> String {
90        self.backend.as_str().to_string()
91    }
92
93    /// Validates.
94    pub fn validate(&self) -> Result<(), String> {
95        match self.backend {
96            AgentBackendKind::Ollama => {
97                if self.ollama_base_url.trim().is_empty() {
98                    return Err("Ollama base URL is required when backend is Ollama".into());
99                }
100                if self.ollama_model.trim().is_empty() {
101                    return Err("Ollama model tag is required when backend is Ollama".into());
102                }
103                if !(self.ollama_base_url.starts_with("http://")
104                    || self.ollama_base_url.starts_with("https://"))
105                {
106                    return Err("Ollama base URL must start with http:// or https://".into());
107                }
108            }
109            AgentBackendKind::Remote => {
110                // remote_endpoint optional for now (MCP path may supply later)
111            }
112            _ => {}
113        }
114        Ok(())
115    }
116}
117
118fn settings_path() -> std::path::PathBuf {
119    app_meta_dir().join(SETTINGS_FILE)
120}
121
122/// Loads inference-backend-settings.
123pub fn load_inference_backend_settings() -> InferenceBackendSettings {
124    let path = settings_path();
125    if !path.is_file() {
126        // Seed from AgentConfig.inference_backend if present.
127        if let Some(state) = crate::state::APP_STATE.get() {
128            if let Ok(cfg) = state.config.lock() {
129                let mut s = InferenceBackendSettings::default();
130                s.apply_agent_config_backend_string(&cfg.inference_backend);
131                return s;
132            }
133        }
134        return InferenceBackendSettings::default();
135    }
136    std::fs::read_to_string(&path)
137        .ok()
138        .and_then(|text| serde_json::from_str(&text).ok())
139        .unwrap_or_default()
140}
141
142/// Saves inference-backend-settings.
143pub fn save_inference_backend_settings(settings: &InferenceBackendSettings) -> Result<(), String> {
144    settings.validate()?;
145    let path = settings_path();
146    if let Some(parent) = path.parent() {
147        std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
148    }
149    let json = serde_json::to_string_pretty(settings).map_err(|e| e.to_string())?;
150    std::fs::write(&path, json).map_err(|e| e.to_string())?;
151
152    // Keep AgentConfig.inference_backend in sync for legacy UI that only stores a string.
153    if let Some(state) = crate::state::APP_STATE.get() {
154        if let Ok(mut cfg) = state.config.lock() {
155            cfg.inference_backend = settings.as_agent_config_string();
156            if let Ok(json) = serde_json::to_string_pretty(&*cfg) {
157                let _ = std::fs::write(crate::state::config_file_path(), json);
158            }
159        }
160    }
161    Ok(())
162}
163
164/// `backend` label.
165pub fn backend_label(settings: &InferenceBackendSettings) -> &'static str {
166    match settings.backend {
167        AgentBackendKind::Local => "Local GGUF (in-process Qualia)",
168        AgentBackendKind::Remote => "Remote (Nym mixnet, consent required)",
169        AgentBackendKind::Hybrid => "Hybrid (local first, remote/ollama fallback)",
170        AgentBackendKind::Ollama => "Ollama (optional HTTP harness)",
171    }
172}
173
174/// True when chat should use the Ollama harness instead of LocalLlmAgent.
175pub fn use_ollama_harness() -> bool {
176    matches!(
177        load_inference_backend_settings().backend,
178        AgentBackendKind::Ollama
179    )
180}
181
182#[cfg(test)]
183mod tests {
184    use super::*;
185
186    #[test]
187    fn default_is_local() {
188        let settings = InferenceBackendSettings::default();
189        assert_eq!(settings.backend, AgentBackendKind::Local);
190        assert!(!use_ollama_harness() || settings.backend == AgentBackendKind::Ollama);
191    }
192
193    #[test]
194    fn ollama_validate_requires_url_and_model() {
195        let mut s = InferenceBackendSettings {
196            backend: AgentBackendKind::Ollama,
197            ollama_base_url: String::new(),
198            ollama_model: String::new(),
199            ..Default::default()
200        };
201        assert!(s.validate().is_err());
202        s.ollama_base_url = "http://127.0.0.1:11434".into();
203        s.ollama_model = "llama3.2".into();
204        assert!(s.validate().is_ok());
205    }
206
207    #[test]
208    fn from_str_roundtrip_ollama() {
209        assert_eq!(
210            AgentBackendKind::from_str("ollama"),
211            AgentBackendKind::Ollama
212        );
213        assert_eq!(AgentBackendKind::Ollama.as_str(), "ollama");
214    }
215}