{"id":49190541,"url":"https://github.com/oracle/oci-openai-java","last_synced_at":"2026-04-23T06:30:53.122Z","repository":{"id":338164704,"uuid":"1155179064","full_name":"oracle/oci-openai-java","owner":"oracle","description":"OCI OpenAI Client for Java simplifies integration between OpenAI’s Java SDK and Oracle Cloud Infrastructure (OCI) GenAI service by providing robust authentication and authorization utilities. ","archived":false,"fork":false,"pushed_at":"2026-04-13T16:10:35.000Z","size":225,"stargazers_count":4,"open_issues_count":3,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-13T18:10:28.673Z","etag":null,"topics":["java","oci-openai","openai-responses-api","sdk"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"upl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oracle.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-11T08:03:01.000Z","updated_at":"2026-04-13T16:08:14.000Z","dependencies_parsed_at":null,"dependency_job_id":"bbce14ab-bfee-49a9-9d94-54c359a1dc44","html_url":"https://github.com/oracle/oci-openai-java","commit_stats":null,"previous_names":["oracle/oci-openai-java"],"tags_count":0,"template":false,"template_full_name":"oracle/template-repo","purl":"pkg:github/oracle/oci-openai-java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Foci-openai-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Foci-openai-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Foci-openai-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Foci-openai-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oracle","download_url":"https://codeload.github.com/oracle/oci-openai-java/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Foci-openai-java/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32169655,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-23T02:19:40.750Z","status":"ssl_error","status_checked_at":"2026-04-23T02:17:55.737Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","oci-openai","openai-responses-api","sdk"],"created_at":"2026-04-23T06:30:52.380Z","updated_at":"2026-04-23T06:30:53.115Z","avatar_url":"https://github.com/oracle.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [DEPRECATED] OCI OpenAI SDK for java\n\nThis library is no longer maintained. You should use official [OpenAI SDK](https://developers.openai.com/api/docs/libraries), not the [OCI SDK](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdks.htm) nor the legacy [OCI OpenAI SDK](https://github.com/oracle-samples/oci-openai), to invoke the Responses API. Ensure you have the latest version of the OpenAI SDK installed.\n\nIf you need IAM Auth, use the below in conjunction with OpenAI SDK.\n- Python [https://github.com/oracle-samples/oci-genai-auth-python](https://github.com/oracle-samples/oci-genai-auth-python)\n- Java [https://github.com/oracle-samples/oci-genai-auth-java](https://github.com/oracle-samples/oci-genai-auth-java)\n\nIf you have been using the legacy OCI OpenAI SDK below prior to our GA release, we will continue to support that.\n- [https://github.com/oracle-samples/oci-openai](https://github.com/oracle-samples/oci-openai)\n- [https://github.com/oracle/oci-openai-java](https://github.com/oracle/oci-openai-java)\n\n## About\n\nThe **OCI OpenAI Java** library provides secure and convenient access to the OpenAI-compatible REST API hosted by **OCI Generative AI Service**.\n\n---\n\n## Table of Contents\n- [oci-openai-java](#oci-openai-java)\n  - [Table of Contents](#table-of-contents)\n  - [Before You Start](#before-you-start)\n  - [Installation](#installation)\n  - [Usage](#usage)\n    - [Quick Start](#quick-start)\n    - [Authentication](#authentication)\n    - [Client Initialization Parameters](#client-initialization-parameters)\n    - [Base URL and endpoint overrides](#base-url-and-endpoint-overrides)\n    - [Error Handling](#error-handling)\n    - [Cleanup](#cleanup)\n  - [Examples](#examples)\n  - [Third-Party APIs](#third-party-apis)\n  - [Contributing](#contributing)\n  - [Security](#security)\n  - [License](#license)\n\n---\n\n## Before you start\n\n**Important!**\n\nNote that this package, as well as API keys package described below, only supports OpenAI, xAi Grok and Meta LLama models on OCI Generative AI.\n\nBefore you start using this package, determine if this is the right option for you.\n\nIf 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.\n\nWith OCI Generative AI API Keys, use the native `openai` SDK like before. Just update the `base_url`, create API keys in your OCI console, insure the policy granting the key access to generative AI services is present and you are good to go.\n\n- Create an API key in Console: **Generative AI** -\u003e **API Keys**\n- Create a security policy: **Identity \u0026 Security** -\u003e **Policies**\n\nTo authorize a specific API Key\n```\nallow any-user to use generative-ai-family in compartment \u003ccompartment-name\u003e where ALL { request.principal.type='generativeaiapikey', request.principal.id='ocid1.generativeaiapikey.oc1.us-chicago-1....' }\n```\n\nTo authorize any API Key\n```\nallow any-user to use generative-ai-family in compartment \u003ccompartment-name\u003e where ALL { request.principal.type='generativeaiapikey' }\n```\n\n---\n\n## Installation\nAll providers in this module are distributed as single jar on the Maven Central\nRepository. The jar is compiled for JDK 17, and is forward compatible with later\nJDK versions. The coordinates for the latest release (pending release to maven central) are:\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.oracle.genai\u003c/groupId\u003e\n    \u003cartifactId\u003eoci-openai-java-sdk\u003c/artifactId\u003e\n    \u003cversion\u003e0.1.20\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Usage\n\n### Quick Start\n\nCreate a drop-in `OpenAIClient` that targets OCI and send your first text generation request.\n\n```java\nimport java.time.Duration;\nimport java.util.Objects;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.models.responses.Response;\nimport com.openai.models.responses.ResponseCreateParams;\nimport com.oracle.genai.openai.OciOpenAI;\n\npublic class QuickStart {\n    private static final String COMPARTMENT_ID = \"\u003cYOUR_COMPARTMENT_OCID\u003e\";\n\n    public static void main(String[] args) throws Exception {\n        OpenAIClient client = OciOpenAI.builder()\n                .compartmentId(COMPARTMENT_ID)\n                .authType(\"oci_config\")          // or security_token, instance_principal, resource_principal\n                .profile(\"DEFAULT\")              // OCI config profile when using config-based auth\n                .region(\"us-chicago-1\")          // or baseUrl/serviceEndpoint override\n                .timeout(Duration.ofMinutes(2))\n                .logRequestsAndResponses(true)   // optional debug logging\n                .build();\n\n        try {\n            Response response = client.responses().create(ResponseCreateParams.builder()\n                    .model(\"openai.gpt-4o\")\n                    .store(false)\n                    .input(Objects.requireNonNull(\"Write a short poem about cloud computing.\"))\n                    .build());\n\n            System.out.println(response.output());\n        } finally {\n            client.close();\n        }\n    }\n}\n```\n\n\u003e - Provide **one** of `region`, `baseUrl`, or `serviceEndpoint` to resolve the OCI Generative AI endpoint.\n\n### Authentication\n\n`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`).\n\n#### 1) OCI Config / Session Token\n\nUse when developing locally with an OCI config file. For session tokens, set `authType` to `security_token`; for long-lived keys use `oci_config`.\n\n```java\nOpenAIClient client = OciOpenAI.builder()\n        .compartmentId(\"\u003cCOMPARTMENT_OCID\u003e\")\n        .conversationStoreId(\"\u003cCONVERSATION_STORE_OCID\u003e\")\n        .authType(\"security_token\")   // or \"oci_config\"\n        .profile(\"DEFAULT\")\n        .region(\"us-chicago-1\")\n        .build();\n```\n\n#### 2) Resource Principal Authentication\n\nFor workloads running in OCI Functions, Container Instances, etc.\n\n```java\nOpenAIClient client = OciOpenAI.builder()\n        .compartmentId(\"\u003cCOMPARTMENT_OCID\u003e\")\n        .authType(\"resource_principal\")\n        .region(\"us-chicago-1\")\n        .build();\n```\n\u003e Ensure the dynamic group bound to the resource principal has policies to call the Generative AI APIs.\n\n#### 3) Instance Principal Authentication\n\nFor code running on OCI Compute instances.\n\n```java\nOpenAIClient client = OciOpenAI.builder()\n        .compartmentId(\"\u003cCOMPARTMENT_OCID\u003e\")\n        .authType(\"instance_principal\")\n        .region(\"us-chicago-1\")\n        .build();\n```\n\u003e The instance must belong to a dynamic group that grants access to the Generative AI endpoints.\n\n#### 4) Custom Auth Provider\n\nThe library supports multiple OCI authentication methods (signers). Choose the one that matches your runtime environment and security posture.\n\nSupported auth providers\n\n- `SessionTokenAuthenticationDetailsProvider` — Uses an OCI session token from your local OCI CLI profile.\n- `ResourcePrincipalAuthenticationDetailsProvider` — Uses Resource Principal auth.\n- `InstancePrincipalsAuthenticationDetailsProvider` — Uses Instance Principal auth. Best for OCI Compute instances with dynamic group policies.\n- `ConfigFileAuthenticationDetailsProvider` — Uses an OCI user API key. Suitable for service accounts/automation where API keys are managed securely.\n\nMinimal examples of constructing each auth type:\n```\n// 1) Session (local dev; uses ~/.oci/config + session token)\nOpenAIClient openAIClient = OciOpenAI.builder().authType(\"security_token\").build();\n\n// 2) Resource Principal (OCI services with RP)\nOpenAIClient openAIClient = OciOpenAI.builder().authType(\"resource_principal\").build();\n\n// 3) Instance Principal (OCI Compute)\nOpenAIClient openAIClient = OciOpenAI.builder().authType(\"instance_principal\").build();\n\n// 4) User Principal (API key in ~/.oci/config)\nOpenAIClient openAIClient = OciOpenAI.builder().authType(\"oci_config\").build();\n```\n\n### Client Initialization Parameters\n\n`OciOpenAI.builder()` mirrors the OpenAI Java client while adding OCI routing and headers.\n\n| Parameter | Description | Required |\n|-----------|-------------|----------|\n| `compartmentId` | OCID sent as `opc-compartment-id`/`CompartmentId` | ✅ |\n| `authType` or `authProvider` | Authentication mechanism (`oci_config`, `security_token`, `instance_principal`, `resource_principal`, or a `BasicAuthenticationDetailsProvider`) | ✅ |\n| `region` | OCI region short code; auto-derives base URL | ✅\u003cbr/\u003e*(unless `baseUrl` or `serviceEndpoint` is set)* |\n| `baseUrl` | Fully qualified endpoint override (includes API path) | ❌ |\n| `serviceEndpoint` | Service endpoint without API path; `/openai/v1` is appended | ❌ |\n| `conversationStoreId` | Optional Conversation Store OCID attached to every call | ❌ |\n| `timeout` | Request timeout (applies to HTTP client and client options) | ❌ |\n| `logRequestsAndResponses` | Print request/response bodies for debugging | ❌ |\n\n### Base URL and endpoint overrides\n\n```java\n// Explicit baseUrl (e.g., dedicated endpoint)\nOpenAIClient client = OciOpenAI.builder()\n        .compartmentId(\"\u003cCOMPARTMENT_OCID\u003e\")\n        .authType(\"security_token\")\n        .profile(\"DEFAULT\")\n        .baseUrl(\"https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/openai/v1\")\n        .build();\n\n// Derive from service endpoint; SDK appends /openai/v1\nOpenAIClient client2 = OciOpenAI.builder()\n        .compartmentId(\"\u003cCOMPARTMENT_OCID\u003e\")\n        .authType(\"security_token\")\n        .profile(\"DEFAULT\")\n        .serviceEndpoint(\"https://inference.generativeai.us-chicago-1.oci.oraclecloud.com\")\n        .build();\n```\n\n### Error Handling\n\nThe OpenAI Java SDK exceptions still apply. Catch `NotFoundException`, `UnauthorizedException`, or `BadRequestException` to inspect headers/diagnostics when OCI rejects a call.\n\n```java\ntry {\n    // call Responses API\n} catch (NotFoundException | UnauthorizedException | BadRequestException e) {\n    System.out.println(e.headers());\n}\n```\n\n### Cleanup\n\n`OpenAIClient` implements `AutoCloseable`. Close it when finished to release HTTP resources:\n\n```java\ntry (OpenAIClient client = OciOpenAI.builder()\n        .compartmentId(\"\u003cCOMPARTMENT_OCID\u003e\")\n        .authType(\"security_token\")\n        .region(\"us-chicago-1\")\n        .build()) {\n    // use client\n}\n```\n\n---\n\n## Examples\nExamples for OCI OpenAI Java SDK can be found [examples/src/main/java/com/examples/demo](examples/src/main/java/com/examples/demo).\n\n---\n\n---\n\n## Third-Party APIs\n\nDevelopers choosing to distribute a binary implementation of this project are responsible for obtaining and providing all required licenses and copyright notices for the third-party code used in order to ensure compliance with their respective open source licenses.\n\n---\n\n## Contributing\n\nThis project welcomes contributions from the community.\nBefore submitting a pull request, please [review our contribution guide](./CONTRIBUTING.md).\n\n---\n\n## Security\n\nPlease consult the [security guide](./SECURITY.md) for our responsible security vulnerability disclosure process.\n\n---\n\n\n## License\n\nCopyright (c) 2025 Oracle and/or its affiliates.\n\nReleased under the Universal Permissive License v1.0 as shown at\n[https://oss.oracle.com/licenses/upl/](https://oss.oracle.com/licenses/upl/)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foracle%2Foci-openai-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foracle%2Foci-openai-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foracle%2Foci-openai-java/lists"}