converge_core/

llm.rs

// Copyright 2024-2025 Aprio One AB, Sweden
// Author: Kenneth Pernyer, kenneth@aprio.one
// SPDX-License-Identifier: LicenseRef-Proprietary
// All rights reserved. This source code is proprietary and confidential.
// Unauthorized copying, modification, or distribution is strictly prohibited.

//! LLM provider abstraction for Converge.
//!
//! This module provides a trait-based abstraction for LLM providers,
//! allowing different backends (Claude, GPT, local models) to be swapped.
//!
//! # Architecture
//!
//! ```text
//! LlmProvider (trait)
//!     ├── MockProvider (testing)
//!     ├── AnthropicProvider (Claude API) [requires "llm" feature]
//!     └── OpenAiProvider (GPT API) [future]
//! ```
//!
//! # Example
//!
//! ```
//! use converge_core::llm::{LlmProvider, LlmRequest, MockProvider, MockResponse};
//!
//! // Create a mock provider for testing
//! let provider = MockProvider::new(vec![
//!     MockResponse::success("The market is growing", 0.85),
//! ]);
//!
//! let request = LlmRequest::new("Analyze the Nordic B2B market");
//! let response = provider.complete(&request).expect("should succeed");
//!
//! assert!(response.content.contains("market"));
//! ```

use serde::{Deserialize, Serialize};
use std::fmt;

// =============================================================================
// CORE TYPES
// =============================================================================

/// Request to an LLM provider.
#[derive(Debug, Clone, Serialize)]
pub struct LlmRequest {
    /// The user prompt.
    pub prompt: String,
    /// Optional system prompt.
    pub system: Option<String>,
    /// Maximum tokens to generate.
    pub max_tokens: u32,
    /// Temperature (0.0 = deterministic, 1.0 = creative).
    pub temperature: f64,
    /// Optional stop sequences.
    pub stop_sequences: Vec<String>,
}

impl LlmRequest {
    /// Creates a new request with default parameters.
    #[must_use]
    pub fn new(prompt: impl Into<String>) -> Self {
        Self {
            prompt: prompt.into(),
            system: None,
            max_tokens: 1024,
            temperature: 0.7,
            stop_sequences: Vec::new(),
        }
    }

    /// Sets the system prompt.
    #[must_use]
    pub fn with_system(mut self, system: impl Into<String>) -> Self {
        self.system = Some(system.into());
        self
    }

    /// Sets max tokens.
    #[must_use]
    pub fn with_max_tokens(mut self, max_tokens: u32) -> Self {
        self.max_tokens = max_tokens;
        self
    }

    /// Sets temperature.
    #[must_use]
    pub fn with_temperature(mut self, temperature: f64) -> Self {
        self.temperature = temperature;
        self
    }

    /// Adds a stop sequence.
    #[must_use]
    pub fn with_stop_sequence(mut self, stop: impl Into<String>) -> Self {
        self.stop_sequences.push(stop.into());
        self
    }
}

/// Response from an LLM provider.
#[derive(Debug, Clone, Deserialize)]
pub struct LlmResponse {
    /// The generated content.
    pub content: String,
    /// The model that generated this response.
    pub model: String,
    /// Token usage statistics.
    pub usage: TokenUsage,
    /// Finish reason.
    pub finish_reason: FinishReason,
}

/// Token usage statistics.
#[derive(Debug, Clone, Default, Deserialize)]
pub struct TokenUsage {
    /// Tokens in the prompt.
    pub prompt_tokens: u32,
    /// Tokens in the completion.
    pub completion_tokens: u32,
    /// Total tokens used.
    pub total_tokens: u32,
}

/// Reason the generation stopped.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum FinishReason {
    /// Natural end of response.
    Stop,
    /// Hit `max_tokens` limit.
    MaxTokens,
    /// Hit a stop sequence.
    StopSequence,
    /// Content was filtered.
    ContentFilter,
}

/// Error from an LLM provider.
#[derive(Debug, Clone)]
pub struct LlmError {
    /// Error kind.
    pub kind: LlmErrorKind,
    /// Human-readable message.
    pub message: String,
    /// Whether the request can be retried.
    pub retryable: bool,
}

impl fmt::Display for LlmError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{:?}: {}", self.kind, self.message)
    }
}

impl std::error::Error for LlmError {}

/// Kind of LLM error.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LlmErrorKind {
    /// Invalid API key.
    Authentication,
    /// Rate limit exceeded.
    RateLimit,
    /// Invalid request parameters.
    InvalidRequest,
    /// Model not available.
    ModelNotFound,
    /// Network or connection error.
    Network,
    /// Provider returned an error.
    ProviderError,
    /// Response couldn't be parsed.
    ParseError,
    /// Request timed out.
    Timeout,
}

impl LlmError {
    /// Creates an authentication error.
    #[must_use]
    pub fn auth(message: impl Into<String>) -> Self {
        Self {
            kind: LlmErrorKind::Authentication,
            message: message.into(),
            retryable: false,
        }
    }

    /// Creates a rate limit error.
    #[must_use]
    pub fn rate_limit(message: impl Into<String>) -> Self {
        Self {
            kind: LlmErrorKind::RateLimit,
            message: message.into(),
            retryable: true,
        }
    }

    /// Creates a network error.
    #[must_use]
    pub fn network(message: impl Into<String>) -> Self {
        Self {
            kind: LlmErrorKind::Network,
            message: message.into(),
            retryable: true,
        }
    }

    /// Creates a parse error.
    #[must_use]
    pub fn parse(message: impl Into<String>) -> Self {
        Self {
            kind: LlmErrorKind::ParseError,
            message: message.into(),
            retryable: false,
        }
    }

    /// Creates a provider error.
    #[must_use]
    pub fn provider(message: impl Into<String>) -> Self {
        Self {
            kind: LlmErrorKind::ProviderError,
            message: message.into(),
            retryable: false,
        }
    }
}

// =============================================================================
// LLM PROVIDER TRAIT
// =============================================================================

/// Trait for LLM providers.
///
/// Implement this trait to add support for new LLM backends.
///
/// # Deprecation Notice
///
/// This trait is deprecated in favor of the capability boundary traits in
/// `converge_core::traits`:
///
/// - [`ChatBackend`](crate::traits::ChatBackend) - For chat completion
/// - [`EmbedBackend`](crate::traits::EmbedBackend) - For embedding generation
/// - [`LlmBackend`](crate::traits::LlmBackend) - Umbrella combining both
///
/// See `converge-core/BOUNDARY.md` for migration guide and trait ownership.
#[deprecated(
    since = "0.2.0",
    note = "Use converge_core::traits::{ChatBackend, EmbedBackend, LlmBackend} instead. See BOUNDARY.md for migration."
)]
pub trait LlmProvider: Send + Sync {
    /// The name of this provider (e.g., "anthropic", "openai").
    fn name(&self) -> &str;

    /// The model being used (e.g., "claude-3-opus", "gpt-4").
    fn model(&self) -> &str;

    /// Sends a completion request to the LLM.
    ///
    /// # Errors
    ///
    /// Returns `LlmError` if the request fails.
    fn complete(&self, request: &LlmRequest) -> Result<LlmResponse, LlmError>;

    /// Returns a provenance string for tracking (e.g., "claude-3-opus:abc123").
    fn provenance(&self, request_id: &str) -> String {
        format!("{}:{}", self.model(), request_id)
    }
}

// =============================================================================
// MOCK PROVIDER (for testing)
// =============================================================================

/// Pre-configured response for `MockProvider`.
#[derive(Debug, Clone)]
pub struct MockResponse {
    /// The content to return.
    pub content: String,
    /// Simulated confidence (used by callers to set `ProposedFact` confidence).
    pub confidence: f64,
    /// Whether this response should succeed.
    pub success: bool,
    /// Optional error to return.
    pub error: Option<LlmError>,
}

impl MockResponse {
    /// Creates a successful mock response.
    #[must_use]
    pub fn success(content: impl Into<String>, confidence: f64) -> Self {
        Self {
            content: content.into(),
            confidence,
            success: true,
            error: None,
        }
    }

    /// Creates a failing mock response.
    #[must_use]
    pub fn failure(error: LlmError) -> Self {
        Self {
            content: String::new(),
            confidence: 0.0,
            success: false,
            error: Some(error),
        }
    }
}

/// Mock LLM provider for testing.
///
/// Returns pre-configured responses in order. Useful for deterministic tests.
pub struct MockProvider {
    model: String,
    responses: std::sync::Mutex<Vec<MockResponse>>,
    call_count: std::sync::atomic::AtomicUsize,
}

impl MockProvider {
    /// Creates a new mock provider with pre-configured responses.
    #[must_use]
    pub fn new(responses: Vec<MockResponse>) -> Self {
        Self {
            model: "mock-model".into(),
            responses: std::sync::Mutex::new(responses),
            call_count: std::sync::atomic::AtomicUsize::new(0),
        }
    }

    /// Creates a mock that always returns the same response.
    #[must_use]
    pub fn constant(content: impl Into<String>, confidence: f64) -> Self {
        let content = content.into();
        // Create many copies for repeated calls
        let responses = (0..100)
            .map(|_| MockResponse::success(content.clone(), confidence))
            .collect();
        Self::new(responses)
    }

    /// Returns the number of times `complete` was called.
    #[must_use]
    pub fn call_count(&self) -> usize {
        self.call_count.load(std::sync::atomic::Ordering::SeqCst)
    }
}

impl LlmProvider for MockProvider {
    fn name(&self) -> &'static str {
        "mock"
    }

    fn model(&self) -> &str {
        &self.model
    }

    fn complete(&self, _request: &LlmRequest) -> Result<LlmResponse, LlmError> {
        self.call_count
            .fetch_add(1, std::sync::atomic::Ordering::SeqCst);

        let mut responses = self.responses.lock().expect("MockProvider mutex poisoned");

        if responses.is_empty() {
            return Err(LlmError::provider("MockProvider: no more responses"));
        }

        let response = responses.remove(0);

        if let Some(error) = response.error {
            return Err(error);
        }

        Ok(LlmResponse {
            content: response.content,
            model: self.model.clone(),
            usage: TokenUsage {
                prompt_tokens: 10,
                completion_tokens: 20,
                total_tokens: 30,
            },
            finish_reason: FinishReason::Stop,
        })
    }
}

// =============================================================================
// LLM AGENT
// =============================================================================

use crate::agent::Agent;
use crate::context::{Context, ContextKey, ProposedFact};
use crate::effect::AgentEffect;
use crate::validation::encode_proposal;
use std::sync::Arc;

/// Configuration for an LLM-powered agent.
#[derive(Clone)]
pub struct LlmAgentConfig {
    /// System prompt for the LLM.
    pub system_prompt: String,
    /// Template for the user prompt (use {context} for context injection).
    /// Deprecated: Use `prompt_format` instead for new code.
    pub prompt_template: String,
    /// Prompt format (EDN by default for token efficiency).
    pub prompt_format: crate::prompt::PromptFormat,
    /// Target context key for generated proposals.
    pub target_key: ContextKey,
    /// Dependencies that trigger this agent.
    pub dependencies: Vec<ContextKey>,
    /// Default confidence for proposals (can be overridden by parser).
    pub default_confidence: f64,
    /// Maximum tokens for generation.
    pub max_tokens: u32,
    /// Temperature for generation.
    pub temperature: f64,
    /// Requirements for model selection (optional).
    /// If set, a model selector can be used to choose an appropriate provider.
    /// Note: Model selection is handled by the provider crate, not core.
    pub requirements: Option<crate::model_selection::AgentRequirements>,
}

impl Default for LlmAgentConfig {
    fn default() -> Self {
        Self {
            system_prompt: String::new(),
            prompt_template: "{context}".into(),
            prompt_format: crate::prompt::PromptFormat::Edn,
            target_key: ContextKey::Hypotheses,
            dependencies: vec![ContextKey::Seeds],
            default_confidence: 0.7,
            max_tokens: 1024,
            temperature: 0.7,
            requirements: None,
        }
    }
}

/// Parser for LLM responses into proposals.
pub trait ResponseParser: Send + Sync {
    /// Parses an LLM response into proposals.
    fn parse(&self, response: &LlmResponse, target_key: ContextKey) -> Vec<ProposedFact>;
}

/// Simple parser that creates one proposal from the entire response.
pub struct SimpleParser {
    /// ID prefix for generated proposals.
    pub id_prefix: String,
    /// Default confidence.
    pub confidence: f64,
}

impl Default for SimpleParser {
    fn default() -> Self {
        Self {
            id_prefix: "llm".into(),
            confidence: 0.7,
        }
    }
}

impl ResponseParser for SimpleParser {
    fn parse(&self, response: &LlmResponse, target_key: ContextKey) -> Vec<ProposedFact> {
        let content = response.content.trim();
        if content.is_empty() {
            return Vec::new();
        }

        let id = format!("{}-{}", self.id_prefix, uuid_v4_simple());

        vec![ProposedFact {
            key: target_key,
            id,
            content: content.to_string(),
            confidence: self.confidence,
            provenance: response.model.clone(),
        }]
    }
}

/// Parser that splits response into multiple proposals by delimiter.
pub struct MultiLineParser {
    /// ID prefix for generated proposals.
    pub id_prefix: String,
    /// Delimiter to split on (e.g., "\n", "---").
    pub delimiter: String,
    /// Default confidence.
    pub confidence: f64,
}

impl MultiLineParser {
    /// Creates a parser that splits on newlines.
    #[must_use]
    pub fn newline(id_prefix: impl Into<String>, confidence: f64) -> Self {
        Self {
            id_prefix: id_prefix.into(),
            delimiter: "\n".into(),
            confidence,
        }
    }
}

impl ResponseParser for MultiLineParser {
    fn parse(&self, response: &LlmResponse, target_key: ContextKey) -> Vec<ProposedFact> {
        response
            .content
            .split(&self.delimiter)
            .map(str::trim)
            .filter(|s| !s.is_empty())
            .enumerate()
            .map(|(i, content)| ProposedFact {
                key: target_key,
                id: format!("{}-{}", self.id_prefix, i),
                content: content.to_string(),
                confidence: self.confidence,
                provenance: response.model.clone(),
            })
            .collect()
    }
}

/// An agent powered by an LLM provider.
///
/// This agent:
/// 1. Builds a prompt from context
/// 2. Calls the LLM provider
/// 3. Parses the response into `ProposedFacts`
/// 4. Emits them to the Proposals key for validation
///
/// # Idempotency
///
/// This agent uses **context-based idempotency**: it checks whether it has
/// already contributed by looking for facts with its ID prefix in the target key.
/// There is no hidden `has_run` state — all lifecycle control is derived from context.
pub struct LlmAgent {
    name: String,
    provider: Arc<dyn LlmProvider>,
    config: LlmAgentConfig,
    parser: Arc<dyn ResponseParser>,
    /// Full dependencies including `target_key` (for idempotency checks).
    /// Cached at construction to satisfy the `&[ContextKey]` return type.
    full_dependencies: Vec<ContextKey>,
}

impl LlmAgent {
    /// Creates a new LLM agent.
    ///
    /// The agent's dependencies automatically include the target key to support
    /// context-based idempotency (checking if this agent already contributed).
    pub fn new(
        name: impl Into<String>,
        provider: Arc<dyn LlmProvider>,
        config: LlmAgentConfig,
    ) -> Self {
        let name_str = name.into();

        // Build full dependencies: config dependencies + target_key for idempotency
        let mut full_dependencies = config.dependencies.clone();
        if !full_dependencies.contains(&config.target_key) {
            full_dependencies.push(config.target_key);
        }

        // Default parser uses agent name as ID prefix for stable identification
        let parser = Arc::new(SimpleParser {
            id_prefix: name_str.clone(),
            confidence: 0.7,
        });

        Self {
            name: name_str,
            provider,
            config,
            parser,
            full_dependencies,
        }
    }

    /// Sets a custom response parser.
    #[must_use]
    pub fn with_parser(mut self, parser: Arc<dyn ResponseParser>) -> Self {
        self.parser = parser;
        self
    }

    /// Builds the prompt from context using the configured format.
    fn build_prompt(&self, ctx: &Context) -> String {
        use std::fmt::Write;

        // Use new compact prompt format if EDN is selected
        if matches!(self.config.prompt_format, crate::prompt::PromptFormat::Edn) {
            let prompt_ctx =
                crate::prompt::PromptContext::from_context(ctx, &self.config.dependencies);
            let output_contract =
                crate::prompt::OutputContract::new("proposed-fact", self.config.target_key);

            // Extract objective from template (remove {context} placeholder)
            let objective = if self.config.prompt_template == "{context}" {
                format!("analyze-{:?}", self.config.target_key).to_lowercase()
            } else {
                self.config
                    .prompt_template
                    .replace("{context}", "")
                    .trim()
                    .to_string()
            };

            let agent_prompt = crate::prompt::AgentPrompt::new(
                crate::prompt::AgentRole::Proposer,
                objective,
                prompt_ctx,
                output_contract,
            )
            .with_constraint(crate::prompt::Constraint::NoHallucinate)
            .with_constraint(crate::prompt::Constraint::NoInvent);

            return agent_prompt.serialize(self.config.prompt_format);
        }

        // Fallback to plain text format (backward compatible)
        let mut context_str = String::new();

        for &key in &self.config.dependencies {
            let facts = ctx.get(key);
            if !facts.is_empty() {
                let _ = writeln!(context_str, "\n## {key:?}");
                for fact in facts {
                    let _ = writeln!(context_str, "- {}: {}", fact.id, fact.content);
                }
            }
        }

        self.config
            .prompt_template
            .replace("{context}", &context_str)
    }
}

impl Agent for LlmAgent {
    fn name(&self) -> &str {
        &self.name
    }

    fn dependencies(&self) -> &[ContextKey] {
        // Includes target_key for idempotency re-evaluation
        &self.full_dependencies
    }

    fn accepts(&self, ctx: &Context) -> bool {
        // Precondition: at least one input dependency has data
        let has_input = self.config.dependencies.iter().any(|k| ctx.has(*k));
        if !has_input {
            return false;
        }

        // Idempotency: check if we've already contributed to target key
        // Facts from this agent have IDs starting with "{agent_name}-"
        let my_prefix = format!("{}-", self.name);
        let already_contributed = ctx
            .get(self.config.target_key)
            .iter()
            .any(|f| f.id.starts_with(&my_prefix));

        !already_contributed
    }

    fn execute(&self, ctx: &Context) -> AgentEffect {
        // No hidden state mutation - idempotency is context-based

        let prompt = self.build_prompt(ctx);

        let request = LlmRequest::new(prompt)
            .with_system(self.config.system_prompt.clone())
            .with_max_tokens(self.config.max_tokens)
            .with_temperature(self.config.temperature);

        match self.provider.complete(&request) {
            Ok(response) => {
                let proposals = self.parser.parse(&response, self.config.target_key);

                // Encode proposals for the validation pipeline
                let facts: Vec<_> = proposals.iter().map(encode_proposal).collect();

                AgentEffect::with_facts(facts)
            }
            Err(e) => {
                // Log the error but don't crash - emit nothing
                tracing::error!(agent = %self.name, error = %e, "LLM call failed");
                AgentEffect::empty()
            }
        }
    }
}

/// Generate a simple UUID-like string (not cryptographically secure).
fn uuid_v4_simple() -> String {
    use std::time::{SystemTime, UNIX_EPOCH};
    let nanos = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_nanos())
        .unwrap_or(0);
    format!("{:x}", nanos % 0xFFFF_FFFF)
}

// =============================================================================
// LLM ROUTER - Opinionated model selection by role
// =============================================================================

/// The purpose/role an LLM is being used for.
///
/// This allows building opinionated configurations that route different
/// tasks to different models. For example:
/// - Use Perplexity for web research (grounded in search results)
/// - Use Gemini for fast analysis
/// - Use GPT for verification/second opinions
/// - Use Claude for synthesis and final output
///
/// The core is unopinionated - this enum allows the next layer to be opinionated.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum LlmRole {
    /// Web research - gathering information from the internet.
    /// Good choices: Perplexity, Gemini with grounding.
    WebResearch,

    /// Fast analysis of structured data.
    /// Good choices: Gemini Flash, GPT-4o-mini.
    FastAnalysis,

    /// Deep analysis requiring nuanced understanding.
    /// Good choices: Claude Opus, GPT-4, Gemini Pro.
    DeepAnalysis,

    /// Verification/second opinion on another model's output.
    /// Best practice: Use a different model family than the original.
    Verification,

    /// Creative generation (strategies, ideas, hypotheses).
    /// Good choices: Claude, GPT-4.
    Creative,

    /// Synthesis - combining multiple sources into coherent output.
    /// Good choices: Claude Opus.
    Synthesis,

    /// Code generation and analysis.
    /// Good choices: Claude, GPT-4, specialized code models.
    Code,

    /// Summarization of long content.
    /// Good choices: Models with long context windows.
    Summarization,

    /// Custom role for domain-specific purposes.
    Custom(&'static str),
}

impl fmt::Display for LlmRole {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::WebResearch => write!(f, "web-research"),
            Self::FastAnalysis => write!(f, "fast-analysis"),
            Self::DeepAnalysis => write!(f, "deep-analysis"),
            Self::Verification => write!(f, "verification"),
            Self::Creative => write!(f, "creative"),
            Self::Synthesis => write!(f, "synthesis"),
            Self::Code => write!(f, "code"),
            Self::Summarization => write!(f, "summarization"),
            Self::Custom(name) => write!(f, "custom:{name}"),
        }
    }
}

/// Routes LLM requests to appropriate providers based on role.
///
/// # Example
///
/// ```
/// use converge_core::llm::{LlmRouter, LlmRole, MockProvider};
/// use std::sync::Arc;
///
/// let gemini = Arc::new(MockProvider::constant("Gemini analysis", 0.85));
/// let claude = Arc::new(MockProvider::constant("Claude synthesis", 0.90));
/// let perplexity = Arc::new(MockProvider::constant("Web results", 0.80));
///
/// let router = LlmRouter::new()
///     .with_provider(LlmRole::WebResearch, perplexity)
///     .with_provider(LlmRole::FastAnalysis, gemini.clone())
///     .with_provider(LlmRole::Synthesis, claude.clone())
///     .with_default(claude);
///
/// // Routes to appropriate provider based on role
/// let provider = router.get(LlmRole::WebResearch).unwrap();
/// assert_eq!(provider.name(), "mock");
/// ```
pub struct LlmRouter {
    /// Role-to-provider mapping.
    providers: std::collections::HashMap<LlmRole, Arc<dyn LlmProvider>>,
    /// Default provider for unmapped roles.
    default: Option<Arc<dyn LlmProvider>>,
}

impl Default for LlmRouter {
    fn default() -> Self {
        Self::new()
    }
}

impl LlmRouter {
    /// Creates a new empty router.
    #[must_use]
    pub fn new() -> Self {
        Self {
            providers: std::collections::HashMap::new(),
            default: None,
        }
    }

    /// Registers a provider for a specific role.
    #[must_use]
    pub fn with_provider(mut self, role: LlmRole, provider: Arc<dyn LlmProvider>) -> Self {
        self.providers.insert(role, provider);
        self
    }

    /// Sets the default provider for unmapped roles.
    #[must_use]
    pub fn with_default(mut self, provider: Arc<dyn LlmProvider>) -> Self {
        self.default = Some(provider);
        self
    }

    /// Gets the provider for a role, falling back to default.
    #[must_use]
    pub fn get(&self, role: LlmRole) -> Option<Arc<dyn LlmProvider>> {
        self.providers
            .get(&role)
            .cloned()
            .or_else(|| self.default.clone())
    }

    /// Checks if a role has a registered provider.
    #[must_use]
    pub fn has_provider(&self, role: LlmRole) -> bool {
        self.providers.contains_key(&role) || self.default.is_some()
    }

    /// Lists all registered roles.
    #[must_use]
    pub fn roles(&self) -> Vec<LlmRole> {
        self.providers.keys().copied().collect()
    }

    /// Completes a request using the provider for the given role.
    ///
    /// # Errors
    ///
    /// Returns error if no provider is configured for the role, or if the
    /// provider fails.
    pub fn complete(&self, role: LlmRole, request: &LlmRequest) -> Result<LlmResponse, LlmError> {
        let provider = self.get(role).ok_or_else(|| {
            LlmError::provider(format!("No provider configured for role: {role}"))
        })?;
        provider.complete(request)
    }
}

/// Configuration for a multi-model pipeline.
///
/// Allows defining which models to use for each stage of a workflow.
/// This is where opinionated choices live.
///
/// # Example
///
/// ```
/// use converge_core::llm::{ModelConfig, LlmRole};
///
/// let config = ModelConfig::new()
///     .model(LlmRole::WebResearch, "perplexity", "sonar-pro")
///     .model(LlmRole::FastAnalysis, "google", "gemini-2.0-flash")
///     .model(LlmRole::DeepAnalysis, "anthropic", "claude-opus-4")
///     .model(LlmRole::Verification, "openai", "gpt-4.5")
///     .model(LlmRole::Synthesis, "anthropic", "claude-opus-4");
///
/// assert_eq!(config.get(LlmRole::WebResearch), Some(("perplexity", "sonar-pro")));
/// ```
#[derive(Debug, Clone, Default)]
pub struct ModelConfig {
    /// Role to (`provider_name`, `model_id`) mapping.
    models: std::collections::HashMap<LlmRole, (String, String)>,
}

impl ModelConfig {
    /// Creates a new empty configuration.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Configures a model for a role.
    #[must_use]
    pub fn model(
        mut self,
        role: LlmRole,
        provider: impl Into<String>,
        model_id: impl Into<String>,
    ) -> Self {
        self.models.insert(role, (provider.into(), model_id.into()));
        self
    }

    /// Gets the configured model for a role.
    #[must_use]
    pub fn get(&self, role: LlmRole) -> Option<(&str, &str)> {
        self.models
            .get(&role)
            .map(|(p, m)| (p.as_str(), m.as_str()))
    }

    /// Checks if a role has a configured model.
    #[must_use]
    pub fn has(&self, role: LlmRole) -> bool {
        self.models.contains_key(&role)
    }

    /// Creates a preset for high-quality, diverse model selection.
    ///
    /// Uses different model families for verification to catch errors.
    #[must_use]
    pub fn high_quality() -> Self {
        Self::new()
            .model(LlmRole::WebResearch, "perplexity", "sonar-pro")
            .model(LlmRole::FastAnalysis, "google", "gemini-2.0-flash")
            .model(LlmRole::DeepAnalysis, "anthropic", "claude-opus-4")
            .model(LlmRole::Verification, "openai", "gpt-4.5")
            .model(LlmRole::Creative, "anthropic", "claude-opus-4")
            .model(LlmRole::Synthesis, "anthropic", "claude-opus-4")
            .model(LlmRole::Code, "anthropic", "claude-sonnet-4")
            .model(LlmRole::Summarization, "google", "gemini-2.0-flash")
    }

    /// Creates a preset optimized for speed and cost.
    #[must_use]
    pub fn fast() -> Self {
        Self::new()
            .model(LlmRole::WebResearch, "perplexity", "sonar")
            .model(LlmRole::FastAnalysis, "google", "gemini-2.0-flash")
            .model(LlmRole::DeepAnalysis, "google", "gemini-2.0-flash")
            .model(LlmRole::Verification, "anthropic", "claude-haiku-3.5")
            .model(LlmRole::Creative, "anthropic", "claude-sonnet-4")
            .model(LlmRole::Synthesis, "anthropic", "claude-sonnet-4")
            .model(LlmRole::Code, "anthropic", "claude-sonnet-4")
            .model(LlmRole::Summarization, "google", "gemini-2.0-flash")
    }

    /// Creates a preset using only Anthropic models.
    #[must_use]
    pub fn anthropic_only() -> Self {
        Self::new()
            .model(LlmRole::WebResearch, "anthropic", "claude-sonnet-4")
            .model(LlmRole::FastAnalysis, "anthropic", "claude-haiku-3.5")
            .model(LlmRole::DeepAnalysis, "anthropic", "claude-opus-4")
            .model(LlmRole::Verification, "anthropic", "claude-sonnet-4")
            .model(LlmRole::Creative, "anthropic", "claude-opus-4")
            .model(LlmRole::Synthesis, "anthropic", "claude-opus-4")
            .model(LlmRole::Code, "anthropic", "claude-sonnet-4")
            .model(LlmRole::Summarization, "anthropic", "claude-haiku-3.5")
    }
}

// =============================================================================
// TESTS
// =============================================================================

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn mock_provider_returns_responses_in_order() {
        let provider = MockProvider::new(vec![
            MockResponse::success("First response", 0.8),
            MockResponse::success("Second response", 0.9),
        ]);

        let request = LlmRequest::new("test");

        let r1 = provider.complete(&request).unwrap();
        assert_eq!(r1.content, "First response");

        let r2 = provider.complete(&request).unwrap();
        assert_eq!(r2.content, "Second response");

        assert_eq!(provider.call_count(), 2);
    }

    #[test]
    fn mock_provider_can_return_errors() {
        let provider = MockProvider::new(vec![MockResponse::failure(LlmError::rate_limit(
            "Too many requests",
        ))]);

        let request = LlmRequest::new("test");
        let result = provider.complete(&request);

        assert!(result.is_err());
        let err = result.unwrap_err();
        assert_eq!(err.kind, LlmErrorKind::RateLimit);
        assert!(err.retryable);
    }

    #[test]
    fn constant_mock_returns_same_response() {
        let provider = MockProvider::constant("Always this", 0.75);

        let request = LlmRequest::new("test");

        for _ in 0..5 {
            let response = provider.complete(&request).unwrap();
            assert_eq!(response.content, "Always this");
        }
    }

    #[test]
    fn request_builder_works() {
        let request = LlmRequest::new("Hello")
            .with_system("You are helpful")
            .with_max_tokens(500)
            .with_temperature(0.5)
            .with_stop_sequence("\n");

        assert_eq!(request.prompt, "Hello");
        assert_eq!(request.system, Some("You are helpful".into()));
        assert_eq!(request.max_tokens, 500);
        assert!((request.temperature - 0.5).abs() < 0.001);
        assert_eq!(request.stop_sequences, vec!["\n"]);
    }

    #[test]
    fn provenance_string_includes_model() {
        let provider = MockProvider::constant("test", 0.8);
        let provenance = provider.provenance("req-123");
        assert_eq!(provenance, "mock-model:req-123");
    }

    #[test]
    fn llm_agent_emits_proposals() {
        use crate::context::Fact;
        use crate::engine::Engine;
        use crate::validation::ValidationAgent;

        let provider = Arc::new(MockProvider::constant(
            "The Nordic market shows strong growth potential",
            0.8,
        ));

        let config = LlmAgentConfig {
            system_prompt: "You are a market analyst".into(),
            prompt_template: "Analyze this market: {context}".into(),
            target_key: ContextKey::Hypotheses,
            dependencies: vec![ContextKey::Seeds],
            default_confidence: 0.75,
            ..Default::default()
        };

        let mut engine = Engine::new();

        // Add a seed
        let mut ctx = Context::new();
        let _ = ctx.add_fact(Fact {
            key: ContextKey::Seeds,
            id: "market".into(),
            content: "Nordic B2B SaaS".into(),
        });

        // Register LLM agent and validator
        engine.register(LlmAgent::new("MarketAnalyst", provider.clone(), config));
        engine.register(ValidationAgent::with_defaults());

        let result = engine.run(ctx).expect("should converge");

        // The LLM agent should have called the provider
        assert!(provider.call_count() > 0);

        // The proposal should have been validated and promoted
        let hypotheses = result.context.get(ContextKey::Hypotheses);
        assert_eq!(hypotheses.len(), 1);
        assert!(hypotheses[0].content.contains("Nordic"));
    }

    #[test]
    fn llm_agent_handles_provider_errors() {
        use crate::context::Fact;
        use crate::engine::Engine;

        let provider = Arc::new(MockProvider::new(vec![MockResponse::failure(
            LlmError::rate_limit("Too many requests"),
        )]));

        let config = LlmAgentConfig {
            dependencies: vec![ContextKey::Seeds],
            ..Default::default()
        };

        let mut engine = Engine::new();

        let mut ctx = Context::new();
        let _ = ctx.add_fact(Fact {
            key: ContextKey::Seeds,
            id: "test".into(),
            content: "test".into(),
        });

        engine.register(LlmAgent::new("FailingAgent", provider, config));

        // Should converge without crashing
        let result = engine.run(ctx).expect("should converge despite error");
        assert!(result.converged);

        // No proposals should have been emitted
        assert!(result.context.get(ContextKey::Proposals).is_empty());
    }

    #[test]
    fn multi_line_parser_splits_response() {
        let parser = MultiLineParser::newline("item", 0.7);

        let response = LlmResponse {
            content: "First insight\nSecond insight\n\nThird insight".into(),
            model: "test-model".into(),
            usage: TokenUsage::default(),
            finish_reason: FinishReason::Stop,
        };

        let proposals = parser.parse(&response, ContextKey::Signals);

        assert_eq!(proposals.len(), 3);
        assert_eq!(proposals[0].id, "item-0");
        assert_eq!(proposals[0].content, "First insight");
        assert_eq!(proposals[1].content, "Second insight");
        assert_eq!(proposals[2].content, "Third insight");
    }

    #[test]
    fn llm_agent_builds_prompt_from_context() {
        use crate::context::Fact;
        use crate::prompt::PromptFormat;

        let provider = Arc::new(MockProvider::constant("response", 0.8));

        let config = LlmAgentConfig {
            prompt_template: "Context:\n{context}\n\nAnalyze this.".into(),
            dependencies: vec![ContextKey::Seeds, ContextKey::Signals],
            prompt_format: PromptFormat::Plain, // Use plain format for template testing
            ..Default::default()
        };

        let agent = LlmAgent::new("TestAgent", provider, config);

        let mut ctx = Context::new();
        let _ = ctx.add_fact(Fact {
            key: ContextKey::Seeds,
            id: "seed-1".into(),
            content: "Market info".into(),
        });
        let _ = ctx.add_fact(Fact {
            key: ContextKey::Signals,
            id: "signal-1".into(),
            content: "Growth trend".into(),
        });

        let prompt = agent.build_prompt(&ctx);

        assert!(prompt.contains("Market info"));
        assert!(prompt.contains("Growth trend"));
        assert!(prompt.contains("Analyze this"));
    }

    // =========================================================================
    // ROUTER TESTS
    // =========================================================================

    #[test]
    fn router_routes_by_role() {
        let gemini = Arc::new(MockProvider::new(vec![MockResponse::success(
            "Gemini response",
            0.85,
        )]));
        let claude = Arc::new(MockProvider::new(vec![MockResponse::success(
            "Claude response",
            0.90,
        )]));

        let router = LlmRouter::new()
            .with_provider(LlmRole::FastAnalysis, gemini)
            .with_provider(LlmRole::Synthesis, claude);

        let request = LlmRequest::new("test");

        let fast_response = router.complete(LlmRole::FastAnalysis, &request).unwrap();
        assert_eq!(fast_response.content, "Gemini response");

        let synth_response = router.complete(LlmRole::Synthesis, &request).unwrap();
        assert_eq!(synth_response.content, "Claude response");
    }

    #[test]
    fn router_falls_back_to_default() {
        let default = Arc::new(MockProvider::constant("Default response", 0.75));

        let router = LlmRouter::new().with_default(default);

        let request = LlmRequest::new("test");

        // Any role should fall back to default
        let response = router.complete(LlmRole::WebResearch, &request).unwrap();
        assert_eq!(response.content, "Default response");

        let response = router.complete(LlmRole::Code, &request).unwrap();
        assert_eq!(response.content, "Default response");
    }

    #[test]
    fn router_returns_error_when_no_provider() {
        let router = LlmRouter::new(); // No providers

        let request = LlmRequest::new("test");
        let result = router.complete(LlmRole::WebResearch, &request);

        assert!(result.is_err());
        let err = result.unwrap_err();
        assert!(err.message.contains("No provider configured"));
    }

    #[test]
    fn model_config_stores_choices() {
        let config = ModelConfig::new()
            .model(LlmRole::WebResearch, "perplexity", "sonar-pro")
            .model(LlmRole::DeepAnalysis, "anthropic", "claude-opus-4");

        assert_eq!(
            config.get(LlmRole::WebResearch),
            Some(("perplexity", "sonar-pro"))
        );
        assert_eq!(
            config.get(LlmRole::DeepAnalysis),
            Some(("anthropic", "claude-opus-4"))
        );
        assert_eq!(config.get(LlmRole::Code), None);
    }

    #[test]
    fn model_config_presets_cover_all_standard_roles() {
        let high_quality = ModelConfig::high_quality();
        let fast = ModelConfig::fast();
        let anthropic = ModelConfig::anthropic_only();

        // All presets should cover the main roles
        for role in [
            LlmRole::WebResearch,
            LlmRole::FastAnalysis,
            LlmRole::DeepAnalysis,
            LlmRole::Verification,
            LlmRole::Creative,
            LlmRole::Synthesis,
            LlmRole::Code,
            LlmRole::Summarization,
        ] {
            assert!(high_quality.has(role), "high_quality missing {role}");
            assert!(fast.has(role), "fast missing {role}");
            assert!(anthropic.has(role), "anthropic missing {role}");
        }
    }

    #[test]
    fn high_quality_uses_different_families_for_verification() {
        let config = ModelConfig::high_quality();

        let (deep_provider, _) = config.get(LlmRole::DeepAnalysis).unwrap();
        let (verify_provider, _) = config.get(LlmRole::Verification).unwrap();

        // Verification should use a different provider family
        assert_ne!(
            deep_provider, verify_provider,
            "Verification should use different model family than deep analysis"
        );
    }

    #[test]
    fn llm_role_display() {
        assert_eq!(format!("{}", LlmRole::WebResearch), "web-research");
        assert_eq!(format!("{}", LlmRole::DeepAnalysis), "deep-analysis");
        assert_eq!(format!("{}", LlmRole::Custom("my-role")), "custom:my-role");
    }
}