### Execute Simple-OpenAI Demo Example (Shell)

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

This shell command runs a specific demo example using the rundemo.sh script. The <demo> placeholder should be replaced with the name of a Java demo file (e.g., 'Chat') to execute that particular demonstration.

```Shell
./rundemo.sh <demo>
```

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

### Install Simple-OpenAI via Maven

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

Add the Simple-OpenAI and optional OkHttp dependencies to your Maven `pom.xml` file. This library requires Java 11 or a newer version.

```XML
<dependency>
    <groupId>io.github.sashirestela</groupId>
    <artifactId>simple-openai</artifactId>
    <version>[simple-openai_latest_version]</version>
</dependency>
<!-- OkHttp dependency is optional if you decide to use it with simple-openai -->
<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>[okhttp_latest_version]</version>
</dependency>
```

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

### Install Simple-OpenAI via Gradle

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

Add the Simple-OpenAI and optional OkHttp dependencies to your Gradle `build.gradle` file. This library requires Java 11 or a newer version.

```Groovy
dependencies {
    implementation 'io.github.sashirestela:simple-openai:[simple-openai_latest_version]'
    /* OkHttp dependency is optional if you decide to use it with simple-openai */
    implementation 'com.squareup.okhttp3:okhttp:[okhttp_latest_version]'
}
```

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

### Example Conversation Flow with OpenAI Chat Completion

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

This section presents a console output demonstrating a multi-turn conversation with the OpenAI Chat Completion service. It illustrates how a user interacts with an AI assistant, asking questions about a specific topic (Lima, Peru), receiving detailed information, and getting tips. The underlying Java code (linked as ConversationDemo.java) uses streaming and potentially function calls to achieve this interactive experience.

```Console Output
Welcome! Write any message: Hi, can you help me with some quetions about Lima, Peru?
Of course! What would you like to know about Lima, Peru?

Write any message (or write 'exit' to finish): Tell me something brief about Lima Peru, then tell me how's the weather there right now. Finally give me three tips to travel there.
### Brief About Lima, Peru
Lima, the capital city of Peru, is a bustling metropolis that blends modernity with rich historical heritage. Founded by Spanish conquistador Francisco Pizarro in 1535, Lima is known for its colonial architecture, vibrant culture, and delicious cuisine, particularly its world-renowned ceviche. The city is also a gateway to exploring Peru's diverse landscapes, from the coastal deserts to the Andean highlands and the Amazon rainforest.

### Current Weather in Lima, Peru
I'll check the current temperature and the probability of rain in Lima for you.### Current Weather in Lima, Peru
- **Temperature:** Approximately 11.8°C
- **Probability of Rain:** Approximately 97.8%

### Three Tips for Traveling to Lima, Peru
1. **Explore the Historic Center:**
   - Visit the Plaza Mayor, the Government Palace, and the Cathedral of Lima. These landmarks offer a glimpse into Lima's colonial past and are UNESCO World Heritage Sites.

2. **Savor the Local Cuisine:**
   - Don't miss out on trying ceviche, a traditional Peruvian dish made from fresh raw fish marinated in citrus juices. Also, explore the local markets and try other Peruvian delicacies.

3. **Visit the Coastal Districts:**
   - Head to Miraflores and Barranco for stunning ocean views, vibrant nightlife, and cultural experiences. These districts are known for their beautiful parks, cliffs, and bohemian atmosphere.

Enjoy your trip to Lima! If you have any more questions, feel free to ask.

Write any message (or write 'exit' to finish): exit
```

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

### Build Simple-OpenAI Project with Maven (Shell)

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

This shell command uses Maven to clean and install the Simple-OpenAI project. This step compiles the source code, runs tests, and packages the project, making it ready for execution.

```Shell
mvn clean install
```

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

### Clone Simple-OpenAI GitHub Repository (Shell)

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

This shell command clones the Simple-OpenAI project repository from GitHub. It's the initial step to set up the project locally for development or running examples.

```Shell
git clone https://github.com/sashirestela/simple-openai.git
cd simple-openai
```

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

### OpenAI Text Completion Streamed Response Object Examples

Source: https://github.com/sashirestela/simple-openai/blob/main/src/test/resources/completions_create_stream.txt

Provides examples of the JSON objects returned by the OpenAI Text Completion API when streaming is enabled. The first example shows a typical token chunk, while the second demonstrates the final message containing usage statistics and an empty `choices` array.

```JSON
{"id":"cmpl-9MGAU927gpgN0Fw3h85furc6mQ9av","object":"text_completion","created":1715092394,"choices":[{"text":" where c is the length of the hypotenuse and","index":0,"logprobs":null,"finish_reason":null}],"model":"gpt-3.5-turbo-instruct","usage":null}
```

```JSON
{"id":"cmpl-9MGAU927gpgN0Fw3h85furc6mQ9av","object":"text_completion","created":1715092394,"model":"gpt-3.5-turbo-instruct","usage":{"prompt_tokens":15,"completion_tokens":85,"total_tokens":100},"choices":[]}
```

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

### Perform Chat Completion using OpenAI API (Java)

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

This example shows how to use the OpenAI Chat Completion service to ask a question and receive a full answer. The response is printed to the console.

```Java
var chatRequest = ChatRequest.builder()
        .model("gpt-4o-mini")
        .message(SystemMessage.of("You are an expert in AI."))
        .message(UserMessage.of("Write a technical article about ChatGPT, no more than 100 words."))
        .temperature(0.0)
        .maxCompletionTokens(300)
        .build();
var futureChat = openAI.chatCompletions().create(chatRequest);
var chatResponse = futureChat.join();
System.out.println(chatResponse.firstContent());
```

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

### Generate Audio from Text using OpenAI API (Java)

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

This example demonstrates how to use the OpenAI Audio service to convert text into speech. It requests the audio in binary format (InputStream) and saves it to a file.

```Java
var speechRequest = SpeechRequest.builder()
        .model("tts-1")
        .input("Hello world, welcome to the AI universe!")
        .voice(Voice.ALLOY)
        .responseFormat(SpeechResponseFormat.MP3)
        .speed(1.0)
        .build();
var futureSpeech = openAI.audios().speak(speechRequest);
var speechResponse = futureSpeech.join();
try {
    var audioFile = new FileOutputStream(speechFileName);
    audioFile.write(speechResponse.readAllBytes());
    System.out.println(audioFile.getChannel().size() + " bytes");
    audioFile.close();
} catch (Exception e) {
    e.printStackTrace();
}
```

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

### Transcribe Audio to Text using OpenAI API (Java)

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

This example shows how to use the OpenAI Audio service to transcribe an audio file into text. It requests the transcription in plain text format.

```Java
var audioRequest = TranscriptionRequest.builder()
        .file(Paths.get("hello_audio.mp3"))
        .model("whisper-1")
        .responseFormat(AudioResponseFormat.VERBOSE_JSON)
        .temperature(0.2)
        .timestampGranularity(TimestampGranularity.WORD)
        .timestampGranularity(TimestampGranularity.SEGMENT)
        .build();
var futureAudio = openAI.audios().transcribe(audioRequest);
var audioResponse = futureAudio.join();
System.out.println(audioResponse);
```

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

### Perform Streaming Chat Completion using OpenAI API (Java)

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

This example demonstrates how to use the OpenAI Chat Completion service to receive an answer in partial message deltas. Each delta is printed to the console as it arrives.

```Java
var chatRequest = ChatRequest.builder()
        .model("gpt-4o-mini")
        .message(SystemMessage.of("You are an expert in AI."))
        .message(UserMessage.of("Write a technical article about ChatGPT, no more than 100 words."))
        .temperature(0.0)
        .maxCompletionTokens(300)
        .build();
var futureChat = openAI.chatCompletions().createStream(chatRequest);
var chatResponse = futureChat.join();
chatResponse.filter(chatResp -> chatResp.getChoices().size() > 0 && chatResp.firstContent() != null)
        .map(Chat::firstContent)
        .forEach(System.out::print);
System.out.println();
```

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

### Generate Images using OpenAI API (Java)

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

This example demonstrates how to use the OpenAI Image service to generate multiple images based on a prompt. It requests image URLs and prints them to the console, also decoding and saving them locally.

```Java
var imageRequest = ImageRequest.builder()
        .prompt("An image of orange cat hugging other white cat with a light blue scarf.")
        .model("gpt-image-1")
        .background(Background.TRANSPARENT)
        .outputFormat(OutputFormat.PNG)
        .quality(Quality.MEDIUM)
        .size(Size.X_1024_1024)
        .moderation(Moderation.LOW)
        .n(2)
        .build();
var futureImage = openAI.images().create(imageRequest);
var imageResponse = futureImage.join();
IntStream.range(0, imageResponse.getData().size()).forEach(i -> {
    var filePath = "src/demo/resources/image" + (i + 1) + ".png";
    Base64Util.decode(imageResponse.getData().get(i).getB64Json(), filePath);
    System.out.println(filePath);
});
```

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

### Call OpenAI Chat Completion for Audio Input and Output

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

Shows how to interact with OpenAI's Chat Completion using audio. It sends audio input (MP3) as a user message and receives an audio response from the model. The example also demonstrates saving the generated audio and printing its transcript.

```java
var messages = new ArrayList<ChatMessage>();
messages.add(SystemMessage.of("Respond in a short and concise way."));
messages.add(UserMessage.of(List.of(ContentPartInputAudio.of(InputAudio.of(
        Base64Util.encode("src/demo/resources/question1.mp3", null), InputAudioFormat.MP3)))));
chatRequest = ChatRequest.builder()
        .model("gpt-4o-audio-preview")
        .modality(Modality.TEXT)
        .modality(Modality.AUDIO)
        .audio(Audio.of(Voice.ALLOY, AudioFormat.MP3))
        .messages(messages)
        .build();
var chatResponse = openAI.chatCompletions().create(chatRequest).join();
var audio = chatResponse.firstMessage().getAudio();
Base64Util.decode(audio.getData(), "src/demo/resources/answer1.mp3");
System.out.println("Answer 1: " + audio.getTranscript());

messages.add(AssistantMessage.builder().audioId(audio.getId()).build());
messages.add(UserMessage.of(List.of(ContentPartInputAudio.of(InputAudio.of(
        Base64Util.encode("src/demo/resources/question2.mp3", null), InputAudioFormat.MP3)))));
chatRequest = ChatRequest.builder()
        .model("gpt-4o-audio-preview")
        .modality(Modality.TEXT)
        .modality(Modality.AUDIO)
        .audio(Audio.of(Voice.ALLOY, AudioFormat.MP3))
        .messages(messages)
        .build();
chatResponse = openAI.chatCompletions().create(chatRequest).join();
audio = chatResponse.firstMessage().getAudio();
Base64Util.decode(audio.getData(), "src/demo/resources/answer2.mp3");
System.out.println("Answer 2: " + audio.getTranscript());
```

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

### Call OpenAI Chat Completion with Vision for Local Images

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

Illustrates using OpenAI's Chat Completion service to analyze a local image file. The image is encoded using `Base64Util` and sent with a text prompt. The example streams and prints the model's detailed response about the image content.

```java
var chatRequest = ChatRequest.builder()
        .model("gpt-4o-mini")
        .messages(List.of(
                UserMessage.of(List.of(
                        ContentPartText.of(
                                "What do you see in the image? Give in details in no more than 100 words."),
                        ContentPartImageUrl.of(ImageUrl.of(
                                Base64Util.encode("src/demo/resources/machupicchu.jpg", MediaType.IMAGE)))))))
        .temperature(0.0)
        .maxCompletionTokens(500)
        .build();
var chatResponse = openAI.chatCompletions().createStream(chatRequest).join();
chatResponse.filter(chatResp -> chatResp.getChoices().size() > 0 && chatResp.firstContent() != null)
        .map(Chat::firstContent)
        .forEach(System.out::print);
System.out.println();
```

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

### OpenAI Assistants API Event: thread.run.step

Source: https://github.com/sashirestela/simple-openai/blob/main/src/test/resources/threads_runs_create_stream_error_1.txt

Example of a `thread.run.step` event, indicating a step in the execution of an assistant run. This event provides details about the type of step, such as message creation, and its current status, offering insight into the assistant's real-time progress.

```APIDOC
{"id":"step_lmDenBFdg4FoEBmRRWE1s8DZ","object":"thread.run.step","created_at":1714853354,"run_id":"run_uNQ87yXUBgR3bf8AKnzO0p1b","assistant_id":"asst_eC1BeXfmDfbyiSB79WewXLw9","thread_id":"thread_DWFcoAFxKqpNR8MKplqFREzl","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1714853953,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_HdHuRcbxQRyO6ttCZt2PeSLO"}},"usage":null}
```

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

### Java OpenAI Chat Completion with Custom Function Calling

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

This Java code demonstrates how to integrate custom function calling with OpenAI's Chat Completion API. It defines three functions (`get_weather`, `product`, `run_alarm`) using classes that implement the `Functional` interface. The `FunctionExecutor` utility enrolls these functions and handles their execution based on the model's tool call. The example shows a full chat interaction where the 'product' function is invoked and its result is used in a follow-up chat.

```Java
public void demoCallChatWithFunctions() {
    var functionExecutor = new FunctionExecutor();
    functionExecutor.enrollFunction(
            FunctionDef.builder()
                    .name("get_weather")
                    .description("Get the current weather of a location")
                    .functionalClass(Weather.class)
                    .strict(Boolean.TRUE)
                    .build());
    functionExecutor.enrollFunction(
            FunctionDef.builder()
                    .name("product")
                    .description("Get the product of two numbers")
                    .functionalClass(Product.class)
                    .strict(Boolean.TRUE)
                    .build());
    functionExecutor.enrollFunction(
            FunctionDef.builder()
                    .name("run_alarm")
                    .description("Run an alarm")
                    .functionalClass(RunAlarm.class)
                    .strict(Boolean.TRUE)
                    .build());
    var messages = new ArrayList<ChatMessage>();
    messages.add(UserMessage.of("What is the product of 123 and 456?"));
    chatRequest = ChatRequest.builder()
            .model("gpt-4o-mini")
            .messages(messages)
            .tools(functionExecutor.getToolFunctions())
            .build();
    var futureChat = openAI.chatCompletions().create(chatRequest);
    var chatResponse = futureChat.join();
    var chatMessage = chatResponse.firstMessage();
    var chatToolCall = chatMessage.getToolCalls().get(0);
    var result = functionExecutor.execute(chatToolCall.getFunction());
    messages.add(chatMessage);
    messages.add(ToolMessage.of(result.toString(), chatToolCall.getId()));
    chatRequest = ChatRequest.builder()
            .model("gpt-4o-mini")
            .messages(messages)
            .tools(functionExecutor.getToolFunctions())
            .build();
    futureChat = openAI.chatCompletions().create(chatRequest);
    chatResponse = futureChat.join();
    System.out.println(chatResponse.firstContent());
}

public static class Weather implements Functional {

    @JsonPropertyDescription("City and state, for example: León, Guanajuato")
    @JsonProperty(required = true)
    public String location;

    @JsonPropertyDescription("The temperature unit, can be 'celsius' or 'fahrenheit'")
    @JsonProperty(required = true)
    public String unit;

    @Override
    public Object execute() {
        return Math.random() * 45;
    }

}

public static class Product implements Functional {

    @JsonPropertyDescription("The multiplicand part of a product")
    @JsonProperty(required = true)
    public double multiplicand;

    @JsonPropertyDescription("The multiplier part of a product")
    @JsonProperty(required = true)
    public double multiplier;

    @Override
    public Object execute() {
        return multiplicand * multiplier;
    }

}

public static class RunAlarm implements Functional {

    @Override
    public Object execute() {
        return "DONE";
    }

}
```

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

### Define OpenAI Chat Message Structure

Source: https://github.com/sashirestela/simple-openai/blob/main/src/test/resources/files_getcontent.txt

This snippet illustrates the standard JSON format for defining a conversational turn in an OpenAI-compatible chat model. It includes a system message to set the AI's persona, a user message as input, and an assistant message as a generated response. This structure is crucial for providing context and managing the flow of interaction with the AI.

```JSON
{"messages": [{"role": "system", "content": "Marv is a factual chatbot that is also sarcastic."}, {"role": "user", "content": "What's the capital of France?"}, {"role": "assistant", "content": "Paris, as if everyone doesn't know that already."}]}
```

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

### Initialize SimpleOpenAI Client (Java/Kotlin)

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

This snippet demonstrates how to create an instance of the `SimpleOpenAI` client in both Java and Kotlin. It shows how to set the API key and optionally provide a custom `OkHttpClientAdapter` for network operations. This object is essential for interacting with the OpenAI API.

```Java
SimpleOpenAI openAI = SimpleOpenAI.builder()
    .apiKey(API_KEY)
    .clientAdapter(new OkHttpClientAdapter())  // Optionally you could add a custom OkHttpClient
    .build();
```

```Kotlin
val openAI = SimpleOpenAI.builder()
    .apiKey(API_KEY)
    .clientAdapter(OkHttpClientAdapter())  // Optionally you could add a custom OkHttpClient
    .build()
```

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

### OpenAI Chat Completion Streaming Raw Data

Source: https://github.com/sashirestela/simple-openai/blob/main/src/test/resources/chatcompletions_create_stream.txt

This snippet shows the complete sequence of Server-Sent Events (SSE) received during a single streaming chat completion from the OpenAI API. Each line starting with 'data:' represents a JSON object containing a 'delta' field that incrementally builds the response content, followed by a 'stop' signal and final usage information.

```JSON
data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" \\("},"logprobs":null,"finish_reason":null}],"usage":null}
data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":"a"},"logprobs":null,"finish_reason":null}],"usage":null}
data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":"^"},"logprobs":null,"finish_reason":null}],"usage":null}
data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":"2"},"logprobs":null,"finish_reason":null}],"usage":null}
data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" +"},"logprobs":null,"finish_reason":null}],"usage":null}
data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" b"},"logprobs":null,"finish_reason":null}],"usage":null}
data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":"^"},"logprobs":null,"finish_reason":null}],"usage":null}
data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":"2"},"logprobs":null,"finish_reason":null}],"usage":null}
data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" ="},"logprobs":null,"finish_reason":null}],"usage":null}
data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" c"},"logprobs":null,"finish_reason":null}],"usage":null}
data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":"^"},"logprobs":null,"finish_reason":null}],"usage":null}
data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":"2"},"logprobs":null,"finish_reason":null}],"usage":null}
data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":"\\"},"logprobs":null,"finish_reason":null}],"usage":null}
data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":")."},"logprobs":null,"finish_reason":null}],"usage":null}
data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}],"usage":null}
data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[],"usage":{"prompt_tokens":35,"completion_tokens":67,"total_tokens":102}}
data: [DONE]
```

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

### Enforcing Structured JSON Output from OpenAI Chat Completion in Java

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

This Java code snippet demonstrates how to configure the OpenAI Chat Completion service to return responses strictly adhering to a predefined JSON schema. It uses the ResponseFormat.jsonSchema feature, mapping the output to a Java class (MathReasoning) for type-safe parsing. The example shows a math tutor guiding a user, with the reasoning steps and final answer structured as JSON.

```Java
public void demoCallChatWithStructuredOutputs() {
    var chatRequest = ChatRequest.builder()
            .model("gpt-4o-mini")
            .message(SystemMessage
                    .of("You are a helpful math tutor. Guide the user through the solution step by step."))
            .message(UserMessage.of("How can I solve 8x + 7 = -23"))
            .responseFormat(ResponseFormat.jsonSchema(JsonSchema.builder()
                    .name("MathReasoning")
                    .schemaClass(MathReasoning.class)
                    .build()))
            .build();
    var chatResponse = openAI.chatCompletions().createStream(chatRequest).join();
    chatResponse.filter(chatResp -> chatResp.getChoices().size() > 0 && chatResp.firstContent() != null)
            .map(Chat::firstContent)
            .forEach(System.out::print);
    System.out.println();
}

public static class MathReasoning {

    public List<Step> steps;
    public String finalAnswer;

    public static class Step {

        public String explanation;
        public String output;

    }

}
```

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

### OpenAI Thread Message Delta Event Example

Source: https://github.com/sashirestela/simple-openai/blob/main/src/test/resources/threads_runs_create_stream_1.txt

This snippet illustrates a concrete example of a `thread.message.delta` event received via Server-Sent Events (SSE). It shows the event type and the JSON payload containing an incremental message content update, typically used for streaming responses from an OpenAI-compatible API.

```SSE
event: thread.message.delta
data: {"id":"msg_HdHuRcbxQRyO6ttCZt2PeSLO","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"ños"}}]}}
```

```JSON
{
  "id": "msg_HdHuRcbxQRyO6ttCZt2PeSLO",
  "object": "thread.message.delta",
  "delta": {
    "content": [
      {
        "index": 0,
        "type": "text",
        "text": {
          "value": "ños"
        }
      }
    ]
  }
}
```

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

### Initialize Simple-OpenAI for Anyscale Provider (Java)

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

This Java code snippet shows how to initialize the SimpleOpenAIAnyscale client. It requires setting the API key from an environment variable. Optional parameters include a custom base URL and a custom client adapter.

```Java
var openai = SimpleOpenAIAnyscale.builder()
    .apiKey(System.getenv("ANYSCALE_API_KEY"))
    //.baseUrl(customUrl)   Optionally you could pass a custom baseUrl
    //.clientAdapter(...)   Optionally you could pass a custom clientAdapter
    .build();
```

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

### Configure Gemini Vertex Demo Environment Variables (Shell)

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

These shell commands set the environment variables required for running demos with Gemini Vertex. They specify the base URL for the Vertex AI API and the path to the GCP service account credentials JSON file, essential for authentication.

```Shell
export GEMINI_VERTEX_BASE_URL=https://<location>-aiplatform.googleapis.com/v1beta1/projects/<gcp project>/locations/<location>>/endpoints/openapi
export GEMINI_VERTEX_SA_CREDS_PATH=<path to GCP service account credentials JSON file>
```

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

### OpenAI Chat Completion Streaming Data (SSE Format)

Source: https://github.com/sashirestela/simple-openai/blob/main/src/test/resources/chatcompletions_create_stream.txt

A complete example of a streaming response from the OpenAI chat completion API, formatted as Server-Sent Events (SSE). Each line prefixed with `data:` contains a JSON object representing a partial response chunk, typically including a `delta.content` field for the streamed text.

```JSON
data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" the"},"logprobs":null,"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" length"},"logprobs":null,"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" of"},"logprobs":null,"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" the"},"logprobs":null,"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" hyp"},"logprobs":null,"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":"oten"},"logprobs":null,"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":"use"},"logprobs":null,"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" ("},"logprobs":null,"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":"the"},"logprobs":null,"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" side"},"logprobs":null,"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" opposite"},"logprobs":null,"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" the"},"logprobs":null,"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" right"},"logprobs":null,"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" angle"},"logprobs":null,"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":")"},"logprobs":null,"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" is"},"logprobs":null,"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" equal"},"logprobs":null,"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" to"},"logprobs":null,"finish_reason":null}],"usage":null}
```

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

### Initialize Simple-OpenAI for Azure Provider (Java)

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

This Java code snippet demonstrates how to initialize the SimpleOpenAIAzure client. It requires setting the API key, base URL (including resource name and deployment ID), and API version via environment variables. An optional custom client adapter can also be provided.

```Java
var openai = SimpleOpenAIAzure.builder()
    .apiKey(System.getenv("AZURE_OPENAI_API_KEY"))
    .baseUrl(System.getenv("AZURE_OPENAI_BASE_URL"))   // Including resourceName and deploymentId
    .apiVersion(System.getenv("AZURE_OPENAI_API_VERSION"))
    //.clientAdapter(...)   Optionally you could pass a custom clientAdapter
    .build();
```

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

### OpenAI Thread Message Delta Event Structure and Example

Source: https://github.com/sashirestela/simple-openai/blob/main/src/test/resources/threads_runs_create_stream_error_1.txt

Describes the structure of the `thread.message.delta` event, which is streamed by the OpenAI API to provide real-time updates on message content. Each event contains an ID, object type, and a delta object with content updates, typically text value fragments. An example JSON payload is also provided.

```APIDOC
Event: thread.message.delta
Description: Represents an incremental update to a message in a thread.

Data Object Structure:
  id: string (Unique identifier for the message)
  object: string (Always "thread.message.delta")
  delta: object (Contains the changes to the message)
    content: array of objects (List of content parts that have changed)
      - index: integer (The index of the content part being updated)
      - type: string (The type of content, e.g., "text")
      - text: object (Details for text content)
        value: string (The incremental text content)
```

```JSON
{
  "id": "msg_HdHuRcbxQRyO6ttCZt2PeSLO",
  "object": "thread.message.delta",
  "delta": {
    "content": [
      {
        "index": 0,
        "type": "text",
        "text": {
          "value": "ños"
        }
      }
    ]
  }
}
```

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

### Configure Simple-OpenAI for Gemini Vertex API (Java)

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

This Java code shows how to initialize `SimpleOpenAIGeminiVertex` to connect to the Gemini Vertex API. It requires setting a base URL and an API key provider function, and allows for an optional custom client adapter.

```Java
var openai = SimpleOpenAIGeminiVertex.builder()
    .baseUrl(System.getenv("GEMINI_VERTEX_BASE_URL"))
    .apiKeyProvider(<a function that returns a valid API key that refreshes every hour>)
    //.clientAdapter(...)   Optionally you could pass a custom clientAdapter
    .build();
```

```APIDOC
Supported Services:
- chatCompletionService (text generation, streaming, function calling, vision, structured outputs)
```

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

### OpenAI Chat Completion Stream Chunk Example

Source: https://github.com/sashirestela/simple-openai/blob/main/src/test/resources/chatcompletions_create_stream.txt

This snippet showcases the JSON structure of a single data chunk from an OpenAI chat completion stream. Each chunk includes metadata like `id`, `object` type, `created` timestamp, and `model`, along with a `choices` array containing the `delta` object, which holds the incrementally streamed `content`.

```JSON
{"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" the"},"logprobs":null,"finish_reason":null}],"usage":null}
```

```JSON
{"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" sum"},"logprobs":null,"finish_reason":null}],"usage":null}
```

```JSON
{"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" of"},"logprobs":null,"finish_reason":null}],"usage":null}
```

```JSON
{"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" the"},"logprobs":null,"finish_reason":null}],"usage":null}
```

```JSON
{"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" squares"},"logprobs":null,"finish_reason":null}],"usage":null}
```

```JSON
{"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" of"},"logprobs":null,"finish_reason":null}],"usage":null}
```

```JSON
{"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" the"},"logprobs":null,"finish_reason":null}],"usage":null}
```

```JSON
{"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" lengths"},"logprobs":null,"finish_reason":null}],"usage":null}
```

```JSON
{"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" of"},"logprobs":null,"finish_reason":null}],"usage":null}
```

```JSON
{"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" the"},"logprobs":null,"finish_reason":null}],"usage":null}
```

```JSON
{"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" other"},"logprobs":null,"finish_reason":null}],"usage":null}
```

```JSON
{"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" two"},"logprobs":null,"finish_reason":null}],"usage":null}
```

```JSON
{"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" sides"},"logprobs":null,"finish_reason":null}],"usage":null}
```

```JSON
{"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":"."},"logprobs":null,"finish_reason":null}],"usage":null}
```

```JSON
{"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":" Math"},"logprobs":null,"finish_reason":null}],"usage":null}
```

```JSON
{"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":"em"},"logprobs":null,"finish_reason":null}],"usage":null}
```

```JSON
{"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":"atically"},"logprobs":null,"finish_reason":null}],"usage":null}
```

```JSON
{"id":"chatcmpl-9MEw3bKUxW4tUpBe9ajJdN57u0nmo","object":"chat.completion.chunk","created":1715087655,"model":"gpt-4-1106-preview","system_fingerprint":null,"choices":[{"index":0,"delta":{"content":","},"logprobs":null,"finish_reason":null}],"usage":null}
```

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

### Configure Simple-OpenAI for Mistral API (Java)

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

This Java code demonstrates how to initialize `SimpleOpenAIMistral` for the Mistral API. It requires an API key and supports optional custom base URL or client adapter.

```Java
var openai = SimpleOpenAIMistral.builder()
    .apiKey(System.getenv("MISTRAL_API_KEY"))
    //.baseUrl(customUrl)   Optionally you could pass a custom baseUrl
    //.clientAdapter(...)   Optionally you could pass a custom clientAdapter
    .build();
```

```APIDOC
Supported Services:
- chatCompletionService (text generation, streaming, function calling, vision)
- embeddingService (float format)
- modelService (list, detail, delete)
```

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

### Create SimpleOpenAI Object with API Key

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

Initialize the `SimpleOpenAI` object by providing your OpenAI API Key. The key is typically loaded from an environment variable for security best practices.

```Java
var openAI = SimpleOpenAI.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .build();
```

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

### Configure Simple-OpenAI for Gemini Google API (Java)

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

This Java code demonstrates how to initialize `SimpleOpenAIGeminiGoogle` to interact with the Gemini Google API. It primarily requires setting the API key and optionally allows for a custom base URL or client adapter.

```Java
var openai = SimpleOpenAIGeminiGoogle.builder()
    .apiKey(System.getenv("GEMINIGOOGLE_API_KEY"))
    //.baseUrl(customUrl)   Optionally you could pass a custom baseUrl
    //.clientAdapter(...)   Optionally you could pass a custom clientAdapter
    .build();
```

```APIDOC
Supported Services:
- chatCompletionService (text generation, streaming, function calling, vision, structured outputs)
- embeddingService (float format)
```

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

### Maven Commands for Spotless Code Formatting

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

These Maven commands are used to check and apply code formatting rules defined by Spotless. Running `spotless:check` verifies formatting, while `spotless:apply` automatically rewrites source code to conform to the specified style. It's recommended to run these before committing changes.

```Shell
mvn spotless:check
mvn spotless:apply
```

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

### Configure Android Project for Simple-OpenAI (Groovy)

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

This Groovy snippet for `build.gradle` shows the necessary Android configuration to integrate Simple-OpenAI. It specifies minimum SDK version, Java compatibility, Kotlin JVM target, and declares the required dependencies for Simple-OpenAI and OkHttp.

```Groovy
android {
    //...
    defaultConfig {
        //...
        minSdk 24
        //...
    }
    //...
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
    }
    kotlinOptions {
        jvmTarget = '11'
    }
}

dependencies {
    //...
    implementation 'io.github.sashirestela:simple-openai:[simple-openai_version]'
    implementation 'com.squareup.okhttp3:okhttp:[okhttp_version]'
}
```

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

### OpenAI API: Thread Run Queued Event Data

Source: https://github.com/sashirestela/simple-openai/blob/main/src/test/resources/threads_runs_createthreadandrun_stream_1.txt

Shows the data structure for a 'thread.run.queued' event, which indicates the run's status as queued, along with its configuration and tool definitions. This payload is identical to the 'thread.run.created' event in this example.

```APIDOC
{"id":"run_52tHMSE6i1HsqrHXPYYSmSJG","object":"thread.run","created_at":1714853375,"assistant_id":"asst_eC1BeXfmDfbyiSB79WewXLw9","thread_id":"thread_ZBbf7KAjtlMu5V7yULv3TdTy","status":"queued","started_at":null,"expires_at":1714853975,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4-turbo","instructions":"You are a very kind assistant. If you cannot find correct facts to answer the questions, you have to refer to the attached files or use the functions provided. Finally, if you receive math questions, you must write and run code to answer them.","tools":[{"type":"function","function":{"name":"CurrentTemperature","description":"Get the current temperature for a specific location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g., San Francisco, CA"},"unit":{"type":"string","description":"The temperature unit to use. Infer this from the user's location."}},"required":["location","unit"]}}},{"type":"function","function":{"name":"RainProbability","description":"Get the probability of rain for a specific location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g., San Francisco, CA"}},"required":["location"]}}}],"tool_resources":{"code_interpreter":{"file_ids":[]}},"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto"}
```