From e838dcbd05f3e08489cd2b227a6d2cc481acf779 Mon Sep 17 00:00:00 2001 From: Sudipta Borah Date: Wed, 11 Feb 2026 19:45:39 +0530 Subject: [PATCH 1/2] update readme with more usage details --- README.md | 174 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 167 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 9f164c1..279ca3b 100644 --- a/README.md +++ b/README.md @@ -49,23 +49,115 @@ allow any-user to use generative-ai-family in compartment whe ## Installation All providers in this module are distributed as single jar on the Maven Central Repository. The jar is compiled for JDK 17, and is forward compatible with later -JDK versions. The coordinates for the latest release are: +JDK versions. The coordinates for the latest release (pending release to maven central) are: ```xml com.oracle.genai oci-openai-java-sdk - 0.1.13 + 0.1.20 ``` ---- +Optionally, the packages can be manually installed in a local maven repository by downloading from [releases page](https://github.com/oracle/oci-openai-java/releases), and running the following command (-sources and -javadoc files are optional): -## Examples -Examples for OCI OpenAI Java SDK can be found [examples/src/main/java/com/examples/demo](examples/src/main/java/com/examples/demo). +```bash +mvn install:install-file \ +-DpomFile=oci-openai-java-sdk-x.y.z.pom \ +-Dfile=oci-openai-java-sdk-x.y.z.jar \ +-Dsources=oci-openai-java-sdk-x.y.z-sources.jar \ +-Djavadoc=oci-openai-java-sdk-x.y.z-javadoc.jar +``` ---- +## Usage + +### Quick Start + +Create a drop-in `OpenAIClient` that targets OCI and send your first text generation request. + +```java +import java.time.Duration; +import java.util.Objects; + +import com.openai.client.OpenAIClient; +import com.openai.models.responses.Response; +import com.openai.models.responses.ResponseCreateParams; +import com.oracle.genai.openai.OciOpenAI; + +public class QuickStart { + private static final String COMPARTMENT_ID = ""; + + public static void main(String[] args) throws Exception { + OpenAIClient client = OciOpenAI.builder() + .compartmentId(COMPARTMENT_ID) + .authType("oci_config") // or security_token, instance_principal, resource_principal + .profile("DEFAULT") // OCI config profile when using config-based auth + .region("us-chicago-1") // or baseUrl/serviceEndpoint override + .timeout(Duration.ofMinutes(2)) + .logRequestsAndResponses(true) // optional debug logging + .build(); + + try { + Response response = client.responses().create(ResponseCreateParams.builder() + .model("openai.gpt-4o") + .store(false) + .input(Objects.requireNonNull("Write a short poem about cloud computing.")) + .build()); + + System.out.println(response.output()); + } finally { + client.close(); + } + } +} +``` + +> - Provide **one** of `region`, `baseUrl`, or `serviceEndpoint` to resolve the OCI Generative AI endpoint. + +### Authentication + +`OciOpenAI` supports the same OCI IAM flows exposed by the OCI Java SDK through the `authType` value (or you can pass a prebuilt `BasicAuthenticationDetailsProvider` via `authProvider`). + +#### 1) OCI Config / Session Token + +Use when developing locally with an OCI config file. For session tokens, set `authType` to `security_token`; for long-lived keys use `oci_config`. + +```java +OpenAIClient client = OciOpenAI.builder() + .compartmentId("") + .conversationStoreId("") + .authType("security_token") // or "oci_config" + .profile("DEFAULT") + .region("us-chicago-1") + .build(); +``` + +#### 2) Resource Principal Authentication + +For workloads running in OCI Functions, Container Instances, etc. + +```java +OpenAIClient client = OciOpenAI.builder() + .compartmentId("") + .authType("resource_principal") + .region("us-chicago-1") + .build(); +``` +> Ensure the dynamic group bound to the resource principal has policies to call the Generative AI APIs. + +#### 3) Instance Principal Authentication + +For code running on OCI Compute instances. -### Signers +```java +OpenAIClient client = OciOpenAI.builder() + .compartmentId("") + .authType("instance_principal") + .region("us-chicago-1") + .build(); +``` +> The instance must belong to a dynamic group that grants access to the Generative AI endpoints. + +#### 4) Custom Auth Provider The library supports multiple OCI authentication methods (signers). Choose the one that matches your runtime environment and security posture. @@ -91,6 +183,74 @@ OpenAIClient openAIClient = OciOpenAI.builder().authType("instance_principal").b OpenAIClient openAIClient = OciOpenAI.builder().authType("oci_config").build(); ``` +### Client Initialization Parameters + +`OciOpenAI.builder()` mirrors the OpenAI Java client while adding OCI routing and headers. + +| Parameter | Description | Required | +|-----------|-------------|----------| +| `compartmentId` | OCID sent as `opc-compartment-id`/`CompartmentId` | ✅ | +| `authType` or `authProvider` | Authentication mechanism (`oci_config`, `security_token`, `instance_principal`, `resource_principal`, or a `BasicAuthenticationDetailsProvider`) | ✅ | +| `region` | OCI region short code; auto-derives base URL | ✅
*(unless `baseUrl` or `serviceEndpoint` is set)* | +| `baseUrl` | Fully qualified endpoint override (includes API path) | ❌ | +| `serviceEndpoint` | Service endpoint without API path; `/openai/v1` is appended | ❌ | +| `conversationStoreId` | Optional Conversation Store OCID attached to every call | ❌ | +| `timeout` | Request timeout (applies to HTTP client and client options) | ❌ | +| `logRequestsAndResponses` | Print request/response bodies for debugging | ❌ | + +### Base URL and endpoint overrides + +```java +// Explicit baseUrl (e.g., dedicated endpoint) +OpenAIClient client = OciOpenAI.builder() + .compartmentId("") + .authType("security_token") + .profile("DEFAULT") + .baseUrl("https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/openai/v1") + .build(); + +// Derive from service endpoint; SDK appends /openai/v1 +OpenAIClient client2 = OciOpenAI.builder() + .compartmentId("") + .authType("security_token") + .profile("DEFAULT") + .serviceEndpoint("https://inference.generativeai.us-chicago-1.oci.oraclecloud.com") + .build(); +``` + +### Error Handling + +The OpenAI Java SDK exceptions still apply. Catch `NotFoundException`, `UnauthorizedException`, or `BadRequestException` to inspect headers/diagnostics when OCI rejects a call. + +```java +try { + // call Responses API +} catch (NotFoundException | UnauthorizedException | BadRequestException e) { + System.out.println(e.headers()); +} +``` + +### Cleanup + +`OpenAIClient` implements `AutoCloseable`. Close it when finished to release HTTP resources: + +```java +try (OpenAIClient client = OciOpenAI.builder() + .compartmentId("") + .authType("security_token") + .region("us-chicago-1") + .build()) { + // use client +} +``` + +--- + +## Examples +Examples for OCI OpenAI Java SDK can be found [examples/src/main/java/com/examples/demo](examples/src/main/java/com/examples/demo). + +--- + --- ## Third-Party APIs From b4aafac45f5da22d5cd45a65cb6e1cdc9f4f7573 Mon Sep 17 00:00:00 2001 From: Sudipta Borah Date: Wed, 11 Feb 2026 19:52:25 +0530 Subject: [PATCH 2/2] remove instructions to use jar from release page --- README.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/README.md b/README.md index 279ca3b..f1cb411 100644 --- a/README.md +++ b/README.md @@ -58,16 +58,6 @@ JDK versions. The coordinates for the latest release (pending release to maven c ``` -Optionally, the packages can be manually installed in a local maven repository by downloading from [releases page](https://github.com/oracle/oci-openai-java/releases), and running the following command (-sources and -javadoc files are optional): - -```bash -mvn install:install-file \ --DpomFile=oci-openai-java-sdk-x.y.z.pom \ --Dfile=oci-openai-java-sdk-x.y.z.jar \ --Dsources=oci-openai-java-sdk-x.y.z-sources.jar \ --Djavadoc=oci-openai-java-sdk-x.y.z-javadoc.jar -``` - ## Usage ### Quick Start