Added Responses API support + small fix for optional parameters (#378)

Author: pielas

README.md

@@ -463,8 +463,9 @@ object Main extends App {
   val responseFormat: ResponseFormat.JsonSchema =
     ResponseFormat.JsonSchema(
       name = "mathReasoning",
-      strict = true,
-      schema = jsonSchema
+      strict = Some(true),
+      schema = Some(jsonSchema),
+      description = None
     )
 
   val bodyMessages: Seq[Message] = Seq(

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

@@ -35,6 +35,7 @@ import sttp.openai.requests.images.variations.ImageVariationsConfig
 import sttp.openai.requests.models.ModelsResponseData.{DeletedModelData, ModelData, ModelsResponse}
 import sttp.openai.requests.moderations.ModerationsRequestBody.ModerationsBody
 import sttp.openai.requests.moderations.ModerationsResponseData.ModerationData
+import sttp.openai.requests.responses._
 import sttp.openai.requests.threads.QueryParameters
 import sttp.openai.requests.threads.ThreadsRequestBody.CreateThreadBody
 import sttp.openai.requests.threads.ThreadsResponseData.{DeleteThreadResponse, ThreadData}
@@ -405,6 +406,105 @@ class OpenAI(authToken: String, baseUri: Uri = OpenAIUris.OpenAIBaseUri) {
       .delete(openAIUris.chatCompletion(completionId))
       .response(asJson_parseErrors[DeleteChatCompletionResponse])
 
+  /** Creates a model response.
+    *
+    * Provide text or image inputs to generate text or JSON outputs. Have the model call your own custom code or use built-in tools like web
+    * search or file search to use your own data as input for the model's response.
+    *
+    * [[https://platform.openai.com/docs/api-reference/responses/create]]
+    *
+    * @param requestBody
+    *   Model response request body.
+    *
+    * @return
+    *   Returns a Response object.
+    */
+  def createModelResponse(requestBody: ResponsesRequestBody): Request[Either[OpenAIException, ResponsesResponseBody]] =
+    openAIAuthRequest
+      .post(openAIUris.Responses)
+      .body(asJson(requestBody))
+      .response(asJson_parseErrors[ResponsesResponseBody])
+
+  /** Retrieves a model response with the given ID.
+    *
+    * [[https://platform.openai.com/docs/api-reference/responses/get]]
+    *
+    * @param responseId
+    *   The ID of the response to retrieve.
+    *
+    * @return
+    *   The Response object matching the specified ID.
+    */
+  def getModelResponse(
+      responseId: String,
+      queryParameters: GetResponseQueryParameters
+  ): Request[Either[OpenAIException, ResponsesResponseBody]] = {
+    val uri = openAIUris
+      .response(responseId)
+      .withParams(queryParameters.toMap)
+
+    openAIAuthRequest
+      .get(uri)
+      .response(asJson_parseErrors[ResponsesResponseBody])
+  }
+
+  /** Deletes a model response with the given ID.
+    *
+    * [[https://platform.openai.com/docs/api-reference/responses/delete]]
+    *
+    * @param responseId
+    *   The ID of the chat completion to delete.
+    *
+    * @return
+    *   A deletion confirmation object.
+    */
+  def deleteModelResponse(responseId: String): Request[Either[OpenAIException, DeleteModelResponseResponse]] =
+    openAIAuthRequest
+      .delete(openAIUris.response(responseId))
+      .response(asJson_parseErrors[DeleteModelResponseResponse])
+
+  /** Cancels a model response with the given ID.
+    *
+    * Only responses created with the background parameter set to true can be cancelled
+    *
+    * [[https://platform.openai.com/docs/api-reference/responses/cancel]]
+    *
+    * @param responseId
+    *   The ID of the Upload.
+    *
+    * @return
+    *   The Upload object with status cancelled.
+    */
+  def cancelResponse(responseId: String): Request[Either[OpenAIException, ResponsesResponseBody]] =
+    openAIAuthRequest
+      .post(openAIUris.cancelResponse(responseId))
+      .response(asJson_parseErrors[ResponsesResponseBody])
+
+  /** Returns a list of input items for a given response.
+    *
+    * [[https://platform.openai.com/docs/api-reference/responses/input-items]]
+    *
+    * @param responseId
+    *   The ID of the response to retrieve input items for.
+    * @param queryParameters
+    *   Query parameters for pagination and filtering.
+    *
+    * @return
+    *   A list of input items for the response.
+    */
+  def listResponsesInputItems(
+      responseId: String,
+      queryParameters: ListInputItemsQueryParameters = ListInputItemsQueryParameters.empty
+  ): Request[Either[OpenAIException, InputItemsListResponseBody]] = {
+    val uri = openAIUris
+      .responseInputItems(responseId)
+      .withParams(queryParameters.toMap)
+
+    openAIAuthRequest
+      .get(uri)
+      .response(asJson_parseErrors[InputItemsListResponseBody])
+  }
+
   /** Returns a list of files that belong to the user's organization.
     *
     * [[https://platform.openai.com/docs/api-reference/files]]
@@ -1533,6 +1633,7 @@ private class OpenAIUris(val baseUri: Uri) {
   val Translations: Uri = audioBase.addPath("translations")
   val Speech: Uri = audioBase.addPath("speech")
   val VariationsImage: Uri = imageBase.addPath("variations")
+  val Responses: Uri = uri"$baseUri/responses"
 
   val Assistants: Uri = uri"$baseUri/assistants"
   val Threads: Uri = uri"$baseUri/threads"
@@ -1563,6 +1664,10 @@ private class OpenAIUris(val baseUri: Uri) {
 
   def assistant(assistantId: String): Uri = Assistants.addPath(assistantId)
 
+  def response(responseId: String): Uri = Responses.addPath(responseId)
+  def cancelResponse(responseId: String): Uri = response(responseId).addPath("cancel")
+  def responseInputItems(responseId: String): Uri = response(responseId).addPath("input_items")
+
   def thread(threadId: String): Uri = Threads.addPath(threadId)
   def threadMessages(threadId: String): Uri = Threads.addPath(threadId).addPath("messages")
   def threadMessage(threadId: String, messageId: String): Uri = Threads.addPath(threadId).addPath("messages").addPath(messageId)

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

@@ -32,6 +32,7 @@ import sttp.openai.requests.images.variations.ImageVariationsConfig
 import sttp.openai.requests.models.ModelsResponseData.{DeletedModelData, ModelData, ModelsResponse}
 import sttp.openai.requests.moderations.ModerationsRequestBody.ModerationsBody
 import sttp.openai.requests.moderations.ModerationsResponseData.ModerationData
+import sttp.openai.requests.responses._
 import sttp.openai.requests.threads.QueryParameters
 import sttp.openai.requests.threads.ThreadsRequestBody.CreateThreadBody
 import sttp.openai.requests.threads.ThreadsResponseData.{DeleteThreadResponse, ThreadData}
@@ -267,6 +268,81 @@ class OpenAISyncClient private (
   def deleteChatCompletion(completionId: String): DeleteChatCompletionResponse =
     sendOrThrow(openAI.deleteChatCompletion(completionId))
 
+  /** Creates a model response.
+    *
+    * Provide text or image inputs to generate text or JSON outputs. Have the model call your own custom code or use built-in tools like web
+    * search or file search to use your own data as input for the model's response.
+    *
+    * [[https://platform.openai.com/docs/api-reference/responses/create]]
+    *
+    * @param requestBody
+    *   Model response request body.
+    */
+  def createModelResponse(requestBody: ResponsesRequestBody): ResponsesResponseBody =
+    sendOrThrow(openAI.createModelResponse(requestBody))
+
+  /** Retrieves a model response with the given ID.
+    *
+    * [[https://platform.openai.com/docs/api-reference/responses/get]]
+    *
+    * @param responseId
+    *   The ID of the response to retrieve.
+    *
+    * @return
+    *   The Response object matching the specified ID.
+    */
+  def getModelResponse(
+      responseId: String,
+      queryParameters: GetResponseQueryParameters
+  ): ResponsesResponseBody =
+    sendOrThrow(openAI.getModelResponse(responseId, queryParameters))
+
+  /** Deletes a model response with the given ID.
+    *
+    * [[https://platform.openai.com/docs/api-reference/responses/delete]]
+    *
+    * @param responseId
+    *   The ID of the chat completion to delete.
+    *
+    * @return
+    *   A deletion confirmation object.
+    */
+  def deleteModelResponse(responseId: String): DeleteModelResponseResponse =
+    sendOrThrow(openAI.deleteModelResponse(responseId))
+
+  /** Cancels a model response with the given ID.
+    *
+    * Only responses created with the background parameter set to true can be cancelled
+    *
+    * [[https://platform.openai.com/docs/api-reference/responses/cancel]]
+    *
+    * @param responseId
+    *   The ID of the Upload.
+    *
+    * @return
+    *   The Upload object with status cancelled.
+    */
+  def cancelResponse(responseId: String): ResponsesResponseBody =
+    sendOrThrow(openAI.cancelResponse(responseId))
+
+  /** Returns a list of input items for a given response.
+    *
+    * [[https://platform.openai.com/docs/api-reference/responses/list-input-items]]
+    *
+    * @param responseId
+    *   The ID of the response to retrieve input items for.
+    * @param queryParameters
+    *   Query parameters for pagination and filtering.
+    *
+    * @return
+    *   A list of input items for the response.
+    */
+  def listResponsesInputItems(
+      responseId: String,
+      queryParameters: ListInputItemsQueryParameters = ListInputItemsQueryParameters.empty
+  ): InputItemsListResponseBody =
+    sendOrThrow(openAI.listResponsesInputItems(responseId, queryParameters))
+
   /** Returns a list of files that belong to the user's organization.
     *
     * [[https://platform.openai.com/docs/api-reference/files]]

core/src/main/scala/sttp/openai/json/SnakePickle.scala

@@ -1,7 +1,12 @@
 package sttp.openai.json
 
+import ujson._
+
 /** An object that transforms all snake_case keys into camelCase [[https://com-lihaoyi.github.io/upickle/#CustomConfiguration]] */
 object SnakePickle extends upickle.AttributeTagged {
+
+  override def tagName: String = "type"
+
   private def camelToSnake(s: String): String =
     s.replaceAll("([A-Z])", "#$1").split('#').map(_.toLowerCase).mkString("_")
 
@@ -16,12 +21,6 @@ object SnakePickle extends upickle.AttributeTagged {
   override def objectAttributeKeyWriteMap(s: CharSequence): String =
     camelToSnake(s.toString)
 
-  override def objectTypeKeyReadMap(s: CharSequence): String =
-    snakeToCamel(s.toString)
-
-  override def objectTypeKeyWriteMap(s: CharSequence): String =
-    camelToSnake(s.toString)
-
   /** This is required in order to parse null values into Scala's Option */
   override implicit def OptionWriter[T: SnakePickle.Writer]: Writer[Option[T]] =
     implicitly[SnakePickle.Writer[T]].comap[Option[T]] {
@@ -34,3 +33,45 @@ object SnakePickle extends upickle.AttributeTagged {
       override def visitNull(index: Int) = None
     }
 }
+
+object SerializationHelpers {
+
+  /** Creates a ReadWriter for nested discriminator patterns where the object is wrapped in another object with a discriminator field
+    * pointing to the nested content. Additionally, automatically added discriminator field is removed from the nested object.
+    *
+    * For example: {"type": "json_schema", "json_schema": {...actual object...}}
+    *
+    * @param discriminatorValue
+    *   The value for the discriminator field (e.g., "json_schema")
+    * @param nestedField
+    *   The name of the field containing the nested object (e.g., "json_schema")
+    * @param baseRW
+    *   The base ReadWriter for the type T (typically SnakePickle.macroRW)
+    * @return
+    *   A ReadWriter that wraps the object in the nested discriminator structure
+    */
+  def withNestedDiscriminator[T](discriminatorValue: String, nestedField: String)(implicit
+      baseRW: SnakePickle.Writer[T]
+  ): SnakePickle.Writer[T] =
+    SnakePickle
+      .writer[Value]
+      .comap { t =>
+        val baseJson = SnakePickle.writeJs(t)
+        // Filter out tagName from nested case class
+        val cleanedJson = baseJson match {
+          case obj: Obj =>
+            val filtered = obj.obj.filterNot { case (key, _) =>
+              key == SnakePickle.tagName
+            }
+            Obj.from(filtered)
+          case other => other
+        }
+        Obj(
+          SnakePickle.tagName -> discriminatorValue,
+          nestedField -> cleanedJson
+        )
+      }
+
+  def caseObjectWithDiscriminatorWriter[T](discriminatorValue: String): SnakePickle.Writer[T] =
+    SnakePickle.writer[Value].comap(_ => Obj(SnakePickle.tagName -> Str(discriminatorValue)))
+}