structured-outputs: changes from code review

Author: damo

README.md

@@ -343,21 +343,23 @@ is a feature that ensures that the model will always generate responses that adh
 A JSON schema can be defined by creating a
 [`ResponseFormatJsonSchema`](openai-java-core/src/main/kotlin/com/openai/models/ResponseFormatJsonSchema.kt)
 and setting it on the input parameters. However, for greater convenience, a JSON schema can instead
-be derived automatically from the structure of an arbitrary Java class. The response will then
-automatically convert the generated JSON content to an instance of that Java class.
+be derived automatically from the structure of an arbitrary Java class. The JSON content from the
+response will then be converted automatically to an instance of that Java class. A full, working
+example of the use of Structured Outputs with arbitrary Java classes can be seen in
+[`StructuredOutputsClassExample`](openai-java-example/src/main/java/com/openai/example/StructuredOutputsClassExample.java).
 
 Java classes can contain fields declared to be instances of other classes and can use collections:
 
 ```java
 class Person {
     public String name;
-    public int yearOfBirth;
+    public int birthYear;
 }
 
 class Book {
     public String title;
     public Person author;
-    public int yearPublished;
+    public int publicationYear;
 }
 
 class BookList {
@@ -375,7 +377,7 @@ import com.openai.models.chat.completions.ChatCompletionCreateParams;
 import com.openai.models.chat.completions.StructuredChatCompletionCreateParams;
 
 StructuredChatCompletionCreateParams<BookList> params = ChatCompletionCreateParams.builder()
-        .addUserMessage("List six famous nineteenth century novels.")
+        .addUserMessage("List some famous late twentieth century novels.")
         .model(ChatModel.GPT_4_1)
         .responseFormat(BookList.class)
         .build();
@@ -403,11 +405,25 @@ import java.util.Optional;
 class Book {
     public String title;
     public Person author;
-    public int yearPublished;
+    public int publicationYear;
     public Optional<String> isbn;
 }
 ```
 
+Generic type information for fields is retained in the class's metadata, but _generic type erasure_
+applies in other scopes. While, for example, a JSON schema defining an array of strings can be
+derived from the `BoolList.books` field with type `List<String>`, a valid JSON schema cannot be
+derived from a local variable of that same type, so the following will _not_ work:
+
+```java
+List<String> books = new ArrayList<>();
+
+StructuredChatCompletionCreateParams<BookList> params = ChatCompletionCreateParams.builder()
+        .responseFormat(books.class)
+        // ...
+        .build();
+```
+
 If an error occurs while converting a JSON response to an instance of a Java class, the error
 message will include the JSON response to assist in diagnosis. For instance, if the response is
 truncated, the JSON data will be incomplete and cannot be converted to a class instance. If your
@@ -435,20 +451,23 @@ well.
 schema in the request.
 - **Version Compatibility**: There may be instances where local validation fails while remote
 validation succeeds. This can occur if the SDK version is outdated compared to the restrictions
-enforced by the remote model.
+enforced by the remote AI model.
 - **Disabling Local Validation**: If you encounter compatibility issues and wish to bypass local
-validation, you can disable it by passing `false` to the `responseFormat(Class<T>, boolean)` method
-when building the parameters. (The default value for this parameter is `true`.)
+validation, you can disable it by passing
+[`JsonSchemaLocalValidation.NO`](openai-java-core/src/main/kotlin/com/openai/core/JsonSchemaLocalValidation.kt)
+to the `responseFormat(Class<T>, JsonSchemaLocalValidation)` method when building the parameters.
+(The default value for this parameter is `JsonSchemaLocalValidation.YES`.)
 
 ```java
+import com.openai.core.JsonSchemaLocalValidation;
 import com.openai.models.ChatModel;
 import com.openai.models.chat.completions.ChatCompletionCreateParams;
 import com.openai.models.chat.completions.StructuredChatCompletionCreateParams;
 
 StructuredChatCompletionCreateParams<BookList> params = ChatCompletionCreateParams.builder()
-        .addUserMessage("List six famous nineteenth century novels.")
+        .addUserMessage("List some famous late twentieth century novels.")
         .model(ChatModel.GPT_4_1)
-        .responseFormat(BookList.class, false) // Disable local validation.
+        .responseFormat(BookList.class, JsonSchemaLocalValidation.NO)
         .build();
 ```
 
@@ -470,14 +489,17 @@ import com.fasterxml.jackson.annotation.JsonPropertyDescription;
 class Person {
     @JsonPropertyDescription("The first name and surname of the person")
     public String name;
-    public int yearOfBirth;
+    public int birthYear;
+    @JsonPropertyDescription("The year the person died, or 'present' if the person is living.")
+    public String deathYear;
 }
 
 @JsonClassDescription("The details of one published book")
 class Book {
     public String title;
     public Person author;
-    public int yearPublished;
+    @JsonPropertyDescription("The year in which the book was first published.")
+    public int publicationYear;
     @JsonIgnore public String genre;
 }
 

openai-java-core/src/main/kotlin/com/openai/core/JsonSchemaLocalValidation.kt

@@ -0,0 +1,19 @@
+package com.openai.core
+
+/**
+ * Options for local validation of JSON schemas derived from arbitrary classes before a request is
+ * executed.
+ */
+enum class JsonSchemaLocalValidation {
+    /**
+     * Validate the JSON schema locally before the request is executed. The remote AI model will
+     * also validate the JSON schema.
+     */
+    YES,
+
+    /**
+     * Do not validate the JSON schema locally before the request is executed. The remote AI model
+     * will always validate the JSON schema.
+     */
+    NO,
+}

openai-java-core/src/main/kotlin/com/openai/core/JsonSchemaValidator.kt

@@ -201,9 +201,7 @@ internal class JsonSchemaValidator private constructor() {
      *   each new schema.
      */
     fun validate(rootSchema: JsonNode): JsonSchemaValidator {
-        if (isValidationComplete) {
-            throw IllegalStateException("Validation already complete.")
-        }
+        check(!isValidationComplete) { "Validation already complete." }
         isValidationComplete = true
 
         validateSchema(rootSchema, ROOT_PATH, ROOT_DEPTH)

openai-java-core/src/main/kotlin/com/openai/core/StructuredOutputs.kt

@@ -23,33 +23,33 @@ private val MAPPER =
         .addModule(JavaTimeModule())
         .build()
 
+@JvmSynthetic
 internal fun <T> fromClass(
     type: Class<T>,
-    localValidation: Boolean = true,
+    localValidation: JsonSchemaLocalValidation = JsonSchemaLocalValidation.YES,
 ): ResponseFormatJsonSchema {
     val schema = extractSchema(type)
 
-    if (localValidation) {
+    if (localValidation == JsonSchemaLocalValidation.YES) {
         val validator = JsonSchemaValidator.create().validate(schema)
 
-        if (!validator.isValid()) {
-            throw IllegalArgumentException(
-                "Local validation failed for JSON schema derived from $type:\n" +
-                    validator.errors().joinToString("\n") { " - $it" }
-            )
+        require(validator.isValid()) {
+            "Local validation failed for JSON schema derived from $type:\n" +
+                validator.errors().joinToString("\n") { " - $it" }
         }
     }
 
     return ResponseFormatJsonSchema.builder()
         .jsonSchema(
             ResponseFormatJsonSchema.JsonSchema.builder()
                 .name("json-schema-from-${type.simpleName}")
-                .schema(JsonValue.from(schema))
+                .schema(JsonValue.fromJsonNode(schema))
                 .build()
         )
         .build()
 }
 
+@JvmSynthetic
 internal fun <T> extractSchema(type: Class<T>): JsonNode {
     // Validation is not performed by this function, as it allows extraction of the schema and
     // validation of the schema to be controlled more easily when unit testing, as no exceptions
@@ -76,6 +76,7 @@ internal fun <T> extractSchema(type: Class<T>): JsonNode {
     return SchemaGenerator(configBuilder.build()).generateSchema(type)
 }
 
+@JvmSynthetic
 internal fun <T> fromJson(json: String, type: Class<T>): T =
     try {
         MAPPER.readValue(json, type)

openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionCreateParams.kt

@@ -19,6 +19,7 @@ import com.openai.core.Enum
 import com.openai.core.ExcludeMissing
 import com.openai.core.JsonField
 import com.openai.core.JsonMissing
+import com.openai.core.JsonSchemaLocalValidation
 import com.openai.core.JsonValue
 import com.openai.core.Params
 import com.openai.core.allMaxBy
@@ -1304,15 +1305,20 @@ private constructor(
          *
          * @param responseFormat A class from which a JSON schema will be derived to define the
          *   response format.
-         * @param localValidation `true` (the default) to validate the JSON schema locally when it
-         *   is generated by this method to confirm that it adheres to the requirements and
-         *   restrictions on JSON schemas imposed by the OpenAI specification; or `false` to disable
-         *   local validation. See the SDK documentation for more details.
+         * @param localValidation [com.openai.core.JsonSchemaLocalValidation.YES] (the default) to
+         *   validate the JSON schema locally when it is generated by this method to confirm that it
+         *   adheres to the requirements and restrictions on JSON schemas imposed by the OpenAI
+         *   specification; or [com.openai.core.JsonSchemaLocalValidation.NO] to skip local
+         *   validation and rely only on remote validation. See the SDK documentation for more
+         *   details.
          * @throws IllegalArgumentException If local validation is enabled, but it fails because a
          *   valid JSON schema cannot be derived from the given class.
          */
         @JvmOverloads
-        fun <T : Any> responseFormat(responseFormat: Class<T>, localValidation: Boolean = true) =
+        fun <T : Any> responseFormat(
+            responseFormat: Class<T>,
+            localValidation: JsonSchemaLocalValidation = JsonSchemaLocalValidation.YES,
+        ) =
             StructuredChatCompletionCreateParams.builder<T>()
                 .wrap(responseFormat, this, localValidation)
 

openai-java-core/src/main/kotlin/com/openai/models/chat/completions/StructuredChatCompletion.kt

@@ -10,9 +10,16 @@ import com.openai.models.completions.CompletionUsage
 import java.util.Objects
 import java.util.Optional
 
+/**
+ * A wrapper for [ChatCompletion] that provides type-safe access to the [choices] when using the
+ * _Structured Outputs_ feature to deserialize a JSON response to an instance of an arbitrary class.
+ * See the SDK documentation for more details on _Structured Outputs_.
+ *
+ * @param T The type of the class to which the JSON data in the response will be deserialized.
+ */
 class StructuredChatCompletion<T : Any>(
-    val responseFormat: Class<T>,
-    val chatCompletion: ChatCompletion,
+    @get:JvmName("responseFormat") val responseFormat: Class<T>,
+    @get:JvmName("chatCompletion") val chatCompletion: ChatCompletion,
 ) {
     /** @see ChatCompletion.id */
     fun id(): String = chatCompletion.id()
@@ -68,8 +75,8 @@ class StructuredChatCompletion<T : Any>(
 
     class Choice<T : Any>
     internal constructor(
-        internal val responseFormat: Class<T>,
-        internal val choice: ChatCompletion.Choice,
+        @get:JvmName("responseFormat") val responseFormat: Class<T>,
+        @get:JvmName("choice") val choice: ChatCompletion.Choice,
     ) {
         /** @see ChatCompletion.Choice.finishReason */
         fun finishReason(): FinishReason = choice.finishReason()

openai-java-core/src/main/kotlin/com/openai/models/chat/completions/StructuredChatCompletionCreateParams.kt

@@ -1,6 +1,7 @@
 package com.openai.models.chat.completions
 
 import com.openai.core.JsonField
+import com.openai.core.JsonSchemaLocalValidation
 import com.openai.core.JsonValue
 import com.openai.core.checkRequired
 import com.openai.core.fromClass
@@ -11,9 +12,18 @@ import com.openai.models.ReasoningEffort
 import java.util.Objects
 import java.util.Optional
 
+/**
+ * A wrapper for [ChatCompletionCreateParams] that provides a type-safe [Builder] that can record
+ * the type of the [responseFormat] used to derive a JSON schema from an arbitrary class when using
+ * the _Structured Outputs_ feature. When a JSON response is received, it is deserialized to am
+ * instance of that type. See the SDK documentation for more details on _Structured Outputs_.
+ *
+ * @param T The type of the class that will be used to derive the JSON schema in the request and to
+ *   which the JSON response will be deserialized.
+ */
 class StructuredChatCompletionCreateParams<T : Any>
 internal constructor(
-    val responseFormat: Class<T>,
+    @get:JvmName("responseFormat") val responseFormat: Class<T>,
     /**
      * The raw, underlying chat completion create parameters wrapped by this structured instance of
      * the parameters.
@@ -33,7 +43,7 @@ internal constructor(
         internal fun wrap(
             responseFormat: Class<T>,
             paramsBuilder: ChatCompletionCreateParams.Builder,
-            localValidation: Boolean,
+            localValidation: JsonSchemaLocalValidation,
         ) = apply {
             this.responseFormat = responseFormat
             this.paramsBuilder = paramsBuilder
@@ -396,7 +406,10 @@ internal constructor(
          * @see ChatCompletionCreateParams.Builder.responseFormat
          */
         @JvmOverloads
-        fun responseFormat(responseFormat: Class<T>, localValidation: Boolean = true) = apply {
+        fun responseFormat(
+            responseFormat: Class<T>,
+            localValidation: JsonSchemaLocalValidation = JsonSchemaLocalValidation.YES,
+        ) = apply {
             this.responseFormat = responseFormat
             paramsBuilder.responseFormat(fromClass(responseFormat, localValidation))
         }

openai-java-core/src/main/kotlin/com/openai/models/chat/completions/StructuredChatCompletionMessage.kt

@@ -7,10 +7,18 @@ import com.openai.models.chat.completions.ChatCompletionMessage.FunctionCall
 import java.util.Objects
 import java.util.Optional
 
+/**
+ * A wrapper for [ChatCompletionMessage] that provides type-safe access to the [content] when using
+ * the _Structured Outputs_ feature to deserialize a JSON response to an instance of an arbitrary
+ * class. See the SDK documentation for more details on _Structured Outputs_.
+ *
+ * @param T The type of the class to which the JSON data in the content will be deserialized when
+ *   [content] is called.
+ */
 class StructuredChatCompletionMessage<T : Any>
 internal constructor(
-    val responseFormat: Class<T>,
-    val chatCompletionMessage: ChatCompletionMessage,
+    @get:JvmName("responseFormat") val responseFormat: Class<T>,
+    @get:JvmName("chatCompletionMessage") val chatCompletionMessage: ChatCompletionMessage,
 ) {
 
     private val content: JsonField<T> by lazy {

openai-java-core/src/main/kotlin/com/openai/services/blocking/chat/ChatCompletionService.kt

@@ -58,12 +58,14 @@ interface ChatCompletionService {
     /** @see create */
     fun <T : Any> create(
         params: StructuredChatCompletionCreateParams<T>
+    ): StructuredChatCompletion<T> = create(params, RequestOptions.none())
+
+    /** @see create */
+    fun <T : Any> create(
+        params: StructuredChatCompletionCreateParams<T>,
+        requestOptions: RequestOptions = RequestOptions.none(),
     ): StructuredChatCompletion<T> =
-        StructuredChatCompletion<T>(
-            params.responseFormat,
-            // Normal, non-generic create method call via `ChatCompletionCreateParams`.
-            create(params.rawParams),
-        )
+        StructuredChatCompletion<T>(params.responseFormat, create(params.rawParams, requestOptions))
 
     /**
      * **Starting a new project?** We recommend trying