add list fine tuning job checkpoints method

Author: michal.zyga

core/src/main/scala/sttp/openai/OpenAI.scala

@@ -576,6 +576,9 @@ class OpenAI(authToken: String, baseUri: Uri = OpenAIUris.OpenAIBaseUri) {
   /** Get status updates for a fine-tuning job.
     *
     * [[https://platform.openai.com/docs/api-reference/fine-tuning/list-events]]
+    *
+    * @param fineTuningJobId
+    *   The ID of the fine-tuning job to get checkpoints for.
     */
   def listFineTuningJobEvents(
       fineTuningJobId: String,
@@ -590,6 +593,26 @@ class OpenAI(authToken: String, baseUri: Uri = OpenAIUris.OpenAIBaseUri) {
       .response(asJson_parseErrors[ListFineTuningJobEventResponse])
   }
 
+  /** List checkpoints for a fine-tuning job.
+    *
+    * [[https://platform.openai.com/docs/api-reference/fine-tuning/list-checkpoints]]
+    *
+    * @param fineTuningJobId
+    *   The ID of the fine-tuning job to get checkpoints for.
+    */
+  def listFineTuningJobCheckpoints(
+      fineTuningJobId: String,
+      queryParameters: finetuning.QueryParameters = finetuning.QueryParameters.empty
+  ): Request[Either[OpenAIException, ListFineTuningJobCheckpointResponse]] = {
+    val uri = openAIUris
+      .fineTuningJobCheckpoints(fineTuningJobId)
+      .withParams(queryParameters.toMap)
+
+    openAIAuthRequest
+      .get(uri)
+      .response(asJson_parseErrors[ListFineTuningJobCheckpointResponse])
+  }
+
   /** Gets info about the fine-tune job.
     *
     * [[https://platform.openai.com/docs/api-reference/embeddings/create]]
@@ -1097,6 +1120,7 @@ private class OpenAIUris(val baseUri: Uri) {
 
   def fineTuningJob(fineTuningJobId: String): Uri = FineTuningJobs.addPath(fineTuningJobId)
   def fineTuningJobEvents(fineTuningJobId: String): Uri = fineTuningJob(fineTuningJobId).addPath("events")
+  def fineTuningJobCheckpoints(fineTuningJobId: String): Uri = fineTuningJob(fineTuningJobId).addPath("checkpoints")
 
   def file(fileId: String): Uri = Files.addPath(fileId)
   def fileContent(fileId: String): Uri = Files.addPath(fileId, "content")

core/src/main/scala/sttp/openai/OpenAISyncClient.scala

@@ -17,12 +17,7 @@ import sttp.openai.requests.embeddings.EmbeddingsRequestBody.EmbeddingsBody
 import sttp.openai.requests.embeddings.EmbeddingsResponseBody.EmbeddingResponse
 import sttp.openai.requests.files.FilesResponseData.{DeletedFileData, FileData, FilesResponse}
 import sttp.openai.requests.finetuning
-import sttp.openai.requests.finetuning.{
-  FineTuningJobRequestBody,
-  FineTuningJobResponse,
-  ListFineTuningJobEventResponse,
-  ListFineTuningJobResponse
-}
+import sttp.openai.requests.finetuning._
 import sttp.openai.requests.images.ImageResponseData.ImageResponse
 import sttp.openai.requests.images.creation.ImageCreationRequestBody.ImageCreationBody
 import sttp.openai.requests.images.edit.ImageEditsConfig
@@ -377,13 +372,29 @@ class OpenAISyncClient private (
   /** Get status updates for a fine-tuning job.
     *
     * [[https://platform.openai.com/docs/api-reference/fine-tuning/list-events]]
+    *
+    * @param fineTuningJobId
+    *   The ID of the fine-tuning job to get checkpoints for.
     */
   def listFineTuningJobEvents(
       fineTuningJobId: String,
       queryParameters: finetuning.QueryParameters = finetuning.QueryParameters.empty
   ): ListFineTuningJobEventResponse =
     sendOrThrow(openAI.listFineTuningJobEvents(fineTuningJobId, queryParameters))
 
+  /** List checkpoints for a fine-tuning job.
+    *
+    * [[https://platform.openai.com/docs/api-reference/fine-tuning/list-checkpoints]]
+    *
+    * @param fineTuningJobId
+    *   The ID of the fine-tuning job to get checkpoints for.
+    */
+  def listFineTuningJobCheckpoints(
+      fineTuningJobId: String,
+      queryParameters: finetuning.QueryParameters = finetuning.QueryParameters.empty
+  ): ListFineTuningJobCheckpointResponse =
+    sendOrThrow(openAI.listFineTuningJobCheckpoints(fineTuningJobId, queryParameters))
+
   /** Gets info about the fine-tune job.
     *
     * [[https://platform.openai.com/docs/api-reference/embeddings/create]]

core/src/main/scala/sttp/openai/requests/finetuning/FineTuningJobResponse.scala

@@ -4,7 +4,9 @@ import sttp.openai.OpenAIExceptions.OpenAIException.DeserializationOpenAIExcepti
 import sttp.openai.json.SnakePickle
 import ujson.Str
 
-/** @param id
+/** The fine_tuning.job object represents a fine-tuning job that has been created through the API.
+  *
+  * @param id
   *   The object identifier, which can be referenced in the API endpoints.
   * @param createdAt
   *   The Unix timestamp (in seconds) for when the fine-tuning job was created.
@@ -129,7 +131,9 @@ object ListFineTuningJobResponse {
   implicit val listFineTuningResponseR: SnakePickle.Reader[ListFineTuningJobResponse] = SnakePickle.macroR[ListFineTuningJobResponse]
 }
 
-/** @param `object`
+/** Fine-tuning job event object
+  *
+  * @param `object`
   *   The object type, which is always "fine_tuning.job.event".
   * @param id
   *   The object identifier.
@@ -168,3 +172,62 @@ object ListFineTuningJobEventResponse {
   implicit val listFineTuningJobEventResponseR: SnakePickle.Reader[ListFineTuningJobEventResponse] =
     SnakePickle.macroR[ListFineTuningJobEventResponse]
 }
+
+/** The fine_tuning.job.checkpoint object represents a model checkpoint for a fine-tuning job that is ready to use.
+  *
+  * @param id
+  *   The checkpoint identifier, which can be referenced in the API endpoints.
+  * @param createdAt
+  *   The Unix timestamp (in seconds) for when the checkpoint was created.
+  * @param fineTunedModelCheckpoint
+  *   The name of the fine-tuned checkpoint model that is created.
+  * @param stepNumber
+  *   The step number that the checkpoint was created at.
+  * @param metrics
+  *   Metrics at the step number during the fine-tuning job.
+  * @param fineTuningJobId
+  *   The name of the fine-tuning job that this checkpoint was created from.
+  * @param `object`
+  *   The object type, which is always "fine_tuning.job.checkpoint".
+  */
+case class FineTuningJobCheckpointResponse(
+    id: String,
+    createdAt: Int,
+    fineTunedModelCheckpoint: String,
+    stepNumber: Int,
+    metrics: Metrics,
+    fineTuningJobId: String,
+    `object`: String = "fine_tuning.job.checkpoint"
+)
+
+object FineTuningJobCheckpointResponse {
+  implicit val fineTuningJobCheckpointResponseR: SnakePickle.Reader[FineTuningJobCheckpointResponse] =
+    SnakePickle.macroR[FineTuningJobCheckpointResponse]
+}
+
+case class ListFineTuningJobCheckpointResponse(
+    `object`: String = "list",
+    data: Seq[FineTuningJobCheckpointResponse],
+    firstId: String,
+    lastId: String,
+    hasMore: Boolean
+)
+
+object ListFineTuningJobCheckpointResponse {
+  implicit val listFineTuningJobCheckpointResponseR: SnakePickle.Reader[ListFineTuningJobCheckpointResponse] =
+    SnakePickle.macroR[ListFineTuningJobCheckpointResponse]
+}
+
+case class Metrics(
+    step: Float,
+    trainLoss: Float,
+    trainMeanTokenAccuracy: Float,
+    validLoss: Float,
+    validMeanTokenAccuracy: Float,
+    fullValidLoss: Float,
+    fullValidMeanTokenAccuracy: Float
+)
+
+object Metrics {
+  implicit val metricsR: SnakePickle.Reader[Metrics] = SnakePickle.macroR[Metrics]
+}

core/src/test/scala/sttp/openai/fixtures/FineTuningJobFixture.scala

@@ -149,6 +149,32 @@ object FineTuningJobFixture {
                                                       |  "has_more": true
                                                       |}""".stripMargin
 
+  val jsonListFineTuningJobCheckpointsResponse: String = """{
+                                                      |  "object": "list",
+                                                      |  "data": [
+                                                      |    {
+                                                      |      "object": "fine_tuning.job.checkpoint",
+                                                      |      "id": "ftckpt_zc4Q7MP6XxulcVzj4MZdwsAB",
+                                                      |      "created_at": 1721764867,
+                                                      |      "fine_tuned_model_checkpoint": "ft:gpt-4o-mini-2024-07-18:my-org:custom-suffix:96olL566:ckpt-step-2000",
+                                                      |      "metrics": {
+                                                      |        "full_valid_loss": 0.134,
+                                                      |        "full_valid_mean_token_accuracy": 0.874,
+                                                      |        "step": 0.123,
+                                                      |        "train_loss": 0.346,
+                                                      |        "train_mean_token_accuracy": 0.736,
+                                                      |        "valid_loss": 0.654,
+                                                      |        "valid_mean_token_accuracy": 0.738
+                                                      |      },
+                                                      |      "fine_tuning_job_id": "ftjob-abc123",
+                                                      |      "step_number": 2000
+                                                      |    }
+                                                      |  ],
+                                                      |  "first_id": "ftckpt_zc4Q7MP6XxulcVzj4MZdwsAB",
+                                                      |  "last_id": "ftckpt_enQCFmOTGj3syEpYVhBRLTSy",
+                                                      |  "has_more": true
+                                                      |}""".stripMargin
+
   val fineTuningJobResponse: FineTuningJobResponse = FineTuningJobResponse(
     id = "ft-id",
     createdAt = 1000,

core/src/test/scala/sttp/openai/requests/finetuning/FineTuningDataSpec.scala

@@ -131,7 +131,39 @@ class FineTuningDataSpec extends AnyFlatSpec with Matchers with EitherValues {
     // when
     val deserializedJsonResponse: Either[Exception, ListFineTuningJobEventResponse] =
       SttpUpickleApiExtension.deserializeJsonSnake[ListFineTuningJobEventResponse].apply(jsonResponse)
+    // then
+    deserializedJsonResponse.value shouldBe expectedResponse
+  }
 
+  "Given list fine tuning job checkpoints response as Json" should "be properly deserialized to case class" in {
+    // given
+    val jsonResponse = FineTuningJobFixture.jsonListFineTuningJobCheckpointsResponse
+    val expectedResponse: ListFineTuningJobCheckpointResponse = ListFineTuningJobCheckpointResponse(
+      data = Seq(
+        FineTuningJobCheckpointResponse(
+          id = "ftckpt_zc4Q7MP6XxulcVzj4MZdwsAB",
+          createdAt = 1721764867,
+          fineTunedModelCheckpoint = "ft:gpt-4o-mini-2024-07-18:my-org:custom-suffix:96olL566:ckpt-step-2000",
+          metrics = Metrics(
+            fullValidLoss = 0.134f,
+            fullValidMeanTokenAccuracy = 0.874f,
+            step = 0.123f,
+            trainLoss = 0.346f,
+            trainMeanTokenAccuracy = 0.736f,
+            validLoss = 0.654f,
+            validMeanTokenAccuracy = 0.738f
+          ),
+          fineTuningJobId = "ftjob-abc123",
+          stepNumber = 2000
+        )
+      ),
+      firstId = "ftckpt_zc4Q7MP6XxulcVzj4MZdwsAB",
+      lastId = "ftckpt_enQCFmOTGj3syEpYVhBRLTSy",
+      hasMore = true
+    )
+    // when
+    val deserializedJsonResponse: Either[Exception, ListFineTuningJobCheckpointResponse] =
+      SttpUpickleApiExtension.deserializeJsonSnake[ListFineTuningJobCheckpointResponse].apply(jsonResponse)
     // then
     deserializedJsonResponse.value shouldBe expectedResponse
   }