//! Model provider connections. //! //! DeepSeek and OpenAI both expose an OpenAI-compatible chat-completions API, //! so one request/response shape covers both. The provider layer builds the //! request from a closed set of approved [`SystemFacts`]; the API key is never //! part of the request and is injected by the transport (see //! `phoebus-executor::ai`). [`TestTransport`] makes the whole path exercisable //! without a network. use std::collections::{BTreeMap, HashMap}; use phoebus_core::config::InstallConfig; use phoebus_core::hardware::HardwareReport; use serde::{Deserialize, Serialize}; use crate::privacy::is_forbidden_path; use crate::{parse_proposal, AiError, AiProposal}; /// The selectable providers. `None` means "continue without AI". #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum ProviderKind { None, DeepSeek, OpenAi, /// An OpenAI-compatible server the user runs locally (Ollama, llama.cpp, /// LM Studio, ...). No model is shipped; the user downloads and serves one. Local, } impl ProviderKind { pub fn as_str(self) -> &'static str { match self { ProviderKind::None => "none", ProviderKind::DeepSeek => "deepseek", ProviderKind::OpenAi => "openai", ProviderKind::Local => "local", } } /// Parse a user-facing provider name (aliases included). pub fn parse(value: &str) -> Option { match value.trim().to_ascii_lowercase().as_str() { "" | "none" | "no" | "off" | "without" => Some(ProviderKind::None), "deepseek" => Some(ProviderKind::DeepSeek), "openai" | "chatgpt" | "gpt" => Some(ProviderKind::OpenAi), "local" | "ollama" | "llama" | "llamacpp" | "llama.cpp" | "lmstudio" | "lm-studio" => { Some(ProviderKind::Local) } _ => None, } } /// The default chat-completions endpoint. For `Local` this is the common /// Ollama OpenAI-compatible address; `--ai-endpoint` overrides it. pub fn endpoint(self) -> &'static str { match self { ProviderKind::None => "", ProviderKind::DeepSeek => "https://api.deepseek.com/chat/completions", ProviderKind::OpenAi => "https://api.openai.com/v1/chat/completions", ProviderKind::Local => "http://127.0.0.1:11434/v1/chat/completions", } } pub fn default_model(self) -> &'static str { match self { ProviderKind::None => "", ProviderKind::DeepSeek => "deepseek-chat", ProviderKind::OpenAi => "gpt-4o-mini", ProviderKind::Local => "llama3.1", } } /// Only the hosted providers need an API key; a local server usually does /// not, but `--ai-api-key-file` may still be supplied if it does. pub fn requires_key(self) -> bool { matches!(self, ProviderKind::DeepSeek | ProviderKind::OpenAi) } } /// A bounded summary of the machine, and nothing else. No home directories, no /// logs, no credentials, no file contents. #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] pub struct SystemFacts { pub arch: String, pub cpu_model: String, pub cpu_cores: u32, pub memory_mib: u64, pub cpu_features: Vec, pub gpu_vendors: Vec, pub firmware: String, pub target_disk: String, pub disk_size_gib: u64, pub disk_ssd: bool, pub gentoo_profile: String, pub binhost_available: bool, pub desktop_profile: String, pub filesystem: String, pub encryption: String, pub recommended_kernel_profile: String, /// Measured compile times (seconds) for the slowest packages, capped. pub measured_compile_times: BTreeMap, } /// Storage facts supplied by the caller (disk probing lives in the executor). #[derive(Debug, Clone, Default, PartialEq, Eq)] pub struct DiskSummary { pub path: String, pub size_gib: u64, pub ssd: bool, } const MAX_HISTORY: usize = 40; impl SystemFacts { pub fn from_system( config: &InstallConfig, hardware: &HardwareReport, history: &HashMap, binhost_available: bool, disk: Option, ) -> Self { let mut measured: Vec<(String, u64)> = history .iter() .map(|(atom, secs)| (atom.clone(), *secs)) .collect(); measured.sort_by(|a, b| b.1.cmp(&a.1).then_with(|| a.0.cmp(&b.0))); measured.truncate(MAX_HISTORY); let disk = disk.unwrap_or_default(); SystemFacts { arch: config.system.arch.clone(), cpu_model: hardware.cpu.model.clone(), cpu_cores: hardware.cpu.cores, memory_mib: hardware.memory_mib, cpu_features: hardware.cpu.features.clone(), gpu_vendors: hardware .gpu_vendors() .into_iter() .map(|v| v.as_str().to_string()) .collect(), firmware: hardware.firmware_str().to_string(), target_disk: disk.path, disk_size_gib: disk.size_gib, disk_ssd: disk.ssd, gentoo_profile: phoebus_core::system::selected_profile(config), binhost_available, desktop_profile: config.desktop.profile.to_string(), filesystem: config.storage.filesystem.to_string(), encryption: config.encryption.mode.to_string(), recommended_kernel_profile: hardware.recommended_kernel_profile().to_string(), measured_compile_times: measured.into_iter().collect(), } } pub fn render(&self) -> String { serde_json::to_string_pretty(self).unwrap_or_else(|_| "{}".to_string()) } /// Refuse to send facts if any string field looks like a personal path. pub fn validate_no_forbidden(&self) -> Result<(), AiError> { let strings = [ &self.arch, &self.cpu_model, &self.firmware, &self.target_disk, &self.gentoo_profile, &self.desktop_profile, &self.filesystem, &self.encryption, &self.recommended_kernel_profile, ]; for value in strings.into_iter().chain(self.gpu_vendors.iter()) { if is_forbidden_path(value) { return Err(AiError::PrivateData(value.clone())); } } for atom in self.measured_compile_times.keys() { if is_forbidden_path(atom) { return Err(AiError::PrivateData(atom.clone())); } } Ok(()) } } /// The instructions given to the model. They are deliberately explicit about /// the closed action set and the evidence requirement. pub const SYSTEM_PROMPT: &str = "\ You are the Phoebus OS installation advisor. You may ONLY propose changes using \ this closed set of actions, each with a non-empty reason and optional evidence: set_hostname, set_timezone, set_locale, set_keymap, set_username, set_target_disk, set_filesystem (btrfs|ext4), set_encryption (none|luks2), set_kernel_profile (safe|optimized|aggressive), set_package_policy (balanced|source_first|binary_first), set_desktop_profile (none|minimal|dwl|full), set_flatpak (bool), set_binary_packages (bool), set_build_jobs (1-256), set_package_use (atom, flag, enabled). Reply with ONLY a JSON object of the form: {\"version\":1,\"changes\":[{\"action\":\"...\",...}],\"rationale\":[{\"action\":\"...\",\"reason\":\"...\",\"evidence\":[\"...\"]}]} Rules: prefer stability and a proven boot over speculative performance; never propose disabling signature verification, enabling ~amd64 globally, weakening LUKS2/Btrfs/systemd/UEFI, or any shell/command action; do not invent package atoms; keep required boot/encryption/filesystem settings fixed. You do not have a shell and cannot execute anything."; #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] pub struct ChatMessage { pub role: String, pub content: String, } #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] pub struct ResponseFormat { #[serde(rename = "type")] pub kind: String, } #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] pub struct ChatRequest { pub model: String, pub messages: Vec, pub temperature: f32, #[serde(skip_serializing_if = "Option::is_none")] pub response_format: Option, } /// Build the chat request for a provider. The API key is not part of it. pub fn build_request(provider: ProviderKind, model: &str, facts: &SystemFacts) -> ChatRequest { let model = if model.trim().is_empty() { provider.default_model().to_string() } else { model.trim().to_string() }; let user = format!( "Detected system facts (JSON):\n{}\n\nPropose a version 1 AiProposal.", facts.render() ); ChatRequest { model, messages: vec![ ChatMessage { role: "system".into(), content: SYSTEM_PROMPT.into(), }, ChatMessage { role: "user".into(), content: user, }, ], temperature: 0.0, response_format: Some(ResponseFormat { kind: "json_object".into(), }), } } #[derive(Debug, Deserialize)] struct ChatResponse { choices: Vec, } #[derive(Debug, Deserialize)] struct Choice { message: ChoiceMessage, } #[derive(Debug, Deserialize)] struct ChoiceMessage { content: String, } /// Extract the assistant's text content from a chat-completions response and /// strip a Markdown code fence if the model added one. pub fn extract_content(body: &str) -> Result { let parsed: ChatResponse = serde_json::from_str(body) .map_err(|e| AiError::Provider(format!("invalid chat response: {e}")))?; let content = parsed .choices .first() .map(|c| c.message.content.trim().to_string()) .filter(|c| !c.is_empty()) .ok_or_else(|| AiError::Provider("model returned no content".into()))?; let inner = if let Some(rest) = content.strip_prefix("```") { let rest = rest.strip_prefix("json").unwrap_or(rest); rest.trim_start_matches(['\n', '\r']) .trim_end() .strip_suffix("```") .unwrap_or(rest) .trim() .to_string() } else { content }; if inner.is_empty() { return Err(AiError::Provider("model returned empty content".into())); } Ok(inner) } /// Transport used to reach a provider. The executor implements this with curl; /// tests implement it with canned responses. pub trait ModelTransport { fn send(&self, provider: ProviderKind, url: &str, body: &str) -> Result; } /// A transport that always returns a fixed response (tests, offline dry runs). pub struct TestTransport { pub response: String, } impl TestTransport { pub fn new(response: impl Into) -> Self { Self { response: response.into(), } } /// Wrap a bare proposal JSON in an OpenAI-style chat response. pub fn proposal(proposal_json: &str) -> Self { Self::new( serde_json::json!({ "choices": [{ "message": { "content": proposal_json } }] }) .to_string(), ) } } impl ModelTransport for TestTransport { fn send(&self, _provider: ProviderKind, _url: &str, _body: &str) -> Result { Ok(self.response.clone()) } } /// Ask a provider for a proposal and parse it, fail-closed at every step. pub fn complete_proposal( provider: ProviderKind, model: &str, facts: &SystemFacts, transport: &dyn ModelTransport, ) -> Result { complete_proposal_at(provider, provider.endpoint(), model, facts, transport) } /// As `complete_proposal`, but with an explicit endpoint (`--ai-endpoint`), for /// a self-hosted model on a non-default port. pub fn complete_proposal_at( provider: ProviderKind, endpoint: &str, model: &str, facts: &SystemFacts, transport: &dyn ModelTransport, ) -> Result { if provider == ProviderKind::None { return Err(AiError::ProviderUnavailable( "no AI provider selected".into(), )); } if endpoint.trim().is_empty() { return Err(AiError::ProviderUnavailable( "no provider endpoint configured".into(), )); } facts.validate_no_forbidden()?; let request = build_request(provider, model, facts); let body = serde_json::to_string(&request)?; let response = transport.send(provider, endpoint, &body)?; let content = extract_content(&response)?; parse_proposal(&content) } #[cfg(test)] mod tests { use super::*; use phoebus_core::config::InstallConfig; use phoebus_core::hardware::{CpuInfo, GpuInfo, GpuVendor, HardwareReport}; fn facts() -> SystemFacts { let mut config = InstallConfig::default(); config.desktop.profile = phoebus_core::DesktopProfile::Dwl; let hardware = HardwareReport { cpu: CpuInfo { model: "Test CPU".into(), cores: 8, features: vec!["vmx".into(), "avx2".into()], ..Default::default() }, memory_mib: 16384, gpus: vec![GpuInfo { vendor: GpuVendor::Intel, description: "iGPU".into(), }], ..Default::default() }; let history = HashMap::from([("sys-apps/systemd".to_string(), 420u64)]); SystemFacts::from_system( &config, &hardware, &history, true, Some(DiskSummary { path: "/dev/vda".into(), size_gib: 32, ssd: true, }), ) } #[test] fn facts_contain_only_system_data() { let facts = facts(); let rendered = facts.render(); assert!(rendered.contains("Test CPU")); assert!(rendered.contains("/dev/vda")); assert!(!rendered.contains("/home/")); assert!(!is_forbidden_path(&facts.target_disk)); facts.validate_no_forbidden().unwrap(); } #[test] fn forbidden_paths_in_facts_are_refused() { let mut facts = facts(); facts.cpu_model = "/home/alice/secret".into(); assert!(matches!( facts.validate_no_forbidden(), Err(AiError::PrivateData(_)) )); } #[test] fn history_is_capped_and_sorted() { let mut history = HashMap::new(); for i in 0..100u64 { history.insert(format!("cat/pkg{i}"), i); } let facts = SystemFacts::from_system( &InstallConfig::default(), &HardwareReport::default(), &history, true, None, ); assert_eq!(facts.measured_compile_times.len(), MAX_HISTORY); // The 40 slowest packages (60..=99) are kept. assert!(facts .measured_compile_times .values() .all(|v| *v >= 100 - MAX_HISTORY as u64)); } #[test] fn provider_endpoints_and_parsing() { assert_eq!(ProviderKind::parse("ChatGPT"), Some(ProviderKind::OpenAi)); assert_eq!( ProviderKind::parse("deepseek"), Some(ProviderKind::DeepSeek) ); assert_eq!(ProviderKind::parse("continue without AI"), None); assert_eq!(ProviderKind::parse("none"), Some(ProviderKind::None)); assert_eq!(ProviderKind::parse("ollama"), Some(ProviderKind::Local)); assert_eq!(ProviderKind::parse("Local"), Some(ProviderKind::Local)); assert!(ProviderKind::OpenAi.endpoint().starts_with("https://")); assert!(ProviderKind::None.endpoint().is_empty()); assert!(ProviderKind::Local .endpoint() .starts_with("http://127.0.0.1")); assert!(ProviderKind::DeepSeek.requires_key()); assert!(ProviderKind::OpenAi.requires_key()); // A self-hosted local server needs no key. assert!(!ProviderKind::Local.requires_key()); assert!(!ProviderKind::None.requires_key()); } #[test] fn local_provider_uses_an_explicit_endpoint() { let proposal = r#"{"version":1,"changes":[{"action":"set_flatpak","value":true}]}"#; let transport = TestTransport::proposal(proposal); let parsed = complete_proposal_at( ProviderKind::Local, "http://127.0.0.1:8080/v1/chat/completions", "qwen2.5-coder", &facts(), &transport, ) .unwrap(); assert_eq!(parsed.changes.len(), 1); assert!(complete_proposal_at(ProviderKind::Local, "", "", &facts(), &transport).is_err()); } #[test] fn request_has_no_secret_and_pins_the_schema() { let request = build_request(ProviderKind::DeepSeek, "", &facts()); let body = serde_json::to_string(&request).unwrap(); assert_eq!(request.model, "deepseek-chat"); assert!(body.contains(SYSTEM_PROMPT.split('.').next().unwrap())); assert!(!body.to_lowercase().contains("api_key")); assert!(!body.contains("Bearer")); assert_eq!( request.response_format.as_ref().map(|r| r.kind.as_str()), Some("json_object") ); } #[test] fn extract_content_strips_code_fences() { let body = r#"{"choices":[{"message":{"content":"```json\n{\"version\":1,\"changes\":[]}\n```"}}]}"#; let content = extract_content(body).unwrap(); assert_eq!(content, r#"{"version":1,"changes":[]}"#); assert!(extract_content("not json").is_err()); assert!(extract_content(r#"{"choices":[]}"#).is_err()); } #[test] fn test_transport_round_trips_a_proposal() { let proposal = r#"{"version":1,"changes":[{"action":"set_flatpak","value":true}]}"#; let transport = TestTransport::proposal(proposal); let parsed = complete_proposal(ProviderKind::OpenAi, "", &facts(), &transport).unwrap(); assert_eq!(parsed.changes.len(), 1); } #[test] fn unavailable_provider_is_explicit() { let transport = TestTransport::new("{}"); let err = complete_proposal(ProviderKind::None, "", &facts(), &transport).unwrap_err(); assert!(matches!(err, AiError::ProviderUnavailable(_))); } }