documentation improvements

Author: CJCrafter

build.gradle.kts

@@ -8,6 +8,7 @@ plugins {
     `maven-publish`
     signing
     kotlin("jvm") version "1.7.20-RC"
+    id("org.jetbrains.dokka") version "1.8.10" // KDoc Documentation Builder
     id("com.github.breadmoirai.github-release") version "2.4.1"
 }
 

src/main/java/com/cjcrafter/openai/chat/package-info.java

@@ -14,7 +14,25 @@ import java.util.concurrent.TimeUnit
 /**
  * The ChatBot class wraps the OpenAI API and lets you send messages and
  * receive responses. For more information on how this works, check out
- * the [OpenAI Documentation](https://platform.openai.com/docs/api-reference/completions)).
+ * the [OpenAI Documentation](https://platform.openai.com/docs/api-reference/chat)).
+ *
+ * [com.cjcrafter.openai.chat] differs from [com.cjcrafter.openai.completions].
+ * Chat has conversational memory, and is best suited to generate human-readable
+ * text. Think of chat as a human that insists on giving elaborate responses.
+ * If you are looking for more robotic or specific responses, consider using
+ * completions instead.
+ *
+ * To get your API key:
+ * 1. Log in to your account: Go to [https://www.openai.com/](openai.com) and
+ * log in.
+ * 2. Access the API dashboard: After logging in, click on the "API" tab.
+ * 3. Choose a subscription plan: Select a suitable plan based on your needs
+ * and complete the payment process.
+ * 4. Obtain your API key: After subscribing to a plan, you will be redirected
+ * to the API dashboard, where you can find your unique API key. Copy and store it securely.
+ *
+ * @property apiKey Your OpenAI API key. It starts with `"sk-"` (without the quotes).
+ * @constructor Create a ChatBot for responding to requests.
  */
 class ChatBot(private val apiKey: String) {
 

src/main/java/com/cjcrafter/openai/completions/package-info.java

@@ -1,37 +1,54 @@
 package com.cjcrafter.openai.chat
 
-import com.google.gson.JsonObject
 import com.google.gson.annotations.SerializedName
 
 /**
- * These are the arguments that control the result of the output. For more
- * information, refer to the [OpenAI Docs](https://platform.openai.com/docs/api-reference/completions/create).
+ * [ChatRequest] holds the configurable options that can be sent to the OpenAI
+ * Chat API. For most use cases, you only need to set [model] and [messages].
+ * For more detailed descriptions for each option, refer to the
+ * [Chat Wiki](https://platform.openai.com/docs/api-reference/chat)
  *
- * @param model            The model used to generate the text. Recommended: "gpt-3.5-turbo."
- * @param messages         All previous messages from the conversation.
- * @param temperature      How "creative" the results are. [0.0, 2.0].
- * @param topP             Controls how "on topic" the tokens are.
- * @param n                Controls how many responses to generate. Numbers >1 will chew through your tokens.
- * @param stream           **UNTESTED** recommend keeping this false.
- * @param stop             The sequence used to stop generating tokens.
- * @param maxTokens        The maximum number of tokens to use.
- * @param presencePenalty  Prevent talking about duplicate topics.
- * @param frequencyPenalty Prevent repeating the same text.
- * @param logitBias        Control specific tokens from being used.
- * @param user             Who send this request (for moderation).
+ * [messages] stores **ALL** previous messages from the conversation. It is
+ * **YOUR RESPONSIBILITY** to store and update this list for your conversations
+ * (Check out the [JavaChatTest] or the READEME.md for an example). In general,
+ * the list should start with a [ChatUser.SYSTEM] message, then alternate between
+ * [ChatUser.USER] and [ChatUser.ASSISTANT]. Failing to follow this order may
+ * confuse the model and cause it to apologize for not responding.
+ *
+ * It is best practice to store 1 [ChatRequest] for each conversation, and to
+ * update the variables (especially [messages]) between [ChatBot.generateResponse]
+ * calls. You can easily store your [ChatRequest] as a string or as a json file
+ * using google's GSON library to serialize the object as a JSON string.
+ *
+ * You should not set [stream]. TODO update docs after adding stream support
+ *
+ * @property model            The model used to generate the text. Recommended: `"gpt-3.5-turbo"` (without quotes).
+ * @property messages         A mutable list of previous messages from the conversation.
+ * @property temperature      How "creative" the results are. [0.0, 2.0]. Defaults to `1.0`.
+ * @property topP             Controls how "on topic" the tokens are. Defaults to `1.0`.
+ * @property n                Controls how many responses to generate. Numbers >1 will chew through your tokens. Defaults to `1`.
+ * @property stream           true=wait until entire message is generated, false=respond procedurally. Defaults to `false`.
+ * @property stop             The sequence used to stop generating tokens. Defaults to `null`.
+ * @property maxTokens        The maximum number of tokens to use. Defaults to `infinity`.
+ * @property presencePenalty  Prevent talking about duplicate topics. Defaults to `0.0`.
+ * @property frequencyPenalty Prevent repeating the same text. Defaults to `0.0`.
+ * @property logitBias        Increase/Decrease the chances of a specific token to appear in generated text. Defaults to `null`.
+ * @property user             Who send this request (for moderation).
+ * @constructor Create a chat request
+ * @see ChatBot.generateResponse
  * @see <a href="https://platform.openai.com/docs/api-reference/completions/create">OpenAI Wiki</a>
  */
 data class ChatRequest @JvmOverloads constructor(
-    val model: String,
+    var model: String,
     var messages: MutableList<ChatMessage>,
-    val temperature: Float = 1.0f,
-    @field:SerializedName("top_p") val topP: Float = 1.0f,
-    val n: Int = 1,
-    val stream: Boolean = false,
-    val stop: String? = null,
-    @field:SerializedName("max_tokens") val maxTokens: Int? = null,
-    @field:SerializedName("presence_penalty") val presencePenalty: Float = 0f,
-    @field:SerializedName("frequency_penalty") val frequencyPenalty: Float = 0f,
-    @field:SerializedName("logit_bias") val logitBias: JsonObject? = null,
-    val user: String? = null
+    var temperature: Float? = null,
+    @field:SerializedName("top_p") var topP: Float? = null,
+    var n: Int? = null,
+    var stream: Boolean? = null,
+    var stop: String? = null,
+    @field:SerializedName("max_tokens") var maxTokens: Int? = null,
+    @field:SerializedName("presence_penalty") var presencePenalty: Float? = null,
+    @field:SerializedName("frequency_penalty") var frequencyPenalty: Float? = null,
+    @field:SerializedName("logit_bias") var logitBias: Map<String, Float>? = null,
+    var user: String? = null
 )

src/main/java/com/cjcrafter/openai/exception/package-info.java

@@ -28,6 +28,9 @@ class ChatResponse(
     /**
      * Shorthand for accessing the generated messages (shorthand for
      * [ChatResponse.choices]).
+     *
+     * @param index The index of the message (`0` for most use cases).
+     * @return The generated [ChatChoice] at the index.
      */
     operator fun get(index: Int): ChatChoice {
         return choices[index]

src/main/kotlin/com/cjcrafter/openai/chat/ChatBot.kt

@@ -0,0 +1,4 @@
+/**
+ * @see [OpenAI Wiki](https://platform.openai.com/docs/api-reference/completions)
+ */
+package com.cjcrafter.openai.completions

src/main/kotlin/com/cjcrafter/openai/chat/ChatRequest.kt

@@ -0,0 +1,9 @@
+/**
+ * Since we are accessing a cloud-based service, there are *many* steps
+ * that can go wrong. This package contains classes the wraps common error
+ * codes with instructions to fix or minimize the occurrence of errors. All
+ * exceptions inherit from [com.cjcrafter.openai.exception.OpenAIException].
+ *
+ * @see [OpenAI Wiki](https://platform.openai.com/docs/guides/error-codes/api-errors)
+ */
+package com.cjcrafter.openai.exception

src/main/kotlin/com/cjcrafter/openai/chat/ChatResponse.kt

@@ -6,7 +6,7 @@
 import java.util.List;
 import java.util.Scanner;
 
-public class JavaTest {
+public class JavaChatTest {
 
     public static void main(String[] args) throws IOException {
         Scanner scan = new Scanner(System.in);