Wrap finish reason in an enum

Author: CJCrafter

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

@@ -3,21 +3,29 @@ package com.cjcrafter.openai.chat
 import com.google.gson.JsonObject
 
 /**
- * Holds the data for 1 generated text completion. For most use cases, only 1
- * [ChatChoice] is generated.
+ * The OpenAI API returns a list of [ChatChoice]. Each chat choice has a
+ * generated message ([ChatChoice.message]) and a finish reason
+ * ([ChatChoice.finishReason]). For most use cases, you only need the generated
+ * message.
+ *
+ * By default, only 1 [ChatChoice] is generated (since [ChatRequest.n] == 1).
+ * When you increase `n`, more options are generated. The more options you
+ * generate, the more tokens you use. In general, it is best to **ONLY**
+ * generate 1 response, and to let the user regenerate the response.
  *
  * @param index        The index in the array... 0 if [ChatRequest.n]=1.
  * @param message      The generated text.
  * @param finishReason Why did the bot stop generating tokens?
+ * @see FinishReason
  */
-class ChatChoice(val index: Int, val message: ChatMessage, val finishReason: String) {
+class ChatChoice(val index: Int, val message: ChatMessage, val finishReason: FinishReason?) {
 
     /**
      * JSON constructor for internal use.
      */
     constructor(json: JsonObject) : this(
         json["index"].asInt,
         ChatMessage(json["message"].asJsonObject),
-        json["finish_reason"].toString()
+        if (json["finish_reason"].isJsonNull) null else FinishReason.valueOf(json["finish_reason"].asString.uppercase())
     )
 }

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

@@ -0,0 +1,31 @@
+package com.cjcrafter.openai.chat
+
+/**
+ * [FinishReason] wraps the possible reasons that a generation model may stop
+ * generating tokens. For most **PROPER** use cases (see [best practices]()),
+ * the finish reason will be [STOP]. When working with streams, finish reason
+ * will be `null` since it has not completed the message yet.
+ */
+enum class FinishReason {
+
+    /**
+     * [STOP] is the most common finish reason, and it occurs when the model
+     * completely generates its entire message, and has nothing else to add.
+     * Ideally, you always want your finish reason to be [STOP].
+     */
+    STOP,
+
+    /**
+     * [LENGTH] occurs when the bot is not able to finish the response within
+     * its token limit. When it reaches the token limit, it sends the
+     * incomplete message with finish reason [LENGTH]
+     */
+    LENGTH,
+
+    /**
+     * [TEMPERATURE] is a rare occurrence, and only happens when the
+     * [ChatRequest.temperature] is low enough that it is impossible for the
+     * model to continue generating text.
+     */
+    TEMPERATURE
+}