### Run an Example from Source

Source: https://github.com/openai/openai-java/blob/main/CONTRIBUTING.md

This command demonstrates how to execute a specific example class from the `openai-java-example` module using Gradle. Ensure the example class is correctly defined.

```sh
$ ./gradlew :openai-java-example:run -PmainClass=com.openai.example.YourExample
```

--------------------------------

### Create a New Example Class

Source: https://github.com/openai/openai-java/blob/main/CONTRIBUTING.md

This Java code snippet shows the basic structure for creating a new example class within the `openai-java-example` directory. It serves as a starting point for adding custom examples.

```java
package com.openai.example;

public class YourExample {
    public static void main(String[] args) {
        // ...
    }
}
```

--------------------------------

### Manually Start Mock Server

Source: https://github.com/openai/openai-java/blob/main/CONTRIBUTING.md

Manually start the mock server to run tests repeatedly against it.

```sh
./scripts/mock
```

--------------------------------

### Basic Workload Identity Setup

Source: https://github.com/openai/openai-java/blob/main/README.md

Configure the OpenAI client with workload identity using a Kubernetes service account token provider. Ensure necessary imports are included.

```java
import com.openai.auth.*;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;

SubjectTokenProvider provider = K8sServiceAccountTokenProvider.builder().build();

WorkloadIdentity workloadIdentity = WorkloadIdentity.builder() 
    .identityProviderId("your-identity-provider-id")
    .serviceAccountId("your-service-account-id")
    .provider(provider)
    .build();

OpenAIClient client = OpenAIOkHttpClient.builder()
    .workloadIdentity(workloadIdentity)
    .build();
```

--------------------------------

### Run Tests with Mock Server

Source: https://github.com/openai/openai-java/blob/main/CONTRIBUTING.md

Execute tests using the provided script, which automatically starts the mock server if not already running.

```sh
./scripts/test
```

--------------------------------

### Iterate Through Paginated Jobs

Source: https://github.com/openai/openai-java/blob/main/_autodocs/types.md

Demonstrates how to list and iterate through paginated fine-tuning jobs using the ListPage type. Includes examples for fetching the next page and using an auto-pager.

```java
JobListPage page = client.fineTuning().jobs().list();

for (FineTuningJob job : page.items()) {
    System.out.println(job.id());
}

if (page.hasNextPage()) {
    JobListPage nextPage = page.nextPage();
}

// Or auto-paginate
for (FineTuningJob job : page.autoPager()) {
    System.out.println(job.id());
}
```

--------------------------------

### Asynchronous Streaming Chat Completions (Basic)

Source: https://github.com/openai/openai-java/blob/main/README.md

Subscribe to chat completion chunks using an asynchronous client. This basic example prints each chunk as it is received.

```java
import com.openai.core.http.AsyncStreamResponse;
import com.openai.models.chat.completions.ChatCompletionChunk;
import java.util.Optional;

client.async().chat().completions().createStreaming(params).subscribe(chunk -> {
    System.out.println(chunk);
});
```

--------------------------------

### Implementing Function Calling with Chat Completions

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/chat-completions.md

Shows how to define a Java class to represent a tool (function) that the model can call. It then demonstrates how to build Chat Completion parameters to include this tool and process the model's response to invoke the tool and get results.

```java
class GetWeather {
    public String location;
    
    public String execute() {
        return "Sunny, 72°F in " + location;
    }
}

ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
    .model(ChatModel.GPT_4O)
    .addTool(GetWeather.class)
    .addUserMessage("What's the weather in San Francisco?")
    .build();

ChatCompletion response = client.chat().completions().create(params);

response.choices().stream()
    .flatMap(choice -> choice.message().toolCalls().stream())
    .flatMap(List::stream)
    .forEach(toolCall -> {
        if ("GetWeather".equals(toolCall.function().name())) {
            GetWeather weather = toolCall.function()
                .arguments(GetWeather.class);
            String result = weather.execute();
            System.out.println(result);
        }
    });
```

--------------------------------

### Build Chat Completion Parameters with Multiple Messages

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/chat-completions.md

This example shows how to construct ChatCompletionCreateParams with multiple messages, including user, assistant, and system messages, to form a conversation history.

```java
ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
    .model(ChatModel.GPT_4O)
    .addUserMessage("What's 2 + 2?")
    .addAssistantMessage("2 + 2 = 4")
    .addUserMessage("Can you explain why?")
    .addSystemMessage("You are a helpful math tutor.")
    .build();
```

--------------------------------

### Global Client Configuration for Async Streaming Executor

Source: https://github.com/openai/openai-java/blob/main/README.md

Configure the `Executor` for all asynchronous streaming operations globally when building the `OpenAIClient`. This simplifies setup for applications with consistent threading needs.

```java
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import java.util.concurrent.Executors;

OpenAIClient client = OpenAIOkHttpClient.builder()
    .fromEnv()
    .streamHandlerExecutor(Executors.newFixedThreadPool(4))
    .build();
```

--------------------------------

### Initialize OpenAI Client from Environment Variables

Source: https://github.com/openai/openai-java/blob/main/_autodocs/client-initialization.md

Create an OpenAI client instance by reading configuration from environment variables. This is a common way to manage credentials and settings without hardcoding them.

```java
OpenAIClient client = OpenAIOkHttpClient.fromEnv();

// Reuse for all API calls
client.chat().completions().create(params1);
client.chat().completions().create(params2);

// Close when shutting down (optional but recommended for resource-intensive applications)
client.close();
```

--------------------------------

### List and Paginate Files

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/files.md

Demonstrates how to list files for fine-tuning, access items on the current page, and paginate through all files using auto-pagination or manual pagination.

```java
// List all files for fine-tuning
FileListPage page = client.files().list(FileListParams.builder()
    .purpose(FilePurpose.FINE_TUNE)
    .build());

// Access current page items
page.items().forEach(file -> {
    System.out.println(file.id() + ": " + file.filename());
});

// Auto-paginate through all files
page.autoPager().forEach(file -> {
    System.out.println(file.id());
});

// Manual pagination
while (true) {
    for (FileObject file : page.items()) {
        process(file);
    }
    
    if (!page.hasNextPage()) break;
    page = page.nextPage();
}
```

--------------------------------

### Access Undocumented Response Properties

Source: https://github.com/openai/openai-java/blob/main/README.md

Use `_additionalProperties()` to get a map of all properties in the response, including undocumented ones. Access specific properties using `get()` and handle different JSON types with a visitor pattern.

```java
import com.openai.core.JsonValue;
import java.util.Map;

Map<String, JsonValue> additionalProperties = client.chat().completions().create(params)._additionalProperties();
JsonValue secretPropertyValue = additionalProperties.get("secretProperty");

String result = secretPropertyValue.accept(new JsonValue.Visitor<>() {
    @Override
    public String visitNull() {
        return "It's null!";
    }

    @Override
    public String visitBoolean(boolean value) {
        return "It's a boolean!";
    }

    @Override
    public String visitNumber(Number value) {
        return "It's a number!";
    }

    // Other methods include `visitMissing`, `visitString`, `visitArray`, and `visitObject`
    // The default implementation of each unimplemented method delegates to `visitDefault`, which throws by default, but can also be overridden
});
```

--------------------------------

### EmbeddingCreateParams with Multiple String Inputs

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/embeddings.md

Example of creating an embedding request with a list of strings as input.

```java
// Multiple strings
EmbeddingCreateParams params2 = EmbeddingCreateParams.builder()
    .input(List.of(
        "First text",
        "Second text",
        "Third text"
    ))
    .model("text-embedding-3-small")
    .build();
```

--------------------------------

### EmbeddingCreateParams with Single String Input

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/embeddings.md

Example of creating an embedding request with a single string as input.

```java
// Single string input
EmbeddingCreateParams params1 = EmbeddingCreateParams.builder()
    .input("Single text")
    .model("text-embedding-3-small")
    .build();
```

--------------------------------

### Configure Client with Environment Variables and Manual Settings

Source: https://github.com/openai/openai-java/blob/main/README.md

Combine environment variable configuration with manual settings. This allows for default configurations via environment variables while overriding specific ones manually.

```java
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;

OpenAIClient client = OpenAIOkHttpClient.builder()
    // Configures using the `openai.apiKey`, `openai.adminKey`, `openai.orgId`, `openai.projectId`, `openai.webhookSecret` and `openai.baseUrl` system properties
    // Or configures using the `OPENAI_API_KEY`, `OPENAI_ADMIN_KEY`, `OPENAI_ORG_ID`, `OPENAI_PROJECT_ID`, `OPENAI_WEBHOOK_SECRET` and `OPENAI_BASE_URL` environment variables
    .fromEnv()
    .apiKey("My API Key")
    .build();
```

--------------------------------

### Retrieve File Information

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/files.md

Get metadata for a specific uploaded file using its file ID.

```java
FileObject file = client.files().retrieve(FileRetrieveParams.builder()
    .fileId("file_abc123")
    .build());

System.out.println("Status: " + file.status().orElse("unknown"));
System.out.println("Created: " + new Date(file.createdAt() * 1000));
```

--------------------------------

### Upload File for Fine-tuning

Source: https://github.com/openai/openai-java/blob/main/_autodocs/README.md

Demonstrates how to upload a file, such as training data in JSONL format, for fine-tuning a model. Specify the file path and the purpose. Ensure the client is initialized.

```java
FileCreateParams params = FileCreateParams.builder()
    .file(Paths.get("training_data.jsonl"))
    .purpose(FilePurpose.FINE_TUNE)
    .build();

FileObject file = client.files().create(params);
System.out.println("Uploaded: " + file.id());
```

--------------------------------

### Initialize Asynchronous OpenAI Client from Environment Variables

Source: https://github.com/openai/openai-java/blob/main/_autodocs/client-initialization.md

Initialize the asynchronous client using environment variables for API keys and other configurations.

```java
// Using environment variables
OpenAIClientAsync client = OpenAIOkHttpClientAsync.fromEnv();
```

--------------------------------

### Get Binary File Content

Source: https://github.com/openai/openai-java/blob/main/README.md

Retrieve binary content of a file using its ID. This method returns an HttpResponse object.

```java
import com.openai.core.http.HttpResponse;
import com.openai.models.files.FileContentParams;

HttpResponse response = client.files().content("file_id");
```

--------------------------------

### ChatCompletionChunk (Streaming)

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/chat-completions.md

This section explains how to handle streaming chat completion responses, providing a Java example for processing chunks as they arrive.

```APIDOC
## ChatCompletionChunk (Streaming)

Represents a single chunk in a streaming response.

### Key Properties

This example shows how to process a streaming response from the chat completion API.

```java
StreamResponse<ChatCompletionChunk> stream = 
    client.chat().completions().createStreaming(params);

stream.stream().forEach(chunk -> {
    chunk.choices().forEach(choice -> {
        Delta delta = choice.delta();
        Optional<String> content = delta.content();
        String finishReason = choice.finishReason();
        
        if (content.isPresent()) {
            System.out.print(content.get());
        }
    });
});
```
```

--------------------------------

### Configure Client from Environment Variables

Source: https://github.com/openai/openai-java/blob/main/README.md

Use this snippet to configure the client by reading API keys and other settings from environment variables. This is useful for deployment environments.

```java
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;

// Configures using the `openai.apiKey`, `openai.adminKey`, `openai.orgId`, `openai.projectId`, `openai.webhookSecret` and `openai.baseUrl` system properties
// Or configures using the `OPENAI_API_KEY`, `OPENAI_ADMIN_KEY`, `OPENAI_ORG_ID`, `OPENAI_PROJECT_ID`, `OPENAI_WEBHOOK_SECRET` and `OPENAI_BASE_URL` environment variables
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
```

--------------------------------

### Responses API Streaming

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/streaming.md

Shows how to stream responses from the Responses API using `StreamResponse`. This example processes output text deltas.

```java
ResponseCreateParams params = ResponseCreateParams.builder()
    .model(ResponsesModel.GPT_5_2_PRO)
    .input("Write a poem")
    .stream(true)
    .build();

try (StreamResponse<ResponseStreamEvent> stream = 
         client.responses().createStreaming(params)) {
    
    stream.stream().forEach(event -> {
        if (event.isOutputTextDelta()) {
            OutputTextDeltaEvent textEvent = event.asOutputTextDelta();
            System.out.print(textEvent.delta());
        }
    });
}
```

--------------------------------

### Initialize OpenAI Client and File Service

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/files.md

Access the FileService by initializing an OpenAIClient from environment variables.

```java
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
FileService fileService = client.files();
```

--------------------------------

### ChatCompletion Response

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/chat-completions.md

This section describes the structure of a standard chat completion response and provides a Java code example for accessing its key properties.

```APIDOC
## ChatCompletion Response

The response object from a completion request.

### Key Properties

This example demonstrates how to retrieve and use the response from a chat completion.

```java
ChatCompletion completion = client.chat().completions().create(params);

String id = completion.id();                    // Completion ID
String model = completion.model();              // Model used
long createdAt = completion.created();          // Unix timestamp
int inputTokens = completion.usage().promptTokens();
int outputTokens = completion.usage().completionTokens();

List<Choice> choices = completion.choices();
choices.forEach(choice -> {
    String content = choice.message().content().orElse("");
    String finishReason = choice.finishReason();
    System.out.println("Content: " + content);
    System.out.println("Finish reason: " + finishReason);
});
```
```

--------------------------------

### Initialize Synchronous OpenAI Client from Environment Variables

Source: https://github.com/openai/openai-java/blob/main/_autodocs/client-initialization.md

Use this method to initialize the synchronous client when API keys and other configurations are set as environment variables.

```java
// Using environment variables (OPENAI_API_KEY, OPENAI_ORG_ID, OPENAI_PROJECT_ID, etc.)
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
```

--------------------------------

### Configure Azure OpenAI Client (Java)

Source: https://github.com/openai/openai-java/blob/main/_autodocs/README.md

Set up the OpenAI client to work with Azure OpenAI by providing credentials and the base URL. Uses DefaultAzureCredential for authentication.

```java
OpenAIClient client = OpenAIOkHttpClient.builder()
    .credential(BearerTokenCredential.create(
        AuthenticationUtil.getBearerTokenSupplier(
            new DefaultAzureCredentialBuilder().build(),
            "https://cognitiveservices.azure.com/.default")))
    .baseUrl("https://your-resource.openai.azure.com")
    .build();
```

--------------------------------

### Function Calling

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/chat-completions.md

This section details how to enable and utilize function calling with chat completions, allowing the model to invoke external functions. Includes a Java example.

```APIDOC
## Function Calling

Define and call external functions through the model:

### Example

This example demonstrates setting up a `GetWeather` function and calling it via the chat completion API.

```java
class GetWeather {
    public String location;
    
    public String execute() {
        return "Sunny, 72°F in " + location;
    }
}

ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
    .model(ChatModel.GPT_4O)
    .addTool(GetWeather.class)
    .addUserMessage("What's the weather in San Francisco?")
    .build();

ChatCompletion response = client.chat().completions().create(params);

response.choices().stream()
    .flatMap(choice -> choice.message().toolCalls().stream())
    .flatMap(List::stream)
    .forEach(toolCall -> {
        if ("GetWeather".equals(toolCall.function().name())) {
            GetWeather weather = toolCall.function()
                .arguments(GetWeather.class);
            String result = weather.execute();
            System.out.println(result);
        }
    });
```
```

--------------------------------

### Initialize and Use OpenAI Client

Source: https://github.com/openai/openai-java/blob/main/_autodocs/README.md

Create a single client instance for your application and reuse it. The client can be closed when shutting down, though it also offers auto-cleanup after idle time.

```java
OpenAIClient client = OpenAIOkHttpClient.fromEnv();

// Use throughout application
ChatCompletion response = client.chat().completions().create(params);

// Close when shutting down (optional, auto-cleanup after idle time)
client.close();
```

--------------------------------

### List Files with Pagination

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/files.md

Demonstrates how to list files, filter by purpose, and paginate through the results using both auto-pagination and manual pagination.

```APIDOC
## List Files with Pagination

### Description
Lists all files associated with fine-tuning jobs and provides examples for accessing paginated results.

### Method
`client.files().list(params)`

### Parameters
#### Query Parameters
- **purpose** (FilePurpose) - Required - The purpose of the files to list (e.g., `FilePurpose.FINE_TUNE`).

### Response
#### Success Response
- **FileListPage** - An object containing a list of `FileObject` and pagination information.
  - **items** (List<FileObject>) - The list of files in the current page.
  - **hasNextPage** (boolean) - Indicates if there is a next page of results.
  - **nextPage()** - Method to retrieve the next page of results.
  - **autoPager()** - An iterable to automatically paginate through all files.
```

--------------------------------

### Initialize Asynchronous OpenAI Client with Custom Configuration

Source: https://github.com/openai/openai-java/blob/main/_autodocs/client-initialization.md

Initialize the asynchronous client using a builder pattern to set a custom API key.

```java
// Using builder
OpenAIClientAsync client = OpenAIOkHttpClientAsync.builder()
    .apiKey("your-api-key")
    .build();
```

--------------------------------

### Modify Client Configuration Temporarily

Source: https://github.com/openai/openai-java/blob/main/README.md

Use `withOptions()` to create a client with modified settings without affecting the original client. This is useful for temporary configuration changes like setting a different base URL or max retries.

```java
import com.openai.client.OpenAIClient;

OpenAIClient clientWithOptions = client.withOptions(optionsBuilder -> {
    optionsBuilder.baseUrl("https://example.com");
    optionsBuilder.maxRetries(42);
});
```

--------------------------------

### Wait for Streaming Completion

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/streaming.md

Starts a streaming API call and blocks until the entire stream has been received and processed. This pattern is suitable when the subsequent logic depends on the complete stream data.

```java
CompletableFuture<Void> done = asyncClient.chat().completions()
    .createStreaming(params)
    .subscribe(chunk -> System.out.println(chunk))
    .onCompleteFuture();

// Block until complete
done.join();
```

--------------------------------

### Build All Modules

Source: https://github.com/openai/openai-java/blob/main/CONTRIBUTING.md

Build all modules of the project using Gradle.

```sh
./gradlew build
```

--------------------------------

### Annotation Precedence: Jackson vs. Swagger

Source: https://github.com/openai/openai-java/blob/main/README.md

When both Jackson and Swagger annotations are applied to the same schema field, Jackson annotations take precedence. This example shows that the description for 'myProperty' will be set by @JsonPropertyDescription.

```java
import com.fasterxml.jackson.annotation.JsonPropertyDescription;
import io.swagger.v3.oas.annotations.media.Schema;

class MyObject {
    @Schema(description = "Swagger description")
    @JsonPropertyDescription("Jackson description")
    public String myProperty;
}
```

--------------------------------

### Azure OpenAI Integration with Bearer Token

Source: https://github.com/openai/openai-java/blob/main/_autodocs/client-initialization.md

Integrate the OpenAI client with Azure OpenAI services using a Bearer Token credential. This example demonstrates obtaining a token using Azure's DefaultAzureCredentialBuilder.

```java
OpenAIClient client = OpenAIOkHttpClient.builder()
    .fromEnv()
    .credential(BearerTokenCredential.create(
        AuthenticationUtil.getBearerTokenSupplier(
            new DefaultAzureCredentialBuilder().build(),
            "https://cognitiveservices.azure.com/.default"
        )
    ))
    .build();
```

--------------------------------

### Build File Creation Request Parameters

Source: https://github.com/openai/openai-java/blob/main/_autodocs/types.md

Shows how to construct parameters for file upload requests, specifying the file path and purpose.

```java
FileCreateParams params = FileCreateParams.builder()
    .file(Paths.get("file.jsonl"))
    .purpose(FilePurpose.FINE_TUNE)
    .build();
```

--------------------------------

### Access Raw JSON Value of a Property

Source: https://github.com/openai/openai-java/blob/main/README.md

Use `_` prefixed methods to get a `JsonField` object representing the raw JSON value of a property. This allows checking for missing or null values, and deserializing into custom types.

```java
import com.openai.core.JsonField;
import com.openai.models.chat.completions.ChatCompletionMessageParam;
import java.util.Optional;

JsonField<List<ChatCompletionMessageParam>> messages = client.chat().completions().create(params)._messages();

if (messages.isMissing()) {
  // The property is absent from the JSON response
} else if (messages.isNull()) {
  // The property was set to literal null
} else {
  // Check if value was provided as a string
  // Other methods include `asNumber()`, `asBoolean()`, etc.
  Optional<String> jsonString = messages.asString();

  // Try to deserialize into a custom type
  MyClass myObject = messages.asUnknown().orElseThrow().convert(MyClass.class);
}
```

--------------------------------

### Initialize Synchronous OpenAI Client with Custom Configuration

Source: https://github.com/openai/openai-java/blob/main/_autodocs/client-initialization.md

Initialize the synchronous client using a builder pattern to specify custom API keys, organization IDs, base URLs, and network settings.

```java
// Using builder with custom configuration
OpenAIClient client = OpenAIOkHttpClient.builder()
    .apiKey("your-api-key")
    .organization("your-org-id")
    .project("your-project-id")
    .baseUrl("https://api.openai.com/v1")
    .maxRetries(3)
    .timeout(Duration.ofSeconds(30))
    .build();
```

--------------------------------

### Accessing ChatCompletion Response Properties

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/chat-completions.md

Demonstrates how to access key properties from a standard ChatCompletion response object, such as ID, model, creation timestamp, and token usage. It also shows how to iterate through choices to get content and finish reasons.

```java
ChatCompletion completion = client.chat().completions().create(params);

String id = completion.id();                    // Completion ID
String model = completion.model();              // Model used
long createdAt = completion.created();          // Unix timestamp
int inputTokens = completion.usage().promptTokens();
int outputTokens = completion.usage().completionTokens();

List<Choice> choices = completion.choices();
choices.forEach(choice -> {
    String content = choice.message().content().orElse("");
    String finishReason = choice.finishReason();
    System.out.println("Content: " + content);
    System.out.println("Finish reason: " + finishReason);
});
```

--------------------------------

### List Available Gradle Tasks

Source: https://github.com/openai/openai-java/blob/main/CONTRIBUTING.md

Use this command to see all the Gradle tasks that can be executed for the project. This is useful for understanding the available development workflows.

```sh
./gradlew tasks
```

--------------------------------

### Chat Completions with Function Calling

Source: https://github.com/openai/openai-java/blob/main/README.md

Demonstrates how to use function calling with chat completions. It includes setting up tools, making a request, processing tool calls, and handling follow-up questions.

```java
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.ChatModel;
import com.openai.models.chat.completions.*;
import java.util.Collection;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();

ChatCompletionCreateParams.Builder createParamsBuilder = ChatCompletionCreateParams.builder()
        .model(ChatModel.GPT_3_5_TURBO)
        .maxCompletionTokens(2048)
        .addTool(GetSdkQuality.class)
        .addTool(GetSdkScore.class)
        .addUserMessage("How good are the following SDKs and what do reviewers say: "
                + "OpenAI Java SDK, Unknown Company SDK.");

client.chat().completions().create(createParamsBuilder.build()).choices().stream()
        .map(ChatCompletion.Choice::message)
        // Add each assistant message onto the builder so that we keep track of the
        // conversation for asking a follow-up question later.
        .peek(createParamsBuilder::addMessage)
        .flatMap(message -> {
            message.content().ifPresent(System.out::println);
            return message.toolCalls().stream().flatMap(Collection::stream);
        })
        .forEach(toolCall -> {
            Object result = callFunction(toolCall.function());
            // Add the tool call result to the conversation.
            createParamsBuilder.addMessage(ChatCompletionToolMessageParam.builder()
                    .toolCallId(toolCall.id())
                    .contentAsJson(result)
                    .build());
        });

// Ask a follow-up question about the function call result.
createParamsBuilder.addUserMessage("Why do you say that?");
client.chat().completions().create(createParamsBuilder.build()).choices().stream()
        .flatMap(choice -> choice.message().content().stream())
        .forEach(System.out::println);

static Object callFunction(ChatCompletionMessageToolCall.Function function) {
  switch (function.name()) {
    case "GetSdkQuality":
      return function.arguments(GetSdkQuality.class).execute();
    case "GetSdkScore":
      return function.arguments(GetSdkScore.class).execute();
    default:
      throw new IllegalArgumentException("Unknown function: " + function.name());
  }
}
```

--------------------------------

### Basic Async Streaming Chat Completion

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/streaming.md

Demonstrates how to initiate an asynchronous streaming chat completion and process the chunks as they arrive. Ensure the client is initialized and parameters are set for streaming.

```java
OpenAIClientAsync asyncClient = OpenAIOkHttpClientAsync.fromEnv();

ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
    .model(ChatModel.GPT_4O)
    .addUserMessage("Write a haiku")
    .stream(true)
    .build();

asyncClient.chat().completions()
    .createStreaming(params)
    .subscribe(chunk -> {
        chunk.choices().forEach(choice -> {
            System.out.print(choice.delta().content().orElse(""));
        });
    });
```

--------------------------------

### Build Chat Completion Request Parameters

Source: https://github.com/openai/openai-java/blob/main/_autodocs/types.md

Demonstrates how to construct parameters for chat completion requests using the builder pattern.

```java
ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
    .model(ChatModel.GPT_4O)
    .addUserMessage("text")
    .addAssistantMessage("text")
    .addSystemMessage("text")
    .messages(messagesList)
    .temperature(0.7f)
    .topP(0.9f)
    .frequencyPenalty(0.0f)
    .presencePenalty(0.0f)
    .maxCompletionTokens(1000)
    .stopSequences(Arrays.asList("END"))
    .stream(false)
    .responseFormat(ChatCompletionCreateParams.ResponseFormat.builder()
        .jsonObject(ChatCompletionCreateParams.ResponseFormat.JsonObject.builder().build())
        .build())
    .build();
```

--------------------------------

### Show Dependency Tree with Gradle

Source: https://github.com/openai/openai-java/blob/main/CONTRIBUTING.md

Displays the dependency tree for the project. This helps in understanding transitive dependencies and identifying potential conflicts.

```sh
./gradlew dependencies
```

--------------------------------

### Upload a File for Fine-tuning

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/files.md

Upload a local file to OpenAI for fine-tuning purposes. Ensure the file is in the correct format (e.g., .jsonl).

```java
FileCreateParams params = FileCreateParams.builder()
    .file(Paths.get("training_data.jsonl"))
    .purpose(FilePurpose.FINE_TUNE)
    .build();

FileObject file = client.files().create(params);
System.out.println("File ID: " + file.id());
System.out.println("Filename: " + file.filename());
System.out.println("Size: " + file.bytes() + " bytes");
```

--------------------------------

### Implement the Function Calling Flow

Source: https://github.com/openai/openai-java/blob/main/_autodocs/advanced-features.md

This snippet demonstrates the complete flow of function calling: creating parameters, sending a request, checking for tool calls, parsing arguments, executing the function, and continuing the conversation with the result.

```java
ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
    .model(ChatModel.GPT_4O)
    .addTool(GetWeather.class)
    .addUserMessage("What's the weather in San Francisco?")
    .build();

ChatCompletion response = client.chat().completions().create(params);

// Check if model requested function call
response.choices().stream()
    .flatMap(choice -> choice.message().toolCalls().stream())
    .flatMap(List::stream)
    .forEach(toolCall -> {
        // Parse arguments into function object
        GetWeather weather = toolCall.function()
            .arguments(GetWeather.class);
        
        // Execute function
        String result = weather.execute();
        
        // Continue conversation with result
        ChatCompletionCreateParams followUp = params.toBuilder()
            .addMessage(response.choices().get(0).message())
            .addMessage(ChatCompletionToolMessageParam.builder()
                .toolCallId(toolCall.id())
                .content(result)
                .build())
            .build();
        
        ChatCompletion finalResponse = client.chat() 
            .completions()
            .create(followUp);
        
        System.out.println("Final response: " + 
            finalResponse.choices().get(0).message().content());
    });
```

--------------------------------

### Asynchronous File Upload

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/files.md

Shows how to asynchronously upload a file for fine-tuning using the `OpenAIOkHttpClientAsync` client. It includes handling the upload completion or failure via `CompletableFuture`.

```java
OpenAIOpenAIOkHttpClientAsync asyncClient = OpenAIOkHttpClientAsync.fromEnv();

FileCreateParams params = FileCreateParams.builder()
    .file(Paths.get("data.jsonl"))
    .purpose(FilePurpose.FINE_TUNE)
    .build();

CompletableFuture<FileObject> future = asyncClient.files().create(params);

future.thenAccept(file -> {
    System.out.println("Uploaded: " + file.id());
}).exceptionally(e -> {
    System.err.println("Upload failed: " + e.getMessage());
    return null;
});
```

--------------------------------

### Build Chat Completion Parameters

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/chat-completions.md

This snippet demonstrates how to build the parameters for creating a chat completion using the builder pattern. It sets the model, user message, temperature, and max completion tokens.

```java
ChatCompletionCreateParams.Builder builder = ChatCompletionCreateParams.builder()
    .model(ChatModel.GPT_4O)
    .addUserMessage("Your message here")
    .temperature(0.7f)
    .maxCompletionTokens(1000)
    .build();
```

--------------------------------

### Run Project Tests with Gradle

Source: https://github.com/openai/openai-java/blob/main/CONTRIBUTING.md

This command runs all the unit and integration tests defined for the project. It's crucial for verifying code correctness.

```sh
./gradlew test
```

--------------------------------

### Format Code with Gradle

Source: https://github.com/openai/openai-java/blob/main/CONTRIBUTING.md

Applies code formatting rules to the entire project using Spotless. This ensures consistent code style across the codebase.

```sh
./gradlew spotlessApply
```

--------------------------------

### Basic Chat Completion

Source: https://github.com/openai/openai-java/blob/main/_autodocs/README.md

Demonstrates how to perform a basic chat completion request and print the response content. Ensure the OpenAI client is initialized.

```java
OpenAIClient client = OpenAIOkHttpClient.fromEnv();

ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
    .model(ChatModel.GPT_4O_MINI)
    .addUserMessage("What is 2 + 2?")
    .build();

ChatCompletion response = client.chat().completions().create(params);
System.out.println(response.choices().get(0).message().content());
```

--------------------------------

### Add OpenAI Spring Boot Starter Dependency (Gradle)

Source: https://github.com/openai/openai-java/blob/main/README.md

Include the OpenAI Java Spring Boot starter in your Gradle project to simplify configuration.

```kotlin
implementation("com.openai:openai-java-spring-boot-starter:4.41.0")
```

--------------------------------

### Configure OpenAI Properties in application.yml

Source: https://github.com/openai/openai-java/blob/main/README.md

Configure OpenAI API key, base URL, and other client options using YAML syntax in `application.yml`.

```yaml
openai:
  base-url: https://api.openai.com/v1
  api-key: My API Key
  admin-key: My Admin API Key
  org-id: My Organization
  project-id: My Project
  webhook-secret: My Webhook Secret
```

--------------------------------

### Stream Resource Management

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/streaming.md

Illustrates proper stream resource management using try-with-resources or manual closing with a finally block.

```java
// Good - uses try-with-resources
try (StreamResponse<ChatCompletionChunk> stream = 
         client.chat().completions().createStreaming(params)) {
    stream.stream().forEach(chunk -> process(chunk));
}

// Also good - manual close
StreamResponse<ChatCompletionChunk> stream = 
    client.chat().completions().createStreaming(params);
try {
    stream.stream().forEach(chunk -> process(chunk));
} finally {
    stream.close();
}
```

--------------------------------

### Check Formatting with Gradle

Source: https://github.com/openai/openai-java/blob/main/CONTRIBUTING.md

Use Gradle to directly check code formatting.

```sh
./gradlew spotlessCheck  # Check formatting
```

--------------------------------

### Spring Boot Starter Dependency for OpenAI Java

Source: https://github.com/openai/openai-java/blob/main/_autodocs/DOCUMENTATION_INDEX.md

Use this dependency in your Spring Boot application to easily integrate the OpenAI Java client.

```xml
<dependency>
    <groupId>com.openai</groupId>
    <artifactId>openai-java-spring-boot-starter</artifactId>
    <version>4.41.0</version>
</dependency>
```

--------------------------------

### Configure OkHttp Connection Pooling for OpenAI Client

Source: https://github.com/openai/openai-java/blob/main/_autodocs/client-initialization.md

Shows how to configure OkHttp's connection pooling settings, such as maximum idle connections and keep-alive duration, for improved performance.

```java
OpenAIClient client = OpenAIOkHttpClient.builder()
    .maxIdleConnections(5)
    .keepAliveDuration(Duration.ofMinutes(2))
    .build();
```

--------------------------------

### Instantiate ChatModel Enum

Source: https://github.com/openai/openai-java/blob/main/_autodocs/types.md

Shows how to instantiate specific chat models from the `ChatModel` enum.

```java
ChatModel model = ChatModel.GPT_4O;
ChatModel modelMini = ChatModel.GPT_4O_MINI;
```

--------------------------------

### Async File Upload

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/files.md

Shows how to asynchronously upload a file for fine-tuning using the async client and handle the response or errors.

```APIDOC
## Async File Upload

### Description
Uploads a file asynchronously and handles the completion or failure of the upload operation.

### Method
`asyncClient.files().create(params)`

### Parameters
#### Request Body
- **params** (FileCreateParams) - Required - Parameters for file creation.
  - **file** (Path) - Required - The path to the file to upload.
  - **purpose** (FilePurpose) - Required - The purpose of the file (e.g., `FilePurpose.FINE_TUNE`).

### Response
#### Success Response
- **CompletableFuture<FileObject>** - A future that completes with the uploaded `FileObject` upon success.
  - **id** (string) - The ID of the uploaded file.
  - **filename** (string) - The name of the uploaded file.

#### Error Handling
- **exceptionally** - Handles any exceptions that occur during the asynchronous upload process.
```

--------------------------------

### Build Project JARs

Source: https://github.com/openai/openai-java/blob/main/CONTRIBUTING.md

This command builds the entire OpenAI Java project, generating JAR files for each module. These JAR files can be found in their respective module's `build/libs/` directory.

```sh
$ ./gradlew build
```

--------------------------------

### Configure Client Manually

Source: https://github.com/openai/openai-java/blob/main/README.md

Configure the client by manually providing API keys and other settings. This is suitable for development or when environment variables are not preferred.

```java
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;

OpenAIClient client = OpenAIOkHttpClient.builder()
    .apiKey("My API Key")
    .adminApiKey("My Admin API Key")
    .build();
```

--------------------------------

### Iterate All Fine-Tuning Jobs (Async)

Source: https://github.com/openai/openai-java/blob/main/README.md

Use `autoPager()` with the asynchronous client to iterate through all fine-tuning jobs. This returns an `AsyncStreamResponse` which can be subscribed to.

```java
import com.openai.core.http.AsyncStreamResponse;
import com.openai.models.finetuning.jobs.FineTuningJob;
import com.openai.models.finetuning.jobs.JobListPageAsync;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;

CompletableFuture<JobListPageAsync> pageFuture = client.async().fineTuning().jobs().list();

pageFuture.thenRun(page -> page.autoPager().subscribe(job -> {
    System.out.println(job);
}));

// If you need to handle errors or completion of the stream
pageFuture.thenRun(page -> page.autoPager().subscribe(new AsyncStreamResponse.Handler<>() {
    @Override
    public void onNext(FineTuningJob job) {
        System.out.println(job);
    }

    @Override
    public void onComplete(Optional<Throwable> error) {
        if (error.isPresent()) {
            System.out.println("Something went wrong!");
            throw new RuntimeException(error.get());
        } else {
            System.out.println("No more!");
        }
    }
}));

// Or use futures
pageFuture.thenRun(page -> page.autoPager()
    .subscribe(job -> {
        System.out.println(job);
    })
    .onCompleteFuture()
    .whenComplete((unused, error) -> {
        if (error != null) {
            System.out.println("Something went wrong!");
            throw new RuntimeException(error);
        } else {
            System.out.println("No more!");
        }
    }));
```

--------------------------------

### Enable Debug Logging for OpenAI Client

Source: https://github.com/openai/openai-java/blob/main/_autodocs/client-initialization.md

Illustrates how to enable debug logging for the OpenAI client to inspect requests and responses, either programmatically or via environment variables.

```java
OpenAIClient client = OpenAIOkHttpClient.builder()
    .fromEnv()
    .logLevel(LogLevel.DEBUG)
    .build();

// Or via environment: export OPENAI_LOG=debug
```

--------------------------------

### Check Formatting and Linting

Source: https://github.com/openai/openai-java/blob/main/CONTRIBUTING.md

Run the lint script to check code formatting and static analysis.

```sh
./scripts/lint
```

--------------------------------

### Configure OpenAI Properties in application.properties

Source: https://github.com/openai/openai-java/blob/main/README.md

Set OpenAI API key, base URL, and other client options using properties in `application.properties`.

```properties
openai.base-url=https://api.openai.com/v1
openai.api-key=My API Key
openai.admin-key=My Admin API Key
openai.org-id=My Organization
openai.project-id=My Project
openai.webhook-secret=My Webhook Secret
```

--------------------------------

### Manual Pagination for Fine-Tuning Jobs

Source: https://github.com/openai/openai-java/blob/main/_autodocs/advanced-features.md

Implement manual pagination to control the fetching of fine-tuning job pages, allowing for custom processing logic and explicit control over page retrieval.

```java
JobListPage page = client.fineTuning().jobs().list();

while (true) {
    // Process current page
    for (FineTuningJob job : page.items()) {
        processJob(job);
    }
    
    // Check for next page
    if (!page.hasNextPage()) break;
    page = page.nextPage();
}
```

--------------------------------

### Handle OpenAI API Exceptions in Java

Source: https://github.com/openai/openai-java/blob/main/_autodocs/client-initialization.md

Demonstrates how to catch and handle various OpenAI exceptions, including rate limiting, authentication failures, and general API or SDK errors.

```java
try {
    ChatCompletion result = client.chat().completions().create(params);
} catch (RateLimitException e) {
    // Handle rate limiting
    Thread.sleep(5000); // Wait before retrying
} catch (UnauthorizedException e) {
    // Handle authentication failure
    System.err.println("Invalid API key");
} catch (OpenAIServiceException e) {
    // Handle other HTTP errors
    System.err.println("API error: " + e.statusCode());
} catch (OpenAIException e) {
    // Handle other SDK errors
    throw new RuntimeException("SDK error", e);
}
```

--------------------------------

### Iterate All Fine-Tuning Jobs (Sync)

Source: https://github.com/openai/openai-java/blob/main/README.md

Use `autoPager()` with the synchronous client to iterate through all fine-tuning jobs across all pages. This returns an `Iterable`.

```java
import com.openai.models.finetuning.jobs.FineTuningJob;
import com.openai.models.finetuning.jobs.JobListPage;

JobListPage page = client.fineTuning().jobs().list();

// Process as an Iterable
for (FineTuningJob job : page.autoPager()) {
    System.out.println(job);
}

// Process as a Stream
page.autoPager()
    .stream()
    .limit(50)
    .forEach(job -> System.out.println(job));
```

--------------------------------

### ClientOptions Builder

Source: https://github.com/openai/openai-java/blob/main/_autodocs/types.md

Sets client-level configurations, including base URL, timeouts, and retry counts. Use this builder to establish default settings for all requests made by the client.

```java
ClientOptions options = ClientOptions.builder()
    .baseUrl("https://api.openai.com/v1")
    .timeout(Timeout.builder()
        .read(Duration.ofSeconds(60))
        .build())
    .maxRetries(3)
    .logLevel(LogLevel.DEBUG)
    .build();
```

--------------------------------

### Async Chat Completions

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/chat-completions.md

Demonstrates how to make asynchronous calls to the chat completions endpoint using the OpenAI Java SDK. It shows how to initiate a request and handle the response or errors asynchronously.

```APIDOC
## Async Chat Completions

This section details how to perform asynchronous chat completion requests.

### Method Signature
```java
CompletableFuture<ChatCompletion> create(ChatCompletionRequest params)
```

### Example Usage
```java
OpenAIClientAsync asyncClient = OpenAIOkHttpClientAsync.fromEnv();

CompletableFuture<ChatCompletion> future = 
    asyncClient.chat().completions().create(params);

future.thenAccept(completion -> {
    System.out.println("Completion: " + 
        completion.choices().get(0).message().content());
}).exceptionally(e -> {
    System.err.println("Error: " + e.getMessage());
    return null;
});
```
```

--------------------------------

### Set Environment Variables for OpenAI API Key

Source: https://github.com/openai/openai-java/blob/main/_autodocs/README.md

Configure API key, organization ID, project ID, base URL, webhook secret, and logging level using environment variables. These are checked first during client initialization.

```bash
export OPENAI_API_KEY="sk-..."
export OPENAI_ORG_ID="org-..."
export OPENAI_PROJECT_ID="proj-..."
export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_WEBHOOK_SECRET="whsec_..."
export OPENAI_LOG="debug"
```

--------------------------------

### Build Embedding Request Parameters

Source: https://github.com/openai/openai-java/blob/main/_autodocs/types.md

Illustrates how to build parameters for embedding requests, specifying input, model, and dimensions.

```java
EmbeddingCreateParams params = EmbeddingCreateParams.builder()
    .input("text to embed")
    .model("text-embedding-3-small")
    .dimensions(256)
    .encodingFormat(EmbeddingCreateParams.EncodingFormat.FLOAT)
    .user("user-id")
    .build();
```

--------------------------------

### Use Custom HTTP Client

Source: https://github.com/openai/openai-java/blob/main/_autodocs/advanced-features.md

Integrate a completely custom HTTP client implementation with the OpenAI client. This allows for fine-grained control over network requests.

```java
class CustomHttpClient implements HttpClient {
    @Override
    public HttpResponse execute(HttpRequest request) {
        // Custom implementation
        return null;
    }
    
    @Override
    public void close() {
        // Cleanup
    }
}

OpenAIClient client = OpenAIClientImpl.builder()
    .httpClient(new CustomHttpClient())
    .build();
```

--------------------------------

### Initialize ChatCompletionService

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/chat-completions.md

Access the ChatCompletionService from the OpenAI client. This is the entry point for all chat completion operations.

```java
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
ChatCompletionService chatService = client.chat().completions();
```

--------------------------------

### Handle NotFoundException (404)

Source: https://github.com/openai/openai-java/blob/main/_autodocs/errors.md

Catch this exception when a requested resource such as a model, file, or thread does not exist. Verify that the resource ID is correct.

```java
try {
    client.files().retrieve(FileRetrieveParams.builder()
        .fileId("file_nonexistent")
        .build());
} catch (NotFoundException e) {
    System.err.println("File not found");
    // Handle: verify resource ID exists
}
```

--------------------------------

### File Upload with Different Input Types

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/files.md

Demonstrates creating file upload parameters using various input types: file path, InputStream, byte array, and URL with a custom filename. The file path method is preferred as it includes the filename.

```java
// From file path (preferred - includes filename)
FileCreateParams params1 = FileCreateParams.builder()
    .file(Paths.get("training.jsonl"))
    .purpose(FilePurpose.FINE_TUNE)
    .build();
```

```java
// From InputStream (filename not included)
FileCreateParams params2 = FileCreateParams.builder()
    .file(new FileInputStream("training.jsonl"))
    .purpose(FilePurpose.FINE_TUNE)
    .build();
```

```java
// From byte array (filename not included)
byte[] data = Files.readAllBytes(Paths.get("training.jsonl"));
FileCreateParams params3 = FileCreateParams.builder()
    .file(data)
    .purpose(FilePurpose.FINE_TUNE)
    .build();
```

```java
// From URL (with custom filename)
FileCreateParams params4 = FileCreateParams.builder()
    .file(MultipartField.<InputStream>builder()
        .value(new URL("https://example.com/data.jsonl").openStream())
        .filename("training.jsonl")
        .build())
    .purpose(FilePurpose.FINE_TUNE)
    .build();
```

--------------------------------

### Create File Upload Parameters

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/files.md

Use this builder to construct parameters for file upload requests. Specify the file content and its purpose.

```java
FileCreateParams params = FileCreateParams.builder()
    .file(Paths.get("data.jsonl"))
    .purpose(FilePurpose.FINE_TUNE)
    .build();
```

--------------------------------

### Using Different Embedding Models

Source: https://github.com/openai/openai-java/blob/main/_autodocs/api-reference/embeddings.md

Shows how to create embedding parameters using either the 'text-embedding-3-small' or 'text-embedding-3-large' models.

```java
// Small, efficient model
EmbeddingCreateParams params = EmbeddingCreateParams.builder()
    .input("Your text")
    .model("text-embedding-3-small")
    .build();

// Larger, more capable model
EmbeddingCreateParams params = EmbeddingCreateParams.builder()
    .input("Your text")
    .model("text-embedding-3-large")
    .build();
```

--------------------------------

### Publish Local Maven Artifact

Source: https://github.com/openai/openai-java/blob/main/CONTRIBUTING.md

This command publishes the OpenAI Java library to your local Maven repository, allowing you to use it in other projects without depending on remote repositories. Ensure you have commented out `signAllPublications()` in `buildSrc/src/main/kotlin/openai.publish.gradle.kts` before running.

```sh
$ ./gradlew publishToMavenLocal
```