linger-openai-sdk 0.1.1

use crate::error::LingerError;
use crate::RequestId;
use serde::{Deserialize, Serialize};
use serde_json::Value;
use std::collections::BTreeMap;

/// EN: Request body for `POST /v1/evals`.
/// 中文：`POST /v1/evals` 的请求体。
#[derive(Clone, Debug, Serialize, PartialEq)]
#[non_exhaustive]
pub struct CreateEvalRequest {
    /// EN: Data source configuration used by the eval.
    /// 中文：eval 使用的数据源配置。
    pub data_source_config: Value,
    /// EN: Testing criteria that score eval runs.
    /// 中文：用于给 eval run 评分的测试准则。
    pub testing_criteria: Vec<Value>,
    /// EN: Optional eval name.
    /// 中文：可选的 eval 名称。
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// EN: Optional metadata.
    /// 中文：可选元数据。
    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
    pub metadata: BTreeMap<String, String>,
    /// EN: Forward-compatible optional fields not yet covered by handwritten types.
    /// 中文：手写类型尚未覆盖的前向兼容可选字段。
    #[serde(flatten)]
    pub extra: BTreeMap<String, Value>,
}

impl CreateEvalRequest {
    /// EN: Starts building an eval creation request.
    /// 中文：开始构建 eval 创建请求。
    pub fn builder() -> CreateEvalRequestBuilder {
        CreateEvalRequestBuilder::default()
    }
}

/// EN: Builder for eval creation requests.
/// 中文：eval 创建请求的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct CreateEvalRequestBuilder {
    data_source_config: Option<Value>,
    testing_criteria: Vec<Value>,
    name: Option<String>,
    metadata: BTreeMap<String, String>,
    extra: BTreeMap<String, Value>,
}

impl CreateEvalRequestBuilder {
    /// EN: Sets the eval data source configuration.
    /// 中文：设置 eval 数据源配置。
    pub fn data_source_config(mut self, data_source_config: Value) -> Self {
        self.data_source_config = Some(data_source_config);
        self
    }

    /// EN: Adds one eval testing criterion.
    /// 中文：添加一个 eval 测试准则。
    pub fn testing_criterion(mut self, testing_criterion: Value) -> Self {
        self.testing_criteria.push(testing_criterion);
        self
    }

    /// EN: Replaces all eval testing criteria.
    /// 中文：替换全部 eval 测试准则。
    pub fn testing_criteria(mut self, testing_criteria: impl IntoIterator<Item = Value>) -> Self {
        self.testing_criteria = testing_criteria.into_iter().collect();
        self
    }

    /// EN: Sets the optional eval name.
    /// 中文：设置可选的 eval 名称。
    pub fn name(mut self, name: impl Into<String>) -> Self {
        self.name = Some(name.into());
        self
    }

    /// EN: Adds a metadata key/value pair.
    /// 中文：添加一个元数据键值对。
    pub fn metadata(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.metadata.insert(key.into(), value.into());
        self
    }

    /// EN: Adds a forward-compatible JSON field.
    /// 中文：添加一个前向兼容 JSON 字段。
    pub fn extra(mut self, name: impl Into<String>, value: Value) -> Self {
        self.extra.insert(name.into(), value);
        self
    }

    /// EN: Builds and validates the request.
    /// 中文：构建并校验请求。
    pub fn build(self) -> Result<CreateEvalRequest, LingerError> {
        validate_optional_string("name", self.name.as_deref())?;
        validate_metadata(&self.metadata)?;
        validate_json_value("data_source_config", self.data_source_config.as_ref(), true)?;
        validate_json_values("testing_criteria", &self.testing_criteria, true)?;
        validate_extra_fields(&self.extra)?;
        Ok(CreateEvalRequest {
            data_source_config: self
                .data_source_config
                .expect("validated data_source_config"),
            testing_criteria: self.testing_criteria,
            name: self.name,
            metadata: self.metadata,
            extra: self.extra,
        })
    }
}

/// EN: Request body for `POST /v1/evals/{eval_id}`.
/// 中文：`POST /v1/evals/{eval_id}` 的请求体。
#[derive(Clone, Debug, Default, Serialize, PartialEq, Eq)]
#[non_exhaustive]
pub struct ModifyEvalRequest {
    /// EN: Updated eval name.
    /// 中文：更新后的 eval 名称。
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// EN: Updated metadata.
    /// 中文：更新后的元数据。
    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
    pub metadata: BTreeMap<String, String>,
}

impl ModifyEvalRequest {
    /// EN: Starts building an eval modification request.
    /// 中文：开始构建 eval 修改请求。
    pub fn builder() -> ModifyEvalRequestBuilder {
        ModifyEvalRequestBuilder::default()
    }
}

/// EN: Builder for eval modification requests.
/// 中文：eval 修改请求的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct ModifyEvalRequestBuilder {
    name: Option<String>,
    metadata: BTreeMap<String, String>,
}

impl ModifyEvalRequestBuilder {
    /// EN: Sets the updated eval name.
    /// 中文：设置更新后的 eval 名称。
    pub fn name(mut self, name: impl Into<String>) -> Self {
        self.name = Some(name.into());
        self
    }

    /// EN: Adds an updated metadata key/value pair.
    /// 中文：添加一个更新后的元数据键值对。
    pub fn metadata(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.metadata.insert(key.into(), value.into());
        self
    }

    /// EN: Builds and validates the request.
    /// 中文：构建并校验请求。
    pub fn build(self) -> Result<ModifyEvalRequest, LingerError> {
        validate_optional_string("name", self.name.as_deref())?;
        validate_metadata(&self.metadata)?;
        Ok(ModifyEvalRequest {
            name: self.name,
            metadata: self.metadata,
        })
    }
}

/// EN: Request body for `POST /v1/evals/{eval_id}/runs`.
/// 中文：`POST /v1/evals/{eval_id}/runs` 的请求体。
#[derive(Clone, Debug, Serialize, PartialEq)]
#[non_exhaustive]
pub struct CreateEvalRunRequest {
    /// EN: Details about the run data source.
    /// 中文：run 数据源的详细信息。
    pub data_source: Value,
    /// EN: Optional run name.
    /// 中文：可选的 run 名称。
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// EN: Optional metadata.
    /// 中文：可选元数据。
    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
    pub metadata: BTreeMap<String, String>,
    /// EN: Forward-compatible optional fields not yet covered by handwritten types.
    /// 中文：手写类型尚未覆盖的前向兼容可选字段。
    #[serde(flatten)]
    pub extra: BTreeMap<String, Value>,
}

impl CreateEvalRunRequest {
    /// EN: Starts building an eval run creation request.
    /// 中文：开始构建 eval run 创建请求。
    pub fn builder() -> CreateEvalRunRequestBuilder {
        CreateEvalRunRequestBuilder::default()
    }
}

/// EN: Builder for eval run creation requests.
/// 中文：eval run 创建请求的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct CreateEvalRunRequestBuilder {
    data_source: Option<Value>,
    name: Option<String>,
    metadata: BTreeMap<String, String>,
    extra: BTreeMap<String, Value>,
}

impl CreateEvalRunRequestBuilder {
    /// EN: Sets the run data source.
    /// 中文：设置 run 数据源。
    pub fn data_source(mut self, data_source: Value) -> Self {
        self.data_source = Some(data_source);
        self
    }

    /// EN: Sets the optional run name.
    /// 中文：设置可选的 run 名称。
    pub fn name(mut self, name: impl Into<String>) -> Self {
        self.name = Some(name.into());
        self
    }

    /// EN: Adds a metadata key/value pair.
    /// 中文：添加一个元数据键值对。
    pub fn metadata(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.metadata.insert(key.into(), value.into());
        self
    }

    /// EN: Adds a forward-compatible JSON field.
    /// 中文：添加一个前向兼容 JSON 字段。
    pub fn extra(mut self, name: impl Into<String>, value: Value) -> Self {
        self.extra.insert(name.into(), value);
        self
    }

    /// EN: Builds and validates the request.
    /// 中文：构建并校验请求。
    pub fn build(self) -> Result<CreateEvalRunRequest, LingerError> {
        validate_optional_string("name", self.name.as_deref())?;
        validate_metadata(&self.metadata)?;
        validate_json_value("data_source", self.data_source.as_ref(), true)?;
        validate_extra_fields(&self.extra)?;
        Ok(CreateEvalRunRequest {
            data_source: self.data_source.expect("validated data_source"),
            name: self.name,
            metadata: self.metadata,
            extra: self.extra,
        })
    }
}

/// EN: Eval object returned by the Evals API.
/// 中文：Evals API 返回的 eval 对象。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
#[non_exhaustive]
pub struct Eval {
    /// EN: Eval id.
    /// 中文：eval ID。
    pub id: String,
    /// EN: API object type.
    /// 中文：API 对象类型。
    pub object: String,
    /// EN: Unix timestamp for creation.
    /// 中文：创建时间的 Unix 时间戳。
    pub created_at: u64,
    /// EN: Eval name.
    /// 中文：eval 名称。
    #[serde(default)]
    pub name: String,
    /// EN: Metadata attached to the eval.
    /// 中文：附加到 eval 的元数据。
    #[serde(default)]
    pub metadata: BTreeMap<String, String>,
    /// EN: Data source configuration returned by the API.
    /// 中文：API 返回的数据源配置。
    #[serde(default)]
    pub data_source_config: Value,
    /// EN: Testing criteria returned by the API.
    /// 中文：API 返回的测试准则。
    #[serde(default)]
    pub testing_criteria: Vec<Value>,
    /// EN: Additional fields preserved for forward compatibility.
    /// 中文：为前向兼容保留的额外字段。
    #[serde(flatten)]
    pub extra: BTreeMap<String, Value>,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

impl Eval {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

/// EN: Eval run object returned by the Evals API.
/// 中文：Evals API 返回的 eval run 对象。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
#[non_exhaustive]
pub struct EvalRun {
    /// EN: Eval run id.
    /// 中文：eval run ID。
    pub id: String,
    /// EN: API object type.
    /// 中文：API 对象类型。
    pub object: String,
    /// EN: Unix timestamp for creation.
    /// 中文：创建时间的 Unix 时间戳。
    pub created_at: u64,
    /// EN: Parent eval id.
    /// 中文：父级 eval ID。
    pub eval_id: String,
    /// EN: Eval run status.
    /// 中文：eval run 状态。
    pub status: String,
    /// EN: Eval run name.
    /// 中文：eval run 名称。
    #[serde(default)]
    pub name: Option<String>,
    /// EN: Model evaluated by the run, when applicable.
    /// 中文：run 评估的模型，如适用。
    #[serde(default)]
    pub model: Option<String>,
    /// EN: Metadata attached to the run.
    /// 中文：附加到 run 的元数据。
    #[serde(default)]
    pub metadata: BTreeMap<String, String>,
    /// EN: Run data source returned by the API.
    /// 中文：API 返回的 run 数据源。
    #[serde(default)]
    pub data_source: Value,
    /// EN: Run error information, when returned.
    /// 中文：响应中存在时的 run 错误信息。
    #[serde(default)]
    pub error: Option<Value>,
    /// EN: Usage per model, when returned.
    /// 中文：响应中存在时的逐模型用量。
    #[serde(default)]
    pub per_model_usage: Vec<Value>,
    /// EN: Results per testing criterion, when returned.
    /// 中文：响应中存在时的逐测试准则结果。
    #[serde(default)]
    pub per_testing_criteria_results: Vec<Value>,
    /// EN: Dashboard report URL, when returned.
    /// 中文：响应中存在时的控制台报告 URL。
    #[serde(default)]
    pub report_url: Option<String>,
    /// EN: Aggregate result counters, when returned.
    /// 中文：响应中存在时的汇总结果计数。
    #[serde(default)]
    pub result_counts: Value,
    /// EN: Additional fields preserved for forward compatibility.
    /// 中文：为前向兼容保留的额外字段。
    #[serde(flatten)]
    pub extra: BTreeMap<String, Value>,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

impl EvalRun {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

/// EN: Paginated eval run list returned by the Evals API.
/// 中文：Evals API 返回的分页 eval run 列表。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
#[non_exhaustive]
pub struct EvalRunPage {
    /// EN: API list object type.
    /// 中文：API 列表对象类型。
    pub object: String,
    /// EN: Runs on this page.
    /// 中文：本页 run。
    #[serde(default)]
    pub data: Vec<EvalRun>,
    /// EN: First run id on this page.
    /// 中文：本页第一个 run ID。
    #[serde(default)]
    pub first_id: Option<String>,
    /// EN: Last run id on this page.
    /// 中文：本页最后一个 run ID。
    #[serde(default)]
    pub last_id: Option<String>,
    /// EN: Whether more runs are available.
    /// 中文：是否还有更多 run。
    pub has_more: bool,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

impl EvalRunPage {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

/// EN: Deletion result returned by the Eval Runs API.
/// 中文：Eval Runs API 返回的删除结果。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
#[non_exhaustive]
pub struct EvalRunDeletion {
    /// EN: Deleted eval run id.
    /// 中文：已删除的 eval run ID。
    pub run_id: String,
    /// EN: API object type.
    /// 中文：API 对象类型。
    pub object: String,
    /// EN: Whether the run was deleted.
    /// 中文：run 是否已删除。
    pub deleted: bool,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

impl EvalRunDeletion {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

/// EN: Eval run output item returned by the Evals API.
/// 中文：Evals API 返回的 eval run output item。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
#[non_exhaustive]
pub struct EvalRunOutputItem {
    /// EN: Output item id.
    /// 中文：output item ID。
    pub id: String,
    /// EN: API object type.
    /// 中文：API 对象类型。
    pub object: String,
    /// EN: Unix timestamp for creation.
    /// 中文：创建时间的 Unix 时间戳。
    pub created_at: u64,
    /// EN: Parent eval id.
    /// 中文：父级 eval ID。
    pub eval_id: String,
    /// EN: Parent eval run id.
    /// 中文：父级 eval run ID。
    pub run_id: String,
    /// EN: Output item status.
    /// 中文：output item 状态。
    pub status: String,
    /// EN: Identifier for the source data item.
    /// 中文：源数据项的标识符。
    pub datasource_item_id: u64,
    /// EN: Source data item details.
    /// 中文：源数据项详情。
    #[serde(default)]
    pub datasource_item: Value,
    /// EN: Grader results for this output item.
    /// 中文：此 output item 的评分器结果。
    #[serde(default)]
    pub results: Vec<Value>,
    /// EN: Input and output sample details.
    /// 中文：输入和输出样本详情。
    #[serde(default)]
    pub sample: Value,
    /// EN: Additional fields preserved for forward compatibility.
    /// 中文：为前向兼容保留的额外字段。
    #[serde(flatten)]
    pub extra: BTreeMap<String, Value>,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

impl EvalRunOutputItem {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

/// EN: Paginated eval run output item list returned by the Evals API.
/// 中文：Evals API 返回的分页 eval run output item 列表。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
#[non_exhaustive]
pub struct EvalRunOutputItemPage {
    /// EN: API list object type.
    /// 中文：API 列表对象类型。
    pub object: String,
    /// EN: Output items on this page.
    /// 中文：本页 output item。
    #[serde(default)]
    pub data: Vec<EvalRunOutputItem>,
    /// EN: First output item id on this page.
    /// 中文：本页第一个 output item ID。
    #[serde(default)]
    pub first_id: Option<String>,
    /// EN: Last output item id on this page.
    /// 中文：本页最后一个 output item ID。
    #[serde(default)]
    pub last_id: Option<String>,
    /// EN: Whether more output items are available.
    /// 中文：是否还有更多 output item。
    pub has_more: bool,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

impl EvalRunOutputItemPage {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

/// EN: Paginated eval list returned by the Evals API.
/// 中文：Evals API 返回的分页 eval 列表。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
#[non_exhaustive]
pub struct EvalPage {
    /// EN: API list object type.
    /// 中文：API 列表对象类型。
    pub object: String,
    /// EN: Evals on this page.
    /// 中文：本页 eval。
    #[serde(default)]
    pub data: Vec<Eval>,
    /// EN: First eval id on this page.
    /// 中文：本页第一个 eval ID。
    #[serde(default)]
    pub first_id: Option<String>,
    /// EN: Last eval id on this page.
    /// 中文：本页最后一个 eval ID。
    #[serde(default)]
    pub last_id: Option<String>,
    /// EN: Whether more evals are available.
    /// 中文：是否还有更多 eval。
    pub has_more: bool,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

impl EvalPage {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

/// EN: Deletion result returned by the Evals API.
/// 中文：Evals API 返回的删除结果。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
#[non_exhaustive]
pub struct EvalDeletion {
    /// EN: Deleted eval id.
    /// 中文：已删除的 eval ID。
    pub eval_id: String,
    /// EN: API object type.
    /// 中文：API 对象类型。
    pub object: String,
    /// EN: Whether the eval was deleted.
    /// 中文：eval 是否已删除。
    pub deleted: bool,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

impl EvalDeletion {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

fn validate_json_value(
    name: &str,
    value: Option<&Value>,
    require_present: bool,
) -> Result<(), LingerError> {
    match value {
        Some(value) if value.is_null() => Err(LingerError::invalid_config(format!(
            "{name} must not be null"
        ))),
        Some(_) => Ok(()),
        None if require_present => Err(LingerError::invalid_config(format!("{name} is required"))),
        None => Ok(()),
    }
}

fn validate_json_values(
    name: &str,
    values: &[Value],
    require_non_empty: bool,
) -> Result<(), LingerError> {
    if require_non_empty && values.is_empty() {
        return Err(LingerError::invalid_config(format!("{name} is required")));
    }
    if values.iter().any(Value::is_null) {
        return Err(LingerError::invalid_config(format!(
            "{name} must not contain null values"
        )));
    }
    Ok(())
}

fn validate_metadata(metadata: &BTreeMap<String, String>) -> Result<(), LingerError> {
    for key in metadata.keys() {
        if key.trim().is_empty() {
            return Err(LingerError::invalid_config(
                "metadata keys must not be empty",
            ));
        }
    }
    Ok(())
}

fn validate_optional_string(name: &str, value: Option<&str>) -> Result<(), LingerError> {
    if value.is_some_and(|value| value.trim().is_empty()) {
        return Err(LingerError::invalid_config(format!(
            "{name} must not be empty"
        )));
    }
    Ok(())
}

fn validate_extra_fields(extra: &BTreeMap<String, Value>) -> Result<(), LingerError> {
    for (key, value) in extra {
        if key.trim().is_empty() {
            return Err(LingerError::invalid_config(
                "extra field names must not be empty",
            ));
        }
        if value.is_null() {
            return Err(LingerError::invalid_config(format!(
                "extra field {key} must not be null"
            )));
        }
    }
    Ok(())
}