liter-llm 1.16.0

//! Canonical, binding-friendly LLM client configuration.
//!
//! [`LlmConfig`] is plain serde data (no secrets, no trait objects, no
//! `Duration`) so it can be constructed directly from JSON/TOML/YAML in any
//! language binding and converted into a [`super::ClientConfigBuilder`] via
//! [`LlmConfig::into_client_builder`].
//!
//! Unlike [`super::FileConfig`] (which is `Deserialize`-only and hidden from
//! bindings), every type in this module is `Serialize + Deserialize` and
//! generates binding surface in every target language.

use std::collections::HashMap;
use std::time::Duration;

use serde::{Deserialize, Serialize};

/// Canonical configuration for an LLM client.
///
/// All fields except `model` are optional so that partially-specified
/// configs (e.g. from environment-driven defaults) round-trip cleanly.
/// Convert to a runtime client configuration via
/// [`LlmConfig::into_client_builder`].
///
/// `temperature` and `max_tokens` are request-time parameters rather than
/// client-level settings; they are carried on this struct for callers to
/// read when building individual requests, and are intentionally **not**
/// mapped by [`LlmConfig::into_client_builder`].
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct LlmConfig {
    /// Model identifier (e.g. `"gpt-4o"`, `"bedrock/anthropic.claude-3-sonnet-20240229-v1:0"`).
    pub model: String,
    /// API key for authentication.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub api_key: Option<String>,
    /// Override base URL. When set, all requests go here and provider
    /// auto-detection is skipped.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub base_url: Option<String>,
    /// Request timeout, in seconds.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub timeout_secs: Option<u64>,
    /// Maximum number of retries on 429 / 5xx responses.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_retries: Option<u32>,
    /// Sampling temperature for requests built from this config.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub temperature: Option<f64>,
    /// Maximum number of tokens to generate for requests built from this config.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_tokens: Option<u64>,
    /// Automatically load the API key from the provider's environment variable
    /// when no explicit key is provided (default: `true`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub load_env: Option<bool>,
    /// Extra headers sent on every request.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub headers: Option<HashMap<String, String>>,
    /// Custom provider configurations, in addition to the built-in providers.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub providers: Option<Vec<LlmProviderConfig>>,
    /// Response cache configuration.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cache: Option<LlmCacheConfig>,
    /// Budget enforcement configuration.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub budget: Option<LlmBudgetConfig>,
    /// Per-model rate limiting configuration.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub rate_limit: Option<LlmRateLimitConfig>,
    /// Enable per-request cost tracking.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cost_tracking: Option<bool>,
    /// Enable OpenTelemetry-compatible tracing spans.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub tracing: Option<bool>,
    /// Cooldown duration after transient errors, in seconds.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cooldown_secs: Option<u64>,
    /// Background health check interval, in seconds.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub health_check_secs: Option<u64>,
    /// AWS Bedrock configuration (region, credentials, cross-region routing).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub bedrock: Option<BedrockConfig>,
}

/// Response cache configuration.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct LlmCacheConfig {
    /// Maximum number of cached entries.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_entries: Option<usize>,
    /// Cache entry time-to-live, in seconds.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ttl_seconds: Option<u64>,
    /// Cache backend name (e.g. `"memory"`, or an `opendal` scheme).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub backend: Option<String>,
    /// Backend-specific configuration key/value pairs.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub backend_config: Option<HashMap<String, String>>,
}

/// Budget enforcement configuration.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct LlmBudgetConfig {
    /// Global spend limit in USD.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub global_limit: Option<f64>,
    /// Per-model spend limits in USD, keyed by model name.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub model_limits: Option<HashMap<String, f64>>,
    /// Enforcement mode: `"hard"` (reject over-budget requests) or `"soft"` (log only).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub enforcement: Option<String>,
}

/// Per-model rate limiting configuration.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct LlmRateLimitConfig {
    /// Requests per minute limit.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub rpm: Option<u32>,
    /// Tokens per minute limit.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub tpm: Option<u64>,
    /// Rate limit window, in seconds.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub window_seconds: Option<u64>,
}

/// A custom provider configuration entry.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct LlmProviderConfig {
    /// Provider name, used to key model prefix matching.
    pub name: String,
    /// Base URL for the provider's OpenAI-compatible API.
    pub base_url: String,
    /// Header name used to carry the API key (defaults to `Authorization` when unset).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub auth_header: Option<String>,
    /// Model name prefixes routed to this provider (e.g. `["my-provider/"]`).
    #[serde(default)]
    pub model_prefixes: Vec<String>,
}

/// AWS Bedrock configuration.
///
/// All fields are optional; anything left unset falls back to the standard
/// AWS environment variables (`AWS_DEFAULT_REGION` / `AWS_REGION`,
/// `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`,
/// `BEDROCK_CROSS_REGION`).
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct BedrockConfig {
    /// AWS region (e.g. `"us-east-1"`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub region: Option<String>,
    /// Cross-region inference profile prefix (e.g. `"us"`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cross_region_prefix: Option<String>,
    /// Explicit AWS access key ID.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub access_key_id: Option<String>,
    /// Explicit AWS secret access key.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub secret_access_key: Option<String>,
    /// Explicit AWS session token (temporary credentials).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub session_token: Option<String>,
}

impl LlmConfig {
    /// Convert into a [`super::ClientConfigBuilder`], applying every field
    /// that is set.
    ///
    /// `model`, `temperature`, and `max_tokens` are request-time parameters
    /// and are not mapped onto the builder; read them directly from this
    /// struct when constructing individual requests.
    pub fn into_client_builder(self) -> super::ClientConfigBuilder {
        let api_key = self.api_key.unwrap_or_default();
        let mut builder = super::ClientConfigBuilder::new(api_key);

        if let Some(enabled) = self.load_env {
            builder = builder.load_env(enabled);
        }
        if let Some(url) = self.base_url {
            builder = builder.base_url(url);
        }
        if let Some(t) = self.timeout_secs {
            builder = builder.timeout(Duration::from_secs(t));
        }
        if let Some(r) = self.max_retries {
            builder = builder.max_retries(r);
        }

        #[cfg(any(feature = "native-http", feature = "wasm-http"))]
        if let Some(headers) = self.headers {
            for (k, v) in headers {
                if reqwest::header::HeaderName::from_bytes(k.as_bytes()).is_ok()
                    && reqwest::header::HeaderValue::from_str(&v).is_ok()
                {
                    builder.config.extra_headers.push((k, v));
                }
            }
        }

        #[cfg(feature = "tower")]
        {
            if let Some(cache) = self.cache {
                use crate::tower::{CacheBackend, CacheConfig};
                let backend = match cache.backend.as_deref() {
                    Some("memory") | None => CacheBackend::Memory,
                    #[cfg(feature = "opendal-cache")]
                    Some(scheme) => CacheBackend::OpenDal {
                        scheme: scheme.to_string(),
                        config: cache.backend_config.unwrap_or_default(),
                    },
                    #[cfg(not(feature = "opendal-cache"))]
                    Some(_) => CacheBackend::Memory,
                };
                builder = builder.cache(CacheConfig {
                    max_entries: cache.max_entries.unwrap_or(256),
                    ttl: Duration::from_secs(cache.ttl_seconds.unwrap_or(300)),
                    backend,
                });
            }

            if let Some(budget) = self.budget {
                use crate::tower::{BudgetConfig, Enforcement};
                builder = builder.budget(BudgetConfig {
                    global_limit: budget.global_limit,
                    model_limits: budget.model_limits.unwrap_or_default(),
                    enforcement: match budget.enforcement.as_deref() {
                        Some("soft") => Enforcement::Soft,
                        _ => Enforcement::Hard,
                    },
                });
            }

            if let Some(secs) = self.cooldown_secs {
                builder = builder.cooldown(Duration::from_secs(secs));
            }

            if let Some(rl) = self.rate_limit {
                use crate::tower::RateLimitConfig;
                builder = builder.rate_limit(RateLimitConfig {
                    rpm: rl.rpm,
                    tpm: rl.tpm,
                    window: Duration::from_secs(rl.window_seconds.unwrap_or(60)),
                });
            }

            if let Some(secs) = self.health_check_secs {
                builder = builder.health_check(Duration::from_secs(secs));
            }

            if let Some(ct) = self.cost_tracking {
                builder = builder.cost_tracking(ct);
            }

            if let Some(t) = self.tracing {
                builder = builder.tracing(t);
            }
        }

        if let Some(bedrock) = self.bedrock {
            if let Some(region) = bedrock.region {
                builder = builder.bedrock_region(region);
            }
            if let Some(prefix) = bedrock.cross_region_prefix {
                builder = builder.bedrock_cross_region_prefix(prefix);
            }
            if bedrock.access_key_id.is_some() || bedrock.secret_access_key.is_some() {
                builder = builder.bedrock_credentials(
                    bedrock.access_key_id.unwrap_or_default(),
                    bedrock.secret_access_key.unwrap_or_default(),
                    bedrock.session_token,
                );
            }
        }

        builder
    }

    /// Get the custom provider configurations from this config.
    pub fn providers(&self) -> &[LlmProviderConfig] {
        self.providers.as_deref().unwrap_or(&[])
    }
}

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

    fn minimal() -> LlmConfig {
        LlmConfig {
            model: "gpt-4o".to_owned(),
            ..Default::default()
        }
    }

    #[test]
    fn default_has_empty_model_and_no_optionals() {
        let config = LlmConfig::default();
        assert_eq!(config.model, "");
        assert!(config.api_key.is_none());
        assert!(config.base_url.is_none());
        assert!(config.bedrock.is_none());
        assert!(config.providers.is_none());
    }

    #[test]
    fn empty_optionals_are_omitted_from_json() {
        let config = minimal();
        let json = serde_json::to_string(&config).expect("serialize should succeed");
        assert_eq!(json, r#"{"model":"gpt-4o"}"#);
    }

    #[test]
    fn empty_optionals_are_omitted_from_toml() {
        let config = minimal();
        let toml = toml::to_string(&config).expect("serialize should succeed");
        assert_eq!(toml.trim(), r#"model = "gpt-4o""#);
    }

    #[test]
    fn json_round_trip_with_parity_fields() {
        let mut headers = HashMap::new();
        headers.insert("X-Custom".to_owned(), "value".to_owned());

        let config = LlmConfig {
            model: "gpt-4o".to_owned(),
            api_key: Some("sk-test".to_owned()),
            base_url: Some("https://api.example.com/v1".to_owned()),
            timeout_secs: Some(120),
            max_retries: Some(5),
            temperature: Some(0.7),
            max_tokens: Some(4096),
            load_env: Some(false),
            headers: Some(headers),
            ..Default::default()
        };

        let json = serde_json::to_string(&config).expect("serialize should succeed");
        let round_tripped: LlmConfig = serde_json::from_str(&json).expect("deserialize should succeed");
        assert_eq!(round_tripped, config);
    }

    #[test]
    fn toml_round_trip_with_bedrock_and_custom_provider() {
        let toml = r#"
model = "bedrock/anthropic.claude-3-sonnet-20240229-v1:0"
api_key = "unused-for-sigv4"

[bedrock]
region = "eu-central-1"
cross_region_prefix = "eu"

[[providers]]
name = "my-provider"
base_url = "https://my-llm.example.com/v1"
model_prefixes = ["my-provider/"]
"#;
        let config: LlmConfig = toml::from_str(toml).expect("TOML should parse");
        assert_eq!(config.model, "bedrock/anthropic.claude-3-sonnet-20240229-v1:0");
        assert_eq!(
            config.bedrock.as_ref().and_then(|b| b.region.as_deref()),
            Some("eu-central-1")
        );
        assert_eq!(
            config.bedrock.as_ref().and_then(|b| b.cross_region_prefix.as_deref()),
            Some("eu")
        );
        assert_eq!(config.providers().len(), 1);
        assert_eq!(config.providers()[0].name, "my-provider");

        let serialized = toml::to_string(&config).expect("serialize should succeed");
        let round_tripped: LlmConfig = toml::from_str(&serialized).expect("re-parse should succeed");
        assert_eq!(round_tripped, config);
    }

    #[test]
    fn into_client_builder_maps_core_fields() {
        let config = LlmConfig {
            model: "gpt-4o".to_owned(),
            api_key: Some("sk-test".to_owned()),
            timeout_secs: Some(30),
            max_retries: Some(2),
            ..Default::default()
        };
        let client_config = config.into_client_builder().build();
        assert_eq!(client_config.timeout, Duration::from_secs(30));
        assert_eq!(client_config.max_retries, 2);
    }

    #[test]
    fn into_client_builder_maps_bedrock_region() {
        let config = LlmConfig {
            model: "bedrock/anthropic.claude-3-sonnet-20240229-v1:0".to_owned(),
            bedrock: Some(BedrockConfig {
                region: Some("eu-central-1".to_owned()),
                ..Default::default()
            }),
            ..Default::default()
        };
        let client_config = config.into_client_builder().build();
        assert_eq!(client_config.bedrock_region.as_deref(), Some("eu-central-1"));
    }

    #[test]
    fn into_client_builder_maps_bedrock_credentials() {
        let config = LlmConfig {
            model: "bedrock/anthropic.claude-3-sonnet-20240229-v1:0".to_owned(),
            bedrock: Some(BedrockConfig {
                access_key_id: Some("AKIAEXAMPLE".to_owned()),
                secret_access_key: Some("secret".to_owned()),
                session_token: Some("token".to_owned()),
                ..Default::default()
            }),
            ..Default::default()
        };
        let client_config = config.into_client_builder().build();
        assert_eq!(client_config.bedrock_access_key_id.as_deref(), Some("AKIAEXAMPLE"));
        assert_eq!(client_config.bedrock_secret_access_key.as_deref(), Some("secret"));
        assert_eq!(client_config.bedrock_session_token.as_deref(), Some("token"));
    }
}