openai-kotlin

When working with the Assistants API, you may need to handle advanced execution flows:

• Tool Outputs: If a run enters the Status.RequiresAction state, you must submit the results of any required tool calls using openAI.submitToolOutput(...).
• Streaming: For real-time event updates during a run, instead of polling, use openAI.createStreamingRun(...) or openAI.createStreamingThreadRun(...) to stream run events.

To tell the model how to use a function, you must define its parameters using a JSON Schema object. This is constructed using the Parameters.buildJsonObject DSL. You specify the type (usually object), the properties (the arguments the function accepts), and a required array listing mandatory fields.

val params = Parameters.buildJsonObject {
    put("type", "object")
    putJsonObject("properties") {
        putJsonObject("location") {
            put("type", "string")
            put("description", "The city and state, e.g. San Francisco, CA")
        }
        putJsonObject("unit") {
            put("type", "string")
            putJsonArray("enum") {
                add("celsius")
                add("fahrenheit")
            }
        }
    }
    putJsonArray("required") {
        add("location")
    }
}

Vector stores allow you to store and index files for file_search use cases. You can create, list, retrieve, update, and delete vector stores, as well as manage the files attached to them.

To attach files to a vector store, use createVectorStoreFile. For large numbers of files, use createVectorStoreFilesBatch to perform batch operations.

// Create a vector store
val vectorStore = openAI.createVectorStore(
    request = VectorStoreRequest(name = "Support FAQ")
)

// Attach a file to a vector store
val vectorStoreFile = openAI.createVectorStoreFile(
    id = VectorStoreId("vs_abc123"),
    request = VectorStoreFileRequest(fileId = FileId("file-abc123"))
)

// Batch files into a vector store
val batch = openAI.createVectorStoreFilesBatch(
    id = VectorStoreId("vs_abc123"),
    request = FileBatchRequest(fileIds = listOf(FileId("file-abc123"), FileId("file-def456")))
)

To use snapshot versions, add the Maven snapshots repository to your Gradle configuration.

repositories {
   //...
   maven { url 'https://central.sonatype.com/repository/maven-snapshots/' }
}

For Maven projects, use the openai-client-jvm artifact. Note that the BOM is not supported in Maven. You must also include a Ktor engine (e.g., ktor-client-okhttp-jvm) with runtime scope.

<dependencies>
    <dependency>
        <groupId>com.aallam.openai</groupId>
        <artifactId>openai-client-jvm</artifactId>
        <version>4.1.0</version>
    </dependency>
            
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-okhttp-jvm</artifactId>
        <version>3.0.0</version>
        <scope>runtime</scope>
    </dependency>
</dependencies>

While the default host is https://api.openai.com/v1/, you can connect to Azure or other compatible hosts by providing a custom OpenAIHost to the OpenAIConfig.

// Azure configuration
val host = OpenAIHost.azure(
    resourceName = "your-resource-name",
    deploymentId = "your-deployment-id",
    apiVersion = "2024-10-21",
)

val config = OpenAIConfig(
    host = host,
    token = "your-api-token",
)

val openAI = OpenAI(config)

// Custom compatible host
val host = OpenAIHost(
    baseUrl = "http://localhost:8080/v1/",
)

val config = OpenAIConfig(
    host = host,
    token = "your-api-token",
)

val openAI = OpenAI(config)

You can use the openai-client-bom to manage versions more easily. When using the BOM, you can define the openai-client dependency without an explicit version, but you still need to provide a Ktor engine at runtime.

dependencies {
    // import Kotlin API client BOM
    implementation platform('com.aallam.openai:openai-client-bom:4.1.0')

    // define dependencies without versions
    implementation 'com.aallam.openai:openai-client'
    runtimeOnly 'io.ktor:ktor-client-okhttp'
}

If you already have a RawSource (for example, from an in-memory stream or a custom implementation) and want to specify the filename that will be sent to the OpenAI API, use the FileSource constructor with the name and source parameters.

import com.aallam.openai.api.file.FileSource
import kotlinx.io.files.Path
import kotlinx.io.files.SystemFileSystem

val source = SystemFileSystem.source(Path("path/to/audio.wav"))
val fileSource = FileSource(name = "audio.wav", source = source)

You can create an instance of the OpenAI client in two ways: by passing parameters directly to the constructor or by providing a pre-configured OpenAIConfig object. It is recommended to use environment variables for your API key for security.

// Option 1: Direct initialization
val openai = OpenAI(
    token = "your-api-key",
    timeout = Timeout(socket = 60.seconds),
    // additional configurations...
)

// Option 2: Using OpenAIConfig
val config = OpenAIConfig(
    token = apiKey,
    timeout = Timeout(socket = 60.seconds),
    // additional configurations...
)

val openAI = OpenAI(config)

The library provides access to the legacy fine-tunes API. You can create fine-tunes using a training file and a model, list existing fine-tunes, retrieve details, cancel ongoing processes, and monitor progress via events (either as a list or a Flow).

// Create fine-tune
val fineTune = openAI.fineTune(
    request = FineTuneRequest(
        trainingFile = FileId("file-abc123"),
        model = ModelId("ada")
    )
)

// Stream fine-tune events
val eventsFlow: Flow<FineTuneEvent> = openAI.fineTuneEventsFlow(FineTuneId("ft-abc123"))