openai-interface 0.14.0

//! The Fine-tuning API: manage fine-tuning jobs via `/fine_tuning`.
//!
//! > ![warn] This module is untested!
//! > If you encounter any issues, please report them on the repository.
//!
//! A fine-tuning job trains a model on a JSONL training file (and an
//! optional validation file) uploaded through the
//! [`files`](crate::files) API. See
//! [the OpenAI Fine-tuning guide](https://platform.openai.com/docs/guides/fine-tuning).
//!
//! Submodules: [`jobs`] (create / list / retrieve / cancel, plus the
//! events and checkpoints sub-resources) and [`models`] (restore a
//! fine-tuned model after a timeout).
//!
//! The `POST /fine_tuning/alpha/permissions` endpoints (GRPO reward
//! functions) are not implemented; they are reserved for the
//! enterprise-only alpha program.

pub mod jobs;
pub mod models;

/// The lifecycle status of a fine-tuning job.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum FineTuningJobStatus {
    /// The job is being validated and queued.
    ValidatingFiles,
    /// The job is waiting in the queue.
    Queued,
    /// The job is running.
    Running,
    /// The job finished successfully.
    Succeeded,
    /// The job failed.
    Failed,
    /// The job was cancelled by the user.
    Cancelled,
}

/// The per-step training/validation loss statistics of a fine-tuning
/// job.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct FineTuneMetrics {
    /// Training loss for this step.
    #[serde(default)]
    pub step: Option<u64>,
    /// Training loss.
    #[serde(default)]
    pub train_loss: Option<serde_json::Value>,
    /// Training mean token accuracy.
    #[serde(default)]
    pub train_mean_token_accuracy: Option<serde_json::Value>,
    /// Validation loss.
    #[serde(default)]
    pub valid_loss: Option<serde_json::Value>,
    /// Validation mean token accuracy.
    #[serde(default)]
    pub validation_mean_token_accuracy: Option<serde_json::Value>,
    /// Full validation loss.
    #[serde(default)]
    pub full_valid_loss: Option<serde_json::Value>,
    /// Full validation mean token accuracy.
    #[serde(default)]
    pub full_valid_mean_token_accuracy: Option<serde_json::Value>,
}

/// The hyperparameters of a fine-tuning job.
///
/// All fields are optional because the server may omit values when they
/// are set to `auto`.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct Hyperparameters {
    /// Number of epochs. A number, or `"auto"`.
    #[serde(default)]
    pub n_epochs: Option<serde_json::Value>,
    /// Batch size (in examples). A number, or `"auto"`.
    #[serde(default)]
    pub batch_size: Option<serde_json::Value>,
    /// Learning rate multiplier. A number, or `"auto"`.
    #[serde(default)]
    pub learning_rate_multiplier: Option<serde_json::Value>,
}

/// The result files of a completed fine-tuning job.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct FineTuningJob {
    /// The job ID, e.g. `ftjob_...`.
    pub id: String,
    /// The object type, always `fine_tuning.job`.
    #[serde(default)]
    pub object: Option<String>,
    /// Unix timestamp (seconds) of when the job was created.
    pub created_at: u64,
    /// Unix timestamp (seconds) of when the job finished.
    #[serde(default)]
    pub finished_at: Option<u64>,
    /// The base model that was fine-tuned.
    pub model: String,
    /// The name of the resulting fine-tuned model, once the job
    /// succeeds.
    #[serde(default)]
    pub fine_tuned_model: Option<String>,
    /// The organization that owns the job.
    #[serde(default)]
    pub organization_id: Option<String>,
    /// The current lifecycle status.
    pub status: FineTuningJobStatus,
    /// The ID of the uploaded JSONL training file.
    pub training_file: String,
    /// The ID of the uploaded JSONL validation file, if provided.
    #[serde(default)]
    pub validation_file: Option<String>,
    /// The hyperparameters used for the job.
    #[serde(default)]
    pub hyperparameters: Option<Hyperparameters>,
    /// The seed used for the job.
    #[serde(default)]
    pub seed: Option<u64>,
    /// The suffix appended to the fine-tuned model name.
    #[serde(default)]
    pub suffix: Option<String>,
    /// The integrations configured for the job.
    #[serde(default)]
    pub integrations: Option<serde_json::Value>,
    /// The accumulated metrics and checkpoints of the job.
    #[serde(default)]
    pub result_files: Vec<String>,
    /// The computed metrics of the job, if available.
    #[serde(default)]
    pub metrics: Option<FineTuneMetrics>,
    /// The user that created the job.
    #[serde(default)]
    pub user_provided_suffix: Option<bool>,
    /// The error of a failed job.
    #[serde(default)]
    pub error: Option<crate::errors::ApiError>,
    /// Arbitrary key-value metadata attached to the job.
    #[serde(default)]
    pub metadata: Option<std::collections::HashMap<String, String>>,
    /// The method used for fine-tuning (supervised, DPO, or
    /// reinforcement learning), as raw JSON.
    #[serde(default)]
    pub method: Option<serde_json::Value>,
    /// Estimated number of billable tokens.
    #[serde(default)]
    pub estimated_finish: Option<u64>,
    /// Token counts of the job, when reported.
    #[serde(default)]
    pub trained_tokens: Option<u64>,
    /// Unix timestamp (seconds) of when the job is estimated to finish.
    #[serde(rename = "estimated_finish_minutes")]
    #[serde(default)]
    pub estimated_finish_minutes: Option<u64>,
}

crate::impl_from_str!(FineTuningJob);