phoebus_os/installer-rs/crates/phoebus-ai/src/provider.rs
2026-09-24 11:42:16 -07:00

725 lines
26 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>,
/// 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<String>,
/// Saved per-application backend preferences.
#[serde(default)]
pub saved_preferences: BTreeMap<String, String>,
/// 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<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(),
..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\":\"<action>\",\"value\":<value>}],\"rationale\":[{\"action\":\"<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<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())
}
}
/// 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<std::collections::VecDeque<String>>,
requests: std::sync::Mutex<Vec<String>>,
}
impl ScriptedTransport {
pub fn new(responses: Vec<String>) -> Self {
Self {
responses: std::sync::Mutex::new(responses.into()),
requests: std::sync::Mutex::new(Vec::new()),
}
}
pub fn requests(&self) -> Vec<String> {
self.requests.lock().unwrap().clone()
}
}
impl ModelTransport for ScriptedTransport {
fn send(&self, _provider: ProviderKind, _url: &str, body: &str) -> Result<String, AiError> {
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<AiProposal, AiError> {
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<AiProposal, AiError> {
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<AiProposal, AiError> {
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(_)));
}
}