Added scala docs

softwaremill · May 17, 2024 · a3ee92e · a3ee92e
1 parent 57c04ab
commit a3ee92e
Show file tree

Hide file tree

Showing 14 changed files with 566 additions and 43 deletions.
diff --git a/README.md b/README.md
@@ -39,9 +39,10 @@ import sttp.openai.requests.completions.chat.ChatRequestBody.{ChatBody, ChatComp
 import sttp.openai.requests.completions.chat.message._
 
 object Main extends App {
+  // Read your API secret-key from env variables
+  private val apiKey = System.getenv("openai-key")
+
   // Create an instance of OpenAISyncClient providing your API secret-key
-  private val apiKey = System.getProperty("openai-key")
-
   val openAI: OpenAISyncClient = OpenAISyncClient(apiKey)
 
   // Create body of Chat Completions Request
@@ -98,7 +99,6 @@ object Main extends App {
       content = Content.TextContent("Hello!"),
     )
   )
-
 
   val chatRequestBody: ChatBody = ChatBody(
     // assuming one has already executed `ollama pull mistral` in console
@@ -146,7 +146,11 @@ import sttp.openai.requests.completions.chat.message._
 
 object Main extends IOApp {
   override def run(args: List[String]): IO[ExitCode] = {
-    val openAI: OpenAI = new OpenAI("your-secret-key", uri"https://api.groq.com/openai/v1")
+    // Read your API secret-key from env variables
+    private val apiKey = System.getenv("openai-key")
+
+    // Create an instance of OpenAISyncClient providing your API secret-key
+    val openAI: OpenAI = new OpenAI(apiKey, uri"https://api.groq.com/openai/v1")
 
     val bodyMessages: Seq[Message] = Seq(
       Message.UserMessage(
@@ -158,6 +162,7 @@ object Main extends IOApp {
       model = ChatCompletionModel.CustomChatCompletionModel("gemma-7b-it"),
       messages = bodyMessages
     )
+
     HttpClientCatsBackend.resource[IO]().use { backend =>
       val response: IO[Either[OpenAIException, ChatResponse]] =
         openAI
@@ -214,7 +219,11 @@ import sttp.openai.requests.completions.chat.message._
 
 object Main extends IOApp {
   override def run(args: List[String]): IO[ExitCode] = {
-    val openAI: OpenAI = new OpenAI("your-secret-key")
+    // Read your API secret-key from env variables
+    private val apiKey = System.getenv("openai-key")
+
+    // Create an instance of OpenAISyncClient providing your API secret-key
+    val openAI: OpenAI = new OpenAI(apiKey)
 
     val bodyMessages: Seq[Message] = Seq(
       Message.UserMessage(
@@ -226,6 +235,7 @@ object Main extends IOApp {
       model = ChatCompletionModel.GPT35Turbo,
       messages = bodyMessages
     )
+
     HttpClientCatsBackend.resource[IO]().use { backend =>
       val response: IO[Either[OpenAIException, ChatResponse]] =
         openAI
@@ -284,7 +294,11 @@ import sttp.openai.requests.completions.chat.message._
 
 object Main extends IOApp {
   override def run(args: List[String]): IO[ExitCode] = {
-    val openAI: OpenAI = new OpenAI("your-secret-key")
+    // Read your API secret-key from env variables
+    private val apiKey = System.getenv("openai-key")
+
+    // Create an instance of OpenAISyncClient providing your API secret-key
+    val openAI: OpenAI = new OpenAI(apiKey)
 
     val bodyMessages: Seq[Message] = Seq(
       Message.UserMessage(

diff --git a/core/src/main/scala/sttp/openai/OpenAI.scala b/core/src/main/scala/sttp/openai/OpenAI.scala
@@ -16,7 +16,12 @@ import sttp.openai.requests.embeddings.EmbeddingsRequestBody.EmbeddingsBody
 import sttp.openai.requests.embeddings.EmbeddingsResponseBody.EmbeddingResponse
 import sttp.openai.requests.files.FilesResponseData._
 import sttp.openai.requests.finetunes.FineTunesRequestBody
-import sttp.openai.requests.finetunes.FineTunesResponseData.{DeleteFineTuneModelResponse, FineTuneEventsResponse, FineTuneResponse, GetFineTunesResponse}
+import sttp.openai.requests.finetunes.FineTunesResponseData.{
+  DeleteFineTuneModelResponse,
+  FineTuneEventsResponse,
+  FineTuneResponse,
+  GetFineTunesResponse
+}
 import sttp.openai.requests.images.ImageResponseData.ImageResponse
 import sttp.openai.requests.images.creation.ImageCreationRequestBody.ImageCreationBody
 import sttp.openai.requests.images.edit.ImageEditsConfig
@@ -33,13 +38,23 @@ import sttp.openai.requests.threads.ThreadsRequestBody.CreateThreadBody
 import sttp.openai.requests.threads.ThreadsResponseData.{DeleteThreadResponse, ThreadData}
 import sttp.openai.requests.threads.messages.ThreadMessagesRequestBody.CreateMessage
 import sttp.openai.requests.threads.messages.ThreadMessagesResponseData.{ListMessagesResponse, MessageData}
-import sttp.openai.requests.threads.runs.ThreadRunsRequestBody.{CreateRun, CreateThreadAndRun, ModifyRun, SubmitToolOutputsToRun, ToolOutput}
+import sttp.openai.requests.threads.runs.ThreadRunsRequestBody.{
+  CreateRun,
+  CreateThreadAndRun,
+  ModifyRun,
+  SubmitToolOutputsToRun,
+  ToolOutput
+}
 import sttp.openai.requests.threads.runs.ThreadRunsResponseData.{ListRunStepsResponse, ListRunsResponse, RunData, RunStepData}
 import sttp.openai.requests.threads.QueryParameters
 import sttp.openai.requests.vectorstore.VectorStoreRequestBody.{CreateVectorStoreBody, ModifyVectorStoreBody}
 import sttp.openai.requests.vectorstore.VectorStoreResponseData.{DeleteVectorStoreResponse, ListVectorStoresResponse, VectorStore}
 import sttp.openai.requests.vectorstore.file.VectorStoreFileRequestBody.{CreateVectorStoreFileBody, ListVectorStoreFilesBody}
-import sttp.openai.requests.vectorstore.file.VectorStoreFileResponseData.{DeleteVectorStoreFileResponse, ListVectorStoreFilesResponse, VectorStoreFile}
+import sttp.openai.requests.vectorstore.file.VectorStoreFileResponseData.{
+  DeleteVectorStoreFileResponse,
+  ListVectorStoreFilesResponse,
+  VectorStoreFile
+}
 
 import java.io.File
 import java.nio.file.Paths
@@ -944,24 +959,54 @@ class OpenAI(authToken: String, baseUri: Uri = OpenAIUris.OpenAIBaseUri) {
       .post(openAIUris.threadRunCancel(threadId, runId))
       .response(asJsonSnake[RunData])
 
+  /** Creates vector store
+    *
+    * @param createVectorStoreBody
+    *   Options for new vector store
+    * @return
+    *   Newly created vector store or exception
+    */
   def createVectorStore(createVectorStoreBody: CreateVectorStoreBody): Request[Either[OpenAIException, VectorStore]] =
     betaOpenAIAuthRequest
       .post(openAIUris.VectorStores)
       .body(createVectorStoreBody)
       .response(asJsonSnake[VectorStore])
 
+  /** Lists vector store
+    *
+    * @param queryParameters
+    *   Search params
+    * @return
+    *   List of vector stores matching criteria or exception
+    */
   def listVectorStores(
       queryParameters: QueryParameters = QueryParameters.empty
   ): Request[Either[OpenAIException, ListVectorStoresResponse]] =
     betaOpenAIAuthRequest
       .get(openAIUris.VectorStores.withParams(queryParameters.toMap))
       .response(asJsonSnake[ListVectorStoresResponse])
 
+  /** Retrieves vector store by id
+    *
+    * @param vectorStoreId
+    *   Id of vector store
+    * @return
+    *   Vector store object or exception
+    */
   def retrieveVectorStore(vectorStoreId: String): Request[Either[OpenAIException, VectorStore]] =
     betaOpenAIAuthRequest
       .get(openAIUris.vectorStore(vectorStoreId))
       .response(asJsonSnake[VectorStore])
 
+  /** Modifies vector store
+    *
+    * @param vectorStoreId
+    *   Id of vector store to modify
+    * @param modifyVectorStoreBody
+    *   New values for store properties
+    * @return
+    *   Modified vector store object
+    */
   def modifyVectorStore(
       vectorStoreId: String,
       modifyVectorStoreBody: ModifyVectorStoreBody
@@ -971,11 +1016,27 @@ class OpenAI(authToken: String, baseUri: Uri = OpenAIUris.OpenAIBaseUri) {
       .body(modifyVectorStoreBody)
       .response(asJsonSnake[VectorStore])
 
+  /** Deletes vector store
+    *
+    * @param vectorStoreId
+    *   Id of vector store to be deleted
+    * @return
+    *   Result of deleted operation
+    */
   def deleteVectorStore(vectorStoreId: String): Request[Either[OpenAIException, DeleteVectorStoreResponse]] =
     betaOpenAIAuthRequest
       .delete(openAIUris.vectorStore(vectorStoreId))
       .response(asJsonSnake[DeleteVectorStoreResponse])
 
+  /** Creates vector store file
+    *
+    * @param vectorStoreId
+    *   Id of vector store for file
+    * @param createVectorStoreFileBody
+    *   Properties of file
+    * @return
+    *   Newly created vector store file
+    */
   def createVectorStoreFile(
       vectorStoreId: String,
       createVectorStoreFileBody: CreateVectorStoreFileBody
@@ -985,6 +1046,15 @@ class OpenAI(authToken: String, baseUri: Uri = OpenAIUris.OpenAIBaseUri) {
       .body(createVectorStoreFileBody)
       .response(asJsonSnake[VectorStoreFile])
 
+  /** List files belonging to particular datastore
+    *
+    * @param vectorStoreId
+    *   Id of vector store
+    * @param queryParameters
+    *   Search params
+    * @return
+    *   List of vector store files
+    */
   def listVectorStoreFiles(
       vectorStoreId: String,
       queryParameters: ListVectorStoreFilesBody = ListVectorStoreFilesBody()
@@ -993,11 +1063,29 @@ class OpenAI(authToken: String, baseUri: Uri = OpenAIUris.OpenAIBaseUri) {
       .get(openAIUris.vectorStoreFiles(vectorStoreId).withParams(queryParameters.toMap))
       .response(asJsonSnake[ListVectorStoreFilesResponse])
 
+  /** Retrieves vector store file by id
+    *
+    * @param vectorStoreId
+    *   Id of vector store
+    * @param fileId
+    *   Id of vector store file
+    * @return
+    *   Vector store file
+    */
   def retrieveVectorStoreFile(vectorStoreId: String, fileId: String): Request[Either[OpenAIException, VectorStoreFile]] =
     betaOpenAIAuthRequest
       .get(openAIUris.vectorStoreFile(vectorStoreId, fileId))
       .response(asJsonSnake[VectorStoreFile])
 
+  /** Deletes vector store file by id
+   *
+   * @param vectorStoreId
+   *   Id of vector store
+   * @param fileId
+   *   Id of vector store file
+   * @return
+   *   Result of delete operation
+   */
   def deleteVectorStoreFile(vectorStoreId: String, fileId: String): Request[Either[OpenAIException, DeleteVectorStoreFileResponse]] =
     betaOpenAIAuthRequest
       .delete(openAIUris.vectorStoreFile(vectorStoreId, fileId))

diff --git a/core/src/main/scala/sttp/openai/OpenAISyncClient.scala b/core/src/main/scala/sttp/openai/OpenAISyncClient.scala
@@ -690,41 +690,114 @@ class OpenAISyncClient private (authToken: String, backend: SyncBackend, closeCl
   def cancelRun(threadId: String, runId: String): RunData =
     sendOrThrow(openAI.cancelRun(threadId, runId))
 
+  /** Creates vector store
+   *
+   * @param createVectorStoreBody
+   *   Options for new vector store
+   * @return
+   *   Newly created vector store or exception
+   */
   def createVectorStore(createVectorStoreBody: CreateVectorStoreBody): VectorStore =
     sendOrThrow(openAI.createVectorStore(createVectorStoreBody))
 
+  /** Lists vector store
+   *
+   * @param queryParameters
+   *   Search params
+   * @return
+   *   List of vector stores matching criteria or exception
+   */
   def listVectorStores(
       queryParameters: QueryParameters = QueryParameters.empty
   ): ListVectorStoresResponse =
     sendOrThrow(openAI.listVectorStores(queryParameters))
 
+  /** Retrieves vector store by id
+   *
+   * @param vectorStoreId
+   *   Id of vector store
+   * @return
+   *   Vector store object or exception
+   */
   def retrieveVectorStore(vectorStoreId: String): VectorStore =
     sendOrThrow(openAI.retrieveVectorStore(vectorStoreId))
 
+  /** Modifies vector store
+   *
+   * @param vectorStoreId
+   *   Id of vector store to modify
+   * @param modifyVectorStoreBody
+   *   New values for store properties
+   * @return
+   *   Modified vector store object
+   */
   def modifyVectorStore(
       vectorStoreId: String,
       modifyVectorStoreBody: ModifyVectorStoreBody
   ): VectorStore =
     sendOrThrow(openAI.modifyVectorStore(vectorStoreId, modifyVectorStoreBody))
 
+  /** Deletes vector store
+   *
+   * @param vectorStoreId
+   *   Id of vector store to be deleted
+   * @return
+   *   Result of deleted operation
+   */
   def deleteVectorStore(vectorStoreId: String): DeleteVectorStoreResponse =
     sendOrThrow(openAI.deleteVectorStore(vectorStoreId))
 
+  /** Creates vector store file
+   *
+   * @param vectorStoreId
+   *   Id of vector store for file
+   * @param createVectorStoreFileBody
+   *   Properties of file
+   * @return
+   *   Newly created vector store file
+   */
   def createVectorStoreFile(
       vectorStoreId: String,
       createVectorStoreFileBody: CreateVectorStoreFileBody
   ): VectorStoreFile =
     sendOrThrow(openAI.createVectorStoreFile(vectorStoreId, createVectorStoreFileBody))
 
+  /** List files belonging to particular datastore
+   *
+   * @param vectorStoreId
+   *   Id of vector store
+   * @param queryParameters
+   *   Search params
+   * @return
+   *   List of vector store files
+   */
   def listVectorStoreFiles(
       vectorStoreId: String,
       queryParameters: ListVectorStoreFilesBody = ListVectorStoreFilesBody()
   ): ListVectorStoreFilesResponse =
     sendOrThrow(openAI.listVectorStoreFiles(vectorStoreId, queryParameters))
 
+  /** Retrieves vector store file by id
+   *
+   * @param vectorStoreId
+   *   Id of vector store
+   * @param fileId
+   *   Id of vector store file
+   * @return
+   *   Vector store file
+   */
   def retrieveVectorStoreFile(vectorStoreId: String, fileId: String): VectorStoreFile =
     sendOrThrow(openAI.retrieveVectorStoreFile(vectorStoreId, fileId))
 
+  /** Deletes vector store file by id
+   *
+   * @param vectorStoreId
+   *   Id of vector store
+   * @param fileId
+   *   Id of vector store file
+   * @return
+   *   Result of delete operation
+   */
   def deleteVectorStoreFile(vectorStoreId: String, fileId: String): DeleteVectorStoreFileResponse =
     sendOrThrow(openAI.deleteVectorStoreFile(vectorStoreId, fileId))
 

diff --git a/core/src/main/scala/sttp/openai/requests/assistants/AssistantsResponseData.scala b/core/src/main/scala/sttp/openai/requests/assistants/AssistantsResponseData.scala
@@ -64,9 +64,11 @@ object AssistantsResponseData {
     * @param data
     *   A list of assistant objects.
     * @param firstId
+    *   Id of first object
     * @param lastId
+    *   Id of last object
     * @param hasMore
-    *   }
+    *   Denotes if there are more object available }
     */
   case class ListAssistantsResponse(
       `object`: String = "list",
@@ -80,6 +82,7 @@ object AssistantsResponseData {
   }
 
   /** @param id
+    *   Id of deleted object
     * @param `object`
     *   assistant.deleted
     * @param deleted