openai-interface 0.10.0

//! List the checkpoints of a fine-tuning job via
//! `GET /fine_tuning/jobs/{job_id}/checkpoints`.
//!
//! > ![warn] This module is untested!
//! > If you encounter any issues, please report them on the repository.
//!
//! Checkpoints are only created for jobs with `integrations` or when the
//! official service decides to snapshot the run; the list may be empty.

use url::Url;

use crate::{
    errors::OapiError,
    fine_tuning::FineTuneMetrics,
    rest::get::{Get, GetNoStream},
};

/// Lists the checkpoints of a fine-tuning job.
#[derive(Debug, Clone, Default)]
pub struct ListFineTuningCheckpointsRequest<'a> {
    /// The ID of the job whose checkpoints to list, e.g. `ftjob_...`.
    pub job_id: &'a str,
    /// A cursor for pagination: return checkpoints created *after*
    /// this checkpoint ID.
    pub after: Option<&'a str>,
    /// A limit on the number of checkpoints to be returned (1-100,
    /// default 20).
    pub limit: Option<u32>,
    /// Additional query parameters appended verbatim to the URL.
    pub extra_query: Option<std::collections::HashMap<String, String>>,
}

impl Get for ListFineTuningCheckpointsRequest<'_> {
    /// Builds the URL for the request.
    ///
    /// `base_url` should be like <https://api.openai.com/v1>
    fn build_url(&self, base_url: &str) -> Result<String, OapiError> {
        let mut url = Url::parse(base_url.trim_end_matches('/')).map_err(OapiError::UrlError)?;
        url.path_segments_mut()
            .map_err(|_| OapiError::UrlCannotBeBase(base_url.to_string()))?
            .push("fine_tuning")
            .push("jobs")
            .push(self.job_id)
            .push("checkpoints");

        let mut touched = false;
        {
            let mut pairs = url.query_pairs_mut();
            if let Some(after) = self.after {
                pairs.append_pair("after", after);
                touched = true;
            }
            if let Some(limit) = self.limit {
                pairs.append_pair("limit", &limit.to_string());
                touched = true;
            }
            if let Some(extra_query) = &self.extra_query {
                for (key, value) in extra_query {
                    pairs.append_pair(key, value);
                }
                touched = true;
            }
        }
        if !touched {
            url.set_query(None);
        }

        Ok(url.to_string())
    }
}

impl GetNoStream for ListFineTuningCheckpointsRequest<'_> {
    type Response = ListFineTuningCheckpointsResponse;
}

/// A checkpoint of a fine-tuning job.
#[derive(Debug, Clone, serde::Deserialize)]
pub struct FineTuningCheckpoint {
    /// The checkpoint ID, e.g. `ftckpt_...`.
    pub id: String,
    /// The object type, always `fine_tuning.job.checkpoint`.
    #[serde(default)]
    pub object: Option<String>,
    /// Unix timestamp (seconds) of when the checkpoint was created.
    pub created_at: u64,
    /// The name of the fine-tuned model at this checkpoint.
    pub fine_tuned_model_checkpoint: String,
    /// The step number the checkpoint was taken at.
    pub step_number: u64,
    /// The metrics at this checkpoint.
    #[serde(default)]
    pub metrics: Option<FineTuneMetrics>,
    /// The ID of the job the checkpoint belongs to.
    pub fine_tuning_job_id: String,
}

/// The response of listing a job's checkpoints.
#[derive(Debug, Clone, serde::Deserialize)]
pub struct ListFineTuningCheckpointsResponse {
    /// The checkpoints on this page.
    #[serde(default)]
    pub data: Vec<FineTuningCheckpoint>,
    /// Whether more checkpoints exist after this page.
    #[serde(default)]
    pub has_more: Option<bool>,
    /// The ID of the first checkpoint on the page, for cursor
    /// pagination.
    #[serde(default)]
    pub first_id: Option<String>,
    /// The ID of the last checkpoint on the page, for cursor
    /// pagination.
    #[serde(default)]
    pub last_id: Option<String>,
    /// The object type (`list`), if the provider sends it.
    #[serde(default)]
    pub object: Option<String>,
}

crate::impl_from_str!(ListFineTuningCheckpointsResponse);