Align with Python repo for GA release

README.md

@@ -4,43 +4,22 @@ The **OCI GenAI Auth** Java library provides OCI request-signing helpers for the
 
 ## Table of Contents
 
-- [Before you start](#before-you-start)
+- [Installation](#installation)
 - [Using OCI IAM Auth](#using-oci-iam-auth)
 - [Using API Key Auth](#using-api-key-auth)
 - [Using AgentHub APIs](#using-agenthub-apis)
-- [Using Partner APIs](#using-partner-apis)
-- [Running the Examples](#running-the-examples)
-- [Building from Source](#building-from-source)
-
-## Before you start
-
-**Important!**
-
-Note that this package, as well as API keys described below, only supports OpenAI, xAi Grok and Meta LLama models on OCI Generative AI.
-
-Before you start using this package, determine if this is the right option for you.
-
-If you are looking for a seamless way to port your code from an OpenAI compatible endpoint to OCI Generative AI endpoint, and you are currently using OpenAI-style API keys, you might want to use [OCI Generative AI API Keys](https://docs.oracle.com/en-us/iaas/Content/generative-ai/api-keys.htm) instead.
-
-With OCI Generative AI API Keys, use the native `openai-java` SDK like before. Just update the `base_url`, create API keys in your OCI console, ensure the policy granting the key access to generative AI services is present and you are good to go.
-
-- Create an API key in Console: **Generative AI** -> **API Keys**
-- Create a security policy: **Identity & Security** -> **Policies**
-
-To authorize a specific API Key
-```
-allow any-user to use generative-ai-family in compartment <compartment-name> where ALL { request.principal.type='generativeaiapikey', request.principal.id='ocid1.generativeaiapikey.oc1.us-chicago-1....' }
-```
-
-To authorize any API Key
-```
-allow any-user to use generative-ai-family in compartment <compartment-name> where ALL { request.principal.type='generativeaiapikey' }
-```
+- [Using Partner APIs (passthrough)](#using-partner-apis-passthrough)
+- [Examples](#examples)
+- [Contributing](#contributing)
+- [Security](#security)
+- [License](#license)
 
 ## Installation
 
 Requires **Java 17+** and **Maven 3.8+**.
 
+`oci-genai-auth-java` is designed to work together with the official [OpenAI Java SDK](https://github.com/openai/openai-java).
+
 ```xml
 <dependencyManagement>
     <dependencies>
@@ -64,51 +43,59 @@ Requires **Java 17+** and **Maven 3.8+**.
 
 ## Using OCI IAM Auth
 
-Use OCI IAM auth when you want to sign requests with your OCI profile (session/user/resource/instance principal) instead of API keys.
+Use OCI IAM auth when you want to sign requests with your OCI profile (session/user/resource/instance principal). Recommended if you are building OCI-native production workloads.
 
 ```java
 import com.oracle.genai.auth.OciAuthConfig;
 import com.oracle.genai.auth.OciOkHttpClientFactory;
 import com.openai.client.OpenAIClient;
-import com.openai.client.OpenAIClientImpl;
-import com.openai.core.ClientOptions;
+import com.openai.client.okhttp.OpenAIOkHttpClient;
 
 OciAuthConfig config = OciAuthConfig.builder()
         .authType("security_token")
         .profile("DEFAULT")
-        .compartmentId("ocid1.compartment.oc1..aaaaaaaaexample")
         .build();
 
 OkHttpClient ociHttpClient = OciOkHttpClientFactory.build(config);
 
-// Plug the OCI-signed OkHttpClient into the OpenAI SDK
-OpenAIClient client = new OpenAIClientImpl(
-        ClientOptions.builder()
-                .baseUrl("https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1")
-                .apiKey("not-used")
-                .httpClient(new OpenAIOkHttpAdapter(ociHttpClient, baseUrl))
-                .build());
+OpenAIClient client = OpenAIOkHttpClient.builder()
+        .baseUrl("https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1")
+        .okHttpClient(ociHttpClient)
+        .apiKey("not-used")
+        .build();
 ```
 
 ## Using API Key Auth
 
-Use OCI Generative AI API Keys if you want a direct API-key workflow with the OpenAI SDK.
+Use OCI Generative AI API Keys if you want a long-lived API key style auth. Recommended if you are migrating from other OpenAI-compatible API providers.
+
+To create the OCI Generative AI API Keys, follow [this guide](https://docs.oracle.com/en-us/iaas/Content/generative-ai/api-keys.htm).
+
+You don't need to install `oci-genai-auth-java` if you use API key auth.
 
 ```java
 import com.openai.client.OpenAIClient;
-import com.openai.client.OpenAIClientImpl;
-import com.openai.core.ClientOptions;
-
-OpenAIClient client = new OpenAIClientImpl(
-        ClientOptions.builder()
-                .baseUrl("https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1")
-                .apiKey(System.getenv("OCI_GENAI_API_KEY"))
-                .build());
+import com.openai.client.okhttp.OpenAIOkHttpClient;
+
+OpenAIClient client = OpenAIOkHttpClient.builder()
+        .baseUrl("https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1")
+        .apiKey(System.getenv("OCI_GENAI_API_KEY"))
+        .build();
 ```
 
 ## Using AgentHub APIs
 
-AgentHub provides a unified interface for interacting with models and agentic capabilities. It is compatible with OpenAI's Responses API and the Open Responses Spec, enabling developers to build agents with the OpenAI SDK. Only the project OCID is required — no compartment ID needed.
+OCI AgentHub provides a unified API for interacting with models and agentic capabilities.
+
+- It is compatible with OpenAI's Responses API and the [Open Responses Spec](https://www.openresponses.org/specification), enabling developers to build agents with OpenAI SDK, OpenAI Agents SDK, LangChain, LangGraph, AI SDK, CrewAI, and more.
+- It offers a uniform interface, auth, billing to access multiple model providers including OpenAI, Gemini, xAI, and GPT-OSS models hosted in OCI and your Dedicated AI Cluster.
+- It provides built-in agentic primitives such as agent loop, reasoning, short-term memory, long-term memory, web search, file search, image generation, code execution, and more.
+
+In addition to the compatible endpoint to Responses API, AgentHub also offers compatible endpoints to Files API, Vector Stores API, and Containers API.
+
+Explore [examples](examples/agenthub) to get started.
+
+Note: OpenAI commercial models and image generation are only available to Oracle internal teams at this moment.
 
 ```java
 OciAuthConfig config = OciAuthConfig.builder()
@@ -126,9 +113,15 @@ OpenAIClient client = OpenAIOkHttpClient.builder()
         .build();
 ```
 
-## Using Partner APIs
+## Using Partner APIs (passthrough)
+
+OCI also offers Partner API which passes through your calls to partners such as OpenAI. We will support more partners in the future.
+
+You can leverage Partner API when you want to use OpenAI's API and GPT models, but with OCI auth and billing.
+
+Note: Currently Partner API is only available to Oracle internal teams. Only features that meet partner's Zero Data Retention are available through Partner API.
 
-Partner endpoints require the compartment OCID header.
+If you want multi-provider model access and features unavailable under partner's Zero Data Retention (such as File Search), use the AgentHub APIs above.
 
 ```java
 OciAuthConfig config = OciAuthConfig.builder()
@@ -138,69 +131,26 @@ OciAuthConfig config = OciAuthConfig.builder()
         .build();
 
 OkHttpClient ociHttpClient = OciOkHttpClientFactory.build(config);
-
-// The compartment ID is automatically injected as a header by the library
-OpenAIClient client = new OpenAIClientImpl(
-        ClientOptions.builder()
-                .baseUrl("https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1")
-                .apiKey("not-used")
-                .httpClient(new OpenAIOkHttpAdapter(ociHttpClient, baseUrl))
-                .build());
+OpenAIClient client = OpenAIOkHttpClient.builder()
+        .baseUrl("https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1")
+        .okHttpClient(ociHttpClient)
+        .apiKey("not-used")
+        .build();
 ```
 
-## Authentication Types
-
-| Auth Type | Use Case |
-|-----------|----------|
-| `oci_config` | Local development with API key in `~/.oci/config` |
-| `security_token` | Local development with OCI CLI session token |
-| `instance_principal` | OCI Compute instances with dynamic group policies |
-| `resource_principal` | OCI Functions, Container Instances |
-
-## Running the Examples
-
-1. Update the constants in each example with your `COMPARTMENT_ID`, `PROJECT_OCID`, and set the correct `REGION`.
-2. Set the `OCI_GENAI_API_KEY` environment variable when an example uses API key authentication.
-3. Install dependencies: `mvn install -DskipTests`.
-
-The [examples/](examples/) directory is organized as follows:
-
-| Directory | Description |
-|-----------|-------------|
-| [examples/agenthub/openai/](examples/agenthub/openai/) | AgentHub examples using the OpenAI Responses API |
-| [examples/partner/openai/](examples/partner/openai/) | Partner examples using OpenAI Chat Completions |
-
-These examples are **not** compiled as part of the Maven build. Copy them into your own project.
-
-## Building from Source
-
-```bash
-# Compile
-mvn clean compile
-
-# Run tests
-mvn test
-
-# Full verification
-mvn clean verify
-
-# Install to local Maven repository
-mvn install -DskipTests
-
-# Confirm no vendor SDK dependencies
-mvn dependency:tree -pl oci-genai-auth-java-core
-```
+## Examples
+Demo code and instructions on how to run them, for both agenthub and partner usecases can be found in [examples](examples/) folder.
 
 ## Contributing
 
-This project welcomes contributions from the community. Before submitting a pull request, please review our [contribution guide](./CONTRIBUTING.md).
+This project welcomes contributions from the community. Before submitting a pull request, please [review our contribution guide](./CONTRIBUTING.md)
 
 ## Security
 
-Please consult the [security guide](./SECURITY.md) for our responsible security vulnerability disclosure process.
+Please consult the [security guide](./SECURITY.md) for our responsible security vulnerability disclosure process
 
 ## License
 
 Copyright (c) 2026 Oracle and/or its affiliates.
 
-Released under the [Universal Permissive License v1.0](https://oss.oracle.com/licenses/upl/).
+Released under the Universal Permissive License v1.0 as shown at https://oss.oracle.com/licenses/upl/.

examples/agenthub/README.md

@@ -1,35 +1,55 @@
 # AgentHub Examples
 
-AgentHub provides a unified interface for interacting with models and agentic capabilities.
-It is compatible with OpenAI's Responses API and the Open Responses Spec, enabling
-developers to build agents with the OpenAI SDK.
+This folder contains examples for OCI Generative AI AgentHub APIs using the OpenAI Java SDK.
 
 ## Prerequisites
 
-1. Create a **Generative AI Project** on OCI Console.
-2. Update `PROJECT_OCID` and `REGION` in each example file.
-3. Authenticate with OCI:
-   - **OCI IAM**: `oci session authenticate`
-   - **API Key**: Set `OCI_GENAI_API_KEY` environment variable
+1. Install dependencies:
 
-## Base URL
+   ```bash
+   mvn install -DskipTests
+   ```
 
-```
-https://inference.generativeai.<REGION>.oci.oraclecloud.com/openai/v1
-```
+2. Configure constants in each example file:
+   - `PROJECT_OCID`
+   - `REGION`
+
+3. (Optional) You can override project at runtime:
+
+   ```bash
+   export OCI_GENAI_PROJECT_ID=<your_project_ocid>
+   ```
+
+4. If running API-key based examples, set:
+
+   ```bash
+   export OCI_GENAI_API_KEY=<your_oci_genai_api_key>
+   ```
 
 ## Examples
 
+Quickstarts:
+
+| File | Description |
+|------|-------------|
+| `QuickstartResponsesOciIam.java` | Quickstart with OCI IAM authentication |
+| `QuickstartResponsesApiKey.java` | Quickstart with API key authentication |
+
+Responses API examples:
+
+| File | Description |
+|------|-------------|
+| `responses/CreateResponse.java` | Create a response |
+| `responses/StreamingTextDelta.java` | Stream response text deltas |
+
+Tools examples:
+
 | File | Description |
 |------|-------------|
-| `openai/QuickstartResponsesOciIam.java` | Quickstart with OCI IAM authentication |
-| `openai/QuickstartResponsesApiKey.java` | Quickstart with API key authentication |
-| `openai/responses/CreateResponse.java` | Create a response |
-| `openai/responses/StreamingTextDelta.java` | Stream response text deltas |
-| `openai/tools/WebSearch.java` | Web search tool |
-| `openai/tools/FunctionCalling.java` | Function calling tool |
+| `tools/FunctionCalling.java` | Function calling tool |
+| `tools/WebSearch.java` | Web search tool |
 
-## Running
+## Notes
 
-These are standalone Java files. Copy them into your project with the required dependencies
-(`oci-genai-auth-java-core` and `openai-java`), then compile and run.
+- Most examples use IAM signing through `oci-genai-auth-java`.
+- AgentHub examples use OpenAI-compatible `/openai/v1` endpoints and require a project OCID.

examples/partner/README.md

@@ -0,0 +1,20 @@
+# Partner Examples
+
+This folder contains partner API examples using the OpenAI Java SDK.
+
+## Prerequisites
+
+1. Install dependencies:
+
+   ```bash
+   mvn install -DskipTests
+   ```
+
+2. Configure constants in each example file:
+   - `COMPARTMENT_ID`
+   - `REGION`
+
+## Notes
+
+- Partner endpoints use pass-through mode and require the `opc-compartment-id` header.
+- These examples use IAM signing through `oci-genai-auth-java`.

examples/partner/openai/BasicChatCompletion.java

@@ -5,7 +5,7 @@
  */
 
 /**
- * Demonstrates a basic chat completion request for the Partner (pass-through) endpoint.
+ * Demonstrates a basic chat completion request for the Partner endpoint.
  *
  * <p>This file is a standalone example — it is NOT compiled as part of the Maven build.
  * Copy it into your own project and add the required dependencies.

examples/partner/openai/StreamingChatCompletion.java

@@ -5,7 +5,7 @@
  */
 
 /**
- * Demonstrates streaming chat completion responses for the Partner (pass-through) endpoint.
+ * Demonstrates streaming chat completion responses for the Partner endpoint.
  */
 
 import com.openai.client.OpenAIClient;

examples/partner/openai/ToolCallChatCompletion.java

@@ -5,7 +5,7 @@
  */
 
 /**
- * Demonstrates tool calling with chat completions for the Partner (pass-through) endpoint.
+ * Demonstrates tool calling with chat completions for the Partner endpoint.
  */
 
 import com.openai.client.OpenAIClient;