zeph_core/

provider_factory.rs

// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
// SPDX-License-Identifier: MIT OR Apache-2.0

//! Pure provider factory helpers: build `AnyProvider` instances from config entries.
//!
//! This module contains configuration-to-provider transformation functions that are
//! used by internal `zeph-core` subsystems (skills, tools, autodream, session config).
//! They are intentionally separated from bootstrap orchestration logic so that provider
//! construction can be reasoned about and tested independently of startup sequencing.

use zeph_llm::any::AnyProvider;
use zeph_llm::claude::ClaudeProvider;
use zeph_llm::compatible::CompatibleProvider;
use zeph_llm::gemini::GeminiProvider;
use zeph_llm::http::llm_client;
use zeph_llm::ollama::OllamaProvider;
use zeph_llm::openai::OpenAiProvider;

use crate::agent::state::ProviderConfigSnapshot;
use crate::config::{Config, ProviderEntry, ProviderKind};

/// Error type for provider construction failures.
///
/// String-based variants flatten the error chain intentionally: bootstrap errors are
/// terminal (the application exits), so downcasting is not needed at this stage.
/// If a future phase requires programmatic retry on specific failures, expand these
/// variants into typed sub-errors.
#[derive(Debug, thiserror::Error)]
pub enum BootstrapError {
    /// Configuration validation failed.
    #[error("config error: {0}")]
    Config(#[from] crate::config::ConfigError),
    /// Provider construction failed (missing secrets, unsupported kind, etc.).
    #[error("provider error: {0}")]
    Provider(String),
    /// Memory subsystem initialization failed.
    #[error("memory error: {0}")]
    Memory(String),
    /// Age vault initialization failed.
    #[error("vault init error: {0}")]
    VaultInit(crate::vault::AgeVaultError),
    /// I/O error during bootstrap.
    #[error("I/O error: {0}")]
    Io(#[from] std::io::Error),
}

/// Build an `AnyProvider` from a `ProviderEntry` using a runtime config snapshot.
///
/// Called by the `/provider <name>` slash command to switch providers at runtime without
/// requiring the full `Config`. Router and Orchestrator provider kinds are not supported
/// for runtime switching — they require the full provider pool to be re-initialized.
///
/// # Errors
///
/// Returns `BootstrapError::Provider` when the provider kind is unsupported for runtime
/// switching, a required secret is missing, or the entry is misconfigured.
pub fn build_provider_for_switch(
    entry: &ProviderEntry,
    snapshot: &ProviderConfigSnapshot,
) -> Result<AnyProvider, BootstrapError> {
    use zeph_common::secret::Secret;
    // Reconstruct a minimal Config from the snapshot so we can reuse build_provider_from_entry.
    // Only fields read by build_provider_from_entry are populated; everything else uses defaults.
    // Secrets are stored as plain strings in the snapshot because Secret does not implement Clone.
    let mut config = Config::default();
    config.secrets.claude_api_key = snapshot.claude_api_key.as_deref().map(Secret::new);
    config.secrets.openai_api_key = snapshot.openai_api_key.as_deref().map(Secret::new);
    config.secrets.gemini_api_key = snapshot.gemini_api_key.as_deref().map(Secret::new);
    config.secrets.compatible_api_keys = snapshot
        .compatible_api_keys
        .iter()
        .map(|(k, v)| (k.clone(), Secret::new(v.as_str())))
        .collect();
    config.timeouts.llm_request_timeout_secs = snapshot.llm_request_timeout_secs;
    config
        .llm
        .embedding_model
        .clone_from(&snapshot.embedding_model);
    build_provider_from_entry(entry, &config)
}

/// Build an `AnyProvider` from a unified `ProviderEntry` (new `[[llm.providers]]` format).
///
/// All provider-specific fields come from `entry`; the global `config` is used only for
/// secrets and timeout settings.
///
/// # Errors
///
/// Returns `BootstrapError::Provider` when a required secret is missing or an entry is
/// misconfigured (e.g. compatible provider without a name).
#[allow(clippy::too_many_lines)]
pub fn build_provider_from_entry(
    entry: &ProviderEntry,
    config: &Config,
) -> Result<AnyProvider, BootstrapError> {
    match entry.provider_type {
        ProviderKind::Ollama => {
            let base_url = entry
                .base_url
                .as_deref()
                .unwrap_or("http://localhost:11434");
            let model = entry.model.as_deref().unwrap_or("qwen3:8b").to_owned();
            let embed = entry
                .embedding_model
                .clone()
                .unwrap_or_else(|| config.llm.embedding_model.clone());
            let mut provider = OllamaProvider::new(base_url, model, embed);
            if let Some(ref vm) = entry.vision_model {
                provider = provider.with_vision_model(vm.clone());
            }
            if config.mcp.forward_output_schema {
                tracing::debug!(
                    "mcp.forward_output_schema is enabled but Ollama does not support \
                     output schema forwarding; setting ignored for this provider"
                );
            }
            Ok(AnyProvider::Ollama(provider))
        }
        ProviderKind::Claude => {
            let api_key = config
                .secrets
                .claude_api_key
                .as_ref()
                .ok_or_else(|| {
                    BootstrapError::Provider("ZEPH_CLAUDE_API_KEY not found in vault".into())
                })?
                .expose()
                .to_owned();
            let model = entry
                .model
                .clone()
                .unwrap_or_else(|| "claude-haiku-4-5-20251001".to_owned());
            let max_tokens = entry.max_tokens.unwrap_or(4096);
            let provider = ClaudeProvider::new(api_key, model, max_tokens)
                .with_client(llm_client(config.timeouts.llm_request_timeout_secs))
                .with_extended_context(entry.enable_extended_context)
                .with_thinking_opt(entry.thinking.clone())
                .map_err(|e| BootstrapError::Provider(format!("invalid thinking config: {e}")))?
                .with_server_compaction(entry.server_compaction)
                .with_prompt_cache_ttl(entry.prompt_cache_ttl)
                .with_output_schema_forwarding(
                    config.mcp.forward_output_schema,
                    config.mcp.output_schema_hint_bytes,
                    config.mcp.max_description_bytes,
                );
            tracing::info!(
                forward = config.mcp.forward_output_schema,
                "mcp.output_schema.forwarding_configured"
            );
            Ok(AnyProvider::Claude(provider))
        }
        ProviderKind::OpenAi => {
            let api_key = config
                .secrets
                .openai_api_key
                .as_ref()
                .ok_or_else(|| {
                    BootstrapError::Provider("ZEPH_OPENAI_API_KEY not found in vault".into())
                })?
                .expose()
                .to_owned();
            let base_url = entry
                .base_url
                .clone()
                .unwrap_or_else(|| "https://api.openai.com/v1".to_owned());
            let model = entry
                .model
                .clone()
                .unwrap_or_else(|| "gpt-4o-mini".to_owned());
            let max_tokens = entry.max_tokens.unwrap_or(4096);
            Ok(AnyProvider::OpenAi(
                OpenAiProvider::new(
                    api_key,
                    base_url,
                    model,
                    max_tokens,
                    entry.embedding_model.clone(),
                    entry.reasoning_effort.clone(),
                )
                .with_client(llm_client(config.timeouts.llm_request_timeout_secs))
                .with_output_schema_forwarding(
                    config.mcp.forward_output_schema,
                    config.mcp.output_schema_hint_bytes,
                    config.mcp.max_description_bytes,
                ),
            ))
        }
        ProviderKind::Gemini => {
            let api_key = config
                .secrets
                .gemini_api_key
                .as_ref()
                .ok_or_else(|| {
                    BootstrapError::Provider("ZEPH_GEMINI_API_KEY not found in vault".into())
                })?
                .expose()
                .to_owned();
            let model = entry
                .model
                .clone()
                .unwrap_or_else(|| "gemini-2.0-flash".to_owned());
            let max_tokens = entry.max_tokens.unwrap_or(8192);
            let base_url = entry
                .base_url
                .clone()
                .unwrap_or_else(|| "https://generativelanguage.googleapis.com".to_owned());
            let mut provider = GeminiProvider::new(api_key, model, max_tokens)
                .with_base_url(base_url)
                .with_client(llm_client(config.timeouts.llm_request_timeout_secs));
            if let Some(ref em) = entry.embedding_model {
                provider = provider.with_embedding_model(em.clone());
            }
            if let Some(level) = entry.thinking_level {
                provider = provider.with_thinking_level(level);
            }
            if let Some(budget) = entry.thinking_budget {
                provider = provider
                    .with_thinking_budget(budget)
                    .map_err(|e| BootstrapError::Provider(e.to_string()))?;
            }
            if let Some(include) = entry.include_thoughts {
                provider = provider.with_include_thoughts(include);
            }
            if config.mcp.forward_output_schema {
                tracing::debug!(
                    "mcp.forward_output_schema is enabled but Gemini does not support \
                     output schema forwarding; setting ignored for this provider"
                );
            }
            Ok(AnyProvider::Gemini(provider))
        }
        ProviderKind::Compatible => {
            let name = entry.name.as_deref().ok_or_else(|| {
                BootstrapError::Provider(
                    "compatible provider requires 'name' field in [[llm.providers]]".into(),
                )
            })?;
            let base_url = entry.base_url.clone().ok_or_else(|| {
                BootstrapError::Provider(format!(
                    "compatible provider '{name}' requires 'base_url'"
                ))
            })?;
            let model = entry.model.clone().unwrap_or_default();
            let api_key = entry.api_key.clone().unwrap_or_else(|| {
                config
                    .secrets
                    .compatible_api_keys
                    .get(name)
                    .map(|s| s.expose().to_owned())
                    .unwrap_or_default()
            });
            let max_tokens = entry.max_tokens.unwrap_or(4096);
            let provider = CompatibleProvider::new(
                name.to_owned(),
                api_key,
                base_url,
                model,
                max_tokens,
                entry.embedding_model.clone(),
            )
            .with_output_schema_forwarding(
                config.mcp.forward_output_schema,
                config.mcp.output_schema_hint_bytes,
                config.mcp.max_description_bytes,
            );
            tracing::info!(
                forward = config.mcp.forward_output_schema,
                provider = name,
                "mcp.output_schema.forwarding_configured"
            );
            Ok(AnyProvider::Compatible(provider))
        }
        #[cfg(feature = "candle")]
        ProviderKind::Candle => {
            let candle = entry.candle.as_ref().ok_or_else(|| {
                BootstrapError::Provider(
                    "candle provider requires 'candle' section in [[llm.providers]]".into(),
                )
            })?;
            let source = match candle.source.as_str() {
                "local" => zeph_llm::candle_provider::loader::ModelSource::Local {
                    path: std::path::PathBuf::from(&candle.local_path),
                },
                _ => zeph_llm::candle_provider::loader::ModelSource::HuggingFace {
                    repo_id: entry
                        .model
                        .clone()
                        .unwrap_or_else(|| config.llm.effective_model().to_owned()),
                    filename: candle.filename.clone(),
                },
            };
            let template =
                zeph_llm::candle_provider::template::ChatTemplate::parse_str(&candle.chat_template);
            let gen_config = zeph_llm::candle_provider::generate::GenerationConfig {
                temperature: candle.generation.temperature,
                top_p: candle.generation.top_p,
                top_k: candle.generation.top_k,
                max_tokens: candle.generation.capped_max_tokens(),
                seed: candle.generation.seed,
                repeat_penalty: candle.generation.repeat_penalty,
                repeat_last_n: candle.generation.repeat_last_n,
            };
            let device = select_device(&candle.device)?;
            // Floor at 1s so that inference_timeout_secs = 0 does not cause every request to
            // immediately time out.
            let inference_timeout =
                std::time::Duration::from_secs(candle.inference_timeout_secs.max(1));
            zeph_llm::candle_provider::CandleProvider::new_with_timeout(
                &source,
                template,
                gen_config,
                candle.embedding_repo.as_deref(),
                candle.hf_token.as_deref(),
                device,
                inference_timeout,
            )
            .map(AnyProvider::Candle)
            .map_err(|e| BootstrapError::Provider(e.to_string()))
        }
        #[cfg(not(feature = "candle"))]
        ProviderKind::Candle => Err(BootstrapError::Provider(
            "candle feature is not enabled".into(),
        )),
    }
}

/// Select the candle compute device based on a string preference.
///
/// Resolution order: `"metal"` → Metal GPU (requires `metal` feature),
/// `"cuda"` → CUDA GPU (requires `cuda` feature), `"auto"` → best available,
/// anything else → CPU.
///
/// # Errors
///
/// Returns `BootstrapError::Provider` when the requested device is not available (e.g.
/// `"metal"` requested but compiled without the `metal` feature).
#[cfg(feature = "candle")]
pub fn select_device(
    preference: &str,
) -> Result<zeph_llm::candle_provider::Device, BootstrapError> {
    match preference {
        "metal" => {
            #[cfg(feature = "metal")]
            return zeph_llm::candle_provider::Device::new_metal(0)
                .map_err(|e| BootstrapError::Provider(e.to_string()));
            #[cfg(not(feature = "metal"))]
            return Err(BootstrapError::Provider(
                "candle compiled without metal feature".into(),
            ));
        }
        "cuda" => {
            #[cfg(feature = "cuda")]
            return zeph_llm::candle_provider::Device::new_cuda(0)
                .map_err(|e| BootstrapError::Provider(e.to_string()));
            #[cfg(not(feature = "cuda"))]
            return Err(BootstrapError::Provider(
                "candle compiled without cuda feature".into(),
            ));
        }
        "auto" => {
            #[cfg(feature = "metal")]
            if let Ok(device) = zeph_llm::candle_provider::Device::new_metal(0) {
                return Ok(device);
            }
            #[cfg(feature = "cuda")]
            if let Ok(device) = zeph_llm::candle_provider::Device::new_cuda(0) {
                return Ok(device);
            }
            Ok(zeph_llm::candle_provider::Device::Cpu)
        }
        _ => Ok(zeph_llm::candle_provider::Device::Cpu),
    }
}

/// Determine the effective embedding model name for the memory subsystem.
///
/// Resolution order:
/// 1. `embedding_model` from the `[[llm.providers]]` entry marked `embed = true`
/// 2. `embedding_model` from the first entry in `[[llm.providers]]`
/// 3. `[llm] embedding_model` global fallback
#[must_use]
pub fn effective_embedding_model(config: &Config) -> String {
    // Prefer a dedicated embed provider.
    if let Some(m) = config
        .llm
        .providers
        .iter()
        .find(|e| e.embed)
        .and_then(|e| e.embedding_model.as_ref())
    {
        return m.clone();
    }
    // Fall back to the first provider's embedding model.
    if let Some(m) = config
        .llm
        .providers
        .first()
        .and_then(|e| e.embedding_model.as_ref())
    {
        return m.clone();
    }
    config.llm.embedding_model.clone()
}

#[cfg(test)]
mod tests {
    #[cfg(feature = "candle")]
    use super::select_device;

    #[cfg(feature = "candle")]
    #[test]
    fn select_device_cpu_default() {
        let device = select_device("cpu").unwrap();
        assert!(matches!(device, zeph_llm::candle_provider::Device::Cpu));
    }

    #[cfg(feature = "candle")]
    #[test]
    fn select_device_unknown_defaults_to_cpu() {
        let device = select_device("unknown").unwrap();
        assert!(matches!(device, zeph_llm::candle_provider::Device::Cpu));
    }

    #[cfg(all(feature = "candle", not(feature = "metal")))]
    #[test]
    fn select_device_metal_without_feature_errors() {
        let result = select_device("metal");
        assert!(result.is_err());
        assert!(result.unwrap_err().to_string().contains("metal feature"));
    }

    #[cfg(all(feature = "candle", not(feature = "cuda")))]
    #[test]
    fn select_device_cuda_without_feature_errors() {
        let result = select_device("cuda");
        assert!(result.is_err());
        assert!(result.unwrap_err().to_string().contains("cuda feature"));
    }

    #[cfg(feature = "candle")]
    #[test]
    fn select_device_auto_fallback() {
        let device = select_device("auto").unwrap();
        assert!(matches!(
            device,
            zeph_llm::candle_provider::Device::Cpu
                | zeph_llm::candle_provider::Device::Cuda(_)
                | zeph_llm::candle_provider::Device::Metal(_)
        ));
    }
}