use std::time::Duration;

/// LLM 调用过程中可能发生的所有错误。
///
/// 错误按可重试性分为两类：
/// - **可重试**：`RateLimit`、`Timeout`、状态码 >= 500
/// - **不可重试**：`Authentication`、`ContextLength`、状态码 4xx（除 429）
///
/// 错误消息面向最终用户（中文），并尽量附带可操作的修复建议（如检查 API key、减少上下文）。
#[derive(thiserror::Error, Debug)]
#[non_exhaustive]
pub enum LlmError {
    /// API 认证失败（API key 无效、过期或权限不足）。
    #[error(
        "LLM 认证失败: {0}。请检查环境变量中的 API key（如 OPENAI_API_KEY / ANTHROPIC_API_KEY）是否正确"
    )]
    Authentication(String),

    /// 请求被限流，可选地附带重试等待时间。可重试。
    #[error("LLM 限流（服务方），建议等待 {retry_after:?} 后重试")]
    RateLimit { retry_after: Option<Duration> },

    /// HTTP 请求失败（网络错误或非 2xx 状态码），包含状态码与响应体。
    #[error(
        "LLM 请求失败（HTTP {status}）: {body}。请检查 Provider 端点地址（base_url）和网络连通性"
    )]
    Request { status: u16, body: String },

    /// 请求超时。可重试。
    #[error("LLM 请求超时（{duration:?}）。请检查网络连接，或调大 LlmCycle 超时配置")]
    Timeout { duration: Duration },

    /// 流式响应处理错误（SSE 解析失败、流中断等）。可重试。
    #[error("LLM 流式响应错误: {0}。可重试或改用非流式接口")]
    Stream(String),

    /// 上下文长度超出模型窗口限制。
    #[error(
        "LLM 上下文超限：当前 {actual} tokens > 模型上限 {limit} tokens。请减少消息历史、缩短 prompt，或启用 auto-compaction（llm::compact）"
    )]
    ContextLength { actual: u32, limit: u32 },

    /// 其他未分类的 LLM 调用失败。
    #[error("LLM 调用失败: {0}")]
    Other(String),
}