llm-universal 0.2.0

//! One client interface for OpenAI-compatible APIs and the Anthropic Messages API.
//!
//! The same code (`ChatRequest` -> `ChatResponse`) runs against any provider; switching
//! providers means switching the constructor:
//!
//! ```no_run
//! # use llm_universal::*;
//! # async fn demo() -> Result<()> {
//! let provider: Box<dyn LlmProvider> = Box::new(AnthropicProvider::new("sk-ant-..."));
//! // or: Box::new(OpenAiProvider::new("sk-...")),
//! // or: Box::new(OpenAiProvider::new("").with_base_url("http://localhost:11434/v1")),
//! let req = ChatRequest::new("claude-opus-5-5")
//!     .system("Be concise.")
//!     .max_tokens(512)
//!     .message(Message::user("Hello!"));
//! let resp = provider.chat(&req).await?;
//! println!("{}", resp.text());
//! # Ok(()) }
//! ```
//!
//! Errors follow the official SDKs: see [`LlmError`] and [`ApiError`].

#![forbid(unsafe_code)]
#![warn(missing_debug_implementations)]

mod anthropic;
mod cohere;
mod error;
mod gemini;
mod openai;
mod types;

pub use anthropic::AnthropicProvider;
pub use cohere::CohereProvider;
pub use error::{ApiError, ApiErrorKind, LlmError};
pub use gemini::GeminiProvider;
pub use openai::OpenAiProvider;
pub use types::*;

use async_trait::async_trait;
use serde_json::Value;

pub type Result<T> = std::result::Result<T, LlmError>;

/// Common contract implemented by every provider.
#[async_trait]
pub trait LlmProvider: Send + Sync {
    async fn chat(&self, request: &ChatRequest) -> Result<ChatResponse>;
}

fn invalid(message: String) -> LlmError {
    LlmError::InvalidArgument(message)
}

/// Largest successful response body that is read (32 MiB).
const MAX_RESPONSE_BYTES: usize = 32 * 1024 * 1024;
/// Largest error response body that is kept (64 KiB); the rest is dropped.
const MAX_ERROR_BYTES: usize = 64 * 1024;

/// Host part of `base_url`, or an error if it carries credentials or a query string.
fn checked_host<'a>(provider: &str, base_url: &'a str) -> Result<&'a str> {
    let rest = base_url
        .strip_prefix("https://")
        .or_else(|| base_url.strip_prefix("http://"))
        .ok_or_else(|| {
            invalid(format!(
                "{provider}: base_url must start with http:// or https://"
            ))
        })?;
    let authority = rest.split('/').next().unwrap_or_default();
    if authority.contains('@') || base_url.contains('?') || base_url.contains('#') {
        // Credentials in the URL would leak into logs and error chains.
        return Err(invalid(format!(
            "{provider}: base_url must not contain credentials, a query string or a fragment"
        )));
    }
    if authority.is_empty() {
        return Err(invalid(format!("{provider}: base_url has no host")));
    }
    Ok(authority)
}

fn is_loopback(authority: &str) -> bool {
    let host = if let Some(rest) = authority.strip_prefix('[') {
        rest.split(']').next().unwrap_or_default()
    } else {
        authority.split(':').next().unwrap_or_default()
    };
    host == "localhost" || host.ends_with(".localhost") || host == "::1" || host.starts_with("127.")
}

/// Validates the request and provider settings before any network call.
pub(crate) fn validate(
    provider: &'static str,
    api_key: &str,
    require_key: bool,
    base_url: &str,
    max_tool_name: usize,
    req: &ChatRequest,
) -> Result<()> {
    let authority = checked_host(provider, base_url)?;
    if base_url.starts_with("http://") && !api_key.is_empty() && !is_loopback(authority) {
        return Err(invalid(format!(
            "{provider}: refusing to send an API key over plain http:// to a non-local host; use https://"
        )));
    }
    if require_key && api_key.trim().is_empty() {
        return Err(invalid(format!("{provider}: api_key must not be empty")));
    }
    if req.model.trim().is_empty() {
        return Err(invalid("model must not be empty".to_string()));
    }
    if req.model.chars().any(char::is_control) {
        return Err(invalid(
            "model must not contain control characters".to_string(),
        ));
    }
    if req.messages.is_empty() {
        return Err(invalid("messages must not be empty".to_string()));
    }
    for (i, message) in req.messages.iter().enumerate() {
        let has_content = message.parts.iter().any(|p| match p {
            Part::Text { text } => !text.is_empty(),
            _ => true,
        });
        if !has_content {
            return Err(invalid(format!("messages[{i}] has no content")));
        }
    }
    if let Some(t) = req.temperature {
        if !(0.0..=2.0).contains(&t) {
            return Err(invalid(format!(
                "temperature must be between 0.0 and 2.0, got {t}"
            )));
        }
    }
    let mut names = std::collections::HashSet::new();
    for tool in &req.tools {
        let valid_name = !tool.name.is_empty()
            && tool.name.len() <= max_tool_name
            && tool
                .name
                .chars()
                .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-');
        if !valid_name {
            return Err(invalid(format!(
                "tool name `{}` must match ^[a-zA-Z0-9_-]{{1,{max_tool_name}}}$",
                tool.name
            )));
        }
        if !names.insert(tool.name.as_str()) {
            return Err(invalid(format!("duplicate tool name `{}`", tool.name)));
        }
        if tool.parameters["type"] != "object" {
            return Err(invalid(format!(
                "tool `{}`: parameters must be a JSON Schema with \"type\": \"object\"",
                tool.name
            )));
        }
    }
    Ok(())
}

/// Header value for a secret, marked sensitive so it is never printed by `Debug`.
pub(crate) fn secret_header(provider: &str, value: &str) -> Result<reqwest::header::HeaderValue> {
    let mut header = reqwest::header::HeaderValue::from_str(value).map_err(|_| {
        invalid(format!(
            "{provider}: api_key contains characters not allowed in an HTTP header"
        ))
    })?;
    header.set_sensitive(true);
    Ok(header)
}

/// Default HTTP client: timeouts, no redirects (so the key is never sent to another host),
/// and a bounded idle pool.
pub(crate) fn http_client() -> reqwest::Client {
    reqwest::Client::builder()
        .connect_timeout(std::time::Duration::from_secs(10))
        .timeout(std::time::Duration::from_secs(300))
        .redirect(reqwest::redirect::Policy::none())
        .pool_max_idle_per_host(8)
        .build()
        .unwrap_or_else(|_| reqwest::Client::new())
}

/// Reads at most `cap` bytes of the body. Past the cap it fails, or, with `truncate`,
/// keeps the first `cap` bytes and drops the rest.
async fn read_body(mut response: reqwest::Response, cap: usize, truncate: bool) -> Result<String> {
    let too_large = || LlmError::InvalidResponse(format!("response body exceeds {cap} bytes"));
    if !truncate && response.content_length().is_some_and(|n| n > cap as u64) {
        return Err(too_large());
    }
    let mut buf = Vec::new();
    while let Some(chunk) = response.chunk().await.map_err(LlmError::from_reqwest)? {
        if buf.len() + chunk.len() > cap {
            if !truncate {
                return Err(too_large());
            }
            buf.extend_from_slice(&chunk[..cap - buf.len()]);
            break;
        }
        buf.extend_from_slice(&chunk);
    }
    Ok(String::from_utf8_lossy(&buf).into_owned())
}

/// Sends the request, maps non-2xx responses to [`ApiError`] and parses the body as JSON.
pub(crate) async fn send_json(request: reqwest::RequestBuilder) -> Result<Value> {
    let response = request.send().await.map_err(LlmError::from_reqwest)?;
    let status = response.status().as_u16();
    let headers = response.headers();
    let request_id = headers
        .get("request-id")
        .or_else(|| headers.get("x-request-id"))
        .and_then(|v| v.to_str().ok())
        .map(str::to_string);

    if !(200..300).contains(&status) {
        let text = read_body(response, MAX_ERROR_BYTES, true).await?;
        return Err(LlmError::Api(Box::new(ApiError::from_response(
            status, request_id, &text,
        ))));
    }
    let text = read_body(response, MAX_RESPONSE_BYTES, false).await?;
    serde_json::from_str(&text).map_err(|source| LlmError::Deserialize {
        source,
        content: error::truncate(&text),
    })
}

/// Compiles the README examples as doctests.
#[cfg(doctest)]
#[doc = include_str!("../README.md")]
pub struct ReadmeDoctests;