//! 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, /// Free space on the intended root, in MiB (`0` means unknown). #[serde(default)] pub storage_free_mib: u64, /// Whether a Wayland session/stack is in use on the intended system. #[serde(default)] pub wayland: bool, /// Lanes whose tooling is present and usable (Portage, Nix, Flatpak, ...). #[serde(default)] pub available_backends: Vec, /// Saved per-application backend preferences. #[serde(default)] pub saved_preferences: BTreeMap, /// Whether Btrfs snapshots and rollback are available for recovery. #[serde(default)] pub recovery_snapshots: bool, } /// 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(), ..Default::default() } } 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())); } } for backend in &self.available_backends { if is_forbidden_path(backend) { return Err(AiError::PrivateData(backend.clone())); } } for (app, backend) in &self.saved_preferences { if is_forbidden_path(app) || is_forbidden_path(backend) { return Err(AiError::PrivateData(format!("{app}={backend}"))); } } Ok(()) } } /// Maximum accepted provider response size (16 MiB). A larger response is /// treated as hostile and refused rather than buffered. pub const MAX_RESPONSE_BYTES: u64 = 16 * 1024 * 1024; /// Validate a provider endpoint before it is handed to the transport. /// /// Only `http(s)` is allowed, and the URL may not contain whitespace, control /// characters, quotes or backslashes: the transport embeds it in a curl config /// file, so those characters could otherwise inject curl directives. Local and /// LAN endpoints remain valid (that is the point of the explicit endpoint), but /// unsafe schemes such as `file:`, `gopher:` or `scp:` are refused. pub fn validate_endpoint(url: &str) -> Result<(), AiError> { let trimmed = url.trim(); if trimmed.is_empty() { return Err(AiError::ProviderUnavailable( "no provider endpoint configured".into(), )); } let lower = trimmed.to_ascii_lowercase(); if !(lower.starts_with("http://") || lower.starts_with("https://")) { return Err(AiError::Provider(format!( "refusing non-http(s) endpoint scheme: {trimmed}" ))); } if trimmed .chars() .any(|c| c.is_whitespace() || c.is_control() || c == '"' || c == '\\') { return Err(AiError::Provider( "endpoint contains a character that is unsafe in a transport config".into(), )); } 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_encryption (none|luks2), set_kernel_profile (safe|optimized|aggressive), set_package_policy (balanced|source_first|binary_first), set_desktop_profile (mango), 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\":\"\",\"value\":}],\"rationale\":[{\"action\":\"\",\"reason\":\"...\",\"evidence\":[\"...\"]}]} Every change object has EXACTLY the two keys `action` and `value`. Put the chosen option in `value`; never use the action name as a key. Correct examples: {\"action\":\"set_kernel_profile\",\"value\":\"safe\"} {\"action\":\"set_desktop_profile\",\"value\":\"mango\"} {\"action\":\"set_binary_packages\",\"value\":true} {\"action\":\"set_build_jobs\",\"value\":8} Rules: prefer stability and a proven boot over speculative performance; always keep kernel profile as safe (prebuilt binary kernel sys-kernel/gentoo-kernel-bin) for installation reliability and speed (never propose changing kernel profile to optimized or aggressive); never propose set_target_disk (the user selects the target disk in the wizard); never propose disabling signature verification, enabling ~amd64 globally, weakening LUKS2/Btrfs/systemd/UEFI, or any shell/command action; do not invent package atoms; Flatpak, Nix, Btrfs filesystem, and the Mango + DMS desktop profile are required, non-removable core subsystems of Phoebus OS (never propose disabling, changing, or removing them); the NVIDIA driver branch and kernel-module flavor are selected from the detected PCI device IDs and are not proposable; keep required boot/encryption/filesystem/desktop 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()) } } /// A transport that returns a scripted sequence of responses, one per call /// (tests of retry and multi-turn behaviour). pub struct ScriptedTransport { responses: std::sync::Mutex>, requests: std::sync::Mutex>, } impl ScriptedTransport { pub fn new(responses: Vec) -> Self { Self { responses: std::sync::Mutex::new(responses.into()), requests: std::sync::Mutex::new(Vec::new()), } } pub fn requests(&self) -> Vec { self.requests.lock().unwrap().clone() } } impl ModelTransport for ScriptedTransport { fn send(&self, _provider: ProviderKind, _url: &str, body: &str) -> Result { self.requests.lock().unwrap().push(body.to_string()); self.responses .lock() .unwrap() .pop_front() .ok_or_else(|| AiError::Provider("no scripted response left".into())) } } /// Wrap a bare proposal in an OpenAI-style chat response (test helper). pub fn chat_response(content: &str) -> String { serde_json::json!({ "choices": [{ "message": { "content": content } }] }).to_string() } /// 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) } /// Build the request again, appending a corrective turn after a rejected reply. /// Models occasionally key a change by the action name or add prose; one /// bounded corrective round-trip meaningfully improves reliability without /// weakening the parser. pub fn build_corrected_request( provider: ProviderKind, model: &str, facts: &SystemFacts, correction: &str, ) -> ChatRequest { let mut request = build_request(provider, model, facts); request.messages.push(ChatMessage { role: "user".into(), content: format!( "Your previous reply was rejected: {correction}. Reply with ONLY the \ corrected JSON object, with no prose and no code fence." ), }); request } /// As `complete_proposal`, but with an explicit endpoint (`--ai-endpoint`), for /// a self-hosted model on a non-default port. A rejected reply is retried once /// with a corrective turn; the strict parser is still the final authority. 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(), )); } validate_endpoint(endpoint)?; facts.validate_no_forbidden()?; let attempt = |request: &ChatRequest| -> Result { let body = serde_json::to_string(request)?; let response = transport.send(provider, endpoint, &body)?; let content = extract_content(&response)?; parse_proposal(&content) }; match attempt(&build_request(provider, model, facts)) { Ok(proposal) => Ok(proposal), Err(first) => { let correction = first.to_string(); attempt(&build_corrected_request( provider, model, facts, &correction, )) } } } #[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::Mango; 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(), pci_id: None, pci_address: None, }], ..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 endpoint_validation_rejects_unsafe_schemes_and_injection() { assert!(validate_endpoint("https://api.deepseek.com/chat/completions").is_ok()); assert!(validate_endpoint("http://192.168.1.10:11434/v1/chat/completions").is_ok()); assert!(validate_endpoint("http://127.0.0.1:8080/v1/chat/completions").is_ok()); assert!(validate_endpoint("file:///etc/shadow").is_err()); assert!(validate_endpoint("scp://host/path").is_err()); assert!(validate_endpoint("https://x/v1\"\nheader = \"A: b").is_err()); assert!(validate_endpoint("https://x/v1 with space").is_err()); assert!(validate_endpoint("").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 a_rejected_proposal_is_retried_once_with_a_correction() { // First response uses the wrong key (the failure seen with a real // model); the second is corrected. let bad = chat_response( r#"{"version":1,"changes":[{"action":"set_kernel_profile","profile":"safe"}],"rationale":[]}"#, ); let good = chat_response( r#"{"version":1,"changes":[{"action":"set_kernel_profile","value":"safe"}],"rationale":[{"action":"set_kernel_profile","reason":"x"}]}"#, ); let transport = ScriptedTransport::new(vec![bad, good]); let proposal = complete_proposal_at( ProviderKind::Local, "http://127.0.0.1:8080/v1/chat/completions", "m", &facts(), &transport, ) .unwrap(); assert_eq!(proposal.changes.len(), 1); let requests = transport.requests(); assert_eq!(requests.len(), 2, "exactly one corrective retry"); assert!( requests[1].contains("rejected"), "the retry carries the reason" ); } #[test] fn a_retry_that_still_fails_is_still_rejected() { let bad = chat_response(r#"{"version":1,"changes":[{"action":"nope"}]}"#); let transport = ScriptedTransport::new(vec![bad.clone(), bad]); assert!(complete_proposal_at( ProviderKind::Local, "http://127.0.0.1:8080/v1/chat/completions", "m", &facts(), &transport ) .is_err()); assert_eq!(transport.requests().len(), 2); } #[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(_))); } }