Simple-OpenAI Java Library

Simple-OpenAI provides a consistent Java interface for a wide range of OpenAI services. Supported features include:

• Audio: Speech, Transcription, Translation
• Batch: Batches of Chat Completion
• Chat Completion: Text Generation, Streaming, Function Calling, Vision, Structured Outputs, Audio, Web Search
• Completion: Legacy Text Generation
• Embedding: Vectoring Text
• Files: Upload Files
• Fine Tuning: Customize Models
• Image: Generate, Edit, Variation
• Models: List models
• Moderation: Check harmful text
• Realtime: Speech-to-Speech Conversation, Multimodality, Function Calling
• Response: Text Generation, Streaming, Function Calling, Vision, Structured Outputs, Reasoning, Computer Use, File Search, Web Search, Remote MCP, Image Generation, Code Interpreter, Reusable Prompts
• Session Token: Create Ephemeral Tokens, Create Transcription Ephemeral Tokens
• Upload: Upload Large Files in Parts
• Assistants Beta v2: Assistants, Threads, Messages, Runs, Steps, Vector Stores, Streaming, Function Calling, Vision, Structured Outputs

Function calling allows the model to interact with your local business logic. To implement this:

1. Create classes that implement the Functional interface.
2. Use @JsonProperty and @JsonPropertyDescription to define the function arguments for the model.
3. Use FunctionExecutor to enroll these functions and execute the logic when the model requests a tool call.
4. Pass the tools to the ChatRequest using functionExecutor.getToolFunctions().

public 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;
    }
}

// Usage in Chat
var functionExecutor = new FunctionExecutor();
functionExecutor.enrollFunction(FunctionDef.builder()
        .name("product")
        .description("Get the product of two numbers")
        .functionalClass(Product.class)
        .strict(Boolean.TRUE)
        .build());

var chatRequest = ChatRequest.builder()
        .model("gpt-4o-mini")
        .messages(List.of(UserMessage.of("What is 123 * 456?")))
        .tools(functionExecutor.getToolFunctions())
        .build();

Simple-OpenAI supports several third-party providers via specialized builder classes. Each provider has different supported services.

Gemini Vertex API

Use SimpleOpenAIGeminiVertex. Requires google-auth-library-oauth2-http dependency.

• Supported Services: chatCompletionService.
• Setup: Requires baseUrl and an apiKeyProvider (function returning a refreshing API key).

Gemini Google API

Use SimpleOpenAIGeminiGoogle.

• Supported Services: chatCompletionService, embeddingService (float format).

Deepseek API

Use SimpleOpenAIDeepseek.

• Supported Services: chatCompletionService (includes thinking), modelService (list).

Mistral API

Use SimpleOpenAIMistral.

• Supported Services: chatCompletionService, embeddingService (float format), modelService (list, detail, delete).

Azure OpenAI

Use SimpleOpenAIAzure.

• Supported Services: chatCompletionService, fileService, assistantService beta V2.
• Setup: Requires apiKey, baseUrl (including resourceName and deploymentId), and apiVersion.

Anyscale

Use SimpleOpenAIAnyscale.

• Supported Services: chatCompletionService (tested with Mistral).

To use Simple-OpenAI in an Android project, ensure your build.gradle is configured with the following requirements:

1. SDK Version: minSdk must be at least 24.
2. Java Compatibility: Set sourceCompatibility and targetCompatibility to JavaVersion.VERSION_11 and jvmTarget to '11'.
3. Dependencies: Include simple-openai and okhttp.

Initialization (Java):

SimpleOpenAI openAI = SimpleOpenAI.builder()
    .apiKey(API_KEY)
    .clientAdapter(new OkHttpClientAdapter())
    .build();

Initialization (Kotlin):

val openAI = SimpleOpenAI.builder()
    .apiKey(API_KEY)
    .clientAdapter(OkHttpClientAdapter())
    .build()

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]'
}

To use Simple-OpenAI in your Java project, add the dependency to your build configuration. Note that you must use Java 11 or greater. While the library works with the default HTTP client, you can optionally add okhttp if you prefer to use it for communication.

### Maven
```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>

Gradle

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]'
}

Simple-OpenAI supports automatic retries using exponential backoff with optional jitter. You can customize the retry behavior by building a RetryConfig and passing it to the SimpleOpenAI builder.

Configuration Options:

• maxAttempts: Maximum number of retry attempts (Default: 3)
• initialDelayMs: Initial delay before retrying in milliseconds (Default: 1000)
• maxDelayMs: Maximum delay between retries in milliseconds (Default: 10000)
• backoffMultiplier: Multiplier for exponential backoff (Default: 2.0)
• jitterFactor: Percentage of jitter to apply to delay values (Default: 0.2)
• retryableExceptions: List of exception types that trigger a retry (Default: IOException, ConnectException, SocketTimeoutException)
• retryableStatusCodes: List of HTTP status codes that trigger a retry (Default: 408, 409, 429, 500-599)

var retryConfig = RetryConfig.builder()
    .maxAttempts(4)
    .initialDelayMs(500)
    .maxDelayMs(8000)
    .backoffMultiplier(1.5)
    .jitterFactor(0.1)
    .build();

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