feat(chat): add verbosity parameter support

CHANGELOG.md

@@ -1,3 +1,8 @@
+## Unreleased
+
+### Added
+- **chat**: add verbosity parameter support for controlling response length and detail
+
 ## 4.0.1
 > Published 02 Feb 2025
 

openai-client/src/commonTest/kotlin/com/aallam/openai/client/TestChatCompletions.kt

@@ -302,4 +302,30 @@ class TestChatCompletions : TestOpenAI() {
         assertNotNull(results.last().usage?.completionTokens)
         assertNotNull(results.last().usage?.totalTokens)
     }
+
+    @Test
+    fun chatCompletionsWithVerbosity() = test {
+        val request = chatCompletionRequest {
+            model = ModelId("gpt-4o")
+            verbosity = Verbosity.Low
+            messages {
+                user {
+                    content = "Explain quantum computing"
+                }
+            }
+            maxTokens = 100
+        }
+
+        val completion = openAI.chatCompletion(request)
+        assertTrue { completion.choices.isNotEmpty() }
+        assertNotNull(completion.choices.first().message.content)
+    }
+
+    @Test
+    fun verbosityValues() {
+        // Test that verbosity values are correctly defined
+        assertEquals("low", Verbosity.Low.id)
+        assertEquals("medium", Verbosity.Medium.id)
+        assertEquals("high", Verbosity.High.id)
+    }
 }

openai-core/src/commonMain/kotlin/com.aallam.openai.api/chat/ChatCompletionRequest.kt

@@ -31,6 +31,12 @@ public data class ChatCompletionRequest(
      */
     @SerialName("reasoning_effort") public val reasoningEffort: Effort? = null,
 
+    /**
+     * Constrains the verbosity of responses. Currently supported values are low, medium, and high.
+     * Controls how concise or verbose the model's output will be.
+     */
+    @SerialName("verbosity") public val verbosity: Verbosity? = null,
+
     /**
      * What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random,
      * while lower values like 0.2 will make it more focused and deterministic.
@@ -213,7 +219,13 @@ public class ChatCompletionRequestBuilder {
      * Constrains effort on reasoning for reasoning models. Currently supported values are low, medium, and high.
      * Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.
      */
-    public val reasoningEffort: Effort? = null
+    public var reasoningEffort: Effort? = null
+
+    /**
+     * Constrains the verbosity of responses. Currently supported values are low, medium, and high.
+     * Controls how concise or verbose the model's output will be.
+     */
+    public var verbosity: Verbosity? = null
 
     /**
      * What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random,
@@ -391,6 +403,7 @@ public class ChatCompletionRequestBuilder {
         model = requireNotNull(model) { "model is required" },
         messages = requireNotNull(messages) { "messages is required" },
         reasoningEffort = reasoningEffort,
+        verbosity = verbosity,
         temperature = temperature,
         topP = topP,
         n = n,

openai-core/src/commonMain/kotlin/com.aallam.openai.api/chat/Verbosity.kt

@@ -0,0 +1,28 @@
+package com.aallam.openai.api.chat
+
+import kotlinx.serialization.Serializable
+import kotlin.jvm.JvmInline
+
+/**
+ * Verbosity level for controlling response length and detail.
+ */
+@Serializable
+@JvmInline
+public value class Verbosity(public val id: String) {
+    public companion object {
+        /**
+         * Low verbosity - terse, concise responses.
+         */
+        public val Low: Verbosity = Verbosity("low")
+
+        /**
+         * Medium verbosity - balanced responses (default).
+         */
+        public val Medium: Verbosity = Verbosity("medium")
+
+        /**
+         * High verbosity - detailed, comprehensive responses.
+         */
+        public val High: Verbosity = Verbosity("high")
+    }
+}