chore(docs): update readme (#58)

Author: stainless-app[bot]

README.md

@@ -61,6 +61,9 @@ OpenAIClient client = OpenAIOkHttpClient.builder()
 Alternately, set the environment with `OPENAI_API_KEY`, `OPENAI_ORG_ID` or `OPENAI_PROJECT_ID`, and use `OpenAIOkHttpClient.fromEnv()` to read from the environment.
 
 ```java
+import com.openai.client.OpenAIClient;
+import com.openai.client.okhttp.OpenAIOkHttpClient;
+
 OpenAIClient client = OpenAIOkHttpClient.fromEnv();
 
 // Note: you can also call fromEnv() from the client builder, for example if you need to set additional properties
@@ -82,12 +85,14 @@ Read the documentation for more configuration options.
 
 ### Example: creating a resource
 
-To create a new chat completion, first use the `ChatCompletionCreateParams` builder to specify attributes,
-then pass that to the `create` method of the `completions` service.
+To create a new chat completion, first use the `ChatCompletionCreateParams` builder to specify attributes, then pass that to the `create` method of the `completions` service.
 
 ```java
 import com.openai.models.ChatCompletion;
 import com.openai.models.ChatCompletionCreateParams;
+import com.openai.models.ChatCompletionMessageParam;
+import com.openai.models.ChatCompletionUserMessageParam;
+import com.openai.models.ChatModel;
 import java.util.List;
 
 ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
@@ -102,12 +107,11 @@ ChatCompletion chatCompletion = client.chat().completions().create(params);
 
 ### Example: listing resources
 
-The OpenAI API provides a `list` method to get a paginated list of jobs.
-You can retrieve the first page by:
+The OpenAI API provides a `list` method to get a paginated list of jobs. You can retrieve the first page by:
 
 ```java
 import com.openai.models.FineTuningJob;
-import com.openai.models.Page;
+import com.openai.models.FineTuningJobListPage;
 
 FineTuningJobListPage page = client.fineTuning().jobs().list();
 for (FineTuningJob job : page.data()) {
@@ -118,6 +122,9 @@ for (FineTuningJob job : page.data()) {
 Use the `FineTuningJobListParams` builder to set parameters:
 
 ```java
+import com.openai.models.FineTuningJobListPage;
+import com.openai.models.FineTuningJobListParams;
+
 FineTuningJobListParams params = FineTuningJobListParams.builder()
     .after("after")
     .limit(20L)
@@ -143,14 +150,14 @@ See [Pagination](#pagination) below for more information on transparently workin
 
 To make a request to the OpenAI API, you generally build an instance of the appropriate `Params` class.
 
-In [Example: creating a resource](#example-creating-a-resource) above, we used the `ChatCompletionCreateParams.builder()` to pass to
-the `create` method of the `completions` service.
+In [Example: creating a resource](#example-creating-a-resource) above, we used the `ChatCompletionCreateParams.builder()` to pass to the `create` method of the `completions` service.
 
-Sometimes, the API may support other properties that are not yet supported in the Java SDK types. In that case,
-you can attach them using the `putAdditionalProperty` method.
+Sometimes, the API may support other properties that are not yet supported in the Java SDK types. In that case, you can attach them using the `putAdditionalProperty` method.
 
 ```java
-import com.openai.models.core.JsonValue;
+import com.openai.core.JsonValue;
+import com.openai.models.ChatCompletionCreateParams;
+
 ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
     // ... normal properties
     .putAdditionalProperty("secret_param", JsonValue.from("4242"))
@@ -164,15 +171,19 @@ ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
 When receiving a response, the OpenAI Java SDK will deserialize it into instances of the typed model classes. In rare cases, the API may return a response property that doesn't match the expected Java type. If you directly access the mistaken property, the SDK will throw an unchecked `OpenAIInvalidDataException` at runtime. If you would prefer to check in advance that that response is completely well-typed, call `.validate()` on the returned model.
 
 ```java
+import com.openai.models.ChatCompletion;
+
 ChatCompletion chatCompletion = client.chat().completions().create().validate();
 ```
 
 ### Response properties as JSON
 
-In rare cases, you may want to access the underlying JSON value for a response property rather than using the typed version provided by
-this SDK. Each model property has a corresponding JSON version, with an underscore before the method name, which returns a `JsonField` value.
+In rare cases, you may want to access the underlying JSON value for a response property rather than using the typed version provided by this SDK. Each model property has a corresponding JSON version, with an underscore before the method name, which returns a `JsonField` value.
 
 ```java
+import com.openai.core.JsonField;
+import java.util.Optional;
+
 JsonField field = responseObj._field();
 
 if (field.isMissing()) {
@@ -194,24 +205,27 @@ if (field.isMissing()) {
 Sometimes, the server response may include additional properties that are not yet available in this library's types. You can access them using the model's `_additionalProperties` method:
 
 ```java
+import com.openai.core.JsonValue;
+
 JsonValue secret = errorObject._additionalProperties().get("secret_field");
 ```
 
 ---
 
 ## Pagination
 
-For methods that return a paginated list of results, this library provides convenient ways access
-the results either one page at a time, or item-by-item across all pages.
+For methods that return a paginated list of results, this library provides convenient ways access the results either one page at a time, or item-by-item across all pages.
 
 ### Auto-pagination
 
-To iterate through all results across all pages, you can use `autoPager`,
-which automatically handles fetching more pages for you:
+To iterate through all results across all pages, you can use `autoPager`, which automatically handles fetching more pages for you:
 
 ### Synchronous
 
 ```java
+import com.openai.models.FineTuningJob;
+import com.openai.models.FineTuningJobListPage;
+
 // As an Iterable:
 FineTuningJobListPage page = client.fineTuning().jobs().list(params);
 for (FineTuningJob job : page.autoPager()) {
@@ -234,12 +248,12 @@ asyncClient.fineTuning().jobs().list(params).autoPager()
 
 ### Manual pagination
 
-If none of the above helpers meet your needs, you can also manually request pages one-by-one.
-A page of results has a `data()` method to fetch the list of objects, as well as top-level
-`response` and other methods to fetch top-level data about the page. It also has methods
-`hasNextPage`, `getNextPage`, and `getNextPageParams` methods to help with pagination.
+If none of the above helpers meet your needs, you can also manually request pages one-by-one. A page of results has a `data()` method to fetch the list of objects, as well as top-level `response` and other methods to fetch top-level data about the page. It also has methods `hasNextPage`, `getNextPage`, and `getNextPageParams` methods to help with pagination.
 
 ```java
+import com.openai.models.FineTuningJob;
+import com.openai.models.FineTuningJobListPage;
+
 FineTuningJobListPage page = client.fineTuning().jobs().list(params);
 while (page != null) {
     for (FineTuningJob job : page.data()) {
@@ -258,22 +272,22 @@ This library throws exceptions in a single hierarchy for easy handling:
 
 - **`OpenAIException`** - Base exception for all exceptions
 
-  - **`OpenAIServiceException`** - HTTP errors with a well-formed response body we were able to parse. The exception message and the `.debuggingRequestId()` will be set by the server.
+- **`OpenAIServiceException`** - HTTP errors with a well-formed response body we were able to parse. The exception message and the `.debuggingRequestId()` will be set by the server.
 
-    | 400    | BadRequestException           |
-    | ------ | ----------------------------- |
-    | 401    | AuthenticationException       |
-    | 403    | PermissionDeniedException     |
-    | 404    | NotFoundException             |
-    | 422    | UnprocessableEntityException  |
-    | 429    | RateLimitException            |
-    | 5xx    | InternalServerException       |
-    | others | UnexpectedStatusCodeException |
+  | 400    | BadRequestException           |
+  | ------ | ----------------------------- |
+  | 401    | AuthenticationException       |
+  | 403    | PermissionDeniedException     |
+  | 404    | NotFoundException             |
+  | 422    | UnprocessableEntityException  |
+  | 429    | RateLimitException            |
+  | 5xx    | InternalServerException       |
+  | others | UnexpectedStatusCodeException |
 
-  - **`OpenAIIoException`** - I/O networking errors
-  - **`OpenAIInvalidDataException`** - any other exceptions on the client side, e.g.:
-    - We failed to serialize the request body
-    - We failed to parse the response body (has access to response code and body)
+- **`OpenAIIoException`** - I/O networking errors
+- **`OpenAIInvalidDataException`** - any other exceptions on the client side, e.g.:
+  - We failed to serialize the request body
+  - We failed to parse the response body (has access to response code and body)
 
 ## Microsoft Azure OpenAI
 
@@ -319,10 +333,12 @@ See the complete Azure OpenAI examples in the [Azure OpenAI example](https://git
 
 ### Retries
 
-Requests that experience certain errors are automatically retried 2 times by default, with a short exponential backoff. Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors will all be retried by default.
-You can provide a `maxRetries` on the client builder to configure this:
+Requests that experience certain errors are automatically retried 2 times by default, with a short exponential backoff. Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors will all be retried by default. You can provide a `maxRetries` on the client builder to configure this:
 
 ```java
+import com.openai.client.OpenAIClient;
+import com.openai.client.okhttp.OpenAIOkHttpClient;
+
 OpenAIClient client = OpenAIOkHttpClient.builder()
     .fromEnv()
     .maxRetries(4)
@@ -334,6 +350,10 @@ OpenAIClient client = OpenAIOkHttpClient.builder()
 Requests time out after 10 minutes by default. You can configure this on the client builder:
 
 ```java
+import com.openai.client.OpenAIClient;
+import com.openai.client.okhttp.OpenAIOkHttpClient;
+import java.time.Duration;
+
 OpenAIClient client = OpenAIOkHttpClient.builder()
     .fromEnv()
     .timeout(Duration.ofSeconds(30))
@@ -345,24 +365,24 @@ OpenAIClient client = OpenAIOkHttpClient.builder()
 Requests can be routed through a proxy. You can configure this on the client builder:
 
 ```java
+import com.openai.client.OpenAIClient;
+import com.openai.client.okhttp.OpenAIOkHttpClient;
+import java.net.InetSocketAddress;
+import java.net.Proxy;
+
 OpenAIClient client = OpenAIOkHttpClient.builder()
     .fromEnv()
-    .proxy(new Proxy(
-        Type.HTTP,
-        new InetSocketAddress("proxy.com", 8080)
-    ))
+    .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("example.com", 8080)))
     .build();
 ```
 
 ## Making custom/undocumented requests
 
-This library is typed for convenient access to the documented API. If you need to access undocumented
-params or response properties, the library can still be used.
+This library is typed for convenient access to the documented API. If you need to access undocumented params or response properties, the library can still be used.
 
 ### Undocumented request params
 
-To make requests using undocumented parameters, you can provide or override parameters on the params object
-while building it.
+To make requests using undocumented parameters, you can provide or override parameters on the params object while building it.
 
 ```kotlin
 FooCreateParams address = FooCreateParams.builder()
@@ -373,10 +393,7 @@ FooCreateParams address = FooCreateParams.builder()
 
 ### Undocumented response properties
 
-To access undocumented response properties, you can use `res._additionalProperties()` on a response object to
-get a map of untyped fields of type `Map<String, JsonValue>`. You can then access fields like
-`._additionalProperties().get("secret_prop").asString()` or use other helpers defined on the `JsonValue` class
-to extract it to a desired type.
+To access undocumented response properties, you can use `res._additionalProperties()` on a response object to get a map of untyped fields of type `Map<String, JsonValue>`. You can then access fields like `._additionalProperties().get("secret_prop").asString()` or use other helpers defined on the `JsonValue` class to extract it to a desired type.
 
 ## Logging