phoebus_os/installer-rs/crates/phoebus-ai/src/provider.rs
Phoebus 3a405dd1e7 feat(installer): require AI to install; add local provider
Installing Phoebus now requires a connected model: the install gate refuses
with no provider unless the explicit break-glass --no-ai (alias --legacy, or
PHOEBUS_NO_AI=1) is used. Add a 'local' provider kind (Ollama/llama.cpp/
LM Studio) with an optional API key and --ai-endpoint override, so a user can
run a model they downloaded; no model is shipped. Desktop installs now include
xdg-desktop-portal + gtk/wlr backends for Flatpak and Wayland apps.
2026-09-20 14:41:53 -07:00

528 lines
18 KiB
Rust

//! 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<Self> {
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<String>,
pub gpu_vendors: Vec<String>,
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<String, u64>,
}
/// 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<String, u64>,
binhost_available: bool,
disk: Option<DiskSummary>,
) -> 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<ChatMessage>,
pub temperature: f32,
#[serde(skip_serializing_if = "Option::is_none")]
pub response_format: Option<ResponseFormat>,
}
/// 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<Choice>,
}
#[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<String, AiError> {
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<String, AiError>;
}
/// 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<String>) -> 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<String, AiError> {
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<AiProposal, AiError> {
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<AiProposal, AiError> {
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(_)));
}
}